@mstar-harness/opencode 0.6.13 → 0.6.14

package/harness-skills/mstar-design-md/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: mstar-design-md
+description: DESIGN.md design system specification for Morning Star projects. Create, audit, and maintain project-level design tokens (Colors, Typography, Spacing, Elevation, Motion, Shapes, Components, Voice & Content) using Vercel Geist as reference template. Three-level completeness checklist (MVP/Standard/Production) with built-in upgrade placeholders. Supports light/dark dual-theme via DESIGN.md + DESIGN.dark.md sharing same token names with different values. Prepare 阶段由 @architect 主责创建，@product-manager 提供设计需求；@frontend-dev / @fullstack-dev 实现 UI 时消费；@qc-specialist / @qa-engineer 审查 UI 对齐 DESIGN.md。Read when PM assigns DESIGN.md creation in Prepare, initiating a new UI project, @architect defining a design system, implementing styled components, auditing UI against design spec, adding dark theme, or user mentions "DESIGN.md" / "design tokens" / "design system". Phase gate → **mstar-phase-gates**; paths → **mstar-plan-conventions**.
+---
+
+## Load order
+
+**Before first Read of this skill: Read `mstar-harness-core` (SKILL.md).** For Prepare phase integration and gate rules, read `mstar-phase-gates`. For plan directory paths (`{HARNESS_DIR}`, `{SPECS_DIR}`), read `mstar-plan-conventions`. On conflict, **`mstar-harness-core` wins**.
+
+| 你还可能要 Read | 何时 |
+|-----------------|------|
+| `mstar-phase-gates` | Prepare 阶段判定 gate、何时 DESIGN.md 必须就绪 |
+| `mstar-plan-conventions` | `{HARNESS_DIR}` / `{SPECS_DIR}` 路径解析 |
+| `mstar-roles` | `@architect` / `@product-manager` / `@frontend-dev` / `@qc-specialist` / `@qa-engineer` 角色职责边界 |
+| `mstar-coding-behavior` | 实现角色消费 DESIGN.md 前的通用编码约束 |
+
+## Scope (DESIGN.md lifecycle)
+
+| Topic | See |
+|-------|-----|
+| Normative spec: section definitions, token naming, light/dark rules | `references/design-md-spec.md` |
+| Three-level completeness checklist (MVP / Standard / Production) | `references/completeness-checklist.md` |
+| Vercel Geist DESIGN.md as annotated reference | `references/vercel-example.md` |
+| Full template with Level 2/3 placeholders | `templates/DESIGN.md.template` |
+| Dark theme template (same token names, different values) | `templates/DESIGN.dark.md.template` |
+
+**Out of scope:** rendered UI artifacts (use Open Design MCP `user-open-design`); frontend implementation that consumes DESIGN.md tokens (use `@frontend-dev` / `@fullstack-dev`); QC review verdict rules (→ **`mstar-review-qc`**).
+
+## Location
+
+- **Primary**: project root `DESIGN.md` (human + agent visible, aligns with `AGENTS.md`)
+- **Dark theme**: project root `DESIGN.dark.md` (same token names, different values)
+- `DESIGN.md` is a **project-level design contract**, not a harness internal artifact. It lives beside `README.md` and `AGENTS.md`.
+
+## Role lifecycle
+
+### Creator: `@architect` (primary) + `@product-manager` (requirements)
+
+`@architect` owns DESIGN.md content — token selection, naming, completeness level decisions. `@product-manager` provides design intent: brand identity, target audience, must-have UI patterns, accessibility requirements.
+
+### Orchestrator: `@project-manager`
+
+In Prepare phase, PM decides whether the project needs a DESIGN.md. If yes, dispatches to `@architect` with product requirements from `@product-manager`. PM checks DESIGN.md exists and meets the assigned completeness level before `plan(locked)`.
+
+### Consumers
+
+- `@frontend-dev` / `@fullstack-dev` — read DESIGN.md before implementing styled components; map tokens to CSS/theme variables
+- `@qc-specialist` — verify UI implementation aligns with DESIGN.md tokens
+- `@qa-engineer` — verify visual output matches design spec
+
+## Phase gate integration
+
+DESIGN.md is a **Prepare-stage artifact** (like spec). It must be created and reviewed before `plan(locked)` for any plan that includes UI work.
+
+1. PM includes "DESIGN.md creation/audit" in Prepare tracking checklist when the plan involves UI
+2. `@architect` creates or updates DESIGN.md; `@product-manager` reviews design intent alignment
+3. PM gates on: DESIGN.md exists, meets completeness level declared in plan, `@product-manager` signed off
+
+For **hotfix** or plans with no UI changes, DESIGN.md check may be skipped.
+
+## Completeness levels
+
+DESIGN.md supports three levels, each with built-in upgrade path:
+
+1. **Level 1 — MVP** (minimal, prevents guesswork): palette, base typography, spacing scale
+2. **Level 2 — Standard** (consistent components): full token scales, breakpoints, component tokens (Button, Input)
+3. **Level 3 — Production** (complete design system): dual theme, elevation, motion, shapes, component library, voice
+
+The template includes all levels; Level 2 and 3 sections are commented out with `<!-- LEVEL2_PLACEHOLDER: ... -->` markers that explain when to activate them. The audit workflow detects these placeholders and can recommend upgrade.
+
+Full checklist → `references/completeness-checklist.md`.
+
+## Workflows
+
+### Workflow 1: Create DESIGN.md (Prepare phase)
+
+1. Read `references/design-md-spec.md` for section definitions
+2. Copy `templates/DESIGN.md.template` to `{PROJECT_ROOT}/DESIGN.md`
+3. Interview `@product-manager` for brand colors, typography preferences, must-have patterns
+4. Fill Level 1 sections; leave Level 2/3 as-is (commented placeholders)
+5. If plan requires Level 2+ out of the gate, fill those sections too
+6. Run the completeness audit workflow below to confirm level
+7. Report to PM: path created, level achieved, what's needed for next level
+
+### Workflow 2: Audit DESIGN.md completeness
+
+1. Read `DESIGN.md` and `DESIGN.dark.md` (if exists)
+2. Load `references/completeness-checklist.md`
+3. Check each checklist item; note gaps
+4. Report:
+   - Current completeness level
+   - Gaps preventing next level
+   - Presence of upgrade placeholders (`LEVEL2_PLACEHOLDER`, `LEVEL3_PLACEHOLDER`)
+   - Recommendation: whether to upgrade now or defer
+5. Update DESIGN.md level tag (e.g., `<!-- COMPLETENESS_LEVEL: 1 -->`) if changed
+
+### Workflow 3: Add dark theme
+
+1. Read existing `DESIGN.md` to extract token names
+2. Copy `templates/DESIGN.dark.md.template` to `{PROJECT_ROOT}/DESIGN.dark.md`
+3. For each token in DESIGN.md, define the dark-theme equivalent value
+4. Preserve same token names; only values change (see `references/design-md-spec.md` § Light/Dark rules)
+5. Audit with Workflow 2 to confirm Level 3 completeness
+
+### Workflow 4: Consume DESIGN.md (implementation roles)
+
+Before writing styled UI code:
+1. Read `DESIGN.md` (and `DESIGN.dark.md` if exists)
+2. Extract tokens into implementation layer (CSS custom properties, Tailwind config, theme object, etc.)
+3. Follow DESIGN.md Voice & Content rules for copy text
+4. If DESIGN.md is missing or incomplete, report to PM — do not guess tokens
+
+## Light/Dark dual-theme rules
+
+Dual theme uses **same token names, different values** across two files:
+
+```
+DESIGN.md         DESIGN.dark.md
+-----------       --------------
+gray-100: #fff    gray-100: #111
+gray-1000: #000   gray-1000: #eee
+```
+
+- Token names are the **SSOT interface** — consumers reference tokens by name, not raw values
+- `references/design-md-spec.md` § Light/Dark rules defines the contract
+
+## Open Design integration
+
+If `user-open-design` MCP is available:
+- DESIGN.md is the **design intent** (tokens + rules)
+- Open Design manages **rendered artifacts** (HTML/CSS/JSX previews)
+- When DESIGN.md is updated, recommend syncing the Open Design project to reflect new tokens
+- DESIGN.md does not replace Open Design; they are complementary
+
+## References
+
+- `references/design-md-spec.md` — normative spec: section definitions, token naming conventions, light/dark contract
+- `references/completeness-checklist.md` — three-level audit checklist with detailed criteria per level
+- `references/vercel-example.md` — Vercel Geist DESIGN.md as annotated reference (read when creating from scratch or needing design inspiration)
+
+**Templates (this skill):**
+- `templates/DESIGN.md.template` — full template including all Level 1-3 sections with placeholder comments
+- `templates/DESIGN.dark.md.template` — dark theme template with same token names, different values

package/harness-skills/mstar-design-md/references/completeness-checklist.md

@@ -0,0 +1,175 @@
+# DESIGN.md Completeness Checklist
+
+Three-level progressive checklist for evaluating whether a `DESIGN.md` is sufficient to drive agent UI generation. Each level builds on the previous level's requirements.
+
+## How to use
+
+1. Read `DESIGN.md` (and `DESIGN.dark.md` if exists)
+2. Check each item in the target level (and all lower levels)
+3. An item is **complete** only when concrete values exist — placeholder comments do not count
+4. A `DESIGN.md` is at **Level N** when all items in Level N and below are complete
+5. Record the result in a comment at the top of DESIGN.md:
+
+```
+<!-- COMPLETENESS_LEVEL: N — last audited YYYY-MM-DD -->
+```
+
+## Level 1 — MVP (prevents guesswork)
+
+The minimum bar for an agent to produce UI without hallucinating colors and typography. Sufficient for early-stage projects, prototypes, and CLI tools with minimal UI.
+
+### Checklist
+
+- [ ] **Overview** — design system name and aesthetic principles stated
+- [ ] **Colors — Background** — at least one surface color (`background-100`)
+- [ ] **Colors — Text** — at least one text color (`gray-1000` or equivalent)
+- [ ] **Colors — Accent** — at least one accent color for links/actions (`blue*` or brand equivalent)
+- [ ] **Colors — Semantic** — at least one error color (`red*`) and warning color (`amber*`)
+- [ ] **Typography — Body** — at least one body text token with font family, size, weight, line height
+- [ ] **Typography — Heading** — at least one heading token
+- [ ] **Spacing** — base unit declared (4px or 8px) and at least 5 scale steps
+- [ ] **Breakpoints** — at least 2 responsive breakpoints defined
+
+### What an agent CAN do at Level 1
+
+- Style a basic page with correct brand colors
+- Choose readable typography
+- Apply consistent spacing
+- Make a responsive layout that works on mobile and desktop
+- Signal errors with the correct color
+
+### What an agent CANNOT do at Level 1
+
+- Build a consistent component library (no component tokens)
+- Apply elevation/shadow correctly (will guess)
+- Use motion responsibly (will guess)
+- Generate dark mode (no DESIGN.dark.md)
+- Apply voice rules to copy text
+
+### Verdict
+
+- **All 9 items checked → Level 1 complete**
+- **Missing items → below Level 1 (insufficient for agent UI generation)**
+
+## Level 2 — Standard (consistent components)
+
+Sufficient for building a consistent, polished UI with reusable components. The expected level for production codebases with a frontend.
+
+Prerequisite: Level 1 complete.
+
+### Checklist
+
+- All Level 1 items complete
+- [ ] **Colors — Full background scale** — `background-100` through at least `background-300`
+- [ ] **Colors — Full gray solid scale** — `gray-100` through `gray-1000` (10 steps)
+- [ ] **Colors — Gray alpha scale** — at least `gray-alpha-100` through `gray-alpha-600`
+- [ ] **Colors — All accent scales** — `blue`, `red`, `amber`, `green`, `teal`, `purple`, `pink` with at least `700`/`800`/`900`/`1000` steps each
+- [ ] **Typography — Headings** — at least 3 heading levels (e.g., `heading-32`, `heading-24`, `heading-20`)
+- [ ] **Typography — Labels** — at least one label token
+- [ ] **Typography — Buttons** — at least one button typography token
+- [ ] **Spacing** — full 9-step scale (4, 8, 12, 16, 24, 32, 40, 64, 96px) and three-step rhythm documented
+- [ ] **Breakpoints** — at least 4 breakpoints
+- [ ] **Components — Button** — at least primary and secondary variants with size variants (default 40px, small 32px), plus hover/active/disabled/focus states
+- [ ] **Components — Input** — at least default variant with size variants, plus hover/active/disabled/focus/error states
+
+### What an agent CAN do at Level 2
+
+- Everything from Level 1
+- Build a consistent Button component with all states
+- Build a consistent Input component with all states
+- Use the full color scale for nuanced visual hierarchy
+- Apply correct typography to every text role
+- Use translucent overlays and borders (alpha scale)
+- Pick the right accent color for each semantic purpose
+
+### What an agent CANNOT do at Level 2
+
+- Generate dark mode (no DESIGN.dark.md)
+- Apply elevation/shadows with confidence (may guess)
+- Use motion consistently (may guess)
+- Enforce voice rules on copy text
+- Know the correct border radius for each component type
+
+### Verdict
+
+- **All 11 items checked (on top of Level 1) → Level 2 complete**
+- **1–3 items missing → Level 2 partial; useable but expect component inconsistencies**
+- **4+ items missing → below Level 2; recommend completing Level 1 only deploy**
+
+## Level 3 — Production (complete design system)
+
+Full design system ready for production at scale. Includes dual theme, motion, and voice.
+
+Prerequisite: Level 2 complete.
+
+### Checklist
+
+- All Level 1 and Level 2 items complete
+- [ ] **DESIGN.dark.md exists** — dark theme file with same token names, dark-appropriate values
+- [ ] **Dark theme covers all tokens** — every token in DESIGN.md has a corresponding entry in DESIGN.dark.md
+- [ ] **Elevation — Shadows** — at least 3 elevation levels (card, popover, modal) with explicit `box-shadow` values
+- [ ] **Motion — Easing** — easing curve declared
+- [ ] **Motion — Durations** — at least state change, popover, modal durations
+- [ ] **Motion — Reduced motion** — `prefers-reduced-motion` rule declared
+- [ ] **Shapes — Border radius** — at least 4 radius tokens (surface/input, menu/modal, fullscreen, pill)
+- [ ] **Components — Full library** — at least Card, Modal, Tooltip, Menu/Dropdown tokens
+- [ ] **Voice & Content** — writing rules documented: casing conventions, action naming, error format, toast format, empty state format
+
+### What an agent CAN do at Level 3
+
+- Everything from Levels 1 and 2
+- Generate dark-mode-compatible UI
+- Apply elevation correctly for every UI layer
+- Animate state changes consistently
+- Apply correct border radius per element type
+- Write correct microcopy (button labels, errors, toasts, empty states)
+- Build a full component library (Card, Modal, Tooltip, Menu)
+
+### Verdict
+
+- **All 9 items checked → Level 3 complete (production-ready)**
+- **DESIGN.dark.md missing but rest complete → Level 2+ (partial Level 3, no dark mode)**
+
+## Audit workflow
+
+### When auditing existing DESIGN.md
+
+1. Load the DESIGN.md file
+2. Start at Level 1 checklist — check each item against actual content
+3. If Level 1 complete, proceed to Level 2
+4. If Level 2 complete, proceed to Level 3
+5. Record the level as `<!-- COMPLETENESS_LEVEL: N -->` at top of DESIGN.md
+6. For each incomplete item, note what's missing and which level it belongs to
+7. Check for `LEVEL2_PLACEHOLDER` / `LEVEL3_PLACEHOLDER` markers — if present and the project is ready for upgrade, recommend activation
+
+### When creating new DESIGN.md
+
+1. Decide target level with PM/architect:
+   - Prototype / early project → Level 1
+   - Production frontend → Level 2
+   - Full design system → Level 3
+2. Copy the template from `templates/DESIGN.md.template`
+3. Fill all items in the target level
+4. Run this checklist to confirm
+5. Leave higher-level placeholders as-is
+
+### When upgrading DESIGN.md
+
+1. Read current DESIGN.md and note the level tag
+2. Identify which items in the next level are missing
+3. For each missing item, either:
+   - Fill with concrete values if known
+   - Leave the `LEVEL*_PLACEHOLDER` marker if deferred
+4. Re-audit and update the level tag
+
+## Upgrade trigger conditions
+
+Agents encountering a DESIGN.md with placeholders should evaluate these conditions:
+
+| Condition | Action |
+|-----------|--------|
+| `LEVEL2_PLACEHOLDER` found AND plan includes component work | Recommend completing the Level 2 sections |
+| `LEVEL3_PLACEHOLDER` found AND plan includes dark mode | Recommend creating DESIGN.dark.md |
+| `LEVEL3_PLACEHOLDER` found AND plan targets production release | Recommend completing Level 3 |
+| `COMPLETENESS_LEVEL: 1` AND project has >3 UI views | Recommend upgrading to Level 2 |
+| `COMPLETENESS_LEVEL: 2` AND project has dark mode requirement | Recommend upgrading to Level 3 |

package/harness-skills/mstar-design-md/references/design-md-spec.md

@@ -0,0 +1,378 @@
+# DESIGN.md Normative Spec
+
+This document defines the normative structure, token naming conventions, and rules for a properly formed `DESIGN.md` file. It is the single source of truth for what each section means and how tokens should be defined.
+
+## 1. File format
+
+- Plain Markdown (`.md`) in project root
+- UTF-8 encoding
+- Multi-theme: `DESIGN.md` (light/default) + `DESIGN.dark.md` (dark variant, same token names)
+
+## 2. Section definitions
+
+Each section below maps to one heading in `DESIGN.md`. Sections are ordered as shown in Vercel Geist (recommended), but projects may omit sections not yet relevant.
+
+### 2.1 Overview
+
+**Purpose:** Declare the design system's identity — a short statement that grounds all downstream decisions.
+
+**What to include:**
+- Name of the design system
+- Core aesthetic principles (e.g., minimal, high-contrast, playful)
+- Primary audience (developer tools, consumer app, dashboard, etc.)
+- Note whether this is a light theme, dark theme, or references another file for the opposite theme
+
+**Example (minimal):**
+
+```
+# Acme Design
+
+Acme Design is a minimal, high-contrast design system for our developer dashboard.
+Prioritize readability and signal state through color and iconography, not decoration.
+
+This is the Light theme. The Dark theme lives at `/DESIGN.dark.md`.
+```
+
+**Level relevance:** Level 1+
+
+### 2.2 Colors
+
+**Purpose:** Define every color used in the UI, organized into scales.
+
+**Conventions:**
+- Each color scale has 10 steps (`100`–`1000`), encoding intent:
+  - `100`: default background
+  - `200`: hover background
+  - `300`: active background
+  - `400`: default border
+  - `500`: hover border
+  - `600`: active border
+  - `700`: solid fill
+  - `800`: solid fill hover
+  - `900`: secondary text/icons
+  - `1000`: primary text/icons
+- **Background scales** (`background-100`, `background-200`): page/card surfaces
+- **Alpha scales** (`gray-alpha-*`): translucent overlays, borders, dividers — layer over any background
+- **Solid scales** (`gray-*`): text, opaque fills — hold contrast on any surface
+- **Accent scales** (`blue`, `red`, `amber`, `green`, `teal`, `purple`, `pink`): carry meaning — success, error, warning, links, focus
+- Accent scales may use fewer steps if not all needed
+
+**Values:** sRGB hex (`#ffffff`), optionally with wide-gamut equivalents in `oklch()`.
+
+**Example:**
+
+```
+## Colors
+
+### Background
+| Token | Value |
+|-------|-------|
+| background-100 | #ffffff |
+| background-200 | #f5f5f5 |
+
+### Gray (solid)
+| Token | Value |
+|-------|-------|
+| gray-100 | #f5f5f5 |
+| gray-700 | #333333 |
+| gray-1000 | #111111 |
+
+### Accent
+| Token | Value |
+|-------|-------|
+| blue-700 | #0066ff |
+| red-700 | #e60000 |
+```
+
+**Level relevance:** Level 1+ requires at least background, gray, and one accent. Level 2+ requires full 10-step scales, alpha scale, and all accent colors.
+
+### 2.3 Typography
+
+**Purpose:** Define font families, sizes, weights, line heights, and letter spacing for every text role.
+
+**Conventions:**
+- **Heading tokens** (`heading-72` through `heading-14`): title pages and section headings
+- **Label tokens** (`label-20` through `label-12`): single-line scannable text — navigation, form labels, table headers
+- **Copy tokens** (`copy-24` through `copy-13`): multi-line body text with taller line height
+- **Button tokens** (`button-16` through `button-12`): medium-weight labels for buttons
+- **Mono tokens**: same metrics with monospace font for code/data
+- Each token carries: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`
+- Token name encodes intended font size (e.g., `copy-14` ≈ 14px body copy)
+- Use tabular figures for numbers that need alignment
+
+**Example (minimal):**
+
+```
+## Typography
+
+### Headings
+| Token | Font | Size | Weight | Line | Spacing |
+|-------|------|------|--------|------|---------|
+| heading-32 | Inter | 32px | 600 | 1.2 | -0.02em |
+| heading-20 | Inter | 20px | 600 | 1.3 | -0.01em |
+
+### Body
+| Token | Font | Size | Weight | Line | Spacing |
+|-------|------|------|--------|------|---------|
+| copy-16 | Inter | 16px | 400 | 1.6 | 0 |
+| copy-14 | Inter | 14px | 400 | 1.5 | 0 |
+```
+
+**Level relevance:** Level 1+ requires at least body text (one copy token) and one heading token. Level 2+ requires full heading/label/copy/button typography scale.
+
+### 2.4 Spacing & Layout
+
+**Purpose:** Define the spatial grid and responsive breakpoints.
+
+**Conventions:**
+- Base unit: 4px or 8px (consistent across the system)
+- Scale: `4, 8, 12, 16, 24, 32, 40, 64, 96` (on 4px) or equivalent on 8px
+- Three-step rhythm: small inside group → medium between groups → large between sections
+- Card padding: 24px default, 16px compact, 32px hero
+- Content max-width with responsive side padding
+- Breakpoints: provide explicit pixel values and names
+
+**Example:**
+
+```
+## Layout
+
+### Spacing scale
+4px, 8px, 12px, 16px, 24px, 32px, 40px, 64px, 96px
+
+### Rhythm
+- 8px: inside a group (label + input, icon + text)
+- 16px: between related groups
+- 32-40px: between sections
+
+### Breakpoints
+| Name | Width |
+|------|-------|
+| sm | 401px |
+| md | 601px |
+| lg | 961px |
+| xl | 1200px |
+```
+
+**Level relevance:** Level 1+ requires spacing scale and at least 2 breakpoints.
+
+### 2.5 Elevation & Depth
+
+**Purpose:** Define shadow values for layered UI elements.
+
+**Conventions:**
+- Use tonal surfaces first, shadows second — keep shadows subtle
+- Define shadow values per elevation level: cards, popovers, modals
+- Pair each elevation with a matching border radius
+
+**Example:**
+
+```
+## Elevation
+
+### Shadows
+| Level | Value |
+|-------|-------|
+| Card | 0 2px 2px rgba(0,0,0,0.04) |
+| Popover | 0 1px 1px rgba(0,0,0,0.02), 0 4px 8px -4px rgba(0,0,0,0.04), 0 16px 24px -8px rgba(0,0,0,0.06) |
+| Modal | 0 1px 1px rgba(0,0,0,0.02), 0 8px 16px -4px rgba(0,0,0,0.04), 0 24px 32px -8px rgba(0,0,0,0.06) |
+```
+
+**Level relevance:** Level 3 only.
+
+### 2.6 Motion
+
+**Purpose:** Define animation durations and easing curves.
+
+**Conventions:**
+- Motion clarifies change, never decorates
+- Default: 0ms (instant) is often the best choice
+- When needed: short, physical easing — roughly 150ms state, 200ms popover, 300ms modal
+- Honor `prefers-reduced-motion`
+- No looping or attention-grabbing animations
+
+**Example:**
+
+```
+## Motion
+
+### Easing
+Default: cubic-bezier(0.175, 0.885, 0.32, 1.1)
+
+### Durations
+| Context | Duration |
+|---------|----------|
+| State change | 150ms |
+| Popover/Tooltip | 200ms |
+| Modal/Overlay | 300ms |
+```
+
+**Level relevance:** Level 3 only.
+
+### 2.7 Shapes
+
+**Purpose:** Define border radius values.
+
+**Conventions:**
+- Keep radii tight and consistent
+- One radius family per view, never mix rounded and sharp corners
+- Common values: 6px (surfaces), 12px (menus/modals), 16px (fullscreen), 9999px (pills)
+
+**Example:**
+
+```
+## Shapes
+
+### Border Radius
+| Context | Value |
+|---------|-------|
+| Surface, Input, Button | 6px |
+| Menu, Modal, Popover | 12px |
+| Fullscreen | 16px |
+| Pill, Avatar | 9999px |
+```
+
+**Level relevance:** Level 3 only.
+
+### 2.8 Components
+
+**Purpose:** Define ready-to-use token values for common components.
+
+**Conventions:**
+- Each component gets: `backgroundColor`, `textColor`, `rounded`, `height` (and `borderColor` where applicable)
+- Size variants: default (40px), small (32px), large (48px)
+- State mappings: hover steps foreground up one, active steps up two; border from 400→500→600
+- Focus ring: two-layer box-shadow (surface gap + accent ring)
+- Disabled: 100 fill + 700 text + not-allowed cursor
+
+**Example:**
+
+```
+## Components
+
+### Button
+| Variant | Background | Text | Border | Radius | Height |
+|---------|-----------|------|--------|--------|--------|
+| primary | gray-1000 | background-100 | — | 6px | 40px |
+| secondary | background-100 | gray-1000 | gray-alpha-400 | 6px | 40px |
+| tertiary | transparent | gray-1000 | — | 6px | 40px |
+| error | red-800 | #fff | — | 6px | 40px |
+
+### Input
+| Variant | Background | Text | Border | Radius | Height |
+|---------|-----------|------|--------|--------|--------|
+| default | background-100 | gray-1000 | gray-alpha-400 | 6px | 40px |
+```
+
+**Level relevance:** Level 2+ requires at least Button and Input tokens. Level 3 requires full component library.
+
+### 2.9 Voice & Content
+
+**Purpose:** Define content writing rules for the UI.
+
+**Conventions:**
+- Title Case for labels, buttons, titles, tabs
+- Sentence case for body, helper text, toasts
+- Verb + Noun for actions (`Deploy Project`, never `Confirm`)
+- Errors: what happened + what to do
+- Toasts: specific thing + no trailing period + no `successfully`
+- Empty states: describe the first action
+- In-progress: present participle + ellipsis (`Deploying…`)
+- Use numerals, curly quotes, the ellipsis character
+
+**Example:**
+
+```
+## Voice & Content
+
+- Use Title Case for labels, buttons, titles, and tabs
+- Sentence case for body, helper text, and toasts
+- Name actions with a verb and a noun: `Deploy Project`, `Delete Member`
+- Write errors as what happened plus what to do next
+- Toasts name the specific thing that changed, drop the trailing period
+- Empty states point to the first action: `No deployments yet. Push to your Git repository to create one.`
+```
+
+**Level relevance:** Level 3 only.
+
+## 3. Token naming conventions
+
+### Color tokens
+
+```
+{namespace}-{step}
+```
+
+- `namespace`: `background`, `gray`, `gray-alpha`, `blue`, `red`, `amber`, `green`, `teal`, `purple`, `pink`
+- `step`: `100`–`1000` (10-step scale encoding intent as defined in §2.2)
+
+### Typography tokens
+
+```
+{role}-{size}
+```
+
+- `role`: `heading`, `label`, `copy`, `button`
+- `size`: approximate font size in pixels
+- Mono variant: `{role}-{size}-mono`
+
+### Breakpoint tokens
+
+Lowercase short names: `sm`, `md`, `lg`, `xl`, `2xl`
+
+## 4. Light/Dark dual-theme rules
+
+### Contract
+
+Dual theme uses **same token names with different values** in two separate files:
+
+- `DESIGN.md` — light (or default) theme
+- `DESIGN.dark.md` — dark theme
+
+### Rules
+
+1. **Token names are identical** across both files
+2. **Only the values differ** — a light `background-100: #ffffff` becomes dark `background-100: #111111`
+3. **Both files define the same token set** — no token can exist in only one file
+4. **DESIGN.md is always the SSOT for token names** — DESIGN.dark.md copies the structure
+5. If a token isn't relevant to dark mode (e.g., a light-only accent), include it in DESIGN.dark.md anyway with a sensible dark-equivalent value
+6. Add `DESIGN.dark.md` path reference in DESIGN.md Overview
+
+### Naming
+
+Dark theme file must be named `DESIGN.dark.md` (not `design-dark.md` or `DESIGN_DARK.md`).
+
+## 5. Upgrade placeholders
+
+Sections not yet filled should use HTML comment markers:
+
+```
+<!-- LEVEL2_PLACEHOLDER: Complete the 10-step color scales and add alpha scale when the design matures. See `references/completeness-checklist.md` § Level 2. -->
+```
+
+```
+<!-- LEVEL3_PLACEHOLDER: Add Elevation, Motion, Shapes, Voice & Content, and full Component library when ready for production design system. See `references/completeness-checklist.md` § Level 3. -->
+```
+
+Agents encountering these placeholders understand that:
+- The section is intentionally deferred, not accidentally empty
+- The placeholder describes what's missing and when to revisit
+- An upgrade workflow can detect these markers and recommend progression
+
+## 6. Mapping to implementation
+
+DESIGN.md tokens should map to implementation as follows:
+
+| DESIGN.md | Implementation |
+|-----------|---------------|
+| Color tokens | CSS custom properties (`--color-gray-100`) or theme object |
+| Typography tokens | CSS classes or Tailwind prose config |
+| Spacing scale | CSS custom properties or Tailwind spacing config |
+| Breakpoints | CSS media queries or Tailwind screens |
+| Elevation | `box-shadow` or Tailwind shadow config |
+| Motion | `transition` or animation library config |
+| Shapes | `border-radius` or Tailwind radius config |
+| Component tokens | Component prop defaults or CSS classes |
+| Voice rules | Linter rules or prompt context for copy generation |
+
+The agent consuming DESIGN.md is responsible for this mapping, not DESIGN.md itself. DESIGN.md stays implementation-agnostic.