spec-frontend

/spec-frontend — Specify a substantial existing-frontend redesign

Purpose

Turn an existing page, route, or flow into a detailed, product-specific redesign specification before code changes begin.

Use this when /improve-ui-ux would be too small: the goal is a material improvement to hierarchy, visual craft, interaction, and usability while preserving intended product behavior and valuable brand equity.

Invocation

/spec-frontend <route/component and desired outcome>

Accepted input

An existing rendered route or component, pain points, screenshots or references, target users, desired degree of change, brand constraints, and success criteria.

Prerequisites

A HarnessKit workspace and an existing frontend surface. A runnable preview is strongly preferred; static-only planning must be labelled lower confidence.

Procedure

1. Apply context-discovery. Identify the exact surface, user, primary task, product goal, requested degree of change, preservation constraints, non-goals, preview command, stable fixture/data, supported themes, and relevant viewports.
2. Inspect repository evidence before asking questions. Ask one grouped batch of only decision-changing questions, normally no more than three and never more than five. If the user requests a dramatic change, clarify what must remain recognizable rather than treating “drastic” as permission to replace everything.
3. Apply the complete curated skill set, loading each canonical body rather than fetching upstream prompts at runtime: frontend-design-direction, visual-craft, design-system-integration, ui-state-design, responsive-ui-engineering, accessible-ui-engineering, motion-design, and browser-visual-validation.
4. Run a discovery wave using native isolated subagents in parallel when the active tool supports them:
   • visual-qa-tester records a reproducible baseline with like-for-like route, data, state, viewport, theme, task steps, console, and network conditions;
   • design-system-specialist maps tokens, typography, icons, primitives, components, themes, states, and closest precedents. Otherwise use clearly labelled native-sequential or simulated-sequential passes. Record the actual execution mode; never imply independence that did not exist.
5. Give the same brief, context capsule, baseline, and reuse map to independent read-only specialist passes. Do not show them each other's first conclusions:
   • ux-reviewer: task flow, comprehension, copy, information architecture, friction, recovery, and state completeness;
   • visual-craft-specialist: hierarchy, typography, color, spacing, gaps, density, optical alignment, shape, elevation, imagery, icons, and anti-AI-slop;
   • interaction-design-specialist: buttons and controls, feedback, focus, async states, interruption, gestures, and purposeful motion;
   • accessibility-reviewer: semantic, keyboard, focus, contrast, zoom/reflow, reduced-motion, form, and recovery constraints.
6. Have frontend-design-lead synthesize—not vote—one recommended direction. Offer two only for a genuine unresolved product/brand fork. Preserve material dissent and explain why the selected direction fits the user outcome.
7. Inspect active packs before continuing. If more than one primary aesthetic pack is enabled, stop and ask the user to choose exactly one; exporter priority does not make contradictory directions coherent. Otherwise use at most one explicitly enabled primary aesthetic pack: frontend-design, taste-skill, or ui-ux-pro-max. The optional emil-design-engineering layer may supplement interaction craft. Do not silently enable packs, blend competing voices, execute upstream scripts, or copy a source skill's stack/dependency recommendations over repository evidence.
8. Write .agent/specs/<kebab-case-name>.md as an ordinary valid HarnessKit spec using the required frontmatter below. Include:
   • baseline evidence and named user outcome;
   • preservation constraints, non-goals, and rejected alternatives;
   • selected design thesis and anti-AI-slop acceptance rubric;
   • content and hierarchy;
   • typography roles, scale, weight, line height, and measure;
   • semantic color roles, themes, contrast, and non-color cues;
   • spacing/density/grid, alignment, radius, borders, elevation, imagery, and icons;
   • responsive transition rules based on content pressure;
   • complete operational and control-state matrices;
   • interaction/motion purpose, timing behavior, interruption, reduced motion, pointer/touch/keyboard behavior, and performance acceptance;
   • accessibility contract;
   • design-system reuse and narrowly justified extensions;
   • dependency-ordered implementation tasks, files/ownership, tests, browser scenarios, fixtures, viewports, gates, risks, and approval needs.
9. Present a /sum-spec-style plain-language summary and stop for explicit approval. Do not launch implementation workers or edit production code.