Overview

Design tokens are the substrate every other theming feature compiles into. A token is a named CSS variable — --bg-primary, --text-secondary, --radius-md, --fontSize-text-sm — and blocks style themselves by referencing token names, never raw values.

The color pickers, typography scale, border presets, and component editors are all friendly front-ends that ultimately write token values. The Tokens & CSS tab is the direct line: define or override any token yourself, and write raw CSS overrides for anything the visual editors don't cover.

Note: The tab starts pre-filled. A newly created theme opens this tab with a skeleton already in place: the light and dark token blocks, followed by an empty, correctly-scoped block for every styleable component, each commented with the component's name. Fill in what you need and leave the rest.

Scoping Every Rule You Write

Your app renders inside an element carrying the class interface-theme. Prefix every rule with it.

An unscoped rule is not ignored — it's injected into the page like any other rule and will match. Scoping earns its keep for two reasons:

• Containment. The class is the boundary that keeps your theme inside your app. Drop it and the rule also reaches the builder and platform UI around your app, which are built from the same components.

• Specificity. Everything the theme itself emits for a component is already scoped — the Components editor compiles its output to .interface-theme .ua-button. A bare .ua-button is one class less specific, so it loses to any component style touching the same property. Matching the scope puts you on equal footing.

Light and Dark Mode Pattern

The active color mode is published as a data-color-scheme attribute. It can land either on the app's root element or on an element inside it, so a mode-specific rule needs both forms to be reliable:

Warning: Note the difference between the two dark selectors: the first has no space (attribute on the same element as the scope class); the second has a space (attribute on a descendant). Both are needed.

Special case: toast notifications

The toast notification (.ua-toast) renders in a floating layer where the scope class and the component class land on the same element. Its rules concatenate rather than nest — .interface-theme.ua-toast { … }, no space. If a toast rule written the descendant way doesn't apply, this is why.

How Everything Compiles Together

When the app loads, the theme is assembled into one stylesheet in a fixed cascade order. Later layers beat earlier ones:

1. Platform defaults — every token has a default value; an untouched theme still looks complete because of this layer.

2. Your theme's light tokens, then dark tokens (dark applies only in dark mode).

3. Component styles from the component styling editors.

4. Your custom CSS from the Tokens & CSS tab — last, so it wins every tie.

Note: A theme only stores what you changed. Untouched tokens keep their platform defaults.

Color Token Reference

Brand seed tokens and derived scales

Single-value color tokens

Trade-offs & Gotchas

• Overrides here beat every other theming surface. Custom CSS from this tab is applied after everything else the theme produces — tokens, border radii, and per-component styles. If a component style mysteriously doesn't apply, check this tab first for a competing override.

• The mobile app reads these tokens too. The theme's compiled output feeds the published mobile app. A token or CSS change here ships to native surfaces even if you only checked it on web, and a mistake can break the mobile app silently. The mobile app understands a narrower slice of CSS: plain hex colors, sizes in rem/em/px. Colors in rgb, hsl, or oklch, computed calc sizes, and gradients render fine on web but fail on mobile. Raw CSS rules style web only — mobile does not apply selectors.

• Token names are a contract. Overriding an existing token restyles everything that reads it. Prefer defining your own new tokens for one-off values and override built-in ones deliberately.

• Per-block Custom CSS can't reach pop-out content. CSS you write on an individual block is scoped to that block. Dropdown menus, date-picker calendars, tooltips, and other floating popovers render at the top of the page — outside the block — so a block-scoped rule never reaches them. Put such rules in this app-wide tab instead.

Frequently Asked Questions

Why does my custom CSS work on some components but not others?

This is almost always a specificity issue. An unscoped rule like .ua-button { … } is one class less specific than the theme's own scoped rules (.interface-theme .ua-button { … }). Prefix every rule with .interface-theme to match the theme's specificity — then your rule wins because it is applied later.

Can I override a token only in dark mode?

Yes. Use the dual-selector pattern: .interface-theme[data-color-scheme='dark'], .interface-theme [data-color-scheme='dark'] { --my-token: #value; }. The two selectors cover the attribute landing on the root element vs. on a descendant — both are needed for reliable results.

Will my custom CSS affect the mobile app?

Token definitions (CSS custom properties) are read by the mobile app. Raw CSS rules (selectors and declarations) style the web app only — mobile does not apply them. Keep token values to plain hex colors and px/rem/em sizes; avoid rgb/hsl/oklch, calc, and gradients in token values for mobile compatibility.

How do I style a tooltip or dropdown that appears outside my block?

Per-block Custom CSS can't reach pop-out content because it renders outside the block's DOM subtree. Put the rule in this app-wide Tokens & CSS tab instead — rules here apply across the whole app, including floating content. Keep the rule specific to avoid unintended side effects.

Related Pages

• Theme Builder — the tokens → theme → app picture

• Colors & Color Scheme — the friendly editor for color tokens

• Typography — the friendly editor for font tokens

• Borders & Radius — the presets behind the radius tokens

• Appearance & Styling Guide — per-component CSS, scoped and lower-priority than this tab