Introduction
Getting started
StableFour steps, in this order. Most design-system efforts fail by starting at step two.
Updated in v1.0.0
Foundry is a template demonstration
1. Take the tokens first
Every visual decision in Foundry resolves to a CSS custom property. Copy src/app/globals.css into your project and you have the whole system: light and dark schemes, five palettes, three densities, focus treatment, motion and the Tailwind bridge.
Nothing else in the library works without this file, and almost everything works with only this file. Read the token reference to see every value rendered from the live stylesheet.
2. Copy one component
Open any component page — Button is a good first one — and copy the implementation tab. Paste it into src/components/ui/. Its only imports are React, lucide-react and two small local utilities that come with it.
Every component page shows the exact file that renders the preview above it. There is no separate “example” that might have drifted.
3. Compose a section
A section is an arrangement of primitives, not a new kind of thing. Copy a section from the section catalogue and it will name the primitives it needs at the top of the file. There are 109 of them, each solving a different layout problem.
4. Compose a page
Ten finished page patterns show what this looks like at full size. Read one of their source files: it is a handful of imports and a fragment. Then try the composition playground, which assembles a page from the same blocks with the choices in the URL.
What to read next
- Installation — project requirements and the Tailwind bridge
- Composition — how the four levels fit together
- Accessibility — the contracts every primitive guarantees