@fireworks-ai/design-system

Shared React components and design tokens for Fireworks AI products.

Component previews and docs (Storybook): https://storybook.preview.fireworks.ai

npm i @fireworks-ai/design-system

Requirements

| Dependency | Requirement | | --- | --- | | react / react-dom | ^19.0.0, peer, required | | next | ^16.0.0, peer, required | | react-hook-form | ^7.62.0, peer, optional — only needed for ./components/ui/form | | tailwindcss | ^4.0.0, required |

Usage

Components

Import each component from its own subpath.

import { Action } from '@fireworks-ai/design-system/Action';
import { DataTable } from '@fireworks-ai/design-system/DataTable';

Then point Tailwind at the compiled components. Tailwind only generates CSS for classes it finds while scanning, and it never scans node_modules — so skip this and every component renders unstyled, with nothing to tell you why.

@source "../node_modules/@fireworks-ai/design-system/dist";

Adjust that path so it resolves to node_modules from wherever your CSS file sits. For the full list of subpaths, run npm view @fireworks-ai/design-system exports.

Theme and cn

Tailwind v4 is required. The stylesheet uses v4-only syntax (@theme, @utility, @source), so v3 cannot parse it, and there is no tailwind.config.js route to the tokens. Run npx @tailwindcss/upgrade first if you are still on v3.

Import theme.css after tailwindcss, and import it as a whole. It is the only stylesheet the package exports, and it pulls in three files whose resets only work in that order.

@import 'tailwindcss';
@import '@fireworks-ai/design-system/styles/theme.css';

That import replaces Tailwind's palette, type scale, and font weights — it does not extend them. It also styles bare h1–h6. Anything it drops stops compiling, silently:

• Colors. gray runs 50–900 (plus a 750), the other families offer 50 / 100 / 300 / 500 / 700, and there is white. slate-500 and the rest of Tailwind's palette are gone.
• Type scale. xs sm base lg 2xl 3xl 4xl 5xl — note there is no text-xl. Every step carries its own line-height and letter-spacing, so a size class is already a finished type style; do not add leading-* or tracking-* on top.
• Font weights. Only font-normal, font-medium, and font-semibold survive. font-bold produces nothing at all.

Use cn from this package to merge a className, rather than building your own twMerge. This instance is configured with the package's @utility classes; a stock one mistakes text-eyebrow for a color, so cn('text-eyebrow', 'text-gray-900') quietly drops it.

import { cn } from '@fireworks-ai/design-system/lib/utils';

Color tokens

The CSS variables hold RGB triples instead of hex, which lets hand-written CSS pick its own alpha: rgb(var(--gray-900) / 0.4).

The same values also ship as plain TypeScript constants, with no CSS side effects. A test keeps the two in sync.

import { colors } from '@fireworks-ai/design-system/tokens/colors';

colors.gray[900]; // '#18181B'

Use the constants only where a CSS variable cannot reach — chart configs, canvas, SVG. If the value ends up in a stylesheet, use the utility class instead.

Contributing

Development

Run the dev script to start a watching build. From the repo root, bun run dev --filter=@fireworks/web... runs both the web app and the design system.

Building

bun run build in this package, or bun run build --filter=@fireworks-ai/design-system from the repo root.

Adding new components

[!IMPORTANT] All components need to be defined within the exports field of the package.json file!

{
  "exports": {
    "./NewComponent": {
      "types": "./dist/NewComponent.d.ts",
      "import": "./dist/NewComponent.js"
    }
  }
}

Import other files in this package with relative paths. Self-referencing subpath imports such as @fireworks-ai/design-system/Action survive into dist/, which breaks consumers whenever the package is renamed, and the ~/ alias is not resolvable at all outside this repo.

Releasing

Run publish-design-system.yml manually from the Actions tab, with bump set to patch, minor, or major. The workflow bumps the version itself, so do not edit version by hand. It validates first — build, typecheck, tests, a packaging dry run, and a check that the version is not already on npm — then opens a release PR carrying the bumped package.json and bun.lock, publishes, and finally tags the commit it was dispatched from as design-system-v<version>. Merge that PR once the run is green: while main still points at the published version, the next release fails its preflight check.