Styles & Tokens

LAW 1: definitions own ZERO style values. Token names only. The SDK renderer owns no styles either: it only resolves token names against the theme served live from the platform (unoverse://theme/<name>, an MCP resource, never baked into a bundle). A color change is a refresh, not a release.

The law

// ❌ NEVER: raw values in a definition
{ "style": { "padding": "12px", "color": "#4F46E5", "fontSize": "1.25rem" } }

// ✅ ALWAYS: token names
{ "style": { "padding": "4", "color": "text.primary", "font": "headline.sm" } }

No px / rem / em / #hex anywhere in any component, atom, or template definition. Studio’s publish lint scans for exactly this and blocks (08).
Sizes use the space scale ("width": "8" = 2rem, Tailwind-style: step N = N × 0.25rem), and only real steps: 0 1 1.5 2 3 4 5 6 7 8 10 12 16 20 24 28 40 50 75 90 100 120 140 160 180 200 (+ full/auto). An invented step ("26", "3.5") is NOT rounded: it falls through as broken CSS and the element silently reverts to auto sizing. Studio’s publish lint rejects off-scale values.
❌ No invented component-named tokens (cardMin, wizardWidth): use the generic scale steps. If the scale genuinely lacks a step, extend the scale in styles/, don’t smuggle a value into a definition.

Style KEYS are closed too: the cross-platform contract

It’s not just values: the set of style keys (padding, direction, radius, hover, …) is a closed vocabulary, exactly the neutral intents the SDK style interpreter maps, and the contract every renderer (web today; iOS, Android, React Native, Flutter as they land) implements. An unknown key is ignored by every renderer, so it is always a typo (colour) or a web-ism that would never port (backdropFilter, gridTemplateColumns). Both the schema (editor squiggle) and Studio’s publish lint (error) enforce the key set, including inside hover/active and when[].apply. If a design genuinely needs an intent the vocabulary lacks, that’s a platform conversation (a new key every renderer must implement): never a definition-side workaround. Why so strict: brand and dark-mode swaps must touch styles/ only. One raw hex in one definition breaks that guarantee for the whole org.

The token layers

rx/<project>/styles/
├── base/        # raw scales: the only place raw values EXIST
│   ├── color.json        # palettes
│   ├── spacing.json      # the space scale (the closed step set: see LAW above)
│   ├── typography.json   # font scales
│   └── radius.json / shadow.json / border.json / motion.json
├── semantic/    # named meanings, built FROM base
│   ├── text-styles.json  # headline.lg, body.sm… (referenced via "font")
│   ├── fonts.json / spacing.json / icons.json
│   ├── app-sizes.json    # STANDARD APP SIZES: chat · rail · panel (see below)
│   └── prose.json / skeleton.json / keyframes.json / root.json
└── themes/      # brand / dark-mode swaps
    ├── light.json
    └── dark.json

Layer	Answers	Definitions may reference?
base	”what values exist”	❌ never directly
semantic	”what things mean” (`text.primary`, `surface.base`, space steps)	✅ this is your vocabulary
themes	”what this brand/mode maps them to”	❌ selected at runtime, not referenced

Definitions speak semantic. Themes remap semantic → base per brand or mode; a theme-contract guard keeps token names consistent so every theme satisfies every definition.

Standard app sizes (`semantic/app-sizes.json`)

The named width blocks a template’s appWidth can reference (05: Sizing). The starter set:

Name	Starter value	Meant for
`chat`	`min(100vw, 680px)`	the core conversational surface: a panel that is always open
`chat-slim`	`min(100vw, 480px)`	the narrow chat used when a voice panel/focus surface is open beside it
`rail`	`min(100vw, 360px)`	a narrow stacked-cards slide-out
`panel`	`min(100vw, 600px)`	a full detail/form slide-out

Every size carries a viewport ceiling (min(100vw, …)): the full designed width on desktop, never wider than the screen on mobile. (Panels side-by-side can still exceed a phone’s width together: the dedicated mobile layout pass will decide stacking/overlay behavior; the ceiling keeps each panel individually safe until then.) Names are optional: raw CSS in appWidth is always valid, but prefer them: every template in the org stays on the same scale, and retuning a size is one edit here. Add org-specific names freely (the linter validates that any name a template uses is declared). Unlike every other token home these values are raw host-facing CSS on purpose: they size the app’s outer panel, which the embedding page applies, they are never inner styles.

Org scoping

Components live in TWO tiers. The design system (the installed marketplace package: generic, universal: cards, charts, media) is shared by every org and references token names only. An org component (rx/<project>/components/: the client’s own microapp: their finder, their page) is org-private: it belongs to that client and is served under their org. Names are unique across all tiers (lint-enforced), so a bare reference is unambiguous.
Atoms are universal and authoring-time only: rx/atoms/, one copy; the server expands every Ref before serving (atoms are never served or enumerable).
Templates and styles are org-scoped: rx/<project>/. Each org gets its own complete token set and templates. There are no overlays: if two orgs need different looks from the same universal component, that difference is 100% in their styles/. A component only becomes an org component when it IS the client’s product, not to restyle a shared one.

Starting a new org: copy the neutral baseline and re-token it

# Studio: New Project: the scaffold includes a complete copy of the default token set

(Every project starts from the same default set, so rebranding is editing values, never inventing structure.)

Styling checklist

Zero raw values in any definition (linter enforces)
Only semantic token names referenced (text.primary, not a palette entry)
No component-named tokens invented
New brand/mode = a new themes/ file, zero definition edits
Theme keeps the full token contract (guard test)

Next: 06b, Lifecycle Hooks, a component that fetches its own data.

Getting Started

Core Concepts

Workflow

The law

Style KEYS are closed too: the cross-platform contract

The token layers

Standard app sizes (`semantic/app-sizes.json`)

Org scoping

Styling checklist

​The law

​Style KEYS are closed too: the cross-platform contract

​The token layers

​Standard app sizes (semantic/app-sizes.json)

​Org scoping

​Styling checklist

The law

Style KEYS are closed too: the cross-platform contract

The token layers

Standard app sizes (`semantic/app-sizes.json`)

Org scoping

Styling checklist