@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/claude-code/harness-design/SKILL.md

@@ -0,0 +1,265 @@
+# Harness Design
+
+> Aesthetic direction workflow. Capture design intent, generate DESIGN.md with anti-patterns and platform notes, review components against aesthetic guidelines, and enforce design constraints at configurable strictness levels.
+
+## When to Use
+
+- Establishing aesthetic direction for a new or existing project (style, tone, differentiator)
+- When `on_new_feature` triggers fire and the feature has design scope requiring aesthetic guidance
+- Reviewing existing components against declared design intent and anti-patterns
+- Enforcing design constraints via the knowledge graph with configurable strictness
+- Generating or updating `design-system/DESIGN.md` with aesthetic direction, anti-patterns, and platform notes
+- NOT for design token generation or palette selection (use harness-design-system)
+- NOT for accessibility auditing or WCAG compliance (use harness-accessibility)
+- NOT for platform-specific token implementation into CSS/Tailwind/etc. (use harness-design-web/mobile, Phase 5)
+
+## Process
+
+### Phase 1: INTENT -- Capture Aesthetic Intent
+
+1. **Read existing design artifacts.** Search for:
+   - `design-system/DESIGN.md` -- existing aesthetic direction documentation (from harness-design-system output)
+   - `design-system/tokens.json` -- existing W3C DTCG tokens (palette, typography, spacing defined by harness-design-system)
+   - `harness.config.json` -- project configuration for design settings
+
+2. **Check harness configuration.** Read `harness.config.json` for:
+   - `design.strictness` -- enforcement level (`strict`, `standard`, `permissive`). If not set, default to `standard`.
+   - `design.platforms` -- which platforms are enabled (web, mobile)
+   - `design.aestheticIntent` -- path to design intent doc (default: `design-system/DESIGN.md`)
+
+3. **Load industry profile.** If an industry is specified (via CLI `--industry` arg or config), read the industry profile from `agents/skills/shared/design-knowledge/industries/{industry}.yaml`. Available industries include: `saas`, `fintech`, `healthcare`, `ecommerce`, `creative`, `emerging-tech`, `lifestyle`, `services`. The profile provides sector-specific guidance on:
+   - Recommended visual style and tone
+   - Industry conventions and user expectations
+   - Regulatory or cultural considerations
+   - Common anti-patterns for the sector
+
+4. **Capture user intent.** Ask the user to define:
+   - **Style:** minimal, expressive, corporate, playful, editorial, or custom
+   - **Tone:** warm, cool, neutral, bold, muted, or custom
+   - **Key differentiator:** what makes this product's visual identity unique
+   - **Anti-patterns:** specific design choices to explicitly avoid (e.g., "no gradients on data elements," "no decorative borders on cards")
+
+5. **Load shared design knowledge.** Read anti-pattern awareness from `agents/skills/shared/design-knowledge/`:
+   - `palettes/curated.yaml` -- curated palettes to understand which aesthetic families are available
+   - `typography/pairings.yaml` -- typography pairings to understand which font combinations are recommended
+   - Industry-specific anti-pattern guidance from the loaded industry profile
+
+6. **Confirm intent before proceeding.** Present a summary of the captured aesthetic intent to the user. This is a hard gate -- no DESIGN.md generation without the user confirming their aesthetic intent.
+
+### Phase 2: DIRECTION -- Generate DESIGN.md
+
+1. **Generate or update `design-system/DESIGN.md`.** The document must contain the following sections:
+
+   **Aesthetic Direction:**
+   - Style declaration (the chosen style and what it means for this project)
+   - Tone description (how the tone manifests in color usage, typography weight, spacing density)
+   - Key differentiator (the unique visual identity aspect and how it is expressed)
+
+   **Anti-Patterns:**
+   - Project-specific anti-patterns (from user input in Phase 1)
+   - Industry-informed anti-patterns (from the loaded industry profile)
+   - Each anti-pattern includes: name, description, example of what NOT to do, and why it conflicts with the declared intent
+
+   **Platform Notes:**
+   - Web-specific guidance (CSS strategy, responsive behavior, animation preferences)
+   - Mobile-specific guidance (touch targets, native component usage, platform conventions)
+   - Cross-platform consistency rules (which elements must be identical vs. platform-adapted)
+
+   **Strictness Override:**
+   - Current `designStrictness` level and what it means
+   - Instructions for changing strictness in `harness.config.json`
+   - Behavior differences per level:
+     - `permissive` -- all design violations reported as `info` (nothing blocks)
+     - `standard` -- anti-pattern and accessibility violations are `warn`, critical violations are `error` (default)
+     - `strict` -- accessibility violations are `error` (blocks CI/PR merge), anti-pattern violations are `warn`
+
+2. **Populate the knowledge graph.** If a graph exists at `.harness/graph/`:
+   - Create an `AestheticIntent` node with properties: style, tone, differentiator, strictness level. Use `DesignIngestor` from `packages/graph/src/ingest/DesignIngestor.ts` for graph ingestion.
+   - Create a `DECLARES_INTENT` edge from the project node to the `AestheticIntent` node.
+   - This enables downstream skills (harness-accessibility, harness-impact-analysis) to query the declared design intent.
+
+3. **Run harness validate.** After generating DESIGN.md, verify the project still passes all constraints. The new file must not break existing validations.
+
+### Phase 3: REVIEW -- Review Components Against Design Intent
+
+1. **Scan for anti-pattern violations.** Use Grep to search the codebase for patterns that match declared anti-patterns:
+   - Hardcoded color values not present in `design-system/tokens.json` (suggests off-brand color usage)
+   - Font families flagged as anti-patterns in the design intent (e.g., decorative fonts in a minimal project)
+   - Layout patterns on the forbidden list (e.g., excessive drop shadows in a flat design, gradients on data elements)
+   - CSS properties or values that contradict the declared style (e.g., rounded corners in a sharp-edge design)
+
+2. **Load detection rules from shared design knowledge.** Read from `agents/skills/shared/design-knowledge/`:
+   - `anti-patterns/typography.yaml` — font combinations, size, weight, and line-height issues that clash with the declared style
+   - `anti-patterns/color.yaml` — hardcoded colors, insufficient contrast, color-only indicators that undermine the declared tone
+   - `anti-patterns/layout.yaml` — spacing inconsistencies, missing touch targets, fixed-width containers
+   - `anti-patterns/motion.yaml` — missing prefers-reduced-motion, long animations, scroll-jacking
+   - `industries/{industry}.yaml` — industry-specific rules from the loaded industry profile
+
+3. **Cross-reference with graph constraints.** If a graph exists at `.harness/graph/`:
+   - Query for existing `VIOLATES_DESIGN` edges using `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts`
+   - Compare current findings against previously recorded violations
+   - Identify new violations and resolved violations
+
+4. **Assign severity based on `designStrictness`:**
+   - `permissive` -- all findings are `info` severity
+   - `standard` -- anti-pattern violations and accessibility-related findings are `warn`, critical design constraint violations are `error`
+   - `strict` -- accessibility violations are `error` (blocks), anti-pattern violations are `warn`
+
+5. **Report findings.** Present each finding with:
+   - File path and line number
+   - Violation description and which anti-pattern or design constraint it violates
+   - Severity level (based on current strictness)
+   - Suggested remediation
+
+### Phase 4: ENFORCE -- Surface and Record Violations
+
+1. **Create constraint nodes in the graph.** For each violated design rule, if a graph exists at `.harness/graph/`:
+   - Create a `DesignConstraint` node for the rule being violated (if one does not already exist)
+   - Create a `VIOLATES_DESIGN` edge from the violating component to the `DesignConstraint` node
+   - Use `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts` to manage constraint creation and violation recording
+
+2. **Format violation output.** Each violation follows a numbered format:
+
+   ```
+   DESIGN-001 [warn] Anti-pattern: gradient used on data visualization element
+     File:       src/components/Chart.tsx
+     Line:       42
+     Constraint: No gradients on data elements
+     Intent:     Style "minimal" prohibits decorative effects on informational components
+     Fix:        Replace linear-gradient with solid color from token "neutral.100"
+
+   DESIGN-002 [error] Off-brand color: hardcoded #ff6b35 not in token set
+     File:       src/components/Alert.tsx
+     Line:       18
+     Constraint: All colors must reference design tokens
+     Intent:     Tone "cool" conflicts with warm orange accent
+     Fix:        Use token "semantic.warning" (#f59e0b) or add color to tokens.json via harness-design-system
+
+   DESIGN-003 [info] Typography: decorative font "Playfair Display" used in component
+     File:       src/components/Hero.tsx
+     Line:       8
+     Constraint: Heading font must match declared typography pairing
+     Intent:     Style "minimal" uses Inter for all headings
+     Fix:        Replace with token "typography.heading.fontFamily"
+   ```
+
+3. **Control severity by `designStrictness`:**
+   - `permissive` -- all violations output as `info` (DESIGN-001 [info], DESIGN-002 [info], etc.)
+   - `standard` -- anti-patterns and a11y = `warn`, off-brand tokens = `error` (default)
+   - `strict` -- a11y violations = `error` (blocks CI), anti-patterns = `warn`, off-brand tokens = `error`
+
+4. **Run harness validate.** After recording violations in the graph, run validation to ensure the enforcement pass is consistent with the project state.
+
+## Harness Integration
+
+- **`harness validate`** -- Run after generating DESIGN.md and after enforcement passes. Design violations surface as constraint violations at the configured strictness level.
+- **`harness scan`** -- Run after changes to refresh the knowledge graph. Updated graph enables accurate violation detection and impact analysis.
+- **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Parses `tokens.json` and `DESIGN.md` to create graph nodes representing the design system. Creates `AestheticIntent` nodes and `DECLARES_INTENT` edges during the DIRECTION phase.
+- **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) -- Manages `DesignConstraint` nodes and `VIOLATES_DESIGN` edges in the graph. Reads `design.strictness` to control violation severity. Used during REVIEW and ENFORCE phases.
+
+**Graph naming convention:** This skill uses PascalCase for node types (`AestheticIntent`, `DesignToken`, `DesignConstraint`) and UPPER_SNAKE for edge types (`DECLARES_INTENT`, `VIOLATES_DESIGN`, `USES_TOKEN`, `PLATFORM_BINDING`) as conceptual labels. The graph schema registers these as snake_case identifiers (`aesthetic_intent`, `design_token`, `design_constraint`, `declares_intent`, `violates_design`, `uses_token`, `platform_binding`). The adapter classes (`DesignIngestor`, `DesignConstraintAdapter`) handle the mapping — always use the adapters rather than constructing graph queries with raw type names.
+
+- **`harness-design-system`** -- Dependency. This skill reads tokens and design intent generated by harness-design-system. Token-level issues (palette changes, new colors) are resolved by running harness-design-system, not this skill.
+- **`harness-impact-analysis`** -- When design tokens change, impact analysis traces which components consume affected tokens. Use this to determine which components need re-review after token updates.
+
+## Success Criteria
+
+- `design-system/DESIGN.md` exists with all required sections: Aesthetic Direction, Anti-Patterns, Platform Notes, Strictness Override
+- Anti-patterns are detected in the codebase and reported with file paths, line numbers, and severity
+- `designStrictness` configuration is read from `harness.config.json` and respected in all severity assignments
+- `AestheticIntent` node created in the knowledge graph with style, tone, differentiator, and strictness properties
+- `DECLARES_INTENT` edge connects the project to the aesthetic intent node
+- `DesignConstraint` nodes created for each violated design rule
+- `VIOLATES_DESIGN` edges connect violating components to their constraint nodes
+- Violations output in numbered format (DESIGN-001, DESIGN-002, etc.) with severity matching strictness level
+- `harness validate` passes after DESIGN.md generation and enforcement
+- User confirmed aesthetic intent before DESIGN.md generation (hard gate)
+
+## Examples
+
+### Example: SaaS Analytics Dashboard Aesthetic Direction
+
+**Context:** A SaaS analytics dashboard project. Industry: `saas`. Design tokens already generated by harness-design-system. No existing DESIGN.md aesthetic direction.
+
+**INTENT capture:**
+
+```
+Industry profile:     Loaded (saas) -- recommends professional, data-focused aesthetic
+Style:                Minimal
+Tone:                 Cool, professional
+Differentiator:       Dense information display with generous whitespace between sections
+Anti-patterns:        No gradients on data elements, no decorative borders on cards,
+                      no more than 2 font weights per component
+Strictness:           standard (from harness.config.json)
+```
+
+**DIRECTION output (DESIGN.md excerpt):**
+
+```markdown
+## Aesthetic Direction
+
+**Style:** Minimal -- clean lines, flat surfaces, no decorative elements that do not serve
+an informational purpose. Every visual element must earn its place by conveying data or
+guiding the user's eye.
+
+**Tone:** Cool, professional -- slate and blue palette dominates. Warm colors reserved
+exclusively for semantic states (warning, error). No warm accents in neutral UI.
+
+**Differentiator:** Dense information display with generous whitespace between sections.
+Components are compact internally but breathe externally. Card padding is tight (12px),
+but gaps between cards are generous (24px+).
+
+## Anti-Patterns
+
+| Pattern                    | Description                                  | Why It Conflicts                           |
+| -------------------------- | -------------------------------------------- | ------------------------------------------ |
+| Gradients on data elements | linear-gradient on charts, tables, cards     | Minimal style: flat surfaces only          |
+| Decorative card borders    | border with color on .card elements          | Minimal style: borders are structural only |
+| Excess font weights        | More than 2 font-weight values per component | Minimal style: typographic restraint       |
+
+## Strictness Override
+
+Current level: **standard**
+
+To change, update `harness.config.json`:
+"design": { "strictness": "strict" | "standard" | "permissive" }
+```
+
+**REVIEW findings:**
+
+```
+Found 3 anti-pattern violations in 2 files:
+
+DESIGN-001 [warn] Gradient on data element
+  File:       src/components/RevenueChart.tsx:42
+  Constraint: No gradients on data elements
+  Fix:        Replace linear-gradient(#3b82f6, #1d4ed8) with solid token "primary.500"
+
+DESIGN-002 [warn] Decorative border on card
+  File:       src/components/MetricCard.tsx:15
+  Constraint: No decorative borders on cards
+  Fix:        Remove border-color: #3b82f6, use border-color: transparent or remove border
+
+DESIGN-003 [info] Three font weights in one component
+  File:       src/components/MetricCard.tsx:8
+  Constraint: Max 2 font weights per component
+  Fix:        Consolidate font-weight values to 400 (body) and 600 (heading) only
+```
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **No DESIGN.md generated without the user confirming aesthetic intent.** The INTENT phase must end with explicit user confirmation of style, tone, differentiator, and anti-patterns. Do not generate based on assumptions.
+- **No enforcement without reading tokens from harness-design-system.** The REVIEW and ENFORCE phases require `design-system/tokens.json` to exist. If tokens have not been generated, instruct the user to run harness-design-system first.
+- **Strictness must be read from configuration, not assumed.** Read `design.strictness` from `harness.config.json`. If the key does not exist, default to `standard` and report the default to the user. Never hardcode a strictness level.
+- **No anti-pattern detection without a declared intent.** The REVIEW phase requires an existing DESIGN.md with declared anti-patterns. If no intent has been captured, run the INTENT and DIRECTION phases first.
+- **No graph mutations without validating node types.** When creating `AestheticIntent`, `DesignConstraint`, or `VIOLATES_DESIGN` edges, verify the node and edge types are registered in the graph schema before writing.
+
+## Escalation
+
+- **When the user cannot articulate a style or tone:** Suggest industry-based defaults from the loaded industry profile. Present 2-3 options with examples: "Based on the saas industry profile, common styles are: (1) Minimal -- clean, data-focused, (2) Corporate -- structured, trustworthy, (3) Expressive -- colorful, engaging. Which resonates most?"
+- **When declared anti-patterns conflict with existing code:** Present a migration path rather than flagging every instance as a violation. Report: "Found 47 instances of gradients on data elements. Recommend a phased migration: (1) Update new components immediately, (2) Schedule legacy component updates over 3 sprints. Set strictness to 'permissive' during migration to avoid blocking CI."
+- **When tokens do not exist yet:** Do not attempt to infer a token set. Instruct the user: "Design tokens have not been generated. Run harness-design-system first to create `design-system/tokens.json`, then re-run harness-design for aesthetic direction."
+- **When strictness level conflicts with team velocity:** Explain the tradeoffs: "Strict mode blocks PRs on any design violation. If this is slowing the team, consider 'standard' mode which blocks only on critical violations (off-brand colors, accessibility) and warns on anti-patterns."
+- **When the knowledge graph is unavailable:** Skip graph operations in DIRECTION and ENFORCE phases. Log: "Graph not available at `.harness/graph/` -- skipping AestheticIntent node creation and violation recording. Run `harness scan` later to populate." Continue with file-based operations.

package/dist/agents/skills/claude-code/harness-design/skill.yaml

@@ -0,0 +1,53 @@
+name: harness-design
+version: "1.0.0"
+description: Aesthetic direction workflow, anti-pattern enforcement, DESIGN.md generation, and strictness configuration
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-design
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: strictness
+      description: Override strictness level (strict, standard, permissive)
+      required: false
+    - name: industry
+      description: Industry vertical for aesthetic recommendations
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-design
+    path: string
+type: flexible
+phases:
+  - name: intent
+    description: Capture aesthetic intent, style, tone, and differentiator
+    required: true
+  - name: direction
+    description: Generate DESIGN.md with aesthetic direction, anti-patterns, and platform notes
+    required: true
+  - name: review
+    description: Review existing components against design intent and anti-patterns
+    required: false
+  - name: enforce
+    description: Enforce design constraints via graph, surface violations by strictness level
+    required: false
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-design-system

package/dist/agents/skills/claude-code/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."