The guide

A world is a named identity that the five sites can all wear. This page says what one is made of, how its sheet is worked out, and how a prototype built somewhere else picks it up.

• What a world is
• The token sheet
• How values are derived
• Where colour comes from
• Using a world in a prototype
• The primitives
• Sketch and full
• Lineage and batches
• Cards and the cardui retrofit
• What the build checks
• The studio and compare

What a world is

Five things joined under one name. A token sheet for colour, type, shape, line, elevation, controls, icons and motion. A page surface and a card surface from Patterns. A frame family from Ornaments, with a choice per cardui kit. Card defaults for cardui. And a dossier: concept, personality, what it is not, references, voice, lexicon, do and don't, a signature and a verdict.

Colour comes from Colors and type from Typefaces. Nothing is copied by hand: the build syncs every sibling site's data and resolves the world against it.

This site defines worlds. It does not prototype them. Screens and flows are built wherever the prototype lives, from the three files a world exports.

The token sheet

Every world resolves to the same list of CSS variables, about ninety of them, with no prefix. The names the sibling sites already used keep their meaning (--pbg --pfg --pmuted --pacc --pline, the heading and body variables, --radius, --surface, --good --warn --crit), so a cardui card works on day one. The rest are new and follow the same bare style.

Most worlds set the shape by naming a preset and override single values. The five presets are square, soft, round, pill and cut. A pill world has 12, 20 and 28 pixel radii, 1.5 pixel lines and 44 pixel controls; a square world has no radius at all, and its pills become tabs.

How values are derived

A world file names only what makes it itself. Everything else is worked out, and the world page marks those values "derived" in the token table, with the rule beside them.

• Muted text is the text colour mixed 62 percent into the page in OKLCH; lines are 14 percent; the card surface is the page with 4 percent of the text (8 percent on a dark world); the sunken surface is 6 percent.
• Ink on the accent is white when white reaches 4.5:1 on it, else the text colour.
• Status colours start at the accent's lightness with a chroma of 0.12 at hue 150 (good), 80 (warn) and 25 (crit), then step darker until they read at 4.5:1 on the page.
• A world is light when its page is above 0.6 in OKLCH lightness. Light worlds take black shadow ink and the accent as the focus colour.
• A calm world runs its durations at 0.8 and loses the overshoot; a lively one runs at 1.2.
• The type scale comes from the pairing when Typefaces records one, else from a house scale of 3.5rem down to 0.75rem.

The same derivations run twice: in Python at build time (tools/resolve.py) and in the browser (js/tokens.js). The build checks they give the same sheet for every world, so a world made in the browser exports exactly what the build would.

Where colour comes from

From exactly one of three places, in this order: a Colors palette, whose roles map straight onto the sheet; a Typefaces palette sheet; or the world's own hexes, at least page, text and accent. Own hexes are a first class source, because exploration invents palettes faster than Colors can record them. An override applies on top of any source, and the token table says "adjusted from" and names the palette.

Using a world in a prototype

A world leaves as three files. Link the first two, put the world's id on the html element, and build with the primitives.

<html data-world="space-age">
<link rel="stylesheet" href="https://worldui.sky-ai.com/tokens/space-age.css">
<link rel="stylesheet" href="https://worldui.sky-ai.com/primitives.css">
<button class="wp-btn">Launch</button>

1. tokens/{id}.css is the resolved sheet, the reduced motion block, and the Google Fonts import the pairing needs.
2. primitives.css is the same file for every world.
3. briefs/{id}.md is the brief: concept, personality, references, voice, a copy map for the strings every prototype has, do and don't, the sheet in words, the sources and these instructions. It is written to be pasted whole into a build prompt.

The one rule for the prototype: never set a colour, radius, shadow or duration by hand. Anything new reads the sheet.

The primitives

One implementation of each control, driven only by the sheet: buttons, fields, checks, radios, switches, segmented controls and tabs, chips and badges, links, dividers, avatars, tooltips, toasts, dialogs, tables, a card, and four page templates (header, toolbar, content, footer). Every state is styled twice, by the real pseudo class and by a data-state attribute, so the primitives page can show rest, hover, focus, active, disabled, error and loading side by side. Badges always pair a glyph with a word; colour is never the only signal.

Sketch and full

A sketch needs a concept sentence, three personality words and a verdict. A full world needs the whole dossier except sound. The sheet is the cheap part; the dossier is earned by the worlds that survive. A sketch is labelled a sketch everywhere it appears, and its weaker contrast pairs are warnings rather than errors.

Lineage and batches

Worlds arrive in batches, each a theme or one exploration session. A world records the world it was forked from, and the build works out which top level groups changed. The batch page draws the family tree.

Cards and the cardui retrofit

The world page shows twelve cardui cards from the kits the world dresses best, rendered by cardui's own renderer, never a copy of it. A world can strip a kit's frame, replace it, or hide the kit. cardui is being retrofitted so its card styles read the shape, elevation, control, icon and motion tokens too. Until that lands everywhere, cards follow the world's colours, type and frames, and their buttons keep their own shapes.

What the build checks

• Every world has the required fields and valid values, and one colour source.
• No dashes in any written string. Hyphens inside words are fine.
• Text on the page reaches 7:1 and ink on the accent 4.5:1 for every world. For full worlds the accent reaches 3:1 on the page and each status colour 3:1 on both surfaces; for sketches these are warnings.
• Every palette, pairing, surface, frame, kit and source theme the world names exists in the synced data.
• The browser and the build agree on every sheet, and every full world's brief has all its sections.

The studio and compare

The studio is where new worlds are made, in the browser, with nothing saved on a server. Start blank, fork a world (every control fills from it and the new world records where it came from), or start from a harvest candidate, which picks a pairing and a palette from the themes the candidate names. The controls run in the order of the sheet: colour, type, shape, elevation, controls, icons and motion, surfaces, frame, cards, sources, and last the dossier, where the tier switch marks the fields that tier needs.

Colour has three sources as tabs: a Colors palette, one of the forty Typefaces sheets, or your own hexes. Next to the hexes the studio measures the contrast pairs the build cares about and says which pass. Any role can then be overridden on top.

The stage on the right is the primitives sheet and six cardui cards, a product, a hotel, a stat tile, a form, a person and a toast. After every change the world is resolved again by the same code the world pages use, and the cards are dressed again through cardui's own renderer. The Check panel above the stage runs the build's rules that need no build: ids, enums, the dash rule, tiers, contrast and whether every named palette, pairing, surface, frame and theme exists.

• Mutate shows the current world varied along one axis: every shape preset, every elevation preset, the forty Typefaces sheets, or the pairings of one Typefaces theme. Click a cell to adopt it.
• Save draft keeps the world in this browser; Drafts lists them to load or delete.
• Copy JSON gives the record ready to paste into a batch file, with the changed list worked out against the parent.
• Export gives the three files for the unsaved world. The token file and the brief are written by the same template the build uses, and the build checks the two agree on every world, so a draft tried in a prototype is exactly what it will be once committed.
• Share copies a link that carries the whole record, studio.html?world=; studio.html?from=space-age opens a fork.

Compare puts two worlds side by side in the same primitives and the same six cards, with one width for both. Above the columns it lists every token whose value differs, grouped as the sheet is grouped, with both values. Name one world, compare.html?a=gourmet, and it is compared with the world it was forked from, or the page says it has no parent. Every world page links to both: Compare, and Fork in studio.