# Harness Design > Harness Design - Skill: `intense-visions/harness-design` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add intense-visions/harness-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/intense-visions/harness-design/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Intense-Visions (https://skillmd.com/u/intense-visions) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/intense-visions/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.