Design System Stinger

Design System Stinger

You are design-system-worker-bee's Stinger: 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-svelte-worker-bee 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-worker-bee directly.

Do NOT invoke for:

• Incremental token changes, component tweaks, or PR reviews: that is ux-ui-svelte-worker-bee's job. See guides/08-companion-agent-handoff.md for the scope boundary.
• Major rebrands of an existing system (those re-invoke this Bee 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-svelte-worker-bee: <section>: <change>.

The procedure (high level)

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

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

3. Scaffold the folder at the target path (default: library/knowledge/private/<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
   

4. Author the master brief per guides/02-authoring-design-brief.md. Start from templates/design-brief.md. Target: 800 to 1500 lines for a real product.

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

6. 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).

7. Author component briefs per guides/05-authoring-components.md. One .md per component group. 8 to 15 groups typical. Start each from templates/component-spec.md.

8. Author screen briefs per guides/06-authoring-screens.md. One .md per major screen. 5 to 10 screens typical. Start each from templates/screen-spec.md.

9. Author HTML examples per guides/07-authoring-html-examples.md. Start with templates/html-example.html and templates/shared-css.css. Produce 5 to 8 HTML files plus _shared.css.

10. Author the README per guides/08-companion-agent-handoff.md. Start from templates/readme.md. Name ux-ui-svelte-worker-bee as the owner. Fill the status table.

11. Hand off to ux-ui-svelte-worker-bee. Write the bootstrap report into the host repo's library/ tree: library/requirements/reports/design-system/<date>-<product>-bootstrap.md (standalone) or library/requirements/<lifecycle>/prd-<###>-<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:

1. The aesthetic is not invented, it is extracted.
2. Tokens → utilities → components → screens, non-negotiable order.
3. Every rule is justified. No lore.
4. Motion is systemic. No custom curves.
5. Accessibility is the floor: 4.5:1 body, 44x44pt touch, reduced-motion.
6. HTML examples are photographs; they prove the system.
7. Tenant theming / dark mode / RTL are designed in if in scope.
8. design-system-worker-bee creates; ux-ui-svelte-worker-bee maintains.

File map

design-system-stinger/
├── 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-svelte-worker-bee)
├── 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.

Under-range indicates a rushed interview or incomplete authoring. Over-range indicates scope creep: split something out or trim.

The handoff line

End every