Display Axes

Five axes, five attributes

Each axis is a provider, a control, a hook, one attribute on <html> and one localStorage key. Nothing crosses between them: switching to dark does not change the contrast, and going compact does not change the font size. Do not confuse these with the two navigation axes — WorkspaceSwitcher (which data) and AppLauncher (which product) — which are a different set entirely.

All five persist the same way: one string in localStorage under the key named on each card. That makes them per user and per device — nothing is sent to a server, and the same person gets large text on their phone and compact rows on their laptop without the two fighting. If you need a choice to follow an account across machines, that is an app-level preference you store yourself and feed in through defaultValue.

The controls, live

Watch the card while you use the two right-hand controls. Compact layout moves the table's row padding and header height — --row-py and --table-head-h — and nothing horizontal, because “compact” means more rows in view, not text pushed against the edge. Font size moves the root size, so the badge, the button and the icons scale with the text instead of drifting out of proportion with it.

Reading an axis in your own code

Four hooks ship with the package; useTheme is not one of them, because axis 1 is next-themes and you read it with next-themes' own hook. All four package hooks throw outside their provider rather than quietly returning a default — a control that silently does nothing is far harder to diagnose than one that crashes on the first render. The table below is live: it reflects the choices you just made. Its third column is not derived from the hook values — it is read off document.documentElement through a MutationObserver, so the remove-at-default rule below is observable rather than asserted. The snippet leaves that part out; it shows the hooks only.

Each hook also returns mounted, and it is not optional decoration. The provider must hold its default value through the first client render or React reports a hydration mismatch, so the stored choice only lands in state after the first effect. In that gap the hook reports the default, not the truth. The four axis controls gate on it the same way — disabled={!mounted} — so a fast clicker cannot overwrite their own saved setting with the placeholder one. ThemeToggle has no provider flag to read, so it keeps a mounted state of its own and answers the same problem differently: until its first effect it renders a same-size empty <span aria-hidden /> rather than a disabled button — nothing to click, and the layout still does not jump.

Persisting a choice as an account default

All five controls take a notify callback: onContrastChange has been there since ContrastToggle shipped, and 1.8.0 added onThemeChange, onDensityChange and onFontSizeChange so the other three match; PalettePicker arrived in 3.15.0 with onPaletteChange. They exist for the one thing the localStorage model cannot do on its own — letting the app learn a choice was made, so it can record an account default that follows the user to their next device.

onThemeChange hands you a ThemeChoice — "light" | "dark" | "system", exported in 1.8.0 — a closed set of three in which "system" is a real value, not “unchosen”. An account default has to store all three: collapse it to a light/dark boolean and you throw away follow the OS, which is exactly what someone who runs dark-by-schedule loses on their second machine. And variant="icon" never emits "system" — it only flips light ⇄ dark — so a UI that must let the user get back to system has to use variant="menu".

Seeding the account default before first paint

New in 3.7.0, in @comitor/ui/shell. DisplayPrefsSeedScript writes the account's defaults into localStorage with a synchronous inline script, ahead of the anti-flash scripts, so the very first frame is already right — and since 3.15.0 it takes a palette key beside theme, contrast, density and fontSize. The provider props cannot do this: defaultValue is the product’s default, used only while a device has nothing stored, so a device that already holds a value never learns that the account changed — and defaultContrast reaches the page only through an effect, after the paint.

The rule is follow the account, unless this device was changed by hand. Beside each key the script keeps a marker, <key>-seeded, holding what it seeded last: no value yet → seed; the account changed and the device still holds the old seed → seed again; the device holds something else → keep it, because the person chose it here. Render it as the first child of <body>, above the providers; with nothing valid to seed it renders nothing — even an empty script is one more thing CSP has to allow.

// app/layout.tsx — a Server Component. The seed is the account's defaults, read
// wherever your app keeps them (a cookie written at sign-in, the session…).
import {
  ContrastProvider,
  DensityProvider,
  DisplayPrefsSeedScript,
  FontSizeProvider,
  PaletteProvider,
  ThemeProvider,
} from '@comitor/ui/shell'
import { headers } from 'next/headers'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const nonce = (await headers()).get('x-nonce') ?? undefined
  const seed = await readAccountDisplayDefaults() // e.g. { theme: 'dark', contrast: 'high', palette: 'teal' }

  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        {/* FIRST child of <body>, above the five providers: their anti-flash
            scripts run in document order, and must find the seeded values. */}
        <DisplayPrefsSeedScript seed={seed} nonce={nonce} />
        <ThemeProvider nonce={nonce}>
          <ContrastProvider nonce={nonce}>
            <DensityProvider nonce={nonce}>
              <FontSizeProvider nonce={nonce}>
                {/* Only in a product that lets the user choose a palette: without this
                    provider the seed's palette key is stored and never read. */}
                <PaletteProvider nonce={nonce}>{children}</PaletteProvider>
              </FontSizeProvider>
            </DensityProvider>
          </ContrastProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

Wiring all five

Every provider belongs at the root layout, above AppShell rather than inside it — sign-in pages, landing pages and error pages need the same appearance as the app. The layout itself stays a Server Component. What follows is the display-axis part of this site's own layout, which also carries a language segment and ComitorLocaleProvider (see app/[lang]/layout.tsx).

// app/layout.tsx — a Server Component. The display-axis part of this site's own root layout
// (app/[lang]/layout.tsx, which also takes the language segment and mounts ComitorLocaleProvider),
// with the metadata and viewport blocks cut down to one line and the comment translated.
import { ContrastProvider, DensityProvider, FontSizeProvider, PaletteProvider, ThemeProvider } from '@comitor/ui/shell'
import type { Metadata } from 'next'
import { Inter } from 'next/font/google'
import './globals.css'

const inter = Inter({
  subsets: ['latin', 'vietnamese'],
  weight: ['400', '500', '600', '700', '800'],
  display: 'swap',
  variable: '--font-inter',
})

export const metadata: Metadata = { title: 'Comitor Design System' }

/**
 * The five axes know nothing about each other, so the NESTING ORDER is arbitrary.
 * All five anti-flash scripts are rendered by the providers themselves, inside
 * <body>, ahead of the app's markup — nothing goes into <head>.
 *
 * Palette: this site lets the READER choose (the picker in the header), so that every
 * demo can be seen under every palette — hence the provider, on the package default,
 * gold. It does NOT also write data-palette on <html>: that attribute plus a provider
 * without defaultValue renders gold (the provider's script removes the attribute when
 * the final value is gold). No CSP here, so no nonce; add one and pass it to all five.
 *
 * `suppressHydrationWarning` on <html> is mandatory: those five scripts edit this
 * element before React hydrates, so the client HTML never matches the server's.
 */
export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="en" suppressHydrationWarning className="bg-background">
      <body className={`${inter.variable} font-sans antialiased`}>
        <ThemeProvider>
          <ContrastProvider>
            <DensityProvider>
              <FontSizeProvider>
                <PaletteProvider>{children}</PaletteProvider>
              </FontSizeProvider>
            </DensityProvider>
          </ContrastProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

• Nesting order is arbitrary. The five contexts never read one another, so any permutation behaves identically.
• Language is not a sixth axis. ComitorLocaleProvider belongs in the same root layout, but it writes no attribute on <html>, runs no anti-flash script and keeps nothing in localStorage — the language is the user’s account setting, handed down on the server. It reads none of the five and none of them reads it, so it can wrap them or sit between them. What must be inside it is every control on this page: their strings come from its shell, contrast and displayAxis namespaces. This site renders none, because it is English and English is the default; a Comitor app renders one, as below (Set the language).
• suppressHydrationWarning on <html> is mandatory. Five inline scripts edit that element before React hydrates. Without the attribute React reports a mismatch on every load of every page; with it, only <html> itself is exempted, not the tree below it.
• Nothing goes in <head>. The app adds no script tag of its own — see the next section.
• next-themes must be a single copy. It keeps one context singleton for the whole tree. Two copies in node_modules and the app's useTheme() reads a different provider than the package's — nothing fails to compile, the theme button just stops working.

// app/layout.tsx in a Comitor app — the four every app mounts, plus the language. PaletteProvider
// (the fifth) only when users may pick the theme colour — see Theme palette above.
import { ComitorLocaleProvider } from '@comitor/ui'
import { ContrastProvider, DensityProvider, FontSizeProvider, ThemeProvider } from '@comitor/ui/shell'
import { getLocale } from 'next-intl/server'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  // The user's own setting, through next-intl — never a hard-coded 'vi'.
  const locale = await getLocale()

  return (
    <html lang={locale} suppressHydrationWarning>
      <body>
        {/* Outside the four or between them: none of the five reads another. */}
        <ComitorLocaleProvider locale={locale}>
          <ThemeProvider>
            <ContrastProvider>
              <DensityProvider>
                <FontSizeProvider>{children}</FontSizeProvider>
              </DensityProvider>
            </ContrastProvider>
          </ThemeProvider>
        </ComitorLocaleProvider>
      </body>
    </html>
  )
}

The anti-flash script lives in the body

A stored choice has to be on <html> before the first paint. React effects run after paint, so an effect is too late: someone who chose high contrast, or large text, would see one frame of the default and then a jump. Each provider therefore renders a tiny synchronous script — ContrastScript, DensityScript, FontSizeScript, PaletteScript — as its own first child. An app does not add these; the provider already did. They are exported only for the case where you build your own provider or need the tag somewhere else in the body.

The script reads one localStorage key and, if the value is not the default, writes one attribute. Since 3.15.0 the density, font-size and palette scripts also apply the provider’s defaultValue when nothing is stored, and remove the attribute when they land on the package default; every prop value they interpolate is escaped first, so a storageKey containing </script> cannot close the tag. It touches nothing else, it cannot throw (the read is wrapped — a browser with storage blocked simply falls back to the default), and running it twice is a no-op.

The default value writes nothing

Four of the five axes remove their attribute at the default rather than writing it. There is no data-contrast="normal", no data-density="comfortable", no data-font-size="md", no data-palette="gold" — and correspondingly no CSS block for any of them. (Axis 1 is the exception: next-themes writes class="light" or class="dark" either way, which is its own convention.)

For density this is tidiness. For font size it is an accessibility decision. The medium step must not stamp an absolute size onto <html>. A visitor may have already raised the default text size in their browser; declaring font-size: 16px at the root erases that choice — a WCAG 1.4.4 violation committed inside an accessibility feature. Writing nothing at the default leaves the browser's own size intact, and the two other steps are percentages of that size:

Scaling the root size rather than overriding the --text-* tokens is also deliberate. Icons in the package take their size from the spacing scale, not the type scale — roughly 150 places resolve to calc(var(--spacing) * n) — so moving only the text would leave 16px labels beside 16px icons in every menu row, and would break Kbd first. Moving the root moves everything expressed in rem together and keeps the icon-to-text ratio fixed.

Why only axis 1 uses next-themes

The obvious move for axis 2 would have been a second next-themes provider with attribute="data-contrast" and its own storage key. It does not work. next-themes keeps one context singleton for the whole tree, so nesting a second provider means the innermost one wins and the app's useTheme() starts reading the wrong axis. Nothing fails to compile. The light/dark button simply stops responding, and the cause is nowhere near the symptom.

The contrast axis is also simpler than a theme: two values, no system setting, no prefers-color-scheme query. Sixty hand-written lines cover it without paying that price. Axes 3, 4 and 5 would have been near-identical copies of those sixty lines, so they come out of a shared factory instead — same mount-then-read sequence, same mounted flag, same in-body script, same remove-at-default rule.

ContrastProvider was deliberately left off that factory: it is published API with documented behaviour, and rewriting it is a risk with no payoff. The visible trace of that history is the prop name — defaultContrast on the contrast provider, defaultValue on the other three.

What the high-contrast palette is for

The default palette is the approved comitor-ds look, and it is legible on a good monitor in a normal room. It is not legible on a cheap panel, at low screen brightness, or outdoors — several of its pairs sit under the WCAG threshold on purpose, as a design decision rather than an oversight. The high-contrast palette is the measured set: same components, same layout, different values for the CSS variables. It is a choice the user makes in settings, not something the product decides for them.

The two palettes are separate from light and dark. Each palette has its own light build and its own dark build, which is exactly why this cannot be one four-way theme list: a user picks a side of each axis independently.

The full contract, the token tables and the measured ratios are on Foundations · Colour.

Constants and type guards

Never hard-code 'comitor-density' or 'data-contrast' in an app — import them. The four guards are the same functions the providers use to validate what comes back out of storage.

import {
  CONTRAST_ATTRIBUTE, // 'data-contrast'
  CONTRAST_MODES, // ['normal', 'high']
  CONTRAST_STORAGE_KEY, // 'comitor-contrast'
  DEFAULT_DENSITY, // 'comfortable'
  DEFAULT_FONT_SIZE, // 'md'
  DEFAULT_PALETTE, // 'gold' — the PACKAGE default, whatever defaultValue an app passes
  DENSITY_ATTRIBUTE, // 'data-density'
  DENSITY_MODES, // ['comfortable', 'compact']
  DENSITY_STORAGE_KEY, // 'comitor-density'
  FONT_SIZE_ATTRIBUTE, // 'data-font-size'
  FONT_SIZE_MODES, // ['sm', 'md', 'lg']
  FONT_SIZE_STORAGE_KEY, // 'comitor-font-size'
  isContrastMode,
  isDensityMode,
  isFontSizeMode,
  isThemePalette,
  PALETTE_ATTRIBUTE, // 'data-palette'
  PALETTE_STORAGE_KEY, // 'comitor-palette'
  THEME_PALETTES, // ['gold', 'green', 'teal', 'blue', 'indigo', 'violet', 'rose', 'orange', 'graphite']
  type ThemePalette,
} from '@comitor/ui/shell'

// All of the above are readable from a Server Component. They live in modules with
// NO 'use client' directive (contrast-constants.ts, display-axis-constants.ts), and
// shell/index.ts re-exports them straight from those modules rather than through the
// providers. Route a constant through a client module and an RSC reads it back as
// undefined — no error, no warning.
export function readStoredDensity(raw: unknown) {
  return isDensityMode(raw) ? raw : DEFAULT_DENSITY
}

Note what is not on that list: there is no DEFAULT_CONTRAST. Axes 3, 4 and 5 got DEFAULT_DENSITY, DEFAULT_FONT_SIZE and DEFAULT_PALETTE because the factory needs a named default; axis 2 hard-codes 'normal' in its own signature. The toggle labels do have a constant — DEFAULT_CONTRAST_TOGGLE_LABELS — though since 3.0.0 it is only the English table, kept for an app to spread: ContrastToggle itself reads the contrast namespace of ComitorLocaleProvider, and the Vietnamese pair is comitorMessagesVi.contrast.

Resetting and scoping

The four package hooks give you the setters, so a “restore defaults” button is four calls. It is worth having: a user who set large text on a phone and compact rows on a laptop has two independent states to undo, and these settings never leave the device. The button below is live — it resets this site. Light and dark is not in it, because that axis belongs to next-themes and has its own control.

Two products on the same domain would otherwise share these keys, since localStorage is scoped to the origin. Give each one its own key when that is wrong. The key and the starting value are yours to set; the attribute names are not, because styles.css selects on them.

// A second product on the same domain that must not inherit the first one's choices.
// The storage key and the starting value are yours; the attribute names are not, because
// styles.css selects on them.
import type { ReactNode } from 'react'
import { ContrastProvider, DensityProvider, FontSizeProvider } from '@comitor/ui/shell'

export function CrmDisplayProviders({ children }: { children: ReactNode }) {
  // ⚠ Since 3.15.0 the density, font-size and palette scripts are handed the provider's
  // defaultValue, so defaultValue="compact" is right on the first paint of a first visit.
  // The CONTRAST script is not: it takes no default and writes the attribute only when
  // the stored string is 'high'. So defaultContrast="high" still paints one frame of
  // normal contrast on a first visit, until the provider corrects it. From the user's
  // first click onward the stored value drives the script and there is no flash.
  return (
    <ContrastProvider storageKey="crm-contrast" defaultContrast="high">
      <DensityProvider storageKey="crm-density" defaultValue="compact">
        <FontSizeProvider storageKey="crm-font-size">{children}</FontSizeProvider>
      </DensityProvider>
    </ContrastProvider>
  )
}

Three ways to get this wrong

• Putting a display control inside a settings form. All five controls apply and persist immediately, like the theme button. Mix one into a draft-and-save flow and the “unsaved changes” bar lights up for a change that already took effect, while the toast's Undo rolls back the draft without rolling back the axis — the UI contradicts itself.
• Rendering a control outside its provider. useContrast, useDensity, useFontSize and usePalette throw with a message naming the provider to add. ThemeToggle is the exception — it needs no shell context at all and works on a sign-in page.
• Importing a constant through a client module. The RSC boundary is cut per file: every export of a 'use client' module becomes a client-reference proxy when a Server Component reads it, and a string constant comes back undefined with no error and no warning. That is why the constants live in their own directive-free modules and why the shell barrel re-exports them from there rather than through the providers.

ThemeProvider props

A thin wrapper over next-themes with Comitor defaults — ThemeProviderProps is an alias of next-themes' own props type, so every option below can be overridden.

ThemeToggle props

ContrastProvider props

ContrastToggle props

DensityProvider props

DensityToggle props

FontSizeProvider props

FontSizeControl props

PaletteProvider props

PalettePicker props

ContrastScript · DensityScript · FontSizeScript · PaletteScript props

storageKey and nonce on all four; defaultValue on every one but ContrastScript. You will not normally render any of them: each provider already renders its own as its first child, with its own props passed on.

DisplayPrefsSeedScript props

No directive: it renders in a Server Component, straight in the root layout, without a client island.

Accessibility

• The font-size axis is itself an accessibility feature, so it must not fight the browser. The medium step writes no rule; small and large are percentages of whatever root size the visitor has configured. An absolute size at <html> would override that setting and breach WCAG 1.4.4.
• FontSizeControl is a radiogroup, not three buttons. role="radiogroup" with aria-checked on each option, so a screen reader announces “2 of 3” rather than three unrelated controls. They are real <button> elements reachable by Tab, not a roving-focus group — three options do not justify the extra dependency.
• The size buttons stay at text-sm. If they scaled with the setting, pressing “Large” would move the row of buttons out from under the pointer that just pressed it.
• Overriding a label fixes the visible text and the accessible name together. On ContrastToggle and DensityToggle, label renders a real <label htmlFor>, so the two cannot drift apart — no English accessible name over Vietnamese visible text, which is what WCAG 2.5.3 Label in Name forbids. The description line is visual only, not wired to aria-describedby: keep the label meaningful on its own.
• ThemeToggle in icon mode names itself with toggleTheme while its tooltip shows themeLight / themeDark. Translate all four keys together, and prefer the menu variant where users need to get back to “System” — the icon variant can only alternate between light and dark.
• The four axis controls are disabled until their provider has mounted, and ThemeToggle renders a same-size empty placeholder instead of a button for the same span. For the first paint the provider still reports the default, so an enabled control would show the wrong state and let a fast click overwrite a saved preference. The page itself does not flash, because the anti-flash script has already set the attribute — only the control waits.
• Compact density moves vertical rhythm only. Hit targets keep their horizontal size, and the switch, checkbox and icon dimensions do not shrink — the axis rewrites five padding tokens rather than the global --spacing, which would have dragged 16px icons down to about 13px.
• PalettePicker is a radiogroup of swatches with no text. Each swatch is a role="radio" button whose palette name is its aria-label and title; the selected one adds a check icon and a ring, so the choice is never carried by colour alone. Put a visible heading beside it — the group’s label is heard, not seen.
• Storage failure is not an error. In private mode, or with site data blocked, every read and write is wrapped: the axis falls back to its default and the choice simply lasts for the session.

Related