Design System

One answer to "which design rules apply to this UI?", for every skill and person that asks.

The baseline guides; the project's doc binds. A rule is the project's only when the project wrote it down in a tracked document. Everything this skill bundles is guidance for UI that is being written — never a gate, and never a defect by itself.

References, loaded on demand, all of which travel with this skill: references/material-3.md (the default baseline: color roles, type scale, shape, state, motion, layout), references/interface-rules.md (interaction and accessibility rules, each tagged [gate] or [review]), references/design-direction.md (the brand layer and interface writing, for what a system leaves free), references/measuring.md (auditing by measured value) and references/design-system-template.md (the shape of a project's own doc).

Rationale — why this skill exists and what it took from where: https://github.com/dayvisonassis/sdd-skills/blob/main/docs/Skill_Design_System.md. That file is not part of an installed copy; everything needed to run is in this folder.

INPUT

• mode — apply (default: UI is about to be written, or another skill dispatched this one), author or audit.
• The target: the files, surfaces or routes concerned (apply, audit); nothing for author.
• Auto-discovers: GATES.md, the project's design-system doc, and the UI library from the project's manifest.

OUTPUT

• Always, first: the resolution line — which source binds and why. One of: design system: <path> · design system: <path> (untracked — local to this machine) · baseline: Material 3 — the project declares no design system · library conventions: <library> — Material 3 does not apply .
• apply — the rules for the UI at hand, gated ones first, and the verification to run.
• author — the project's design-system doc, written from the template at a tracked path.
• audit — a findings report. No file is edited.

Step 1 — Resolve the source (every mode, before anything else)

This is the one definition. implement-feature, gate-builder and qa-preflight refer to it and do not restate it.

1. The path GATES.md names in its design-system section.
2. Otherwise a tracked doc at a conventional path: docs/design-system.md, DESIGN.md, docs/**/design*.md, docs/**/ui*.md, a .cursor/rules/*.mdc that describes UI standards, a tokens or Storybook doc.
3. Otherwise none: the bundled baseline applies, as the table below says.

"Tracked" means git ls-files lists it. A doc that lives only in an ignored or untracked folder — a skills folder, or a doc never committed — is local to this machine: use it for this run, say that it is not shared, and never let a gate point at it.

Which part of the baseline applies — when there is no doc, and for whatever a doc is silent on:

A library's conventions are read from the installed package, or its documentation for that version. With neither at hand, follow the patterns the project's code already uses, and list the library's conventions as not verified.

Precedence: the project's doc → the UI library's conventions → the bundled baseline. A conflict is the higher one's to win; two sources are never averaged. The accessibility floors sit outside this order — those of interface-rules.md, and any stricter one the project's doc states: no source overrides them, and a library default that breaks one is a defect, not a convention to follow. When the doc and the dominant pattern in the code disagree, say so — in apply, follow the doc and report the divergence; in author, ask.

What each source may be used for:

Mode apply — before writing UI

1. Resolve (Step 1) and state the resolution line.
2. Read only what the UI at hand needs: a form reads forms, states and density; a new page reads layout. Do not load every reference.
3. Gated rules first. The doc's machine-checkable section is what the project's design-system gate rejects (GATES.md says which gate). Write the UI in the accepted pattern from the start — learning a rule from a failed gate run costs a retry.
4. Then the judgement rules: hierarchy, density, spacing, and the states nobody asks for — empty, loading and failure are designed, and they must not look alike.
5. A token wherever one exists. A literal color, size, radius or duration where the system has a role for it is a divergence, even when the two values are equal today. A value the project's doc states as a number (a 40px field height) is used as that number: the doc chose it.
6. Verify per references/measuring.md: rendered, in every theme the project ships, with the numeric rules read as computed values. What could not be verified is reported by name, so the caller can log it — never as verified.
7. The doc is silent on something this UI needs → follow the baseline and report the gap (doc is silent on <x>; used <baseline rule>). Never edit the doc in this mode.

Mode author — writing the project's doc (a person asks; never dispatched)

1. Resolve. A doc already exists → ask whether to update it or replace it. Never overwrite silently.
2. Existing UI: derive from what is really there. For each candidate rule, count conforming and non-conforming occurrences and take the majority as the rule; near an even split, ask, or record the rule as advisory. Read numeric values from the rendered screen, not from class names (references/measuring.md). List every place where the code and the intended rule disagree.
3. No UI yet: use references/design-direction.md — the subject, the audience, the tone — and decide what the system leaves free: source color, typefaces, shape, density, the personality of motion. One question at a time, each with a recommended answer.
4. Fill references/design-system-template.md. Every rule lands in exactly one of two lists: machine-checkable (a tool can decide it from a file) or judgement (a person or a rendered screen decides it). Every numeric value goes in the measured-values table with its unit, the element to measure and the theme.
5. Save at a tracked path — docs/design-system.md unless the person names another. Say that gate-builder builds the design-system gate from the machine-checkable section and records the path in GATES.md.
6. Refuse your own output when: a rule sits in neither list; a value was copied from the baseline without anyone choosing it; two rules contradict each other.

Mode audit — read-only review

1. Resolve.
2. Static pass over the target files: every rule of the project's doc a file can decide, the accessibility floors a file can decide (zoom disabled, a control with no name), and the [gate] rules of references/interface-rules.md. Load interface-rules.md and measuring.md; material-3.md only when the baseline applies.
3. Rendered pass, when the app can be brought up: every numeric rule measured per references/measuring.md, in every theme, with contrast computed over the composed background.
4. Report, grouped by file or screen, one line per finding: <file>:<line> — <rule id> — <what is wrong> — measured <x>, expected <y>. Split the report in two — binding (a rule of the project's doc, from any of its sections, or an accessibility floor) and suggestions (every baseline rule) — and end with what was not measured, by name. Lead each finding with the most binding id that covers it — the doc's, then the floor's — and add the baseline id in parentheses. A value decidable from the source alone, such as the contrast of two opaque literal colors, may be reported as computed from source <x>; a value that depends on rendering is not measured.
5. Change nothing. A correction belongs to whoever asked: qa-preflight dispatches fix-runner; a person fixes or delegates. This holds when the same request also asks for the fixes: deliver the audit, with the fixes split into the mechanical ones and the ones that need a decision; making them is a separate step, taken once the person has read the report.

RULES

Always:

• Resolve first, and state the resolution line before any rule.
• Let the project's doc win over the library and the library over the baseline.
• Keep machine-checkable rules apart from judgement rules in the doc, and binding findings apart from suggestions in every report.
• Read numeric rules as computed values on the rendered screen, in every theme the project ships.
• Name what was not verified.

Never:

• Invent a project rule, or present a baseline value as if the project had chosen it.
• Use the baseline as the source of a gate, or report a baseline rule as a defect — the accessibility floors excepted.
• Conclude conformance from a class, attribute or token name being present.
• Write gate infrastructure (that is gate-builder's) or edit production code.
• Store the project's doc in a skill folder or any untracked path.
• Fetch rules from the network at run time: the references are bundled so a run is reproducible.
• Write or overwrite a doc nobody asked for.

Edge cases

The scope has no UI (a backend-only change, a library): say so and stop; there is nothing to resolve.

The only doc is untracked: use it for this run, state that it is local, and recommend committing it, or moving it to a tracked path. gate-builder will not build a gate from it.

Several candidate docs: the one GATES.md names wins. With none named, ask (author, audit); when dispatched, take the most specific one and report which.

The project ships two themes and the doc describes one: verify both anyway, and report the doc's silence as a gap.

The doc is older than the code: the dominant pattern contradicts it in several places — report the list. Which one is right is the team's decision, not this skill's.

A project on an earlier Material version: its installed library version's conventions win. Do not migrate tokens or components as a side effect of another task.

"Make it look better" where a doc exists: design-direction.md covers only what the doc leaves free. Changing the system itself is an author change, made on purpose.

Dispatched and something is ambiguous: apply the higher-precedence source, report the ambiguity, and proceed. Never pause a dispatched run to ask.