UI & Components

Theme Tokens, Modes, and Direction

Theme Tokens, Modes, and Direction: anatomy, keyboard behavior, state, and theming in Askr.

Example

import { Button, ThemeScope, ThemeToggle } from '@askrjs/themes/components';

<ThemeScope defaultTheme="system" storageKey="app-theme">
  <Button>Save project</Button>
  <ThemeToggle aria-label="Change color theme" />
</ThemeScope>

Tokens are the single source of truth for color, spacing, radius, and every other visual value in the default theme, so changing an app's look is mostly a matter of overriding CSS custom properties rather than component code. Modes layer on top of tokens to switch between light, dark, system, and the shipped cat-themed presets, and a small Direction component handles setting the dir attribute on a scoped subtree.

Install and import

Pull in the default theme with @import "@askrjs/themes/default"; in your app stylesheet, and add @import "@askrjs/themes/presets"; if you want the additional cat theme family. For the JavaScript side, import { ThemeScope, ThemeToggle, ThemePicker, theme } from '@askrjs/themes/theme', and import { Direction } from '@askrjs/themes/components'.

Live examples

Wrap your app in <ThemeScope><ThemeToggle>{({ nextTheme }) => nextTheme}</ThemeToggle></ThemeScope> to get a working light/dark/system toggle with zero extra state management. After importing the presets layer, set data-theme="tabby" (or ginger, tuxedo, calico, torty) on an ancestor element to switch to one of the cat theme presets.

Anatomy

ThemeScope establishes a reactive scope that tracks the current theme and persists it under a storageKey; the theme() function reads and writes that same scope from anywhere inside it. Token overrides are plain CSS — :root { --ak-color-primary: purple; --ak-radius-md: 12px; } — and apply globally or per-subtree depending on where you write the selector. Direction is a separate, much simpler piece: it just wraps its children, sets the dir attribute, and emits a data-slot="direction" hook.

State model

theme() returns a ThemeScopeValue with theme() to read the current value, setTheme() to change it, the available themes list, and the storageKey it persists under. That's the entire state surface — there's no separate dark-mode flag to manage independently, since dark is just one more value in the same ThemeName union alongside light, system, and the cat preset names.

Keyboard and accessibility

ThemeToggle is built on the real Button component (it accepts ButtonNativeProps minus children and onPress), so it's a genuine, keyboard-operable button by default rather than a custom clickable div. It intentionally ships with no built-in icons — you supply lightIcon, darkIcon, and systemIcon yourself, and the rendered content is wrapped in data-slot="theme-toggle-content" so mixed icon-and-text compositions stay stylable.

Styling and tokens

The token contract spans color, typography, spacing, radius, borders, shadows, focus, motion, icons, layout, and z-index, all under the --ak-* prefix — for example --ak-color-primary, --ak-space-*, --ak-radius-*, and --ak-focus-*. Icon sizing specifically resolves through --ak-icon-size-sm|md|lg|xl and --ak-icon-stroke-width-sm|md|lg|xl, which lets you retune icon scale globally without touching individual components.

API

ThemeName is "light" | "dark" | "system" | CatThemeName | (string & {}), where CAT_THEME_NAMES is the readonly tuple ["tabby", "ginger", "tuxedo", "calico", "torty"]. ThemeScopeProps takes children, defaultTheme, themes, and storageKey; ThemeToggleProps adds lightIcon, darkIcon, systemIcon, and a themes list on top of the Button props it extends; ThemePickerProps wraps a native <select> minus value, defaultValue, and onChange. DEFAULT_THEME_OPTIONS and CAT_THEME_OPTIONS are the shipped option lists for each.

Edge cases

Direction is a thin wrapper that sets dir and a data-slot hook — it is not a full bidi engine, so getting mirrored layouts right in RTL still depends on how logical properties are used throughout your own CSS. Also watch storageKey collisions: if two apps sharing a domain both use the default key, their theme preferences will clobber each other in storage, so set an explicit storageKey per app.

See Customization for the broader selector and override contract these tokens participate in, and Structures for how layout tokens specifically feed into the Block system.