@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/gemini-cli/harness-design-mobile/SKILL.md

@@ -0,0 +1,336 @@
+# Harness Design Mobile
+
+> Token-bound mobile component generation. Scaffold from design tokens and aesthetic intent, implement with React Native, SwiftUI, Flutter, or Compose patterns following platform-specific design rules, and verify every value references the token set with native convention compliance.
+
+## When to Use
+
+- Generating new mobile components that must conform to the project's design system tokens
+- When `on_new_feature` triggers fire with mobile UI scope requiring token-bound component generation
+- When `on_commit` triggers fire and new mobile components contain hardcoded design values that should reference tokens
+- Implementing design intent from `design-system/DESIGN.md` into platform-native styling (StyleSheet, SwiftUI modifiers, Flutter ThemeData, Compose MaterialTheme)
+- Ensuring components follow platform-specific guidelines (iOS Human Interface Guidelines, Material Design 3, Flutter design patterns)
+- NOT for generating design tokens themselves (use harness-design-system)
+- NOT for establishing aesthetic direction or anti-patterns (use harness-design)
+- NOT for accessibility auditing (use harness-accessibility)
+- NOT for web platform components (use harness-design-web)
+
+## Process
+
+### Phase 1: SCAFFOLD — Read Tokens, Detect Platform, Plan Structure
+
+1. **Read design tokens.** Load `design-system/tokens.json` (W3C DTCG format). Extract:
+   - Color tokens: primary, secondary, accent, neutral ramps, semantic colors
+   - Typography tokens: heading and body font families, font weights, font sizes, line heights
+   - Spacing tokens: spacing scale values
+   - If `design-system/tokens.json` does not exist, stop and instruct the user to run `harness-design-system` first.
+
+2. **Read design intent.** Load `design-system/DESIGN.md` for:
+   - Aesthetic direction (style, tone, differentiator)
+   - Anti-patterns to avoid
+   - Platform-specific mobile notes (touch targets, native component usage, platform conventions)
+   - If `design-system/DESIGN.md` does not exist, warn the user and proceed with tokens only.
+
+3. **Check harness configuration.** Read `harness.config.json` for:
+   - `design.strictness` — enforcement level. Default to `standard`.
+   - `design.platforms` — confirm `mobile` is in the platforms list.
+
+4. **Detect mobile platform.** Scan the project for:
+   - **React Native:** `package.json` contains `react-native` or `expo`, `.tsx` files with `StyleSheet` or `react-native` imports
+   - **SwiftUI:** `.swift` files with `import SwiftUI`, `Package.swift` or `.xcodeproj` exists
+   - **Flutter:** `pubspec.yaml` exists, `.dart` files with `import 'package:flutter/`
+   - **Compose:** `build.gradle.kts` with `compose` dependencies, `.kt` files with `@Composable`
+   - If the user specified `--platform`, use that override.
+
+5. **Load platform-specific rules.** Based on detected platform, read platform design guidelines from `agents/skills/shared/design-knowledge/platform-rules/`:
+   - **iOS (SwiftUI/React Native on iOS):** Read `ios.yaml` — Human Interface Guidelines, safe area insets, navigation bar patterns, tab bar conventions, dynamic type support, SF Symbols integration
+   - **Android (Compose/React Native on Android):** Read `android.yaml` — Material Design 3, elevation system, shape system, dynamic color, navigation patterns, edge-to-edge layout
+   - **Flutter:** Read `flutter.yaml` — Flutter design patterns, ThemeData structure, widget composition, adaptive layouts, platform channel considerations
+   - **React Native cross-platform:** Read both `ios.yaml` and `android.yaml` — platform-specific overrides via `Platform.select`, safe area handling, navigation library patterns
+
+6. **Load anti-pattern definitions.** Read anti-pattern files from `agents/skills/shared/design-knowledge/anti-patterns/`:
+   - `typography.yaml` — typographic anti-patterns (too many fonts, inconsistent scales)
+   - `color.yaml` — color anti-patterns (hardcoded hex, insufficient contrast)
+   - `layout.yaml` — layout anti-patterns (magic numbers, inconsistent spacing)
+   - `motion.yaml` — motion anti-patterns (excessive animation, missing reduced-motion)
+
+7. **Build token-to-platform mapping.** Create a lookup table mapping tokens to platform-native representations:
+   - **React Native:** `color.primary.500` maps to `StyleSheet` value or themed constant
+   - **SwiftUI:** `color.primary.500` maps to `Color("primary500")` in asset catalog or `Color(hex:)` extension
+   - **Flutter:** `color.primary.500` maps to `Theme.of(context).colorScheme.primary` or custom `AppColors.primary500`
+   - **Compose:** `color.primary.500` maps to `MaterialTheme.colorScheme.primary` or custom `AppTheme.colors.primary500`
+
+8. **Plan component structure.** Define:
+   - Component file path(s) following platform conventions
+   - Props/parameters interface
+   - Which tokens will be consumed
+   - Platform-specific considerations (safe areas, touch targets, dynamic type)
+   - Present plan to user before proceeding.
+
+### Phase 2: IMPLEMENT — Generate Token-Bound Mobile Components
+
+1. **Generate platform-specific component code.** Based on detected platform:
+
+   **React Native (TypeScript):**
+   - Functional component with TypeScript props interface
+   - All colors via themed StyleSheet or token constants (no hardcoded hex values)
+   - Typography via scaled text styles referencing token font families and sizes
+   - Spacing via token-derived constants in StyleSheet
+   - Platform-specific overrides via `Platform.select` where iOS and Android differ
+   - Safe area handling via `useSafeAreaInsets` for edge-to-edge content
+
+   **SwiftUI:**
+   - View struct with typed properties
+   - Colors from asset catalog or Color extension referencing tokens
+   - Typography via custom `Font` extensions mapping to token values
+   - Spacing via token-derived constants
+   - Dynamic Type support via `.font(.body)` or custom scaled fonts
+   - Safe area respect via `.safeAreaInset` modifiers
+   - iOS Human Interface Guidelines compliance (44pt minimum touch targets)
+
+   **Flutter (Dart):**
+   - StatelessWidget or StatefulWidget with typed constructor parameters
+   - Colors via `Theme.of(context)` or custom `AppColors` class referencing tokens
+   - Typography via `Theme.of(context).textTheme` or custom `AppTypography`
+   - Spacing via token-derived constants class
+   - Material Design 3 compliance (elevation, shape, dynamic color)
+   - Adaptive layout via `LayoutBuilder` or `MediaQuery` for responsive behavior
+
+   **Compose (Kotlin):**
+   - `@Composable` function with typed parameters
+   - Colors via `MaterialTheme.colorScheme` or custom theme referencing tokens
+   - Typography via `MaterialTheme.typography` or custom type scale
+   - Spacing via token-derived `Dp` constants
+   - Material Design 3 compliance (Surface, ElevatedCard, shape system)
+   - Modifier chains for layout following Compose conventions
+
+2. **Apply platform-specific rules:**
+   - **Touch targets:** Minimum 44x44pt (iOS) or 48x48dp (Android/Material)
+   - **Safe areas:** All platforms handle notch/status bar/navigation bar correctly
+   - **Typography scaling:** Support dynamic type (iOS), font scale (Android), and text scale factor (Flutter)
+   - **Elevation/shadows:** Platform-appropriate (iOS shadow, Material elevation, Flutter elevation)
+   - **Navigation patterns:** Platform-native navigation (UINavigationController, NavHost, Navigator)
+
+3. **Add USES_TOKEN annotations.** Insert platform-appropriate comments documenting token consumption:
+   ```
+   // @design-token color.primary.500 — primary action background
+   // @design-token typography.heading.fontFamily — section heading
+   // @design-token spacing.md — card internal padding
+   ```
+
+### Phase 3: VERIFY — Check Token Binding and Platform Compliance
+
+1. **Scan for hardcoded values.** Search generated files for:
+   - Hardcoded color values: hex codes, `UIColor(red:green:blue:)`, `Color(0xFF...)`, `Color(red:green:blue:)`
+   - Hardcoded font families: string literals for font names not referencing tokens
+   - Hardcoded spacing: raw numeric values in padding/margin not from the token scale
+
+2. **Verify token coverage.** For every design value in generated components:
+   - Confirm it resolves to a token in `design-system/tokens.json`
+   - Confirm the token path is valid
+   - Report orphan references
+
+3. **Check platform guideline compliance:**
+   - **iOS:** Touch targets >= 44pt, safe area respected, dynamic type supported
+   - **Android/Material:** Touch targets >= 48dp, edge-to-edge layout, Material 3 components used
+   - **Flutter:** ThemeData used consistently, no hardcoded Material values
+   - **React Native:** Platform.select used for iOS/Android differences, safe area handled
+
+4. **Check anti-pattern compliance.** Cross-reference against `design-system/DESIGN.md` anti-patterns and definitions in `agents/skills/shared/design-knowledge/anti-patterns/`.
+
+5. **Query the knowledge graph.** If available at `.harness/graph/`:
+   - Verify `DesignToken` nodes exist for all referenced tokens
+   - Verify `PLATFORM_BINDING` edges exist for the target mobile platform
+   - Check `VIOLATES_DESIGN` edges via `DesignConstraintAdapter`
+
+6. **Assign severity based on `designStrictness`:**
+   - `permissive` — all findings are `info`
+   - `standard` — hardcoded values are `warn`, platform guideline violations are `warn`, accessibility violations are `error`
+   - `strict` — hardcoded values are `error` (blocks), platform violations are `warn`, accessibility violations are `error`
+
+7. **Report verification results:**
+
+   ```
+   MOBILE-001 [warn] Hardcoded color Color(0xFF3B82F6) — should reference token
+     File: lib/widgets/action_button.dart:15
+     Fix: Use Theme.of(context).colorScheme.primary or AppColors.primary500
+
+   MOBILE-002 [warn] Touch target 32dp below minimum 48dp (Material Design 3)
+     File: lib/widgets/icon_action.dart:22
+     Fix: Set minimumSize to Size(48, 48) in ButtonStyle
+
+   MOBILE-003 [info] Missing dynamic type support
+     File: Sources/Views/ProductCard.swift:18
+     Fix: Use .font(.body) instead of .font(.system(size: 16))
+   ```
+
+8. **Run `harness validate`.** Confirm new components integrate cleanly.
+
+## Harness Integration
+
+- **`harness validate`** — Run after generating components to verify project health.
+- **`harness scan`** — Run after component generation to update the knowledge graph with `USES_TOKEN` and `PLATFORM_BINDING` edges.
+- **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) — Verifies `DesignToken` nodes exist for all tokens referenced by generated components.
+- **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) — Checks for `VIOLATES_DESIGN` edges during VERIFY phase. Reports constraint violations at configured strictness.
+- **`harness-design-system`** — Dependency. Provides `design-system/tokens.json`. If tokens do not exist, instruct user to run harness-design-system first.
+- **`harness-design`** — Dependency. Provides `design-system/DESIGN.md` with aesthetic intent and anti-patterns.
+- **`harness-impact-analysis`** — Traces token changes to affected mobile components via `USES_TOKEN` edges.
+
+**Graph naming convention:** This skill uses PascalCase for node types (`DesignToken`, `DesignConstraint`) and UPPER_SNAKE for edge types (`USES_TOKEN`, `PLATFORM_BINDING`, `VIOLATES_DESIGN`) as conceptual labels. The graph schema registers these as snake_case identifiers (`design_token`, `design_constraint`, `uses_token`, `platform_binding`, `violates_design`). The adapter classes (`DesignIngestor`, `DesignConstraintAdapter`) handle the mapping — always use the adapters rather than constructing graph queries with raw type names.
+
+## Success Criteria
+
+- Generated mobile components reference design tokens exclusively — no hardcoded color, font, or spacing values
+- Platform detection correctly identifies React Native, SwiftUI, Flutter, or Compose projects
+- Token-to-platform mapping produces correct output for each mobile platform
+- Platform-specific rules are enforced (touch targets, safe areas, dynamic type, Material 3 compliance)
+- `@design-token` annotations are present for every consumed token
+- Anti-pattern compliance check catches violations from `design-system/DESIGN.md`
+- Verification report uses severity levels matching `design.strictness` configuration
+- `harness validate` passes after component generation
+
+## Examples
+
+### Example: React Native Card Component
+
+**Context:** Fitness app. React Native with Expo. Tokens from harness-design-system. Design intent: expressive, warm tone.
+
+**SCAFFOLD output:**
+
+```
+Platform detected:  React Native (Expo)
+Tokens loaded:      38 tokens from design-system/tokens.json
+Design intent:      Expressive, warm (from DESIGN.md)
+Component plan:     WorkoutCard with progress indicator
+Token consumption:  color.primary.*, color.accent.*, typography.heading, spacing.md/lg
+Platform rules:     iOS 44pt touch targets, Android 48dp touch targets, safe area insets
+```
+
+**IMPLEMENT output (WorkoutCard.tsx):**
+
+```tsx
+// @design-token color.primary.500 — card accent
+// @design-token color.neutral.50 — card background
+// @design-token color.neutral.900 — primary text
+// @design-token typography.heading.fontFamily — workout title
+// @design-token typography.body.fontFamily — workout details
+// @design-token spacing.md — card padding
+// @design-token spacing.sm — content gap
+
+import { View, Text, StyleSheet, Platform } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { tokens } from '@/theme/tokens';
+
+interface WorkoutCardProps {
+  title: string;
+  duration: string;
+  progress: number;
+}
+
+export function WorkoutCard({ title, duration, progress }: WorkoutCardProps) {
+  return (
+    <View style={styles.card}>
+      <Text style={styles.title}>{title}</Text>
+      <Text style={styles.detail}>{duration}</Text>
+      <View style={styles.progressTrack}>
+        <View style={[styles.progressFill, { width: `${progress}%` }]} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: {
+    backgroundColor: tokens.color.neutral[50],
+    borderRadius: tokens.radius.md,
+    padding: tokens.spacing.md,
+    gap: tokens.spacing.sm,
+    ...Platform.select({
+      ios: {
+        shadowColor: tokens.color.neutral[900],
+        shadowOffset: { width: 0, height: 2 },
+        shadowOpacity: 0.08,
+        shadowRadius: 8,
+      },
+      android: {
+        elevation: 2,
+      },
+    }),
+  },
+  title: {
+    fontFamily: tokens.typography.heading.fontFamily,
+    fontWeight: tokens.typography.heading.fontWeight,
+    fontSize: 18,
+    color: tokens.color.neutral[900],
+  },
+  detail: {
+    fontFamily: tokens.typography.body.fontFamily,
+    fontSize: 14,
+    color: tokens.color.neutral[600],
+  },
+  progressTrack: {
+    height: 6,
+    backgroundColor: tokens.color.neutral[200],
+    borderRadius: 3,
+  },
+  progressFill: {
+    height: 6,
+    backgroundColor: tokens.color.primary[500],
+    borderRadius: 3,
+  },
+});
+```
+
+### Example: SwiftUI List Item
+
+**IMPLEMENT output (WorkoutRow.swift):**
+
+```swift
+// @design-token color.primary.500 — accent color
+// @design-token color.neutral.900 — primary text
+// @design-token color.neutral.600 — secondary text
+// @design-token typography.heading.fontWeight — title weight
+// @design-token spacing.sm — content spacing
+
+import SwiftUI
+
+struct WorkoutRow: View {
+    let title: String
+    let duration: String
+    let progress: Double
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: AppSpacing.sm) {
+            Text(title)
+                .font(.headline)
+                .foregroundColor(AppColors.neutral900)
+
+            Text(duration)
+                .font(.subheadline)
+                .foregroundColor(AppColors.neutral600)
+
+            ProgressView(value: progress)
+                .tint(AppColors.primary500)
+        }
+        .padding(AppSpacing.md)
+        .accessibilityElement(children: .combine)
+    }
+}
+```
+
+## Gates
+
+- **No component generation without reading tokens from harness-design-system.** The SCAFFOLD phase requires `design-system/tokens.json`. Do not generate components with hardcoded values as a fallback.
+- **No hardcoded design values in generated output.** Every color, font, and spacing value must reference a token.
+- **No platform-specific code without platform detection.** The SCAFFOLD phase must detect or receive the target mobile platform before generating components.
+- **No generation without scaffold plan confirmation.** Present the component plan to the user first.
+- **No iOS components without 44pt minimum touch targets.** Touch target violations are `error` severity regardless of strictness level.
+- **No Android/Material components without 48dp minimum touch targets.** Same as iOS — touch targets are non-negotiable.
+- **No graph mutations without validating node types.** Verify edge types are registered before writing.
+
+## Escalation
+
+- **When `design-system/tokens.json` does not exist:** Instruct the user: "Design tokens have not been generated. Run `harness-design-system` first, then re-run `harness-design-mobile`."
+- **When the project targets multiple mobile platforms:** Generate for the primary platform first, then offer to generate platform-adapted variants. React Native projects get both iOS and Android considerations in a single pass.
+- **When tokens are insufficient for the requested component:** Report missing tokens and instruct the user to add them via harness-design-system.
+- **When platform guidelines conflict with design intent:** Present the conflict: "Material Design 3 recommends rounded corners for cards, but your design intent declares 'sharp edges only.' Options: (1) Follow platform guidelines for native feel, (2) Override with design intent for brand consistency."
+- **When the knowledge graph is unavailable:** Skip graph operations. Log: "Graph not available — skipping token node verification and PLATFORM_BINDING edge creation. Run `harness scan` later to populate."

package/dist/agents/skills/gemini-cli/harness-design-mobile/skill.yaml

@@ -0,0 +1,49 @@
+name: harness-design-mobile
+version: "1.0.0"
+description: Token-bound mobile component generation with React Native, SwiftUI, Flutter, and Compose patterns and platform-specific design rules
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+  - on_new_feature
+  - on_commit
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-design-mobile
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: platform
+      description: Target mobile platform (react-native, swiftui, flutter, compose)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-design-mobile
+    path: string
+type: rigid
+phases:
+  - name: scaffold
+    description: Read tokens and design intent, detect mobile platform, plan component structure with platform-specific rules
+    required: true
+  - name: implement
+    description: Generate token-bound components with platform-specific patterns and native conventions
+    required: true
+  - name: verify
+    description: Verify token binding, platform guideline compliance, and design constraints
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-design-system
+  - harness-design

package/dist/agents/skills/gemini-cli/harness-design-system/SKILL.md

@@ -0,0 +1,282 @@
+# Harness Design System
+
+> Token-first design management. Discover existing design patterns, define intent through curated palettes and typography, generate W3C DTCG tokens, and validate every color pair for WCAG compliance.
+
+## When to Use
+
+- Starting a new project that needs design tokens (colors, typography, spacing)
+- Adding design consistency to an existing project that lacks a token system
+- When `on_project_init` triggers fire and the project has no `design-system/tokens.json`
+- When `on_new_feature` triggers fire with design scope (new theme, new component library, rebrand)
+- Regenerating tokens after stakeholder feedback on palette or typography choices
+- NOT for accessibility auditing of existing components (use harness-accessibility)
+- NOT for aesthetic direction, mood boards, or brand strategy (use harness-design, Phase 4)
+- NOT for platform-specific implementation of tokens into CSS/Tailwind/etc. (use harness-design-web/mobile, Phase 5)
+- NOT for fixing individual contrast failures in code (use harness-accessibility fix phase)
+
+## Process
+
+### Phase 1: DISCOVER -- Detect Existing Design System
+
+1. **Read existing design files.** Search for:
+   - `design-system/tokens.json` -- existing W3C DTCG tokens
+   - `design-system/DESIGN.md` -- existing design intent documentation
+   - `tailwind.config.*` -- Tailwind CSS configuration with theme overrides
+   - CSS files with custom properties (`--color-*`, `--font-*`, `--space-*`)
+   - `theme.ts`, `theme.js`, `styles/variables.*` -- CSS-in-JS or preprocessor variables
+
+2. **Check harness configuration.** Read `harness.config.json` for:
+   - `design.strictness` -- enforcement level (`strict`, `standard`, `permissive`)
+   - `design.platforms` -- which platforms are enabled (web, mobile)
+   - `design.tokenPath` -- path to tokens file (default: `design-system/tokens.json`)
+   - `design.aestheticIntent` -- path to design intent doc (default: `design-system/DESIGN.md`)
+
+3. **Detect framework.** Identify the CSS strategy in use:
+   - Tailwind CSS (presence of `tailwind.config.*`)
+   - CSS-in-JS (styled-components, Emotion, Stitches imports)
+   - CSS Modules (`.module.css` or `.module.scss` files)
+   - Vanilla CSS/SCSS (global stylesheets)
+   - None detected (greenfield)
+
+4. **Identify existing patterns.** Use Grep to find:
+   - Color values: hex codes (`#[0-9a-fA-F]{3,8}`), rgb/hsl functions
+   - Font declarations: `font-family` properties, `@font-face` rules
+   - Spacing patterns: margin/padding values, gap values
+   - Count unique values to estimate design debt (many unique colors = high debt)
+
+5. **Load industry recommendations.** If an industry is specified (via CLI arg or config), read the industry profile from `agents/skills/shared/design-knowledge/industries/{industry}.yaml`. This provides sector-specific guidance on color psychology, typography conventions, and regulatory considerations.
+
+6. **Report findings before proceeding.** Present a summary:
+   - Existing token file: yes/no
+   - Framework detected: [name]
+   - Unique colors found: [count]
+   - Unique fonts found: [count]
+   - Industry profile loaded: yes/no
+   - Design debt assessment: low/medium/high
+
+### Phase 2: DEFINE -- Select Palette, Typography, and Spacing
+
+1. **Present palette options.** Load curated palettes from `agents/skills/shared/design-knowledge/palettes/curated.yaml`. Filter by industry tags if an industry is specified. Present 3-5 palette options with:
+   - Palette name and description
+   - Primary, secondary, accent, neutral color ramps
+   - Semantic colors (success, warning, error, info)
+   - Pre-computed contrast ratios for common pairs (text-on-background)
+
+2. **Present typography pairings.** Load pairings from `agents/skills/shared/design-knowledge/typography/pairings.yaml`. Present 3-5 options with:
+   - Heading font + body font combination
+   - Fallback stacks for each font
+   - Recommended size scale (base size, scale ratio)
+   - Line height and letter spacing recommendations
+
+3. **Define spacing scale.** Default: 4px base with multipliers [0.25, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12, 16]. Allow customization of:
+   - Base unit (4px, 8px)
+   - Scale multipliers
+   - Named aliases (xs, sm, md, lg, xl, 2xl, etc.)
+
+4. **Capture design intent.** Ask the user to define:
+   - Style: minimal, expressive, corporate, playful, editorial
+   - Tone: warm, cool, neutral, bold, muted
+   - Key differentiator: what makes this product's visual identity unique
+   - Anti-patterns: specific design choices to avoid
+
+5. **Confirm all choices.** Present a complete summary of palette, typography, spacing, and intent. Wait for user confirmation before generating. This is a hard gate -- no generation without confirmation.
+
+### Phase 3: GENERATE -- Create Tokens and Documentation
+
+1. **Generate `design-system/tokens.json`** in W3C Design Token Community Group (DTCG) format. Structure:
+
+   ```json
+   {
+     "color": {
+       "primary": {
+         "50": { "$value": "#eff6ff", "$type": "color", "$description": "Lightest primary" },
+         "500": { "$value": "#3b82f6", "$type": "color", "$description": "Base primary" },
+         "900": { "$value": "#1e3a5f", "$type": "color", "$description": "Darkest primary" }
+       },
+       "semantic": {
+         "success": {
+           "$value": "{color.green.500}",
+           "$type": "color",
+           "$description": "Success state"
+         },
+         "error": { "$value": "{color.red.500}", "$type": "color", "$description": "Error state" }
+       }
+     },
+     "typography": {
+       "heading": {
+         "fontFamily": { "$value": "Inter, system-ui, sans-serif", "$type": "fontFamily" },
+         "fontWeight": { "$value": 600, "$type": "fontWeight" }
+       },
+       "body": {
+         "fontFamily": { "$value": "Source Sans 3, system-ui, sans-serif", "$type": "fontFamily" },
+         "fontSize": { "$value": "1rem", "$type": "dimension" }
+       }
+     },
+     "spacing": {
+       "xs": { "$value": "4px", "$type": "dimension", "$description": "Extra small spacing" },
+       "sm": { "$value": "8px", "$type": "dimension", "$description": "Small spacing" },
+       "md": { "$value": "16px", "$type": "dimension", "$description": "Medium spacing" },
+       "lg": { "$value": "24px", "$type": "dimension", "$description": "Large spacing" },
+       "xl": { "$value": "32px", "$type": "dimension", "$description": "Extra large spacing" }
+     }
+   }
+   ```
+
+2. **Generate `design-system/DESIGN.md`** with:
+   - Aesthetic direction (style, tone, differentiator)
+   - Color usage guidelines (when to use primary vs. secondary vs. accent)
+   - Typography hierarchy (h1-h6 sizing, body text, captions)
+   - Spacing conventions (component padding, layout gaps, section margins)
+   - Anti-patterns (explicitly forbidden design choices)
+   - Platform-specific notes (Tailwind class mappings, CSS variable names)
+   - Strictness override instructions (how to change `design.strictness`)
+
+3. **Populate the knowledge graph.** If a graph exists at `.harness/graph/`, run `DesignIngestor` from `packages/graph/src/ingest/DesignIngestor.ts` to create graph nodes for:
+   - Each color token (type: `design_token`, subtype: `color`)
+   - Each typography token (type: `design_token`, subtype: `typography`)
+   - Each spacing token (type: `design_token`, subtype: `spacing`)
+   - The aesthetic intent (type: `aesthetic_intent`) with style, tone, differentiator, and strictness properties
+   - `declares_intent` edges from the project to the aesthetic intent node
+
+### Phase 4: VALIDATE -- Verify Tokens and Compliance
+
+1. **Parse `tokens.json` against W3C DTCG structure.** Verify:
+   - Every token has `$value` and `$type` fields
+   - Token references (e.g., `{color.primary.500}`) resolve to existing tokens
+   - No orphan tokens (defined but never referenced in DESIGN.md or usage guidelines)
+
+2. **Check color contrast compliance.** For every declared contrast pair:
+   - Calculate the contrast ratio using the WCAG 2.1 relative luminance formula
+   - Normal text (< 18px): require >= 4.5:1 ratio (WCAG AA)
+   - Large text (>= 18px or >= 14px bold): require >= 3:1 ratio (WCAG AA)
+   - Report each pair with its ratio and pass/fail status
+
+3. **Verify typography completeness.** Check that:
+   - Every font family declaration includes a fallback stack (at least `system-ui` or `sans-serif`/`serif`/`monospace`)
+   - Heading and body fonts are different (unless intentional single-font system)
+   - Font weights are specified as numbers, not names
+
+4. **Verify spacing scale.** Check that:
+   - Spacing values are monotonically increasing
+   - No gaps in the scale (e.g., jumping from 8px to 48px with nothing between)
+   - Base unit is consistent across all values
+
+5. **Run project health check.** Execute `harness validate` to ensure the new files do not break any existing constraints.
+
+6. **Report validation results.** Present a summary:
+   - DTCG structure: pass/fail with details
+   - Contrast pairs: N passed, M failed (list failures)
+   - Typography: pass/fail with details
+   - Spacing: pass/fail with details
+   - Harness validate: pass/fail
+
+## Harness Integration
+
+- **`harness validate`** -- Run after generating tokens to verify project health. Token generation must not break existing constraints.
+- **`harness scan`** -- Run after token changes to refresh the knowledge graph. Updated graph enables impact analysis when tokens are modified later.
+- **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Parses `tokens.json` and `DESIGN.md` to create graph nodes representing the design system. Called during the GENERATE phase.
+- **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) -- Enforces design constraints by checking for `VIOLATES` edges in the graph. Used during validation to detect constraint violations.
+- **`harness-impact-analysis`** -- When tokens change, impact analysis traces which components consume affected tokens, enabling targeted re-validation.
+
+## Success Criteria
+
+- `design-system/tokens.json` exists and is valid W3C DTCG format (every token has `$value` and `$type`)
+- `design-system/DESIGN.md` exists with aesthetic direction, usage guidelines, anti-patterns, and platform notes
+- All declared color contrast pairs pass WCAG AA thresholds (4.5:1 normal text, 3:1 large text)
+- Every font family has a fallback stack
+- Spacing scale is monotonically increasing with no gaps
+- Graph nodes created for each token (if graph exists at `.harness/graph/`)
+- `harness validate` passes after token generation
+- User confirmed palette and typography choices before generation
+
+## Examples
+
+### Example: SaaS Dashboard Project
+
+**Context:** New SaaS analytics dashboard. Industry: `saas`. No existing design system.
+
+**DISCOVER output:**
+
+```
+Design System Discovery Report
+-------------------------------
+Existing token file:    No
+Framework detected:     Tailwind CSS (tailwind.config.ts)
+Unique colors found:    23 (high debt -- colors scattered across components)
+Unique fonts found:     4 (medium debt -- inconsistent font usage)
+Industry profile:       Loaded (saas) -- recommends professional blues, clean sans-serif
+Design debt assessment: High -- no centralized design system, ad-hoc color usage
+```
+
+**DEFINE choices:**
+
+```
+Selected palette:     "Ocean Professional" (blue primary, slate neutral, emerald accent)
+Selected typography:  Inter (headings, 600 weight) + Source Sans 3 (body, 400 weight)
+Spacing base:         4px with standard multipliers
+Style:                Minimal, data-focused
+Tone:                 Cool, professional
+Differentiator:       Dense information display with generous whitespace between sections
+Anti-patterns:        No gradients on data elements, no decorative borders on cards
+```
+
+**GENERATE output (tokens.json snippet):**
+
+```json
+{
+  "color": {
+    "primary": {
+      "50": { "$value": "#eff6ff", "$type": "color", "$description": "Background tint" },
+      "100": { "$value": "#dbeafe", "$type": "color", "$description": "Hover state" },
+      "500": { "$value": "#3b82f6", "$type": "color", "$description": "Primary action" },
+      "700": { "$value": "#1d4ed8", "$type": "color", "$description": "Primary text on light" },
+      "900": { "$value": "#1e3a5f", "$type": "color", "$description": "Darkest primary" }
+    },
+    "neutral": {
+      "50": { "$value": "#f8fafc", "$type": "color", "$description": "Page background" },
+      "900": { "$value": "#0f172a", "$type": "color", "$description": "Primary text" }
+    }
+  },
+  "typography": {
+    "heading": {
+      "fontFamily": { "$value": "Inter, system-ui, sans-serif", "$type": "fontFamily" }
+    },
+    "body": {
+      "fontFamily": { "$value": "Source Sans 3, system-ui, sans-serif", "$type": "fontFamily" }
+    }
+  }
+}
+```
+
+**VALIDATE output:**
+
+```
+Validation Results
+------------------
+DTCG structure:  PASS (42 tokens, all have $value and $type)
+Contrast pairs:  PASS (12/12 pairs meet WCAG AA)
+  - primary-700 on neutral-50:  8.1:1  PASS (normal text)
+  - neutral-900 on neutral-50: 15.4:1  PASS (normal text)
+  - neutral-50 on primary-500:  4.7:1  PASS (normal text)
+Typography:      PASS (all fonts have fallback stacks)
+Spacing:         PASS (monotonically increasing, no gaps)
+Harness validate: PASS
+```
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **No tokens generated without user confirming palette and typography choices.** The DEFINE phase must end with explicit user confirmation. Do not auto-select and generate.
+- **No `tokens.json` written without passing DTCG schema validation.** Every token must have `$value` and `$type`. Malformed tokens are rejected before writing to disk.
+- **No contrast pair allowed below 4.5:1 for normal text.** If a selected palette produces a failing contrast pair, flag it and ask the user to choose an alternative. Do not silently accept.
+- **No fonts without fallback stacks.** Every `fontFamily` token must include at least one generic fallback (`sans-serif`, `serif`, `monospace`, or `system-ui`).
+- **No spacing scale with non-monotonic values.** If a user customizes spacing, validate that values increase. Reject scales where `md` is larger than `lg`.
+
+## Escalation
+
+- **After 3 failed contrast validations on the same palette:** Suggest an alternative palette from the curated set that has pre-verified contrast ratios. Present the alternative with a comparison showing which pairs now pass.
+- **When user rejects all curated palettes:** Accept custom colors but warn: "Custom colors have not been pre-validated for contrast compliance. Running full contrast check now." Run validation and report results before generating.
+- **When existing project has conflicting design patterns:** Surface the specific conflicts (e.g., "Found 5 different blue values across 12 components"). Ask the user to choose: consolidate to the new palette, or map each existing value to the nearest token. Do not silently override existing colors.
+- **When `design.strictness` is set to `permissive` but contrast fails:** Still report the failure as a warning. Permissive mode does not suppress contrast checks -- it only changes the severity from error to warning.
+- **When the graph is unavailable:** Skip the graph population step in GENERATE. Log: "Graph not available at .harness/graph/ -- skipping token graph population. Run `harness scan` later to populate." Continue with file generation.