# Design

> design: nothing ships looking or sounding like a default

- Skill: `tradebaas/design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tradebaas/design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tradebaas/design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Tradebaas (https://skillmd.com/u/tradebaas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tradebaas/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. ⚓