docs menu

Design browser

Sites made from the site template 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.