Skip to content

Web & Digital Experience

Component libraries: finished in every variant and state

A component that looks right in one screenshot isn't finished. It needs every version it comes in, every state it can be in, a name a screen reader can say, and documentation that shows it working. Then a screen can use it without checking, and it behaves the same everywhere it appears. For you, that means every new screen starts from parts that already work, and your products behave the same everywhere.
Discuss your componentsSee what's documented ↓
job cardcomponentvariantsJ-611 · 10–12C-0731 · furnace tune-upscheduledJ-611 · 10–12C-0731 · furnace tune-upen routeJ-611 · 10–12C-0731 · furnace tune-updoneJ-611 · 10–12C-0731 · furnace tune-upneeds partsstatesdefaulthoverfocusloadingdisabledcheckedkeyboardscreen reader name390 widereduced motionused indispatch boardcustomer portaltechnician app

What's written down for every component

For the job card, the same five things as for a button.
Variantseach version, and when to use itscheduled, en route, done, needs parts
Stateshow it looks and behaves in eachdefault, hover, focus, loading, disabled
Propertieswhat a screen passes inthe job, the customer, the time window, the status
Accessibilityits name, role and keyboard behaviourread as “Job J-611, en route, 10 to 12”
Usagewhere it's used, and where it isn'tboards and lists; not for invoices

What makes a part trustworthy

  1. 01

    Clear semantics

    Named for what it is

    A job card is a job card in code, in design and in conversation, never “Card 3”.

  2. 02

    Every state

    Not just the default

    Hover, focus, loading, disabled and error are built and shown side by side.

  3. 03

    Variants on purpose

    A short list, each with a reason

    Four statuses, not a style switch for every request.

  4. 04

    Accessible by default

    Built in once, inherited everywhere

    Focus, labels and announcements live in the component, so every screen gets them.

  5. 05

    Documented with examples

    Live, next to the code

    Each variant and state shown working, with when to use it.

Adding a variant, step by step

The dispatch team needs a job card for jobs waiting on the customer.

Job card · new variant “waiting on customer”

  1. Requested

    by the dispatch board team

    done

  2. Checked against existing variants

    not covered by needs parts

    done

  3. Built in every state

    default to disabled

    done

  4. Tested

    keyboard, screen reader, 390 wide

    done

  5. Documented

    when to use it, with an example

    done

  6. Released

    as a new version; screens move to it when ready

    done

One new variant, ready for every screen that shows a job, and nothing else changed.

What a component library hands off

In

Design decisions
tokens and guidance
Requests
from product teams
Usage
where each part is used
Component library
build, test, document

Out

Components
every variant and state
Documentation
live examples
Versions
released with notes

Worth building when the same parts appear on many screens

Good fit

  • The same part shows up on many screens, or in several products.
  • Teams build their own versions, and they drift.
  • Accessibility has to be built once and kept.

Not the right fit

  • A handful of screens, built once.
  • An existing library does the job as it is.

Where this capability is used

Next to component libraries

Questions about component libraries

Can you build on an existing open-source library?

Often, yes. A good base library covers the basics; we add your own parts, like the job card, and your tokens.

How do teams find and try the components?

In a workbench that shows each component in every variant and state, with the code beside it.

What happens when a component changes?

It's released as a new version with notes. Screens move to it when they're ready, and nothing changes under them without warning.

Do business-specific parts belong in the library?

When more than one screen uses them, yes. The job card, the time-slot picker and the invoice line are as reusable as a button.