Wolkit style (.wolcss)

What it is

.wolcss is the style language of Wolkit apps: selectors and properties like a web style sheet, but every colour, size and curve is a theme token, not a literal value.

Why

A literal colour breaks dark mode, high contrast and the accent colour. With tokens only, an app follows every theme with no code, and the compiler can catch a mistake before the app runs.

How

Write classes in src/styles/app.wolcss, run make styles, then load build/styles.wsb with Wolkit.use_styles. The properties, lints and errors are listed below; this reference is generated from the engine's own code.

Related

Wolkit reference · Your first Wolkit app

Reference

The style language of libWolkit: a small CSS-like subset whose values are theme tokens, not literals. Two authoring tiers meet in one binary table (WSB1): inline arguments checked by the shard's macros, and src/styles/*.wolcss sheets compiled by wolkit-stylec with the same parser the engine's dev loader uses.

.card        { background: card; padding: md; border-radius: m; box-shadow: sm; }
.card:hover  { background: control; }
.row:hover > .actions { opacity: 1; }
@dark        { .card { box-shadow: md; } }
button       { cursor: pointer; transition: background fast ease; }

Selectors and the order of resolution

• .class, a node kind (button), at most one state (.card:hover), and the single form .parent:state > .child for hover-reveal actions. Selector lists with commas are fine.
• States: :hover, :active, :focus, :focus-visible, :disabled, :selected, :checked, :expanded, :empty.
• Media wrap rules: @dark { ... }; several conditions combine with a space (@dark @contrast { ... }). Conditions: @dark, @light, @contrast, @reduce-motion, @reduce-transparency, @compact.
• Node kinds: box, text, image, spacer, divider, button, toggle, slider, text-input, scroll, vlist, canvas, surface, overlay.
• There is no specificity and there is no !important (RU-056). Resolution order is fixed: the rules of the node kind, then the classes in the order the node lists them (later wins), then state and media variants (a variant with more conditions comes later; equals keep the order written), then inline properties.
• A class holds at most 8 variants; a table holds at most 4096 classes and 4 MiB.
• Inherited properties (marked below) are copied from the parent when no rule sets them. Results are interned, so two nodes with the same computed style share one entry.
• The pragma /* wolkit: off-scale */ lifts the spacing and radius scale for a file (WK-005, WK-006). It is counted by a ratchet and reported as WK-020.

Tokens, not literals

Colours are the 13 theme tokens of shared::theme::TOKENS, in this order (ids are the position). alpha(token, 20%) makes a see-through one and transparent is clear. A hex literal is WK-001, rgb() and the like WK-023 (RU-062).

The scales mirror shared::theme::SCALE (a test holds them to it):

A pixel value off the spacing or radius scale is WK-005 or WK-006; a font below 11px is WK-003 (RU-059); a transition over 500 ms is WK-004 (RU-060).

Type roles (font-size: title; sizes mirror shared::theme::scaffold):

Shadows are fixed material (black at an alpha), not themable. box-shadow holds two layers at most; lg is two.

Springs (spring: snappy): stiffness, damping, mass.

Properties

Affects is what a change dirties: layout or paint (a paint change never dirties layout). Anim marks the properties a transition can run on. Ids are append-only (a property's id is part of WSB1).

Layout

Paint

Text

Motion

Shorthands

Layout

A flexbox-like subset. Every box is border-box; sizes are logical f32 pixels. A node's size comes from its style, the parent's stretch or flex result, or its content. Children are laid out by the flexbox algorithm: single and multi line, grow and shrink with min and max freezing, justify-content, align-items, align-self, align-content, gaps, auto margins, row-reverse and column-reverse, absolute children placed by insets in the parent's box, aspect-ratio, and overflow. Where it differs from CSS:

• min-width and min-height of auto are 0, not the content size. Use shrink: 0 or a minimum where text must not be squeezed.
• A container with overflow: scroll or auto never shrinks its children; it reports its content extent for scrolling instead. scroll and vlist nodes start with overflow: auto and flex-direction: column; a spacer starts with grow: 1.
• Percentages resolve against the parent's inner box when it is known and behave as auto otherwise; a percentage margin is a share of the parent's inner width.
• A content-sized width is the smaller of the content's natural width and the room offered; a content-sized height is never clamped.
• align-items: baseline behaves as start in 1.0.
• display: none removes the node from layout; its rectangle is empty.
• An overlay leaves the flow. With an anchor it sits on the chosen side (flipped when it does not fit, shifted to stay inside the window); without one it is centred.
• A vlist positions its realised children by row index (the node key) from the list's estimated row height and the measured heights of rows laid out so far.

Incremental layout: a change marks the node and its ancestors up to the nearest relayout boundary (a node whose width and height are both in pixels, or that is out of the flow). Measured sizes are cached per node.

Not in 1.0

Grid (planned for 1.1), floats, tables, pseudo-elements, @import, @font-face, @keyframes, calc(), filters and blend modes, position: fixed and sticky, variable-font axes, descendant and sibling selectors. Each is reported as WK-009 or WK-012, never ignored silently.

Lints

Diagnostics are sentences with file:line:col, the source line, a caret and a suggestion; the word "failed" never appears (RU-003). tests/lints.rs has one test per id.

The WSB1 table

Little endian: WSB1, version, flags, the number of kinds and classes, one variant list per kind, then each class (name and variant list), then a 32-bit FNV-1a checksum. A variant is a state (0 or one bit), a media mask, an optional parent selector, a 128-bit mask of the properties it sets, and the value of each set property in id order. The loader treats the bytes as untrusted: every count is bounded before use, every value is range checked, and it never panics. wolkit-stylec also writes src/gen/styles.cr, one constant per class.

The compiler

wolkit-stylec [--out build/styles.wsb] [--crystal src/gen/styles.cr] [--deny-warnings] SHEET.wolcss...
wolkit-stylec --doc

Sheets are read in sorted order, so the same files always give the same table. Class ids follow first appearance. Errors print every diagnostic and write nothing (exit 1); warnings print and pass unless --deny-warnings is given. The engine's dev loader (style::compile) and style::load run the same parser and the same checks.

Inline properties

Tier 1 arguments reach the engine as SET_PROP ops with the ids of scene::prop and are mapped by property onto the same declarations (style::inline). A role in font-size sets the size only; text_scale of the environment scales every declared size.