Core concepts

Four ideas carry all of Loupe. Learn them once and every page after this is detail.

The config: groups → options → specimens

A Config is a small tree. The shape is enforced by Zod, so a malformed config fails loudly before it can render.

Config
└─ groups[]          one decision each   (1..n groups)
   └─ options[]      the choices         (2..6 options)
      └─ specimen    what the choice is  (one of 5 kinds)

• A group is a single decision: "Color system", "Headline voice", "Hero layout". It has an id, a title, an optional prompt, and 2–6 options.
• An option is one answer: an id, a label, an optional caption, an optional recommended flag, and exactly one specimen.
• A specimen is what the option looks like — the rendered tile. There are five kinds: imageCrop, palette, type, motion, layoutMock. Each is covered on the specimens page.

const config: Config = {
  version: 1,
  title: "My direction",
  assets: {},          // declared images: { key: { src, width, height } }
  theme: {},           // optional brand tokens (see Theming)
  groups: [
    {
      id: "color",
      title: "Color system",
      prompt: "Which palette carries the brand?",
      options: [
        { id: "ink", label: "Ink + signal", recommended: true, specimen: { /* ... */ } },
        { id: "amber", label: "Warm amber", specimen: { /* ... */ } },
      ],
    },
  ],
  preview: { bands: [/* which group feeds each preview slot */] },
  banned: [],          // prose that flows into the brief
};

Single-select and Clear

Each group holds one locked option at a time — it behaves like a radio group (and is wired as an APG radiogroup with roving tabindex and arrow-key navigation).

• Lock: click a tile (or focus it and press Space/Enter, or arrow to it). The previous pick in that group is released automatically.
• Idempotent: locking the already-locked tile is a no-op — the store does not re-emit.
• Clear: every group shows a Clear control once something is locked. Clearing returns the group to open (no pick), which is distinct from picking a default.
• Recommended vs. Reset vs. Clear all: the stack's Recommended button loads each group's recommended option; Reset clears every group to blank. A group with no recommended option starts open.

This matters because open is a real, meaningful state in the brief — it reads (open), signalling a decision that has not been made yet, rather than silently defaulting.

The composed preview

Locking tiles is only half the value. The other half is seeing the picks compose — a sticky panel that assembles your choices into one artifact-in-miniature, so you judge them together, not in isolation.

The preview.bands array maps each group onto a slot in that panel, and an optional as hint controls how the band renders:

preview: {
  bands: [
    { slot: "voice", fromGroup: "voice", as: "headline" },
    { slot: "color", fromGroup: "color", as: "swatch" },
  ],
  headlineFrom: "voice",   // which group supplies the headline text
}

If you omit preview, every group becomes a band in config order. The headline defaults to the first group that contains a type specimen. Bands for groups that are still open render as labelled empty slots, so the composition shows you what is missing.

The deterministic export brief

The export brief is the point of the whole tool: a handoff that a build pass — human or agent — can consume exactly. It comes in two forms, both derived from the same selections that drive the preview, so the two can never disagree.

• Markdown — the resolved direction: title, locked decisions (one line per group), banned list, workflow. This is what the Copy brief button copies.
• JSON — the machine-readable locks: version, title, decisions[] (group id, title, option id, label), and banned[].

# My direction

## Locked decisions
- Color system: Ink + signal
- Headline voice: Bold sans

## Banned
- Generic SaaS gradient blobs.

"Deterministic" is a load-bearing word here. The brief preserves config order, emits no timestamps and no absolute paths, and normalizes away floating-point noise. The same config and the same picks always produce byte-identical output — so it diffs cleanly in a PR and an agent can assert on it.

Next