One implementation of the interface, shared by every FCF product. Tokens, stylesheet, icons and React components — versioned, tested and published together.
This repository is the executable design system, not a folder of styles to copy. If a decision about how the product looks or behaves is not expressed here, it is not a decision the system has made.
pnpm add @freecodexyz/design-system-react @freecodexyz/design-system-cssimport '@freecodexyz/design-system-css'
import { Button, Card, CardTitle } from '@freecodexyz/design-system-react'| Package | What it is |
|---|---|
@freecodexyz/design-tokens |
The design decisions, as platform-neutral DTCG JSON. Builds to CSS, Sass, TypeScript and JSON. |
@freecodexyz/design-system-css |
The stylesheet: reset, base, components, utilities. Usable with no JavaScript at all. |
@freecodexyz/design-system-scss |
Sass functions and mixins over the tokens. Optional. |
@freecodexyz/design-system-icons |
SVG sources, and the React icons generated from them. |
@freecodexyz/design-system-react |
The React components. |
Dependencies flow one way, and the boundary is enforced by the package graph:
tokens ──▶ css ─┐
──▶ scss │
icons ────────┼──▶ react ──▶ products
│
storybook ◀── (documentation, depends on everything, is depended on by nothing)
Components may depend on tokens. Tokens never depend on components. That is what makes a theme a data change rather than a code change.
apps/
storybook/ Documentation and the component workshop
test-consumer/ A real application installing the real packages
packages/
tokens/ DTCG source + Style Dictionary build
css/ Stylesheet source + Lightning CSS bundle
scss/ Sass interface
icons/ SVG source + generator
react/ Components, one folder each
docs/
principles/ What the system believes
accessibility/ The standard, and how it is enforced
content-guidelines/ How to write the words in the UI
architecture/ Why the packages are shaped this way
governance/ Ownership, versioning, support, deprecation
migration-guides/ How to move between majors
rfcs/ Proposals for changes to the foundations
examples/ Framework integration examples
plugins/ Agent skills, packaged for Claude Code and Codex
scripts/ Repository-wide tooling
pnpm install
pnpm build # every package, in topological order
pnpm dev # Storybook at http://localhost:6006
pnpm test # unit, interaction and accessibility tests
pnpm verify # everything CI runs, in the same orderpnpm verify is the gate. It builds, type-checks, lints, tests, asserts the
published file lists, and then builds a real application against the packages.
Three independent axes, all attributes on the root element:
<html data-theme="dark" data-accent="cyan" data-radius="square">With no data-theme, the system follows the operating system. See
Theming.
- Contrast. Every foreground/background pair the system permits is asserted
at WCAG AA, in both themes and all four accents, by
packages/tokens/test/contrast.test.ts. Three real defects were found and fixed by writing it. - Overridability. Every rule lives in a cascade layer, so any unlayered rule
in a product wins without specificity games. The system never uses
!importantexcept where the opposite could not be wanted. - Themeability. No component hard-codes a colour, size, radius or duration.
Enforced by
packages/css/test/stylesheet.test.ts. - Internationalisation. Logical properties throughout; no
margin-leftanywhere in the shipped CSS. Also enforced by that test. - What we publish is what we tested.
apps/test-consumerinstalls the packages through their realexportsmaps, renders them with no DOM, and builds with a real bundler.
The fcf-design-system plugin packages the system's rules as agent workflows,
so an AI agent integrating or building with it stays on the same bar as CI.
./install-skill.shTwo skills:
integrating-the-design-system— install the packages, import the stylesheet at the right entry for the framework, wire themes and fonts, and migrate off@freecodexyz/ui.building-with-the-design-system— which component, which token, and the rules. It shipsinventory.mjs, which reads the installed packages so it can never drift from the version an app has, andaudit-usage.mjs, which scans an application for the same invariants this repository enforces on itself.
node <skill>/scripts/inventory.mjs --component Button
node <skill>/scripts/audit-usage.mjs srcSee plugins/fcf-design-system/README.md
for direct plugin installation and testing.
Read CONTRIBUTING.md. Changes to the foundations — tokens, theming, package boundaries, the accessibility standard — go through the RFC process first.
Apache-2.0. See LICENSE.