Skip to content

Tokens ​

A token is a CSS custom property the form's stylesheet reads. Datum's own look is made of 139 of them: colour, type, spacing, corners, control size, focus ring and layout. A host restyles the form by giving some of them new values. Nothing else about the form's markup or stylesheet needs to change.

This page lists every token, what it styles and the value Datum gives it. Look and chrome explains frames, header and footer parts and the other ways to change how a form looks.

How a host changes them ​

Tokens are set through createDatumBinding, which datum-form.js exports. Token names are written without the leading dashes.

js
import { createDatumBinding } from "./datum-form.js";

const acme = createDatumBinding({
  tokens: { "color-accent": "#00539b", "radius-control": "2px", "font-family": "Georgia, serif" },
  dark: { "color-accent": "#8ab4f8" },
  responsiveTokens: [{ container: "(width < 30em)", tokens: { "spacing-field-gap": "10px" } }]
});

// binding is a property of the element, not an attribute.
document.querySelector("datum-form").binding = acme;
OptionTokens it sets
tokensValues over Datum's light set.
darkValues over Datum's dark set, drawn while the form's colorScheme is "dark". false draws the light set in either scheme.
responsiveTokensA list of { media, tokens } or { container, tokens }. media is a media query condition without @media. container is a condition on the form's own width, without @container, such as "(width < 24em)". When both are given, container wins.

A token you leave out keeps Datum's value. A token that falls back to another (color-input-border reads color-border) follows that one until you set it. A name the list below does not contain is kept as a private token, for your own css option to read. A value that contains {, } or ;, a closing tag, @import, or a url() that runs script or carries anything but an image is dropped.

Page CSS reaches only some of them ​

The form draws inside a shadow root. A custom property set on the datum-form element in the page's own CSS inherits into it, but Datum's look declares its own value for many tokens on the form's root inside the shadow root, and a declaration there beats an inherited value. So a page rule such as the one below changes nothing:

css
datum-form { --color-accent: red; }   /* no effect: the look sets color-accent itself */

The column "Look sets it" says which tokens this applies to. Of the 139, 49 are set by the light look and 55 by the dark look (6 of those only in the dark set). For the rest a page rule on datum-form does reach the form, in the light scheme:

css
datum-form { --radius-frame: 4px; --spacing-frame-padding: 12px; }  /* reaches the form */

Do not rely on that split. createDatumBinding({ tokens }) sets any token, wins in both schemes, and keeps the choice with the code that registers the binding. Another design system's binding does not read these tokens: they style Datum's own look, and the parts of a form that Datum draws inside a design-system binding take their values from that binding's fallbackTokens (see Writing a binding).

The tiers ​

TierWhat it isHow many
baseWhat a design system always publishes: palette, type scale, body spacing, control and button geometry. Set these first.43
derivedA token whose value is another token (focus-ring-color reads color-accent), plus the form's own surface and colour scheme. Setting one refines; leaving it out is fine.17
geometryA literal a design system rarely prescribes: a control's minimum height, a frame's shadow, the width of a notice's bar. Datum's value stands until you say otherwise.79

A token's group (palette, state, surface, spacing, type, focus, controls, layout) says what it is about. color-surface is the form's own page colour, transparent unless set, so a form sits on the host page's colour. color-scheme is light or dark, emitted as the CSS color-scheme so the browser's own date picker, select list and scrollbars follow the scheme.

The Default column is the value Datum's own light look uses. The Dark column is the dark set's value where it differs. A value written var(--color-border, ...) is a fallback chain: the token follows another until set.

Base tokens ​

TokenGroupDefaultDarkLook sets itWhat it styles
color-textpalette#16171a#e6edf3light and darkThe form's text.
color-mutedpalette#4e525b#9fb3c8light and darkField descriptions, option hints, the character count, the optional mark, the required note and the size line under an attached file.
color-accentpalette#2f4bd6#6ea8felight and darkThe default and primary buttons, link-style buttons, the download link on an attached file's name, the active step, and the focus ring's fallback.
color-borderpalette#9aa2ad#4a5d70light and darkInput borders (unless color-input-border is set), panel and tab outlines, the step bar, table cells, the status line and the file Remove button.
color-input-bgpalette#ffffff#1b2633light and darkThe controls themselves: text inputs, selects, textareas and the language switcher.
color-panelpalette#ffffff#172230light and darkA panel's surface and the active tab.
color-panel-headerpalette#eceef1#1f2b3alight and darkA panel's header band.
color-lightpalette#eceef1#3a4d62light and darkThe light fill: affixes, the --light button, the step numbers, the status line and a notice's ground.
color-darkpalette#16171a#2b3a4alight and darkThe dark fill: the --dark button and the help-mark bubble.
color-on-accentpalette#ffffff#0f1720light and darkText on the filled buttons: primary, start, secondary, success, danger and info, and the active and completed step numbers.
color-on-darkpalette#ffffff#e6edf3light and darkText on color-dark: the dark button and the help-mark bubble.
color-errorstate#b42318#ff7b7blight and darkInline errors, the over-limit count, the summary's text, links and focus ring, an error notice's edge, and what color-danger falls back to.
color-error-bgstate#fce9e7#2e161blight and darkThe error summary's fill and an error notice's, whose words are color-error.
color-error-borderstate#d9776d#8a3a40light and darkThe error summary's edge.
color-secondarystate#4e525b#9fb3c8light and darkThe --secondary button's border and, unless color-secondary-bg says otherwise, its fill.
color-successstate#1e6b3a#3fb950light and darkThe --success and --start buttons, a completed step, and a success notice's edge.
color-warningstate#8a4b00#e8a317light and darkThe --warning button, which draws color-dark text on it, and a warning notice's edge.
color-infostate#1c6e8c#58c4ddlight and darkThe --info button and an info notice's edge.
radius-panelsurface14pxlight and darkA panel's corners.
spacing-field-gapspacing16pxlight and darkThe gap between fields, between the rows of a layout, and inside panels, tabs and steps.
spacing-field-inner-gapspacing6pxlight and darkThe gap between a field's label, hint, control and error, and above the character count; zero for a design system that spaces them by margins.
spacing-option-gapspacing6pxnoThe gap between the options of a radio or checkbox group.
font-familytype"Geist", system-ui, -apple-system, "Segoe UI", sans-seriflight and darkThe form's body face, set on its root and inherited by every control.
font-sizetype0.875remlight and darkThe form's body size, inherited by every control and the affixes.
line-heighttype1.45light and darkThe form's body line height, inherited by every control.
font-weight-labeltype500light and darkLabels, and the legends of radio and checkbox groups.
font-size-labeltype0.8125remlight and darkLabels and legends.
font-size-hinttype0.8125remlight and darkField descriptions, option hints, the character count, the required note, a group's description and the step labels.
font-size-errortype0.8125remlight and darkThe inline error text.
font-weight-errortype600light and darkThe inline error text and the over-limit count.
font-size-titletype1.125remlight and darkThe form's own title.
font-size-headingtype1remlight and darkA chrome heading and a step's heading.
font-size-group-labeltype0.875remlight and darkA group's label (its legend).
font-size-panel-titletype14pxnoA panel's title.
focus-ring-widthfocus2pxnoThe focus ring's width.
focus-ring-offsetfocus2pxnoThe focus ring's offset from the control's edge.
radius-controlcontrols10pxlight and darkThe corner radius of the boxed controls, the affixes and the language switcher.
radius-buttoncontrols999pxlight and darkThe buttons' corner radius at every size.
control-border-widthcontrols1pxnoThe boxed controls' and affixes' border width.
control-paddingcontrols9px 12pxlight and darkThe boxed controls' and affixes' padding.
button-paddingcontrols8px 16pxlight and darkButtons at their default size; the small and large variants keep their own padding.
button-font-sizecontrols0.875remlight and darkButtons at their default size.
button-font-weightcontrols500light and darkButtons at their default size.

Derived tokens ​

TokenGroupDefaultDarkLook sets itWhat it styles
color-input-borderpalette#7b828c#6b8194light and darkInput borders alone, for a binding that treats them apart from panel outlines; falls back to color-border. Keep it 3:1 against color-input-bg.
color-choice-markpalette#16171a#6ea8felight and darkThe mark of a checked radio or checkbox — the dot, the tick — through the native accent-color; falls back to color-accent. A theme drawing its own marks reads it for them.
color-dangerstatevar(--color-error, #c92a2a)#ff7b7bdark onlyThe --danger button; falls back to color-error.
color-secondary-bgstatevar(--color-secondary, #5b6b7a)noThe --secondary button's fill; falls back to color-secondary. "transparent" draws the outline button most design systems have.
color-on-secondarystatevar(--color-on-accent, #fff)noText on the --secondary button; falls back to color-on-accent. An outline secondary sets it to color-secondary.
color-warning-bgstate#fdf1d6#2e2410light and darkA warning notice's fill; falls back to color-light, the ground of a success or info notice, so the amber edge alone sets it apart. color-text sits on it: keep it 4.5:1 against that.
color-disabled-bgstate#eceef1#243245light and darkThe fill of a disabled text box, number, date, select or textarea (outside read-only mode, which keeps the answers at full contrast); falls back to color-light. The text on it is color-muted: keep that 4.5:1 against this.
color-surfacesurfacetransparent#0f1720dark onlyThe form's own page: transparent unless set, so the form sits on the host's. A dark binding sets it and paints itself; the builder's canvas sheet takes the same colour.
color-schemesurfacenormaldarkdark onlylight or dark, emitted as the form's CSS color-scheme so the native parts a stylesheet cannot reach (date picker, select popup, scrollbars) follow the scheme.
color-frame-surfacesurfacevar(--color-surface, #fff)#172230dark onlyThe fill of the paper frame; falls back to color-surface, then white — paper needs a colour of its own on a transparent form.
color-frame-bordersurfacevar(--color-border, #a9bbcb)#4a5d70dark onlyThe border of the outlined and paper frames (chrome.frame); falls back to color-border.
font-family-headingtypeinheritnoThe heading face — the form title, a chrome heading, a group's label, a panel's title, a notice's title, the summary heading and a step heading; the body face unless set.
focus-ring-colorfocusvar(--color-accent, #2f6feb)noThe keyboard focus ring on controls, buttons, tabs, step headings and the summary's links; the accent unless set.
color-on-warningstate#ffffff#2b3a4alight and darkText on the --warning button; falls back to color-dark. A dark palette whose dark fill is light sets it to a dark the yellow can carry.
radius-button-smcontrolsvar(--radius-button, 6px)noThe small button's corners; falls back to radius-button.
radius-button-lgcontrolsvar(--radius-button, 10px)noThe large and start buttons' corners; falls back to radius-button.
width-choice-bordercontrolsvar(--control-border-width, 1px)noA drawn checkbox's or radio's border width; falls back to control-border-width.

Geometry tokens ​

TokenGroupDefaultDarkLook sets itWhat it styles
button-hover-filtercontrolsnonenoA filter over every button under the pointer — brightness(90%) for a design system that darkens all its buttons the same way; none by default.
button-active-filtercontrolsnonenoA filter over every button while pressed; none by default.
radius-framesurface14pxlight and darkThe corner radius of the outlined and paper frames.
shadow-framesurface0 1px 2px rgba(13, 36, 53, .06), 0 8px 24px rgba(13, 36, 53, .07)0 1px 2px rgba(0, 0, 0, .4), 0 8px 24px rgba(0, 0, 0, .45)dark onlyThe paper frame's drop shadow; "none" for a flat design system.
spacing-frame-paddingsurface24pxnoThe room between a frame's edge and the fields.
target-min-sizecontrols24pxnoThe smallest height of a choice row, a summary link and the Back link (WCAG 2.5.8).
target-touch-sizecontrols44pxnoThe minimum height of a journey's Continue, Submit and Back buttons, the size a thumb needs.
layout-max-widthlayoutnonenoCaps the width of the fields column — the line-length limit every government design system puts on a form.
layout-grid-column-minlayout220pxnoHow narrow a grid column may get before the grid wraps it onto the next row.
focus-ring-insetfocusnonenoAn inset box-shadow under the ring, for a design system that thickens the control's own edge on focus.
control-min-heightcontrols40pxlight and darkThe boxed controls' minimum height.
control-max-widthcontrolsmin(75ch, 100%)light and darkThe boxed controls' maximum width.
text-max-widthlayout65chlight and darkCaps the width of the text under a control — the hint, the error, the character count and a group's description — to a reading line (65ch in the studio themes).
textarea-min-heightcontrols72pxnoThe textarea's minimum height.
field-part-justifyspacingautonoHow a field's text parts — label, hint, error, count, a group's legend, the required note — sit in the field's grid: auto (the engine's: a grid item stretches to its column), or start, as wide as their words (as some design systems draw their labels). One token instead of a rule per part.
spacing-option-row-gapspacing8pxnoThe gap between a radio or checkbox and its label.
spacing-option-text-gapspacing2pxnoThe gap between an option's label and its hint.
spacing-group-gapspacing6pxnoThe gap between a labelled group's legend, description and body.
spacing-file-list-gapspacing4pxnoThe gap between the rows of attached files.
spacing-file-item-gapspacing8pxnoThe gap between a file row's name, size and controls.
spacing-chrome-gapspacing8pxnoThe gap between the rows of the form's header and footer.
spacing-chrome-group-gapspacing8px 16pxnoThe row and column gaps between the parts of a chrome group.
spacing-language-switcher-gapspacing6pxnoThe gap between the language switcher's label and its select.
spacing-tab-gapspacing2pxnoThe gap between tabs.
spacing-step-gapspacing6pxnoThe gap between the entries of a step indicator, and between the indicator and its progress line.
spacing-actions-gapspacing8pxnoThe gap between a step's Back and Continue.
radius-messagesurface10pxlight and darkThe corners of the error summary, the status line and a notice.
radius-tooltipsurface8pxlight and darkThe help bubble's corners.
radius-tabsurface8px 8px 0 0noA tab's corners.
radius-file-removecontrols6pxnoA file row's Remove button corners.
padding-messagespacing8px 10pxnoThe padding of the error summary and the status line.
padding-noticespacing10px 12pxnoA notice's padding.
padding-panel-headerspacing8px 12pxnoA panel header's padding.
padding-panel-bodyspacing12pxnoA panel body's padding.
padding-tabspacing7px 12pxnoA tab's padding.
padding-tooltipspacing6px 9pxnoThe help bubble's padding.
padding-file-removespacing2px 8pxnoA file row's Remove button padding.
padding-table-cellspacing4px 8pxnoA cell of a table inside author-written html.
padding-language-switcherspacing5px 8pxnoThe language switcher select's padding.
button-padding-smcontrols4px 10pxnoThe small button's padding.
button-padding-lgcontrols11px 22pxnoThe large and start buttons' padding.
button-font-size-smcontrols12pxnoThe small button's size.
button-font-size-lgcontrols16pxnoThe large and start buttons' size.
button-font-weight-startcontrols600noThe start button's weight — the big call to action is bold.
font-weight-headingtype600noEvery heading the form draws: its title, a chrome heading, a group's legend, a panel's title, a notice's title, the summary heading and a step heading.
font-size-notice-titletype15pxnoA notice's title.
font-size-chrome-texttype14pxnoA chrome text or description part.
line-height-chrome-texttype1.5noA chrome text or description part.
line-height-titletype1.25noThe form's own title.
line-height-headingtype1.3noA chrome heading.
font-size-file-itemtype13pxnoA row of attached files.
font-size-file-metatype12pxnoThe size line under an attached file, and the read-only file field's "none" line.
font-size-file-removetype12pxnoA file row's Remove button.
font-size-tabtype14pxnoA tab's caption.
font-weight-tab-activetype600noThe active tab's caption.
font-size-tooltiptype12pxnoThe help bubble's text.
font-size-language-switchertype13pxnoThe language switcher's label.
font-weight-language-switchertype600noThe language switcher's label.
width-message-bordersurface1pxnoThe edge of the error summary, the status line and a notice.
width-notice-barsurface4pxnoThe bar down a notice's start edge, in the outcome's colour.
width-button-bordercontrols1pxnoThe buttons' border width.
width-panel-bordersurface1pxnoA panel's outline and the rule under its header.
width-tab-bordersurface1pxnoA tab's outline and the rule under the tab list.
width-step-barsurface4pxnoThe bar over each entry of a step indicator, coloured by its status.
width-file-remove-bordercontrols1pxnoA file row's Remove button border width.
size-step-numberspacing1.5emnoThe circle around a step's number.
size-tooltip-markspacing15pxnoThe help mark beside a label.
shadow-tooltipsurface0 4px 12px rgba(13, 36, 53, .2)noThe help bubble's drop shadow.
opacity-button-disabledcontrols.5noHow far a disabled button fades.
icon-checkcontrolsan SVG data URInoThe tick of a drawn checkbox (controls.choiceMarks: "drawn"): an SVG data URI the engine masks in color-choice-mark. A theme's own glyph goes here (svgDataUri).
icon-radiocontrolsan SVG data URInoThe dot of a drawn radio, masked in color-choice-mark.
icon-chevroncontrolsan SVG data URInoThe chevron of a drawn select (controls.selectChevron: "drawn"), masked in the control's text colour.
icon-errorcontrolsan SVG data URInoThe icon before an inline error (controls.errorIcon: "drawn"), masked in color-error.
size-choicecontrols16pxnoA drawn checkbox's or radio's box.
radius-choicecontrols4pxnoA drawn checkbox's corners (a radio is round).
size-chevroncontrols12pxnoA drawn select chevron's box.
spacing-chevron-insetcontrols9pxnoThe room between a drawn chevron and the select's end edge; the select's end padding leaves twice this plus the chevron.
size-error-iconcontrols1emnoA drawn error icon's box.
spacing-error-icon-gapcontrols.35emnoThe gap between a drawn error icon and the message.

MIT licence. Your forms, your data, your keys.