The CarbonWeb Design System

A library of ready-made, on-brand pieces you assemble pages from — instead of designing and coding the same card, button and hero over and over. Plain HTML and CSS. No framework, no build step.

4 min read

1 · How it's organised

Foundation
The raw decisions. Colour, type, spacing, grid, radius, shadow — as variables.
color · type · space · grid · radius · shadow
↓ built from
Atom
The smallest pieces. Made only from foundations.
button · chip · badge · avatar · text-link
↓ built from
Molecule
Assemblies. Foundations plus atoms.
card · accordion · tabs · pricing-card
↓ built from
Section
Full-width page blocks. Anything below.
hero · faq-section · cta-banner · site-footer

Each level may only use the ones below it. That single rule is what keeps the system consistent — nothing reinvents a colour or restyles a button.

2 · How to read a component

card Molecule
built from colortypespace radiusshadow buttonchiptext-link
card/blogcard/iconcard/carousel card/service-price+10 more
Name what you call it. Click to copy.
Built from teal = foundations, green = atoms. Read from the real CSS, so it's never out of date.
Variants forms of the same component, written name/variant.

3 · Using it

1

Find it

Open Reference Names to search everything, or browse the sidebar to see each component live.

2

Name it

Every piece has one unique name. A bare name is the default form; variants add a slash.

3

Ask for it

List the names you want and an assistant builds the page — no need to describe anything.

Build a services page with:
hero/service, chip/tag-category, icon-tile, accordion/service,
faq-section/dark, cta-banner/glow, site-footer/v2

Building by hand instead? Each component's panel gives you the exact <link> imports and markup to copy.

4 · Adding a component

  1. Scaffold it. One command writes all four files, already wired to the tokens, and registers it. What it produces already passes the checker.
  2. Build it with tokens only, reusing atoms rather than restyling them.
  3. Fill in the rules file — when to use it, and when not to. This is what stops the next person misusing it.
  4. Run the checker. python3 tools/audit.py must pass for whatever you touched.
python3 tools/new-component.py metric-tile \
  --category content --level molecule \
  --summary "Compact tile showing a single metric." --variants teal,dark

5 · The five rules

Where to go next