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://uistack.sky-ai.com/worlds/tokens/space-age.css">
<link rel="stylesheet" href="https://uistack.sky-ai.com/worlds/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 and type are the two choices that make a world, so each sits in the studio as one summary row with a Change button. The colour row shows the five swatches, where they come from and the two contrast readouts that matter most; the type row is a line set in the heading face over the body face. The override list for single roles and the mono field stay under the summaries.

Change opens a picker that fills the screen in three columns: filters on the left, a grid of live candidates in the middle, and the current choice on the right. Nothing is written to the world until you press Use this; Cancel or Esc leaves it as it was. Hover a candidate and the stage on the right shows it after a moment; click it and its tuning opens underneath. The stage is a header, two buttons, a field, a row of chips and one cardui card in the world's dress, so a palette or a pairing is judged on interface and never on stripes or a sample sentence alone.

The colour picker has three sources as tabs: the 451 Colors palettes, the forty Typefaces sheets, and Own, where you start from the world's current colours or paste a list of hexes and let the picker propose roles by lightness. Filter by light or dark, the temperature and chroma of the accent, how well the contrast holds, which roles the record carries, collection, sector and mood. Each cell is a small screen: a heading in the world's face, two words of body and a filled button, in that palette. Type a hex in the accent box to sort by the nearest accent, or press Similar on any cell to sort by its background and accent together. Tuning gives each role a hex field, a colour well and three sliders for lightness, chroma and hue; a role map where you click a role, then a swatch, to move a hex; the derived roles with a lock each, where locking keeps the value as an override; and four nudges that move the whole set, plus Swap for a dark version.

The record stays honest about where the colour came from. A tuned Colors palette stays a palette with an override, a tuned sheet stays a sheet with an override, and anything moved off its record by a nudge, a swap or the role map becomes own hexes. The readout above the stage says which of the three it is. A palette that lacks a text or accent role gets one proposed from its own hexes, written as an override so the gap stays visible.

The type picker has two tabs: the 978 Typefaces pairings, and Own, any of the 363 fonts for the heading and any for the body. Filter by heading and body category, the shape of the pair, case, weight, whether it ships a scale, Typefaces theme, vibe and sector. Each cell sets the pairing's name, two lines of body and a button label in the world's colours; its fonts load only as it scrolls into view, one stylesheet per family, so the grid never asks for 363 fonts at once. Tuning covers the heading family, weight (only the weights the font ships), style, case, tracking and line height; the body family, weight and line height; the mono; a scale preset, compact, house, editorial or display, with every step shown; and the measure. Swap exchanges heading and body. A pairing tuned this way stays type.pairing with a type.override; a changed family or a swap makes an own pair, type.own, and the brief says there is no Typefaces record for it yet.

Both pickers open straight from a link: studio.html?from=space-age&pick=colour or pick=type.

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, the twelve palettes nearest the current colours, the twelve pairings nearest the current type, 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.