@mstar-harness/opencode 0.6.20 → 0.6.21

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

@@ -4,13 +4,137 @@ This document defines the normative structure, token naming conventions, and rul
 
 ## 1. File format
 
-- Plain Markdown (`.md`) in project root
+- Markdown (`.md`) with YAML frontmatter in project root
 - UTF-8 encoding
+- **YAML frontmatter** (`---` delimited block at top) contains structured, machine-readable token values
+- **Markdown body** (everything after the `---` closing delimiter) contains human/agent-readable documentation, usage rules, and design intent
 - Multi-theme: `DESIGN.md` (light/default) + `DESIGN.dark.md` (dark variant, same token names)
 
+## 1.5. YAML Frontmatter — Structured Token Store
+
+The YAML frontmatter is the **single source of truth** for token values. The Markdown body is supplementary documentation. Tools and agents MUST parse the frontmatter for token resolution; the body prose explains intent and rules.
+
+### Version field
+
+```yaml
+version: 0.1.0
+```
+
+Format version identifier. Current value: `0.1.0`.
+
+### Name and description
+
+```yaml
+name: "[Design System Name]"
+description: "[Brief description, noting light/dark theme relationship]"
+```
+
+### Colors (`colors:`)
+
+Flat map of token names to hex (or `oklch()` for P3) values. All scales are flat — not nested:
+
+```yaml
+colors:
+  background-100: "#ffffff"
+  gray-1000: "#171717"
+  blue-700: "#006bff"
+  blue-700-p3: "oklch(57.61% 0.2508 258.23)"
+```
+
+- Color token names follow the `{namespace}-{step}` convention (see §3)
+- `*-p3` variants are optional wide-gamut equivalents in `oklch()` for Display P3 screens
+- Alpha tokens use `#rrggbbaa` hex-with-alpha format (8 hex digits)
+- All tokens are at the top level of `colors:` — no sub-grouping by family
+
+### Typography (`typography:`)
+
+Map of tokens to structured sub-objects:
+
+```yaml
+typography:
+  copy-16:
+    fontFamily: Geist Sans
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 1.6
+    letterSpacing: 0
+```
+
+Each typography token sub-object contains exactly five properties: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`. Typography token names follow the `{role}-{size}` convention (see §3).
+
+### Spacing (`spacing:`)
+
+Flat map of numeric keys to pixel values:
+
+```yaml
+spacing:
+  base: 4px
+  1: 4px
+  2: 8px
+  3: 12px
+  4: 16px
+  6: 24px
+  8: 32px
+  10: 40px
+  16: 64px
+  24: 96px
+```
+
+- `base` declares the base unit (typically `4px` or `8px`)
+- Numeric keys are multipliers on the base unit
+
+### Border radius (`rounded:`)
+
+Flat map of semantic keys to pixel values:
+
+```yaml
+rounded:
+  sm: 6px
+  md: 12px
+  lg: 16px
+  full: 9999px
+```
+
+### Components (`components:`)
+
+Map of component variant names to structured sub-objects. Values reference other frontmatter keys using `{path}` syntax:
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.gray-1000}"
+    textColor: "{colors.background-100}"
+    typography: "{typography.button-14}"
+    rounded: "{rounded.sm}"
+    padding: "0 10px"
+    height: 40px
+```
+
+- `{colors.X}` resolves to the value of `colors.X` in the same file's frontmatter
+- `{typography.X}` resolves to the typography object (not a single value — consumers use the full object)
+- `{rounded.X}` resolves to the border-radius value
+- Direct values (like `"#ffffff"` or `40px`) are literal and do not reference other keys
+
+### Completeness level in frontmatter
+
+The frontmatter always contains the full key structure for every level. Level 2+ keys that are not yet filled are YAML-commented out with `# LEVEL2_PLACEHOLDER:` comments. The audit workflow (see `completeness-checklist.md`) checks which keys are active (uncommented) vs. placeholder (commented or containing `[LEVEL` / placeholder values).
+
+### Frontmatter vs. body contract
+
+| Aspect | Frontmatter (YAML) | Body (Markdown) |
+|--------|-------------------|-----------------|
+| Token values | **SSOT** — parse here | Descriptive prose referencing tokens |
+| Color hex values | All active tokens here | Explanation of scale intent, usage rules |
+| Typography specs | Exact CSS properties | Role descriptions, intent encoding |
+| Spacing scale | Exact pixel values | Rhythm rules, usage patterns |
+| Component tokens | Variants with references | State rules, size descriptions, focus patterns |
+| Elevation | N/A (body-only) | box-shadow values per element |
+| Motion | N/A (body-only) | Duration and easing tables |
+| Voice rules | N/A (body-only) | Copy conventions and examples |
+
 ## 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.
+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. Where a section has corresponding YAML frontmatter fields, the frontmatter holds the canonical values and the body provides documentation.
 
 ### 2.1 Overview
 
@@ -39,6 +163,8 @@ This is the Light theme. The Dark theme lives at `/DESIGN.dark.md`.
 
 **Purpose:** Define every color used in the UI, organized into scales.
 
+**SSOT:** All concrete color values live in the frontmatter `colors:` map. The body prose below explains scale conventions and usage intent.
+
 **Conventions:**
 - Each color scale has 10 steps (`100`–`1000`), encoding intent:
   - `100`: default background
@@ -52,44 +178,34 @@ This is the Light theme. The Dark theme lives at `/DESIGN.dark.md`.
   - `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
+- **Alpha scales** (`gray-alpha-*`): translucent overlays, borders, dividers — layer over any background; use `#rrggbbaa` hex-with-alpha or `rgba()` notation
 - **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()`.
+**Values:** sRGB hex (`#ffffff`), optionally with wide-gamut equivalents in `oklch()` as `*-p3` suffix keys.
 
-**Example:**
+**Example frontmatter:**
 
+```yaml
+colors:
+  background-100: "#ffffff"
+  background-200: "#f5f5f5"
+  gray-100: "#f5f5f5"
+  gray-700: "#333333"
+  gray-1000: "#111111"
+  blue-700: "#0066ff"
+  red-700: "#e60000"
 ```
-## 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.
+**Level relevance:** Level 1+ requires at least background, text (gray-900/1000), and one accent (blue-700, red-700, amber-700) active in frontmatter. Level 2+ requires all color scales uncommented and filled.
 
 ### 2.3 Typography
 
 **Purpose:** Define font families, sizes, weights, line heights, and letter spacing for every text role.
 
+**SSOT:** All concrete typography values live in the frontmatter `typography:` map. The body prose explains role semantics and usage intent.
+
 **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
@@ -100,61 +216,63 @@ This is the Light theme. The Dark theme lives at `/DESIGN.dark.md`.
 - 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 |
+**Example frontmatter (minimal):**
+
+```yaml
+typography:
+  heading-32:
+    fontFamily: Inter
+    fontSize: 32px
+    fontWeight: 600
+    lineHeight: 1.2
+    letterSpacing: -0.02em
+  copy-16:
+    fontFamily: Inter
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 1.6
+    letterSpacing: 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.
+**Level relevance:** Level 1+ requires at least one copy and one heading token active in frontmatter. Level 2+ requires heading, label, copy, and button typography tokens.
 
 ### 2.4 Spacing & Layout
 
 **Purpose:** Define the spatial grid and responsive breakpoints.
 
+**SSOT:** Spacing scale values live in the frontmatter `spacing:` map. Border radius values live in `rounded:`. Breakpoints are documented in the body.
+
 **Conventions:**
-- Base unit: 4px or 8px (consistent across the system)
+- Base unit: 4px or 8px (declared as `spacing.base` in frontmatter)
 - 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 |
+**Example frontmatter:**
+
+```yaml
+spacing:
+  base: 4px
+  1: 4px
+  2: 8px
+  3: 12px
+  4: 16px
+  6: 24px
+  8: 32px
+  10: 40px
+  16: 64px
+  24: 96px
+
+rounded:
+  sm: 6px
+  md: 12px
+  lg: 16px
+  full: 9999px
 ```
 
-**Level relevance:** Level 1+ requires spacing scale and at least 2 breakpoints.
+**Level relevance:** Level 1+ requires `spacing.base` and at least 5 scale steps in frontmatter, plus at least 2 breakpoints in body.
 
 ### 2.5 Elevation & Depth
 
@@ -238,33 +356,43 @@ Default: cubic-bezier(0.175, 0.885, 0.32, 1.1)
 
 **Purpose:** Define ready-to-use token values for common components.
 
+**SSOT:** Component variant tokens live in the frontmatter `components:` map. Values reference other frontmatter keys using `{colors.X}`, `{typography.X}`, `{rounded.X}` syntax. The body prose documents state rules (hover/active/disabled/focus) and size variants.
+
 **Conventions:**
-- Each component gets: `backgroundColor`, `textColor`, `rounded`, `height` (and `borderColor` where applicable)
-- Size variants: default (40px), small (32px), large (48px)
+- Each component variant gets: `backgroundColor`, `textColor`, `typography`, `rounded`, `height` (and `padding`, `borderColor` where applicable)
+- Size variants: default (40px), small (32px), large (48px) — override only typography/padding/height
 - 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 |
+**Example frontmatter:**
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.gray-1000}"
+    textColor: "{colors.background-100}"
+    typography: "{typography.button-14}"
+    rounded: "{rounded.sm}"
+    padding: "0 10px"
+    height: 40px
+  button-secondary:
+    backgroundColor: "{colors.background-100}"
+    textColor: "{colors.gray-1000}"
+    typography: "{typography.button-14}"
+    rounded: "{rounded.sm}"
+    padding: "0 10px"
+    height: 40px
+  input:
+    backgroundColor: "{colors.background-100}"
+    textColor: "{colors.gray-1000}"
+    typography: "{typography.label-14}"
+    rounded: "{rounded.sm}"
+    padding: "0 12px"
+    height: 40px
 ```
 
-**Level relevance:** Level 2+ requires at least Button and Input tokens. Level 3 requires full component library.
+**Level relevance:** Level 2+ requires at least Button (primary, secondary) and Input tokens in frontmatter. Level 3 requires full component library.
 
 ### 2.9 Voice & Content
 
@@ -365,14 +493,16 @@ 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.
+| Frontmatter `colors:` | CSS custom properties (`--color-gray-100`) or theme object |
+| Frontmatter `typography:` | CSS classes or Tailwind prose config |
+| Frontmatter `spacing:` | CSS custom properties or Tailwind spacing config |
+| Frontmatter `rounded:` | CSS custom properties or Tailwind radius config |
+| Body breakpoints | CSS media queries or Tailwind screens |
+| Frontmatter `components:` | Component prop defaults or CSS classes |
+| Body elevation | `box-shadow` or Tailwind shadow config |
+| Body motion | `transition` or animation library config |
+| Body voice rules | Linter rules or prompt context for copy generation |
+
+**Frontmatter references** in `components:` (e.g., `"{colors.gray-1000}"`) MUST be resolved by tracing the `{path}` back to the frontmatter key. For example, `"{colors.gray-1000}"` → `colors.gray-1000` → `"#171717"`.
+
+The agent consuming DESIGN.md is responsible for frontmatter parsing and reference resolution, not DESIGN.md itself. DESIGN.md stays implementation-agnostic.

package/harness-skills/mstar-design-md/references/vercel-example.md

@@ -9,10 +9,71 @@ This is Vercel's Geist design system as published at `vercel.com/design.md`, pre
 - It defines a complete Level 3 design system covering all sections
 - The token naming conventions (100-1000 step scale with intent encoding) are widely adopted
 - Light/Dark dual-theme pattern shows how to split same-name tokens across two files
+- The YAML frontmatter + Markdown body split is the standard DESIGN.md file structure
 
 ---
 
-# Geist
+## YAML Frontmatter: Structured Token Store
+
+Vercel Geist DESIGN.md uses a YAML frontmatter block (`---` ... `---`) as the **single source of truth for token values**. The Markdown body below is human-readable documentation. Every DESIGN.md file must follow this pattern.
+
+### Frontmatter structure
+
+```yaml
+---
+version: 0.1.0
+name: Geist
+description: Vercel's Geist design system, Light theme.
+colors:
+  background-100: "#ffffff"
+  gray-1000: "#171717"
+  blue-700: "#006bff"
+  # … all color tokens as flat map …
+typography:
+  copy-16:
+    fontFamily: Geist Sans
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 1.6
+    letterSpacing: 0
+  # … all typography tokens with 5 properties each …
+spacing:
+  base: 4px
+  1: 4px
+  2: 8px
+  # … full scale …
+rounded:
+  sm: 6px
+  md: 12px
+  lg: 16px
+  full: 9999px
+components:
+  button-primary:
+    backgroundColor: "{colors.gray-1000}"
+    textColor: "{colors.background-100}"
+    typography: "{typography.button-14}"
+    rounded: "{rounded.sm}"
+    padding: "0 10px"
+    height: 40px
+  # … all component variants referencing other frontmatter keys …
+---
+```
+
+> **Design note:** The frontmatter-body split is fundamental to the DESIGN.md format. The frontmatter is structured, parseable data; the body is prose documentation. This is the same pattern used by Jekyll, Hugo, and many static site generators — it's well-understood by tooling and agents. The `{colors.X}` reference syntax in components enables single-point-of-change: update `colors.gray-1000` in one place and all components that reference it automatically follow.
+
+### Key design decisions in the frontmatter
+
+1. **Flat color map, not nested by family** — `gray-100: "#…"` not `gray: {100: "#…"}`. This allows flat lookups and avoids deep nesting.
+2. **10-step color scale encodes intent** — `400 = border`, `700 = solid fill`, `1000 = primary text`. Agent reads the step number and knows the role.
+3. **All 5 typography properties per token** — no defaults assumed; every token is self-contained.
+4. **Reference syntax for components** — `"{colors.gray-1000}"` keeps components declarative and avoids value duplication.
+5. **Full frontmatter even for dark theme** — `design.dark.md` has the exact same frontmatter keys with different values.
+
+---
+
+## Markdown Body (documentation)
+
+Below the frontmatter, the body provides human/agent-readable documentation:
 
 ## Overview
 
@@ -130,9 +191,10 @@ Copy is part of the design; keep it precise and free of filler.
 
 ## Key takeaways for creating your own DESIGN.md
 
-1. **Encode intent in token names**, not just values — `gray-400 = border`, `copy-14 = body text`
-2. **State rules, not just values** — "three-step spacing rhythm" is more useful than a raw scale
-3. **Give negative examples** — agents need to know what NOT to do as much as what to do
-4. **Make state derivable** — "100 → 200 → 300 on hover" means the agent can compute any component's state
-5. **Tie tokens to concrete UI elements** — "card shadow", not "level-1 shadow"
-6. **Voice rules should be mechanical** — fill-in-the-blank templates, not vague principles
+1. **Use YAML frontmatter as the token SSOT** — structured colors, typography, spacing, rounded, and components in parseable form; the body is documentation
+2. **Encode intent in token names**, not just values — `gray-400 = border`, `copy-14 = body text`
+3. **State rules, not just values** — "three-step spacing rhythm" is more useful than a raw scale
+4. **Give negative examples** — agents need to know what NOT to do as much as what to do
+5. **Make state derivable** — "100 → 200 → 300 on hover" means the agent can compute any component's state
+6. **Tie tokens to concrete UI elements** — "card shadow", not "level-1 shadow"
+7. **Voice rules should be mechanical** — fill-in-the-blank templates, not vague principles