Halo Ds

Halo Design System

An open-source design system for designers and developers: a Figma library and a React component library built from the same design tokens, with light and dark mode.

📖 Docs & component playground: https://halo-design-system.github.io/Halo-design-system/

Status: early development. Foundations, 44 components, 40 illustrations and 20 awards are in place, in Figma and React. Not yet published to npm.

Packages

Using Halo

npm install @halo-ds/react

That is all the setup: the styles, the design tokens and the Geist font load by themselves when you use a component.

import { Button } from '@halo-ds/react';

Switch themes with the data-theme attribute on <html>: light (default), dark, or system (follows the OS).

Every token is a CSS variable starting with --halo-, so your own styles can use them too:

.card {  background: var(--halo-surface-primary);  color: var(--halo-text-primary);  padding: var(--halo-spacing-md);  border-radius: var(--halo-radius-sm);}

Make it yours

• Quick: override a few brand variables in your own CSS, loaded after Halo's. No rebuild needed.
• Full: change the variables in your copy of the Figma file, export them, and rebuild the tokens so design and code match.

The Theming page in Storybook walks through both, with a live example.

Working on Halo

Requirements: Node.js 20+ and pnpm (npm install -g pnpm). The project pins its own Node 24 runtime, which pnpm downloads automatically.

pnpm install     # install dependenciespnpm dev         # build tokens and start Storybook at http://localhost:6006pnpm build       # build every packagepnpm typecheck   # type-check every package

Project structure

packages/  tokens/     figma/ ← Figma variable exports (source of truth)              scripts/build.mjs → dist/tokens.css, tokens.json, index.js  react/      src/ ← componentsapps/  docs/       Storybook (foundations pages + component stories)docs/         design notes (e.g. dark-mode mapping)

Design → code workflow

1. Design the component in Figma using Halo variables (never raw hex values).
2. Build it in packages/react/src/components/<Name>/ using the matching CSS variables.
3. Add a <Name>.stories.tsx so it appears in Storybook.
4. Review it in Storybook in both light and dark mode.

See CONTRIBUTING.md for details.

License

MIT. The Figma library also includes emojis, icons, flags and brand logos from other open-source projects; see THIRD_PARTY_NOTICES.md for their licences and required credits.