skip to content

In a design-system component library, what separates a headless component from a styled one, and when should a team choose headless?

level: middleimportance: must knowfreq 52%

answer

  1. behaviour without looks
  2. state, keys, focus, semantics
  3. two layers, one behaviour
  4. values differ versus structure differs
  5. the consumer owns the visuals

basics

~20 s

A headless component supplies behaviour — state, keyboard handling, focus and accessibility semantics — and ships no styling; a styled component adds the system's look on top. Choose headless when a product's visuals differ beyond what theming can express.

solid answer

~40 s

A **headless** component implements behaviour only: its state, its keyboard contract, focus handling and roles and states, with no visual design. A **styled** component is the same behaviour wrapped in the system's look. Many libraries ship both as **two layers**, so the behaviour is written and tested once. For a news publisher with a national daily, a sports title and a lifestyle magazine, colour and type differences are a **theming** job and the styled layer serves them. When the sports title's live-score tabs need a structurally different look, it builds on the **headless** layer rather than fighting the styled one. The cost is real: the consuming team now owns visuals, including focus visibility, contrast and layout, so headless suits teams with design-system skill, not every product team.

go deeper

for a junior

Recall that headless means behaviour without styling and styled means behaviour plus the system's look, and that most product screens should use the styled layer.

for a middle

Explain what the headless layer guarantees — state, keyboard contract, focus, semantics — and where the boundary with theming lies: values differ versus structure differs.

for a senior

Judge when a team should build on headless, and list what it takes on: visible focus, contrast, layout and support. Show how a shared headless core keeps styled variants consistent.

for a principal

Decide whether the library exposes the headless layer publicly at all, weighing sub-brand freedom against consistency and a support burden the system team cannot see.

## Two layers in one library A **headless component** is a component that implements *behaviour* and renders no visual design of its own: it manages state (which tab is selected, which panel is open), keyboard interaction, focus movement and the roles and states assistive technology reads. A **styled component** takes that behaviour and applies the design system's look — spacing, colour, type, borders, motion. Many mature libraries are built as **two layers**: | Layer | Owns | The consumer supplies | |---|---|---| | Headless (behaviour) | state, keyboard contract, focus, roles and states | all visuals, most structure | | Styled (presentation) | the system's visual design on top of the headless layer | content and a few options | The styled layer is usually implemented *on* the headless layer, so there is one behaviour implementation, tested once, used everywhere. ## What the headless layer guarantees - **State**: selection, expansion, the highlighted option, with controlled and uncontrolled use. - **Keyboard contract** from the WAI-ARIA Authoring Practices. For a horizontal tab list, Left Arrow and Right Arrow move focus between tabs and wrap from the last to the first; for a disclosure, Enter and Space toggle the content. - **Focus management**: where focus lands when a panel opens or a popup closes. - **Semantics**: the roles and states that describe the widget in the accessibility tree. What it does *not* guarantee: that the result looks right, that the focus indicator is visible, that text has enough contrast, or that the layout holds on a small screen. Those move to whoever writes the visual layer. ## Theming or headless? The boundary A news publisher runs a national daily, a sports title and a lifestyle magazine from one design system. It is easy to reach for headless too early. The dividing line is: - **The values differ** — colours, fonts, radii, spacing density. That is a **theming** problem: the styled components stay, and each masthead gets its own theme. - **The structure or visual language differs** — the sports title's live-score tabs are a horizontal scoreboard strip with team crests; the magazine's explainer accordion is full-bleed with large imagery. No set of theme values turns the standard tabs into a scoreboard. That is where **headless** earns its place. ## When to choose which 1. **Default to the styled layer.** Most product screens want the system's look, and the styled layer delivers it with the fewest decisions. 2. **Choose headless for genuinely different visual structure**, for a sub-brand whose design language diverges, or for a surface the styled components were never designed for. 3. **Choose headless for the system team itself**: building the styled layer on headless primitives keeps behaviour identical across every styled variant. 4. **Avoid headless as a way to dodge the system**: a team that only wants a slightly different border should ask for an option or a theme value, not rebuild the visuals. ## The costs of going headless - **Visual responsibility moves to the consumer.** Focus visibility, contrast, spacing, motion and responsive behaviour are now the consuming team's job. - **Consistency drops.** Every headless consumer can look different; that is the point, and also the risk. - **Support gets harder.** The system team can no longer reproduce an issue from a screenshot, because the visuals are not theirs. - **Accessibility is only partly inherited.** The keyboard contract and semantics come with the behaviour, but labels, headings, visible focus and contrast still depend on what the consumer writes. ## The same split on native platforms Native mobile libraries follow the same shape when they separate a widget's state and interaction logic from its rendering: one behaviour model, several visual treatments. A cross-platform system can share the behaviour specification — states, transitions, keyboard and assistive-technology contract — even when each platform implements rendering differently.

  • What accessibility work remains with a team that builds its tabs on a headless component?
    The headless layer brings the keyboard contract, focus movement and the roles and states. The consuming team still owns a visible focus indicator, text and indicator contrast, meaningful tab labels, and a layout that survives zoom and small screens. Headless removes the hardest behaviour work, not the visual accessibility work.
  • Why do many libraries build their own styled layer on top of their headless layer?
    It keeps one implementation of behaviour. Every styled variant, and every team building directly on headless, gets the same state handling and keyboard contract, tested once. Without the shared layer, styled components and custom builds drift apart in subtle behavioural ways that are hard to find.
  • A masthead wants rounder corners and its own typeface on every component; is headless the answer?
    No. Those are value differences, and a theme per masthead handles them while keeping the styled components. Headless is for structural or visual-language differences no theme can express. Reaching for headless here would hand the masthead all the visual responsibility for a change that needs a handful of values.

saying these in an interview costs you the question

  • Headless components are fully accessible whatever styling the consumer adds
  • Headless means the component has no state, only markup
  • Any brand difference, even colours and fonts, calls for headless components
  • Styled and headless layers should each implement behaviour separately
  • Going headless removes the need for any design-system involvement