Turn your design system into a reference-first Claude skill

Build a Claude skill that applies the {{brand}} design system to all frontend work: pages, components, dashboards, forms and artifacts. Make it reference-first: a short SKILL.md that Claude reads every time, plus reference files it loads only when the task needs them.

Sources (the only place brand values may come from):
<brand_notes>
{{brand_notes}}
</brand_notes>
<tokens>
{{tokens_source}}
</tokens>
Target stack: {{stack}}

Write these files.

1. SKILL.md: orientation, under 200 lines.
   - Frontmatter: `name` (the brand slug plus "-design") and a `description` under 1024 characters: what it applies, the stack, trigger phrases people actually say ("our design system", "{{brand}} style", "on-brand", "use our colours", "match the app"), and the sentence "Always read references/tokens.md before writing any CSS."
   - Identity: the aesthetic in one line, 4 to 6 tone words, and a "What this is NOT" list naming 3 to 5 generic looks Claude would otherwise drift to that are wrong for this brand.
   - Core values table: primary and surface colours, one font per role, default mode, base system.
   - File map, then a "When to load which file" table (task → file). tokens.md loads for every task. For component families with no file yet, say so and point to the principles.
   - Mandatory principles, each a rule plus its exact token names, without their values (tokens.md holds those): colour roles, not values (text on a fill uses that fill's on- pair); tonal elevation (move up the surface-container ladder first, the shadow only supports it; give the surface and shadow for card, hovered card, menu and dialog); type scale only; shape scale only; spacing and size tokens only; state layers (a currentColor overlay at fixed hover, focus, pressed and dragged opacities); motion tokens only, with reduced motion; one main action and one accent per view; dark mode with no component-level overrides.
   - Quick decision table, 20 to 30 rows of need → token, with no values: page background, alternate section, card, dialog, main action, secondary action, selected item, body text, muted text, divider, input border, status colours, heading and body steps, big figures, radius per component, card padding.
   - Pre-output checklist: yes/no checks Claude runs on its own output before replying. At least: a standalone output (an artifact or a single HTML file) includes the font link, :root block, dark block and base styles; no literal colour, font or length outside tokens.md; every text style is a type step plus its tracking; raised surfaces are a surface-container step plus a shadow; every control has hover, focus-visible, pressed and disabled states; transitions use motion tokens; text sits on its on- pair and muted text is never opacity; one filled button per group; the layout works at 360px wide with no horizontal scroll; icon-only buttons have aria-label, decorative SVGs have aria-hidden, and no state is shown by colour alone.

2. references/tokens.md: the single source of truth.
   - The font loading snippet.
   - One :root block, ready to paste: every colour role (primary, secondary, tertiary, error, plus success and warning if the brand uses them, each with on-, -container and on-…-container), the surface-container ladder from lowest to highest, outline and outline-variant, inverse roles, scrim; the type scale; elevation shadows; shape; spacing; component sizes; motion durations and easings; state-layer opacities; layout widths, including a measure for prose.
   - @media overrides in the same file: the compact window shrinks the gutter and display sizes, and reduced motion zeroes the durations.
   - A dark block that overrides every colour role and every shadow, and how to switch it: an attribute on <html>, set from the saved choice or the OS preference before first paint.
   - Base styles (body, links, focus ring, selection), the state-layer CSS, the breakpoints, short usage tables for roles, type steps, elevation levels, shape, spacing and motion, then a Do / Don't list. Name in it the defaults Claude drifts to that this brand rejects, such as Inter, Roboto or Arial and pure black or white body text.

3. references/components-core.md: buttons, cards, chips, badges, text fields, lists, dividers, top app bar, and page structure (container, section, card grid, plus a dashboard shell if the team builds dashboards). Add one components-<family>.md for each other family the brand notes list. For each component: CSS for every variant and state (hover, focus-visible, pressed, disabled, selected, error), a short HTML usage snippet, and an emphasis table wherever variants differ in emphasis (buttons, cards, chips, badges). Each file starts with "Load tokens.md first."

Rules:
- Name variables --md-sys-<group>-<name>: --md-sys-color-primary, --md-sys-typescale-body-large (a font shorthand) plus --md-sys-typescale-body-large-tracking, --md-sys-shape-corner-small, --md-sys-spacing-4, --md-sys-motion-duration-short, --md-sys-state-hover-opacity. Components set type with font, then letter-spacing, then anything the font shorthand resets, such as tabular-nums.
- Use Material 3 role names (primary, on-primary, primary-container, surface-container-high, outline-variant…) unless the source already names its tokens. In that case keep the team's names and map each one to its role in a table.
- Never invent a brand value. When the source lacks one (a container tone, a dark value, a shadow), derive it from the M3 tonal palette of the nearest brand colour (light: container tone 90, on-container tone 10 to 30; dark: role tone 80, on-role 20, container 30, on-container 90; surfaces from a neutral palette at the hue of the brand's surface colour, or of the primary if none is given). If you can run code, use @material/material-color-utilities. Mark each derived value /* derived */ in tokens.md (one comment may cover a block that is all derived), and list every derived value at the end of your reply.
- Check contrast for every on-X / X pair in both themes: at least 4.5:1 for text, 3:1 for outlines that carry meaning. Compute each ratio with the WCAG 2.x relative-luminance formula (run code if you can); don't estimate. Adjust derived values until they pass. If a brand value fails, keep it and flag it.
- If the notes and the tokens disagree (the notes say one accent, the tokens hold two), don't settle it silently: say in SKILL.md what each colour is for and list the conflict as an open question.
- Literal colours, font names and lengths appear only in tokens.md. Component CSS uses var() only; 1px and 2px borders and focus rings are the one exception. Translucency is color-mix() on a token, never an rgba() or #rrggbbaa literal: those break in dark mode.
- Custom properties don't work in @media conditions, so write breakpoints as literals and list them once in tokens.md.
- Fit {{stack}}: say where the :root block goes and how components consume the tokens there (plain classes, CSS modules, a Tailwind theme pointing at the same variables…).
- The decision table, the principles and the component code must give the same answer: one radius for buttons, one surface for cards. When you finish, re-read them against each other, check that every component has every state that applies to it, and fix every gap or mismatch.
- No padding: no component family the team doesn't use, no generic design advice the tokens don't enforce.

Return each file in full under its path, then the derived values, then a contrast table (pair, theme, ratio, pass or fail), then any open questions for the team.

Show all 44 lines