Frontend Component Build

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.

---