@atomic-ui/design-tokens
v0.1.7
Published
The design tokens every Impkt component reads, and the derivation that turns a partner's handful of brand inputs into the whole set.
Readme
@atomic-ui/design-tokens
The tokens every Impkt component reads, and the derivation that produces them from the handful of values a partner sets.
A brand authors around twenty inputs. Eighty-five tokens come out, and the eighty-five are not authorable. That ratio is the whole design, and the reasoning — with what Stripe, Cloudscape, Salesforce and Auth0 each allow — is ADR 0010.
import { DEFAULT_BRAND_INPUTS, deriveTokens, checkContrast, toStylesheet } from '@atomic-ui/design-tokens';
// A site's published brand is already a set of inputs: config.branding.
const inputs = config.branding ?? DEFAULT_BRAND_INPUTS;
const tokens = deriveTokens(inputs);
const report = checkContrast(tokens); // blocks a publish when it fails
const css = toStylesheet(tokens, { fonts: inputs.font.webFonts });What a partner sets
Colour: brand, accent, four surfaces (page, card, header, footer), text,
and danger / warning / success / info. Typography: body family, heading family,
base size, ramp ratio, web fonts. Shape: base radius, base spacing unit, base border
width. Assets: logo, dark logo, favicon.
Two absences are the point. There is no foreground colour — text on a surface is picked by measured contrast, so a partner cannot pin white text onto a mid-tone brand colour, which is the most common white-label accessibility failure. And there is no focus colour — the ring keeps system values, because a focus indicator drawn in a partner's brand colour on that partner's background is where focus visibility dies.
The page surface is the one that may be a gradient. It is safe by construction rather than by exception: nothing is read against it, because text sits on a card.
What derives
Hover, active and subtle states are tone shifts. The type ramp scales from the base
size in rem, with a 12px floor. Spacing and radii are multiples of their units.
Muted text, placeholder text and borders are blends toward the surface, each ratcheted
until it passes — 4.5:1 for text, 3:1 for a UI boundary — so a blend that works for
one brand cannot quietly fail for the next.
Headings take the accent colour, which is what every migrated theme set
typography.headingColor to. Header and footer text takes the accent on a light band
and the picked foreground on a dark one, which reproduces Northwind's purple-on-white
header rather than flattening it to near-black.
Status colours get .default at 3:1 and .text at 4.5:1 separately, because the yellow
that is fine as a warning icon is not fine as warning text.
What it will not do
Derivation keeps what is ours legible. It will not change what is theirs: a
near-white brand colour stays near-white, and checkContrast reports it against 1.4.11
rather than silently darkening it. Telling a partner their brand colour cannot be a
filled button is honest; changing their brand without saying so is not.
The gate is a floor, not a certificate. It is arithmetic over colour pairs — it cannot
see text baked into a logo, a value rendered over an image, or whether an error message
makes sense. ContrastReport.checked reports how many pairs it looked at so a clean
result is not mistaken for an audit.
This is the brand schema
BrandInputsSchema is not a projection of the stored brand document — it is it.
@atomic-ui/content-schemas extends it with the site key and nothing else
(ADR 0012), so there is one
definition rather than a contract and an implementation drifting apart.
Every group is .strict(). Zod strips unknown keys by default, so color.onBrand
would otherwise validate, be dropped, and leave an editor looking at a brand that
ignores a value they set. Being refused says what is actually true: there is nowhere to
put a foreground colour, because foregrounds are measured.
Layout
A brand's layout sets the page frame and the gutters between columns:
pageWidthis the widest the content gets, from 640 to 1600px.margin.phone,margin.tabletandmargin.desktopare the space at the screen's edge.gutter.sm,gutter.mdandgutter.lgare the three gaps a grid can choose.
Margins and gutters name steps on the spacing scale, such as '4' or '6', rather than
pixels, so they follow shape.spaceBase. Each has a default, so a brand that sets none
of this looks as it did before.
toStylesheet emits them as --impkt-layout-* tokens, plus an impkt-page class. An
app puts that class on the element its pages fill, and the content is then centred,
held to the page width, and given the brand's margin for each size of screen:
<main className="impkt-page"><RouterView … /></main>Commands
pnpm --filter @atomic-ui/design-tokens test # derivation, contrast, round-trip
pnpm --filter @atomic-ui/design-tokens typecheck
pnpm --filter @atomic-ui/design-tokens emit # dist/tokens.css + dist/tokens.dtcg.jsonemit writes the house theme: what a shell renders before it knows which partner it is
serving. It calls the same deriveTokens the runtime does, so the file on disk and the
properties a live page carries cannot disagree.
