Harness Design

# 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
```

## Rationalizations to Reject

| Rationalization                                                                                                             | Reality                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "The tokens are already defined, so the aesthetic intent is obvious — I can infer it and skip Phase 1."                     | Tokens define values, not intent. The style, tone, and differentiator exist in the designer's head, not in a color ramp. DESIGN.md cannot be generated without explicit confirmation.                                              |
| "There are only 3 violations and they're minor — I'll skip recording them in the graph to save time."                       | Unrecorded violations are invisible to every downstream skill. harness-impact-analysis and harness-accessibility rely on `VIOLATES_DESIGN` edges existing. Skip graph writes and the enforcement record is permanently incomplete. |
| "The strictness level isn't set in config, so I'll just use strict to be safe."                                             | Defaulting to strict without reading config imposes blocking CI failures the team never agreed to. Always read `design.strictness` and default to `standard` when absent — not to the most aggressive level.                       |
| "This anti-pattern is declared, but there are 40+ instances — it would take forever to report them all, so I'll summarize." | The REVIEW phase must report every finding with file path, line number, and severity. Summarizing hides the scope from the team and makes automated tooling miss violations.                                                       |
| "DESIGN.md already exists from a previous run, so I can skip Phase 2 and go straight to REVIEW."                            | An existing DESIGN.md may be outdated or missing sections. The DIRECTION phase must verify all required sections are present and current before the REVIEW phase can rely on them.                                                 |

## 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.