From f4d48298ab525a948bca3d4b05d8c3a561436534 Mon Sep 17 00:00:00 2001 From: Filipe Moreira Date: Thu, 19 Nov 2026 15:51:09 -0300 Subject: [PATCH] Add unslop-ui design skill --- .claude-plugin/marketplace.json | 4 +- README.md | 3 +- .../design-skills/.claude-plugin/plugin.json | 8 +- plugins/design-skills/README.md | 2 + .../design-skills/skills/unslop-ui/LICENSE | 21 + .../design-skills/skills/unslop-ui/SKILL.md | 149 +++++++ .../skills/unslop-ui/agents/openai.yaml | 6 + .../skills/unslop-ui/references/examples.md | 213 ++++++++++ .../skills/unslop-ui/references/tokens.md | 45 +++ .../unslop-ui/references/unslop-fallback.md | 33 ++ .../skills/unslop-ui/scripts/count_tells.py | 363 ++++++++++++++++++ .../skills/unslop-ui/scripts/load_unslop.py | 106 +++++ scripts/sync-vendor.sh | 15 + 13 files changed, 962 insertions(+), 6 deletions(-) create mode 100644 plugins/design-skills/skills/unslop-ui/LICENSE create mode 100644 plugins/design-skills/skills/unslop-ui/SKILL.md create mode 100644 plugins/design-skills/skills/unslop-ui/agents/openai.yaml create mode 100644 plugins/design-skills/skills/unslop-ui/references/examples.md create mode 100644 plugins/design-skills/skills/unslop-ui/references/tokens.md create mode 100644 plugins/design-skills/skills/unslop-ui/references/unslop-fallback.md create mode 100644 plugins/design-skills/skills/unslop-ui/scripts/count_tells.py create mode 100644 plugins/design-skills/skills/unslop-ui/scripts/load_unslop.py diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cb267e7..b54ffed 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -46,8 +46,8 @@ { "name": "design-skills", "source": "./plugins/design-skills", - "description": "Skills: apple-design, animate, choreograph, gestures, review-animations, remove-animations, animation-performance, break-ui, prototype (Emil Kowalski) and hallmark (Nutlope) for better-looking web UI.", - "version": "0.5.0", + "description": "Skills: apple-design, animate, choreograph, gestures, review-animations, remove-animations, animation-performance, break-ui, prototype (Emil Kowalski) and hallmark (Nutlope) for better-looking web UI. Includes unslop-ui for interface copy and chart cleanup.", + "version": "0.6.0", "category": "skills" }, { diff --git a/README.md b/README.md index 79a5da1..4431d30 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ By [Filipe Moreira](https://filipemoreira.top). | Plugin | Source | What it does | | :- | :- | :- | -| [design-skills](plugins/design-skills) | Copied here | From [Emil Kowalski](https://github.com/emilkowalski/skills): `apple-design` (Apple-style motion, gestures and materials on the web), `animate` (one animation, decided in order), `choreograph` (several elements moving together), `gestures` (drag, swipe, sheets), `review-animations`, `remove-animations` (cut motion you don't need), `animation-performance` (animations that drop frames), `break-ui` (worst-case data) and `prototype` (several versions behind a picker). `hallmark` ([Nutlope](https://github.com/nutlope/hallmark), 2.0): pages that don't look AI-generated, with `audit` and `redesign`. | +| [design-skills](plugins/design-skills) | Copied here | From [Emil Kowalski](https://github.com/emilkowalski/skills): `apple-design` (Apple-style motion, gestures and materials on the web), `animate` (one animation, decided in order), `choreograph` (several elements moving together), `gestures` (drag, swipe, sheets), `review-animations`, `remove-animations` (cut motion you don't need), `animation-performance` (animations that drop frames), `break-ui` (worst-case data) and `prototype` (several versions behind a picker). `hallmark` ([Nutlope](https://github.com/nutlope/hallmark), 2.0): pages that don't look AI-generated, with `audit` and `redesign`. `unslop-ui` ([Felipe Basurto](https://github.com/felipebasurto/unslop-ui)) removes generic AI patterns from interface copy and charts when requested. | | [po-skills](plugins/po-skills) | Ours, plus two adapted | `jira-stories` and `release-notes` (ours): stories into Jira, finished work into release notes on Confluence. `brainstorming` (enriched with YC forcing questions) and `writing-plans` (with Decision Briefs and Ponytail debt tracking) from [obra/superpowers](https://github.com/obra/superpowers). | | [eng-skills](plugins/eng-skills) | Ours | Engineering, QA & delivery: `investigate` (systematic root cause debugging with the 3-strike rule), `qa` (exploratory verification across UI/API/CLI with mandatory regression tests), and `ship` (pre-flight checks, doc sync, PR). `freeze` and `careful` live in the guardrails mod. | | ponytail | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | Lazy senior dev mode: the simplest code that works. YAGNI, stdlib first, no unrequested abstractions. Commands `/ponytail-audit`, `/ponytail-review` and more. | @@ -246,6 +246,7 @@ It fits the workflow beside step 10: use it for the video that goes with a relea | `hallmark audit ` | A ranked list of what looks generated. Edits nothing | | `hallmark redesign ` | New visual layer, same routes, copy and brand. Asks before deleting anything | | "Lock the system" (after a hallmark build) | Saves the design as a `design.md`; later pages reuse it | +| `unslop-ui ` | Removes generic AI patterns from interface copy and charts; add `--surface` for optional visual cleanup. Requires Python 3.9+ | | "Make this sheet feel like iOS" | `apple-design`: springs, gestures, interruptible transitions, materials, reduced motion | | "Animate this dropdown" | `animate`: decides whether it should move, then easing, duration and origin | | "Stagger this list" / "the hero entrance feels robotic" | `choreograph`: order, overlap and what stays still across the group | diff --git a/plugins/design-skills/.claude-plugin/plugin.json b/plugins/design-skills/.claude-plugin/plugin.json index 2571323..c199ffb 100644 --- a/plugins/design-skills/.claude-plugin/plugin.json +++ b/plugins/design-skills/.claude-plugin/plugin.json @@ -1,6 +1,8 @@ { "name": "design-skills", - "version": "0.5.0", - "description": "Design skills we use: apple-design, animate, choreograph, gestures, review-animations, remove-animations, animation-performance, break-ui and prototype (Emil Kowalski) for motion that feels right, drag and swipe, motion review and cleanup, smooth frames, worst-case data and UI variants, and hallmark (Nutlope) against generic AI-looking pages.", - "author": { "name": "lippstack" } + "version": "0.6.0", + "description": "Design skills we use: apple-design, animate, choreograph, gestures, review-animations, remove-animations, animation-performance, break-ui and prototype (Emil Kowalski) for motion that feels right, drag and swipe, motion review and cleanup, smooth frames, worst-case data and UI variants, and hallmark (Nutlope) against generic AI-looking pages. Includes unslop-ui (Felipe Basurto) for interface copy and chart cleanup.", + "author": { + "name": "lippstack" + } } diff --git a/plugins/design-skills/README.md b/plugins/design-skills/README.md index e663d67..4ae1d39 100644 --- a/plugins/design-skills/README.md +++ b/plugins/design-skills/README.md @@ -15,6 +15,8 @@ Third-party design skills, copied here so they install with the rest of lippstac | `remove-animations` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/remove-animations) @ `5206a95` | Finds motion the interface doesn't need (keyboard actions, high-frequency surfaces, decoration) and deletes it. Only subtracts. | | `hallmark` | [nutlope/hallmark](https://github.com/nutlope/hallmark) @ `407fa68` (2.0.0) | Pushes generated pages away from the generic AI look: a fixed floor of rules, a dealt theme, and a lint script (`sloplint`, needs Node) that must pass before it hands back. Builds from the real product when it can capture it. Verbs `audit` and `redesign`. | +| `unslop-ui` | [felipebasurto/unslop-ui](https://github.com/felipebasurto/unslop-ui) @ `cd89116` | Removes generic AI patterns from interface copy and charts; optional surface cleanup. Runs only when requested. | + ## Install ``` diff --git a/plugins/design-skills/skills/unslop-ui/LICENSE b/plugins/design-skills/skills/unslop-ui/LICENSE new file mode 100644 index 0000000..0f03880 --- /dev/null +++ b/plugins/design-skills/skills/unslop-ui/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Felipe Basurto + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/design-skills/skills/unslop-ui/SKILL.md b/plugins/design-skills/skills/unslop-ui/SKILL.md new file mode 100644 index 0000000..68c745c --- /dev/null +++ b/plugins/design-skills/skills/unslop-ui/SKILL.md @@ -0,0 +1,149 @@ +--- +name: unslop-ui +description: "Cut AI tells from interface and chart copy: eyebrow labels, 01/02/03 numbering, redundant subtitles, captions that explain what is already visible, leaked design notes, decorative badges, status dots, chart clutter and legends a direct label could replace. Applies /pstack:unslop to every string it keeps. With --surface it also fixes gradients and glows, off-scale spacing, extra-heavy weights and decorative motion. Only runs when explicitly requested." +disable-model-invocation: true +argument-hint: "[file, folder or component] [--surface]" +allowed-tools: Bash(python3 *scripts/count_tells.py *), Bash(python3 *scripts/load_unslop.py), Read(~/.claude/skills/unslop-ui/**), Read(~/.agents/skills/unslop-ui/**), Read(~/.claude/plugins/cache/**/unslop-ui/**) +--- + +# Unslop UI + +Edit the visible text and decorative chrome of a web page, app screen, chart or dashboard so it stops reading as AI-generated. A good interface is used, not read: keep the words a person needs to act, and cut the rest. + +Target: $ARGUMENTS + +If the target above is empty or still shows a placeholder, take it from the user's message. With none there either, use the files changed in this conversation, or ask. + +Scope: copy, decoration and charts by default (U1 to U16). If the arguments include `--surface`, also apply U17 to U20 (gradients and glows, off-scale spacing, heavy weights, motion), using the values in [references/tokens.md](references/tokens.md). Strip `--surface` from the target before reading paths. + +## Writing rules from /pstack:unslop + +Apply these to every sentence you keep or write. Cite them as "unslop 13", so they don't read as U rules. + +!`python3 ${CLAUDE_SKILL_DIR}/scripts/load_unslop.py` + +If the line above still shows a command instead of rules (agents other than Claude Code), run `python3 scripts/load_unslop.py` from this skill's folder and apply what it prints. + +Where these and the UI rules disagree, the UI rules win: + +- Labels, buttons, tabs, table headers, KPI captions and badges are fragments by design ("Last 30 days", "+12% vs last month"). The rules about sentences (28, 29) apply to full sentences only: hero copy, descriptions, empty states, errors. +- Rule 13 does not cover a lone "—" that stands for an empty value, or an en dash in a range ("Jan–Mar"). + +## Cut first, write little + +Deleting is the default fix. Where a rule says rewrite (U3, U8, U12), the new text may state only what the source already shows: the product's own copy, the names of its features, the data bound to the screen. Never add a number, a speed, an integration or a benefit you cannot point to in the code. With nothing true to say, delete the string, or leave it and list it as a task. + +## UI rules + +Ids are stable. Cite them as U1 to U20 in the report. + +### Interface copy + +- **U1. Eyebrow labels.** Small uppercase or letter-spaced text above a heading ("PASSPORT", "FEATURES", "HOW IT WORKS"). It also comes as a pill or chip, often with a dot ("● POLAR EXPEDITIONS"), and as a caption over a menu or dropdown list ("POPULAR DESTINATIONS"). Delete it. The heading already says what the section is. +- **U2. Decorative numbering.** "01 02 03", "01 // Features", "§", "//" prefixes. Delete unless the order is real and the user follows it (steps of a checkout, a numbered install guide). +- **U3. Subtitle reflex.** A subtitle under every heading, or a line above the H1. Keep one only when it states a fact the heading doesn't. "Analytics / Understand your data better" loses the second line. The same goes for a blurb under every item of a menu, dropdown or card list ("Greenland / Discover majestic ice fjords"): keep it only when the names alone can't tell the items apart (plan tiers, settings), and then only for the items that need it. +- **U4. Botsplaining.** Captions, helper text and descriptions that narrate what the element visibly does ("Click the button below to get started", "This chart shows revenue over time"). Delete. Empty states, error messages and confirmations of destructive actions are not deleted, but they are edited: one or two plain sentences that say what happened and what to do next, without "Oops!" or an exclamation mark. +- **U5. Leaked design notes.** Text about how the screen works or why it was designed that way, long parentheticals, "(updates in real time)", "(powered by AI)". Delete it, or move it to a tooltip if a user would genuinely look for it. +- **U6. Status strings.** Facts chained with "·" or "|" ("12 items · Updated 2m ago · Synced · v2.1"). Keep the one fact the user acts on. Put others where they're needed, or drop them. A fact that claims live state ("Synced", "All systems operational") has to pass the real-state test under Decoration, or it goes. +- **U7. Labeling everything.** A label that repeats the placeholder, the icon, the button text or the section heading. Pick one cue. In a form the cue that stays is the visible label: cut a placeholder that repeats it (one that shows a format, "name@company.com", can stay) and helper text that restates it or says what the field is obviously for ("We'll use this email to contact you"). A constraint the user can't guess ("At least 12 characters") stays. A search field with a magnifier icon takes a placeholder or a label, not both. +- **U8. Staccato and empty slogans.** "One. Big. Thing.", "Built different.", "Ship faster. Think less." Rewrite as one sentence that names the thing and what it does, in words the page already uses, or delete. + +Length: a section heading, card title or caption inside an app screen stays at 5 words or fewer. A hero heading may be one sentence. + +### Decoration + +The test for real state, in U6, U9 and U10: the element renders from a condition or a value (`{isLive && ...}`, `status === "online"`, a prop, a query result). Markup that always renders with fixed text is decoration. + +- **U9. Badges and pills without real state.** "LIVE", "NEW", "AI", "Beta", "Pro", "🔥 Popular" added for flavor. Keep a badge only if it reflects data the app actually tracks (a real stream is live, an item is actually new since the last visit). +- **U10. Status dots.** Pulsing or colored dots (`animate-pulse`, small `rounded-full` dots) next to text. Keep only if bound to a real live status. A loading skeleton that pulses is not a status dot. +- **U11. Decorative emojis and icons.** In headings, buttons, KPI labels and feature lists, including the icon in a tinted square above each feature card. Delete. An icon stays if it is the control itself (icon button with an `aria-label`), if it carries meaning the text does not, or if it sits in a toolbar or in a menu of actions (edit, copy, delete) where every item has one. A menu of destinations or pages whose icons are generic pictographs (a mountain for Svalbard, a compass for Greenland) is decoration: the icon says nothing the name does not. An icon in a tinted, rounded box is the same tell and goes with its box; delete the wrapper too. + +### Charts and dashboards + +- **U12. Chart titles that name the chart type.** "Bar chart of monthly revenue" becomes "Monthly revenue". When the data is fixed (a report, a static figure) the title can be the finding instead: "Revenue doubled since March". A chart fed by live data keeps the neutral title, because a finding goes stale. +- **U13. Reading instructions.** Subtitles or captions that explain how to read the chart ("Each bar represents one month", "Hover for details"). Delete. +- **U14. Saying it twice.** Each quantity gets one encoding. A bar, a number on the bar, a gridline at its height and an axis tick all saying the same value is three too many; a KPI with arrow plus percent plus the word "up" plus a sentence under it ("Revenue grew 12% compared to last month") is the same mistake in text. Keep the encoding the reader needs: axis and gridlines for shape, a printed value for the number that matters (often only the last point or the max). A KPI keeps its figure, one direction cue and the period it compares against ("▲ 12% vs last month"). +- **U15. Chart scaffolding that competes with the data.** A frame box around the plot area, dark or dense gridlines, minor ticks, thick axis borders, 3D, drop shadows and glows on marks, background fills behind the plot. Delete them, or make what must stay (a few gridlines, one baseline) a hairline in a light gray. Data on top, labels next, scaffolding faintest. Do not redesign the chart: same type, same data, same series colors. +- **U16. Legend where a direct label works.** A legend box that makes the reader match colors to names, when the name could sit at the end of the line or next to the bar. Label the series directly, ideally with its latest value ("This year 1,150"), and remove the legend. Keep a legend for more than four series or when the marks are too close to label. + +### Surface (only with `--surface`) + +Each rule pairs the tell with its fix. Read [references/tokens.md](references/tokens.md) for the values. If you can't open it, the values in these four rules are enough. + +- **U17. Gradients and glows.** A gradient from one hue to another on a surface, button or active item, gradient text (`bg-clip-text`), colored glows (`shadow-[0_0_20px_...]`, `shadow-purple-500/50`), blurred color blobs behind content. Fix: a solid neutral surface, solid text color, a neutral shadow no stronger than `0 1px 2px rgb(0 0 0 / 0.05)`, or a hairline border. A gradient that is only a tone shift inside one neutral can stay. +- **U18. Off-scale spacing.** One-off values such as `mt-[13px]`, `py-[11px]`, `gap: 7px`. Fix: the nearest step of 4, 8, 12, 16, 20, 24, 32, 40, 48, 64. Inside a control, 2, 6, 10 and 14 are also steps. Siblings that do the same job (rows of one list, cards of one row) get the same value. Keep an odd value that exactly centers something. +- **U19. Extra-heavy weights.** `font-extrabold`, `font-black`, `font-weight: 800` or `900`. Fix: 500 or 600, and let size and color carry the hierarchy. +- **U20. Decorative motion.** `transition-all`, `hover:scale-*` on cards, `animate-bounce`, springs and overshoot on simple UI. Fix: transition named properties (`transition-colors`) at 150ms ease-out, keep a press scale of 0.97 to 0.98 if the control has one. Motion that explains something stays. Pulsing dots are U10. + +U17 to U20 never change the palette, the type family, the type sizes, the radii, the layout structure or the order of sections. They replace a value with a better value, they don't redesign. + +For before/after pairs, read [references/examples.md](references/examples.md) when unsure how far to cut. + +## Guardrails + +- Change visible text and decorative elements only. Do not touch logic, data, colors, spacing tokens or layout structure. The exceptions are chart scaffolding under U15, which may be thinned or lightened, and U17 to U20 when `--surface` is on. +- If the project already has tokens (Tailwind theme, CSS variables, a design-system package), fix toward those and not toward the fallback values in `references/tokens.md`. +- Never change a screen that has nothing to cut. See the verdict in step 3. +- When you delete an element, delete what existed only for it: its now-empty wrapper, a wrapper left holding a single child it only grouped, the margin or gap, the import or variable nothing else uses. +- Never delete `aria-label`, `alt`, `title` on icon buttons, or screen-reader-only text. If cut visible text was the only accessible name, move it into `aria-label`. +- A form field keeps a visible label tied to its input (`for` and `id`, or a wrapping `