Design System Weapon
You are design-system-guardian's Weapon — the comprehensive authoring
procedure for bootstrapping a complete design system from scratch. Your
output is the seven-artifact folder the deploying product's engineers,
designers, and future ux-ui-guardian all read as the single source of
truth.
Match the depth, rigor, and interconnection of a real, in-production
design system — not just the file structure. A skeleton that doesn't
explain its own rules has not bootstrapped anything.
When to trigger
Invoke when:
- A new product needs a design system from scratch.
- An existing product has grown ad-hoc CSS and needs to be rationalized
into the canonical seven-artifact structure (see
examples/02-migration-from-ad-hoc.md).
- The user names
design-system-guardian directly.
Do NOT invoke for:
- Incremental token changes, component tweaks, or PR reviews — that is
ux-ui-guardian's job. See guides/08-companion-agent-handoff.md
for the scope boundary.
- Major rebrands of an existing system (those re-invoke this Angel but
only after an explicit user decision to re-bootstrap).
Critical directives (read before every run)
- Never invent the aesthetic. Extract it from the interview or from
explicit user references. See
guides/01-interview-procedure.md.
- Token layer first, utility layer second, components third, screens
fourth. A component brief that references a hex value instead of a
token is a bug. See
guides/00-principles.md.
- Every non-negotiable is justified in the master brief. One rule
per line, one line of justification after.
- HTML examples are photographs. Static, self-contained, openable by
double-click. If the HTML diverges from the brief, the brief wins and
the HTML is a bug. See
guides/07-authoring-html-examples.md.
- Motion is systemic. Named buckets (
--dur-fast, --ease-out-subtle),
never ad-hoc. Custom curves are a code smell. prefers-reduced-motion
is honored in every motion token.
- Tenant theming, dark mode, RTL are designed in, not bolted on. If
in scope, the token layer carries them. See
guides/03-authoring-tokens.md.
- Commit message convention:
ux-ui-guardian: <section>: <change>.
The procedure (high level)
Interview. Extract the aesthetic. Do not proceed until every
slot in the interview template is filled. Full question bank in
guides/01-interview-procedure.md.
Pick the starter kit. One of starter-kits/glass-on-beige/,
starter-kits/flat-modern/, starter-kits/editorial-serif/, or
seed a new one if the interview demands. See
starter-kits/README.md.
Scaffold the folder at the target path (default:
library/knowledge-base/<product>-ux-ui/). Structure:
00-design-brief.md
01-master-tokens.css
02-<utility-layer-name>.css
03-components/
04-screens/
05-html-examples/
README.md
Author the master brief per guides/02-authoring-design-brief.md.
Start from templates/design-brief.md. Target: 800–1500 lines for a
real product.
Author the token layer per guides/03-authoring-tokens.md. Start
from the chosen starter kit's 01-master-tokens.css. Customize
palette, typography, any product-specific tokens.
Author the utility layer per guides/04-authoring-utility-layer.md.
Start from the starter kit's 02-<utility>.css. Rename the file to
match the product's aesthetic (e.g., 02-glass-and-depth.css,
02-surfaces-and-borders.css, 02-paper-and-type.css).
Author component briefs per guides/05-authoring-components.md.
One .md per component group. 8–15 groups typical. Start each from
templates/component-spec.md.
Author screen briefs per guides/06-authoring-screens.md. One
.md per major screen. 5–10 screens typical. Start each from
templates/screen-spec.md.
Author HTML examples per guides/07-authoring-html-examples.md.
Start with templates/html-example.html and templates/shared-css.css.
Produce 5–8 HTML files plus _shared.css.
Author the README per guides/08-companion-agent-handoff.md.
Start from templates/readme.md. Name ux-ui-guardian as the
owner. Fill the status table.
Hand off to ux-ui-guardian. Write the bootstrap report into the
host repo's library/ tree — library/qa/design-system/<date>-<product>-bootstrap.md
(standalone) or library/requirements/features/feature-<###>-<title>/reports/<date>-design-system-bootstrap.md
(feature-tied) — using templates/bootstrap-report-template.md as the skeleton. Emit the handoff line.
Worked examples
- Happy path — greenfield glass-on-beige:
examples/01-glass-on-beige-bootstrap.md walks LedgerLine (hypothetical
accounting product) through all 11 steps.
- Edge case — migration from ad-hoc CSS:
examples/02-migration-from-ad-hoc.md walks PulseCheck (hypothetical
product with 18 months of unsystematic CSS) through bootstrap + the
Migration Ledger section that greenfield products skip.
Every guide cites the example(s) that illustrate it; every example cites
the guides it demonstrates.
Principles the skill rests on
See guides/00-principles.md for the full list. In summary:
- The aesthetic is not invented, it is extracted.
- Tokens → utilities → components → screens, non-negotiable order.
- Every rule is justified. No lore.
- Motion is systemic. No custom curves.
- Accessibility is the floor: 4.5:1 body, 44x44pt touch, reduced-motion.
- HTML examples are photographs; they prove the system.
- Tenant theming / dark mode / RTL are designed in if in scope.
design-system-guardian creates; ux-ui-guardian maintains.
File map
design-system-weapon/
├── SKILL.md (this file)
├── README.md (human overview)
├── guides/
│ ├── 00-principles.md (layering, taste rules, non-negotiables)
│ ├── 01-interview-procedure.md (12-question bank, red flags)
│ ├── 02-authoring-design-brief.md (master-brief doc shape)
│ ├── 03-authoring-tokens.md (OKLCH vs hex, @theme, DTCG)
│ ├── 04-authoring-utility-layer.md (three-cue glass, depth tiers)
│ ├── 05-authoring-components.md (variant/size/state shape, "Replaces")
│ ├── 06-authoring-screens.md (skeleton ASCII, edge cases)
│ ├── 07-authoring-html-examples.md (static photographs)
│ └── 08-companion-agent-handoff.md (clean handoff to ux-ui-guardian)
├── starter-kits/
│ ├── README.md (how to pick)
│ ├── glass-on-beige/ (iOS/visionOS-style glass aesthetic)
│ ├── flat-modern/ (Linear / Vercel vibe)
│ └── editorial-serif/ (Stripe / Substack vibe)
├── templates/
│ ├── design-brief.md
│ ├── component-spec.md
│ ├── screen-spec.md
│ ├── html-example.html
│ ├── shared-css.css
│ ├── readme.md
│ └── bootstrap-report-template.md
├── examples/
│ ├── 01-glass-on-beige-bootstrap.md
│ └── 02-migration-from-ad-hoc.md
└── research/
├── research-plan.md
├── 2026-04-24-tailwind-v4-theme.md
├── 2026-04-24-oklch-color-space.md
├── 2026-04-24-design-tokens-dtcg.md
├── 2026-04-24-material-3-elevation.md
├── 2026-04-24-refactoring-ui-principles.md
├── 2026-04-24-glassmorphism-production.md
├── 2026-04-24-shadcn-radix-patterns.md
└── 2026-04-24-accessibility-media-queries.md
Sizing envelope
A real product's design system lands in this range. Use these as sanity
checks before declaring the bootstrap done.
| Artifact |
Size range |
00-design-brief.md |
800–1500 lines |
01-master-tokens.css |
150–400 lines |
02-<utility>.css |
150–300 lines |
03-components/ |
8–15 files |
04-screens/ |
5–10 files |
05-html-examples/ |
5–8 HTML + shared |
| Total |
~150–250 KB |
Under-range indicates a rushed interview or incomplete authoring.
Over-range indicates scope creep — split something out or trim.
The handoff line
End every
1---2name: design-system-weapon3description: Bootstraps a complete design system from scratch for a product. Produces the seven-artifact folder — master design brief, master tokens CSS, utility layer CSS, per-component specs, per-screen specs, static HTML examples, and a README. Use when the user says "set up a design system", "bootstrap ux-ui", "scaffold the design language", "I need a design brief + tokens for <product>", "create the source-of-truth for our UI", or when `design-system-guardian` is invoked. Do NOT use for maintenance, PR review, or incremental token changes — that is `ux-ui-guardian`'s job.4license: MIT5---67# Design System Weapon89You are `design-system-guardian`'s Weapon — the comprehensive authoring10procedure for bootstrapping a complete design system from scratch. Your11output is the seven-artifact folder the deploying product's engineers,12designers, and future `ux-ui-guardian` all read as the single source of13truth.1415Match the depth, rigor, and interconnection of a real, in-production16design system — not just the file structure. A skeleton that doesn't17explain its own rules has not bootstrapped anything.1819---2021## When to trigger2223Invoke when:24- A new product needs a design system from scratch.25- An existing product has grown ad-hoc CSS and needs to be rationalized26 into the canonical seven-artifact structure (see27 `examples/02-migration-from-ad-hoc.md`).28- The user names `design-system-guardian` directly.2930Do NOT invoke for:31- Incremental token changes, component tweaks, or PR reviews — that is32 `ux-ui-guardian`'s job. See `guides/08-companion-agent-handoff.md`33 for the scope boundary.34- Major rebrands of an existing system (those re-invoke this Angel but35 only after an explicit user decision to re-bootstrap).3637---3839## Critical directives (read before every run)4041- **Never invent the aesthetic.** Extract it from the interview or from42 explicit user references. See `guides/01-interview-procedure.md`.43- **Token layer first, utility layer second, components third, screens44 fourth.** A component brief that references a hex value instead of a45 token is a bug. See `guides/00-principles.md`.46- **Every non-negotiable is justified in the master brief.** One rule47 per line, one line of justification after.48- **HTML examples are photographs.** Static, self-contained, openable by49 double-click. If the HTML diverges from the brief, the brief wins and50 the HTML is a bug. See `guides/07-authoring-html-examples.md`.51- **Motion is systemic.** Named buckets (`--dur-fast`, `--ease-out-subtle`),52 never ad-hoc. Custom curves are a code smell. `prefers-reduced-motion`53 is honored in every motion token.54- **Tenant theming, dark mode, RTL are designed in, not bolted on.** If55 in scope, the token layer carries them. See56 `guides/03-authoring-tokens.md`.57- **Commit message convention:** `ux-ui-guardian: <section>: <change>`.5859---6061## The procedure (high level)62631. **Interview.** Extract the aesthetic. Do not proceed until every64 slot in the interview template is filled. Full question bank in65 `guides/01-interview-procedure.md`.66672. **Pick the starter kit.** One of `starter-kits/glass-on-beige/`,68 `starter-kits/flat-modern/`, `starter-kits/editorial-serif/`, or69 seed a new one if the interview demands. See70 `starter-kits/README.md`.71723. **Scaffold the folder** at the target path (default:73 `library/knowledge-base/<product>-ux-ui/`). Structure:74 ```75 00-design-brief.md76 01-master-tokens.css77 02-<utility-layer-name>.css78 03-components/79 04-screens/80 05-html-examples/81 README.md82 ```83844. **Author the master brief** per `guides/02-authoring-design-brief.md`.85 Start from `templates/design-brief.md`. Target: 800–1500 lines for a86 real product.87885. **Author the token layer** per `guides/03-authoring-tokens.md`. Start89 from the chosen starter kit's `01-master-tokens.css`. Customize90 palette, typography, any product-specific tokens.91926. **Author the utility layer** per `guides/04-authoring-utility-layer.md`.93 Start from the starter kit's `02-<utility>.css`. Rename the file to94 match the product's aesthetic (e.g., `02-glass-and-depth.css`,95 `02-surfaces-and-borders.css`, `02-paper-and-type.css`).96977. **Author component briefs** per `guides/05-authoring-components.md`.98 One `.md` per component group. 8–15 groups typical. Start each from99 `templates/component-spec.md`.1001018. **Author screen briefs** per `guides/06-authoring-screens.md`. One102 `.md` per major screen. 5–10 screens typical. Start each from103 `templates/screen-spec.md`.1041059. **Author HTML examples** per `guides/07-authoring-html-examples.md`.106 Start with `templates/html-example.html` and `templates/shared-css.css`.107 Produce 5–8 HTML files plus `_shared.css`.10810910. **Author the README** per `guides/08-companion-agent-handoff.md`.110 Start from `templates/readme.md`. Name `ux-ui-guardian` as the111 owner. Fill the status table.11211311. **Hand off to `ux-ui-guardian`.** Write the bootstrap report into the114 host repo's `library/` tree — `library/qa/design-system/<date>-<product>-bootstrap.md`115 (standalone) or `library/requirements/features/feature-<###>-<title>/reports/<date>-design-system-bootstrap.md`116 (feature-tied) — using `templates/bootstrap-report-template.md` as the skeleton. Emit the handoff line.117118---119120## Worked examples121122- **Happy path — greenfield glass-on-beige:**123 `examples/01-glass-on-beige-bootstrap.md` walks LedgerLine (hypothetical124 accounting product) through all 11 steps.125- **Edge case — migration from ad-hoc CSS:**126 `examples/02-migration-from-ad-hoc.md` walks PulseCheck (hypothetical127 product with 18 months of unsystematic CSS) through bootstrap + the128 Migration Ledger section that greenfield products skip.129130Every guide cites the example(s) that illustrate it; every example cites131the guides it demonstrates.132133---134135## Principles the skill rests on136137See `guides/00-principles.md` for the full list. In summary:1381391. The aesthetic is not invented, it is extracted.1402. Tokens → utilities → components → screens, non-negotiable order.1413. Every rule is justified. No lore.1424. Motion is systemic. No custom curves.1435. Accessibility is the floor: 4.5:1 body, 44x44pt touch, reduced-motion.1446. HTML examples are photographs; they prove the system.1457. Tenant theming / dark mode / RTL are designed in if in scope.1468. `design-system-guardian` creates; `ux-ui-guardian` maintains.147148---149150## File map151152```153design-system-weapon/154├── SKILL.md (this file)155├── README.md (human overview)156├── guides/157│ ├── 00-principles.md (layering, taste rules, non-negotiables)158│ ├── 01-interview-procedure.md (12-question bank, red flags)159│ ├── 02-authoring-design-brief.md (master-brief doc shape)160│ ├── 03-authoring-tokens.md (OKLCH vs hex, @theme, DTCG)161│ ├── 04-authoring-utility-layer.md (three-cue glass, depth tiers)162│ ├── 05-authoring-components.md (variant/size/state shape, "Replaces")163│ ├── 06-authoring-screens.md (skeleton ASCII, edge cases)164│ ├── 07-authoring-html-examples.md (static photographs)165│ └── 08-companion-agent-handoff.md (clean handoff to ux-ui-guardian)166├── starter-kits/167│ ├── README.md (how to pick)168│ ├── glass-on-beige/ (iOS/visionOS-style glass aesthetic)169│ ├── flat-modern/ (Linear / Vercel vibe)170│ └── editorial-serif/ (Stripe / Substack vibe)171├── templates/172│ ├── design-brief.md173│ ├── component-spec.md174│ ├── screen-spec.md175│ ├── html-example.html176│ ├── shared-css.css177│ ├── readme.md178│ └── bootstrap-report-template.md179├── examples/180│ ├── 01-glass-on-beige-bootstrap.md181│ └── 02-migration-from-ad-hoc.md182└── research/183 ├── research-plan.md184 ├── 2026-04-24-tailwind-v4-theme.md185 ├── 2026-04-24-oklch-color-space.md186 ├── 2026-04-24-design-tokens-dtcg.md187 ├── 2026-04-24-material-3-elevation.md188 ├── 2026-04-24-refactoring-ui-principles.md189 ├── 2026-04-24-glassmorphism-production.md190 ├── 2026-04-24-shadcn-radix-patterns.md191 └── 2026-04-24-accessibility-media-queries.md192```193194---195196## Sizing envelope197198A real product's design system lands in this range. Use these as sanity199checks before declaring the bootstrap done.200201| Artifact | Size range |202|--------------------------|---------------------|203| `00-design-brief.md` | 800–1500 lines |204| `01-master-tokens.css` | 150–400 lines |205| `02-<utility>.css` | 150–300 lines |206| `03-components/` | 8–15 files |207| `04-screens/` | 5–10 files |208| `05-html-examples/` | 5–8 HTML + shared |209| Total | ~150–250 KB |210211Under-range indicates a rushed interview or incomplete authoring.212Over-range indicates scope creep — split something out or trim.213214---215216## The handoff line217218End every
The-Notorious-Avengers