Contractor‑Ready Component Spec: 20 UI Components with Props, States, and Acceptance Tests

A contractor‑ready component spec removes ambiguity by listing (1) the precise API/props the component accepts, (2) all visual states and interaction rules, (3) accessibility requirements (role, ARIA, keyboard), and (4) a compact acceptance test that QA or an engineer can run. Use the same structure for every component to avoid repeated design reviews and reduce implementation drift.

This article assumes your team can export component metadata from Figma into JSON (layers, variant names, tokens). Exporting a small JSON payload with names, props, and default values gives engineers a machine‑readable starting point; many Figma plugins and community tools support JSON exports of components and tokens so you can attach real artifact files to tickets.

Each component in the full downloadable catalog (below) follows a strict template: name, props (type + example), visual states, accessibility notes (role, ARIA, keyboard), and a one‑line acceptance test. That structure makes it possible to generate a JSON object a Figma plugin can export and a developer can read into Storybook or a test harness.

Here’s a fully worked example (Button — primary): you’ll find this pattern repeated for 20 components in the catalog: name: Button.Primary; props: label:string ("Save"), size: 'sm'|'md'|'lg', kind: 'primary'|'secondary'|'ghost', loading:boolean, disabled:boolean, iconLeft?:string, iconRight?:string; states: default, hover, pressed, focus, disabled, loading; accessibility: element <button> with accessible name from label or aria-label, support aria-pressed for toggle variants, keyboard focusable (Enter/Space), visible focus indicator; acceptance test: “Label reads 'Save', click triggers onClick once when enabled, visually shows loading state and disables input.”

Repeat that spec for each component type (inputs, selects, toggles, lists, modals, toasts, cards, chips, avatars). The point is exactness: name every prop type and allowed values — not “color” or “size” generically. That makes the JSON deterministic and testable.

For each component, include the programmatic role, required accessible name source (visible label or aria‑label), which ARIA state attributes must change (for example aria-checked, aria-pressed, aria-expanded), and keyboard behavior (tab order, activation keys). These are not optional notes — they belong in the spec so a contractor cannot omit them.

Reference WCAG/WAI‑ARIA guidance when specifying attributes. For example, toggle buttons should expose aria-pressed or role='switch' with aria-checked, and interactive elements must be reachable by keyboard and announce state changes. A single sentence in the acceptance test should verify the correct ARIA attribute update after user interaction.

Practical JSON shape: keep it flat and predictable. Example minimal payload for a Button variant: { "component": "Button.Primary", "props": { "label": "Save", "size": "md", "kind": "primary", "loading": false, "disabled": false }, "states": ["default","hover","pressed","focus","disabled","loading"], "accessibility": { "role": "button", "nameSource": "label", "aria": {} }, "acceptanceTest": "Click triggers onClick once when enabled and loading shows spinner" }.

Generate this JSON from Figma using available community plugins or small scripts that read variant names, text layers, and token references. Embedding this JSON into tickets or the design file ensures the contractor receives both a visual and a machine‑readable contract for behavior.

Before assigning a contractor, attach three artifacts to the ticket: (1) Figma file with named component variants and text layers, (2) exported JSON artifact per component, (3) one‑line acceptance tests that QA or the contractor can run locally. Use your ticket template to require a passing screenshot or Storybook link.

Examples of one‑line acceptance tests (you should include many of these verbatim): Button.Primary — “With label 'Save' enabled, a click calls onClick once and button shows loading spinner and becomes disabled.” Toggle/Switch — “Pressing space toggles aria-checked between 'true' and 'false' and the visible thumb moves to the correct side.” Modal — “Opening the modal traps focus inside, pressing Escape closes it, and aria-hidden is set on the background.”