Tokens

Token layers

Full dependency chain:

Figma variable → Base → Semantic → State → Component → Platform → Tailwind/shadcn

Why six layers

The system originally ran on four layers — Base → Semantic → Component → Tailwind. That structure worked until three things broke it.

The State and Platform layers do not introduce new values. They introduce rules about how values change — which is exactly the part that was previously duplicated by hand.

Layer rules

• A token may only reference the layer directly below it, or any layer further down. It may never reference the layer above.
• Components never reference Base tokens. If a component needs a raw value, the missing piece is a semantic token, not an exception.
• The State layer defines transformations, not new palettes. If a hover value is not derivable from its semantic parent, the semantic token is wrong.
• The Platform layer only ever remaps existing tokens. It never defines a token that exists nowhere else.
• The Bridge layer is the only layer allowed to know the name "Tailwind" or "shadcn". Everything below it is framework-agnostic.

Naming convention

--ds-{group}-{role}-{variant}-{state}
     │       │       │         └── hover, active, selected, disabled
     │       │       └── sm / md / lg / primary / secondary
     │       └── bg, text, border, icon, shadow, radius
     └── palette group, semantic role, or component name

Every token is prefixed --ds-. The prefix is what keeps the system from colliding with Tailwind's own variables when both are live in the same scope.

Figma variables → Base tokens

Figma variable collections map 1:1 onto the Base layer. The MCP server returns variable names with the collection path intact, so the mapping is mechanical:

Semantic and above are authored in code, not in Figma. Figma owns raw values; the DS owns meaning. This is why a renamed Figma style never breaks a component — it only ever invalidates one Base token.

Base tokens

Raw values with no attached meaning. These exist only to be referenced by higher layers.

Color

Seven palette groups, each spanning 10 steps from 900 (darkest) to 50 (lightest).

All 70 steps, as declared. Every value the rest of this system derives — a hover one step darker, a border on the 400 step, an icon on the 700 — is resolvable from this table without opening ds.css.

Plus --ds-white (#FFFFFF) and --ds-hero-gradient (linear-gradient(180deg, #0A4ABF, #0F62FE)), the one gradient in the system and a marketing-only surface.

Two gray steps are deliberately off-ramp from the usual Tailwind values: gray-500 (#636971, normally #6B7280) and gray-400 (#727780, normally #9CA3AF). Both were darkened until muted text and placeholder text clear 4.5:1 on white. See Color for the full contrast table.

Spacing

4px base unit, 10 steps. Every step is a multiple of 4 — there are no half-steps, and no arbitrary values.

Typography

Minor third scale (1.200), snapped to the 4px grid.

Families and weights:

System fonts are a deliberate constraint, not a placeholder. Senco ships to users on metered and unreliable connections; a webfont is a render-blocking request that buys nothing the system needs. It also sidesteps the Figma MCP limitation that custom typefaces do not survive the pipeline.

Shape and elevation

Shadow opacity tops out at 8%. Elevation in Senco signals layering, not drama — a modal should read as above the page, not as a different material.

Motion

Sizing

Z-index

A fixed six-step scale. No component may invent a z-index outside it.

Toast sits above modal on purpose: a transfer failure must be readable while a confirmation dialog is still open.

Semantic tokens

Intent-based aliases. Components reference this layer, not the Base layer. This indirection is what makes theme switching possible.

Color

On-colors

Text and icon colors used on filled surfaces. These exist so that no component has to guess whether white text is legible.

Feedback

Each feedback state is a four-token set — background, border, text, icon — so a notice never has to compose its own palette.

Tip is accent-based rather than info-based. Info is a system message; a tip is Senco talking. Keeping them on different hues prevents the two from blurring together on a busy transfer screen.

Spacing and typography aliases

Semantic spacing names the relationship, not the size. These are conventions in use, not declared variables — the relationship is documented so it stays consistent, and formalizing it as tokens is open work:

State tokens

The State layer defines how a semantic token transforms under interaction. It holds no independent palette — every state value is derived from its semantic parent by a documented rule.

Transformation rules

Which focus form applies is decided by one question: does the control have a visible border at rest? Inputs, selects, input groups, and bordered cards use the bordered form. Buttons, links, toggle items, tabs, switches, list rows, and scroll regions use the outline. The indicator that must meet 3:1 is the border or the outline — the 20% halo is decoration and measures about 1.33:1 against white.

Because each rule is expressed once, the hover behavior of a button, a contact card, and a sidebar item are provably the same thing rather than three similar-looking implementations.

Implemented state tokens

The focus ring is built with color-mix() rather than a fixed rgba value. That is what lets dark mode remap --ds-focus and get a correct ring for free — the transformation survives the theme switch, because the transformation is the token.

State pairs in component tokens

Component tokens that carry state name it explicitly and in pairs:

--ds-actionbtn-primary-bg:          var(--ds-primary);
--ds-actionbtn-primary-bg-hover:    var(--ds-primary-hover);
--ds-actionbtn-primary-shadow:      var(--ds-shadow-sm);
--ds-actionbtn-primary-shadow-hover: var(--ds-shadow-md);

A component token with a -hover variant but no base variant is a bug. Review catches this as an unpaired state.

Utility prefixes

In markup, states are applied with Tailwind's prefix syntax, which resolves through the Bridge layer:

Focus uses focus-visible:, not focus:. A mouse click on a button should not leave a ring behind; a Tab key press must.

Component tokens

Scoped to a single component. Component tokens compose semantic and state tokens, and are the only place a component-specific decision is allowed to live.

Buttons — three components, three token sets

--ds-actionbtn-* does not style the ordinary button. It styles the dashboard action tile: a 72px-tall card with a 40px circular icon above its label. Reading it as the generic button is what produced a 6px-versus-9999px radius contradiction across three files, so the ownership is stated explicitly here.

Action tile

Pill button

Button (default) has no component block. It composes --ds-primary / --ds-primary-hover / --ds-on-accent / --ds-border directly with --ds-radius-md. The danger variant has no component tokens either, and currently resolves to --ds-red-600 — a Base reference, which this layer's own rules forbid. Recorded in Known drift below.

Input

Notice / Feedback

Feedback components consume the semantic feedback sets directly — they define no component tokens of their own. This is intentional: a notice that needed its own colors would mean the semantic set was incomplete.

Senco components

Product-specific components carry the largest component-token blocks, because they encode domain decisions that no generic library would have:

Camera and QR surfaces are the one documented exception to theme remapping. A viewfinder inverts in light mode for no benefit and costs the user their frame of reference, so those tokens are hard values by design. The exception is recorded here rather than discovered in the CSS.

Platform tokens

The Platform layer resolves environment. It never invents values — it only remaps tokens that already exist, which is why adding a theme cannot break a component.

Theme resolution

Dark mode is a remap of the semantic layer, applied at .ds-layout.ds-dark:

Brand blue lightens in dark mode. #0F62FE on #0F172A measures 3.57:1 — under the 4.5:1 bar for text. #458DFF measures 5.53:1 and clears it. The base palette is untouched; only the semantic alias moves.

Lightening the primary fill has a consequence handled in this same layer: --ds-on-accent remaps to #0F172A, because a white label on #458DFF measures 3.23:1. The button component does not change — it still reads --ds-on-accent. See Themes.

Reduced motion

A single platform block neutralizes animation system-wide — components do not each implement their own guard:

@media (prefers-reduced-motion: reduce) {
  .ds-layout *,
  .ds-layout *::before,
  .ds-layout *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Viewport resolution

Breakpoints are Platform-layer inputs, not component decisions. A component reads a container token; the Platform layer decides which container applies. See Responsive breakpoint tokens below.

Scoped platform targets

The prototype scope is a real platform target, not a workaround. A prototype frame represents the Senco app, which has its own theme state independent of the page hosting it.

Density — defined, not implemented

The layer reserves compact and cozy density variants, remapping --ds-space-* and control heights. Neither is implemented in ds.css today. Senco's screens are single-task and mobile-first, so density has never earned its cost. The slot stays documented so that if a desktop transaction table ever needs it, it lands in the Platform layer rather than as per-component overrides.

Component library integration

The Bridge layer — the sixth and outermost. Senco builds on shadcn (base-nova style). A CSS variable bridge maps shadcn and Tailwind variables onto Senco semantic tokens inside the .ds-layout scope.

Sidebar and chart bridges follow the same pattern (--sidebar-*, --chart-1 … --chart-5).

This bridge lives in ds.css, so shadcn components pick up Senco branding without per-component overrides.

The bridge depends on inheritance

The bridge is declared once, on the scope root, and every component reads it by inheritance. Anything that re-declares the same framework variables on descendants — a host application's theme written as .theme * rather than .theme — silently replaces the Senco values with the host's, and nothing looks broken except the colours. When the system is embedded in a host with such a rule, the scope re-asserts inheritance for exactly the variables the bridge defines:

.ds-scope.host-theme *:not(.prototype-scope) {
  --primary: inherit;
  --primary-foreground: inherit;
  /* …every variable the bridge declares */
}

Verification is a single check: a primary button inside the scope must render --ds-primary in light mode and the dark value after the theme switches. If it renders the same colour in both themes, the bridge is not reaching it.

Why the bridge is a layer, not a detail

Everything below layer 6 is technology-agnostic. Moving Senco from Tailwind to CSS-in-JS, or to a native platform, means rewriting one file — the bridge — and nothing else. The DS does not know what renders it, and that is the property the layer exists to protect.

Timing and threshold values

Durations that are not animation. A spec that says a value is "debounced", "throttled", or "has a timeout" has described a requirement and withheld the only part a developer cannot derive — and two developers will pick different numbers, which for a rate quote means two different prices on screen.

These are system defaults. A product surface may override one, but it may not leave it unstated.

Rate expiry is visible before it happens

A quote does not expire silently at zero. The remaining validity is shown from the halfway mark, and expiry replaces the figure with a refresh action rather than a stale number. See Amount input and Transfer flow.

Numeric display precision

"Full precision" previously stood in for the FX rate row. Six significant figures is what makes a rate comparable across corridors — a fixed decimal count either truncates 0.923145 or pads 1,650.00 with noise.

Currency minor units

The minor unit drives amount precision, and three examples are not a contract. The system takes minor units from ISO 4217, via Intl.NumberFormat, with two exceptions it must carry itself:

Known gaps — not yet tokenized

None of the values above exist as --ds-* declarations in ds.css. They are a contract stated here and implemented in component logic. Promoting them to tokens (--ds-timing-settle, --ds-timing-quote-fiat) is open work; until then this table is the single source and a component that picks its own number is a defect.

Responsive breakpoint tokens

Container widths resolved at each breakpoint:

Rules

• Never hard-code raw values in component styles.
• Always reference the layer directly below. Never skip upward.
• Base tokens exist only to be referenced by higher layers.
• Components never reference Base tokens. A missing semantic token is the real problem.
• State tokens must be derivable from their semantic parent by a documented transformation.
• Every component token carrying -hover must have an unprefixed base counterpart.
• Platform overrides only remap. A token introduced inside a theme block is a bug.
• All interactive elements define hover, focus-visible, and disabled states.
• shadcn components inherit Senco tokens via the bridge — do not override individually.

Adding a token

1. Does an existing semantic token cover it? If yes, stop.
2. If the value is raw and reusable, add it to Base and alias it in Semantic.
3. If it only varies by interaction, it belongs in State as a transformation.
4. If it applies to exactly one component, add it to that component's block — and only after 1–3 have failed.
5. Record the decision. A token whose reason is not written down gets duplicated within a quarter.

Deprecating a token

Removal is a two-step change, never one. Mark the token deprecated in ds.css with its replacement named inline, leave it aliased for one release, then delete. An immediate delete turns into a hunt across 29 spec files and every prototype.

Known drift

Drift is listed rather than hidden. An agent reading this file needs to know which statements are contracts and which are intent — an undocumented gap is what produces confidently wrong generated code.