frontend-design

frontend-design

Create distinctive, production-grade frontend interfaces.

Context Files

• $JAAN_CONTEXT_DIR/tech.md - Tech stack context (optional, auto-imported if exists)
  • Uses sections: #current-stack, #frameworks, #constraints
• $JAAN_CONTEXT_DIR/design.md - Design system guidelines (optional)
• $JAAN_CONTEXT_DIR/brand.md - Brand guidelines (optional)
• $JAAN_TEMPLATES_DIR/jaan-to-frontend-design.template.md - Output template
• $JAAN_LEARN_DIR/jaan-to-frontend-design.learn.md - Past lessons (loaded in Pre-Execution)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/frontend-ui-workflow-reference.md - Shared UI workflow reference (CSF3 format, visual scoring)

Input

Component Request: $ARGUMENTS

Accepts any of:

• Component description — "Create a hero section for SaaS landing page"
• Detailed requirements — "Build a pricing card component with 3 tiers, hover effects, CTA buttons"
• PRD reference — Path to PRD file with frontend requirements
• --contract {path} — Optional OpenAPI contract path (from /jaan-to:backend-api-contract output)
• Empty — Start interactive wizard

Contract parsing: If --contract present, extract path first, validate file exists and contains openapi: or swagger: key, then parse remaining positional argument as component description or requirements.

If no input provided, ask: "What component should I design and build?"

---

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: frontend-design Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read context files if available:

• $JAAN_CONTEXT_DIR/tech.md - Know the tech stack for framework-specific code generation
• $JAAN_CONTEXT_DIR/design.md - Know the design system patterns
• $JAAN_CONTEXT_DIR/brand.md - Know brand colors, fonts, tone

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_frontend-design

Language exception: Generated code output (variable names, code blocks, schemas, SQL, API specs) is NOT affected by this setting and remains in the project's programming language.

---

PHASE 1: Analysis (Read-Only)

Thinking Mode

ultrathink

Use extended reasoning for:

• Analyzing component requirements and purpose
• Planning bold design approaches
• Considering accessibility and responsive patterns
• Balancing creativity with usability
• Architecting component structure

Step 1: Parse Component Request

Analyze the provided input to extract:

• If API contract available via --contract: read the spec and extract relevant response schemas to inform data shape in component templates. Use actual field names and types from the spec for realistic mock data.

Build initial understanding:

COMPONENT REQUEST
─────────────────
Type:         {hero/card/form/modal/button/etc}
Purpose:      {what it does}
Context:      {where it's used}
Constraints:  {technical or design constraints}
Unknown:      {areas needing clarification}

If PRD reference:

1. Read the PRD file
2. Extract frontend-relevant requirements
3. Identify component needs from user stories
4. Note technical constraints mentioned

Step 2: Detect Tech Stack

Read $JAAN_CONTEXT_DIR/tech.md if available:

1. Extract frontend framework from #current-stack or #frameworks sections
2. Determine: React, Vue, Svelte, vanilla JS, etc.
3. Note framework version for API compatibility
4. Identify styling approach from tech.md:
   • Tailwind CSS, CSS Modules, styled-components, Sass, vanilla CSS, etc.

Storybook detection (check alongside tech stack):

• Glob: .storybook/main.* — Storybook installed?
• Grep: "storybook" package.json — Storybook in devDependencies?
• Glob: src/**/*.stories.tsx — Existing stories?
• If detected: set storybook_available = true (used in Steps 5, 7b, 10.5)

If tech.md missing or incomplete:

• Ask: "Which framework? (React/Vue/Svelte/Vanilla JS)"
• Ask: "Styling approach? (Tailwind/CSS Modules/styled-components/vanilla CSS)"

Step 3: Gather Design Requirements

Ask up to 7 smart questions based on what's unclear from Steps 1-2. Skip questions already answered by the input or context files.

Design Direction (check settings first)

1. Check settings.yaml (if exists at jaan-to/config/settings.yaml):

   • Look for: design.default_direction, design.palette, design.typography
   • If found, use as baseline

2. Ask user to fill gaps or override (use AskUserQuestion):

   • Question: "What design direction should this take?"
   • Header: "Design Direction"
   • Options:
     • "Bold & Distinctive" — Modern, opinionated, memorable (recommended)
     • "Professional & Clean" — Conservative, trustworthy, subtle
     • "Playful & Creative" — Expressive, fun, unconventional
     • "Minimal & Elegant" — Refined, spacious, sophisticated
     • "Keep Settings Default" — (if settings exist)

3. Infer from context (if still unclear after above):

   • Landing page hero → Bold & Distinctive
   • Dashboard widget → Professional & Clean
   • Marketing page → Playful & Creative
   • Admin form → Minimal & Elegant

Additional Questions (as needed)

4. "Any specific colors, typography, or brand elements to incorporate?" — only if not in brand.md
5. "Any accessibility requirements? (WCAG level, screen reader support)" — only if unclear
6. "Responsive breakpoints needed? (mobile-first assumed)" — only if special requirements
7. "Dark mode support needed?" — only if not specified in design.md

Step 4: Design System Check

Check for existing patterns to maintain consistency:

1. Glob for $JAAN_OUTPUTS_DIR/frontend/design/* to see existing components
2. Read $JAAN_CONTEXT_DIR/design.md (if exists) for:
   • Color palette and usage guidelines
   • Typography scale and hierarchy
   • Spacing system (e.g., 4px, 8px grid)
   • Component patterns and conventions
   • Motion/animation guidelines
3. Grep for similar component patterns (buttons, cards, forms) in codebase

Decision:

• If patterns exist → Note them for consistency
• If no patterns → Create opinionated defaults that establish new standards

Step 5: Plan Component Structure

Based on requirements, tech stack, and design direction, outline the component:

For React:

• Component structure (functional component with hooks)
• Props interface (TypeScript if project uses it)
• State management (if needed - useState, useReducer)
• Styling approach (based on tech.md)
• Accessibility attributes (ARIA labels, roles, keyboard handlers)

For Vue:

• Single File Component structure
• Props definition with TypeScript (if applicable)
• Composition API or Options API (based on project version)
• Scoped styles
• Accessibility attributes

For Vanilla JS/HTML:

• Semantic HTML structure
• Progressive enhancement approach
• CSS organization (BEM methodology, utility classes, or custom properties)
• Minimal JS (if needed for interactivity)

Design Elements to Plan:

• Layout system: Grid, Flexbox, Container Queries
• Typography hierarchy: Display, heading, body, caption levels
• Color usage: Primary, accent, neutral, semantic (success/error/warning)
• Interactive states: hover, focus, active, disabled, loading, error
• Micro-interactions: transitions, animations, scroll-triggered effects
• Responsive behavior: mobile-first breakpoints (e.g., 640px, 1024px, 1280px)

Present component plan:

COMPONENT DESIGN PLAN
─────────────────────
Name:         {ComponentName}
Framework:    {React/Vue/Vanilla}
Type:         {hero/card/form/etc}
Styling:      {Tailwind/CSS Modules/etc}
Scope:        Component + Preview (default)
Storybook:    {yes — will generate CSF3 story / no — skipping}

Key Features:
- {feature_1}
- {feature_2}
- {feature_3}

Design Choices:
- Layout: {grid/flex/hybrid with rationale}
- Typography: {font families, scale, hierarchy}
- Colors: {palette with purpose and meaning}
- Motion: {animation approach and timing}
- Responsive: {breakpoint strategy and behavior}

Accessibility:
- ARIA labels: {yes/no, which ones}
- Keyboard nav: {tab order, focus management}
- Screen reader: {SR-only text, descriptions}
- Color contrast: {WCAG AA/AAA ratios}

Differentiation:
- What makes this distinctive: {unique design choice}
- How it avoids AI slop: {specific anti-patterns avoided}

---

HARD STOP — Review Design Plan

Present complete design summary to user.

Use AskUserQuestion:

• Question: "Proceed with generating the component code?"
• Header: "Generate Component"
• Options:
  • "Yes" — Generate the component
  • "No" — Cancel
  • "Edit" — Let me revise the design direction first

Do NOT proceed to Phase 2 without explicit approval.

---

PHASE 2: Generation (Write Phase)

Step 6: Generate Component Code

Create production-grade, framework-specific component code:

For All Frameworks:

1. Semantic structure — Use proper HTML5 elements (header, section, article, nav, button, etc.)
2. Accessibility — ARIA attributes, roles, keyboard handlers, focus management
3. Modern CSS — Grid, Custom Properties, Container Queries, modern selectors
4. Bold design — Distinctive typography, purposeful colors, unexpected layouts
5. Responsive — Mobile-first approach with fluid scaling
6. Comments — Inline documentation explaining non-obvious design choices

React Example Structure:

// Component with TypeScript props (if applicable)
// Clear prop documentation
// State management (if needed)
// Accessibility attributes
// Inline style comments explaining design choices

Vue Example Structure:

<!-- Template with semantic HTML -->
<!-- Props with TypeScript (if applicable) -->
<!-- Scoped styles with design tokens -->
<!-- Accessibility attributes -->

Vanilla HTML/CSS/JS Structure:

<!-- Semantic HTML structure -->
<!-- Progressive enhancement -->
<!-- CSS with custom properties -->
<!-- Minimal JS for interactivity -->

CSS Guidelines (All Frameworks):

• Use CSS custom properties for theming: --color-primary, --spacing-unit
• Modern features: clamp() for fluid typography, min(), max()
• Container queries for component-level responsiveness
• Smooth transitions: transition: all 0.2s ease-in-out
• Dark mode support (if needed): @media (prefers-color-scheme: dark)
• Reduced motion support: @media (prefers-reduced-motion: reduce)

Design Differentiation:

• Typography: Avoid Inter, Roboto, Arial — choose distinctive fonts
• Colors: Avoid generic purple gradients — use purpose-driven palette
• Layout: Avoid predictable grid — try asymmetry, overlap, diagonal flow
• Motion: Avoid scattered micro-interactions — focus on high-impact moments

Step 7: Generate Preview File

Create standalone HTML preview showing the component in action:

Preview File Structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{ComponentName} Preview</title>
  <!-- Import framework (CDN) if React/Vue -->
  <!-- Import component styles -->
</head>
<body>
  <!-- Component demonstration -->
  <!-- Multiple states if applicable (default, hover, active, disabled, etc.) -->
  <!-- Responsive preview at different viewport widths -->
</body>
</html>

Variants to show:

• Default state
• Interactive states (hover, focus, active)
• Different props/configurations (if applicable)
• Error/loading states (if applicable)
• Dark mode (if supported)

Step 7b: Generate Story File (Conditional)

Skip if storybook_available = false.

When Storybook detected in Step 2, generate a CSF3 story file alongside the component:

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/frontend-ui-workflow-reference.md section "CSF3 Story Format Spec" for the base template and rules.

1. Read existing *.stories.tsx files to match project conventions
2. Generate CSF3 story with Meta<typeof ComponentName> + StoryObj<typeof meta>
3. Cover states from Component State Coverage Matrix: Default, Loading, Error, Empty, variants
4. If component uses CVA: generate one story per variant value (see "CVA Variant Detection" in reference)
5. Map props to argTypes controls (see "argTypes Controls" in reference)

Story file: {id}-{slug}-stories.tsx

Step 8: Generate Documentation

Read template: $JAAN_TEMPLATES_DIR/jaan-to-frontend-design.template.md

Fill all sections:

• Executive Summary: 1-2 sentence overview (component type, framework, key design characteristic)
• Overview: Component metadata table
• Design Rationale: Why these aesthetic and technical choices? How does it avoid generic patterns?
• Usage: Installation, imports, basic example, props API
• Code: Reference to code file with key highlights
• Accessibility: WCAG compliance details, keyboard nav, screen reader support
• Responsive Behavior: Breakpoint behavior table
• Customization: CSS variables for theming
• Metadata: Generated date, skill version, output path

Step 9: Quality Check

Before preview, verify all items:

• Code is syntactically valid (no syntax errors)
• Semantic HTML used (proper elements, not div soup)
• Accessibility attributes present (ARIA labels, roles, keyboard handlers)
• Responsive design implemented (mobile-first, fluid scaling)
• Design choices are bold and distinctive (not generic)
• Color contrast meets WCAG AA (4.5:1 for text, 3:1 for UI elements)
• Focus indicators visible (not outline: none without replacement)
• Inline comments explain non-obvious choices
• No hardcoded values that should be design tokens
• Documentation is complete with all required sections

If any check fails, fix before proceeding.

Step 10: Preview & Approval

Show complete output to user:

• Component code (first 50 lines or full if short)
• Key design choices highlighted
• Documentation structure
• Preview file path

Use AskUserQuestion:

• Question: "Write component files to output?"
• Header: "Write Files"
• Options:
  • "Yes" — Write the files
  • "No" — Cancel
  • "Refine" — Make adjustments first

Step 10.5: Generate ID and Folder Structure

# Source ID generator utility
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"

# Define subdomain directory
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/frontend/design"
mkdir -p "$SUBDOMAIN_DIR"

# Generate next sequential ID
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")

# Create slug from component name (lowercase-kebab-case, max 50 chars)
slug="{component-name-slug}"

# Generate paths
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"
MAIN_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-${slug}.md"
CODE_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-${slug}-code.{jsx|vue|html}"
PREVIEW_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-${slug}-preview.html"
STORIES_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-${slug}-stories.tsx"  # if storybook_available

Preview output configuration:

Output Configuration

• ID: {NEXT_ID}
• Folder: $JAAN_OUTPUTS_DIR/frontend/design/{NEXT_ID}-{slug}/
• Files:
  • {NEXT_ID}-{slug}.md (documentation)
  • {NEXT_ID}-{slug}-code.{ext} (code)
  • {NEXT_ID}-{slug}-preview.html (preview)
  • {NEXT_ID}-{slug}-stories.tsx (CSF3 stories — if Storybook detected)

Step 11: Write Output

1. Create output folder:

   mkdir -p "$OUTPUT_FOLDER"
   

2. Write documentation file: Write filled template to $MAIN_FILE

3. Write component code file: Write generated code to $CODE_FILE

4. Write preview file: Write standalone preview to $PREVIEW_FILE

5. Write stories file (if storybook_available): Write CSF3 stories to $STORIES_FILE

6. Update subdomain index:

   source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
   add_to_index \
     "$SUBDOMAIN_DIR/README.md" \
     "$NEXT_ID" \
     "${NEXT_ID}-${slug}" \
     "{ComponentName}" \
     "{Executive summary — 1-2 sentences}"
   

7. Confirm to user:

   ✓ Component written to: $JAAN_OUTPUTS_DIR/frontend/design/{NEXT_ID}-{slug}/ ✓ Files created:

   • {NEXT_ID}-{slug}.md
   • {NEXT_ID}-{slug}-code.{ext}
   • {NEXT_ID}-{slug}-preview.html ✓ Index updated: $JAAN_OUTPUTS_DIR/frontend/design/README.md

Step 12: Suggest Next Actions

Present follow-up workflow options:

Component generated successfully!

Next Steps:

• Copy code from {CODE_FILE} to your project
• Open {PREVIEW_FILE} in browser to see live preview
• Run /jaan-to:frontend-visual-verify to visually verify the component (requires Storybook + Playwright MCP)
• Run /jaan-to:frontend-story-generate to generate additional stories for more component states
• Run /jaan-to:qa-test-cases "{MAIN_FILE}" to generate test cases
• Run /jaan-to:frontend-task-breakdown if you need integration tasks for larger feature

Step 13: Capture Feedback

Use AskUserQuestion:

• Question: "How did the component turn out?"
• Header: "Feedback"
• Options:
  • "Perfect!" — Done
  • "Needs fixes" — What should I improve?
  • "Learn from this" — Capture a lesson for future runs

If "Learn from this":

• Run /jaan-to:learn-add frontend-design "{feedback}"

---

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Framework-agnostic with tech.md detection
• Template-driven output structure
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

• Valid, working code generated
• Bold design choices implemented and documented
• WCAG AA accessibility met
• Responsive design (mobile-first) implemented
• Framework matches tech.md (or user choice)
• Documentation complete with all required sections
• Preview file works (if scope includes preview)
• CSF3 stories generated (if Storybook detected)
• Output follows v3.0.0 structure (ID, folder, index)
• Index updated with executive summary
• User approved final result