Design

design: nothing ships looking or sounding like a default

Groundwork does not make interfaces itself. Making one runs on impeccable, the design method begin installs per project (node checks/design-method.mjs --install; the enforcement line at the top of node checks/check.mjs says whether this project has it, and which release). This skill is the Groundwork side of that seam. It carries what is genuinely ours, hands it over as binding input, and holds open the three points where the owner decides.

docs/DESIGN.md sections 1 and 2 and docs/design/VOICE.md carry the durable principles and the owner's standing defaults. DESIGN.md section 3 is not written here: it is recorded from the world that was actually built, after the finish review (step 4). A rulebook written before the build gets defended against reality instead of describing it.

Where the two documents live. The method reads docs/DESIGN.md and writes its product record to docs/PRODUCT.md, because docs/ is one of the directories it searches by itself. Neither path is configured anywhere, and neither moves. The product record holds what docs/product/BRIEF.md does not own (platform, stack, brand commitments, evidence on hand, accessibility needs) and points at the brief for scope, users and purpose: a fact that stands in both files is a fact that will disagree with itself later.

No design method installed (a project that started without an interface, a failed install recorded in STATE.md)? Install it first. Everything below assumes it is there. When the install genuinely cannot happen, section 5 is the route that still builds, visibly degraded rather than silently worse.

1. Ask the owner: only what is theirs

Two questions, and only these: the method asks the rest at the point where the answer changes the work, and asking twice is how an owner learns their answers do not travel.

1. Brand reality: existing logo, colors, fonts, brand guide? If yes, that is binding: collect the files into docs/design/reference/ and carry them over as a brand commitment in step 3. If no, nothing is blocked; the direction round derives a brand with the owner.
2. Voice: product language (NL/EN/...), register (je/u/you), and whether this audience changes the standing voice default in VOICE.md.

Feel, accent, temperature and visual references are not asked here. They are the substance of the direction round in step 3, where the owner sees them rendered instead of described, and asking for them twice would seed the answer before that round can do its work.

2. Choose the UI foundation: one source of truth for all UI

Before anything is made, exactly one foundation is fixed for this project's UI. It stays a Groundwork decision, made here, that the method then builds within.

You recommend one; the owner confirms or overrules. Comparing ten libraries is a designer's job, and the owner Groundwork is written for is not one: handing over a ten-page showcase moves the research onto the person with the least basis to do it. So do the research and arrive with a recommendation:

1. Read the stack, the brief and the brand reality from step 1. Verify the candidate's current maintenance, licence and accessibility from its official docs (live, never model memory; that is stack skill territory).
2. Recommend one foundation in a short paragraph: what it is, why it fits this product, and what it costs. Name the one real alternative beside it, per critical-thinking, and say what would have to be true to prefer it. Bespoke is the named alternative to every library, and vice versa.
3. Say in one line that the showcase exists and that you will open it on request: docs/design/reference/ui-library-showcase.html holds one page per library (shadcn/ui, Material UI, Chakra UI, Magic UI, Aceternity UI, Nyxhora UI, React-Bootstrap, React Bits, Mantine, HeroUI) plus the bespoke option, each with the same live components. An owner who wants to compare style registers themselves gets it; nobody is required to.

The two shapes the recommendation picks between: a component library themed with the owner's brand, or a bespoke system of the project's own tokens and components. Bespoke is right when the look is part of the product's value, the brand requirements are strong, or the owner wants zero UI dependencies; the owner can also hand over their own ideas, references or existing UI code, which is binding input rather than a candidate.

Rules for this step:

• The foundation is an expensive-to-reverse choice: run the critical-thinking moves before recommending one, not after the owner has agreed.
• The stack constrains the menu. The showcase's ten are React-centric; for another stack, research equivalents live. The showcase shows style registers, not current facts, which is the other reason the research cannot be delegated to it.
• The owner's brand always sits on top: the library provides structure and behavior, the brand tokens flow in through the library's theming layer (or the token file, if bespoke).
• Record the choice as a decision record (see docs/decisions/0009-ui-foundation-choice.md). It travels into step 3 as a constraint the build must hold, and lands in DESIGN.md section 3 when that section is written. One foundation per project: mixing libraries or building raw UI beside the chosen one requires a new decision record first.

3. Hand over, then hold the three decision points

Fill VOICE.md section 3 first (wording table, error-message pattern, banned list, in this product's register and language). Copy is written during the build, so the voice exists before it.

Then hand the method its input, once, and let it run:

• Product truth it must not ask twice for. docs/product/BRIEF.md and docs/product/CONTEXT.md already hold the users, the purpose, the positioning, the constraints and the domain terms, captured by begin in the owner's own words. The method's init step writes docs/PRODUCT.md from that: give it those two files as the source, play the extracted answers back for a one-line confirmation each, and let it interview only for what it genuinely adds and Groundwork never captured: platform (web, iOS, Android, adaptive), brand commitments, the evidence actually on hand, and accessibility needs beyond the floor. What the brief already owns is pointed at from the record, never copied into it. An owner who has just sat through begin's interview answers nothing here twice.
• The binding design input. DESIGN.md section 1 (the ten principles) is a floor: a direction may build any world it likes on top of it, and may not break it. Section 2 (the owner's standing taste) is the pinned seed, and the method honors a pinned brief. The owner may replace section 2 for this project, at the direction round below, in their own words; nobody else may drop it. Also hand over VOICE.md section 3 and the foundation decision from step 2.
• The accessibility floor in principle 8 and docs/compliance/COMPLIANCE.md is not negotiable by any direction.
• The live-surface contract, on a redesign. A surface that already has visitors carries commitments the method does not know about and will not preserve on its own: URL structure and slugs, page titles and structured data, primary navigation labels, form field names and their order, analytics event and field names, the logo or wordmark, and legal or consent copy. Write that list down from the live site before the direction round, hand it over as a constraint, and check the built result against it. Anything on it that does change, changes on the owner's say-so and ships with redirects. Losing the search ranking is the most expensive way a redesign can succeed visually and fail commercially.

The owner decides at three points, in this order. This is the order of work:

1. The visual direction. The method derives candidate worlds from the audience's own culture, an external roll assigns which one is built so runs cannot converge on the category default, and the owner chooses on a decision page with palettes, first viewports and honest risks, with re-roll and steer available. No production code for a new visual world is written before this choice lands. A direction that breaks the floor in section 1, or quietly drops section 2 without the owner saying so, is sent back for another round; it is not accepted and fixed later.

2. The rendered compositions. The chosen direction is rendered as compositions and approved before code exists. The build then reproduces the approved composition rather than reinterpreting it.

   No image generation on this machine? Then draw them yourself, as flat SVG, and say in one line that you did. Every card in a round goes through one shared frame: same size, same matte unfinish, only the product name and one real headline legible, everything else greeked. This is not decoration. A direction round where the catalogue's challengers carry hosted reference plates and the assigned direction carries an empty slot is a rigged comparison, and the owner will feel the pull without being able to name it. Measured on this repo, 2026-08-06: without generation the assigned card and the standing exit render empty while every challenger shows a picture.

3. The finish verdict. A reviewer that never saw the build thread scores the result and returns a table. Report it as it stands, open items intact, under the reviewer's own word for it. A table with open findings is never handed back as a pass, and never summarized into one. Whether to fund another round or ship as it stands is the owner's call.

   Where the reviewer comes from. What this point is for is a reviewer with none of the build thread in its context; which agent the method can spawn is the method's own business and changes between its releases, so this skill does not restate it. Use the reviewer the installed method names if it can be spawned here. If it cannot, spawn a fresh subagent, hand it the method's own finish-reviewer brief (look it up in the payload rather than from a path written here) plus the input packet that brief asks for, and disclose in one line at finish which of the two ran. Measured 2026-09-07: the install now writes four impeccable-* agents into .claude/agents/, impeccable-finish-reviewer among them, so the first route is the live one here. It was the second route a month earlier, on a payload that wrote none, which is the reason this paragraph states the requirement and checks what is installed instead of naming one of them.

An addition inside a surface that already exists inherits that surface: it is not a new identity exercise, and it does not run this round again.

4. Record

After the finish review, DESIGN.md section 3 is written from the built world: the foundation from step 2, the tokens as they exist in code (code is the SSOT, DESIGN.md mirrors it), the component inventory with its states, and the code SSOT location. That mirror is what design-guard and the mechanical checks validate against.

Done means: VOICE.md filled and DESIGN.md section 3 written from the build (TEMPLATE markers removed), tokens in code, decision records for the UI foundation and for any direction that replaced the owner's standing taste, the finish verdict reported with its open items, and STATE.md updated. Owner answers captured verbatim where wording matters.

5. When the method is unavailable: the degraded route

The method is one package from one maintainer, so it can genuinely be missing: npm unreachable, the release gone, a Node floor this machine cannot meet, an install that refuses. The brief's rule is that a capability which cannot degrade visibly does not get built, so this is that degradation, written down before it is needed. Say in one line that you are on this route and why, record it in STATE.md, and build on:

• The rulebook: docs/DESIGN.md section 1 (the ten principles, as a floor) and section 2 (the owner's standing taste, as the seed), plus both floors in design-guard section 1, accessibility and reduced motion. The method builds on top of these anyway. Without it you have the floor without the craft: plainer, and still not allowed to be inaccessible or ugly by default.
• The three owner stops stay, in the same order, at lower fidelity. Direction: two or three written directions, each with a palette and one flat SVG viewport, and the owner picks; there is no external roll, so name the category default explicitly and make sure one candidate is not it. Compositions: flat SVG, approved before code is written. Finish: a fresh subagent that never saw the build thread scores the result against the rulebook above and the story's acceptance criteria, and its table is reported as it stands, open items intact. Dropping a stop is what turns a degraded build into an unrecoverable one, because the owner never saw the choice.
• Not attempted, and said so: the derived visual worlds, the detector, the method's own review passes. Record in DESIGN.md section 3 that this surface was built on the degraded route, so a later session can offer a re-run through the full method instead of assuming one happened.

A surface built this way is finished work, not a draft. It is re-run only if the owner asks. ⚓