Documentation

Copy the files and link them

Copy src/ into whatever directory your site serves static assets from. The four files under core/ are mandatory and are the only thing that is. Everything else is optional and independent.

<!-- mandatory, in this order for readability, though order does not matter -->
<link rel="stylesheet" href="/css/core/reset.css">
<link rel="stylesheet" href="/css/core/tokens.css">
<link rel="stylesheet" href="/css/core/type.css">
<link rel="stylesheet" href="/css/core/base.css">

A page that imports core and nothing else is already themed, readable and keyboard operable: the reset normalises the browser, the tokens carry both themes, the type file sets a fluid scale with real measure caps, and the base file styles bare elements. No class is needed for any of that.

Import order cannot break you

Every file in the framework opens with the same layer statement and then writes into exactly one of those layers. A layer statement is one of the two at-rules allowed before @import, so the order is fixed the moment any framework file is parsed, whichever one that happens to be.

@layer bare.reset, bare.tokens, bare.base, bare.layout, bare.component, bare.utility;

bare.reset

Browser normalisation. Removes inherited inconsistency, imposes no look.

bare.tokens

The whole custom property surface, including both themes.

bare.base

Bare element defaults. No classes.

bare.layout

The layout primitives: shell, grid, stack, cluster, sidebar, split.

bare.component

Everything with a block, an element and a modifier.

bare.utility

Single-purpose classes. Last, so no utility needs !important.

Your own CSS sits outside every layer, and unlayered rules beat layered ones, so a single class of your own already wins over any framework rule with no specificity fight and no !important.

A page pays only for what it shows

No component file imports a sibling. Importing the table cannot drag in the modal, and shared values live in tokens rather than in cross-imports. That is what makes the cost of a page a function of what is on it.

The page you are reading links twenty-four files. The home page links twenty-three, and neither pays for the components it does not use.

Two barrel files exist, src/forms/index.css and src/data/index.css, for a page that genuinely uses most of a group. They are convenience, never the cheap path.

Light by default, dark on request, and a class always wins

Three states, not two. With no class on the document element the page follows prefers-color-scheme, which means light unless the system asks for dark. Adding .theme-light or .theme-dark pins the choice, and it beats the system preference in both directions.

The part implementations usually get wrong is that source order alone does not achieve this: a later media query still beats an equal-specificity class rule placed before it. The token file solves it twice over. The media query targets :root:not(.theme-light), so a pinned light theme is never matched rather than merely overridden afterwards, and the pinned blocks sit at specificity (0,2,0) against the plain :root default at (0,1,0).

Scoping works too. The classes are written as both :root.theme-light and a bare .theme-light, so a single panel can carry the opposite theme from the page around it.

Custom properties are the API

Every component reads its own hooks with a global token as the fallback. The pattern is always var(--bs-card-bg, var(--s-card)): set the hook and the component changes, leave it alone and it follows the theme.

/* your stylesheet, no build step involved */
:root {
  --bs-card-radius: 0;              /* square cards everywhere        */
  --bs-wrap-max: 72rem;             /* narrower page shell            */
  --bs-btn-radius: 9999px;          /* pill buttons                   */
}

.panel--quiet {
  --bs-card-bg: var(--s-prev);      /* one card, one surface          */
  --bs-card-shadow: var(--bs-shadow-0);
}

One caution the framework itself follows: a custom property declared on an element inherits into everything inside it. That is why the framework's own modifiers set the used value rather than declaring a hook, and why a hook you set on a container will also retune the same primitive nested inside it. Set hooks on the element you mean.

What the CSS guarantees, and what it cannot

Contrast, focus visibility, target size, motion preference and reduced-motion behaviour are properties of the stylesheets and are enforced by tests in this repo. Every text and background pairing that ships is measured against every surface in both themes.

Everything that is behaviour is yours. A tab strip is a roving tabindex, a modal is showModal(), a menu returns focus to its trigger, a scrollable table needs a name and a tabindex. Each component file states its own obligations in the comment at the top, and the documentation pages repeat them next to the example.

Focus

:focus-visible and never :focus, so a pointer user is not shown a ring they did not ask for and a keyboard user always is. The ring is never removed anywhere.

Target size

The reset floors every button at the WCAG 2.2 SC 2.5.8 minimum, so a control cannot ship under target size by omission.

Motion

The reset clamps every animation and transition under prefers-reduced-motion, so a component author who forgets the media query still cannot ship vestibular-triggering motion.

Colour

No state is signalled by colour alone. Every variant that changes a fill also changes a bar, an icon slot, a weight or a marker.

Every file, measured

Produced by bun run size. Raw, gzip and brotli are the file compressed on its own. The last column is what adding that one file to core costs in a single gzip stream, which is the number that matters when the claim is that a page pays only for what it uses.

The two index.css barrels contain only imports, which is why they appear to add almost nothing on their own.