frontend-styleguide

What this skill does

# 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
```dot
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)
```dot
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:
```markdown
## 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:**
```javascript
/**
 * 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