C-349: Replace Style Dictionary with hand-maintained CSS theme

[dahannes]

Summary

C-349 — Replace the Style Dictionary token pipeline with a single hand-maintained CSS theme file.

Breaking Change

The Style Dictionary token pipeline has been removed. The tokens/ directory (3 DTCG JSON files) and scripts/build-tokens.ts are deleted. Token values now live in src/styles/theme.css as a single hand-maintained CSS file with @theme inline registration.

Commits

1. refactor(tokens)!: replace Style Dictionary with hand-maintained CSS theme — core pipeline replacement (18 files)
2. refactor(components): use standard Tailwind utility names for design tokens — migrate components from arbitrary value syntax to standard utilities (10 files)
3. feat(icon): add new icons to registry — 13 new icons for admin-portal (1 file)
4. docs: update CLAUDE.md, README, and ColorReference for new token pipeline — documentation sync (3 files)

Key changes

• src/styles/theme.css (558 lines) consolidates primitives, semantic light/dark tokens, font-face declarations, body styles, gradients, and @theme inline block
• src/styles/tokens.css — standalone @theme inline block for consumer @reference consumption without pulling in tw-animate-css or tailwindcss-react-aria-components
• src/colors.ts exports ColorTeal500 and ColorPurple700 for consumers needing direct hex values
• scripts/validate-tokens.ts replaces build-tokens.ts — checks dark-theme token coverage only

Consumer migration

Admin-portal and cytario-web styles.css files updated to:

@reference "@cytario/design/styles/tokens.css";
@import "@cytario/design/styles.css";
@import "tailwindcss";

Test plan

• npm run validate:tokens passes in CI
• npm run build succeeds
• Storybook renders all components with correct colors
• admin-portal build succeeds with updated styles.css
• cytario-web build succeeds with updated styles.css

Ref: C-349

[cytario-plane]

Linked to Plane Work Item(s)

References

• (C-349) cytario-design: Refactor Tailwind token exposure pipeline for consumer consumption

This comment was auto-generated by Plane

[dahannes]

Why this PR is a win (rationale)

1. Style Dictionary was solving a problem we don't have.
SD's value proposition is multi-platform generation — write tokens once in JSON, emit CSS + iOS Swift + Android XML. We only consume CSS. The pipeline was JSON → CSS custom properties, one target. That's indirection with zero payoff.

2. The @theme duplication was already hand-maintained — just with extra steps.
The old tailwind.css had a 90-line @theme block with hardcoded hex values duplicating every color from the JSON. When you changed a color in tokens/primitives.json, you had to also update tailwind.css by hand. The "single source of truth" claim was already broken — there were two.

3. The build step was a footgun.
npm run dev, build, and build:lib did NOT run build:tokens. You had to remember to run it manually. The CLAUDE.md explicitly warned about this. Forgetting it meant stale tokens shipped to consumers.

4. Tailwind v4's @theme inline is the actual single source of truth now.
Tailwind v4 needs tokens declared in @theme/@theme inline to generate utilities. Style Dictionary generates plain CSS custom properties — it doesn't understand @theme inline. So we'd need SD to generate the CSS variables AND a separate hand-maintained @theme block mapping them. The new approach puts everything in one file: primitives, semantics, dark overrides, and @theme inline — no duplication, no generation step, no drift.

5. The @reference consumer pattern requires it.
Consumer apps need a standalone @theme inline file (tokens.css) they can @reference without pulling in tw-animate-css or tailwindcss-react-aria-components as devDeps. That file can't be Style Dictionary output — SD doesn't emit @theme inline.

What might seem concerning

• "Hand-maintained" sounds fragile — but validate-tokens.ts enforces the one invariant that matters (every light semantic has a dark override). The old pipeline had no such check.
• "We lose token transformation" — SD was doing W3C DTCG JSON → CSS. Since we only target CSS, the "transformation" was just renaming. The CSS is now the source, not a derived artifact.
• "What about TypeScript constants?" — tokens.ts was auto-generated and exported * — nobody was actually importing typed token constants from it. src/colors.ts covers the two hex values consumers actually need.

TL;DR

The Style Dictionary pipeline was providing the illusion of rigor (JSON source of truth, generation step) while actually creating drift (duplicate @theme block, forgotten builds) and couldn't support the Tailwind v4 @reference pattern we need for consumer apps. Removing it makes the system simpler, more correct, and easier to maintain.

[github-actions]

🎉 This PR is included in version 8.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀