design

Harness Design — UI/UX Design Iterations

Design UI/UX for features in any codebase. Produce component trees, layout descriptions, data flow diagrams, and interaction maps. Adapts to the project's framework and component patterns via KB.

Prerequisites

Check for .harness/kb/stack-profile.md. If missing, tell the user to run /harness:init first.

Context Loading

Based on the target app/section:

• Always: .harness/kb/stack-profile.md + .harness/kb/ui-patterns.md
• Data-dependent features: .harness/kb/data-layer.md
• API-dependent features: .harness/kb/api-surface.md
• Always: Check existing components in the target app before proposing new ones

Process

Step 1: Find Input and Classify Target

Determine:

1. Input source: Spec from target_dir, brief, or fresh description
2. Target app/section: Read from ui-patterns.md to identify which app or section this targets
3. Feature type: New page, enhancement to existing page, new component, data table

If ambiguous, ask ONE question to clarify the target.

Step 2: Audit Existing Patterns

Read ui-patterns.md to understand:

• What component library is used (shadcn/ui, Material UI, custom, etc.)
• What state management pattern (Redux, Zustand, React Query, etc.)
• What data fetching pattern exists
• What routing pattern is used

Then check existing components in the target area before proposing new ones. Reference specific existing components by name.

Step 3: Produce Design Artifacts

Create these artifacts for the feature:

Component Tree

FeaturePage
├── FeatureHeader (title, actions)
├── FeatureContent
│   ├── FilterBar (uses existing filters pattern)
│   ├── DataView
│   │   ├── DataTable (follows existing table pattern)
│   │   └── EmptyState
│   └── DetailPanel
│       ├── DetailHeader
│       └── DetailBody
└── FeatureFooter (pagination, bulk actions)

Layout Description

Describe the visual layout in prose or ASCII wireframe. Reference the grid/layout system from ui-patterns.md.

Data Flow

Where data comes from, how it transforms, where it renders:

• Data source → API/query → hook/store → component → render

Interaction Map

User actions and system responses:

User Action	System Response	Component	Notes
Click filter	Re-fetch with params	FilterBar	Debounced
Select row	Open detail panel	DataTable	Slide-in

Reuse Analysis

Need	Existing Component	Action
Data table	{existing table component}	Reuse with custom columns
Form	{existing form pattern}	Follow same pattern
Chart	None exists	Build new, follow {style}

Step 4: Iterate with User (2-3 rounds)

Present design artifacts. Iterate on:

• Component granularity — too many or too few components?
• Data flow — right boundaries between layers?
• Interaction patterns — matches user expectations?

Step 5: Visual Variants

After design artifacts are agreed upon, generate 3 standalone HTML mockups for visual comparison.

Compose a variant brief from the finalized design artifacts:

1. Component Tree → section inventory: what's on screen and the hierarchy
2. Layout Description → spatial arrangement, responsive behavior, content density
3. Interaction Map → key interactive elements (tabs, filters, modals, forms)
4. Data Flow → content types (data tables with status badges, cards with thumbnails, etc.)
5. Visual style → scan existing UI components from ui-patterns.md and the live codebase for color usage, spacing, and layout conventions to match the project's look and feel

Generate 3 HTML files, each differing in at least one meaningful UX dimension:

• Layout structure (sidebar vs top-nav, single-column vs multi-column, card grid vs table)
• Information density (compact vs spacious, progressive disclosure vs everything visible)
• Navigation pattern (tabs vs accordion vs scroll sections)

Each file must be:

• Self-contained — single .html file with <script src="https://cdn.tailwindcss.com">
• Realistic — plausible content for the target feature (real-looking names, dates, values — not Lorem ipsum)
• App-aware — visual style matching the project's existing aesthetic (scan existing components for patterns)
• Disposable — visual references for comparison, not production code

Save to {target_dir}/{topic}-variant-a.html, -variant-b.html, -variant-c.html.

Present to the user:

"I've generated 3 HTML mockups for visual comparison. Open these in your browser:

• A) [approach name] — [1-line description]

• B) [approach name] — [1-line description]

• C) [approach name] — [1-line description]

Which direction do you prefer? (or 'skip' to proceed without variants)"

Record the chosen variant letter for inclusion in the design doc.

Step 6: Save

Save to {target_dir}/design-{slug}-{date}.md with frontmatter:

---
title: "{design title}"
type: design
date: {ISO date}
target-app: "{app name from ui-patterns.md}"
variants: completed | skipped
chosen-variant: "{letter}"               # if variants completed
next-skill: prototype
---

If variants were completed, add a section to the design doc body:

## Visual Direction

Variant **[letter]** selected.
Approach: [approach name — e.g., "Dense sidebar layout"]

Key visual decisions:
- [differentiators from the chosen variant]

Also store via MCP: call harness_add_skillflow_step with skill_type: "design".

Step 7: Suggest Next Step

• Wants to see it working → "Run /harness:prototype to build this based on variant [letter]"
• Ready to build production code → "Hand off to implementation"
• Needs grounding first → "Run /harness:ground to verify the data layer"

Guardrails

• Always reference existing patterns from KB before proposing new ones
• Component tree should show which existing components are reused vs new
• Don't design in a vacuum — every component should trace back to a data source
• Prefer existing component library primitives over custom implementations
• If the project has no UI (pure backend), say so and suggest /harness:ground instead
• HTML variants are disposable visual references — never treat them as production code