What are design tokens? ​

Design tokens are named variables that store visual decisions — colors, spacing, shadows, typography — in a single place. Instead of hardcoding #C10F0C in every button and input, the system defines --primary: #C10F0C once, and every component references that name.

When the brand color changes, you update one value. Everything updates.

The 2-level hierarchy ​

Lighthouse organizes tokens in two levels, from raw values to final usage:

L1 — Primitives    →    L2 — Theme    →    Component
#C10F0C                 --primary           button, badge, input...
LevelWhat it isExampleWho defines it
L1 PrimitivesRaw values — the actual hex, px, rem$red-500: #C10F0CDesigners in Figma (collection primitives)
L2 ThemeSemantic aliases — what a value means--primary: #C10F0CDesigners in Figma (collection theme)
ComponentReferences L2 directly — no extra layerbackground: var(--primary)Dev in SCSS

Components use L2 tokens directly. There is no intermediate component-alias layer.

How themes work ​

Lighthouse supports 4 themes. Each theme is a different set of values for the same L2 token names:

TokenLighthouseDarkLaneoptionsNeoverse
--primary#C10F0C#CD3D3B#3EB0A9#8C8C8C
--q-body-container-bg#FFFFFF#1F1F1F#F6F6F6#1B1B1B
--q-primary-lighter#F2C8C7#F2C8C7#DCF8F6#A9A9A9

Theme switching happens at runtime via the data-bs-theme attribute on the <html> element:

html
<html data-bs-theme="dark">        <!-- dark theme -->
<html data-bs-theme="laneoptions"> <!-- laneoptions theme -->
<html data-bs-theme="neoverse">    <!-- neoverse theme -->
<html>                             <!-- default: lighthouse -->

No page reload needed. The browser recalculates all CSS variables instantly.

For designers — working in Figma ​

All L2 tokens live in the theme collection inside the Figma Design System file. The collection has 4 modes, one per theme.

Token groups in Figma ​

GroupContains
brand/Primary, secondary, status colors (success, danger, warning...)
body/Text colors, backgrounds, container bg, placeholder
primary-var/Lighter/darker shades, opacity variants, focus border
secondary-var/Same structure for secondary color
header-nav-footer/Navbar, footer backgrounds and link colors
component/Active state colors, border color, button color
shadows/Box shadow strings per primary color

How to apply tokens to a component in Figma ​

  1. Select the layer you want to style
  2. In the Fill / Stroke / Effect panel, click the color chip
  3. Switch from "hex" to "Library variables"
  4. Search for the token name (e.g. primary, q-body-container-bg)
  5. Select it — the value will update automatically when you switch mode

Tip: always use L2 tokens (theme collection), never raw hex values or L1 primitives directly on components. This ensures your designs switch theme correctly.

Adding or changing a token ​

  1. Open the theme collection in Figma → Variables panel
  2. Add / edit the variable value in each mode (lighthouse, dark, laneoptions, neoverse)
  3. Communicate the change to the dev team — they will regenerate the SCSS file (see developer section below)

For developers — working in code ​

Where tokens live in the codebase ​

All L2 theme tokens are defined in one file:

dsy/src/_tokens-theme.scss

This file is auto-generated from Figma and must not be edited manually. It contains one CSS block per theme:

scss
/* _tokens-theme.scss — DO NOT EDIT MANUALLY */

:root {
  --primary:             #C10F0C;
  --q-body-container-bg: #FFFFFF;
  --q-primary-lighter:   #F2C8C7;
  /* ... ~35 properties */
}

[data-bs-theme=dark]        { --primary: #CD3D3B; ... }
[data-bs-theme=laneoptions] { --primary: #3EB0A9; ... }
[data-bs-theme=neoverse]    { --primary: #8C8C8C; ... }

How to use tokens in a component ​

Reference L2 variables directly via var():

scss
.my-component {
  color:            var(--body-color);
  background-color: var(--q-body-container-bg);
  border-color:     var(--q-primary-lighter);
  box-shadow:       var(--q-box-shadow-primary-sm);
}

Do not define intermediate aliases. If you need --primary in a component, use var(--primary) directly — don't create --my-component-primary-color: var(--primary) unless the concept is genuinely semantically distinct.

Regenerating tokens after a Figma change ​

When the design team updates a value in the Figma theme collection:

  1. Open a Claude Code session with the Figma MCP server active
  2. Say: "Read the theme collection variables from Figma and regenerate _tokens-theme.scss"
  3. Claude reads the updated values via figma_get_variables and overwrites the file
  4. Run npm run build in the dsy package to verify compilation
  5. Commit: chore(tokens): regenerate _tokens-theme.scss from Figma
Figma (MCP) ──→ Claude Code ──→ _tokens-theme.scss ──→ build ──→ commit

No JSON export, no plugin, no manual copy-paste.

Token reference ​

Complete list of L2 tokens available in the theme collection, organized by group.

Brand ​

TokenFigma variableUsed for
--primarytheme/primaryMain brand color — buttons, active states, links, highlights
--secondarytheme/secondarySecondary brand color — secondary buttons, accents
--successtheme/successPositive feedback — success alerts, confirmation icons
--dangertheme/dangerError states — validation errors, destructive actions
--warningtheme/warningWarning states — alerts, caution badges
--infotheme/infoInformational states — info alerts, tooltips
--lighttheme/lightLight surface alternative
--darktheme/darkDark surface alternative
--whitetheme/whitePure white — always white regardless of theme
--blacktheme/blackPure black — always black regardless of theme
--q-primary-accenttheme/q-primary-accentHighlight accent (orange) — callouts, promo elements
--q-secondary-accenttheme/q-secondary-accentSecondary highlight accent (lime)

Body & Text ​

TokenFigma variableUsed for
--body-colorbody/body-colorDefault text color — paragraphs, labels
--body-secondary-colorbody/body-secondary-colorSecondary text — subtitles, metadata
--body-tertiary-colorbody/body-tertiary-colorMuted text — captions, disabled labels
--q-body-quaternary-colorbody/q-body-quaternary-colorBorders, dividers, inactive step indicators
--body-bgbody/body-bgPage / app background
--q-body-container-bgbody/q-body-container-bgCards, modals, inputs, panels, dropdowns
--body-emphasis-colorbody/body-emphasis-colorHigh-contrast text — headings, icon-only labels
--q-body-tertiary-color-opacity-25body/q-body-tertiary-color-opacity-25Disabled input backgrounds, subtle overlays
--q-body-wrapperbody/q-body-wrapperWrapper / layout background — sidebar, page shell
--q-body-dividerbody/q-body-dividerHorizontal rules, section separators
--q-input-placeholder-colorbody/q-input-placeholder-colorPlaceholder text inside inputs

Primary variants ​

TokenFigma variableUsed for
--q-primary-lighterprimary-var/q-primary-lighterTag backgrounds, hover fills on list items, soft highlights
--q-primary-darkerprimary-var/q-primary-darkerHover state on primary buttons and active links
--q-primary-opacity-50primary-var/q-primary-opacity-50Semi-transparent primary — decorative overlays
--q-primary-opacity-25primary-var/q-primary-opacity-25Focus ring color — inputs, checkboxes, selects
--q-filter-focus-border-colorprimary-var/q-filter-focus-border-colorBorder color on focused filter chips and inputs
--q-form-select-option-hover-bgprimary-var/q-form-select-option-hover-bgHover background in dropdowns and multiselect lists
--q-form-select-option-hover-colortheme/q-form-select-option-hover-colorHover text color in dropdowns and multiselect lists
--q-primary-accent-lighterprimary-accent-var/q-primary-accent-lighterSoft background for primary accent highlights

Secondary variants ​

TokenFigma variableUsed for
--q-secondary-lightersecondary-var/q-secondary-lighterSoft secondary backgrounds
--q-secondary-darkersecondary-var/q-secondary-darkerHover state on secondary buttons
--q-secondary-opacity-50secondary-var/q-secondary-opacity-50Semi-transparent secondary
--q-secondary-opacity-25secondary-var/q-secondary-opacity-25Focus ring for secondary-colored elements
--q-secondary-accent-lightersecondary-accent-var/q-secondary-accent-lighterSoft background for secondary accent highlights

Status variants ​

TokenFigma variableUsed for
--q-success-opacity-50success-var/q-success-opacity-50Semi-transparent success — progress fills, badges
--q-success-opacity-25success-var/q-success-opacity-25Subtle success tint — alert backgrounds
--q-danger-opacity-50danger-var/q-danger-opacity-50Semi-transparent danger
--q-danger-opacity-25danger-var/q-danger-opacity-25Subtle danger tint — error input backgrounds
TokenFigma variableUsed for
--q-navbar-bgheader-nav-footer/q-navbar-bgNavbar background
--q-footer-bgheader-nav-footer/q-footer-bgFooter background
--navbar-light-colorheader-nav-footer/navbar-light-colorDefault navbar link color
--navbar-light-hover-colorheader-nav-footer/navbar-light-hover-colorNavbar link hover color
--navbar-light-active-colorheader-nav-footer/navbar-light-active-colorActive / selected navbar link, tab active border
--navbar-light-disabled-colorheader-nav-footer/navbar-light-disabled-colorDisabled navbar link
--navbar-light-brand-colorheader-nav-footer/navbar-light-brand-colorBrand / logo text color in navbar
--navbar-light-brand-hover-colorheader-nav-footer/navbar-light-brand-hover-colorBrand / logo hover color

Component & interaction ​

TokenFigma variableUsed for
--component-active-bgcomponent-active-bgChecked / selected state — checkboxes, radio, active filters
--component-active-colorcomponent-active-colorText / icon on active component background
--q-component-active-hover-bgq-component-active-hover-bgHover on active / selected elements
--q-component-active-bg-opacity-50q-component-active-bg-opacity-50Semi-transparent active state
--border-colorborder-colorDefault border on inputs, cards, dividers
--btn-colorbtn-colorDefault text color on filled buttons

Shadows ​

TokenFigma variableUsed for
--q-box-shadow-primary-smshadows/q-box-shadow-primary-smSubtle elevation — small cards, tooltips, chips
--q-box-shadow-primaryshadows/q-box-shadow-primaryStandard elevation — dropdowns, popovers
--q-box-shadow-primary-lgshadows/q-box-shadow-primary-lgHigh elevation — modals, floating panels

Primitive token reference ​

Primitive tokens are L1 — fixed values that never change between themes. They live in the primitives collection in Figma and are exposed as CSS custom properties by base.scss.

To update any of these, edit the primitives collection in Figma and communicate the change to the dev team — no _tokens-theme.scss regeneration needed, but a build is required.

Spacing ​

TokenFigma variableValueUsed for
--spacer-0q-spacer-00pxReset / no spacing
--spacer-1q-spacer-10.25remTiny gaps — icon padding, tight inline spacing
--spacer-2q-spacer-20.5remSmall gaps — between label and input, compact lists
--spacer-3q-spacer-30.75remMedium-small gaps — between form fields
--spacer-4q-spacer-41remBase unit — standard padding, button padding
--spacer-5q-spacer-51.5remMedium gaps — card padding, section spacing
--spacer-6q-spacer-62remLarge gaps — between sections
--spacer-7q-spacer-73remExtra large — page-level vertical rhythm

Border radius ​

TokenFigma variableValueUsed for
--q-border-radius-xsq-border-radius-xs2pxSubtle rounding — badges, chips, small tags
--q-border-radius-mdq-border-radius-md8pxStandard rounding — cards, modals, dropdowns
--bs-border-radius-smborder-radius-sm4pxSmall Bootstrap elements — inputs, buttons sm
--bs-border-radius-lgborder-radius-lg16pxLarge panels, toasts, image containers
--bs-border-radius-xlborder-radius-xl32pxPill-shaped elements
--bs-border-radius-xxlborder-radius-xxl800pxFull round — avatars, circular buttons

Border width ​

TokenFigma variableValueUsed for
--bs-border-width (1px default)border-width-11pxDefault border on inputs, cards, dividers
—border-width-22pxEmphasis borders — active tabs, selected states
—border-width-33pxStrong borders — focus rings, alerts
—border-width-44pxHeavy borders — decorative separators
—border-width-55pxMaximum weight borders

Opacity ​

TokenFigma variableValueUsed for
--q-opacity-0q-opacity-00Fully transparent — hidden elements
--q-opacity-25q-opacity-250.25Disabled states, subtle overlays
--q-opacity-50q-opacity-500.50Semi-transparent — hover layers, ghost elements
--q-opacity-75q-opacity-750.75Near-opaque overlays
--q-opacity-100q-opacity-1001Fully opaque — enforce visibility on disabled

Typography — font family ​

TokenFigma variableValueUsed for
(Bootstrap $font-family-base)font-family-sans-serif-primaryBarlowPrimary UI font — all body text, labels, buttons
(Bootstrap $font-family-monospace)font-family-monospace-primaryInterCode blocks, monospace text

Typography — font weight ​

TokenFigma variableValueUsed for
—font-weight-light300Light text — decorative, large display
—font-weight-normal400Body text default
—font-weight-medium500Slightly emphasized labels, nav items
—font-weight-semibold600Subheadings, table headers, badges
—font-weight-bold700Headings, strong emphasis

Typography — font size ​

TokenFigma variableValueUsed for
--q-font-size-xsp/q-font-size-xs12pxCaptions, helper text, badges
--q-input-font-size-smp/font-size-sm14pxSmall inputs, secondary labels
--q-font-size-md / --q-input-font-sizep/q-font-size-md16pxBase body text, default input
--q-input-font-size-lgp/font-size-lg20pxLarge inputs, emphasized text
--q-font-size-xlp/q-font-size-xl24pxSection subtitles, large labels
--q-font-size-xxlp/q-font-size-xxl32pxPage-level titles
--q-d6-font-sizedisplay/q-d6-font-size40pxDisplay 6 / H1 equivalent
--q-d5-font-sizedisplay/q-d5-font-size48pxDisplay 5
--q-d4-font-sizedisplay/q-d4-font-size56pxDisplay 4
--q-d3-font-sizedisplay/q-d3-font-size64pxDisplay 3
--q-d2-font-sizedisplay/q-d2-font-size72pxDisplay 2
--q-d1-font-sizedisplay/q-d1-font-size80pxDisplay 1 — hero titles

Typography — heading size ​

Figma variableValueHTML tag
h/h1-font-size40px<h1>
h/h2-font-size32px<h2>
h/h3-font-size28px<h3>
h/h4-font-size24px<h4>
h/h5-font-size20px<h5>
h/h6-font-size16px<h6>

Typography — line height ​

Figma variableValueUsed for
line-height-sm20pxCompact text — badges, labels, captions
line-height-base24pxBody text default
line-height-lg32pxLarge text, display headings

What not to do ​

❌ Don't✅ Do instead
Edit _tokens-theme.scss manuallyRegenerate it via Claude Code + Figma MCP
Use Token Studio for FigmaUse Figma native Variables (the theme collection)
Use tokens.jsonIt's archived — no longer part of the build
Hardcode hex values in SCSSAlways use var(--token-name)