Foundations

Overview

Foundations is the layer that exists before any component does. What a radius means, what "stale" looks like and which of two colour axes an element may draw from are all decided once here so that sixty components do not each make them differently and a reader looking at a blood-pressure reading does not have to work out whether amber means this is a warning or this is your heart category.

Read the signpost first, because two of the three destinations are not here:

Foundations is what a token means. Handbook and Theming are how you change it. Reference is the generated list of every one.

That sentence is printed at the top of all three pillars. If a page in Foundations starts telling you how to override something, it is in the wrong place and should move to Theming. If it prints a value, the value came from a generator, not from an author.

Foundations is the part of this site that is completely real today. Nothing here depends on a component existing: the token sources are authored, the colour and contrast maths is hand-written, and the generated tables read the same files the product theme reads. The thing most often confused with Foundations is the component library. A foundation is nevertheless not a smaller component. It is the argument a component is not allowed to re-litigate.

How it works

There are three shapes of page in this pillar and they are not interchangeable.

Token families own a scale and the tokens that express it. There are six: Colour, Materials, Motion, Typography, Shape and Space. Each ends in a generated Tokens page, and each one is a scale rather than a palette. The steps are ordered, the ordering carries meaning, and skipping a step is a decision you have to be able to defend.

Expression foundations own a medium that has no numeric scale but still needs one ruling for the whole system. There are four: Iconography, Imagery, Data visualisation and Sound and haptics. Imagery and Sound and haptics were added after the first roster of eight, because a patient-facing system that has a rule about colour and no rule about which skin tone a rash is drawn on has picked the easy half of the problem.

System-wide contracts are not families at all. They are the six pages that every component must satisfy regardless of which tokens it consumes: Principles, Token architecture, Layering and elevation, Interaction states, Data states and Layout.

Every page in the pillar, including this one, has the same six sections in the same order: Overview, How it works, Using it, Tokens, Accessibility impact, Related. The shape is enforced by <PageTemplate> at build time, so a foundation cannot quietly become an essay with no applied guidance and no accessibility consequence.

Using it

Come here when you need to know what something means. Three questions map onto three pillars, and getting them the right way round saves a lot of reading:

• What does --opsin-status-urgent-line signify, and when am I allowed to use it? Foundations answers that.
• How do I add a seventh category to my own build without breaking the status axis? Theming is where that is done.
• What is the complete list of every token that currently exists? Reference has it.

If you are new, read Principles and Token architecture in that order. They are twenty minutes and they make the other pages shorter, because almost every rule in the pillar is one of the five principles applied to a specific medium.

If you are auditing rather than building, the four pages that carry the most weight are Colour, Materials, Data states and Density and touch. Those are where a consumer health product fails a real audit, in roughly that order of frequency.

Tokens

Foundations as a whole owns no tokens. Each family owns its own and publishes it on that family's Tokens page, generated from tokens/*.json by scripts/build-tokens.mts: colour, materials, motion, typography, shape and space.

The complete cross-family list, every token in one table with what it controls and what consumes it, is generated into Reference → Tokens. Nothing on this page duplicates it; a hand-kept second copy of a generated list is a copy that will be wrong within a month.

Accessibility impact

Accessibility is not a seventh foundation. It is a property that each of the ten either protects or destroys, which is why every page in this pillar carries an Accessibility impact section rather than deferring to the Accessibility pillar.

The division of labour is: Foundations states the guarantee a token family makes and the failure mode when it is misused; Accessibility states the conformance position, the measured result, and what an implementing team still owns. Contrast figures are measured by pnpm contrast and rendered by <ContrastReport>. No number on any page in this pillar is typed by a human, and a regression against the published floor fails the build rather than appearing as a footnote.

Related

• Principles has the five rules the rest of the pillar is derived from. Read this first.
• Theming and tokens is the other side of the signpost: how to change what you have just read the meaning of.
• The two colour axes is the single most load-bearing decision in opsinjs, and the one Foundations exists to protect.