| name | design-system-weapon |
| description | 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. |
| license | MIT |
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
