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):

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