shell.seo.section.theming — Documentation

Override semantic roles

Load your theme after base.css. Override named roles inside wl.tokens and keep data-wl-theme="gavia" and data-wl-brand="my-brand" on the same root element as in the starter. Check text, surface and focus contrast in every supported mode; the values below are an example, not a completed palette.

Show Vue code

/* Import after base.css, keeping the token layers. */
@layer wl.tokens {
  [data-wl-theme="gavia"][data-wl-brand="my-brand"] {
    --wl-accent: #245bd1;
    --wl-text-accent: #245bd1;
    --wl-focus-color: #245bd1;
  }
}

Select a theme before mounting

Set data-wl-theme on the document root or a containing element. The public theme composable can resolve light, dark and system preferences; use its early initialization script to avoid a flash of the wrong mode.

Show Vue code

import { useWlTheme } from "gavia-ui/composables";
const theme = useWlTheme({ themes: { light: "gavia", dark: "gavia-dark" } });

Keep application transitions under your control

The themes option also accepts a reactive getter. Map both light and dark to an explicit selection to keep all five named themes independent of OS changes. With target: () => null, useWlTheme only resolves the choice, so your application can apply it inside its own snapshot transition. resolveWlTheme is the pure SSR/early-resolution helper; wlThemeInitScript accepts a static pair.

Choose a stable decorative color

getWlColorFromString maps the same trimmed NFC name to the same palette entry during SSR and in the browser. Its default palette returns foundation token references; pass an ordered nonempty palette for your brand. Keep the person's name and check contrast separately: the mapping does not guarantee unique or accessible foreground colors.

Show Vue code

import { getWlColorFromString } from "gavia-ui/utils";
const outline = getWlColorFromString("Anna Mikhailova");
const brandOutline = getWlColorFromString("Anna Mikhailova", ["coral", "indigo"] as const);

Customize internal DOM

Use WlConfig.pt for app defaults and a local pt prop for one instance. Class and style values merge in default → app → instance order. The 1.0 source accepts canonical section names; the migration guide lists removed aliases. Icon buttons use their own iconButton configuration.

Source and guide