Overview

The design system's tokens are translated from the Figma Base System file into packages/portal-ui/tokens.css. Every table on these pages is rendered from a build-time parse of that file, so the reference can't drift from the shipped values.

Three layers

1. Primitives — the raw ramps (--neutral-900, --brand-50, …). They are mode-dependent: the same variable resolves to a different value in dark mode, and the ramp effectively inverts (--neutral-900 is near-black in light, white in dark). This mirrors the Figma system exactly.

2. Figma aliases — named aliases carried over 1:1 from Figma (--background-bg-primary, --outer-border, …). Because the primitives flip, most aliases keep the same name in both modes; only a few are re-pointed in .dark.

Product light uses two layout borders of warm Soil ink (neutral-800): --outer-border at 9% (aliased as --border for shadcn) for card and control edges, and --inner-border at 6% for dividers and table rules. Dark uses light ink at higher alpha (5% / 3%) so edges read equally. Emphasis is --outer-border-strong. Thickness is --border-width (1px for every edge). --hairline-width is a compat alias. Cards paint via --card-hairline (inset ring); fields and tables use CSS border. Checkbox / radio keep solid --choice-border. 3. shadcn bridge — the token names @sophic/portal-ui components actually consume (--background, --card, --primary, …), mapped onto the layers above. Bridge values without a Figma counterpart yet are marked derived, pending Figma and will be replaced as the Figma system grows.

Apps opt in by importing @sophic/portal-ui/tokens.css after theme.css and may override any variable in their own globals.css.

Brand Icon

The pinwheel sits inside a rounded square — the same composition as the sign-in flow. Product apps use a forest-green frame for app icons and favicons. This docs site uses a hot-pink frame so its tab is easy to spot. Usage and props are on the Brand Icon component page.

Component tokens

Components get their own variables only where the Figma file defines component-level values — no speculative tokens. Components read them with a fallback to their pre-token styling, so apps that don't import tokens.css are unaffected.

Syncing from Figma

The figma: comment markers in tokens.css delimit machine-rewritten blocks. The sync-figma-tokens skill re-extracts the Figma file and regenerates them — hand edits inside marked blocks are overwritten on the next sync.