# Preview

> unframework preview shows every example and component on every target side by side, with controls for their props, and preview build writes it as a static site.

The preview lets you see a component on every target at once while you work on it. Think of a button you restyle in React and only later find too narrow in Svelte, a prop you rename that Angular no longer reads, or an agent asked for a screenshot of a card in seven frameworks that opens seven apps to take it.

`unframework preview` starts one dev server per target your `unframework.config.ts` names, and a page that shows the selection in one labelled frame per target. Pick an example or a component in the sidebar, and change its props in the controls panel, a component's own or those of the components an example renders: every target renders the same thing with the same props.

This page walks you through it. We'll look at:

- **Running it** with `unframework preview`.
- **What it shows:** your examples and your components.
- **The page:** the sidebar, the canvas, the controls panel and the keyboard.
- **Example metadata:** the category, title, description and order of each example.
- **Controls:** the props the preview can set, on a component and in an example.
- **How it works:** the servers, the frames and what it writes.
- **Building a static preview** with `unframework preview build`.
- **Embedding an example** in another page, by its own URL.
- **Deploying it** to any static host.

## Run it

`unframework preview` comes with `@uxfront/unframework`, and needs `@unframework.dev/visual` and `vite` in your project, beside what [`unframework visual`](/docs/tooling/visual#run-it) needs. The sample design system runs it from a script of its `package.json`:

<!-- prettier-ignore -->
```json [package.json]
    "preview": "unframework preview",
```

It prints the page's URL, then each target's server, and runs until you press `Ctrl+C`, which stops every server. These are its options:

| Option         | What it does                                                                                   |
| -------------- | ---------------------------------------------------------------------------------------------- |
| `--target <t>` | Shows one target, and can be repeated. By default it shows every target of your configuration. |
| `--port <n>`   | The page's port. By default the system picks a free one, and each target's server always does. |

It exits `0` once you stop it, and `2` on a usage or configuration error, a project with no example and no component, or a package it needs that isn't installed.

The preview is for your machine while you develop: every server listens on `127.0.0.1` only. Each target's compiler stack, like Angular's, comes from [`package.resolveFrom`](/docs/tooling/configuration#fields), as for `unframework test`.

## What it shows

The sidebar lists your examples first, then your components. An example is a [`*.example.uf.tsx` file](/docs/tooling/visual#examples) with no props, found as `unframework visual` finds it. A component is the default export of a `.uf.tsx` file under `srcDir`, an example excepted. A file with no default export, or one that doesn't compile, isn't listed, and `unframework check` says why.

The page opens on the first example, and keeps the selection in its URL, so a reload or a link shows the same thing. Each frame's caption names its target and says whether it rendered, or why it failed.

A component renders with props alone, so its slots are empty and its models keep their defaults. To see a component with content, write an example that fills it, as `examples/Buttons.example.uf.tsx` does for `Button`.

## The page

The page has three parts, side by side:

- **The sidebar** holds your examples as a tree of their [categories](#example-metadata), and your components below it, by their paths. The filter at the top keeps the items whose name, or whose group's name, holds what you type.
- **The canvas** shows the selection's title and description, and one frame per target. **Targets** above the frames shows them all side by side, or one at a time at the canvas's full size. A preview of one target shows it at the canvas's full size from the start, with no **Targets** switch.
- **The controls panel** holds the [controls](#controls) of the selected component, or of each component the selected example renders, and names the props it can't set.

In a narrow window, the three stack: the sidebar, then the canvas, then the controls.

The page follows your system's light or dark setting. The moon button at the top of the sidebar switches between the two, and the page keeps your choice for the next time you open it. The frames keep a white page in both, since your components bring their own colours.

Everything works from the keyboard. Press `?` to list these shortcuts on the page:

| Key               | What it does                                      |
| ----------------- | ------------------------------------------------- |
| `/`               | Moves to the filter.                              |
| `Esc`             | Clears the filter.                                |
| `↓` in the filter | Moves to the first item of the tree.              |
| `↑` and `↓`       | Move through the tree.                            |
| `←` and `→`       | Close or open a group, or move out of or into it. |
| `Home` and `End`  | Move to the tree's first or last item.            |
| `Enter`           | Shows the item, or opens or closes a group.       |
| `?`               | Lists the shortcuts.                              |

`/` and `?` do nothing while you type in a field.

## Example metadata

The page lists your examples under their categories, by their titles. A doc comment on an example's default export sets them:

<!-- prettier-ignore -->
```tsx [src/components/button/examples/ButtonColors.example.uf.tsx]
/**
 * Every colour the theme defines, on the solid variant.
 * @category Components/Actions/Button
 * @title Colors
 * @order 2
 */
export default function ButtonColors() { … }
```

The comment has to sit directly on `export default`. Its text is the example's description. These are the tags it reads, and it ignores any other:

| Tag         | What it sets                                                         | Without it                                                                 |
| ----------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `@category` | The groups the example sits in, outermost first, separated by `/`.   | The example's directory, or its parent's when the directory is `examples`. |
| `@title`    | The example's name in the list.                                      | The file name in words, without the category's own words in front.         |
| `@order`    | Where it sits among the others, as a number: lower comes first.      | After every example that has one.                                          |
| `@layout`   | How it sits in its frame, as [Example layout](#example-layout) says. | Centred in its frame.                                                      |

So without a comment, `src/components/button/examples/ButtonColors.example.uf.tsx` is `Colors` in `Button`, and `src/components/field-group/examples/FieldGroupDefault.example.uf.tsx` is `Default` in `Field Group`: the directory's name in title case, with `-` and `_` as spaces. An example at your project's root, or in a root `examples/`, is in `Examples`.

Examples sort by `@order`, then by title, then by id. An empty `@category` or `@title`, an `@order` that isn't a number, a malformed `@layout`, or a tag given twice is a warning, [UF7012](/docs/reference/diagnostics#UF7012), which the preview prints when it starts, and `preview build` when it builds. It then uses the value it derives instead.

The comment changes nothing that renders, so [`unframework visual`](/docs/tooling/visual#examples) doesn't read it, and an example keeps its id and its baselines.

### Example layout

Each frame centres its example by default, so a small component like a button sits in the middle of its frame rather than in a corner. `@layout` changes how it sits, the way `display: flex` would on the element the example mounts in:

<!-- prettier-ignore -->
```tsx [src/components/button/examples/ButtonSizes.example.uf.tsx]
/**
 * The two sizes, stacked.
 * @layout column align-start gap
 */
export default function ButtonSizes() { … }
```

Its value is words in any order, at most one of each kind. A kind you leave out keeps its default:

| Words                                                                                                   | What they set                                         | Without them     |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------- |
| `row`, `column`                                                                                         | The direction, `flex-direction`.                      | `row`            |
| `justify-start`, `justify-center`, `justify-end`, `justify-between`, `justify-around`, `justify-evenly` | The alignment along the direction, `justify-content`. | `justify-center` |
| `align-start`, `align-center`, `align-end`, `align-stretch`, `align-baseline`                           | The alignment across it, `align-items`.               | `align-center`   |
| `wrap`                                                                                                  | Whether the items wrap, `flex-wrap`.                  | No wrapping      |
| `gap-xs`, `gap-sm`, `gap`, `gap-lg`, `gap-xl`                                                           | The gap, from a scale.                                | `0`              |
| `gap-<length>`                                                                                          | The gap, as `0` or a length in `px`, `rem` or `em`.   | `0`              |

The scale is `0.25rem`, `0.5rem`, `1rem`, `1.5rem` and `2rem`, so a bare `gap` matches the frame's padding. Reach for a length only when the scale doesn't fit: `gap-8px`, `gap-0.5rem` and `gap-0` work, while `gap-8` and `gap-.5rem` don't. A layout takes one gap, from the scale or a length.

A flex layout keeps `1rem` of padding around the example and fills the frame's height. Centre and end alignment are `safe`, so an example larger than its frame starts at its top-left edge and you can scroll to the rest.

`@layout none` turns all of this off: the example fills the frame's width, as a plain block with no padding. It's the one to pick for a page section or a form that should take the whole width.

The layout sits on the frame's container alone, so the example's own elements look exactly as the component renders them. A component you select in the list is centred, like an example without the tag. An empty value, a word the list doesn't have, two words of one kind or `none` with other words is [UF7012](/docs/reference/diagnostics#UF7012), and the preview centres that example.

## Controls

A component gets one control for each prop whose type the preview can set:

| Prop type                  | Control              |
| -------------------------- | -------------------- |
| `boolean`                  | A checkbox           |
| `string`                   | A text field         |
| `number`                   | A number field       |
| A union of string literals | A list of its values |

The type can be an alias, even one imported from another file. The sample design system's `Button` takes a `variant?: ButtonVariant`, from its `src/types.ts`:

<!-- prettier-ignore -->
```ts [src/types.ts]
export type ButtonVariant = "primary" | "secondary";
```

So its `variant` gets a list of `primary` and `secondary`. Change it, and every frame renders the button again with the new value, in place.

An optional prop starts unset, so the component's own default applies, and its control offers "(default)" to go back to it. A blank text or number field leaves an optional prop unset too. A required prop starts at `false`, an empty string, `0` or the first value of its union.

A prop of any other type, like a function, an object or a union of numbers, gets no control. The page names it, with its type.

### Controls on an example

An example gets the controls of the components it renders, so you can see `ButtonColors` disabled, or in another size, without writing another example. The panel shows one group per component, in the order the example first renders each, headed by the component's name, and by its path too when two groups share a name.

A control's value reaches every instance of that component in the example that doesn't set the prop itself, whatever its value, an instance inside another component's slot included. A prop an instance sets keeps that instance's value. Take the sample design system's `examples/Buttons.example.uf.tsx`:

<!-- prettier-ignore -->
```tsx [examples/Buttons.example.uf.tsx]
import Button from "../src/Button.uf.tsx";

export default function Buttons() {
  return (
    <div>
      <Button>Save</Button> <Button variant="secondary">Cancel</Button>
    </div>
  );
}
```

Set its `variant` control to `secondary`, and **Save** turns `secondary`, while **Cancel** keeps the `secondary` it sets. Set it to `primary`, and **Cancel** still keeps `secondary`.

A prop that every instance sets gets no control, since no instance would take its value: the group names it under "Set by the example". A required prop is always there, because every instance must set it. Every control on an example starts at "(default)", which means "as the example wrote it", so a `boolean` gets a list of "(default)", `true` and `false` rather than a checkbox. A reload, or another selection, starts every control at "(default)" again, as on a component.

Only the components under `srcDir` that the preview lists get controls. A component the example file declares itself, the instances inside it, a component from a package and an instance that `<component is>` renders are left as written. So is an example that declares props, which is [UF7011](/docs/reference/diagnostics#UF7011), or one that doesn't compile: the panel says it has no controls, and the frames show its errors.

The preview reads which controls an example gets when it starts. An instance you add while it runs gets the controls its component already has, and a component new to the example gets its controls once you restart.

## How it works

Each target gets a Vite dev server of its own, built the way `unframework test` builds a browser project: the plugins of your config's [`vite`](/docs/tooling/testing#styling-engines-and-other-vite-plugins), like a styling engine's, then the Unframework plugin for that target, then the target's own plugins, in that order within each of Vite's `enforce` groups. Each listens on a port of its own, so each frame has an origin of its own, and the frameworks never share a page. The page sends each frame the selection and its props with `postMessage`, and each frame mounts it with that target's mount adapter, the one the tests use. Astro has no client runtime, so its frame asks its own server to render on the server, and inserts the HTML.

An example's controls are props the preview gives the example itself. Each target's server rewrites an example before it compiles it: the example takes one optional prop per control, and each instance that doesn't set the control's prop gets it bound, as in `<Button variant={ufPreview.ufControl0}>`. "(default)" leaves the prop unset, so the component's own default applies.

The rewrite keeps every line where it was, so an error points at the right line. It's the preview's alone: your files don't change, and `unframework visual` and `unframework test` render the example as written.

Each server calls `vite` with its target and `mode: "preview"`, for plugins of its own, and merges the other keys it returns into its config, as a test project does. It refuses the same keys, `server.host`, `server.port` and `server.hmr` among them, so the preview never listens beyond your machine.

The preview writes nothing beside your sources. Vite keeps each server's cache in `node_modules/.vite`, and Angular's compiler keeps its scratch in `.uf-tmp/`, in the directory its stack resolves from.

The first time a target meets a dependency it hasn't bundled yet, Vite bundles it and reloads that frame. The frame then asks for the selection again, so you don't have to do anything.

From a script, `startPreview({ root, targets?, port?, toolchainDirs? })` from `@unframework.dev/visual` starts the same servers. It resolves to `{ url, frames, diagnostics, close }` once every one listens: `url` is the page's, `frames` lists each target's origin and port, `diagnostics` holds the [UF7012](/docs/reference/diagnostics#UF7012) warnings of your examples' doc comments, and `close()` stops them all. That's how an agent takes a screenshot of the page with Playwright, then stops the preview.

## Build a static preview

`unframework preview build` writes the same preview as a static site, so you can publish it for the people who use your components, or give each pull request a link to it. It builds each target's frame with Vite, on the configuration its dev server uses, and writes the page that frames them beside them:

<!-- prettier-ignore -->
```bash
unframework preview build --out dist/preview
```

It prints any [UF7012](/docs/reference/diagnostics#UF7012) warning of your examples, then where it wrote the site and the targets it built, and exits `0`. These are its options:

| Option         | What it does                                                                                                            |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--target <t>` | Builds one target, and can be repeated. By default it builds every target of your configuration.                        |
| `--out <dir>`  | The site's directory, relative to your project. By default it's `.unframework/preview`, which examples are never under. |

The build empties `--out` first, so it refuses your project's directory, a directory above it, and one that isn't empty and that no earlier build wrote. Those refusals exit `2`, like a usage or configuration error, a project with nothing to show, or a build that fails.

The site is the page as `index.html`, and one directory per target, like `react/` and `vue/`, with that target's frame as `frame.html`. Every URL in it is relative, so a static host serves it at any path, with no rewrites and no server. Open it at its directory's URL with the final slash, like `https://example.com/preview/`: without it, the page's relative URLs resolve from the directory above.

It runs what the dev preview runs, with three differences:

- **Every frame shares the page's origin,** so the frames share storage and cookies. An example that reads `localStorage` can see what another target's frame wrote there. A frame that the page drives answers only a page of its own origin, so another site can't frame it and drive it. An [embedded example](#embed-an-example) takes one message at most, its colour mode, from the page that frames it.
- **Astro shows each entry with its first props only.** The site has no server to render Astro, so the build renders each example and each component once, with the props the page first sends it, which for an example is every control at "(default)", and the Astro frame shows that render. Change a control, on a component or an example, and the Astro frame says it can't render it, while every other target renders it. Go back to the first values, and it renders again. An [embed with controls](#show-the-controls) on Astro does the same: it shows the message in place of the example, and the panel stays.
- **The frames are development builds,** as the dev servers serve, so they're bigger than a production build. A path under your project, or its repository, appears relative to it, so the site carries no path of the machine that built it.

From a script, `buildPreview({ root, targets?, out?, toolchainDirs? })` from `@unframework.dev/visual` writes the same site, and resolves to `{ out, targets, diagnostics }`, where `diagnostics` holds those warnings.

## Embed an example

Each example has a URL of its own on each target, which shows that example alone, with no sidebar or canvas. Put it in an `<iframe>`, and a docs page, a blog post or a design-system site shows the example live, in the framework you pick. The URL sits beside the page:

<!-- prettier-ignore -->
```text
embed.html?example=<id>&target=<target>
```

`example` is the example's id, its path without `.example.uf.tsx`, like `examples/Card`. `target` is one of the names in the frames' captions, like `vue` or `solid2`. Both are required. So a site at `https://example.com/preview/` shows the sample design system's card in Vue with:

<!-- prettier-ignore -->
```html
<iframe src="https://example.com/preview/embed.html?example=examples/Card&target=vue" title="Card, in Vue"></iframe>
```

We recommend giving each `<iframe>` a `title`, since that's the name a screen reader gives the frame. The **Open** link in each frame's caption opens the selected example's URL on that target in a new tab, so you can copy it from there.

`embed.html` checks the example and the target, then replaces itself with that target's frame, which renders the example once. An unknown or missing example or target shows a message in the frame instead, so an embed is never a blank page. The URL is the contract: the frame's own URL, where `embed.html` sends the browser, may change.

Three optional parameters ask for more:

| Parameter  | Values          | What it does                                                         |
| ---------- | --------------- | -------------------------------------------------------------------- |
| `controls` | `true`          | Shows the example's controls below it.                               |
| `theme`    | `light`, `dark` | Sets the colour mode, which the page that frames it can then change. |
| `resize`   | `true`          | Sends the example's height to the page that frames it.               |

`embed.html` checks each value, and any other one, like `theme=blue`, shows a message that names the values it takes. With none of the three, the embed shows the example alone and takes and sends no messages.

### Show the controls

With `controls=true`, the embed shows the example's controls below it, as the page's **Controls** panel shows them, and each change renders the example again. A prop the example sets itself keeps its value, as in the page. The panel keeps its own styles, so your project's global styles, on `body`, `label` or `select`, reach the example and not the panel.

When you set the `<iframe>`'s height, the example takes the space above the panel, and the panel takes at most half the frame. Each scrolls on its own when its content is taller. With `resize=true` too, nothing scrolls: the embed reports the height of both.

### Set the colour mode

`theme=light` or `theme=dark` sets `data-theme` on the embed's `<html>`, with the matching `color-scheme`, before the example renders. Styleframe's themes select `[data-theme="dark"]`, so a Styleframe project's dark theme applies. The panel follows the mode too. Without `theme`, the embed follows the reader's system.

With `theme` in its URL, the embed also takes the mode from the page that frames it, so the page can change it without a reload, and the control values stay. The page posts this message to the `<iframe>`:

<!-- prettier-ignore -->
```js
iframe.contentWindow.postMessage({ type: "unframework:embed", kind: "theme", theme: "dark" }, "https://example.com");
```

Name the preview's origin as the target, as above, so the message reaches only your preview. The embed takes it only from its parent window, only with exactly these three keys and only with `light` or `dark`. It ignores every other message.

### Size the iframe to its content

With `resize=true`, the embed sends its height, in whole CSS pixels, to the page that frames it, once it has rendered and whenever the height changes:

<!-- prettier-ignore -->
```js
{ type: "unframework:embed", kind: "resize", height: 148 }
```

The page sets the `<iframe>`'s height from it. Check that the message comes from that `<iframe>`, since any frame on the page can post one:

<!-- prettier-ignore -->
```html
<iframe id="card" src="https://example.com/preview/embed.html?example=examples/Card&target=vue&controls=true&theme=light&resize=true" title="Card, in Vue"></iframe>
<script>
  const card = document.getElementById("card");
  addEventListener("message", (event) => {
    if (event.source !== card.contentWindow) return;
    if (event.data?.type !== "unframework:embed" || event.data.kind !== "resize") return;
    card.style.height = `${event.data.height}px`;
  });
  // Call this from the site's colour mode switch.
  function setEmbedTheme(theme) {
    const message = { type: "unframework:embed", kind: "theme", theme };
    card.contentWindow.postMessage(message, "https://example.com");
  }
</script>
```

The height is the page's content: the example, and the panel when it shows. Content outside the page's flow isn't counted, like a dialog that `<Teleport>` moves, or an element positioned outside the example. An example whose height follows the viewport, in `vh`, grows with the `<iframe>`, so give it a fixed height instead.

Keep in mind what an embed does and doesn't do:

- **It takes no props.** An example sets its own props, so the URL holds none, and a component, which needs props, has no embed. The controls set props from inside the embed, and their values don't go in the URL, so a reload starts from "(default)".
- **It takes one message at most.** The colour mode, when its URL has `theme`. The page that frames it can't select an example or set a prop.
- **Your host decides who may frame it.** The site sets no `X-Frame-Options` or `Content-Security-Policy: frame-ancestors`, so any page can frame it. To limit that, set one of those headers on your host.

The dev preview serves the same page, at `embed.html` beside its own URL, like `http://127.0.0.1:5173/embed.html?example=examples/Card&target=vue`. The page takes a free port on each run unless you set `--port`, so set it to keep a dev URL from one run to the next. Each target's server still takes a free port, which `embed.html` finds for you.

## Deploy

The site is plain files, so any static host serves it. On Cloudflare, a Worker with static assets serves the directory, and Workers Builds builds it on every push and gives each pull request a preview URL. Add a script that builds it to your `package.json`:

<!-- prettier-ignore -->
```json [package.json]
    "preview:build": "unframework preview build --out dist/preview",
```

Then point a `wrangler.json` at the directory:

<!-- prettier-ignore -->
```json [wrangler.json]
{
  "name": "my-components-preview",
  "compatibility_date": "2026-11-01",
  "assets": { "directory": "./dist/preview" },
  "previews": {}
}
```

In the Worker's build settings, the build command is `npm run preview:build`, and the deploy command is `npx wrangler deploy`.

The decisions behind this page are [ADR-0088](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0088-unframework-preview.md), [ADR-0110](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0110-examples-carry-metadata-in-a-doc-comment.md), [ADR-0111](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0111-unframework-preview-build-writes-a-static-site.md), [ADR-0112](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0112-an-example-opens-by-its-own-url.md) and [ADR-0113](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0113-preview-controls-reach-an-examples-components.md).
