Foundations

Colour, type, space, shape, elevation, focus, icons and layout: the parts every screen is made of. Every value here comes from tokens/discotheque.json and tokens/folio.json, and from the CSS that scripts/build.mjs generates from them. When the two disagree, the JSON wins; run pnpm build.

There are two looks:

• Discothèque (the default) is print you can touch: warm paper, thick ink outlines, hard offset shadows, a serif for display.
• Folio (data-look="folio" on <html>) is calm and conventional: cool greys, 1px borders, soft shadows, one sans-serif.

Each look has a light and a dark theme. Discothèque calls them “Lights on” and “Lights off”; Folio calls them “Light” and “Dark”. See the README for the attributes.

One set of names

Component CSS reads Discothèque’s variable names whatever the look. Folio gives those names its own values, so var(--paper) is warm paper in Discothèque and Folio’s grey canvas in Folio. Write component CSS with the shared names below and it works in both looks.

Folio’s own token names are also available, prefixed: --folio-canvas, --folio-accent, --folio-presence-3 and so on (only under data-look="folio"). Use them only for something that exists in Folio alone.

Colour

Surfaces

Text and lines

Action, selection and status

Mustard is for small things: a selection, a count, a highlight, a button. A big panel that calls for you takes --panel-highlight with --on-panel-highlight and --shadow-panel-highlight instead. In Lights on it is the same mustard; in Lights off, where a wall of mustard glares, it is mustard-soft with a mustard offset shadow, and the selections and counts inside it stay full mustard.

.needs-you {
  background: var(--panel-highlight);
  color: var(--on-panel-highlight);
  box-shadow: var(--shadow-panel-highlight);
}

Roles that differ by look

A few variables name a role rather than a colour, because the two looks fill that role differently. Prefer them to the raw colour.

--chocolate is white in Folio: Folio has no dark band, so the top bar and sidebar are plain surfaces. For a toast or tooltip that must stay dark in both looks, use --inverse.

Code wells

A code well is a dark panel for code: a block of code, a terminal, a request and its answer. It stays dark in both themes, so code reads the same everywhere, and it has its own syntax colours.

Folio only

These exist as --folio-* variables only under data-look="folio":

• --folio-accent-hover: primary button hover and press.
• --folio-danger, --folio-on-danger: a danger fill and its text.
• --folio-on-success: text on a success fill.
• --folio-overlay: the dialog backdrop (rgba(16, 24, 40, 0.45) light, rgba(0, 0, 0, 0.6) dark).
• --folio-presence-1 to --folio-presence-6 and --folio-on-presence: one colour per person on a screen, with initials in --folio-on-presence (at least 4.5:1 on all six).
• --folio-type-article, --folio-type-event, --folio-type-media, --folio-type-person: type squares in link chips and search results.

Contrast pairs that are safe

Ratios are WCAG contrast, computed from the token values, light theme then dark, and rounded down. The pairs live in tokens/contrast.json; pnpm check fails when one drops below what it needs (4.5:1 for text, 3:1 for large text and for focus rings and the edges of controls), and pnpm build writes these tables from the same list.

Pairs to avoid:

Type

Families

The fonts are self-hosted: @moteurio/design/fonts/discotheque.css and @moteurio/design/fonts/folio.css. Courier Prime is not bundled; it falls back to Courier New.

Scale

The type scale is in the token JSON (type.groups), not in CSS variables yet. An app writes these sizes in its own CSS. The few type variables that do exist are --ui-size (16px Discothèque, 14px Folio), the --label-* set below, and in Folio a set of --fs-* sizes that let CSS written with Discothèque’s sizes come out one notch denser.

Discothèque

display-xl and display-l set Fraunces’ optical size to 144. Letter spacing tightens as the size grows: -0.03em, -0.02em, -0.01em.

Folio

Folio has no weight above 600 and no celebration or empty-state face: those variables point at IBM Plex Sans.

Labels

Labels and eyebrows read four variables, so one rule works in both looks:

Field labels have their own set, the same in both looks: --field-label-size 13px, --field-label-tracking 0, --field-label-case none.

Spacing

A 4px base. The names are steps, not pixels.

Folio’s JSON also defines space-12 (48px, empty-state padding), but it is not in the CSS yet; use calc(var(--space-6) * 2) or write 48px.

Radius

Use --radius-button and --radius-badge on buttons and badges rather than picking a radius: a button is a pill in Discothèque and a rounded rectangle in Folio.

Borders

Folio’s JSON also names border-selected (2px: a selected media card, the active tab’s underline) and focus-width (2px); in CSS the focus width is --focus-ring.

In Discothèque every object has a 2px ink outline and rows are split by dotted rules. In Folio, objects have a 1px hairline (--rule) and controls a 1px stronger edge (--outline-control), because a hairline is too faint to be the only edge of something you can press.

Elevation and shadows

The two looks lift things differently. Discothèque has no soft shadows: an object that lifts gets a hard offset in ink, like card stock on a desk. Folio separates objects with borders first, and keeps soft, low shadows for things that float.

Folio’s shadows, light theme (dark uses black at higher opacity):

shadow-m has no shared name; use --folio-shadow-m under Folio. Two more variables carry the press: --press (3px in Discothèque, the distance a primary button travels into its shadow; 0 in Folio) and --lift (-1px in Discothèque, how far a hovered object rises; 0 in Folio).

Levels, from the page up: the page (--paper), objects on it (--paper-raised with an outline), things that float above it (menus, popovers, toasts), then dialogs over a backdrop. Use the next shadow up only when the object really sits above the one below.

Focus

Every interactive element shows a focus ring when reached by keyboard:

:focus-visible {
  outline: var(--focus-ring) solid var(--focus);
  outline-offset: 2px;
  box-shadow: 0 0 0 2px var(--focus-edge);
}

Discothèque’s ring is two bands: the mustard ring, and an ink edge filling the 2px gap between it and the element. Mustard alone is too light on Lights-on paper (1.8:1), and no single colour reads on both the cream paper and the chocolate sidebar, so whichever band the ground hides, the other one shows: the ink edge on paper (12.2:1), the mustard on chocolate (4.8:1 or more) and in Lights off (8.6:1 on paper). The edge is the ink that reads on mustard in both themes, so the two bands stay apart too (6.7:1). Folio’s ring is one colour, at least 5:1 wherever it sits, and its edge is transparent.

The edge is a box-shadow, so an element with a shadow of its own lists both, edge first: box-shadow: 0 0 0 2px var(--focus-edge), var(--shadow-press);.

• Never remove the outline without drawing another one.
• Show focus on the element that has it, or on its visible box when the real element is hidden (a checkbox’s square, a switch’s track).
• Don’t show the ring on mouse click: use :focus-visible.

Icons

The package ships no icons. Apps built on it use Lucide (lucide-react in React), at its default 2px stroke, in currentColor so icons take the text colour.

When an icon needs a label:

• Next to text, the icon is decoration: aria-hidden="true", no label.
• Alone in a button, the button needs a name: aria-label="Remove", plus a tooltip with the same words for sighted users.
• Carrying meaning on its own (a status, a warning), give it a text alternative or put the words beside it. Colour and shape are never the only signal.
• Use the same icon for the same action everywhere, and never an icon that only makes sense once you know the app.

Layout and breakpoints

There are no breakpoint or grid tokens yet. What the tokens give:

• Gutters: --space-4 (16px) on phones, --space-6 (24px) on desktop.
• Content padding: --space-8 (32px) on wide screens.
• Region gaps: --space-10 (40px) between major regions.
• Reading width: rich text at most 72 characters per line (Folio’s body-l note).

Each app sets its own breakpoints in its CSS for now. Prefer container queries for components that appear in more than one width (a card in a sidebar and in a page), and media queries for the page shell. Check every layout at 320px wide: no horizontal page scroll, and targets of at least 24px.