Tokens

The token layer ships in nk-lib as @nkapp/lib/tokens.css: the semantic colour mapping every app shares, a type scale, an elevation scale built from veils rather than shadows, and a nine-step z-ladder. Every value on this page is read out of the live stylesheet or measured off the rendered specimen — a tokens page that hardcoded its own values would be documenting a copy.

Colour

The mapping is shared; the channel triplets stay per-app. Both palettes are rendered at once, straight from the stylesheet.

Semantic palette

Both themes, live

Left column is :root, right column is .dark — both lifted out of the bundled stylesheet at runtime and applied as inline custom properties, so this is the real palette rendering twice rather than a table about it. The first line under each swatch is the declared OKLCH triplet; the second is the sRGB the browser actually painted.

Light · :root
backgroundAa
——
cardAa
——
popoverAa
——
primaryAa
——
secondaryAa
——
mutedAa
——
accentAa
——
destructiveAa
——
border
input
ring
aura-cyan
veil-5
veil-10
Dark · .dark
backgroundAa
——
cardAa
——
popoverAa
——
primaryAa
——
secondaryAa
——
mutedAa
——
accentAa
——
destructiveAa
——
border
input
ring
aura-cyan
veil-5
veil-10

Why there is no “theme this subtree” trick: a custom property is substituted at the element where it is declared. --color-primary is declared once on :root as oklch(var(--primary)), resolved there, and inherited already-finished — so setting --primary on a nested element changes nothing. The two panes above work only because they re-declare the mapping as well as the channels. Worth knowing before you try to theme a region of a page.

The four dark --background values across the eight apps diverge on purpose — that is a product decision, not drift. What is shared is the mapping: tokens.cssowns which utility exists and which colour function wraps the channels; each app’s global.css owns the triplets.

The format-coupling rule

The single most expensive mistake this layer exists to prevent. Not an argument — a measurement.

hsl(var(--primary))

Measured, not argued
Correct · semantic tokenbg-primary—
Coupled · deliberate bughsl(var(--primary))—

The worked example is NkUsageBar, which styled its primary variant as shadow-[0_0_8px_hsl(var(--primary)/0.3)] — teal fill, white halo. It is fixed, and the fix is the format-agnostic path rather than a new token: shadow-[0_0_8px] shadow-primary/30, because Tailwind’s shadow utilities fill --tw-shadow-color from the semantic token via color-mix. A --shadow-glow-primary token was deliberately not added: the obvious spelling would have re-introduced the coupling it exists to remove.

Correct
A component consumes the semantic token — bg-primary, var(--color-primary), shadow-primary/30. The colour function is applied in exactly one place, tokens.css §1, and the call site never knows which colour space it is in.
Regressed
The call site re-wraps the raw channel triplet: hsl(var(--primary)/0.3). hsl() accepts unitless numbers, so it reads the OKLCH lightness as degrees of hue and the hue as a percentage lightness, clamps to 100% and renders white. No error, no warning, no failing build — it failed silently in 2 of 8 apps and converting the other six would have made it fail in all of them.

Type

Six steps, each carrying its own weight, leading and tracking, plus the two composites the --text-* namespace cannot express.

--text-*

6 steps

Each step is registered under Tailwind's --text-* namespace, so the utility carries size, weight, line-height and tracking together — you never pair text-display with a separate font-weight. The metrics on the right are measured off the specimen next to them.

text-display
Environments

View titles. One per screen.

—
text-heading
Deploy targets

Section + modal titles.

—
text-title
Gateway routes

Panel headers, card titles.

—
text-body
Three services will be rebuilt and the routes reloaded.

Default text and table cells.

—
text-label
LAST DEPLOY

The uppercase micro-label.

—
text-fact
127.0.0.1:3006 · 41ms

Machine facts.

—

nk-label · nk-fact

Composites

Two levels are defined by more than the type scale can carry: a label is always uppercase, a fact is always monospace. These classes are the whole style in one token.

Deploy target

nk-label — uppercase, over the --text-label step. Its size, weight, line-height and tracking are the four values measured off the label row of the --text-* specimen above, and are deliberately not transcribed here: the step was retuned once already, and the transcription is the thing that went stale.

nk-prod-vps · 187.124.188.112 · 41ms

nk-fact — the Mono-for-Facts Rule: anything a machine produced or consumes is monospace.

Adopting the scale

A no-op substitution

These two rows are the same rendering, and that is the demonstration. nk-label used to be the specs/DESIGN.md proposal — 11px / 700 / 0.08em — which made adopting it a visual change at every call site, and a mechanical substitution into a design review. It was retuned to the string the apps actually render, so the token now IS that string and swapping one for the other changes nothing. The cost moved rather than vanishing: the sites already on nk-label are the ones that shifted. modules/nk-lib/src/tokens.css names them.

Copy-pasted 171× todayLast deploytext-[10px] font-black uppercase tracking-widest
The tokenLast deploynk-label

cn()

The scales above only survive if the call site goes through cn. This is the mechanism that makes that true, re-checked on every render.

cn()

All tokens registered
Type steps · cn('text-X', 'text-foreground')
text-displaytext-display text-foregroundPass
text-titletext-title text-foregroundPass
text-headingtext-heading text-foregroundPass
text-bodytext-body text-foregroundPass
text-labeltext-label text-foregroundPass
text-facttext-fact text-foregroundPass
Z-ladder · cn('z-X', 'z-50')
z-basez-50Pass
z-raisedz-50Pass
z-stickyz-50Pass
z-headerz-50Pass
z-scrimz-50Pass
z-drawerz-50Pass
z-popoverz-50Pass
z-toastz-50Pass
z-tooltipz-50Pass
Through cn()Gateway routes
What an unregistered merge returnedGateway routes

The maintenance rule, plainly: a token added to tokens.css must also be registered in src/utils/cn.ts, or it silently misbehaves. Not “may” — will, in one of the two directions above, with no error, no warning and no failing build. Adopting the type scale is therefore not just a class swap: it depends on the call site going through cn at all.

Correct
cn('text-title', 'text-foreground') keeps both classes, and cn('z-popover', 'z-50') returns just z-50 — an override genuinely displaces the base class instead of racing it in stylesheet order.
Regressed
tailwind-mergeonly knows Tailwind’s stock class names, so it guesses, and it guesses wrong in both directions: text-title gets filed as a colour (the text- prefix is shared by size and colour), the later colour wins and the type step is deleted; z-tooltip is not recognised as a z-index at all, so it displaces nothing and the winner is left to stylesheet order.

Elevation

Depth by lightness and a hairline fence, because a black shadow cannot be darker than a near-black base.

nk-elevate-1 · nk-elevate-2

Veil + hairline

Depth is a translucent tonal layer fenced by a 1px hairline, not a drop shadow. Stacking another veil reads as one step closer. Nested here so the steps are adjacent — which is the only way to judge them.

Base
nk-elevate-1 · veil-5
nk-elevate-2 · veil-10

--shadow-*

3 tokens

Deliberately short. Two ambient shadows that always ship WITH a hairline, and one fence on its own. A shadow is only allowed to detach a genuinely floating layer from the page.

hairline

The fence alone.

ambient

A raised control.

overlay

Menus, dialogs.

Why the stock shadows were escalating

Dark ground, live

Tailwind's shadows are pure black at 10–25% alpha — that is how you separate surfaces on a LIGHT ground. On a near-black base a black shadow cannot be darker than what is already there, so it does not read, so the codebase reached for shadow-2xl and then for hand-rolled glows. Both panes below are real; only the palette differs.

Light ground
shadow-2xl
nk-elevate-1
Dark ground
shadow-2xl
nk-elevate-1

The Tonal Layering Rule: if you reach for box-shadow to separate two flat panels, the layering is wrong — stack a veil instead.

Z-layers

Nine named rungs replacing twelve raw values — printed, and then proved by painting them in reverse.

--nk-z-*

9 rungs

Nine named rungs replacing twelve raw values. Two resolutions are encoded: z-popover sits ABOVE z-drawer on purpose — a select opened inside a dialog must paint over that dialog — and z-tooltip replaces the z-[9999] escape hatch.

z-base—In-flow content. The default.
z-raised—Layering inside a card or table. Never escapes it.
z-sticky—Page-level sticky chrome.
z-header—The persistent app header.
z-scrim—The dimming backdrop behind a drawer.
z-drawer—The drawer / modal panel itself.
z-popover—Menus, selects, comboboxes.
z-toast—Transient notifications.
z-tooltip—Always last. Never traps focus.

The ladder, painted

Reverse DOM order

These plates are written to the DOM top rung first. If the utilities did nothing, 'base' — written last — would be on top. It is not: the stack reads in ladder order, which is the only evidence that matters.

z-tooltip—
z-toast—
z-popover—
z-drawer—
z-scrim—
z-header—
z-sticky—
z-raised—
z-base—

Spacing

The scale that was deliberately left alone, and why adding to it would have made things worse.

--spacing

Nothing added

The one scale this pass deliberately did not extend. DESIGN.md's spacing scale already IS Tailwind's: v4 derives every step from --spacing: 0.25rem, so p-2 is 8px. Adding --spacing-xs would create a second spelling of a step that already exists and let p-xs and p-2 drift apart in review. The reconciliation is this row, not a token — and the numbers are measured off the boxes, so it is checkable.

xsp-2—
smp-3—
mdp-4—
lgp-6—
xlp-8—

Adoption

An honest ledger of what the token layer drives today.

tokens.css

7/8 reached

What the token layer actually drives today, audited against modules/nk-lib rather than assumed from the spec.

  • Semantic colour mappingIn use

    All eight apps consume one @theme block instead of eight hand-copied ones. The channel triplets stay per-app; only the mapping moved.

  • aura-cyanIn use

    Consumed by NkSidebar — the navigation accent it had been referencing before the colour existed anywhere in the monorepo.

  • veil-5 · veil-10In use

    Used directly as bg-veil-5 / bg-veil-10 by NkOtpInput, NkBottomSheet and NkNotificationCenterButton.

  • nk-elevate-1 · nk-elevate-2Declared only

    No consumer. The composites exist; the components that stack veils spell it out by hand. A token nothing consumes is a proposal, and this page says so.

  • --shadow-* scalePartial

    shadow-overlay and shadow-ambient are consumed by NkPopover, NkTable, NkSplitPane, NkBottomSheet and NkNotificationCenterButton. Raw shadow-2xl and arbitrary glows survive elsewhere.

  • Type scalePartial

    nk-label in NkTable and NkOtpInput; nk-fact in NkSteps and NkRelativeTime; text-title/text-heading in NkEmptyState. The ~40 copy-pasted label strings across hub, auth, admin and website are untouched — migration is a deliberate visual change, not a mechanical one.

  • Z-ladderPartial

    Adopted by NkPopover (and everything that renders through it), NkDrawer, NkBottomSheet, NkSplitPane and NkNotificationCenterButton. NkTooltip still carries a raw z-50, which is exactly the rung it should not be on.

  • cn() registrationIn use

    Both lists match tokens.css: six --text-* steps and nine --nk-z-* rungs. The matrix above re-checks that every time this page renders.

Source: modules/nk-lib/src/tokens.css and modules/nk-lib/src/utils/cn.ts. Imported by this app in src/app/global.css, after @import "tailwindcss" — the at-rules have to be processed by Tailwind v4 to emit anything at all.