DESIGN.md: interview, then write the design system
Produce one file, DESIGN.md: tokens in YAML front matter, eleven ## sections of prose
explaining them. Reply in the user's language; token names and headings stay English.
Paths are relative to this skill's folder: ${CLAUDE_SKILL_DIR}, or run from that folder.
The workflow (in order)
- Establish the target.
web(default) orpower-apps(the design will become a Power Apps canvas app throughcreate-app). Ask if it is not clear. Forpower-apps, readreferences/shared/powerapps-profile.mdnow and keep every later choice inside it. - Collect what exists. Read what the user already gave: brief, logo, screenshots,
brand guide, an existing
DESIGN.md. Then ask only for what is missing, fromreferences/interview.md: product and audience, brand colours and fonts, sites they admire and why, devices, density, light or dark, accessibility needs. At most two rounds of questions. If the user says "you decide", decide and say which defaults you took. - No strong view? Offer two or three directions. Each: an invented name, one sentence, a palette (primary, surface, text, accent as hex), a type pairing with open fallbacks. Let the user pick or mix.
- Derive the tokens, in this order:
- colours: a
primary, neutrals, surfaces, text, and semantic states (success,warning,error,info), each filled colour with anon-partner; - typography: 9–15 levels, each with
fontFamily,fontSize,fontWeight,lineHeight(addletterSpacingwhere it is not zero); rounded: a radius scale;spacing: a scale on a stated base unit (4px or 8px);- components that reference those tokens: buttons with states, cards, inputs with helper and error text, badges, navigation. Every colour token is used by at least one component.
- colours: a
- Write the whole file from
assets/DESIGN.template.md: all eleven sections, in order.references/section-guide.mdsays what goes in each##and###and how long.references/format.mdis the format itself: keys, types, references, lint rules.assets/example/DESIGN.mdis a finished, lint-clean example for an invented brand; read it for tone and depth, never copy its values. - Lint with
python3 ${CLAUDE_SKILL_DIR}/scripts/design_lint.py DESIGN.md(scripts/design_lint.py; add--target power-appsfor that target). Fix every error and lint again. Report every warning with the fix you made or the reason it stands. If Node.js is available, also runnpx @google/design.md lint DESIGN.mdand report where the two disagree;references/format.md§7 lists the known differences. - Hand over the complete file (write
DESIGN.mdat the project root when there is a project folder; otherwise give the user the file), with the lint verdict and the warnings. Name the next step:mock-uiturns thisDESIGN.mdplus the screen requirements into HTML mockups.
Rules
- Tokens are normative. Prose explains them. Every hex value in the prose is the
value of a token, named beside it:
**Moss** ({colors.primary} — #2f6b3a). - Components reference tokens, never colour literals:
"{colors.primary}". Components cannot reference other components; make each variant its own component (button-primary-hover). - References name the YAML path:
{colors.primary},{typography.body-md}, and{components.button-primary}(plural, as the key is). The collection writes the singular{component.…}in prose; the linter warns on it. - Contrast. Text on every filled component meets 4.5:1 (WCAG AA). The linter measures it; a failing pair is an error, not a warning. Status is never shown by colour alone.
- The design system is the user's own. A site they admire is a source of qualities (density, restraint, contrast), not something to reproduce. Never reuse another company's name, logo, wordmark or signature palette, and never name the admired site in the file.
- Fonts. Write a typeface the user wants as a preference with an open fallback stack. Never state that a proprietary typeface is available or licensed.
- Updating an existing
DESIGN.md: keep every token name stable, even when its value changes. Mockups and screens already built on it refer to the names. Add rather than rename; list anything retired in Iteration Guide. - Under
power-apps: when the user asks for an effect the profile rules out (shadows, blur, transitions, hover on a parent, one-sided borders, a non-Segoe font), say plainly that the canvas cannot reproduce it, name the substitute, use the substitute in the tokens, and record both in## Known Gaps. Describe hover, pressed and disabled states only for buttons and icons. Never present an unverified item as confirmed.
Hand-off
references/shared/handoff.md is the contract between
the five skills: where DESIGN.md goes, identifier rules, targets. Never assume an
earlier skill ran, and end by naming mock-ui.