# Design browser

> Every token, atom, component and block of a site, rendered by the site itself at /_design, with variants, controls, light and dark, languages and widths. Designers edit tokens from the studio and agents read the components through MCP.

Sites made from the [site template](/docs/site-template.md) have a design browser at `/_design`. It is a route of the site, so it shows the real components with the real styles and data, and there is nothing else to build or deploy.

- **Tokens**: color swatches in both schemes with their contrast, the web font families with a sample of each file (and whether it loaded), font stacks, the type scale, spacing, radii, shadows and motion.
- **Atoms**, **components** and **blocks**: every variant from the component's examples file, one at a time or all side by side.
- **Controls**: change props (text, numbers, switches, choices, colors) and see the result at once.
- **Light and dark**, **language** and **width** (phone, tablet, desktop or full).
- **Real content**: pick a block from a page or a post in the project and see the component with it, drafts included.

The browser opens in development, or in draft mode: from the studio's design tab, or with the preview link `/api/galerne/preview?secret=…&redirect=/_design`. It stays private: pages carry `noindex` and `robots.txt` disallows the route.

One variant alone, for a screenshot or an agent: `/_design/frame/blocks/hero?variant=split&theme=dark&lang=fr`.

## Examples files

Each component has a `<name>.examples.tsx` next to it:

```ts
import { images } from '@/design/fixtures.ts'
import { blockExamples } from '../examples.ts'
import { Hero } from './hero.tsx'

export default blockExamples('hero', {
  title: 'Hero',
  description: 'The opening of a page.',
  component: Hero,
  variants: {
    split: { args: { heading: 'Concerts by the water', image: images.harbour, layout: 'split' } },
    'text only': { args: { heading: 'Notes on making things for the web' }, description: 'No image.' },
  },
  controls: {
    heading: { type: 'text' },
    layout: { type: 'select', options: ['split', 'centered', 'cover'] },
  },
})
```

Atoms and components use `defineExamples` from `@galerne/next/design` the same way, with the component's props as `args`. Controls are keyed by dot paths into the args (`items.0.title`). Examples files hold data only, without JSX, so a plain Node script reads them.

`scripts/design-manifest.ts` finds every examples file and writes `design/registry.ts` (what the browser renders) and `design/manifest.json` (what agents read). `dev` and `build` run it; after adding a file, run `npm run design`.

## In the studio

The **design** tab of a project frames the site's `/_design` on the current branch, like the preview pane of the editor. It needs the preview URL and secret in **Settings**, **General**.

The token editor next to it lists `theme/tokens.json`: color pickers for the light and dark values with contrast hints, a font picker with the site's own web fonts (the `fonts` group) and stacks of fonts every system has, and steppers for sizes and spacing. Web fonts render in the frame, which loads them from the site. Each change restyles the framed site at once, without saving. **save on a branch** commits only the changed tokens with `update_theme`, the branch preview rebuilds, and the change goes through review like any other.

## For agents

`list_components` returns the components, their props, controls and variants, and the CMS fields of blocks. Give `id` for one component with the args of each variant. It reads `design/manifest.json` from the site repo on a branch when Galerne manages the code, else from the site at `<preview URL>/_design/manifest.json` with the preview secret.

Agents see their work the same way people do: `preview_url` with `path: "/_design/blocks/hero"`, then fetch or screenshot the page.
