
design-skills
A design workflow that starts by itself: setup interview, /design, states, options, design system and self-critique.
- GitHub stars
- 7
Install
/plugin install design-skills@design-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add diego3g/design-skills.
Contents
Discovered from sourceSkills 7
Design critique
Overview
Critique the screen people will see, not the source you can read: render it first. Run the rules as a checklist, rank what you find by how much it hurts the person using the screen, and report before you change anything, unless you were asked to refine. When you refine, fix only what the findings name, then look again.
When to use
- "Review this", "what's wrong with this screen?", "refine", "polish", "it feels off".
- You just finished a screen and are about to show it.
- Before handing a design to code.
When NOT to use
- A specific edit ("fix the typo", "make it blue"): make it. You may mention a serious problem you noticed in one line, without fixing it.
Before you start
- Read
DESIGN.mdat the project root if it exists: it is the project's design brief. - Read the project's design system. Where it differs from a default in the rules, the project wins. Don't flag it as a defect; note the difference once.
- Pick your tool's adapter in
references/adapters/(paper.md,figma.md,html.md). If no adapter matches your tool, do the same verbs in your tool and say which you mapped by hand. With no design tool at all, build in HTML (html.md). If an image is all you have, say that values read from it are estimates. - Decide the mode:
- review: the person asks about a design ("review", "critique", "what's wrong"). Report only.
- refine: the person asks to improve one ("refine", "polish", "fix it", "make it better").
- self-check: your own work that the person hasn't seen yet, including when another design skill calls this one. Fix what you find within the task's scope, render again, then show it with a short list of what the check changed.
Steps
-
Render it and look. Take a screenshot at the size people use, and at a phone width if it's responsive. Look at it as the person using it would, and answer:
- What do I see first?
- Is that the most important thing?
- What is the one next action?
If you cannot render, say so at the top of your answer, and mark the findings that need a render to confirm.
-
Run every rule group in the rules: hierarchy, space, stability, interaction feel, contrast and colour, text, consistency, motion. Check each state the screen shows, not only the default.
-
Rank the findings by impact on the person:
- blocks or misleads;
- slows down;
- looks careless.
For each one: the problem, where it is, why it matters, and the fix.
-
Review mode: deliver the ranked report and stop. Don't write a fixed version or edit any file until the person picks the fixes. Refine and self-check modes:
- apply the fixes, limited to what the findings name: no new layout, no new sections, no new files, no restructured files;
- render again with the same command and sizes as step 1 (if it worked then, it works now: try it before saying you can't);
- re-run the checks on what changed;
- report each fix and anything that is still open.
-
A fix that changes a shared component (a button used on twenty screens) is not a local fix. Name it, and hand it to the design-system process, so every screen that uses the piece changes together.
Rules (summary; detail in references/rules.md)
| Group | The core check |
|---|---|
| Hierarchy | One thing wins the first glance; at most one primary action; when in doubt, remove |
| Space | No dead or oversized areas, no cramped groups; repeated rows align in fixed-width slots |
| Stability | Nothing changes size when loading, swapping labels, selecting or toggling |
| Interaction feel | Hover is quieter than selected; focus ring only from the keyboard; pointer cursor only on links (on the web, follow the project's convention) |
| Contrast and colour | Small text readable on tinted and grey grounds; one strong colour moment |
| Text | No one-word last lines; titles capped in lines; plain words; says what happens next |
| Consistency | The same piece looks the same everywhere; banners only for whole-app problems |
| Motion | Only where it helps; opening slower than closing; respects reduced motion |
Done when
- Review: a rendered look (or an explicit "couldn't render") and every rule group checked; a ranked report; nothing changed.
- Refine / self-check: the named fixes applied, re-rendered and re-checked, and the report says what changed and what's still open.
Common mistakes
| Thought | Reality |
|---|---|
| "I can read the HTML/CSS, that's enough" | People see pixels. Wrapped titles, overlaps and shifts only show when rendered. Render, or say you couldn't. |
| "I'll include a fixed version so they see the result" | In review mode that's choosing for them. Report; fix what they pick. |
| "The loading button looks broken" | Name the class of problem: it changes width. Layout shift is the finding, and the fix is a fixed width with the label hidden under a spinner. |
| "The headline is long" | Check how it breaks: a one-word last line is a finding on its own. Balance the lines. |
| "While refining, I'll also add a max width, a phone layout and split the CSS" | Refine fixes the findings. Anything else is a new proposal: list it, don't do it. |
| "I couldn't render after the fixes" (when the first render worked) | Run the same command again. The re-check is the point of refining. |
| "Their hover equals their selected, that's a bug" | Check the project's guide first. If it says so on purpose, it's their rule. Note it, don't flag it. |
Design setup
Overview
Before the first screen, agree on what the product is, who it's for, how it should feel and what it should never look like. Write that down in DESIGN.md, the brief every later design decision reads first. Ask, don't invent: a brand made up by the agent is a guess the person will have to undo. Read what exists, interview the person one question at a time, write the brief, stop for approval, then build the foundations.
When to use
- A design task and no
DESIGN.mdat the project root. - "Set up the design", "define our style / brand / guidelines",
/design-setup.
When NOT to use
DESIGN.mdexists and the task is a design: usedesign.- Changing one token or one guideline: use
design-system.
Steps
- Read first. README, docs, existing CSS or tokens, the design file, brand folders, any old
DESIGN.mddraft. Write down what they already answer. Never ask a question these files answer. Confirm it in one line instead ("Your README says pt-BR only and members over 60, so I'll design for 18px text and 48px taps"). - Interview, one question per message. Follow the interview in its order: product, audience and voice, mood, brand, references, constraints.
- Offer 3–5 options plus "something else" whenever you can.
- Skip any question already answered.
- Stop when the answers are enough to design the first screen. Six good answers beat fifteen.
- References are required. Ask for 2–5 products, sites or images they like. For each one, ask what to take and what to avoid. If it's a link or an image you can open, look at it and say what you see before asking.
- Write
DESIGN.mdat the project root from the template, with all eight sections: Product, Audience and voice, Mood, Brand, References, Constraints, Decisions log, Open questions.- Use their words where you can.
- Anything you inferred and they didn't confirm goes under Open questions, not into the brief as fact.
- Stop and show the person
DESIGN.md. Change it until they approve it. - REQUIRED SUB-SKILL: use
design-systemin create mode for the foundations (tokens, type, spacing, interaction rules). It has its own approval stop.- Existing tokens and styles are the starting point: extend them, don't rename or move them without asking.
If the person says "skip" or "just design it"
Don't keep asking. Write a minimal DESIGN.md from what you read and what they said:
- every gap becomes an Open question;
- every assumption is marked "(assumed)".
Say in one line which assumptions matter most. "Skip" waives the interview and the brief's approval stop. If the project has no tokens yet, the foundations step (and its stop) still runs, because design can only draw with system pieces. Then continue with the task they asked for.
Before you start
- If no adapter in
references/adapters/matches your tool, do the same verbs in your tool and say which you mapped by hand. With no design tool at all, build in HTML (html.md). If an image is all you have, say that values read from it are estimates. DESIGN.mdis a plain Markdown file in the repo in every tool. Only the optional references board lives in the design tool.
Rules
| Rule | Why |
|---|---|
| One question per message, with options | A wall of questions gets skimmed and half-answered |
| Read before asking; never ask what the files say | Asking what's in the README tells them you didn't look |
| No invented brand: colours, fonts and mood come from them or are marked "(assumed)" | An invented brand is a guess they have to undo screen by screen |
| References always come with take/avoid | "I like Stripe" is useless; "take the calm spacing, avoid the gradients" is a rule |
| "Never like" is asked explicitly | What to avoid narrows the design faster than what to aim for |
| Don't redesign existing files during setup | Setup records decisions; changing their CSS is a design task they didn't ask for yet |
| No screens during setup | Screens come from design, after the brief and foundations are approved |
Done when
DESIGN.md is approved with its eight sections, and the foundations are approved through design-system. After a "skip": DESIGN.md is written with its assumptions marked, the foundations exist (approved, or already in the project), and the original task has continued.
Common mistakes
| Thought | Reality |
|---|---|
| "I'll pick a nice palette and fonts, they can change it" | They can't change what they didn't know was decided. Ask, or mark it "(assumed)". |
| "While I'm here I'll mock the main screens" | That's design's job, after approval. Setup ends at the brief and foundations. |
| "Let me ask all six questions at once to save time" | One per message, with options. It's faster for them to answer. |
| "Their tokens are messy, I'll restructure them" | Extend them. Restructuring is a separate, approved change. |
| "No references given, I'll skip that section" | Ask for them. If they have none, offer three that fit the mood and ask what to take and avoid from each. |
Design system
Overview
A design system is the place where a decision is made once and then reused everywhere. Every colour is a token, every interactive piece shows all its states, and every change reaches every screen that uses the piece. Build it in layers, foundations first, and stop for approval at each layer. An audit reports and never fixes on its own.
When to use
- "Start a style guide / design system / tokens for …"
- Adding a component, variant or token, or changing an existing one.
- "Make these screens consistent", "standardize", "audit the guide", or loose hex values and one-off pieces in the screens.
When NOT to use
- A question about one value ("what's our primary colour?"): answer it.
- A small edit the person described exactly (one value, one label, one size), even on a shared piece: change it once where it's defined and say which screens it affects. No states matrix, no stop.
Before you start
- Read
DESIGN.mdat the project root if it exists: it is the project's design brief. - Find what exists: tokens, the guide, the components, the screens and the code. An existing guide wins on look. Follow its rules even where they differ from the defaults below, and mention the difference once.
- Pick your tool's adapter in
references/adapters/(paper.md,figma.md,html.md). If no adapter matches your tool, do the same verbs in your tool and say which you mapped by hand. With no design tool at all, build in HTML (html.md). If an image is all you have, say that values read from it are estimates. - Decide the mode: create, add or change, or audit.
Steps · create
-
Foundations draft:
- colour roles (token roles);
- type scale;
- spacing;
- radius;
- shadows (two at most);
- layout widths;
- motion durations;
- a short "how we write" section.
Name tokens by role (
text-muted,border-hover,danger-bg), never only by value (gray-500). -
Interaction rules, once: for bordered pieces, borderless pieces and the primary action, write how hover, pressed, focus (keyboard only), disabled, loading and selected look. Components follow these rules instead of each inventing its own.
-
Stop and show the person the foundations and the interaction rules. Don't build components yet.
-
Components one at a time, in the order the first screens need them. Each gets a guide section with the component anatomy: a legend with the rule and why, examples, and a states matrix of variants × states. Add each one to the component index.
Steps · add or change a piece
- Check whether an existing component plus a variant covers it. Prefer reuse to a one-off.
- Draw it with the anatomy, including the full states matrix. A new colour, size or icon becomes a token or an icon-set entry now, not later.
- List every screen and code location that uses the piece.
- Stop and show the person the change and that list.
- On approval, propagate:
- update every screen on the list;
- update the code, if any;
- update the component index;
- report what changed where.
Steps · audit
- Run the audit checklist over the guide, the screens and the code if any.
- Write the report: findings ranked by severity, each with where it is, why it matters and the proposed fix.
- Stop and show the person the report. Change no file until they say which fixes to make. Saving copies of the originals doesn't make editing them acceptable.
Rules
Firm (any project):
| Rule | Why |
|---|---|
| Every colour is a token; no loose hex values in screens or code | Loose values drift into near-duplicates that nobody can change at once |
| One icon set | Mixed sets look like mixed products |
| Design and code change together, design first | Otherwise the guide stops being the truth within a week |
| Every interactive piece has a states matrix | States drawn ad hoc on screens never agree |
| A change to a shared piece is listed with the screens it affects before it propagates | Otherwise one "small" change silently redesigns twenty screens |
Defaults (an existing guide overrides them):
| Default | Why |
|---|---|
| On hover, bordered pieces only darken the border | A changing background on cards and fields feels heavy |
| Hover is subtler than selected | When hover looks like selected, people think two things are chosen |
| Selecting never changes font weight | A weight change shifts the text's width |
| Placeholders are lighter than muted text | Otherwise a placeholder reads as entered text |
| Items in stacked lists and menus have a small gap, never touching | Touching highlights merge into one block |
| The focus ring only appears from the keyboard | A ring after a mouse click looks like a bug |
| Loading keeps the element's exact size | Layout shift |
| Shadows only on floating things (menus, popovers, dialogs, toasts), at two strengths | Shadows everywhere flatten the hierarchy they were meant to create |
| At most one primary action per screen | Two primaries means the screen didn't decide |
Done when
- Create: foundations and interaction rules approved; each component has its anatomy, states matrix and an index row.
- Change: every listed screen and code location updated, and the index updated.
- Audit: a ranked report delivered and no file changed.
Common mistakes
| Thought | Reality |
|---|---|
| "I'll build the whole guide in one go: tokens and ten components" | Ten components on unapproved foundations means ten reworks. Foundations, stop, then components. |
| "The audit found problems, I'll just fix them" | The person may disagree with half of the fixes. Report, stop, fix only what they pick. |
| "I kept the originals in a backup folder, so fixing is safe" | A backup doesn't make the person agree with the fixes. Report first. |
| "Buttons have hover and disabled, good enough" | A states matrix has every state × every variant: normal, hover, pressed, focus, disabled, loading, selected. |
"--teal-600 is a token" | It's a value. Components need roles (--color-primary) so the value can change in one place. |
| "This screen needs a slightly different card" | Make it a variant of the card, or use the card. A one-off is the start of drift. |
Design
Overview
The front door for making anything visual. It turns "design the pricing page" into a finished, reviewed design. It works from the project's brief, covers every state, offers options only when the direction is open, uses only the design system's pieces, and checks its own work before showing it. It calls the other design skills at fixed points; it doesn't replace them.
When to use
- "Design / create / mock up / redesign the <page, screen, flow, element>",
/design. - Several pages at once ("design the onboarding: welcome, sign-up, verify").
When NOT to use
- A small edit the person described exactly (one value, one label, one size): make it.
- Only a review ("what's wrong with this?"):
design-critique. Only options:three-proposals.
Before you start
- If no adapter in
references/adapters/matches your tool, do the same verbs in your tool and say which you mapped by hand. With no design tool at all, build in HTML (html.md). If an image is all you have, say that values read from it are estimates.
Stops are real
A stop means: end your turn with the question and wait. You can always do that, even in a one-shot or headless session, where your final message is the question. Never decide a stop for the person because the session "can't wait" or "to save a round trip". Deciding it yourself turns a five-second answer into hours of redoing.
Steps
- Context.
- Read
DESIGN.mdat the project root. If it's missing → REQUIRED SUB-SKILL:design-setup, then come back here. - Read the design system (tokens, components, guide) and the screens related to this one.
- When the brief and the code disagree (the brief says teal, the tokens say blue): follow the code, say so in one line, add the conflict to
DESIGN.md› Open questions, and offer to update whichever is wrong. Never override tokens inside a page's own CSS.
- Read
- Scope in words. List each page or element to make, each with its job and its one next action.
- Ambiguous words get one interpretation stated plainly ("pricing page = the bakery's price list, not subscription plans").
- Stop and confirm the list when there's more than one item or the request is vague. One clear item: go on.
- For each item, in order:
- REQUIRED SUB-SKILL:
screen-states. Its written state list and its stop come first. - Open direction? Only when the person asked for ideas, or when two structurally different layouts are plausible and neither the brief nor the system chooses between them → REQUIRED SUB-SKILL:
three-proposalsbefore drawing the states. For several pages, ask at the scope stop which page (if any) gets options; never run an option round per page by default. The states are then drawn in the picked direction. A screen that follows an existing pattern goes straight to drawing. - Draw the main state, then the other states, using only the system's pieces and tokens. Something new (a component, a colour, a size the scale doesn't have) → REQUIRED SUB-SKILL:
design-system(add mode) before using it. Never hard-code a new value in a page. - REQUIRED SUB-SKILL:
design-critiquein self-check mode on every board: render it, fix what it finds within this task's scope, and render again.
- REQUIRED SUB-SKILL:
- Close.
- Show the result with the summary below.
- Append the decisions to
DESIGN.md› Decisions log (date, decision, why). - Move any question that got answered out of Open questions.
Closing summary (the shape of your final message)
Made: <pages/elements> — <where: files or boards>
Decisions: <each, one line with its why> (also in DESIGN.md › Decisions log)
System changes: <pieces or tokens added/changed> — affects: <screens>
Self-check fixed: <what design-critique changed before you saw it>
Open questions: <what the person still has to decide>
Rules
| Rule | Why |
|---|---|
DESIGN.md first, every time | Without the brief every screen invents its own style |
| Scope confirmed before work when it's more than one item | Three pages built on a wrong reading is three pages wasted |
States list before drawing (via screen-states) | The happy path is one state of many |
| Options only when the direction is open | Options on a solved pattern waste the person's attention |
Only system pieces and tokens; new ones go through design-system | Hard-coded values in pages are where drift starts |
| Code beats a stale brief; note it, don't override | The tokens are what ships; the brief is updated by decision, not silently |
| Self-check before showing | The person should review design, not catch mistakes |
Decisions go into DESIGN.md | Next session's design starts from them, not from memory |
Done when
Every item in the confirmed scope has its states drawn and self-checked, any system change has gone through design-system, the closing summary has been given, and DESIGN.md's Decisions log has been updated.
Common mistakes
| Thought | Reality |
|---|---|
| "Three pages are clear enough, I'll just build them" | Confirm the list first. It costs one message. |
| "I'll make buttons 52px here; the token says 44, but this audience needs bigger" | That's a system decision. Propose it through design-system, then use it everywhere. |
| "The brief says teal, so I'll override the blue in this page's CSS" | Code wins. Flag the conflict and ask; never patch tokens locally. |
| "I'll show it, they'll tell me what's wrong" | Run design-critique in self-check first, and say what it fixed. |
| "The decisions are in my message, that's enough" | Messages scroll away. Append them to DESIGN.md. |
| "This session can't stop for answers, so I'll make the calls myself and list them" | Ending your turn with the question is stopping. Do that; build nothing past the first open stop. |
| "To save a round trip I'll put both stops in one message" | Fine, if you then stop. Ask both, build nothing, wait. |
Screen states
Overview
A screen is not designed until every state it can be in is designed. The happy path is one state out of twenty. List the states in words first, get the list approved, then draw. Agreeing on a list costs a minute. Discovering a missing state in code costs a day.
When to use
- A new screen, flow or component, or a redesign of one.
- "Cover all the states", "what are we missing?", "is this ready for dev?"
- The design shows one perfect case: three orders, short names, everything loaded.
When NOT to use
- A small edit to an existing screen ("make the button 2px taller", "fix this typo"). Make the edit and stop.
- Pure copy changes, or a question about the design.
Before you start
- Read
DESIGN.mdat the project root if it exists: it is the project's design brief. - Read the project's design system and existing screens. They win on look: reuse their empty state, banner and loading pieces instead of inventing new ones.
- Pick your tool's adapter in
references/adapters/(paper.md,figma.md,html.md). If no adapter matches your tool, do the same verbs in your tool and say which you mapped by hand. With no design tool at all, build in HTML (html.md). If an image is all you have, say that values read from it are estimates. - Know the screen's job: who uses it, what they came to do, and what the one next action is.
Steps
-
Write the state list. Walk every group in the state catalogue: Data, System, Activity, People, Interaction. Mark each item in one of three ways:
- applies, with a one-line description of what the screen shows;
- doesn't apply, with a reason;
- open question for the person.
Stop and show the person the list. Do not draw yet.
-
Draw the main state with realistic invented data: the most complex realistic case, not the tidiest. Use long names, many items, and mixed statuses. Build it one section at a time, and check each section rendered before the next.
-
Draw every other state that applies:
- a state that changes the whole screen (empty, offline, couldn't load) gets a full board;
- a state that changes one part (a failed row, a saving button, a stale banner) goes on a state sheet that shows just that part.
-
Check every state:
- Does it offer the action that resolves it, and say who does it?
- Does moving between states keep the layout still (same widths and heights, no jumping)?
-
Name and order the boards as described in naming and sheets:
<number> · <screen> · <state>, the main state first, the other states next, sheets last, and a cover note at the start of each row. -
Look at what you made. Screenshot or render every board and compare it with the list. If you cannot render, say so plainly, and name what wasn't checked.
Rules
| Rule | Why |
|---|---|
| The list comes before any drawing, and the person approves it | It's the cheapest moment to find a missing state or one that doesn't apply |
| Sample data is long, many and messy | Short tidy data hides truncation, overflow and wrapping bugs |
| Assume more than one person uses it | "Someone else already did it" and "changed while you looked" happen every day |
| No state without a way out: what to do next and who does it | A dead end makes people call support |
| A failure is worded as a failure, never as a deliberate pause | "Stopped" reads like someone chose it; "Couldn't save" tells the truth |
| One standard empty-state piece across the product | Ten bespoke empty states drift apart and cost ten times more |
| A whole-app problem goes in a top banner; a problem with one item goes inline on that item | A banner for one row's error shouts at everyone about nothing |
| Loading and label swaps keep the element's size | Layout shift makes people click the wrong thing |
| Interaction states (hover, focus, disabled…) come from the design system's states matrix | Redrawing them on every screen creates drift; draw them once, in the system |
Done when
Every catalogue item is drawn, marked "doesn't apply" with a reason, or listed as an open question. The boards are named and ordered, and you looked at each one or said which you couldn't.
Common mistakes
| Thought | Reality |
|---|---|
| "I'll just design all the states in one go, it's faster" | Without an approved list you draw states nobody needs and miss the ones they do. List, stop, then draw. |
| "Three sample orders show the idea" | Show forty, and show a customer called "Maria Fernanda de Albuquerque Santos". The overflow state is a real state. |
| "Loading, empty, error, offline: covered" | Those are four of the catalogue's groups' easiest items. Also check many/overflow, long text, someone-else-did-it, changed-while-viewing, permissions and slow. |
| "I'll put all the states on one page" | An unnamed pile can't be reviewed or handed off. Name and order the boards. |
| "I couldn't render it, but it's fine" | Say what you couldn't check. Unverified layout is a guess. |
Red flags: stop and go back to step 1
- You are drawing and no state list was approved.
- Every name in the mock fits on one line.
- The design never mentions a second person.
Three proposals
Overview
When someone asks for options, they want to choose, not to be handed a winner. Give them three directions that solve the problem in genuinely different ways, side by side, at the same fidelity, next to what exists today, with your recommendation first. Then wait for the pick.
When to use
- "Give me options", "3 variations", "other directions", "what else could this be?"
- "I don't like this", "rethink it", "try something different".
- "Design both so I can choose": that means two.
When NOT to use
- A specific change ("change the title to Preferences", "make it blue"): make it.
- One clear fix the person already described.
Before you start
- Read
DESIGN.mdat the project root if it exists: it is the project's design brief. - Read the project's design system and the screen in question. All options use the system's pieces and tokens: options differ in design, not in brand.
- Pick your tool's adapter in
references/adapters/(paper.md,figma.md,html.md). If no adapter matches your tool, do the same verbs in your tool and say which you mapped by hand. With no design tool at all, build in HTML (html.md). If an image is all you have, say that values read from it are estimates.
Steps
-
Restate the problem in one or two sentences: what's wrong today, and what a good result must do. If the request was only "make it better", name the problem you see. Stop and confirm it with the person before designing. If they already named the problem, go on.
-
Choose the directions on different axes (divergence axes): structure or placement, interaction model, density, emphasis, or what gets removed. Write each direction as one line: the idea and its trade-off. Directions must differ: a different axis, or clearly different values on one axis when the person names the axis ("too dense" → three density answers). A change of colour, theme or font is never an axis.
-
Build the comparison board in a temporary area (comparison board):
- a legend card (each option's idea, what it's good at, what it costs, and the recommendation with its reason);
- "Current", a copy of today's design, when one exists;
- options A, B, C, the same size and with the same realistic data.
Never edit the real screens.
-
Draw every option with final-screen care, including the states that its difference affects. If B moves an action into a menu, show the menu open.
-
Present the recommendation first, then one line per option. Stop. The person picks, combines ("B with A's header"), or rejects all of them.
-
After the answer:
- Pick or combination: apply it to the real screens and the design system (and its propagation to every screen that uses a changed piece), then clear the temporary area.
- All rejected: go back to step 1 with their reason as the new problem statement. Allow changes to the surrounding parts. Never answer a rejection with small tweaks of the same options.
Rules
| Rule | Why |
|---|---|
| Three by default; two for "both" (when they named both options, skip the bolder-option rule); exactly the number they ask for otherwise | The count is theirs; three is enough to compare without fatigue |
| Different axes, not different paint | Three layouts in three colour schemes is one idea with three skins |
| Always recommend, and say why | They asked an expert; "tell me which you like" hands the work back |
| "Current" sits on the board | People judge change against what they know |
| Same data, same size, same fidelity | A polished option next to sketches is a vote, not a choice |
| No straw men: every option is one you'd defend | Fake options waste the person's attention and trust |
| One option is deliberately bolder | Otherwise the set only covers safe variations |
| Real screens stay untouched until the pick | Options that leak into the product are decisions nobody made |
Done when
The board shows the legend, Current and every option at equal fidelity; the recommendation is stated first; you have stopped for the pick. After the pick: applied to the real screens and the system, and the temporary area cleared.
Common mistakes
| Thought | Reality |
|---|---|
| "Option C: the same page in a dark theme" | Theme is paint, not a direction. Change structure, interaction, density, emphasis or what's removed. |
| "I'll let them choose without biasing them" | Not recommending isn't neutral, it's unhelpful. Recommend first, with the reason. |
| "The original file is unchanged, so they can compare" | Put Current on the board, next to the options. |
| "They rejected all three, I'll adjust the closest one" | A rejection is new information about the problem. Restate it and diverge again. |
| "They asked for 5, but 3 is the method" | Give 5. The divergence rule still applies to all of them. |
| "Options share the same fixes, so they look alike" | Shared fixes are fine. Say so once in the legend and make the main axis differ. |
A design skill that applies is not optional. Small edits are the only exception (see below).
How
- Check the routing table below. The one thing to look at first is whether
DESIGN.mdexists at the project root; it decides betweendesign-setupanddesign. Don't guess it. - Invoke the skill with your Skill tool, and announce: "Using to ."
- Follow it exactly, including its stops for the person's approval. A stop means ending your turn with the question, which is always possible, even in a headless or one-shot session. Never decide a stop for the person.
Routing table
| The situation | Skill |
|---|---|
| Any request to design, create, mock up or redesign a page, screen, flow or element | design |
A design task in a project with no DESIGN.md at its root | design-setup first, then design |
| "Set up the design", "define our style / brand / guidelines" | design-setup |
| "Options", "alternatives", "other directions", "I don't like it", "rethink this" | three-proposals |
| "Review", "refine", "polish", "make it better", "feels off", or you are about to show your own design | design-critique |
| Tokens, the style guide, a new or changed component, "make consistent", "audit" | design-system |
| "What states are missing?", "is this ready for dev?" | screen-states |
A reusable piece for the system ("we need a date picker component") goes to design-system; something on a specific page goes to design. These are this plugin's skills (design-skills:<name> in Claude Code); prefer them over same-named skills from elsewhere.
Priority
design-setupbeforedesignwhen there is noDESIGN.md. Reviews, options for an existing screen, audits and state questions don't need a brief: they work from what's already there.designbefore its sub-skills: it callsscreen-states,three-proposals,design-systemanddesign-critiqueat the right moment, so don't start them yourself in the middle of adesignrun.design-critiqueis the last step before you show anything you made.
Small edits: no process
A change the person described exactly (one value, one label, one element's size, one colour, a typo) is made directly. No skill, no states list, no options.
- If the thing is shared (a button style used on many screens), change it once where it is defined, and say which screens it affects. Don't open a full design pass for it.
- If you're unsure whether it's small, it isn't. Use the table.
Red flags
| Thought | Reality |
|---|---|
| "It's just a quick mockup, I'll skip the process" | A quick mockup is still a design. The states list takes a minute. Use design. |
"There's no DESIGN.md, but the request is clear enough" | Without a brief, every screen invents its own style. design-setup first; the person can say "skip". |
| "I'll draw it now and review it later" | Showing unreviewed work trains the person to do your review. design-critique runs before you show. |
| "I know which states it needs" | You know the happy path. screen-states lists the rest. |
| "Let me read the files first, then decide on a skill" | Skills tell you what to read. Decide first. |
| "This is a small change" (to a new page) | A new page is never a small change. |
| "The session can't wait for answers, so I'll decide and list my calls" | End your turn with the question. Deciding for them is the one thing the stops exist to prevent. |
Other agents
Where this skill isn't loaded automatically, put the routing table above in your AGENTS.md (or the equivalent) so the agent sees it at the start of every session.
Hooks 1
Sponsors
Details
- Marketplace
- diego3g/design-skills
- Category
- Design