Generating Frontend Styleguides

Overview

A frontend styleguide is a living document that defines visual patterns, component APIs, and reusable code for a web project. This skill ensures you create comprehensive, efficient styleguides without wasting context on repeated exploration. Core principle: Explore once with subagent, document findings permanently to CLAUDE.md, never explore again.

When to Use

Use this skill when the user asks to:

• "Create a style guide"
• "Document our component library"
• "Build a design system"
• "Make reusable components"
• "Standardize our frontend patterns"
• "Update the style guide"
• "Add a component to the style guide"
• "Edit existing components"

First: Creating vs Editing Decision

digraph create_vs_edit {
    "User requests styleguide work" [shape=doublecircle];
    "CLAUDE.md has Frontend Style Guide section?" [shape=diamond];
    "Creating NEW style guide" [shape=box];
    "Editing EXISTING style guide" [shape=box];
    "Follow creation workflow" [shape=box];
    "Use CLAUDE.md context ONLY" [shape=box];
    "User requests styleguide work" -> "CLAUDE.md has Frontend Style Guide section?";
    "CLAUDE.md has Frontend Style Guide section?" -> "Creating NEW style guide" [label="no"];
    "CLAUDE.md has Frontend Style Guide section?" -> "Editing EXISTING style guide" [label="yes"];
    "Creating NEW style guide" -> "Follow creation workflow";
    "Editing EXISTING style guide" -> "Use CLAUDE.md context ONLY";
}

CRITICAL RULE: If CLAUDE.md already has a "Frontend Style Guide" section, you are EDITING. Do NOT re-explore. Use only the documented context in CLAUDE.md.

Creation Workflow (New Style Guides Only)

digraph styleguide_creation {
    "Creating new style guide" [shape=doublecircle];
    "Ask design preferences" [shape=box];
    "Launch Explore subagent" [shape=box];
    "Document findings to CLAUDE.md" [shape=box];
    "Use frontend-design skill" [shape=box];
    "Create reusable components" [shape=box];
    "Done" [shape=doublecircle];
    "Creating new style guide" -> "Ask design preferences";
    "Ask design preferences" -> "Launch Explore subagent";
    "Launch Explore subagent" -> "Document findings to CLAUDE.md";
    "Document findings to CLAUDE.md" -> "Use frontend-design skill";
    "Use frontend-design skill" -> "Create reusable components";
    "Create reusable components" -> "Done";
}

Editing Workflow (Existing Style Guides)

When CLAUDE.md already has a "Frontend Style Guide" section:

1. Read CLAUDE.md ONLY - All context you need is already documented
2. Use frontend-design skill - Before creating new components
3. Create/update components - Using existing patterns from CLAUDE.md
4. Update CLAUDE.md - Add new component to inventory NEVER:

• Re-run Explore subagent when editing
• Use Grep/Glob to "check for changes"
• Read unnecessary files
• "Verify" the documented structure Why: You already explored once and documented everything. Re-exploring wastes context. Trust the CLAUDE.md documentation.

Step 1: Ask Design Preferences FIRST

Before any exploration, ask the user these questions using AskUserQuestion:

1. Design System/Framework:
   • "Which design system or framework should we follow?"
   • Options: shadcn/ui, Material UI, Bootstrap, Tailwind CSS, Custom, Other
   • Include description of what each provides
2. Typography:
   • "Should we include/exclude custom fonts?"
   • Options: User will specify fonts, Figure it out based on this vibe (user input)
   • If Google Fonts selected, ask which font families
3. Additional Components (optional):
   • "Are there any specialized components beyond standard UI elements you need?"
   • Let user list any domain-specific components (charts, calendars, specialized inputs) CRITICAL: Do NOT skip these questions. Design system choice affects everything.

Step 2: Launch Explore Subagent

REQUIRED: Use Task tool with

subagent_type: "Explore"

and only in the frontend/ . Do NOT explore or access any NextJS code or other executable code directories e.g.

node_modules/

or

.next/

Never use direct Glob/Grep for codebase exploration. The Explore agent is 50-100x more context-efficient. Exploration parameters:

Task tool with:
- subagent_type: "Explore"
- thoroughness: "medium"
- prompt: "Explore the frontend codebase structure. Find:
  1. Component directory structure
  2. Styling methodology (CSS modules, Tailwind, styled-components, etc.)
  3. Existing component patterns and naming conventions
  4. Any existing design tokens or theme configuration
  5. Build tooling and framework (React, Vue, etc.)
  EXCLUDE: node_modules, dist, build, .next, out, coverage, any installation/executable directories
  Summarize findings in a structured format."

Why Explore subagent: Saves 50-100x context vs running multiple Glob/Grep commands yourself.

Step 3: Document Findings to CLAUDE.md

IMMEDIATELY after Explore completes, write findings to

.claude/CLAUDE.md

in a dedicated section:

## Frontend Style Guide
### Project Structure
[Component directories, file organization]
### Styling Approach
[CSS methodology, design tokens, theme system]
### Existing Patterns
[Component patterns, naming conventions]
### Design System
[Framework: shadcn/ui / Material UI / etc.]
[Fonts: Google Fonts - Roboto, Open Sans / System fonts]
### Component Inventory
#### Standard Components
- Button (variants: primary, secondary, outline)
- Input (text, email, password, textarea)
- Card (basic, with header, with actions)
- Modal (dialog, drawer, alert)
- Navigation (navbar, sidebar, tabs)
[etc.]
#### Custom Components
[Any domain-specific components]

Why document to CLAUDE.md: This becomes permanent project context. You'll never need to re-explore. Future sessions load this instantly.

Step 4: Use frontend-design Skill

REQUIRED: Before creating any components, invoke the frontend-design skill:

Skill tool with:
- skill: "frontend-design:frontend-design"

The frontend-design skill ensures:

• Distinctive, production-grade aesthetics
• Proper accessibility patterns
• Modern, polished implementation
• Avoids generic AI aesthetics Do not create components without using this skill. It's the difference between generic and professional.

Step 5: Create Reusable Component Functions

Components must be functions that can be reused, not just documentation. Structure per component:

/**
 * Button Component
 *
 * @param {Object} props
 * @param {'primary'|'secondary'|'outline'} props.variant - Button style variant
 * @param {'sm'|'md'|'lg'} props.size - Button size
 * @param {boolean} props.disabled - Disabled state
 * @param {React.ReactNode} props.children - Button content
 * @param {Function} props.onClick - Click handler
 * @returns {React.ReactElement}
 */
export function Button({
  variant = 'primary',
  size = 'md',
  disabled = false,
  children,
  onClick
}) {
  // Implementation using design system specified
}

Save to:

src/components/

or existing component directory (match project structure). Update CLAUDE.md with component location and usage after creation.

Standard Components (Include by Default)

Unless user specifies otherwise, include these common UI components: Titles, Headers, Text, Headers, Footers Form Elements:

• Button (primary, secondary, outline, ghost variants)
• Input (text, email, password, number)
• Textarea
• Select/Dropdown
• Checkbox
• Radio buttons
• Switch/Toggle Layout:
• Container
• Card
• Grid
• Stack/Flex Navigation:
• Navbar
• Sidebar
• Tabs Feedback:
• Alert/Toast
• Modal/Dialog
• Tooltip
• Loading spinner
• Progress bar Data Display:
• Table
• Badge
• Avatar
• Divider User requested only: Charts, calendars, specialized domain components.

File Organization

Component files:

src/components/[ComponentName]/

or project's existing structure Style guide documentation:

.claude/CLAUDE.md

(section: "Frontend Style Guide") Component demos (if requested): Create separate demo file or Storybook stories Never create in root directory. Match existing project structure.

Common Mistakes

Mistake	Reality
"I'll just grep for components quickly"	Explore subagent is faster and uses 50-100x less context
"I'll document later"	Document to CLAUDE.md immediately or you'll waste context re-exploring
"User knows what design system they want"	Always ask explicitly. Assumptions lead to rework
"Standard components are obvious"	Your standard ≠ their standard. Check existing codebase
"I'll create generic components first"	Use frontend-design skill for professional quality
"I can skip fonts question"	Font choice affects entire design. Always ask
"I should re-explore to verify changes"	CLAUDE.md is the source of truth. Never re-explore when editing
"Let me check the codebase for updates"	If editing, use only CLAUDE.md context. No file reads needed

Red Flags - STOP and Follow Workflow

These thoughts mean you're cutting corners: When Creating:

• "Let me just grep the components directory"
• "I'll explore manually instead of using subagent"
• "I'll remember the findings, no need to document"
• "I'll assume they want Material UI"
• "Standard buttons are simple, I'll skip frontend-design"
• "I don't need to ask about fonts" When Editing:
• "Let me re-explore to see what changed"
• "I should verify the structure with Glob"
• "Let me read the component files to check patterns"
• "I'll just quickly grep to confirm"
• "Maybe the CLAUDE.md documentation is outdated" All of these mean: Stop. Follow the correct workflow (Creating vs Editing).

Exclusions (Never Explore)

ALWAYS exclude these from exploration:

• node_modules/

• dist/

  ,

  build/

  ,

  out/

  ,

  .next/

• coverage/

  ,

  .coverage/

• __pycache__/

  ,

  .pytest_cache/

• Any installation or executable directories

• .git/

• .trunk/

  Why: Wastes context, no useful information for style guides.

Quality Checklist

For Creating New Style Guide:

• Checked if CLAUDE.md has existing "Frontend Style Guide" section (if yes, you're editing not creating)
• Asked about design system (shadcn/ui, Material UI, Bootstrap, Tailwind, etc.)
• Asked about fonts (Google Fonts vs system fonts)
• Used Explore subagent (not direct Glob/Grep)
• Documented findings to

  .claude/CLAUDE.md

  immediately
• Used frontend-design skill before creating components
• Created reusable component functions (not just docs)
• Included all standard components (or confirmed with user)
• Updated CLAUDE.md with component locations For Editing Existing Style Guide:
• Confirmed CLAUDE.md has "Frontend Style Guide" section
• Read CLAUDE.md section ONLY (did not re-explore)
• Did NOT use Explore, Glob, or Grep to "verify"
• Used frontend-design skill before creating new components
• Created/updated components using patterns from CLAUDE.md
• Updated CLAUDE.md component inventory with new additions

The Bottom Line

Explore once. Document permanently. Create professionally. Style guides fail when you:

1. Waste context re-exploring because you didn't document
2. Create generic components because you skipped frontend-design
3. Build wrong components because you assumed instead of asked Follow this workflow to avoid all three.