🎨 Quill Design System (@deriv-com/quill-tokens-components)

React components whose styling is driven entirely by design tokens synced from Figma.

Quill is a React component library plus a Node automation pipeline that extracts design tokens from Figma and generates the CSS/TypeScript token files the components consume. Figma is the single source of truth — components use tokens, never hardcoded values. Change a value in Figma, run one command, and the code stays in sync.

This repo publishes two npm packages:

| Package | Contents | Source | | ------------------------------------------------------ | -------------------------------------------------- | ------------------ | | @deriv-com/quill-tokens-components | React UI primitives + design tokens | repo root (src/) | | @deriv-com/quill-blocks | Marketing/page-section Block components + contracts (guides + JSON Schemas) | packages/blocks/ |

🚀 Quick Start

Install

npm install @deriv-com/quill-tokens-components

Use components

Components ship with their styles bundled — no separate CSS import needed.

import { Button } from "@deriv-com/quill-tokens-components";

<Button type="primary" size="md" label="Click me" />;

Use tokens for custom styling

// Once, at your app entry point:
import "@deriv-com/quill-tokens-components/tokens.css";

.custom-card {
  padding: var(--quill-semantic-size-spacing-16);
  background: var(--quill-semantic-colour-background-primary-surface);
  color: var(--quill-semantic-colour-text-prominent-default);
  border: 1px solid var(--quill-semantic-colour-border-default-default);
  border-radius: var(--quill-semantic-size-radius-8);
}

Tokens are also available as a typed JS object:

import { tokens } from "@deriv-com/quill-tokens-components/tokens";

element.style.padding = tokens["--quill-semantic-size-spacing-16"];

Token categories: --quill-semantic-colour-*, --quill-semantic-size-spacing-*, --quill-semantic-size-radius-*, --quill-semantic-size-width-height-*, --quill-semantic-typography-*. Browse src/tokens/ for the full list.

Figma MCP → tokens: Figma MCP output hardcodes values with the token name in a comment (e.g. background: #ebecef; /* tertiary/background/default */). Convert slash/separated names to var(--quill-...) by replacing / with - and adding the --quill- prefix.

✨ Features

• One-command sync — regenerate all tokens from Figma with npm run tokens
• Three-tier token cascade — primitives → semantic → per-component tokens
• TypeScript — typed tokens with autocomplete; components ship .d.ts
• Light/dark theming via Figma modes
• Dry-run, watch, and CI modes for the token pipeline
• Self-styled components — CSS injected into the JS bundle

🔧 Token Pipeline (Figma → code)

The pipeline lives in scripts/tokens/ and turns Figma variables into the token files under src/tokens/.

Setup

1. Copy the env template and add your Figma credentials:

   cp .env.example .env

   FIGMA_ACCESS_TOKEN=figd_your_token_here   # figma.com/settings → Personal Access Tokens
   FIGMA_FILE_KEY=your_file_key_here          # from the file URL: figma.com/design/FILE_KEY/...

2. Sync:

   npm run tokens

Commands

| Command | Purpose | | ------------------------ | ----------------------------------------------------------- | | npm run tokens | Fetch from Figma REST API + regenerate all token files | | npm run tokens:cached | Regenerate from cached tokens.json (offline, no API call) | | npm run tokens:dry-run | Preview file changes without writing | | npm run tokens:watch | Poll Figma and prompt to regenerate on change | | npm run tokens:ci | Strict validation, non-interactive, proper exit codes |

Everything in src/tokens/ is auto-generated — do not hand-edit. To change a token, change it in Figma and re-sync. Commit the regenerated files (review with git diff src/tokens/); .env and the raw tokens.json cache are gitignored.

The three-tier cascade

1. primitives.css — raw values (--quill-primitive-typography-font-size-14: 14px)
2. semantic_*.css — contextual aliases referencing primitives (--quill-semantic-colour-text-prominent-default)
3. component_*.css — per-component tokens referencing semantic tokens (--quill-button-font-size)

A component's .module.css uses only component-tier variables, which cascade down to primitives. Token names mirror Figma variable names 1:1.

🧩 Component Development

The Figma-driven workflow is owned by two Claude Code skills:

• /createcomponent — build a new component from a Figma node (extract → approve analysis → generate files).
• /updatecomponent — re-sync an existing component to Figma (token restructure, new/removed variants, size migration). --check = read-only, --fix = skip the confirmation gate.

The deep reference — file templates and the Figma-variable→token naming rule — is docs/component-guideline.md.

Structure

Each component is 5 files in its folder, plus a spec file in src/specs/:

src/components/{ComponentName}/
├── {ComponentName}.tsx           # forwardRef, prop-driven variants
├── {ComponentName}.module.css    # design tokens only, no hardcoded values
├── {ComponentName}.stories.tsx   # Storybook stories (flat title: "{ComponentName}")
├── index.ts                      # public exports
└── README.md

src/specs/{ComponentName}.spec.json   # cross-platform spec — NOT in the component folder

Every component must be exported (component + Props type) from src/index.ts.

Conventions

• Tokens only — never hardcode; if a token is missing, add it in Figma and re-sync.
• Size = variants (.sm/.md/.lg classes), not Figma modes — modes are reserved for light/dark.
• No component category — flat Storybook titles, no category field in specs.

🛠️ Development

npm install
npm run storybook     # Storybook dev server on :6006
npm run build         # Vite library build → dist/
npm test              # vitest (token pipeline tests live in scripts/tokens/__tests__/)
npm run lint          # eslint
npm run typecheck     # tsc --noEmit

📚 Documentation

| Document | Purpose | | ---------------------------------------------------------- | ------------------------------------------------- | | docs/component-guideline.md | Figma-driven component standards + file templates | | .claude/skills/ | /createcomponent & /updatecomponent | | CONFIGURATION.md | Token pipeline configuration + CI/CD setup | | API-REFERENCE.md | Token pipeline architecture and modules |

🆘 Troubleshooting

• FIGMA_ACCESS_TOKEN is not defined — .env is missing or not loaded. Verify it exists and matches .env.example (no quotes around values).
• Failed to fetch from Figma API — check the token has file-read access and the file key is correct (curl -H "X-Figma-Token: TOKEN" https://api.figma.com/v1/files/FILE_KEY/variables/local).
• Token not found in a component — run npm run tokens to sync, then confirm the name in src/tokens/.

More in CONFIGURATION.md.

🤝 Contributing

Branch off master, make changes (add tests for pipeline changes), and run npm test && npm run lint && npm run typecheck before opening a PR with a clear description and before/after examples.

📝 License

MIT