| name | sync-design |
| description | Use when the implementation may have drifted from docs/DESIGN.md. Audits src/styles/ and src/components/ section-by-section against the design document, proposes patches, and applies them on confirmation. |
sync-design
Bring the website's CSS, tokens, and components back in sync with
docs/DESIGN.md, the source of truth for the visual design.
This skill is drift-reactive (run when the doc or the styling
moves) and interactive (it never auto-applies invasive changes —
it audits, proposes, and applies on confirmation).
Tracking mechanism
The sibling file .last-updated holds the git commit hash of the
last successful run. An empty file means "never run" — use the
initial commit as the baseline.
Discovery process
Determine what has changed since the baseline:
BASE=$(cat .agent/skills/sync-design/.last-updated)
HEAD=$(git rev-parse HEAD)
git log --oneline "${BASE:-$(git rev-list --max-parents=0 HEAD)}..$HEAD" -- \
docs/DESIGN.md src/styles/ src/components/
git diff --name-only "${BASE:-$(git rev-list --max-parents=0 HEAD)}..$HEAD" -- \
docs/DESIGN.md src/styles/ src/components/
Then read docs/DESIGN.md end-to-end. The Implementation appendix
(§15) is the single mapping source — token map, component map,
pattern map, print map. Every audit in this skill is driven from
those tables.
Mapping: DESIGN.md section → audit target
The doc owns the rules; these files express them. When a row's doc
section moves, audit the corresponding target. When a target moves
without a doc change, that is the drift this skill is for.
| DESIGN.md section | Audit target |
|---|
| §3 Colour system | src/styles/tokens.css; grep for raw hex / rgba in every other CSS file (any literal outside tokens.css is a drift signal). |
| §4 Typography | src/styles/tokens.css (font stacks); per-component CSS for font-size, weight, line-height, letter-spacing. |
| §5 Spacing and layout | Every CSS file; values must be members of the named scale (4/8/12/16/20/24/32/48). Container widths in tokens.css and layout.css. |
| §6 Surfaces and elevation | src/styles/{tokens.css,base.css,modals.css,timeline-vis.css}; backdrop-filter recipes per the table in §6.2. |
| §7 Iconography | Inline SVG in src/components/; sizes must be members of the 4-step icon scale. |
| §8 Motion | Every CSS file; transition durations must be members of the 4-step timing ladder. prefers-reduced-motion block in src/styles/sky.css. |
| §9 Components | The Component map in §15.2. Each row → one or more files to audit against the component contract. |
| §10 Patterns | The Pattern map in §15.3. |
| §11 Voice and microcopy | src/data/cv/*.json; src/data/cv.json (handled by update-cv — surface drift here only). |
| §12 Accessibility | Per-component CSS (focus rings); component TSX (aria-label, role, tab order, semantic elements). |
| §13 Print variant | src/data/cv/print.json, schemas/print.schema.json, src/styles/print.css, src/components/PrintView.tsx, scripts/generate-print.mjs. |
| §14 Process | Not auditable — informational. |
| §15 Implementation appendix | The mapping itself — verify that every CSS variable named in §15.1 exists in tokens.css, every component file in §15.2 exists, etc. |
Update checklist
Walk the codebase against the doc in this order. Each item produces
zero or more drift findings. Group findings by DESIGN.md section in
the report.
Tokens (§3, §4, §15.1)
Typography (§4)
Spacing (§5)
Surfaces (§6)
Iconography (§7)
Motion (§8)
Components (§9, §15.2)
Patterns (§10, §15.3)
Print (§13, §15.4)
Mapping appendix (§15)
Behaviour: audit, propose, apply with confirmation
This skill never auto-applies invasive changes. The flow is:
- Audit. Walk the checklist above end-to-end, reading
docs/DESIGN.md and the audit targets. Collect every drift
finding with its file, line, and a one-line diagnosis.
- Report. Print findings grouped by DESIGN.md section. Format:
[§3.5] src/styles/modals.css:429 — raw hex #c62828 used; should be tokenised as Halt. Order by section, then file.
- Propose. For each finding, draft a concrete patch (file +
suggested edit). Group related patches into batches by section.
Show the batch as a unified diff before applying anything.
- Apply with confirmation. Wait for the user to approve each
batch ("apply tokens batch", "skip motion batch", "revise"). Do
not apply more than one batch without explicit approval.
- Re-audit. After applying any batch, re-run the checklist
over the changed files and report residual drift.
- Stop on judgment calls. Some drift is intentional (a deferred
token, a component variant in flight, a known footnote in §15.1).
Surface these and ask before changing anything.
Verification
After every applied batch, and once at the end of the run:
make fmt — format any touched CSS / TSX.make fmt-check — confirm formatting is clean.make lint — TypeScript and ESLint pass.make build — production build succeeds.- Re-read each touched file end-to-end against its DESIGN.md
section.
All four commands must pass before the run is considered successful.
On success, write the new HEAD hash to
.agent/skills/sync-design/.last-updated.
Skill self-improvement
If the audit surfaces a drift class that the checklist or mapping
table does not yet cover (e.g. a new component family, a new
animation timing, a new surface tier), append a row to the mapping
table or a bullet to the checklist and commit the skill update
alongside the design fixes. The skill is its own long-lived memory;
without this step it rots the same way the doc would.
When tokens move from "footnote exception" to "first-class token"
(e.g. when Pulse or Halt finally become real CSS variables),
delete the footnote in §15.1 of docs/DESIGN.md in the same
patch — leaving stale exceptions is itself drift.
