Tokens

Change a few CSS custom properties to give every Looma component the same visual language. Start with the theme; narrow an override only when you need to.

Prefer a visual starting point? Customize your theme and export its CSS. For geometry, material and generation settings, use the theme reference.

Start with the global values

Import the tokens and a palette, then add your overrides:

@import "@threadlabs/looma/tokens.css";
@import "@threadlabs/looma/theme-light.css";
@import "@threadlabs/looma/theme-dark.css";

:root {
  --ui-accent: #3859b8;
  --ui-radius-sm: 0.125rem;
  --ui-radius-md: 0.375rem;
  --ui-radius-round: 999px;
}

[data-theme="dark"] {
  --ui-accent: #a9bdff;
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) { --ui-accent: #a9bdff; }
}

The large radius derives from the medium radius. Round shapes keep their own radius. Keep overrides unlayered, as above, or place them in a layer after Looma's layers.

Check each mode. A custom palette needs readable text, controls and focus indicators in light, dark and high contrast modes.

Reading surfaces and application chrome

Use --ui-surface-content for a reading area and --ui-surface-chrome for its header, footer or surrounding navigation. Both derive from --ui-surface, with the reading area lighter than the chrome in light and dark themes, including themes whose canvas and raised surfaces share a color.

The roles resolve at each theme boundary. Override either public token when a surface needs a different treatment.

Files

Theming colour

Set the shared seeds. Hover states, tints, borders, muted text and disabled colours derive from them.

:root {
  /* Intent: what an action means. */
  --ui-accent: #5b55d6;
  --ui-danger: #b14d3f;
  --ui-success: #147937;
  --ui-warning: #b27522;
  --ui-info: #2e69b5;

  /* Readable foregrounds for filled actions. */
  --ui-on-accent: #ffffff;
  --ui-on-danger: #ffffff;

  /* The page, the two surfaces either side of it, and the ink. */
  --ui-surface: #ffffff;
  --ui-surface-raised: #ffffff;
  --ui-surface-sunken: #f0f0ec;
  --ui-text: #1a1a1a;
}

Changing --ui-accent updates accent buttons, selected controls, focus rings and their interaction states together. Leave derived values unset when you want them to follow the seed.

Shared colour roles

Actions settle when pressed; disabled controls use a flat neutral surface with no highlight or shadow. Tone changes the colour while the border and elevation keep their visual roles. See the visual role guide for the full rationale.

Supporting accents and statuses

• Supporting accents: set --ui-accent-secondary or --ui-accent-tertiary, then use tone="accent-secondary" or tone="accent-tertiary" on Button, IconButton, Badge, Card, Meter or Text. Without a supporting seed, they follow the primary accent.
• Status relationships: the customizer can retain semantic hues, reduce colour, or use brand families. Labels and icons still carry the meaning. Tips and informational callouts share the Info palette and use different icons.
• Accent assignments: choose the family used for links, focus rings and selected rows independently in the customizer.

Text's tone="secondary" means supporting prose. It is separate from the accent-secondary brand family.

Group values

Set a group value on a form, dialog or other ancestor to change the participating controls inside it. Group values inherit and are intentionally unset in tokens.css: each component falls back to the global theme.

.compact-form {
  --ui-field-radius: 0.25rem;
  --ui-field-danger: #a32642;
}

.floating-workspace {
  --ui-overlay-radius: 0.75rem;
  --ui-overlay-surface: var(--ui-surface-raised);
  --ui-overlay-border: var(--ui-border-strong);
}

Use --ui-danger when validation, destructive actions, badges and callouts should all change. Use --ui-field-danger for validation within a section. Keep its foreground readable.

Component tokens

Each component's API tab lists its public hooks: --ui-<component>[-<variant>][-<state>]-<property>.

A hook wins over that component's group or global fallback. For example, --ui-input-invalid-border wins over --ui-field-danger; --ui-menu-surface wins over --ui-overlay-surface.

Choose the scope

Public hooks inherit through the normal CSS cascade. A nearer declaration wins:

:root { --ui-input-radius: 0.5rem; }       /* Every Input */
.settings { --ui-input-radius: 0.25rem; }  /* Inputs in one section */
.square-input { --ui-input-radius: 0; }   /* One instance */

Use props for predefined options. A hook can override a prop where the component documents that precedence: --ui-stack-gap, for example, overrides Stack's gap prop even when inherited. Set the hook to initial to restore the component's fallback and prop-driven defaults.

Global seeds need a theme boundary. Set them on :root or [data-theme] so derived values recompute. An arbitrary ancestor class does not recompute a palette. --ui-font-size belongs on :root; nested modes share that rem base.

Set the public hook

Components own their declared layout, including flow, alignment and spacing. Set the public hook for the dimension you need:

.quantity { --ui-input-inline-size: 8ch; }
.status-filter { --ui-select-inline-size: 12rem; }
.rail-item { --ui-nav-item-inline-size: auto; }
.address-field { --ui-form-field-min-inline-size: 16rem; }

Use your own classes. Runtime markers such as data-component, private --_* variables and nested inputs or labels are implementation details.

Change a component's default appearance

Point hooks at semantic values so they adapt to the surrounding theme:

:root {
  --ui-button-surface: var(--ui-accent-subtle);
  --ui-button-border: var(--ui-accent);
  --ui-button-text: var(--ui-accent-active);
}

These hooks override Button's tone-derived colours, including explicit tone props. For a local change, put them on an ancestor or a class on that instance.

Themes

Switch with data-theme="light" or data-theme="dark". Leave the root attribute unset to follow the system preference.

[data-theme="dark"] {
  color-scheme: dark;
  --ui-surface: #1a1a1a;
  --ui-surface-raised: #2a2a2a;
  --ui-surface-sunken: #2e2e2e;
  --ui-text: #f0f0ec;
  --ui-on-accent: #1a1a1a;
  --ui-on-danger: #1a1a1a;
  --ui-accent: #a99bf5;
  --ui-danger: #ffa191;
  --ui-success: #84d393;
  --ui-warning: #f0af63;
  --ui-info: #92c0ff;
}

--ui-surface-raised and --ui-surface-sunken are seeded rather than mixed because which direction reads as "lifted" flips between a light and a dark scheme, and only the theme knows which one it is.

In a dark theme the intent tones are light, so their foregrounds (--ui-on-accent, --ui-on-danger, and --ui-on-warning) are dark. That is what lets one tone per intent serve both text and solid surfaces.

Keep exploring

• Customize a theme visually and export CSS or a recipe.
• Theme reference covers typography, spacing, material, motion and generation inputs.
• Browse components for each component's props and public hooks.