@mstar-harness/opencode 0.6.13 → 0.6.14

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

@@ -0,0 +1,138 @@
+# Vercel Geist DESIGN.md — Annotated Reference
+
+This is Vercel's Geist design system as published at `vercel.com/design.md`, presented as a reference for creating new DESIGN.md files. Annotations are inline as `> **Design note:**` blockquotes explaining the rationale behind key decisions.
+
+**Source:** <https://vercel.com/design.md>
+
+**Why this as reference:**
+- Vercel's DESIGN.md is the canonical example of the `DESIGN.md` format in the `awesome-design-md` ecosystem
+- 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
+
+---
+
+# Geist
+
+## Overview
+
+Geist is Vercel's design system for building consistent, developer-focused interfaces. The aesthetic is minimal and high-contrast: plenty of whitespace, restrained color, and content set on near-neutral surfaces. Prioritize readability and accessibility, and use color to signal state or hierarchy rather than decoration.
+
+This is the Light theme. The Dark theme uses the same token names with different values and lives at `/design.dark.md`. Colors are sRGB hex with Display P3 equivalents.
+
+> **Design note:** The Overview does two things well: (1) it states the aesthetic in terms an agent can operationalize ("minimal and high-contrast", "color to signal state or hierarchy rather than decoration"), and (2) it declares the multi-theme structure upfront.
+
+## Colors
+
+Each non-background scale runs 10 steps (`100`–`1000`), and the step encodes intent, not just lightness:
+
+- `100` default background
+- `200` hover background
+- `300` active background
+- `400` default border
+- `500` hover border
+- `600` active border
+- `700` solid fill, high contrast
+- `800` solid fill, hover
+- `900` secondary text and icons
+- `1000` primary text and icons
+
+`background-100` is the primary page and card surface; `background-200` is a secondary surface for subtle separation. The `gray-alpha-*` tokens are translucent, so they layer over any background; use them for borders, dividers, overlays, and hover states. Solid `gray-*` holds its contrast on any surface, so use it for text and opaque fills. Accent scales carry meaning: `blue` for success, links, and focus; `red` for errors; `amber` for warnings; plus `green`, `teal`, `purple`, and `pink`. Use the hex tokens everywhere; each accent scale also ships a `*-p3` wide-gamut value in `oklch()` for Display P3 screens. The Dark theme redefines the same names at `/design.dark.md`.
+
+> **Design note:** This is the key innovation of Vercel's approach: the 10-step scale encodes **intent**, not just a lightness gradient. An agent reading this knows that `700` means "solid fill" and `400` means "border", regardless of the actual hex value. This makes the scale **self-documenting** — an agent can apply tokens correctly without memorizing specific colors. The separation of `gray-alpha` (translucent, layers over any background) from `gray` (solid, holds contrast) is another critical design decision that prevents common UI mistakes.
+
+## Typography
+
+Geist Sans sets UI and prose; Geist Mono sets code, data, and tabular figures. Both are open-source. The `typography` tokens above carry concrete `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, and `letterSpacing`:
+
+- Headings, `heading-72` through `heading-14`, title pages and sections; `letterSpacing` tightens as the size grows.
+- Labels, `label-20` through `label-12`, carry single-line, scannable text: navigation, form labels, table headers, metadata.
+- Copy, `copy-24` through `copy-13`, set multi-line body text with a taller `lineHeight`.
+- Buttons, `button-16` through `button-12`, are medium-weight labels for buttons and compact controls.
+
+`copy-14` and `label-14` cover most text. The `-mono` tokens pair Geist Mono with the same metrics; prefer tabular figures when numbers need to align.
+
+> **Design note:** The typography system encodes **role** plus **size** in the token name (`copy-14`, `label-14`, `button-16`). An agent knows `copy-14` is body text (multi-line, taller line-height) and `label-14` is single-line scannable text — even though they share the same font size. This is the same "intent encoding" pattern as the color scales.
+
+## Layout
+
+Spacing follows a 4px scale: 4, 8, 12, 16, 24, 32, 40, 64, 96px. Keep a three-step rhythm: 8px inside a group, 16px between groups, 32–40px between sections. Cards use 24px padding, 16px when compact and 32px for hero areas. Center content in a 1200px column with side padding that grows at wider breakpoints, and make every layout work on mobile and desktop. Breakpoints are `sm` 401px, `md` 601px, `lg` 961px, `xl` 1200px, and `2xl` 1400px.
+
+> **Design note:** The "three-step rhythm" rule (8px/16px/32px) gives an agent a clear, mechanical way to decide how much space to put between elements. Without this, agents tend to use arbitrary spacing. The card padding variants (24px/16px/32px) similarly prevent inconsistent padding choices.
+
+## Elevation & Depth
+
+Hierarchy comes from tonal surfaces and borders first, so shadows stay subtle. Apply these `box-shadow` values for the light theme:
+
+- Raised cards: `0 2px 2px rgba(0, 0, 0, 0.04)`
+- Popovers and menus: `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)`
+- Modals and dialogs: `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)`
+
+Tooltips take the lightest of these. Pair each elevation with the matching radius below.
+
+> **Design note:** The hierarchy principle is stated first ("tonal surfaces and borders first, so shadows stay subtle"). This prevents agents from over-using shadows. Each elevation is tied to a specific UI element (card, popover, modal) — not an abstract level number — making it trivial for an agent to pick the right shadow.
+
+## Motion
+
+Use motion only when it clarifies a change, never for decoration. Most interactions should feel instant: a duration of `0ms` is often the snappiest and best choice, and the call is context-dependent. When motion genuinely helps, such as revealing or moving an element, keep it short and physical with the easing `cubic-bezier(0.175, 0.885, 0.32, 1.1)`: roughly 150ms for state changes, 200ms for popovers and tooltips, and 300ms for overlays and modals. Avoid long, looping, or attention-grabbing animation, and honor `prefers-reduced-motion` by dropping nonessential motion.
+
+> **Design note:** The explicit "0ms is often the best choice" is crucial — it prevents agents from defaulting to the common 300ms ease-out. The duration table maps cleanly to element types (state change → popover → modal), making it self-documenting.
+
+## Shapes
+
+Radii stay tight: 6px for everyday surfaces and controls, 12px for menus and modals, 16px for fullscreen surfaces. Reserve 9999px for pills, avatars, and circular controls. Keep one radius family per view rather than mixing rounded and sharp corners.
+
+> **Design note:** "One radius family per view" is a strong constraint that prevents inconsistent corner radius mixing — a common agent mistake.
+
+## Components
+
+The `components` tokens above give ready-to-use values per element (`backgroundColor`, `textColor`, `rounded`, `height`) drawn from this theme:
+
+- Primary button: solid `gray-1000` fill with a `background-100` label, for the single most important action on a view.
+- Secondary button: `background-100` fill with a translucent `gray-alpha-400` border.
+- Tertiary button: transparent fill with `gray-1000` text for low-emphasis actions; it tints with `gray-alpha` on hover.
+- Error button: solid `red-800` fill with white text, for destructive actions.
+- Input: `background-100` fill, translucent border, 6px radius.
+
+The variant tokens are the default medium (40px) size. Use the `button-small`/`input-small` (32px) and `button-large`/`input-large` (48px) tokens for the other sizes; large buttons step up to `button-16`. Hover and active states step up the scale: a `100` fill becomes `200` on hover and `300` on active, and borders move from `400` to `500` to `600`. Disabled uses a `gray-100` fill, `gray-700` text, and a not-allowed cursor. Focus shows a two-layer ring (`box-shadow: 0 0 0 2px #ffffff, 0 0 0 4px #006bff`): a 2px gap in the surface color, then a 2px `blue-700` ring.
+
+> **Design note:** The component tokens reference the color/typography/shape tokens defined above — there is no duplication. The state progression rule ("100 → 200 → 300 fill on hover → active") is a **systematic rule**, not a per-component value table. An agent can derive any component's hover state from this rule alone. The focus ring pattern (surface gap + accent ring) is explicitly described with box-shadow values, preventing agents from guessing focus styles.
+
+## Voice & Content
+
+Copy is part of the design; keep it precise and free of filler.
+
+- 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`), never `Confirm`, `OK`, or a bare verb.
+- Write errors as what happened plus what to do next: `Build failed. Bundle exceeds 50 MB. Reduce it or raise the limit.`
+- Toasts name the specific thing that changed, drop the trailing period, and never say `successfully`: `Project deleted`, not `Successfully deleted the project.`
+- Empty states point to the first action: `No deployments yet. Push to your Git repository to create one.`
+- Use the present participle with an ellipsis for in-progress states: `Deploying…`, `Saving…`.
+- Use numerals (`3 projects`), curly quotes, and the ellipsis character; skip `please` and marketing superlatives.
+
+> **Design note:** Voice rules are highly actionable for agents because they give negative examples ("never `Confirm`, `OK`") and positive patterns ("what happened + what to do next"). This turns copy generation from guesswork into a mechanical fill-in-the-blank exercise.
+
+## Do's and Don'ts
+
+- Use the gray scale to rank information: `1000` for primary text, `900` for secondary, `700` for disabled.
+- Keep solid accent color for state and the single most important action on a view.
+- Hold WCAG AA contrast (4.5:1 for body text).
+- Show the focus ring on every interactive element at `:focus-visible`, and never remove an outline without a visible replacement.
+- Apply the typography tokens instead of setting font size, line height, or weight by hand.
+- Don't signal state with color alone; pair it with an icon or text label.
+- Don't use `background-200` as a general fill; it is for subtle separation only.
+- Don't mix rounded and sharp corners, or more than two font weights, in one view.
+- Don't swap `gray-*` for `background-*`; they are separate scales.
+
+> **Design note:** The Do's and Don'ts section serves as a **correctness checklist** for agents. Each item is a specific, verifiable rule. Agents can self-check their UI output against this list. The "Don't" items prevent common mistakes ("don't mix rounded and sharp corners", "don't use `background-200` as a general fill").
+
+---
+
+## 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

package/harness-skills/mstar-design-md/templates/DESIGN.dark.md.template

@@ -0,0 +1,133 @@
+<!-- COMPLETENESS_LEVEL: 3 — dark theme companion to DESIGN.md -->
+
+# [Design System Name] — Dark
+
+## Overview
+
+[Design System Name] Dark is the dark theme companion to [Design System Name]. Use the same token names as DESIGN.md; only the values change. Every token defined in DESIGN.md must have a corresponding entry in this file.
+
+This file uses the same structure as DESIGN.md. When DESIGN.md is updated, update this file with the dark-equivalent values.
+
+<!-- 
+  IMPORTANT: Switch to dark mode by loading this file's values in place of DESIGN.md values.
+  Consumers reference tokens by name, not by value — the switch is transparent.
+-->
+
+## Colors
+
+### Background
+
+<!-- Dark backgrounds are dark grays instead of whites. background-100 is the primary dark surface. -->
+
+| Token | Value |
+|-------|-------|
+| background-100 | #[dark page/card surface, e.g., #111111] |
+
+<!-- LEVEL2_PLACEHOLDER: Match DESIGN.md Level 2 background tokens -->
+<!--
+| background-200 | #[slightly lighter dark surface] |
+| background-300 | #[active dark surface] |
+-->
+
+### Gray (text and fills)
+
+<!-- Dark text colors are light grays. Invert the scale: gray-1000 is light (primary text on dark), gray-100 is dark. -->
+
+| Token | Value |
+|-------|-------|
+| gray-1000 | #[primary text on dark, e.g., #eeeeee] |
+| gray-900 | #[secondary text on dark, e.g., #999999] |
+
+<!-- LEVEL2_PLACEHOLDER: Match DESIGN.md Level 2 gray scale with dark-appropriate values -->
+<!--
+| gray-100 | #[darkest fill, e.g., #1a1a1a] |
+| gray-200 | #[hover fill, e.g., #222222] |
+| gray-300 | #[active fill, e.g., #333333] |
+| gray-400 | #[border, e.g., #444444] |
+| gray-500 | #[hover border, e.g., #555555] |
+| gray-600 | #[active border, e.g., #666666] |
+| gray-700 | #[disabled text, e.g., #777777] |
+| gray-800 | #[solid hover, e.g., #888888] |
+-->
+
+<!-- LEVEL2_PLACEHOLDER: Add gray-alpha scale with white-based transparency for dark backgrounds -->
+<!--
+### Gray Alpha (translucent overlays)
+
+| Token | Value |
+|-------|-------|
+| gray-alpha-100 | rgba(255, 255, 255, 0.04) |
+| gray-alpha-200 | rgba(255, 255, 255, 0.06) |
+| gray-alpha-300 | rgba(255, 255, 255, 0.08) |
+| gray-alpha-400 | rgba(255, 255, 255, 0.12) |
+| gray-alpha-500 | rgba(255, 255, 255, 0.16) |
+| gray-alpha-600 | rgba(255, 255, 255, 0.24) |
+-->
+
+### Accent
+
+<!-- Accent colors may shift to maintain contrast on dark backgrounds. Same token names, adjusted values. -->
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| blue-700 | #[adjusted for dark, typically lighter to maintain contrast] | Interactive elements |
+| red-700 | #[adjusted for dark, typically lighter] | Errors |
+| amber-700 | #[adjusted for dark, typically lighter] | Warnings |
+
+<!-- LEVEL2_PLACEHOLDER: Match all accent scales from DESIGN.md with dark-appropriate values -->
+
+## Typography
+
+<!-- Typography tokens typically remain the same in dark mode. Copy verbatim from DESIGN.md. -->
+
+| Token | Font Family | Size | Weight | Line Height | Letter Spacing |
+|-------|------------|------|--------|-------------|----------------|
+| copy-16 | [same as DESIGN.md] | 16px | 400 | 1.6 | 0 |
+| heading-32 | [same as DESIGN.md] | 32px | 600 | 1.2 | -0.02em |
+
+## Spacing & Layout
+
+<!-- Spacing and breakpoints are identical to DESIGN.md. Copy verbatim. -->
+
+Base unit: [same as DESIGN.md]
+
+| Step | Value |
+|------|-------|
+| 1x | [base × 1] |
+| 2x | [base × 2] |
+| 3x | [base × 3] |
+| 4x | [base × 4] |
+| 6x | [base × 6] |
+
+| Name | Min Width | Target |
+|------|-----------|--------|
+| sm | 401px | Mobile landscape |
+| lg | 961px | Desktop |
+
+<!-- LEVEL3_PLACEHOLDER: Add dark-mode Elevation, Components tokens, and full dark theme parity with DESIGN.md -->
+<!--
+## Elevation & Depth
+
+Shadows on dark backgrounds use lighter, more subtle values. Hierarchy still comes from tonal surfaces first.
+
+### Shadows (dark theme)
+
+| Element | Value |
+|---------|-------|
+| Card | 0 2px 2px rgba(0, 0, 0, 0.12) |
+| Popover | 0 1px 1px rgba(0, 0, 0, 0.08), 0 4px 8px -4px rgba(0, 0, 0, 0.12), 0 16px 24px -8px rgba(0, 0, 0, 0.16) |
+| Modal | 0 1px 1px rgba(0, 0, 0, 0.08), 0 8px 16px -4px rgba(0, 0, 0, 0.12), 0 24px 32px -8px rgba(0, 0, 0, 0.16) |
+
+## Components
+
+Button tokens reference dark color values. Same structure as DESIGN.md, different color references.
+
+### Button
+
+| Variant | Background | Text | Border | Radius | Height |
+|---------|-----------|------|--------|--------|--------|
+| primary | gray-100 (dark value) | background-100 (dark value) | — | 6px | 40px |
+| secondary | background-100 | gray-1000 | gray-alpha-400 | 6px | 40px |
+
+States, sizes, and focus follow the same rules as DESIGN.md.
+-->

package/harness-skills/mstar-design-md/templates/DESIGN.md.template

@@ -0,0 +1,273 @@
+<!-- COMPLETENESS_LEVEL: 1 — last audited [DATE] -->
+
+# [Design System Name]
+
+## Overview
+
+[Design System Name] is a [adjective, e.g., minimal, playful, bold] design system for [project/product name].
+[Aesthetic principles — one sentence describing the visual identity: e.g., "Prioritize readability and clarity with plenty of whitespace and restrained color."]
+
+This is the Light theme.
+<!-- LEVEL2_PLACEHOLDER: When ready for dark theme, create DESIGN.dark.md with same token names and different values. See references/completeness-checklist.md § Level 3. -->
+<!-- Uncomment when dark theme exists: The Dark theme uses the same token names with different values and lives at /DESIGN.dark.md. -->
+
+## Colors
+
+### Background
+
+<!-- Level 1 — Fill in at least background-100. Level 2 adds background-200 and background-300. -->
+
+| Token | Value |
+|-------|-------|
+| background-100 | #[primary page/card surface] |
+
+<!-- LEVEL2_PLACEHOLDER: Add background-200 and background-300 for subtle surface separation. See references/completeness-checklist.md § Level 2/Colors. -->
+<!--
+| background-200 | #[secondary surface] |
+| background-300 | #[active surface] |
+-->
+
+### Gray (text and fills)
+
+<!-- Level 1 — Fill in at least gray-1000 (primary text) and gray-900 (secondary text). -->
+
+| Token | Value |
+|-------|-------|
+| gray-1000 | #[primary text] |
+| gray-900 | #[secondary text] |
+
+<!-- LEVEL2_PLACEHOLDER: Complete the full 10-step scale (gray-100 through gray-1000). See references/design-md-spec.md § Colors. -->
+<!--
+| gray-100 | #[lightest fill] |
+| gray-200 | #[hover fill] |
+| gray-300 | #[active fill] |
+| gray-400 | #[border] |
+| gray-500 | #[hover border] |
+| gray-600 | #[active border] |
+| gray-700 | #[solid fill / disabled text] |
+| gray-800 | #[solid hover] |
+| gray-900 | #[secondary text] |
+| gray-1000 | #[primary text] |
+-->
+
+<!-- LEVEL2_PLACEHOLDER: Add gray-alpha scale for translucent borders, overlays, and hover states. See references/design-md-spec.md § Colors. -->
+<!--
+### Gray Alpha (translucent overlays)
+
+| Token | Value |
+|-------|-------|
+| gray-alpha-100 | rgba(0, 0, 0, 0.04) |
+| gray-alpha-200 | rgba(0, 0, 0, 0.06) |
+| gray-alpha-300 | rgba(0, 0, 0, 0.08) |
+| gray-alpha-400 | rgba(0, 0, 0, 0.12) |
+| gray-alpha-500 | rgba(0, 0, 0, 0.16) |
+| gray-alpha-600 | rgba(0, 0, 0, 0.24) |
+-->
+
+### Accent
+
+<!-- Level 1 — Fill in at least one accent (blue or brand color) for links/actions, plus red for errors and amber for warnings. -->
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| blue-700 | #[links, focus, primary actions] | Interactive elements |
+| red-700 | #[errors, destructive actions] | Errors, delete buttons |
+| amber-700 | #[warnings, alerts] | Warning states |
+
+<!-- LEVEL2_PLACEHOLDER: Complete all accent scales (blue, red, amber, green, teal, purple, pink). Add at minimum 700/800/900/1000 steps per scale. See references/completeness-checklist.md § Level 2/Colors. -->
+<!--
+| green | Success states |
+| teal | Info, secondary brand |
+| purple | Special emphasis |
+| pink | Highlights, badges |
+-->
+
+## Typography
+
+<!-- Level 1 — Fill in at least one body token (copy-*) and one heading token (heading-*). -->
+<!-- Token naming: {role}-{size}. Roles: heading, label, copy, button. Size: approximate font size in px. -->
+
+### Body text
+
+| Token | Font Family | Size | Weight | Line Height | Letter Spacing |
+|-------|------------|------|--------|-------------|----------------|
+| copy-16 | [font-family] | 16px | 400 | 1.6 | 0 |
+
+### Headings
+
+| Token | Font Family | Size | Weight | Line Height | Letter Spacing |
+|-------|------------|------|--------|-------------|----------------|
+| heading-32 | [font-family] | 32px | 600 | 1.2 | -0.02em |
+
+<!-- LEVEL2_PLACEHOLDER: Complete the typography scale. Add at least 3 heading levels, 1 label token, and 1 button typography token. See references/completeness-checklist.md § Level 2/Typography. -->
+<!--
+### Labels (single-line, scannable)
+
+| Token | Font Family | Size | Weight | Line Height | Letter Spacing |
+|-------|------------|------|--------|-------------|----------------|
+| label-14 | [font-family] | 14px | 500 | 1.3 | 0 |
+
+### Buttons
+
+| Token | Font Family | Size | Weight | Line Height | Letter Spacing |
+|-------|------------|------|--------|-------------|----------------|
+| button-14 | [font-family] | 14px | 500 | 1.3 | 0 |
+
+### Additional headings
+| heading-24 | [font-family] | 24px | 600 | 1.3 | -0.01em |
+| heading-20 | [font-family] | 20px | 600 | 1.3 | 0 |
+-->
+
+## Spacing & Layout
+
+### Spacing scale
+
+<!-- Level 1 — Declare base unit and at least 5 scale steps. Base unit is typically 4px or 8px. -->
+
+Base unit: [4px or 8px]
+
+| Step | Value |
+|------|-------|
+| 1x | [base × 1] |
+| 2x | [base × 2] |
+| 3x | [base × 3] |
+| 4x | [base × 4] |
+| 6x | [base × 6] |
+
+<!-- LEVEL2_PLACEHOLDER: Complete the full 9-step scale and add three-step rhythm rules. See references/design-md-spec.md § Spacing & Layout. -->
+<!--
+| 8x | [base × 8] |
+| 10x | [base × 10] |
+| 16x | [base × 16] |
+| 24x | [base × 24] |
+
+### Rhythm
+
+- [small]: inside a group (label + input, icon + text)
+- [medium]: between related groups
+- [large]: between sections
+-->
+
+### Breakpoints
+
+<!-- Level 1 — At least 2 breakpoints for responsive layout. -->
+
+| Name | Min Width | Target |
+|------|-----------|--------|
+| sm | 401px | Mobile landscape |
+| lg | 961px | Desktop |
+
+<!-- LEVEL2_PLACEHOLDER: Add intermediate breakpoints (md, xl, 2xl). See references/completeness-checklist.md § Level 2/Breakpoints. -->
+<!--
+| md | 601px | Tablet |
+| xl | 1200px | Large desktop |
+| 2xl | 1400px | Ultra-wide |
+-->
+
+<!-- LEVEL2_PLACEHOLDER: Add Components section — at minimum Button (primary, secondary) and Input tokens with size variants and all states. See references/design-md-spec.md § Components. -->
+<!--
+## 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 |
+
+**Size variants:**
+| Size | Height | Typography |
+|------|--------|------------|
+| small | 32px | button-12 |
+| default | 40px | button-14 |
+| large | 48px | button-16 |
+
+**States:** Fill steps up: 100→200 (hover), 100→300 (active). Border steps up: 400→500→600. Disabled: gray-100 fill, gray-700 text, not-allowed cursor. Focus: 0 0 0 2px background-100, 0 0 0 4px blue-700.
+
+### Input
+
+| Variant | Background | Text | Border | Radius | Height |
+|---------|-----------|------|--------|--------|--------|
+| default | background-100 | gray-1000 | gray-alpha-400 | 6px | 40px |
+
+**Size variants:** Same as Button (32px/40px/48px).
+
+**States:** Same state progression as Button. Error: border red-700, add error message below.
+-->
+
+<!-- LEVEL3_PLACEHOLDER: Add Elevation & Depth, Motion, Shapes, Voice & Content, and full Component library. See references/completeness-checklist.md § Level 3. -->
+<!--
+## Elevation & Depth
+
+Hierarchy comes from tonal surfaces and borders first; shadows stay subtle.
+
+### Shadows (light theme)
+
+| Element | 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) |
+
+Pair each elevation with the matching radius below.
+
+## Motion
+
+Motion clarifies change, never decorates. Default 0ms is often the best choice.
+
+### Easing
+
+Default: cubic-bezier(0.175, 0.885, 0.32, 1.1)
+
+### Durations
+
+| Context | Duration |
+|---------|----------|
+| State change | 150ms |
+| Popover/Tooltip | 200ms |
+| Modal/Overlay | 300ms |
+
+Honor prefers-reduced-motion: drop nonessential motion.
+
+## Shapes
+
+### Border Radius
+
+| Context | Value |
+|---------|-------|
+| Surface, Input, Button | 6px |
+| Menu, Modal, Popover | 12px |
+| Fullscreen | 16px |
+| Pill, Avatar | 9999px |
+
+Keep one radius family per view; never mix rounded and sharp corners.
+
+## Components — Extended
+
+Add Card, Modal, Tooltip, Menu/Dropdown, Badge tokens following the same pattern as Button/Input.
+
+## 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: [Create Project], [Delete Item]
+- Write errors as what happened + what to do: [Error description. Suggested fix.]
+- Toasts name the specific thing, no trailing period, no "successfully": [Item deleted]
+- Empty states point to the first action: [No items yet. Create one to get started.]
+- In-progress states: present participle + ellipsis: [Saving…], [Loading…]
+- Use numerals, curly quotes, the ellipsis character
+- Skip "please" and marketing superlatives
+-->
+
+## Do's and Don'ts
+
+<!-- Fill in with rules specific to this design system. Examples to customize: -->
+
+- Use [gray-1000] for primary text, [gray-900] for secondary.
+- Keep accent color for state and the single most important action on a view.
+- Hold WCAG AA contrast (4.5:1 for body text).
+- Show focus ring on every interactive element at :focus-visible.
+- Apply typography tokens instead of setting font properties by hand.
+- Don't signal state with color alone; pair it with an icon or text label.
+- Don't use more than two font weights in one view.
+- Don't mix rounded and sharp corners in one view.

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

@@ -31,8 +31,8 @@ description: Morning Star (启明星) harness **强制全局入口** —— 信
 | 角色 | 始终 | 按任务追加（典型） |
 |------|------|-------------------|
 | **全部** | 本 skill | — |
-| **`@project-manager`** | 本 skill | `mstar-dispatch-gates`、`mstar-phase-gates`、`mstar-plan-conventions`、`mstar-superpowers-align`、`mstar-roles`；派 QC 前 `mstar-review-qc`；并行/审查 `mstar-branch-worktree`；plan/status/reports `mstar-plan-artifacts`。**不**读 `mstar-coding-behavior` |
-| **实现/审查/QA/运维** | 本 skill + `mstar-coding-behavior` + 角色 ref | 有 git 写：`mstar-branch-worktree`；有 plan 路径：`mstar-plan-conventions`（路径符号节）；QC/QA：`mstar-review-qc`；改 status/residual：`mstar-plan-artifacts` |
+| **`@project-manager`** | 本 skill | `mstar-dispatch-gates`、`mstar-phase-gates`、`mstar-plan-conventions`、`mstar-superpowers-align`、`mstar-roles`；派 QC 前 `mstar-review-qc`；并行/审查 `mstar-branch-worktree`；plan/status/reports `mstar-plan-artifacts`；UI 类 plan Prepare 阶段 `mstar-design-md`（DESIGN.md 门禁）。**不**读 `mstar-coding-behavior` |
+| **实现/审查/QA/运维** | 本 skill + `mstar-coding-behavior` + 角色 ref | 有 git 写：`mstar-branch-worktree`；有 plan 路径：`mstar-plan-conventions`（路径符号节）；QC/QA：`mstar-review-qc`；改 status/residual：`mstar-plan-artifacts`；UI 任务：`mstar-design-md`（读取 DESIGN.md tokens） |
 | **leaf 承接方** | 上栏 + **`mstar-dispatch-gates`**（反递归节） | — |
 
 Routing eval（Cursor 维护）→ `.cursor/skills/mstar-routing-eval/`，**非**运行时必读。
@@ -83,6 +83,7 @@ PM 在 Assignment 写 **`Task category`**（主类 + 可选 `secondary`）：
 | `mstar-branch-worktree` | 功能分支、worktree、QC/QA 检出对齐 |
 | `mstar-plan-conventions` | `{HARNESS_DIR}` 发现、初始化、Spec 分支模型摘要 |
 | `mstar-plan-artifacts` | 主 plan、reports、`status.json`、residual、knowledge、Done 归档 |
+| `mstar-design-md` | DESIGN.md 设计系统规范 —— 创建/审计/维护 design tokens，三级检查清单，light/dark 双主题 |
 | `mstar-review-qc` | QC 工作流、模板、verdict、residual 留档 |
 | `mstar-coding-behavior` | Think / Simplicity / Surgical / Goal-Driven |
 | `mstar-superpowers-align` | Superpowers × harness 优先级与短语 |

package/harness-skills/mstar-phase-gates/SKILL.md

@@ -111,11 +111,12 @@ description: Morning Star (启明星) Spec-Driven 双阶段门禁 —— Prepare
 2. `clarify` 是否完成（高影响歧义是否收敛）？
 3. 意图门禁是否满足（真实目标 / 成功判据 / 非目标已写明）？
 4. `plan` 是否完成并可引用？
-5. 若分批/暂缓/临时绕行，roadmap 是否落在 plan/status 中，而不是只在对话里？
-6. `tasks` 是否完成？
-7. Assignment 是否含 **`Task category`**（实现类任务）并与 Owner 一致？
-8. 若中途出现 plan drift，是否先回写再继续？
-9. 实现说明中是否体现"最小耐久切片 + 手术式改动 + 可验证检查"？
+5. 若 plan 涉及 UI 工作：`DESIGN.md` 是否存在且满足声明的 completeness level（见 `mstar-design-md`）？
+6. 若分批/暂缓/临时绕行，roadmap 是否落在 plan/status 中，而不是只在对话里？
+7. `tasks` 是否完成？
+8. Assignment 是否含 **`Task category`**（实现类任务）并与 Owner 一致？
+9. 若中途出现 plan drift，是否先回写再继续？
+10. 实现说明中是否体现"最小耐久切片 + 手术式改动 + 可验证检查"？
 
 任一项为「否」时，`Gate decision` 必须是 `blocked`。
 

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

@@ -45,6 +45,7 @@ Treat these as baseline dependencies **where the role touches implementation, re
 | `mstar-branch-worktree` | Git write, parallel worktrees, QC/QA checkout fields |
 | `mstar-plan-conventions` | `{HARNESS_DIR}` discovery, init, Spec branch naming, `writing-plans` path |
 | `mstar-plan-artifacts` | Main plan, `reports/`, `status.json`, residual, knowledge/iteration, Done compaction |
+| `mstar-design-md` | DESIGN.md design system spec — create/audit/maintain tokens, completeness checklist, light/dark dual-theme |
 | `mstar-review-qc` | QC workflow, template, verdict, high-risk checks |
 | `mstar-coding-behavior` | Implementation/debug/refactor (**not** PM orchestration-only) |
 | `mstar-superpowers-align` | Superpowers plugin on; Assignment `Superpowers` lines |
@@ -55,10 +56,10 @@ Treat these as baseline dependencies **where the role touches implementation, re
 | Role | Typical adds |
 | --- | --- |
 | `project-manager` | `mstar-dispatch-gates`, `mstar-phase-gates`, `mstar-plan-conventions`, `mstar-superpowers-align`, `mstar-roles` ref; + `mstar-review-qc` before QC; + `mstar-branch-worktree` / `mstar-plan-artifacts` as the round requires |
-| `fullstack-dev*`, `frontend-dev` | `mstar-coding-behavior`, `mstar-dispatch-gates`, `mstar-branch-worktree` (if repo writes); plan path symbols from `mstar-plan-conventions` (minimal) |
-| `qc-specialist*` | `mstar-review-qc`, `mstar-branch-worktree`, `mstar-plan-artifacts` (report paths) |
-| `qa-engineer` | `mstar-review-qc`, `mstar-branch-worktree`, `mstar-plan-artifacts` (closing R#) |
-| `architect`, `product-manager` | `mstar-phase-gates` (Prepare), `mstar-plan-artifacts` (knowledge/specs) |
+| `fullstack-dev*`, `frontend-dev` | `mstar-coding-behavior`, `mstar-dispatch-gates`, `mstar-branch-worktree` (if repo writes); plan path symbols from `mstar-plan-conventions` (minimal); `mstar-design-md` when implementing styled UI |
+| `qc-specialist*` | `mstar-review-qc`, `mstar-branch-worktree`, `mstar-plan-artifacts` (report paths); `mstar-design-md` when reviewing UI |
+| `qa-engineer` | `mstar-review-qc`, `mstar-branch-worktree`, `mstar-plan-artifacts` (closing R#); `mstar-design-md` when verifying visual output |
+| `architect`, `product-manager` | `mstar-phase-gates` (Prepare), `mstar-plan-artifacts` (knowledge/specs); `mstar-design-md` (creator + design intent) |
 | `ops-engineer` | `mstar-coding-behavior`, `mstar-branch-worktree` |
 | `prompt-engineer` | All topic skills when editing harness text |
 

package/harness-skills/mstar-roles/references/architect.md

@@ -4,7 +4,7 @@
 
 **Always:** `mstar-harness-core`, `mstar-dispatch-gates`, `mstar-phase-gates` (Prepare: specify/clarify/plan), `mstar-plan-conventions` (`{PLAN_DIR}`, `writing-plans` path).
 
-**Typically:** `mstar-plan-artifacts` (knowledge/specs/ADR placement); `mstar-coding-behavior` (surgical doc edits); `mstar-superpowers-align` (when plugin on).
+**Typically:** `mstar-plan-artifacts` (knowledge/specs/ADR placement); `mstar-design-md` (DESIGN.md design system spec — architect is primary creator); `mstar-coding-behavior` (surgical doc edits); `mstar-superpowers-align` (when plugin on).
 
 **On demand:** `mstar-branch-worktree` (when committing architecture docs to the business repo).
 
@@ -52,7 +52,8 @@ Use as applicable:
 2. Module boundaries and interface contracts
 3. Technical decision records (ADR-style)
 4. Risk/rollback strategy and validation plan
-5. Architecture-spec documentation in repository paths assigned by PM
+5. DESIGN.md creation and maintenance — design token selection, naming, completeness level decisions (see `mstar-design-md`)
+6. Architecture-spec documentation in repository paths assigned by PM
 
 ## Scope Boundaries
 

package/harness-skills/mstar-roles/references/frontend-dev.md

@@ -6,7 +6,7 @@
 
 **Typically:** `mstar-plan-conventions` (paths + spec metadata); `mstar-superpowers-align` (when plugin on).
 
-**On demand:** `mstar-branch-worktree` (repo writes); `mstar-phase-gates` (Execute / hotfix when referenced in assignment).
+**On demand:** `mstar-branch-worktree` (repo writes); `mstar-phase-gates` (Execute / hotfix when referenced in assignment); `mstar-design-md` (when implementing styled UI — read DESIGN.md for tokens before writing components).
 
 **Host:** `mstar-host` (detect; `references/opencode.md` | `cursor.md` | `codex.md`).
 
@@ -35,7 +35,7 @@ If any item below matches, **stop** and return `Blocked` to `project-manager` in
 ## Core Responsibilities
 
 1. Implement pages/components/interactions with maintainable frontend architecture
-2. Maintain component consistency and design-system alignment
+2. Maintain component consistency and DESIGN.md alignment — read design tokens before writing styled components
 3. Ensure accessibility and frontend performance quality
 4. Add or update frontend tests where assigned
 

package/harness-skills/mstar-roles/references/fullstack-dev-shared.md

@@ -16,7 +16,7 @@ Behavior is shared; track identity is parameterized.
 
 **Typically:** `mstar-plan-conventions` (path symbols + `metadata.primary_spec` / `spec_refs`); `mstar-superpowers-align` (when plugin on).
 
-**On demand:** `mstar-branch-worktree` (repo writes, `Working branch`); `mstar-phase-gates` (Execute / hotfix sections when gate fields are in the assignment).
+**On demand:** `mstar-branch-worktree` (repo writes, `Working branch`); `mstar-phase-gates` (Execute / hotfix sections when gate fields are in the assignment); `mstar-design-md` (when task includes UI implementation — read DESIGN.md for design tokens).
 
 **Host:** `mstar-host` (detect; `references/opencode.md` | `cursor.md` | `codex.md`).