---
name: design-system-init
effort: medium
description: >
  Bootstrap a component registry / design system on a project that doesn't have
  one yet. Scaffolds ${paths.design_system}/INDEX.md (component index +
  Canonical Authority Matrix), tokens-reference.md (extracted from
  ${paths.global_styles} / Tailwind config), and a components/<Name>.md spec
  per primitive already present under ${paths.components_primitives}. Then
  flips features.has_design_system: true in baldart.config.yml. Use when the
  user says /design-system-init, "crea design system", "bootstrap design
  system", "inizializza registro componenti", or when configure detected no
  design-system path and the user wants one. Idempotent — refuses to overwrite
  an existing registry, supports incremental re-runs to add specs for new
  components.
---

# Design-System Init

Scaffold the component registry that the registry-first protocol
(`framework/agents/design-system-protocol.md`) treats as BLOCKING for every
UI task. Without a registry, the BLOCKING reads in `ui-design`,
`frontend-design`, `ui-expert`, and `/design-review` are inert — they have
nothing to read. This skill creates the missing pieces from the codebase's
current state so the discipline can kick in immediately.

## Project Context

**Reads from `baldart.config.yml`:** `paths.design_system`,
`paths.components_primitives`, `paths.components_root`, `paths.global_styles`,
`paths.ui_guidelines`, `identity.brand_name`, `identity.design_philosophy`,
`stack.design_system_signals`.

**Gated by features:** none — this skill is the bootstrap mechanism for
`features.has_design_system`. It refuses to run when a registry is already
present (`has_design_system: true` AND `paths.design_system/INDEX.md` exists).

**Overlay:** loads `.baldart/overlays/design-system-init.md` if present —
project-specific opinions (e.g. mandated section order in `components/<Name>.md`,
brand-voice rules to inject into the scaffolded INDEX, custom token extraction
recipe for non-Tailwind stacks).

**On missing keys:** ask the user; do not assume defaults. See
`framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


## What This Skill Does

1. **Refusal check.** Reads `baldart.config.yml`.
   - If `features.has_design_system: true` AND `${paths.design_system}/INDEX.md`
     exists: stop with "Registry already present at `${paths.design_system}`.
     To extend it, edit it directly or invoke `ui-design` / `frontend-design`
     which know how to propose registry additions."
   - If `has_design_system: true` but the path is missing: warn about the
     drift, offer to re-scaffold at the configured path.
2. **Resolve target path.** Default `docs/design-system/`. Ask the user to
   confirm or override. Use `${paths.design_system}` if already set in config.
3. **Inventory existing primitives.** Launch the `codebase-architect` agent
   on `${paths.components_primitives}` (and `${paths.components_root}/shared`
   when present) to extract: file path, exported component name, props
   signature, variants (if discoverable), accessibility hooks used, tokens
   referenced.
4. **Extract token contract.** Read `${paths.global_styles}` for CSS custom
   properties; read `tailwind.config.{ts,js,mjs,cjs}` for theme extensions;
   read any `tokens.{json,ts,js}` or Style Dictionary output. Group by
   category (color, spacing, shadow, radius, typography, motion).
5. **Scaffold the files** under the target path:
   - `INDEX.md` — component index, Canonical Authority Matrix (empty
     visual/behavioral/composition columns to be filled by the team),
     pointer to `tokens-reference.md` and `components/`.
   - `tokens-reference.md` — extracted tokens, grouped, with a note that
     `tokens-reference.md` is the SSOT and hardcoded literals are forbidden.
   - `components/<Name>.md` — one file per discovered primitive, generated
     from `scripts/component-spec.template.md`. Fill the fields the inventory
     could resolve; leave clearly-marked TODO sections for the rest.
   - `patterns/.gitkeep` — empty dir for future pattern docs.
6. **Update config.** Set `features.has_design_system: true` and
   `paths.design_system: <target>` in `baldart.config.yml`. Use the same
   YAML write path as `configure` (preserve user values, never clobber
   unrelated keys).
7. **Print next-steps.** Authority Matrix to fill, specs to review, suggested
   first follow-up (`/design-review` on a key route to validate the registry).

## Workflow

1. **Refusal check** — see § What This Skill Does step 1.

2. **Target path prompt:**
   ```
   Scaffold the registry at: docs/design-system/  [Y/n/custom]
   ```

3. **Inventory** — launch `codebase-architect` with this prompt skeleton:
   > Enumerate the UI primitives under `${paths.components_primitives}`. For
   > each: file path, exported name, props type (best-effort from TS/JSDoc),
   > variants (e.g. `variant="primary|ghost"`), accessibility attributes
   > (aria-*, role, focus management), design tokens referenced (CSS vars,
   > Tailwind classes that map to tokens). Report as a JSON-friendly list.

4. **Token extraction** — for each detected source:
   - CSS custom properties: parse `--*: ...;` declarations and group by prefix.
   - Tailwind theme: parse `theme.extend.{colors,spacing,boxShadow,borderRadius,fontFamily,transitionDuration,transitionTimingFunction}`.
   - Style Dictionary / tokens file: parse the JSON tree.
   - If nothing is found, leave a TODO section in `tokens-reference.md`
     pointing the team to populate it before relying on the SSOT contract.

5. **Generate files** using the template in
   `scripts/component-spec.template.md` for each component, and the inline
   templates below for INDEX and tokens-reference.

6. **Persist config:**
   ```yaml
   paths:
     design_system: docs/design-system   # or user-chosen
   features:
     has_design_system: true
   ```

7. **Output** — short status block (see Output Contract).

## Output Contract

```
Design-system bootstrap:
  ✓ Created docs/design-system/INDEX.md
  ✓ Created docs/design-system/tokens-reference.md (32 tokens extracted)
  ✓ Generated 17 component specs under docs/design-system/components/
  ⚠ 4 components had no resolvable props — TODO sections marked
Config updated: baldart.config.yml has_design_system=true, paths.design_system=docs/design-system
Next: review INDEX.md Authority Matrix, fill TODO sections, run /design-review on a key route.
```

## INDEX.md template

The generated `INDEX.md` has this skeleton (concrete values substituted from
the inventory):

```markdown
# ${identity.brand_name} Design System

Single source of truth for visual, behavioral, and compositional decisions on
this product. Read this BEFORE producing or reviewing any UI. The registry-first
protocol is defined in `framework/agents/design-system-protocol.md`.

## Token Contract

Tokens live in [`tokens-reference.md`](tokens-reference.md). Hardcoded color /
shadow / radius / spacing / motion values are FORBIDDEN when these tokens
cover the use case.

## Component Index

| Component | File | Purpose | Spec |
|-----------|------|---------|------|
| Button    | ${paths.components_primitives}/Button.tsx | … | [components/Button.md](components/Button.md) |
| …         | …    | …       | …    |

## Canonical Authority Matrix

| Dimension          | Authority                       | Override path |
|--------------------|---------------------------------|---------------|
| Color / shadow / radius / spacing | `tokens-reference.md` | Propose a new token + ADR |
| Props / variants / a11y           | per-component `components/<Name>.md` | Update the spec in the same change |
| Composition (patterns)            | `patterns/<topic>.md`            | New pattern doc + INDEX entry |

## Quick MUST Rules

- Reuse from the Component Index before inventing a new primitive.
- Consume tokens via the project's mechanism (CSS vars / Tailwind theme /
  theme provider) — never hardcode literals.
- Any new primitive ships with its `components/<Name>.md` spec in the same
  change.
- Authority Matrix violations require a registry update, not a local override.

## How to Extend

- New primitive → create `components/<Name>.md` (the template lives at
  `.framework/framework/.claude/skills/design-system-init/scripts/component-spec.template.md`
  after `npx baldart add` — copy it, fill it in, drop under
  `${paths.design_system}/components/`),
  implement under `${paths.components_primitives}`, add the row above.
- New pattern → create `patterns/<topic>.md`, link from this INDEX.
- New token → add to `tokens-reference.md`, propagate to the project's
  token mechanism.
```

## tokens-reference.md template

```markdown
# Token Reference

Single source of truth for design tokens. Values below are extracted from
${paths.global_styles} and tailwind config (when present). DO NOT hardcode
literals that duplicate these tokens in components.

## Color
- `--color-primary: <value>` — …
- …

## Spacing
- `--space-1: <value>` — …
- …

## Shadow
- …

## Radius
- …

## Typography
- …

## Motion
- duration: …
- easing: …
```

## Notes

- The skill never modifies source components — its only side effects are
  creating files under `${paths.design_system}` and updating
  `baldart.config.yml`.
- Generated specs are starting points, not final docs. The expected next move
  is human review + filling TODO sections + a `/design-review` pass.
- Idempotent: re-running detects existing specs and only generates files for
  new primitives (and updates the Component Index table).

## See Also

- `framework/agents/design-system-protocol.md` — the protocol this skill bootstraps.
- `framework/agents/project-context.md` — config + overlay contract.
- `framework/.claude/skills/ui-design/SKILL.md` — primary consumer (reads
  the registry BLOCKING).
- `scripts/component-spec.template.md` — per-component spec template.
