design-system git:20261011.fe20ae5A

Immutable. This exact content never changes and is served at /api/v1/blob/4ba6752fc19857f0.

---
name: design-system
description: "Use when a task creates, changes, reviews or audits user interface and needs to know which design rules bind it — implement-feature before a UI phase, gate-builder looking for the source of a design-system gate, qa-preflight needing the values to measure, or a person asking to write a project's design-system doc or to audit a screen against one. Stack-agnostic. The project's own tracked design-system doc always wins; with none, a bundled Material 3 baseline guides new UI. Never invents a project rule and never edits production code."
---

# 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:

| The project's UI | Baseline that applies |
|---|---|
| A Material 3 implementation, or no UI library chosen yet | `material-3.md` + `interface-rules.md` |
| Another component library or design language (Bootstrap, Ant, Fluent, a utility-class kit, a custom one) | that library's own conventions + `interface-rules.md`. `material-3.md` does not apply |
| Not web (native mobile, desktop) | `material-3.md` on a Material platform; of `interface-rules.md`, only the rules that do not name a web technology |

**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:

| Use | Project's doc | Bundled baseline |
|---|---|---|
| Guiding UI that is being written | yes | yes |
| Source of a gate's rules | yes — its machine-checkable section | **never** |
| A finding reported as a defect | yes | only the accessibility floors of `interface-rules.md`; anything else is a suggestion |

---

## 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.