Styles

Styles let templates share named design tokens. Put them in a .qtml token module, usually ui/styles/theme.qtml, then import it normally. Token values are emitted as CSS custom properties and can be used through the imported namespace.

Default theme

Every stylesheet generated by render_qtml_styles! begins with QTML's default theme. It supplies light and dark colors, typography, box sizing, body defaults, heading sizes, links, lists, media, form controls, focus states, code blocks, and tables. Start with semantic components and omit properties already covered by these defaults; add QTML properties only for intentional layout or visual overrides.

The defaults expose CSS variables such as --qtml-default-background, --qtml-default-surface, --qtml-default-foreground, --qtml-default-border, and --qtml-default-mono-font for application-specific rules.

Define a theme

// ui/styles/theme.qtml
token background: #ffffff
token foreground: #0f172a
token primary: #2563eb

dark {
    token background: #0f172a
    token foreground: #f8fafc
}

The top-level dark block overrides tokens when a dark ancestor is active. Generate styles from the template entrypoint with render_qtml_styles!; the macro follows component and token imports and emits both component rules and CSS variables.

use qtml_macro::render_qtml_styles;

const QTML_STYLES: &str = render_qtml_styles!("ui/page.qtml");

Import and use it

import "styles/theme.qtml" as theme

Page {
    background: theme.background
    color: theme.foreground

    Button {
        text: "Continue"
        background: theme.primary
    }
}

Imports are file-local. Import the token module in every template that references it, and use theme.name wherever the property accepts a token reference.

Pass multiple entrypoints to generate one deduplicated application stylesheet:

const APP_CSS: &str = render_qtml_styles!("ui/home.qtml", "ui/settings.qtml");