@campfire-interactive/design-tokens
v0.4.0
Published
Shared design tokens for Campfire Suite — raw scales, semantic roles, per-app accent hooks, and an opt-in dark theme
Keywords
Readme
@campfire-interactive/design-tokens
The source of truth for every shared value in the Campfire Suite — colors, type,
spacing, radii, shadows, motion, z-index, chart series and chrome dimensions —
as CSS custom properties under a --cfi- prefix.
tokens.css is the source; tokens.json is generated from it by
scripts/generate.mjs and resolves the var(--cfi-app-*, fallback) chains to
literals for non-CSS consumers.
⚠ 0.2.x is a rewrite, and adoption is not open yet
0.1.1 had 42 tokens. 0.2.0 has 148, in three layers, with an opt-in dark theme. The semantic naming is not settled until more than one app has migrated onto it, so treat these names as movable.
One name already moved: the orange ramp is --cfi-color-orange-*, renamed from
--cfi-color-primary-*. Raw scales in this file are named by hue, so a role word
in a palette slot read as "the primary color" — which is how buttons ended up
wired to it. It is master-data's and pim's app-identity color. The color of
anything you press is --cfi-action.
Three published packages still reference the old name with literal fallbacks
(shell-header, side-nav, volume-intelligence-ui), and that is deliberate:
with the token gone they keep rendering their own literals, which is exactly
what they render today. No alias is provided, because an alias would resolve
volume-intelligence-ui's blue buttons to orange the moment an app imports
this file.
^0.1.1 does not resolve to 0.2.0 — a caret below 1.0 never crosses a minor —
so nothing picks this up by accident. Bumping to ^0.2.0 is a deliberate act,
and the gate for it is in the repo's CLAUDE.md.
Install
npm i @campfire-interactive/design-tokens// once, at the app entry point, BEFORE the app's own stylesheets
import '@campfire-interactive/design-tokens/tokens.css';Declaring the dependency does nothing on its own. It was a dependency of eleven
frontends and imported by none of them; the --cfi-* variables reached those
pages only because shell-header and side-nav bundle their own use of them.
Import the stylesheet, or the tokens are not there.
The three layers, and which one to reference
- Raw scales —
--cfi-color-gray-500,--cfi-font-size-sm. Palette values. Reference these only when defining a semantic token. - Semantic roles —
--cfi-surface,--cfi-content-muted,--cfi-border,--cfi-action, the focus ring, the overlay. This is what component CSS should use. A component that reaches past these into a raw gray cannot be re-themed and breaks in dark mode. - App overrides —
--cfi-app-primaryand friends. The app's own identity color, for the shell badge. Set these in the consuming app.
Two colors, two jobs
--cfi-action is the suite-wide color for anything you press — buttons, links,
focus rings, selected rows. Its value is omsf's #030213, because omsf is the
reference for main styles. It is identical in every app; that is the point of it.
--cfi-app-primary is the app's identity color, and its only job is the app
badge in the shell header plus its tile in the app switcher. The canonical value
per app is the color field in shell-header's appCatalog.
Do not point one at the other. Wiring buttons to the app color makes the same primary button violet in one app, sky blue in another and indigo in a third — the opposite of a design system.
Dark mode is opt-in
<html data-theme="dark"> <!-- explicit -->
<html class="cfi-theme-auto"> <!-- follow the OS -->Neither happens by accident, so adding this file to an app that has never considered dark mode cannot change how it looks today.
Status colors
Each semantic hue carries a -soft background and a -text foreground that
meets 4.5:1 against it. Use the pair. bg-[#10B981]/10 text-[#10B981] — the
shape several apps had — lands near 2:1.
