Design System Documentation Audit & Update
Audit design docs under _docs/_build/design/ (and the _docs/design/ symlink) against the live codebase so documentation stays the single source of truth for how the design chain is implemented in this repo.
Ground truth file: _docs/_build/design/DESIGN_SYSTEM_SSOT.md — update this first when reconciling; then align DESIGN_CHAIN.md, DESIGN_CHARTER.md, and layers/*.md as needed.
Target: $ARGUMENTS
If no target is provided, audit the full _docs/_build/design/ tree and src/app/globals.css, tailwind.config.ts, src/components/ui/, and src/components/ (excluding _archive/).
Design chain (reference)
Bottom-up: D0 charter → D1 tokens (globals.css, tailwind.config.ts) → D2 primitives (src/components/ui/) → D3 domain components → D4 patterns/layouts → D5 pages → D6 motion.
Design values flow downstream only (see .cursor/rules/react-nextjs-best-practices.mdc design chain).
Before starting
- Read
DESIGN_SYSTEM_SSOT.md, DESIGN_CHAIN.md, DESIGN_CHARTER.md, and _docs/_build/design/README.md.
- Read
src/app/globals.css (including @theme, :root, .dark).
- Read
tailwind.config.ts (theme.extend and any relevant keys).
- List
src/components/ui/*.tsx and top-level folders under src/components/ (excluding ui, _archive).
Ground truth collection
From the codebase (not from prose docs alone):
D1 — Tokens
- Note primary/surface/semantic CSS variables in
:root and .dark.
- Note
@theme → --color-* mappings in globals.css.
- Note font stacks (
--font-heading, --font-body, next/font usage in src/app/layout.tsx if relevant).
D2 — Primitives
- File list under
src/components/ui/.
- Confirm policy: no styling edits in
ui/ for product fixes.
D3 — Domain components
- Top-level feature folders under
src/components/.
- Any new high-traffic patterns (hero, nav, chat shell) and their paths.
D4–D5
- Key layout files:
src/app/(public)/layout.tsx, shared headers/footers, layout client wrappers.
- Sample a few
page.tsx files for composition patterns.
D6
- Keyframes and animation utilities in
tailwind.config.ts and globals.css.
Tenant
- Confirm
tenant.config.ts has no hardcoded colors/fonts for UI chrome.
Audit checklist
Compare docs against ground truth. Flag and fix:
- Wrong palette or fonts — e.g. charter says Montserrat/amethyst but code uses Lora/
#bd0036.
- Wrong paths —
_docs/design/ vs _docs/_build/design/ (both valid if symlink exists).
- Stale layer docs —
layers/D1-tokens.md etc. contradict globals.css.
- Missing primitives — new
ui/ components not mentioned.
- Broken links — e.g.
PATHWAYS_DESIGN_ALIGNMENT.md only under _public/proposals/.
- Tailwind version — v4
@import "tailwindcss" vs legacy @tailwind directives in examples.
Update rules
- Refresh
DESIGN_SYSTEM_SSOT.md with accurate tables and “last reviewed” date.
- Edit
DESIGN_CHAIN.md / DESIGN_CHARTER.md to match implementation or add explicit “legacy narrative” notes if product intentionally keeps aspirational copy (prefer matching code).
- Keep README index links correct; fix relative links to
_public/ proposals when needed.
- Do not move design research into
_build/ — proposals stay in _docs/_public/ per CONSTITUTION.md.
After updating
- Grep for
_docs/design and spot-check that symlink _docs/design → _docs/_build/design still exists.
- Ensure no doc claims a token name that does not exist in
globals.css.
- Optional:
pnpm lint on touched TSX if examples were updated.
1---2name: docs-design-system3description: Audit and update design documentation in _docs/_build/design/ to match the actual UI stack (tokens, Tailwind, shadcn primitives, domain components, pages). Keeps DESIGN_SYSTEM_SSOT.md and the design chain aligned with src/.4user-invocable: true5allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent6metadata:7 source: https://skillmd.com/skills/joshuashepherd/docs-design-system8---910# Design System Documentation Audit & Update1112Audit design docs under `_docs/_build/design/` (and the `_docs/design/` symlink) against the **live codebase** so documentation stays the single source of truth for **how the design chain is implemented** in this repo.1314**Ground truth file:** `_docs/_build/design/DESIGN_SYSTEM_SSOT.md` — update this first when reconciling; then align `DESIGN_CHAIN.md`, `DESIGN_CHARTER.md`, and `layers/*.md` as needed.1516Target: $ARGUMENTS1718If no target is provided, audit the full `_docs/_build/design/` tree and `src/app/globals.css`, `tailwind.config.ts`, `src/components/ui/`, and `src/components/` (excluding `_archive/`).1920## Design chain (reference)2122Bottom-up: **D0** charter → **D1** tokens (`globals.css`, `tailwind.config.ts`) → **D2** primitives (`src/components/ui/`) → **D3** domain components → **D4** patterns/layouts → **D5** pages → **D6** motion.2324Design values flow **downstream** only (see `.cursor/rules/react-nextjs-best-practices.mdc` design chain).2526## Before starting27281. Read `DESIGN_SYSTEM_SSOT.md`, `DESIGN_CHAIN.md`, `DESIGN_CHARTER.md`, and `_docs/_build/design/README.md`.292. Read `src/app/globals.css` (including `@theme`, `:root`, `.dark`).303. Read `tailwind.config.ts` (`theme.extend` and any relevant keys).314. List `src/components/ui/*.tsx` and top-level folders under `src/components/` (excluding `ui`, `_archive`).3233## Ground truth collection3435From the **codebase** (not from prose docs alone):3637### D1 — Tokens3839- Note primary/surface/semantic CSS variables in `:root` and `.dark`.40- Note `@theme` → `--color-*` mappings in `globals.css`.41- Note font stacks (`--font-heading`, `--font-body`, `next/font` usage in `src/app/layout.tsx` if relevant).4243### D2 — Primitives4445- File list under `src/components/ui/`.46- Confirm policy: no styling edits in `ui/` for product fixes.4748### D3 — Domain components4950- Top-level feature folders under `src/components/`.51- Any new high-traffic patterns (hero, nav, chat shell) and their paths.5253### D4–D55455- Key layout files: `src/app/(public)/layout.tsx`, shared headers/footers, layout client wrappers.56- Sample a few `page.tsx` files for composition patterns.5758### D65960- Keyframes and animation utilities in `tailwind.config.ts` and `globals.css`.6162### Tenant6364- Confirm `tenant.config.ts` has no hardcoded colors/fonts for UI chrome.6566## Audit checklist6768Compare docs against ground truth. Flag and fix:69701. **Wrong palette or fonts** — e.g. charter says Montserrat/amethyst but code uses Lora/`#bd0036`.712. **Wrong paths** — `_docs/design/` vs `_docs/_build/design/` (both valid if symlink exists).723. **Stale layer docs** — `layers/D1-tokens.md` etc. contradict `globals.css`.734. **Missing primitives** — new `ui/` components not mentioned.745. **Broken links** — e.g. `PATHWAYS_DESIGN_ALIGNMENT.md` only under `_public/proposals/`.756. **Tailwind version** — v4 `@import "tailwindcss"` vs legacy `@tailwind` directives in examples.7677## Update rules7879- Refresh `DESIGN_SYSTEM_SSOT.md` with accurate tables and “last reviewed” date.80- Edit `DESIGN_CHAIN.md` / `DESIGN_CHARTER.md` to match implementation **or** add explicit “legacy narrative” notes if product intentionally keeps aspirational copy (prefer matching code).81- Keep README index links correct; fix relative links to `_public/` proposals when needed.82- Do not move design research into `_build/` — proposals stay in `_docs/_public/` per `CONSTITUTION.md`.8384## After updating85861. Grep for `_docs/design` and spot-check that symlink `_docs/design` → `_docs/_build/design` still exists.872. Ensure no doc claims a token name that does not exist in `globals.css`.883. Optional: `pnpm lint` on touched TSX if examples were updated.