A design system is not the Figma document. It's the file tokens.css in the repo. Everything else is documentation about what actually happens in code.

Across three current projects we have the same setup: a token file as the single source of truth, a thin component layer, and Figma as a mirror of that, not the source. Sounds backwards — works better.

Tokens are code, not spreadsheets

Classic design systems live in spec documents or Figma variables. Nice for designers. For engineers it's a second truth that drifts regularly. We go the other way around: tokens are defined directly in CSS or Swift, with comments for designers.

tokens.css
/* ── Color: Brand ── */
--cc-midnight: #00004F;        /* Primary */
--cc-highlight: #E84A0A;       /* Accent */
--cc-link: #039DC6;            /* Cyan */

/* ── Type ── */
--font-display: "Sora", system-ui;
--font-mono: "JetBrains Mono", monospace;

The file is 122 lines long. It's in the repo. It's versioned. Designers can read it — we run a short crash course on CSS variables once per project, and the language barrier is gone.

Why Figma still stays in the system

Figma is not a design system. But it's a great playground for thinking through components visually before they move into code. For us, Figma is where a new component layout is born, and tokens.css is where it becomes real. Design and engineering sitting at the same table is no accident — that's how our studio works on every project.

  • Designers sketch in Figma, with the imported tokens as variables.
  • Once the shape is set, an engineer (or the designer themselves) writes the HTML/CSS directly in the repo.
  • Figma is synchronized in the background via a plugin — tokens flow back from code.
  • If there's a conflict: code wins. Always.
// End of article