git:20260505.c80b896 to git:20260507.ac2b078

---

name: frontend-component-build

description: "Build production-ready frontend components with accessible markup, sensible props, defined states, and tested behavior. Use this skill whenever the user wants to build a component from scratch, refactor an existing one, design a component API, or implement a UI element with proper states and accessibility. Triggers on build a component, create a button, create a modal, create a form input, component API, props design, component states, refactor component, accessible component. Also triggers when implementing UI from a design that needs to be reusable."

category: development

catalog_summary: "Component architecture, props design, accessibility from the start"

display_order: 2

---

# Frontend Component Build

Build production-ready components. Stack-agnostic principles. Most patterns translate to React, Vue, Svelte, or vanilla web components.

This skill is about implementing a component well. For broader system design see `design-system`. For day-to-day visual decisions see `design-standards`.

---

## When to use

- Building a new component from scratch

- Refactoring an existing component

- Designing a component API (props, slots, events)

- Adding accessibility to an existing component

- Implementing a component from a design

## When NOT to use

- Building a full design system (use `design-system`)

- Page-level design decisions (use `design-standards`)

- Backend or data work (use `code-review-web`)

- Performance-only optimization (use `performance-optimization`)

---

## Required inputs

- The component's purpose (what UI need it serves)

- The design (or willingness to design it)

- The framework or technical context

- The states the component must support

- Accessibility requirements

---

## The framework: 6 dimensions

A complete component handles six dimensions. Skip any one and the component is incomplete.

### 1. Anatomy

Identify the parts that make up the component before writing any markup.

**Common anatomies:**

- Button: container + label + (optional) icon + (optional) loading indicator

- Modal: backdrop + container + header + body + footer + close affordance

- Form input: label + input + (optional) help text + (optional) error message

- Card: container + (optional) header + body + (optional) footer + (optional) media

Naming the parts up front makes the API obvious.

### 2. Variants

What variations does the component support?

- **Visual variants** (primary, secondary, ghost, danger)

- **Size variants** (small, medium, large)

- **Functional variants** (with icon, without icon, icon-only)

Variants should be a managed set, not a free-for-all. Document the supported set; reject requests for new variants without a real use case.

### 3. States

What states must the component handle?

- **Default**

- **Hover** (when pointer is supported)

- **Focus** (always - keyboard navigation requires it)

- **Active / pressed**

- **Disabled**

- **Loading** (where applicable)

- **Error** (for inputs, forms, validation-bound components)

- **Empty** (for components that display data)

Every state needs visual treatment AND accessibility treatment.

### 4. Props / API

Design the component's contract.

**API design principles:**

- **Required props minimal.** What's truly needed every time? That's required. Everything else has a sensible default.

- **Boolean props are red flags.** Three booleans means seven combinations. Prefer enum strings: `variant: "primary" | "secondary" | "ghost"` over `primary={true} ghost={false}`.

- **Children > props.** Where content is content, accept children. Don't invent `headerText` and `bodyText` props when slots work.

- **Composition > configuration.** A component that does 5 things via 12 props often should be 5 smaller components.

- **Type the props.** TypeScript or PropTypes or JSDoc. The type is documentation that won't go out of date.

### 5. Accessibility

Build it accessible from the start. Adding accessibility later is 5x harder.

**Universal:**

- Semantic HTML elements (`<button>`, `<a>`, `<nav>`, `<form>`, etc.) over generic `<div>`

- Keyboard navigable (Tab, Shift+Tab, Enter/Space for buttons)

- Focus visible

- Tap targets minimum 44 by 44 pixels

- ARIA only where semantic HTML is insufficient

**Component-specific:**

- **Button:** use `<button>`. Don't fake one with a `<div>`.

- **Modal:** focus trap, ESC to close, returns focus to trigger on close, `role="dialog"` and `aria-labelledby`.

- **Form input:** label associated via `for`/`id` or `aria-labelledby`. Error messages linked via `aria-describedby`. `aria-invalid` when in error state.

- **Toggles:** `<button>` with `aria-pressed` for two-state, or `role="switch"` for on/off.

- **Tabs:** `role="tablist"` / `role="tab"` / `role="tabpanel"` with `aria-selected` and arrow-key navigation.

- **Tooltips and popovers:** triggered by focus AND hover. Dismissible with ESC.

- **Loading states:** announce with `aria-live` so screen readers know something changed.

### 6. Tests

Verify the component works before declaring it done.

**Test types by priority:**

1. **Visual regression.** Renders correctly across variants and states. (Storybook + visual diff tools, or manual screenshots.)

2. **Accessibility.** Passes axe or equivalent automated checks.

3. **Keyboard navigation.** Tab, Enter, Escape, arrow keys all work as expected.

4. **Component logic.** Props produce expected output. Events fire correctly. (Unit tests.)

5. **Integration.** Component works inside its expected parent contexts.

A component without at least automated accessibility testing is not done.

---

## Workflow

1. **Understand the use case.** What UI need does this component serve? Where will it appear? Adjacent components?

2. **Sketch the anatomy.** Name the parts.

3. **List variants and states.** Match the design system or define new ones if needed.

4. **Design the API.** Required props, optional props, children, events. Type it.

5. **Build the markup with semantic HTML.** Choose the right elements. Avoid generic `<div>` for interactive things.

6. **Style with tokens.** No hardcoded colors, spacing, or sizes.

7. **Add interaction.** Focus management, keyboard handlers, ARIA.

8. **Add states.** Hover, focus, active, disabled, loading, error.

9. **Test.** Automated accessibility, keyboard navigation, visual regression.

10. **Document.** Usage, API, examples, anti-patterns.

---

## Failure patterns

- **Building with `<div onClick>`.** Loses keyboard accessibility, screen reader semantics, and focus. Use `<button>` or `<a>`.

- **Hardcoding colors and sizes.** Tokens exist for a reason. Hardcoded values resist theming and consistency.

- **Boolean prop explosion.** `<Button primary large rounded fullWidth disabled icon />`. Too many booleans means you actually need fewer variants designed more thoughtfully.

- **Forgetting focus states.** Hover gets attention; focus gets neglected. Keyboard users see invisible buttons.

- **Skipping disabled-state thought.** A disabled button should look obviously disabled AND be `aria-disabled` AND not respond to clicks.

- **Inventing ARIA.** ARIA roles and properties have specific behaviors. Made-up ARIA is worse than no ARIA. Use semantic HTML first.

- **Loading state that doesn't announce.** Screen readers don't know the spinner appeared. Use `aria-live="polite"` or `role="status"`.

- **Tooltip-only critical content.** Hover-only content is invisible to keyboard and touch users. Critical content goes in the visible UI.

- **Component without docs.** Future-you, your teammate, or the next maintainer cannot use what they cannot understand.

---

## Output format

A complete component delivery includes:

- **Component code** (in the appropriate framework)

- **Storybook (or equivalent) entry** showing all variants and states

- **Documentation:**

- Anatomy diagram or description

- Props/API table

- Usage examples (basic, advanced, edge cases)

- When to use vs. when to use an alternative

- Anti-patterns (what to avoid)

- Accessibility notes

- **Tests** (visual regression + accessibility + logic)

---

## Reference files