Design System

---
description: "Design system reference — load, browse, or create design system specs"
argument-hint: "[system-name] [token] or 'new [name]' to scaffold"
allowed-tools:
  - Read
  - Write
  - Glob
  - Bash(ls:*)
  - Bash(mkdir:*)
  - AskUserQuestion
model: inherit
context: inherit
user-invocable: true
---

# Design System

<purpose>
Load an existing design system spec for reference, or scaffold a new one from a template.
</purpose>

---

## Mode Detection

Parse `$ARGUMENTS`:
- If first token is `new` → **Scaffold Mode** (remaining tokens = system name)
- Otherwise → **Load Mode** (first token = system name or query)

---

## Load Mode (default)

1. **Discover systems**: `Glob("skills/design-system/systems/*/spec.md")` from the repo root
2. **Select system**:
   - If `$ARGUMENTS` first token matches a discovered system name → use it; remaining tokens are the query
   - If no token match and exactly one system exists → default to it silently
   - If no token match and multiple systems exist → list available systems via `AskUserQuestion`
3. **Load**: `Read systems/<selected>/spec.md`
4. **Present**: Output the spec content. If a query was provided, highlight the relevant section.

---

## Scaffold Mode (`new <name>`)

1. **Parse** system name from `$ARGUMENTS` (e.g., `new acme-brand` → name is `acme-brand`)
2. **Validate** name is lowercase kebab-case; reject otherwise
3. **Create directory**: `mkdir -p systems/<name>/`
4. **Copy template**: Read `templates/spec.md`, write to `systems/<name>/spec.md`
5. **Replace placeholder**: Update `[System Name]` and `[system name]` in the copied file with the actual name
6. **Ask user**:
   ```
   AskUserQuestion: "I've scaffolded `systems/<name>/spec.md` with blank sections.
   Would you like to fill it in interactively now, or edit the file yourself later?"
   ```
   - **Interactive** → Walk through each section (Color Palette, Typography, Borders, Layout, Cards, Components, CSS, Shadows, Breakpoints, Scrollbar, Constraints), asking the user for their values
   - **Later** → Report the file path and stop
7. **Report**: "Design system `<name>` created. Use `/orc:vibe-code <name> [component]` to design with it."

---

## Examples

### Load a system

```
/orc:design-system orc-brand
```
Loads `systems/orc-brand/spec.md` into context — full color palette, typography, layout, component patterns.

### Load with a query

```
/orc:design-system orc-brand typography
```
Loads orc-brand spec, highlights the Typography section (font families, type scale).

### Scaffold a new system

```
/orc:design-system new acme-brand
```
Creates `systems/acme-brand/spec.md` from template with blank sections, asks whether to fill interactively.

### Real-world: how orc-brand was created

The orc-brand design system was built in 3 steps:

1. **Research** — `/orc:adr "Design system for a Claude Code plugin landing page — dark theme, developer-focused, terminal aesthetic"` researched color palettes, typography, and layout patterns across 100+ developer tool landing pages. Output: `docs/adr/ADR5.001-landing-page-design-direction.md`

2. **Scaffold** — `/orc:design-system new orc-brand` created the empty spec from template.

3. **Fill** — The spec was filled based on ADR findings: deep charcoal palette (#0D0D0D base), warm amber accent (#E8A04A) for Claude brand tie-in, Inter + JetBrains Mono typography, three-layer CSS token architecture (primitives → semantic → component), terminal block and feature card component patterns. Static HTML + CSS only — no framework.