Harness Design Craft

# Harness Design Craft

> LLM-judgment-based design ceiling-raiser. Three branchable phases — CRITIQUE finds what's mediocre, POLISH applies high-craft moves, BENCHMARK scores against curated exemplars. The ceiling counterpart to harness-design (declared-intent enforcement, rule-based) and the design-pipeline floor audits.

## When to Use

- Reviewing UI for craft elevation opportunities the rule-based skills can't surface ("hierarchy is muddy here," "loading spinner where a content-matched skeleton would fit")
- After harness-design has captured intent and basic checks pass — go from "consistent" to "stunning"
- Before launching customer-facing surfaces — visual judgment beyond consistency
- During design-engineering work — POLISH phase suggests concrete craft moves with before/after sketches
- For competitive benchmarking — BENCHMARK scores how close you are to Linear / Stripe / Raycast tier
- When `on_new_feature` fires AND the feature touches design surface
- NOT for declared-anti-pattern enforcement (use harness-design)
- NOT for component anatomy completeness (use audit-component-anatomy)
- NOT for token validation (use harness-design-system)
- NOT for accessibility (use harness-accessibility)
- NOT for code generation from scratch (use v0 / bolt.new / Lovable — different tool class)

## Capability Roles

<!-- Capability seam: this skill participates in a real extension point whose three roles are named and concrete. A seam with only one role filled is accidental single-implementation lock-in. See harness-skill-authoring Phase 1C. -->

- **Defines (Service Definition):** the shared craft critique contract (`packages/cli/src/shared/craft/`) — `LlmProvider` + finding/axes schema + run store — shared across all `*-craft` skills. This skill implements, and does not own, that contract.
- **Provides (Provider):** **this skill** — a design ceiling critique/polish/benchmark implemented over the shared contract (`packages/cli/src/design-craft/`).
- **Consumes (Consumer):** `craft-fleet` (the craft-pipeline elevation sweep) and the `harness` natural-language router, which invoke every `*-craft` provider uniformly through the shared critique/finding shape. It is also dispatched by `harness-design-pipeline` in the FILL phase; note it is **not** a formal `Verifier<F>` provider — its output shape differs, so it is dispatched rather than registered in the verifier seam

## Process

### Argument Resolution

- `mode`: `"fast"` (code-only LLM, cheap, default) or `"deep"` (rendered + vision-LLM, ceiling-raising, requires playwright + vision-capable model)
- `phases`: subset of `critique`, `polish`, `benchmark`. Default: all three, sequenced.
- `autoCapture`: B' upgrade behavior. `"prompt"` (default — offer to chain to harness-design if preconditions missing), `"auto"` (chain without prompting), `"skip"` (run with generic-craft rubrics, no offer).
- `files`: optional scoping. Default: all components/pages discovered.

### B' Precondition Check (every invocation)

Before any phase runs, check four preconditions and offer to fulfill missing ones:

| Precondition                 | Source                                          | If missing                                                           |
| ---------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
| `designMdExists`             | `design-system/DESIGN.md` present               | Offer to chain to harness-design (INTENT + DIRECTION)                |
| `aestheticIntentDeclared`    | DESIGN.md Aesthetic Direction section populated | Offer to chain to harness-design (INTENT)                            |
| `tokensExist`                | `design-system/tokens.json` present             | Note in summary; do not auto-chain (harness-design-system territory) |
| `componentRegistryPopulated` | DESIGN.md Component Registry section            | Note in summary; falls back to export-name resolution                |

`autoCapture` controls behavior:

- `prompt`: emit `upgradeOffer` interaction; pause for user choice
- `auto`: chain to harness-design transition automatically (for autopilot)
- `skip`: run with generic-craft rubrics (degrades quality but unblocks first-run)

### Phase: CRITIQUE — Find what is craft-mediocre

1. **Identify targets.** Discover components (or pages, when scoped to pages) to critique. Apply `files` scoping if provided.

2. **Load critique rubrics.** Read from catalog (`catalog/rubrics/`). 10 rubrics in v1 covering: hierarchy clarity, typography craft, motion quality, color confidence, density rhythm, restraint, polish details, copy voice, interaction craft, brand coherence. Filter by `catalog.rubrics` config if set.

3. **For each target × each rubric, run an LLM critique pass:**
   - **Fast mode:** pass source code + rubric prompt + AestheticIntent (if present) to text LLM
   - **Deep mode:** render via playwright at three viewports (1440/768/375), pass screenshots + source + rubric prompt + AestheticIntent to vision-capable LLM
   - Parse response into 3-axis finding: `tier` (foundational/polish/aspirational), `impact` (small/medium/large), `confidence` (high/medium/low — essential for honest LLM output)

4. **Apply harness-design overlap deferral.** Per `design.craft.enabled = true`, when a CRITIQUE finding matches a declared anti-pattern in DESIGN.md, defer to harness-design (suppress this finding) and increment `meta.deferralsToHarnessDesign`.

5. **Compute derived `priority` field** for each finding (tier × impact × confidence-weighted score) for single-axis sorting when needed.

### Phase: POLISH — Apply craft pattern library

1. **Load polish patterns.** Read from catalog (`catalog/patterns/`). 15 patterns in v1 across 5 categories: motion (3), skeleton (3), typography (3), interaction (3), layout (3). Filter by `catalog.patterns` config if set.

2. **For each target × each applicable pattern, evaluate fit:**
   - Match pattern's `applicableTo` criteria (jsx-attribute, css-property, component-type, etc.)
   - LLM judgment: would applying this pattern improve craft here?
   - If yes: produce 3-axis finding with `before` and `after` content (codemod-TODO sketch, not actual edit)

3. **No source modification.** POLISH only emits suggestions with before/after sketches. The user applies via codemod tools or by hand.

### Phase: BENCHMARK — Score against curated exemplars

1. **Load exemplar corpus.** Read from catalog (`catalog/exemplars/`). 50 exemplars in v1 across 5 component types (EmptyState, LoadingState, ErrorState, Modal, Button — 10 each). Filter by `catalog.exemplars` config if set.

2. **For each target component, identify matching exemplars** by component-type tag (e.g., target is an EmptyState → load all 10 EmptyState exemplars).

3. **For each target × matching exemplars, run an LLM benchmark pass:**
   - **Fast mode:** structural comparison (code/markup/declared anatomy vs exemplar's reference markup) — limited but useful as a first signal
   - **Deep mode:** visual comparison via vision-LLM (target screenshot vs exemplar screenshot/URL)
   - Parse response into 5-dim radar: `philosophicalCoherence`, `hierarchy`, `craftExecution`, `function`, `innovation` — each with score (0-100), confidence, notes
   - Compute weighted `overall` score
   - Emit narrative `gaps` (where the target falls short of the best exemplars and why)

4. **Cite exemplars used.** Each `BenchmarkScore` lists `exemplars` (ids) consulted. Increment per-exemplar `citationCount` for measurement.

5. **Derive the award-tier verdict (machine-computed, not LLM-emitted).** Each `BenchmarkScore` carries an `awardBar` verdict — `cleared`, `not-cleared`, or `indeterminate` — derived in code from the radar plus the cited exemplars' reference scores, never emitted by the LLM. The bar is per-dimension: each dimension must reach `max(dimensionFloor, round(fraction × median(cited-exemplar references)))`. Any dimension whose confidence falls below the confidence floor forces `indeterminate` — a score the model is unsure about never certifies award tier. Tunable via `design.craft.benchmark.awardBar` (`dimensionFloor` default 80, `fraction` default 0.95, `confidenceFloor` default medium).

   > **Scope:** the aesthetic radar certifies **desktop craft**. Mobile/responsive behavior is enforced separately by the responsive gate (next step), which can veto `cleared`.

6. **Apply the responsive gate (mechanical, ADR 0085).** `awardBar.responsive` is a machine gate over mobile layout metrics: a `horizontal-overflow` or `unreachable-nav` (no visible nav AND no menu toggle) defect makes it `defective` and **vetoes `cleared` → `not-cleared`**, regardless of the aesthetic score. Supply per-target layout metrics via `responsiveMetrics` (e.g. from a Playwright MCP run) or a `responsiveProbeCommand` — a render step that prints a `ResponsiveMetrics[]` JSON manifest (the CLI ships no browser; a screenshot is insufficient — the gate needs `scrollWidth` / nav visibility). With no metrics the gate is `not-evaluated` and the aesthetic verdict stands; set `design.craft.benchmark.awardBar.responsive.require` to force `indeterminate` instead of a mobile-blind `cleared`.

### Phase: REPORT — Format and persist outputs

1. **Write to graph:** CRITIQUE/POLISH findings → `VIOLATES_CRAFT` edges via extended `DesignConstraintAdapter`. BENCHMARK scores → `CRAFT_SCORE` nodes attached to component nodes. All carry `runId` for check-design verifier fixpoint detection. Idempotent.

2. **Format markdown report.** Grouped by component, with `CRAFT-*` codes linked to `finding-codes.md` and rubric/pattern/exemplar names linked to their catalog entries. Low-confidence findings visually distinguished (italic or `(low confidence:)` prefix).

3. **Emit summary.** Total findings, breakdown by phase, mode (`fast`/`deep`), LLM cost (`llmCalls.{count, costUsd}`), catalog applied, deferrals to harness-design, precondition state.

4. **Signal feedback.** Append to running aggregate: when the same finding-shape recurs N≥5 times across audits (config: `design.craft.signal.proposalThreshold`), emit a candidate pattern proposal to `.harness/design-craft/proposals/`.

## Harness Integration

- **`harness validate`** — Fast-mode CRITIQUE hook (subset of rubrics; opt-in). Findings respect `design.strictness`.
- **`mcp__harness__design_craft`** — Programmatic API. Consumed by harness check-design verifier and design-pipeline orchestrator. Phase selector exposed.
- **`harness-design`** — Soft dependency. B' progressive upgrade chains to it when AestheticIntent missing. Defers declared-anti-pattern findings to it.
- **`harness-design-system`** — Soft dependency. Token-related polish patterns enriched when tokens exist.
- **`DesignConstraintAdapter`** — Extended for `CRAFT-*` codes (CRAFT-C* critique, CRAFT-P* polish, CRAFT-B\* benchmark identifiers) + `CRAFT_SCORE` node type.
- **`packages/intelligence/`** — Wrapped by `llm/provider.ts` for vision-capable LLM calls. May need extension if no vision support today.

## Success Criteria

See `docs/changes/design-pipeline/design-craft-elevator/proposal.md` for the full 38 success criteria. Highlights:

- Three phases independently invocable via `phases` arg
- 3-axis output for CRITIQUE/POLISH; 5-dim radar for BENCHMARK
- Confidence is honest (low-confidence findings emitted, not silently dropped)
- B' detect-and-offer works (preconditions detected, offer payload emitted, chain to harness-design honored)
- Seed catalog complete (10 rubrics + 15 patterns + 50 exemplars)
- Growth infrastructure operational (contribution validation, signal loop, usage measurement)
- Fast-mode ≤ 30s / 50 files; deep-mode ≤ 3min / 10 components
- LLM cost tracked per audit

## Rationalizations to Reject

These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.

| Rationalization                                                                                                 | Why It Is Wrong                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "The screenshot looks stunning, so I will certify this component award-tier / `cleared`."                       | The `awardBar` verdict is machine-computed in code from the radar plus the cited exemplars' reference scores — never LLM-asserted. And the mechanical responsive gate can veto a strong aesthetic score to `not-cleared`. You emit dimension scores; the referee derives the verdict. |
| "The model is only medium-confident on craftExecution, but the visual is clearly strong, so I will upgrade it." | Any dimension whose confidence falls below the confidence floor forces `indeterminate` by design — a score the model is unsure about must never certify award tier. Silently upgrading confidence defeats the honesty the 3-axis output exists to preserve.                           |
| "POLISH found a better spring curve, so I will apply the codemod to the component."                             | POLISH emits before/after sketches only (`fix kind: codemod-todo`); it never modifies source. Applying the change yourself violates the no-autofix gate — the user applies via their own tools.                                                                                       |
| "No DESIGN.md aesthetic intent is declared, so I will skip this component."                                     | The B' check degrades to generic-craft rubrics (or offers to chain to harness-design) — it never skips. Running with generic rubrics and noting the degraded quality is the documented fallback; abstaining abandons the ceiling role.                                                |
| "This CRITIQUE finding matches a declared anti-pattern in DESIGN.md, but it is worth restating for emphasis."   | When `design.craft.enabled` and DESIGN.md declares the matching anti-pattern, defer to harness-design and suppress the finding (increment `deferralsToHarnessDesign`). Restating double-counts what the rule-based floor already owns.                                                |

## Examples

### Example: CRITIQUE finds hierarchy muddiness

**Input:** A Dashboard.tsx page rendering three CTA buttons, all using the same `variant="primary"`.

**Output (3-axis finding):**

```
CRAFT-C001 [foundational | medium | high] Hierarchy muddy: three buttons compete for primary
  File:        src/pages/Dashboard.tsx:88
  Rubric:      hierarchy-clarity (rubric-hierarchy-clarity)
  Tier:        foundational  (this is "fix to be not-broken," not polish)
  Impact:      medium        (users can still complete tasks, but decision fatigue is real)
  Confidence:  high          (rule is unambiguous; LLM saw the three buttons + their identical styling)
  Priority:    derived → 0.78
  Message:     Three primary-variant buttons in the same view: "Save", "Export", "Share".
               No visual signal indicates which is the recommended action. Reduce to one
               primary; demote the others to secondary or ghost variant.
  Cite:        rubric "hierarchy-clarity" / source: huashu-design#hierarchy
```

### Example: POLISH suggests spring physics

**Input:** A Modal.tsx using `transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1)`.

**Output (3-axis finding with before/after):**

```
CRAFT-P001 [polish | medium | high] Spring physics would feel more confident here
  File:        src/components/Modal.tsx:42
  Pattern:     spring-physics-microinteraction
  Tier:        polish        (Modal already works; this elevates the feel)
  Impact:      medium        (users notice modal motion every time)
  Before:      transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
  After:       transition: transform { duration: spring.medium };
               // stiffness:200 damping:25 for modal entries per emil-design-eng#spring-physics
  Fix kind:    codemod-todo (POLISH does not modify source; suggestion only)
```

### Example: BENCHMARK against Linear

**Input:** A custom EmptyState component for the project's task list.

**Output (5-dim radar):**

```
CRAFT-B001 EmptyState component scored against Linear empty list exemplar

  philosophicalCoherence: 80 [high]   "Restraint aligns with declared minimal aesthetic."
  hierarchy:              65 [medium] "Heading and body OK; action button competes
                                       with secondary 'Learn more' link."
  craftExecution:         55 [medium] "Generic illustration; Linear uses subtle line art
                                       matching their monochromatic palette. Missing the
                                       'breathing room' Linear gets via 64px vertical padding."
  function:               85 [high]   "Action is clear and verb-led."
  innovation:             50 [low]    "Standard 4-part anatomy; not differentiated."

  Overall: 67  [medium confidence]
  Gaps:
    - "Reduce the empty-state to one CTA — the secondary link adds noise"
    - "Replace stock illustration with a custom line art aligned to brand"
    - "Increase top padding from 32px to 56px+ to match the breathing-room pattern"
  Exemplars cited: exemplar-linear-empty-list
```

## Gates

- **No assertion of "stunning" without LLM judgment.** This skill is LLM-judgment-based; if no LLM provider is configured, halt with explanatory error — do not degrade to rule-based output.
- **Deep mode requires playwright + vision-capable LLM.** If either is missing, surface to user with the documented fallback path (code-only mode); do not silently degrade.
- **No autofix.** POLISH emits suggestions only; source files are never modified.
- **Confidence is honest.** Low-confidence outputs MUST be emitted (with the low-confidence flag) — never silently upgraded.
- **B' deferral honored.** When `design.craft.enabled = true` and DESIGN.md declares an anti-pattern matching a CRITIQUE finding, defer to harness-design; never double-count.

## Escalation

- **When deep mode renders fail (component not reachable via URL).** Emit a "render-unreachable" finding for the affected component, fall back to fast mode for that component, continue the audit. Do not abort.
- **When the vision-LLM rejects the screenshot (size, content, format).** Log the rejection; downgrade that component's run to fast mode; do not abort.
- **When LLM cost exceeds the configured per-audit budget.** Halt the audit, emit findings collected so far, report the cost overrun. Do not retry. Config: `design.craft.llm.maxCostUsd` (default unset = no cap).
- **When the catalog is empty or unloadable.** Halt with explanatory error pointing to `agents/skills/shared/design-knowledge/craft-{rubrics,patterns,exemplars}/`. Do not synthesize findings without the catalog.
- **When B' detect-and-offer produces an offer the user declines.** Run in generic-craft mode (no AestheticIntent context); note the degraded quality in summary. User can re-invoke with `autoCapture: skip` to suppress future offers.
- **When the same finding-shape recurs across many audits (signal feedback loop).** Auto-export a candidate pattern proposal to `.harness/design-craft/proposals/` after N≥`design.craft.signal.proposalThreshold` recurrences; require human review before promotion to the catalog.
- **When a graph operation fails.** Skip graph integration for that run; emit findings to the report only. Log a warning that `VIOLATES_CRAFT` edges + `CRAFT_SCORE` nodes were not persisted.

## Status

**v1 — in implementation.** See:

- Spec: `docs/changes/design-pipeline/design-craft-elevator/proposal.md`
- Plan: `docs/changes/design-pipeline/design-craft-elevator/plans/2026-05-23-design-craft-elevator-plan.md`
- Finding codes: `docs/changes/design-pipeline/design-craft-elevator/finding-codes.md`
- Contribution guide: `docs/changes/design-pipeline/design-craft-elevator/contribution.md`
- Growth trajectory: `docs/changes/design-pipeline/design-craft-elevator/growth-trajectory.md`
- Roadmap entry: part of the `design-pipeline` initiative in `docs/roadmap.md`
- Prior-art references: `docs/changes/design-pipeline/REFERENCES.md` tier-1 entries (impeccable, emil-design-eng, huashu-design)