@freecodexyz/design-system-react

React components for the FCF design system.

pnpm add @freecodexyz/design-system-react @freecodexyz/design-system-css

import '@freecodexyz/design-system-css'
import { Button, Card, CardTitle } from '@freecodexyz/design-system-react'

React 18.3+ or 19 as a peer dependency, so your application owns the React installation.

Subpath exports

import { Button } from '@freecodexyz/design-system-react/button'
import { Dialog } from '@freecodexyz/design-system-react/dialog'
import { PointCloud } from '@freecodexyz/design-system-react/visual'

The package is sideEffects: false and ships preserved modules, so the root import tree-shakes just as well. Subpaths exist for consumers who prefer an explicit graph.

Components import no CSS

Not import './Button.css', anywhere. That keeps the package SSR-safe, bundler-agnostic and honestly tree-shakeable. Load the stylesheet once, at your entry — either @freecodexyz/design-system-css or, if you would rather have one dependency, @freecodexyz/design-system-react/styles.css, which is the same bundle.

apps/test-consumer asserts this: it renders every component with no DOM present, and fails if the entry point imports CSS.

Layout

src/Button/
├── Button.tsx           implementation
├── Button.types.ts      public prop types
├── Button.stories.tsx   every state
├── Button.test.tsx      behaviour
├── Button.a11y.test.tsx roles, names, keyboard, axe
├── Button.docs.mdx      the consumer-facing page
└── index.ts

Styles live in @freecodexyz/design-system-css, not here — see docs/architecture/layers.md. Micro-primitives that always ship together share a folder.

Relative imports carry explicit .js extensions because the package is built with tsc targeting real Node-resolvable ESM. That is what makes the SSR check meaningful.

Documentation

Storybook has the props, the states, the accessibility notes and the anti-patterns for every component.