# Styles and formats

The look and the deliverable as data packages, the kit every style styles, and how a project finds and pins them.

## A style is the look

A style is a folder: tokens (palette, faces, type scale, leading, margins), motion (exits, easing, transitions, pacing), a sound map, an optional grid and video type scale, how it adapts to each format it supports, `style.css` styling [the kit](#the-kit), and `taste.md`, the rules reviewers hold scenes to. Its stylesheet and proof scene run only inside the render page, which reaches nothing outside the package, so installing a style runs nothing.

Scenes link it: `<link rel="stylesheet" href="rapid:style">` becomes the style's tokens as `--rapid-*` custom properties adapted to the format, then its `style.css`. One scene renders in any style; one style renders to every format it lists.

```text
<name>/
  manifest.json    name, version, schema version, formats, fonts, every file's sha256
  style.json       the look, as tokens
  style.css        the kit's classes, styled
  taste.md         the judgment rules
  vectors/         the style's marks, as SVG (optional)
  fonts/           the style's faces, each folder with its licence (optional)
  refs/            a few reference stills
  proof/           scene.html, its example video, poster, and golden frames
```

A face either ships in `fonts/` (`.woff2`, `.woff`, `.ttf`, `.otf` under a free licence, declared with `@font-face`) or comes from the machine; one the machine lacks, with no allowed substitute present, fails the fonts check by name. See [fonts in a style](/docs/making-a-style#fonts-in-a-style).

Built in, under `styles/`, found by name with nothing to install:

| Style | Look |
|---|---|
| `bubble` | a food brand's world: glossy food cut out and stuck down, bursting out of shapes in front of a giant blobby wordmark, deep fields joined by rolling waves, die-cut stickers, badges, doodles, bouncy motion; its faces and pictures ship with it |
| `conspiracy` | an investigation filmed at night: one light in a dark room, a thin plane of focus racking across typed reports, clippings, instant photos, and red string, type that is evidence, rendered plates of real objects, film grain; its faces and pictures ship with it |
| `launch` | a hardware launch film on white: the style's own rendered laptop and phone enter, turn, open, and leave, against one monument word or a quiet line in the system face |
| `poster` | loud and editorial: condensed serif masses on flat saturated fields, an italic voice, cream cards, glass replies, colour as the score; its faces ship with it |
| `swiss` | International Typographic design: one grotesque on a modular grid, one thing enormous beside a small exact column, type as image, a visible system of rules and numbers, paper, black, and one red |
| `terminal` | the character grid as a design system: one mono cell for everything, huge words built from block cells, reverse-video selection as accent, transition, and call to action; its faces ship with it |

Each built-in style but `poster` also ships `components/`: working scenes for the pieces its look needs (a column wipe, red string with pins, a wave flood, a lid opening, huge words built from cells), each with a `SETTINGS` block to copy into a scene and change. They are starting points, not a cage.

Fields: [package files](/docs/style-json#style). Writing one: [making a style](/docs/making-a-style).

## The kit

The classes every `style.css` styles, listed in `contracts/src/kit.ts` as `KIT_CLASSES`:

| Class | For |
|---|---|
| `field`, `field-dark` | the scene's ground (on `<body>`) and a contrasting one |
| `display`, `title`, `body`, `small` | type, biggest to smallest |
| `voice` | an aside in the speaker's voice |
| `card`, `card-tile`, `card-name`, `card-sub` | a file or link as a card: the card, its tile, its name, its subtitle |
| `accent` | the one thing that matters on screen |

| The scene owns | The style owns |
|---|---|
| position, size, order | colour, face, weight, size, leading, tracking, case |
| when things move, from `t` | corners, borders, outlines, shadows |
| which kit class an element is | how that class looks |

A colour, family, or type size written into a scene breaks it in every other style. Where the kit has no class, build from the custom properties (`background: var(--rapid-color-accent)`); every property is in [writing scenes](/docs/writing-scenes#the-style-in-the-page). `rapid style check` refuses a `style.css` that leaves a kit class unstyled and names it (`style.css doesn't style the kit's .voice, .accent`). A style may style more classes; a scene using them renders plainly elsewhere. `rapid style extract` starts a draft's sheet from `DEFAULT_KIT_CSS`, the kit styled from tokens alone.

## A format is the deliverable

A format is the frame size and rate, the length range, the guides (safe area, readable band, keep-outs), the minimum text size, and the phone copy's size cap. A platform's keep-out belongs to the format, not the look.

Built in, under `formats/`:

| Format | Frame | `min_text` | Guides |
|---|---|---|---|
| `reel` | 1080 × 1920, 30 fps | 40 | `safe` inset 72 px; `band` y 240–1560; `feed-buttons` keep-out x 960–1080, y 900–1650, for type, cards, and bubbles |
| `square` | 1080 × 1080, 30 fps | 40 | `safe` inset 60 px |
| `wide` | 1920 × 1080, 30 fps | 36 | `safe` inset 96 × 54 px |

None has a length limit; each phone copy stays under 30,000,000 bytes and drops to 720p on its short side after 120 s. Fields: [Format](/docs/style-json#format).

## Resolving `--style` and `--format`

1. a folder at that path;
2. a package the project pins in `rapid.lock` by that name;
3. an installed package, `<name>` or `<name>@<version>`;
4. a built-in one: `bubble`, `conspiracy`, `launch`, `poster`, `swiss`, `terminal`; `reel`, `square`, `wide`.

## Installing and pinning

`rapid style add` and `rapid format add` install into `$RAPID_HOME/styles/<name>/<version>/` and `$RAPID_HOME/formats/<name>/<version>/`, read-only. The same version with the same files is a no-op; with different files it is refused.

`rapid style use <name>[@ref]` pins a package in the project's `rapid.lock` (installing it if needed): version, canonical hash, source. A copy that no longer matches its pin is refused. Sources and the lockfile: [sharing styles](/docs/sharing-styles).

A package in transit is a `.zip` of its folder, `manifest.json` at the root, at most 25 MiB, holding only the [allowed file types](/docs/style-json#rules).