Style tokens

Every look in Zvessa comes from a style: a small record of settings called tokens. Screens and blocks never pick a colour, font or size of their own; they ask the style. So changing one token changes every screen at once, and anyone (or their AI) can make a new look without code.

There are three built-in styles, made exactly the way anyone's own style is made:

This page lists every token: what it controls and its value in each built-in style. Values are generated from convex/lib/styles.ts, so they match the app.

The five tokens that change the most #

If you only change a few things, change these. Ask the AI ("make the accent green") or set them in /look/changes:

{ "look": { "style": "tech", "changes": { "colors": { "accent": "#22c55e" } } } }

How tokens fit together #

• Groups. Tokens sit in eight groups: colors, type, shape, space, surface, backdrop, motion and parts. A style only lists what it changes; everything else comes from Classic.
• Layers. Lowest first: Classic's base → the style (and what it extends) → the space's look.changes → a page's own look → a person's own look on their device. Each layer has the same shape, so any of them can change any token.
• Schemes. schemes.dark and schemes.light (or any name, like night) hold the colours that differ between them. colors holds the ones that don't.
• Colour values can be #rrggbb, #rrggbbaa, white, black, transparent, another colour's name (accent), mix(a, b, 30%) (30% of a, the rest b), alpha(a, 20%) or contrast(a). Formulas nest. Any new colour name you add (say brand2) can be used by blocks and mini-apps.

1. Colours #

colors and schemes.<name>. The five columns are the built-in styles in their schemes; "·" means the style doesn't set it (screens fall back as described).

Ground and panels #

Text #

Lines #

Accent #

Status #

Chat #

Media #

2. Text #

type. Fonts are names, never files: system, rounded, serif, mono, and two bundled with the app, grotesk (Space Grotesk) and jetbrains (JetBrains Mono). They load only when a style uses them (about 145 KB together).

Text roles (type.roles, from the "Layout and text blocks" work): every piece of text is one of display, title, headline, subtitle, body, callout, caption, label, overline, number, quote, code. Each role can set size, weight, font (body, display, mono or a font name), case, tracking, leading and tone (a colour). A block names a role, never a size. Tech's label and overline are chat-app's small caps line: 10.5 px, mono, uppercase, wide tracking, in text3; its number role is mono.

3. Shape #

shape.

4. Space #

space.

5. Surfaces, edges and glow #

surface. How boxes are drawn.

6. Backdrop #

backdrop. The ground behind pages and chats. It never moves while you read, stops when the app is in the background, and turns off when the device asks for less motion.

7. Motion #

motion.

8. Parts #

parts.<part>. One piece of the screen restyled on its own, on top of surface. Each part can set treatment, depth, radius, bg, text and line (colours or formulas).

What the built-in styles set:

Futuristic

Tech (dark)

Classic sets no parts.

Examples #

Tech with a green accent. Everything else stays Tech:

{ "look": { "style": "tech", "changes": { "colors": { "accent": "#22c55e" } } } }

A style of your own, made from Tech. List only what changes:

{
  "id": "midnight",
  "name": "Midnight",
  "extends": "tech",
  "schemes": { "dark": { "bg": "#05060a", "accent": "#f59e0b" } },
  "shape": { "radius": 12 },
  "backdrop": { "lights": false }
}

Classic, rounder and roomier, in a serif:

{ "look": { "style": "classic", "changes": { "shape": { "radius": 22 }, "space": { "density": "roomy" }, "type": { "display": "serif" } } } }

A page with its own look (a games page that glows), in /pages/N/look:

{ "schemes": { "dark": { "bg": "#070814" } }, "backdrop": { "kind": "grid", "lines": ["#2dd4bf", "#a78bfa"], "glow": ["alpha(accent, 40%)"], "floor": true } }

For developers #

• Read the resolved style through src/lib/workspace.tsx: useWorkspace().theme, surface(theme, part), bodyText, headingText, monoText, captionText, glowShadow, litEdges, fontFamily(font, weight).
• Chat pieces read src/kits/talk/look.ts (rows, counts, pills, search) and src/kits/talk/chatLook.tsx (bubbles, message box, send button), so every chat in the app matches.
• Marks and EdgeLine in src/components/ui.tsx draw a card's lit corner and a header's lit line.
• Never write a hex value, font or fixed size in a screen; add a token instead, with a value for each built-in style.