Design - Components

This skill guides Claude through designing components and sections within an existing design system. Unlike design-concepts (which explores new visual identities), this skill works within established constraints — same fonts, same colors, same tokens — and finds creative variation through composition, layout, interaction, and information hierarchy.

Core Methodology

Why Constrained Variation Matters

A design system gives you vocabulary. This skill is about writing different sentences with the same words:

Same palette, different emphasis: Brand orange as a subtle border vs. a bold background vs. a gradient accent
Same type scale, different hierarchy: Large title + small body vs. medium everything + bold labels
Same spacing tokens, different density: Compact data table vs. airy editorial card
Same primitives, different composition: Stacked cards vs. side-by-side panels vs. tabbed sections

The goal is showing stakeholders that meaningful variety exists within the system — and helping pick the composition that best serves the component's purpose.

When to Create 3 Variations vs. 1

3 variations: New component type, section redesign, unclear requirements, stakeholder needs to choose
1 variation: Extending an existing pattern, minor variant of something that already works, clear requirements with no ambiguity

Step 1: System Audit

Before designing anything, understand what you're working with. Read the project's design system files.

Files to look for:

- globals.css / global styles (CSS variables, tokens, layers)
- tailwind.config.ts/js (theme extensions, custom values)
- Design token files (colors, spacing, typography scales)
- Component library (shadcn components, Radix primitives, custom components)
- Existing components similar to what's being designed
- Any design docs (docs/design/, docs/css-quick-reference.md, etc.)

What to catalog:

Color tokens: Brand colors, semantic colors, neutral scale, accent colors, dark mode variants
Typography: Font families, size scale, weight scale, any utility classes (.text-page-title, .heading-font, etc.)
Spacing: Token scale (if semantic like section/card/element/rhythm, or numeric like Tailwind defaults)
Animation: Custom durations, easings, keyframes, transition patterns, motion preference support
Component primitives: What's already built — cards, buttons, badges, dialogs, inputs, etc.
Patterns in use: How existing components handle states, hover effects, responsive behavior, dark mode

Output: A brief system audit summary (mental model, not a separate file) that captures what tokens and patterns are available. Reference specific variable names and class names — these are the building blocks for concepts.

Reading the System's Personality

Every design system has a personality even if it wasn't consciously designed. Before composing new components, identify it:

Opal Creek type: Semantic and structured — named spacing tokens (section-lg, card-md), service-specific colors, utility-class typography. Wants consistency and predictability.
ProSocial type: Dynamic and stateful — tiered color progressions, state machine components, gamified micro-interactions. Wants energy and feedback.
DOA type: Atmospheric and textural — glassmorphism, text-stroke effects, gradient animations. Wants mood and visual drama.
Portfolio type: Systematic and polished — comprehensive token coverage, custom easings, staggered animation delays. Wants precision and craft.

Match your composition approach to the system's personality. A compact data-dense card might be right for a structured system; an animated progressive-reveal card might be right for a dynamic one.

Step 2: Component Brief

Ask the user (or extract from context):

What: What component or section? (a card, a nav bar, a hero section, a settings panel, a dashboard widget)
Purpose: What job does this component do for the user? What information does it convey or what action does it enable?
Context: Where does this live in the app? What's around it? What page/view?
Content: What data or content does it display? Be specific — names, numbers, labels, images, icons.
States: What states does it need? (empty, loading, error, populated, hover, active, disabled, selected, expanded/collapsed)
Responsive: Mobile-first? Desktop-only? Needs to work at both extremes?
Constraints: Anything off-limits? Any must-haves? Technical constraints?

If the user gives a brief answer ("design a task card"), fill in reasonable assumptions from the system audit and existing components, then confirm before proceeding.

Step 3: Pattern Research

Two types of research, both quick:

Internal Patterns

Look at how the project already handles similar components:

Search the codebase for components with similar purposes
Note which tokens, layouts, and interaction patterns are already established
Identify conventions (do cards have borders or shadows? do sections use consistent padding tokens?)

External Patterns

Quick web search for best practices:

web_search: "best [component type] UI patterns 2025"
web_search: "[component type] accessibility requirements WCAG"
web_search: "[component type] responsive design patterns"

Focus on: accessibility requirements for the component type, interaction patterns that work well, content hierarchy approaches, common mistakes to avoid.

Step 4: Composition Strategy

Composition Lenses

Instead of aesthetic lenses (the component design equivalent of design-concepts' lens system), select composition lenses — different strategies for arranging and presenting the same content within the same design system.

Pick 3 lenses from these categories. Mix across categories for variety.

Layout Lenses

Lens	Character	Good For
Dense/Compact	Maximum info per pixel, tight spacing, small type	Data-heavy dashboards, list views, power-user tools
Spacious/Editorial	Generous whitespace, large type, breathing room	Marketing sections, hero areas, onboarding, single-focus
Modular/Grid	Card grid, uniform modules, scannable	Galleries, dashboards, feature grids, pricing tables
Asymmetric/Featured	One dominant element + supporting details	Hero + sidebar, featured item + list, media + text
Stacked/Sequential	Vertical flow, clear reading order, progressive	Forms, timelines, step-by-step, mobile-first content

Interaction Lenses

Lens	Character	Good For
Static/Informational	Read-only, clear hierarchy, no interaction needed	Status displays, summaries, reports, confirmation states
Interactive/Explorable	Hover reveals, click-to-expand, inline actions	Data tables, cards with actions, expandable panels
Progressive/Layered	Show summary first, reveal detail on demand	Complex data, mobile views, settings with advanced options
Animated/Transitional	State changes through motion, staggered reveals	Dashboards on load, status changes, gamified UI

Emphasis Lenses

Lens	Character	Good For
Color-Forward	Bold use of system colors, colored backgrounds, gradient accents	CTAs, status indicators, branded sections, categories
Typography-Forward	Size contrast, weight hierarchy, type as design element	Editorial, headings-heavy, text-content sections
Space-Forward	Whitespace as design element, minimal decoration	Premium feel, single-purpose screens, focus states
Border/Structure	Visible containers, dividers, outlined elements	Complex layouts, data organization, forms

How to Select Lenses

Review the system audit — what does this design system do well?
Consider the component's purpose — a data table and a hero section want very different compositions
Pick 3 combinations that produce meaningfully different components
At least one should be a stretch — unexpected but defensible for this use case
Tell the user your lens selections before building

Example:

For a "care task card" in a system with tiered colors, state progressions, and semantic spacing:

Lens 1: Dense/Compact + Interactive — Tight card with inline actions, hover-reveal details

Lens 2: Stacked/Sequential + Progressive — Full-width row that expands to show details

Lens 3: Modular/Grid + Color-Forward — Color-coded card with status-driven background tiers

Step 5: Creating Concepts

Ground Rules

Every concept MUST:

Use only tokens, colors, fonts, and spacing from the existing design system
Reference actual CSS variable names, Tailwind classes, or token names in annotations
Work with the project's component library primitives (if shadcn, use shadcn; if custom, extend custom)
Handle all required states (not just the happy path)
Meet baseline accessibility (4.5:1 contrast, focus states, semantic HTML)
Show responsive behavior (or note how it adapts)

What Differentiates the 3 Concepts

Since the aesthetic is fixed by the design system, concepts differ through:

Dimension	How It Varies
Layout	Grid vs. stack vs. asymmetric vs. table
Information density	Everything visible vs. progressive disclosure vs. summary-only
Token emphasis	Which colors are foregrounded, which spacing scale is used
Interaction model	Static vs. hover-reveals vs. click-to-expand vs. animated transitions
Content priority	What's biggest/first — title? image? status? action?
State handling	How empty/loading/error states are communicated

Concept Format

Concepts are HTML files that use the project's design tokens. Embed the token values directly so the HTML is self-contained and viewable in a browser.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[Component] - Concept [N]: [Lens Name]</title>
  <!-- Load the project's actual fonts -->
  <style>
    /*
     * Design System Tokens (from project's globals.css / tailwind.config)
     * Using actual variable names for traceability
     */
    :root {
      /* Paste relevant tokens here */
    }

    /* Component styles using only system tokens */
  </style>
</head>
<body>
  <!-- Component with realistic content, not Lorem Ipsum -->

  <!--
    ANNOTATIONS:
    Explain key composition decisions and which tokens are used where.
    Connect decisions back to the component's purpose.
  -->

  <!-- Show multiple states: default, hover, active, empty, etc. -->
</body>
</html>

Per-Concept Requirements

Each concept MUST include:

Lens name stated explicitly
Composition rationale: Why this layout/interaction/emphasis for this component
Token mapping: Which system tokens are used and where (e.g., "uses --color-brand-orange for status border, spacing-card-md for internal padding")
State showcase: All required states rendered on the same page
Responsive notes: How it adapts (or annotations if the HTML doesn't demonstrate it)

Concept Refinement

After the user picks a direction:

Refine the chosen concept based on feedback
Increase fidelity — nail all states, interactions, edge cases
Prepare for handoff to implementation
The refined concept HTML should be close enough to the final intent that a developer could implement from it

Step 6: In-Situ Preview

After the user picks a direction and the concept is refined, create an in-situ preview — an HTML file that shows the recommended component in the context of the full screen/page where it will live. This is not a pixel-perfect reproduction; it's a simplified representation of the surrounding UI that gives stakeholders a feel for how the component sits within the page.

Why In-Situ Matters

Isolated component previews answer "what does the component look like?" In-situ previews answer "what does the page feel like with this component?" — which is what stakeholders actually need to approve. A CTA bar that looks great in isolation might feel cramped when the bottom bar, scrollable content, and header are all present.

What to Include

Simplified page chrome: Header/nav, content area, any fixed elements (bottom bars, sidebars) — represented as gray blocks with labels, not fully detailed
Realistic content zone: Enough real-looking content (text, cards, images as placeholder boxes) to convey scroll position and density
The actual component: Rendered at full fidelity using the refined concept's styles and tokens
Phone frame: Wrap the preview in a device frame (375×812 for mobile, or appropriate viewport) so the proportions are accurate
Multiple states: Show the component in its key states (2-3 frames side by side if the component has distinct phases)

What NOT to Include

Don't rebuild the entire page — simplified representations of surrounding UI are fine
Don't add interactive JavaScript — static HTML snapshots of each state
Don't introduce new design decisions for the surrounding UI — use neutral grays and labels

File Naming

docs/design/{component-name}-components-{MMDDYY}/
└── {component-name}-in-situ.html

Template Structure

<!-- Device frame with realistic viewport proportions -->
<div class="device-frame" style="width: 375px; height: 812px; ...">
  <!-- Simplified header/nav -->
  <div class="page-header">...</div>

  <!-- Scrollable content area (enough to show context) -->
  <div class="page-content">...</div>

  <!-- THE COMPONENT — full fidelity from refined concept -->
  <div class="component-zone">...</div>

  <!-- Any other fixed elements (bottom bars, etc.) -->
  <div class="fixed-bottom">...</div>
</div>

Show 2-3 device frames side by side for key states (e.g., Phase 1 and Phase 2).

Step 7: Presentation

File Organization

docs/design/{component-name}-components-{MMDDYY}/
├── {component-name}-concept-1-{lens-name}.html
├── {component-name}-concept-2-{lens-name}.html
├── {component-name}-concept-3-{lens-name}.html
└── {component-name}-overview.md

Component Name Guidelines:

Use kebab-case (lowercase with hyphens)
Be specific: care-task-card, service-hero-section, settings-panel, activity-dashboard
Ask the user for the name if not obvious from context

Overview Document

File: {component-name}-overview.md

# [Component Name] — Design Concepts

## Component Purpose
[What this component does, where it lives, who uses it]

## Design System Context
- **Project**: [project name]
- **Token source**: [globals.css, tailwind.config, etc.]
- **Key tokens used**: [list the most relevant colors, spacing, typography tokens]
- **Existing patterns referenced**: [similar components in the codebase]

## Concept 1: [Name] — [Lens Combination]
**Composition**: [Layout + Interaction + Emphasis lens]
**Approach**: [How this arranges content and why]
**Strengths**: [What this does well for the component's purpose]
**Tradeoffs**: [What this sacrifices — density vs. clarity, simplicity vs. power]
**Tokens highlighted**: [Which system tokens are most prominent]

## Concept 2: [Name] — [Lens Combination]
...

## Concept 3: [Name] — [Lens Combination]
...

## Recommendation
[Which concept best serves the component's purpose and why]

## Next Steps
- [ ] Gather feedback on the 3 directions
- [ ] Refine chosen concept with [specific details]
- [ ] Hand off to implementation

Quality Criteria

Excellent Component Concepts:

System-native: Could not exist outside this specific design system — tokens are visible in the design
Compositionally distinct: Each concept arranges information and interaction differently, not just color-swapped
State-complete: Shows all required states, not just the happy path
Realistic content: Uses actual or realistic data, not "Title Here" / "Description text"
Annotated: Key composition decisions are explained with WHY, tied to component purpose
Accessible: Color contrast meets 4.5:1, focus states exist, semantic HTML structure
Responsive-aware: Either demonstrates responsive behavior or clearly annotates how it adapts
Traceable: Annotations reference actual token names from the system audit

Red Flags:

Concepts that introduce colors, fonts, or spacing not in the design system
Three concepts that only differ in border-radius or shadow
Missing states (especially empty and error)
Placeholder content hiding layout problems
No reference to actual system tokens

Common Pitfalls

Escaping the System

Problem: "This would look better with a different font" — introducing off-system values Instead: Find variety within the system. If the system only has one font, vary weight, size, case, and spacing. Constraints breed creativity.

Surface-Level Variation

Problem: Three concepts that are the same layout with different colored headers Instead: Change the layout structure, the interaction model, or the information hierarchy. A card and a list row are fundamentally different even if they show the same data.

Happy-Path-Only Design

Problem: Concepts only show the component with perfect data Instead: Design the empty state, the loading state, the error state, the overflow state. These reveal whether the composition actually works.

Ignoring What Already Exists

Problem: Designing a card without looking at the project's existing cards Instead: Read existing components first. Extend patterns rather than inventing new ones. If the project uses shadows on cards, don't switch to borders without reason.

Over-Annotating the Obvious

Problem: "This uses padding because padding creates space" Instead: Annotate the non-obvious — why this token over another, why this layout over the simpler option, why this state treatment connects to the component's purpose.

Integration Points

Inputs

Design System: globals.css, tailwind.config, existing components (REQUIRED)
Design Research: Personas, user needs, interaction preferences (if available)
Design Concepts: If a visual direction was already chosen, component design extends that direction
Product Requirements: What the component needs to do, what data it handles

Outputs

Implementation: HTML concepts close enough to code from directly

Related Skills

design-system-init: Use first if no design system exists yet
design-concepts: Use instead if you need a new visual direction, not a new component

Validation Checklist

Before delivering component concepts, verify:

design-components