# atomm Developer Platform

> Full documentation for building generator apps on the atomm platform.
> The design system is published separately as a DESIGN.md-format file at /design.md.

---

# Quickstart

Integrate a generator built with any tech stack into Atomm: **create a generator → add one line of SDK and integrate capabilities → preview and debug locally in real time → submit for review and publish**. No command-line tools required.

> **Any stack that outputs static web files works**
>
> Plain HTML, Vite, Vue, React — any tech stack works. Atomm communicates with your app through a browser-side SDK and doesn't constrain how you build it.

## End-to-end flow

**1. Create a generator in the Developer Console**

Start by picking a name to serve as its public identifier (**must start with a lowercase letter and contain only lowercase letters, digits, and hyphens -; it cannot be changed after creation**, as it becomes part of the runtime subdomain and access path). After creation you'll land on the app detail page to continue setup. This name is used again in local preview and final publishing.

**2. Add the SDK to your app and integrate capabilities**

Add one script tag to your page to get the global `atomm` object:

```html
<script src="https://static-res.makextool.com/scripts/js/generator-sdk/platform-sdk.js"></script>
```

Then integrate platform capabilities as needed. Taking export as an example, this takes two steps — place an export button placeholder element (the SDK renders it in place as an Export button), and register an `export` hook to supply the resulting file:

```html
<!-- Place anywhere on the page; the SDK renders it in place as an Export dropdown -->
<div data-atomm-export-button></div>
```

```js
// The platform calls back into your app for the result file when the user clicks export
atomm.lifecycle.on('export', async () => ({ filename: 'design.glb', blob }))
```

See the [atomm object](/docs/atomm) and [export capability](/docs/export) for details.

**3. Start your local server, then preview and verify in real time in the browser**

Start your local server (e.g. `http://localhost:5173`), build the preview URL using the generator name from step 1, and put your local address into `?local=` (only loopback addresses such as localhost / 127.0.0.1 are supported):

```text
https://www.atomm.com/creativetools/community/generator/<generator-name>?local=http://localhost:5173/
```

DevTool runs your local app inside the same environment it will run in live, and previews it there. The integration assistant panel on the right shows whether the SDK is loaded and lists the platform capabilities available to integrate, so you can verify in the preview that export and other capabilities are being invoked correctly. You can also open this directly from the "Local debugging" card on the app detail page by entering your local address. See [Local debugging](/docs/devtool) for details.

**4. Upload the artifact, submit for review, and publish**

On the app detail page's configuration card, add your listing information, upload the packaged artifact, and submit for review. Once approved, it's automatically published to `https://www.atomm.com/creativetools/community/generator/<生成器名称>`, and users can open and use it directly from the generator gallery — no installation required. See [Submitting for review and publishing](/docs/publish) for details.

---

# Local Debugging

No command-line tools need to be installed. Local debugging takes only two steps: **integrate the SDK**, then open the online DevTool in your browser to load your local service.

## 1. Integrate the Platform SDK

Include this in your app page:

```html
<script src="https://static-res.makextool.com/scripts/js/generator-sdk/platform-sdk.js"></script>
```

Once loaded, the SDK handshakes with the platform and injects a global `atomm` object (see [atomm object](/docs/atomm)).

## 2. Open the Online DevTool Preview

After starting your service locally (any port), open the URL below in your browser and fill your local address into `?local=` (only loopback addresses such as localhost / 127.0.0.1 are supported):

```text
https://www.atomm.com/creativetools/community/generator/<generator-name>?local=http://localhost:5173/
```

- Left: a live preview of your generator (your local service runs in the same environment it will run in live, with the same capability limits)
- Right: two tabs

  - **Simulator**: currently offers "Preview language" — switching it changes what `atomm.app.getLocale()` returns and reloads your generator, so you can verify your localization (see [The atomm object · Language](/docs/atomm#language-atommapp)).
  - **Integration assistant**:
  
    - **SDK integration hint**: shows an "integration incomplete" notice until `platform-sdk.js` is loaded, along with copyable integration code and a documentation link; it disappears automatically once the SDK handshake succeeds.
    - **Platform capability list**: lists the capabilities the platform provides (export / download, the `atomm` object, etc.); each item lets you "view docs" or "copy the integration prompt" to hand off to an AI for integration.

Dev preview mode is fixed to the `dev` environment, incurs no charges, has all platform capabilities enabled by default, and does not depend on any backend data.

> **You can also open it directly from the console**
>
> On the app detail page in the Developer Console, fill in your local address in the "Local Debugging" card to open the preview above directly.

> **About HTTP and mixed content**
>
> `www.atomm.com` runs over HTTPS. Browsers grant a mixed-content exemption for `http` addresses on `localhost`, so a local http service loads normally; **non-localhost http addresses will be blocked by the browser** — use `localhost` or enable HTTPS for your local service.

---

# atomm Object

`atomm` is a global object injected into the page once the platform SDK (`platform-sdk.js`) loads. It exposes platform capabilities and UI utilities, and can be used directly in your generator code.

## Lifecycle — atomm.lifecycle

Register platform lifecycle hooks via `lifecycle.on`:

```js
atomm.lifecycle.on('export', async () => { ... })
```

## Toasts — atomm.ui

Shows a platform-wide toast notification. Takes an object as its argument:

- `type`: optional, one of `success` / `warning` / `error` / `info`, defaults to `success`
- `message`: the notification text
- `duration`: optional, how long the toast stays visible, **in seconds**; `0` means it won't auto-close; defaults to **3 seconds** if omitted

`toast()` returns the **id** of that toast; call `closeToast(id)` to close it manually. A persistent toast with `duration: 0` must be closed this way, or it will stay on screen indefinitely.

```js
atomm.ui.toast({ type: 'success', message: '已完成' })

// Show for 5 seconds
atomm.ui.toast({ type: 'info', message: '正在处理…', duration: 5 })

// duration: 0 keeps it on screen; close it with closeToast once the task finishes
const id = await atomm.ui.toast({ type: 'info', message: '导出中…', duration: 0 })
// …task finishes…
await atomm.ui.closeToast(id)
```

> **toast requires an object**
>
> Passing a string (e.g. `toast('已完成')`) won't work — the platform only reads `message` and `type` off an object, so a string is treated as an empty message. The `ui` namespace currently provides `toast` (which returns the toast's id) and `closeToast`.

## Language — atomm.app

The platform's current UI language, so your generator can localize along with it.

```js
// Current locale code — always one of the 17 supported languages
const locale = await atomm.app.getLocale()

// All supported locales (code + display name), for building a language selector consistent with the platform
const locales = await atomm.app.getSupportedLocales()
// → [{ code: 'zh', name: '简体中文' }, { code: 'en', name: 'English' }, …]
```

Calling `getLocale()` once at startup to pick the initial language is enough. **It is a one-time read, not a subscription** — changing the platform language reloads the whole page, so your app restarts and reads the new value on its own. You never need to listen for changes.

`getLocale()` always returns one of the 17 codes below, but **your app may not have translated all of them**. When you get a language you have no copy for, fall back to English or your own default.

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      Display name
    </th>
    
    <th>
      Language
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        zh
      </code>
    </td>
    
    <td>
      简体中文
    </td>
    
    <td>
      Simplified Chinese
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        en
      </code>
    </td>
    
    <td>
      English
    </td>
    
    <td>
      English
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        zh-hant
      </code>
    </td>
    
    <td>
      繁體中文
    </td>
    
    <td>
      Traditional Chinese
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        de
      </code>
    </td>
    
    <td>
      Deutsch
    </td>
    
    <td>
      German
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        es
      </code>
    </td>
    
    <td>
      Español
    </td>
    
    <td>
      Spanish
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fr
      </code>
    </td>
    
    <td>
      Français
    </td>
    
    <td>
      French
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        it
      </code>
    </td>
    
    <td>
      Italiano
    </td>
    
    <td>
      Italian
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ja
      </code>
    </td>
    
    <td>
      日本語
    </td>
    
    <td>
      Japanese
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ko
      </code>
    </td>
    
    <td>
      한국어
    </td>
    
    <td>
      Korean
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ru
      </code>
    </td>
    
    <td>
      Русский
    </td>
    
    <td>
      Russian
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uk
      </code>
    </td>
    
    <td>
      Українська
    </td>
    
    <td>
      Ukrainian
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sl
      </code>
    </td>
    
    <td>
      Slovenščina
    </td>
    
    <td>
      Slovenian
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        th
      </code>
    </td>
    
    <td>
      ไทย
    </td>
    
    <td>
      Thai
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pl
      </code>
    </td>
    
    <td>
      Polski
    </td>
    
    <td>
      Polish
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cs
      </code>
    </td>
    
    <td>
      Čeština
    </td>
    
    <td>
      Czech
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      Bahasa Indonesia
    </td>
    
    <td>
      Indonesian
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vi
      </code>
    </td>
    
    <td>
      Tiếng Việt
    </td>
    
    <td>
      Vietnamese
    </td>
  </tr>
</tbody>
</table>

The table is in the order `getSupportedLocales()` returns, and "Display name" is exactly the `name` it gives you — use it directly in a language picker.

> **Testing languages locally**
>
> The developer toolkit's Simulator has a "Preview language" dropdown. Switching it changes what `getLocale()` returns and reloads your generator, so you don't have to change the language on the real platform. See [Developer toolkit](/docs/devtool).

## User — atomm.user

```js
// Whether the user is currently logged in (returns only a boolean, no token or profile data)
const loggedIn = await atomm.user.isLoggedIn()

// If not logged in, opens the login dialog and waits for the user to finish; returns whether they ended up logged in
if (!loggedIn) {
  const ok = await atomm.user.login()
  if (!ok) return // User canceled or login failed
}
// Reaching here means the user is logged in — continue with your logic
```

> **Call login from within a user gesture**
>
> `login()` opens a login window, so call it from within a user gesture handler (e.g. a click callback) to avoid having it blocked by the browser's popup blocker. Logging in is a long-running interaction, so the platform already extends its timeout for it (about 5 minutes) — you don't need to add your own.

## Safe invocation

If you're not sure whether your code is running inside the platform, use optional chaining to avoid errors:

```js
window.atomm?.ui?.toast?.({ type: 'info', message: 'hi' })
```

---

# Overview

This section covers the technical requirements for building a three.js 3D preview into a creative tool / generator on the Atomm platform — architecture, interaction, render quality, and performance and stability — and closes with a pre-submission acceptance checklist.

**Applies to**: every generator app that ships a 3D preview view.

The same requirements are also written as a single-file skill for coding agents (**Download 3D Preview Skill**, top right). Hand it straight to yours.

The demo below is what an agent built after reading that skill: drag to orbit, scroll to zoom, and every parameter on the right feeds one geometry IR that the 2D preview, the 3D view and the exported SVG all read from.

## How to read the requirement levels

<table>
<thead>
  <tr>
    <th>
      Term
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Must
      </strong>
    </td>
    
    <td>
      Mandatory. Checked item by item at review.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Should
      </strong>
    </td>
    
    <td>
      The default. Deviate only with a good reason.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Optional
      </strong>
    </td>
    
    <td>
      Implement it if your product needs it.
    </td>
  </tr>
</tbody>
</table>

## Do you need a 3D preview at all?

A 3D preview is optional. Build one only when **thickness, stacked depth or how parts fit together** is core to what your tool has to show. If the output is essentially flat, use a 2D SVG with a procedural material texture instead (a `feTurbulence` wood-grain filter, for example) — you get the material read at a fraction of the cost.

Once you decide to build one, it has to meet every acceptance criterion below. A 3D preview that falls short of the interaction and rendering baseline makes the product feel worse than no 3D at all, and will not pass review.

---

# Architecture

## One geometry source

You **must** follow a single data flow:

```text
Config (parameter object) → pure render → geometry IR → 2D canvas / 3D view / exported file
```

The 3D view **must** consume the same geometry IR as the 2D canvas and the exported file. Do **not** write a second geometry pipeline on the 3D side — the preview and the export will drift apart.

## Coordinate systems

Each rendering space uses the conventions below, and they **must** be documented in one place rather than rediscovered per file:

<table>
<thead>
  <tr>
    <th>
      Space
    </th>
    
    <th>
      Unit / origin / axes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      IR (canonical space)
    </td>
    
    <td>
      mm, centred at (0,0), Y down (2D — no Z)
    </td>
  </tr>
  
  <tr>
    <td>
      3D (three.js)
    </td>
    
    <td>
      mm, Y up, Z is thickness
    </td>
  </tr>
</tbody>
</table>

Outlines are built in the XY plane and extruded along +Z, so the part faces the camera. Flip IR to Y-up by mirroring, not rotating — set `group.scale.y = -1` once, on the content group; rotating it flat moves thickness onto another axis.

Two ways the flip goes wrong:

- **One part is upside-down and mirrored while everything around it is correct** — that mesh set `scale.y` itself. It already inherits the group's flip, so the second one cancels it.
- **Every face renders inside-out** — the flip was applied to the geometry (`geometry.scale(1, -1, 1)`). three.js compensates the winding order from `matrixWorld` at the object level only; there is no compensation at the geometry level.

## Path conversion

SVG paths for text and complex shapes **must** go through `new SVGLoader().parse()` and `SVGLoader.createShapes()` to become a `THREE.Shape` — that path applies the fill rule correctly, so holes and letter counters come out right — and then through `ExtrudeGeometry`. Do **not** write your own SVG path parser.

---

# Interaction

## Camera controls

When you use `OrbitControls`, you **must** configure all of the following:

- **Damping on**: `controls.enableDamping = true`, with `controls.update()` called every frame.
- **Clamped zoom**: set `minDistance` and `maxDistance`. 1.2×R to 8×R (R being the model's bounding radius) is the recommended range — it keeps the camera from entering the model or drifting out to nothing.
- **Clamped pitch**: set `maxPolarAngle` slightly under π (0.95π works), so the camera never tips under the model.
- **Opening shot**: about 3.2×R out, tilted slightly down — the whole model visible at the default angle, and reading as a solid.

## Wheel events

If you take over zoom yourself, you **must** attach a native non-passive listener:

```js
element.addEventListener('wheel', handler, { passive: false })
```

and call `preventDefault()` in the handler. Framework-level wheel bindings are usually passive and cannot stop the page's default scroll (React's `onWheel`, Vue's `@wheel` without a passive opt-out), so zooming inside the 3D area scrolls the whole page with it. The wheel handling built into `OrbitControls` already satisfies this.

## Ambient motion

- You **should** add an idle float: a Lissajous sway on frequencies that are not integer multiples of each other, so there is no perceptible loop point. Keep the amplitude slight.
- You **should** drive drag through an under-damped spring rather than mapping pointer travel 1:1 onto rotation. Aim for the behaviour, not a number: releasing produces **one visible overshoot and settles in roughly 0.3s**. (Stiffness 70 / damping 5.5 lands there in one particular per-frame integrator — the values only mean something alongside the formula you use, so tune to the behaviour.)
- Ambient-motion transforms **must** live on a persistent parent node (the rig) that geometry rebuilds never touch (see [Rebuild on change](/docs/3d-preview/rebuild)), so motion stays continuous while parameters change.
- Every animation **must** honour `prefers-reduced-motion` and switch off entirely when it is set.

## The frame loop

- Per-frame updates (motion, springs, `controls.update()`) **must** run in a rAF loop that mutates `Object3D` transforms directly. The UI framework re-renders only when Config changes; do **not** trigger framework state updates from the frame loop (React `setState`, Vue reactive assignment, Svelte store writes — all of them re-render 60 times a second and drop frames).
- Note that rAF pauses while the tab is hidden (`document.visibilityState === 'hidden'`), so every animated value freezes at its last frame. Anything that reads those values — an automated check, a debugging session — has to bring the tab to the foreground first, or it reads stale numbers and concludes the motion is broken.

## Text selection

The 3D stage container **must** set `user-select: none`, so drag-to-rotate does not select page text.

---

# Rebuild on change

## Rebuild strategy

- Geometry rebuilds triggered by a parameter change **must** be debounced (100–200ms), so dragging a slider does not rebuild per frame and drop the frame rate.
- A rebuild **must** be scoped to the content group's subtree. Camera position, OrbitControls state and the ambient-motion rig **must not** reset because a parameter changed.

## Disposing resources

Two different lifetimes — do **not** collapse them into one dispose function.

**On every rebuild**, release what *this build* created:

- every `geometry.dispose()`
- every `material.dispose()`, plus any texture created for this build

Skip this and GPU memory climbs the whole time someone is adjusting parameters, until the page locks up.

**On unmount only**, release what outlives a rebuild:

- the PMREM render target and the environment map
- textures shared across rebuilds — the procedural noise texture, a `CanvasTexture` shared with the 2D canvas (see [Render quality](/docs/3d-preview/rendering))
- `controls.dispose()` and `renderer.dispose()`

Neither list tolerates items from the other. Regenerating the environment map every rebuild costs a multi-pass PMREM render per debounce tick — more expensive than the leak you were avoiding. Disposing a shared texture every rebuild is worse: the next frame renders against a dead texture and the material goes blank.

Note that walking the content subtree and disposing every texture you find there hits both traps at once — a material *references* shared textures without owning them. **Dispose what you created, not what you referenced.**

## Sizing, DPR and zero-size mount

- `renderer.setPixelRatio()` **must** be clamped — `Math.min(window.devicePixelRatio, 2)`. Rendering at DPR 3 on a phone or a 5K display costs 2.25× the fragments of DPR 2 for no visible gain, and is the most common reason a preview that runs fine on the developer's machine drops frames on the user's.
- Reacting to a container resize means all three of `camera.aspect`, `camera.updateProjectionMatrix()` and `renderer.setSize()`. Miss `updateProjectionMatrix()` and the image stretches; miss `setSize()` and it renders at the old resolution.
- Your component can mount at 0×0 — inside a hidden tab or a collapsed panel. When ResizeObserver reports 0×0 you **must** ignore it and keep the current view state, then initialise or refit once a non-zero size arrives. That is what keeps the view intact across a tab switch.

---

# Render quality

## Lighting

- Image-based lighting **must** be configured; `AmbientLight` alone is **not** acceptable. The recommended setup is the built-in procedural interior — no asset files, no network request, nothing for CSP to block:```js
const pmrem = new THREE.PMREMGenerator(renderer)
const envRT = pmrem.fromScene(new RoomEnvironment()) // keep envRT — it is disposed on unmount, see Rebuild on change
scene.environment = envRT.texture
```
- Keep the environment dim (`scene.environmentIntensity ≈ 0.4` as a reference; a lower `envMapIntensity` on dark parts) to hold contrast, and add one soft directional light so the lighting has a direction.

## Tone mapping

ACES tone mapping **must** be enabled:

```js
renderer.toneMapping = THREE.ACESFilmicToneMapping
```

It makes a visible difference to how MeshStandardMaterial / MeshPhysicalMaterial read.

## Materials

- You **should** generate a procedural noise texture on a canvas and use it as both `map` and `bumpMap` — a cheap way to get a physical material read. Build it **once** and reuse it across rebuilds; [Rebuild on change](/docs/3d-preview/rebuild) covers when to dispose it.
- `ExtrudeGeometry` UVs are world coordinates in mm, so `texture.repeat` **must** be derived from physical size: pick how many mm one tile of the texture should span, and set `repeat = 1 / tile_mm` (a 45mm wood grain gives `1/45`). Hardcode a repeat count instead and the grain changes size whenever the part does.
- The procedural material SVG used by the 2D canvas can be rendered to a canvas and reused in 3D as a `CanvasTexture`, keeping 2D and 3D materials consistent. For the top face — assuming the model is centred on the origin, so world coordinates run from −R to +R — `repeat = 1/(2R)` and `offset = 0.5` map that span onto 0–1.
- You **should** split materials per face group, `[faceMat, sideMat]` (group 0 top and bottom, group 1 sides), with the sides a shade darker to read as solid.

## HDRI environment (optional)

For a more convincing environment, ship a small CC0-licensed 1k `.hdr` (around 1.5MB): run it through PMREM for `scene.environment`, use the raw equirect texture as `scene.background` with a moderate `backgroundBlurriness`, and fall back to RoomEnvironment as an instant placeholder while it loads.

Two things to watch for:

- A downward-tilted camera looks at the panorama's zenith or ground — the flattest part of it — and the background collapses into one blurred colour. Rotate the horizon behind the subject with `backgroundRotation` and `environmentRotation`, and start the camera at a shallower angle.
- Keep the background clearly darker than the subject, so the model's silhouette and its holes stay readable.

---

# Dependencies

- Pin your three.js version. Its API deprecates things continuously — known examples:

  - the `RoomEnvironment` constructor dropped its `renderer` argument around r150;
  - r180 deprecated `RGBELoader` in favour of `HDRLoader` (the old class still loads, but warns);
  - r185 deprecated `PCFSoftShadowMap`, which now silently falls back to `PCFShadowMap`;
  - colour-space and tone-mapping defaults have changed more than once.
- After a three.js upgrade you **must** check the browser console. **No deprecation warnings in the console** is an acceptance criterion.

---

# Common parts

Recipes to reach for when the shape calls for them:

<table>
<thead>
  <tr>
    <th>
      Part
    </th>
    
    <th>
      How to build it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Raised marks / lettering
    </td>
    
    <td>
      Reuse the cut part's outline path → <code>
        SVGLoader
      </code>
      
       → <code>
        ExtrudeGeometry
      </code>
      
      , and place it at <code>
        z = panel thickness
      </code>
      
      . Add it to the content group like everything else — it inherits the group's Y flip, so do <strong>
        not
      </strong>
      
       flip it again
    </td>
  </tr>
  
  <tr>
    <td>
      Thin rings / outlined parts
    </td>
    
    <td>
      Generate inner and outer outlines at <code>
        radius ± stroke/2
      </code>
      
       and extrude the thin ring; sample circles smoothly, flatten polygons
    </td>
  </tr>
  
  <tr>
    <td>
      Fold-up flaps
    </td>
    
    <td>
      Treat every open cut arc as one flap, with the hinge axis running between the arc's two endpoints (its chord). Extrude the flap and rotate it about that axis, in whichever direction lifts the flap's centroid toward +z. The base panel gets the matching hole punched out, while the uncut core stays solid. Cycle the fold angle through a small set of values so the result looks natural
    </td>
  </tr>
</tbody>
</table>

---

# Acceptance checklist

Work through this before you submit. Everything has to pass.

## Interaction

- [ ] OrbitControls damping is on; zoom distance and pitch are both clamped
- [ ] Opening shot is around 3.2×R, tilted slightly down, whole model on one screen
- [ ] The wheel inside the 3D area never scrolls or zooms the page
- [ ] Frame rate holds while a slider is dragged continuously (geometry rebuilds are debounced)
- [ ] Changing any parameter leaves the camera where it was and does not interrupt motion
- [ ] Drag springs back on release; idle has a slight float; `prefers-reduced-motion` disables all of it
- [ ] The 3D stage sets `user-select: none` — dragging never selects page text

## Correctness

- [ ] 3D geometry, the 2D canvas and the exported file all come from one IR (change any parameter and all three follow)
- [ ] The Y-down → Y-up flip happens once on the content group — not per mesh, not on the geometry. No mirrored text, no holes on the wrong side, no inside-out faces
- [ ] Every panel parameter has a visible effect in the 3D view, or is hidden for that mode with an explanation — a parameter that is visible but does nothing is not acceptable

## Performance and stability

- [ ] `setPixelRatio` is clamped (DPR ≤ 2)
- [ ] Five minutes of continuous parameter changes with flat GPU and JS memory (everything is disposed)
- [ ] Hide the tab and come back: the view is intact, not blank, nothing lost
- [ ] Mounting at 0×0 still initialises correctly once a real size arrives
- [ ] A container resize updates `camera.aspect`, `updateProjectionMatrix()` and `setSize()` together — the view refits without stretching

## Render quality

- [ ] Environment lighting is configured (RoomEnvironment or HDRI) with a directional light on top — not bare AmbientLight
- [ ] ACES tone mapping is on
- [ ] The environment map and any shared texture are built once and disposed on unmount only — not regenerated or disposed per rebuild
- [ ] Top and side materials are separate groups, sides a shade darker
- [ ] No three.js deprecation warnings in the browser console

---

# Export

Register the `export` lifecycle hook, and the platform will invoke your generator to retrieve the resulting file whenever the user clicks "Export" or "Open in Studio." The return value is always `{ filename, blob }`, and **any file format is supported** (images, SVG, 3D models, PDF, etc.).

## Placing the Export Button

You **place the export button yourself, inside your app**—add an element with the `data-atomm-export-button` attribute anywhere on the page, and the SDK will render it in place as a platform-controlled Export button (Download / Open in Studio + credit indicator). Clicks are always routed through the platform:

```html
<div data-atomm-export-button></div>
```

> **Two items, two different paths**
>
> Clicking it opens a dropdown with two items that behave differently. **Download** hands the files straight to the user with no dialog at all. **Open in Studio** opens an **export settings dialog** first: the user picks Download or Open in Studio, chooses machine / processing mode / material, and assigns a processing type to each SVG colour group (see [SVG Export Color Spec](/docs/export/svg-color-spec)). Your `export` hook still receives `intent`, fired once per tab, so returning different artefacts per action keeps working.

- Position and outer layout are entirely up to you (e.g., `position: fixed` to pin it to a corner); you can place multiple instances on one page, each hydrating independently.
- The button renders inside a Shadow DOM for style isolation; theming is done exclusively through the documented `--atomm-export-*` CSS variables (set them on the element itself or any ancestor—they're automatically inherited by the button):

```css
[data-atomm-export-button] {
  --atomm-export-bg: #d32f2f; /* Button background color */
  --atomm-export-radius: 0; /* Border radius */
  --atomm-export-width: 200px; /* Width: px, or 100% to fill the container */
  --atomm-export-height: 40px; /* Height */
}
```

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Controls
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --atomm-export-bg
      </code>
      
       / <code>
        -bg-hover
      </code>
      
       / <code>
        -bg-active
      </code>
    </td>
    
    <td>
      <code>
        #070b10
      </code>
      
       / <code>
        #252c36
      </code>
      
       / <code>
        #1c2129
      </code>
    </td>
    
    <td>
      Button background for the default / hover / active states
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-color
      </code>
    </td>
    
    <td>
      <code>
        #fff
      </code>
    </td>
    
    <td>
      Button text color
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-width
      </code>
    </td>
    
    <td>
      <code>
        auto
      </code>
      
       (fits content)
    </td>
    
    <td>
      Button width (<code>
        px
      </code>
      
      , or <code>
        100%
      </code>
      
       to fill the container; min 24px)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-height
      </code>
    </td>
    
    <td>
      <code>
        32px
      </code>
    </td>
    
    <td>
      Button height (<code>
        px
      </code>
      
       or <code>
        100%
      </code>
      
      ; min 24px)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-radius
      </code>
    </td>
    
    <td>
      <code>
        8px
      </code>
    </td>
    
    <td>
      Border radius
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-font
      </code>
      
       / <code>
        -font-size
      </code>
    </td>
    
    <td>
      <code>
        Inter, system-ui, sans-serif
      </code>
      
       / <code>
        14px
      </code>
    </td>
    
    <td>
      Font family / font size
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-menu-bg
      </code>
      
       / <code>
        -menu-color
      </code>
      
       / <code>
        -menu-hover-bg
      </code>
    </td>
    
    <td>
      <code>
        #fff
      </code>
      
       / <code>
        #111
      </code>
      
       / <code>
        #f4f4f5
      </code>
    </td>
    
    <td>
      Dropdown menu colors
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-menu-radius
      </code>
      
       / <code>
        -menu-shadow
      </code>
    </td>
    
    <td>
      <code>
        8px
      </code>
      
       / <code>
        0 4px 16px rgba(16,24,40,.12)
      </code>
    </td>
    
    <td>
      Menu border radius / shadow
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --atomm-export-z
      </code>
    </td>
    
    <td>
      <code>
        1000
      </code>
    </td>
    
    <td>
      Dropdown overlay z-index
    </td>
  </tr>
</tbody>
</table>

> Only the `--atomm-export-*` variables listed above are supported customization points; internal button class names may change at any time, so don't rely on them.

> **The export button only works inside the atomm environment (not a bug)**
>
> The export button—and its Download / Open in Studio / credit indicator—is driven by the atomm platform, and only works when your generator runs inside the atomm environment: the live platform, or the dev tool's local preview (`?local=`).
>
> If you open your generator standalone, outside atomm (e.g. opening the HTML directly), the button may still render, but clicking it won't produce a file and no billing status will show—this is by design, not a bug. Always verify export via local preview or the live platform.

### Free-Use Count / Credit Indicator on the Button

The button automatically displays the current billing status (pushed by the platform—no action needed on your part):

<table>
<thead>
  <tr>
    <th>
      State
    </th>
    
    <th>
      Display
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Free window
    </td>
    
    <td>
      <code>
        30s
      </code>
      
       countdown
    </td>
    
    <td>
      A short grace period granted after a successful export; exports within this window are free
    </td>
  </tr>
  
  <tr>
    <td>
      Free count
    </td>
    
    <td>
      <code>
        Free 3/3
      </code>
    </td>
    
    <td>
      Remaining / total free exports
    </td>
  </tr>
  
  <tr>
    <td>
      Credit cost
    </td>
    
    <td>
      Credit icon + number
    </td>
    
    <td>
      Credits consumed per export once free uses are exhausted
    </td>
  </tr>
</tbody>
</table>

> In local debugging (`?local=`), **clicking export never actually deducts credits**; refreshing the page resets it.

## Registering the export Hook

```js
atomm.lifecycle.on('export', async ({ intent }) => {
  // intent tells you whether the user clicked Download or Open in Studio; the handler reads the current generation result itself and produces a Blob
  const blob = await exportCurrentResultAsBlob()
  if (!blob) {
    throw new Error('请先生成作品后再下载')
  }

  return {
    filename: 'my-generator.glb', // Must include an extension; this determines the downloaded filename and the asset type used by Open in Studio
    blob, // A Blob of any format; MIME type comes from blob.type
  }
})
```

### The intent Argument: Telling Download from Open in Studio

Download and Open in Studio share this one hook. `intent` tells you which dropdown item the user picked, so you can return different output per action.
Each item triggers your hook once; return the same output for both if the distinction does not apply.

<table>
<thead>
  <tr>
    <th>
      intent
    </th>
    
    <th>
      When it fires
    </th>
    
    <th>
      What you typically return
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        'download'
      </code>
    </td>
    
    <td>
      The <strong>
        Download
      </strong>
      
       tab
    </td>
    
    <td>
      Every file the user should get on disk (the platform zips multiple files)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'openInStudio'
      </code>
    </td>
    
    <td>
      The <strong>
        Open in Studio
      </strong>
      
       tab
    </td>
    
    <td>
      Only what Studio should open, typically a single editable vector file
    </td>
  </tr>
</tbody>
</table>

> **Standalone bitmaps are wrapped into SVG for Studio**
>
> A processing type can only be written onto an SVG element as an attribute, and a standalone bitmap file has nowhere to carry one. So when the user picks **Open in Studio**, the platform wraps any standalone bitmap in your output (PNG / JPEG / WebP / GIF / BMP) in an SVG `<image>` — that is what lets it show up under the "Bitmap" group in the dialog, receive a processing type, and reach Studio with it.
>
> Physical size is decided like this: if the image carries a resolution (PNG `pHYs`, JPEG EXIF / JFIF, BMP pixels-per-metre) it is converted to millimetres from that; otherwise the SVG/CSS 96 PPI default is used. **If the size matters, write resolution metadata into the image you export.**
>
> **Download always delivers your bytes untouched** — no wrapping, no attributes. If you told the user you export a PNG, a PNG is what they get.

```js
atomm.lifecycle.on('export', async ({ intent }) => {
  // Open in Studio: the file will be edited further in Studio, so send one vector file
  if (intent === 'openInStudio') {
    return { filename: 'design.svg', blob: await buildSvg() }
  }

  // Download: send every file; the platform bundles them into a single zip
  return [
    { filename: 'cut.svg', blob: cutBlob },
    { filename: 'engrave.svg', blob: engraveBlob },
    { filename: 'score.svg', blob: scoreBlob },
    { filename: 'readme.txt', blob: readmeBlob },
  ]
})
```

> If the distinction doesn't apply to you, return the same thing for both; ignoring `intent` entirely (`async () => { ... }`) keeps working.

## Return Value Fields

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      filename
    </td>
    
    <td>
      string
    </td>
    
    <td>
      The downloaded filename; <strong>
        must include an extension
      </strong>
      
       (e.g., <code>
        design.glb
      </code>
      
      ) and must not contain path separators <code>
        /
      </code>
      
       <code>
        \
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      blob
    </td>
    
    <td>
      Blob
    </td>
    
    <td>
      File content of any format; <strong>
        each file must be ≤ 100MB
      </strong>
      
      ; MIME type comes from <code>
        blob.type
      </code>
      
      , falling back to the filename extension when empty
    </td>
  </tr>
</tbody>
</table>

## Multi-File Export (Optional)

The handler can also return an **array of files**, and the platform will bundle them into **a single zip download**:

```js
atomm.lifecycle.on('export', async () => [
  { filename: 'model.glb', blob: glbBlob },
  { filename: 'preview.png', blob: pngBlob },
])
```

<table>
<thead>
  <tr>
    <th>
      Rule
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      zip filename
    </td>
    
    <td>
      Derived from the base name of the <strong>
        first file
      </strong>
      
       in the array (<code>
        model.glb
      </code>
      
       → <code>
        model.zip
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Duplicate names
    </td>
    
    <td>
      Automatically deduplicated to <code>
        name (1).ext
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Size limit
    </td>
    
    <td>
      The <strong>
        combined size of all files must be ≤ 100MB
      </strong>
      
      ; exceeding this fails the entire export
    </td>
  </tr>
  
  <tr>
    <td>
      Array of length 1
    </td>
    
    <td>
      Downloads the file directly, without wrapping it in a zip
    </td>
  </tr>
  
  <tr>
    <td>
      Open in Studio
    </td>
    
    <td>
      <strong>
        Supports multiple files
      </strong>
      
      —all returned files are handed to Studio to open, with no format restriction; formats Studio doesn't support are flagged by Studio itself. <strong>
        Multi-file import requires xTool Studio 1.8+
      </strong>
      
      ; single-file export remains compatible with older versions
    </td>
  </tr>
</tbody>
</table>

> Single files still use `{ filename, blob }`; use an array for multiple files. If any item in the returned array is invalid (not a Blob, filename missing an extension, etc.), the entire result is considered invalid.

## Getting a Blob

Almost any export source can be converted to a Blob in a single line:

<table>
<thead>
  <tr>
    <th>
      What you have
    </th>
    
    <th>
      Convert to Blob
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Canvas (2D drawing)
    </td>
    
    <td>
      <code>
        canvas.toBlob(cb, 'image/png')
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      SVG string / text / JSON
    </td>
    
    <td>
      <code>
        new Blob([str], { type: 'image/svg+xml' })
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      ArrayBuffer / 3D mesh (glb/stl, etc.)
    </td>
    
    <td>
      <code>
        new Blob([buffer], { type: 'model/gltf-binary' })
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Existing data URL / remote URL
    </td>
    
    <td>
      <code>
        await (await fetch(x)).blob()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      File from <code>
        <input type=file>
      </code>
    </td>
    
    <td>
      Use it directly (a File is already a Blob)
    </td>
  </tr>
</tbody>
</table>

> **The return value is always { filename, blob }**
>
> Export data is always carried as a **Blob**, so any format is supported — a Blob preserves the binary content of any file type.
>
> `filename` must include an extension and must not contain path separators; if a file exceeds 100MB or the return value isn't a valid `{ filename, blob }`, the platform treats it as invalid, the export fails, and the user is notified.

> **Open in Studio's format support is determined by Studio**
>
> Downloads support saving any format to disk. "Open in Studio" hands the file off to xTool Studio to open—the platform makes no assumptions about format, and Studio itself will flag any format it doesn't support.

> **Not registering the hook will cause review rejection**
>
> The export button is available to every generator (it appears as soon as you add `data-atomm-export-button` to your app). If a user clicks export and you haven't registered the `export` hook, the platform receives "the app provides no download method"—and your submission will be rejected in review as a result. Any generator that supports export must register this hook; you can test it locally by clicking "Export" in the preview to confirm a file is produced correctly.

---

# SVG Export Color Spec

The platform reads processing intent from colour: **stroke cuts in #FE0002, stroke engravings in #2366FF, fill engravings in #2366FF.** Every other colour still exports — the user just assigns its processing type by hand.

Your colours are **read, never rewritten**: colour is only used to identify, and the only thing written into the file is the processing type, `data-processing-type`.

## Two colours, five groups

<table>
<thead>
  <tr>
    <th>
      Group
    </th>
    
    <th>
      How to draw it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Red line
    </td>
    
    <td>
      <code>
        stroke=
      </code>
      
       <color-swatch value="#FE0002">
        
      </color-swatch>
    </td>
  </tr>
  
  <tr>
    <td>
      Blue line
    </td>
    
    <td>
      <code>
        stroke=
      </code>
      
       <color-swatch value="#2366FF">
        
      </color-swatch>
    </td>
  </tr>
  
  <tr>
    <td>
      Fill vector
    </td>
    
    <td>
      <code>
        fill=
      </code>
      
       <color-swatch value="#2366FF">
        
      </color-swatch>
    </td>
  </tr>
  
  <tr>
    <td>
      Bitmap
    </td>
    
    <td>
      <code>
        <image>
      </code>
      
       elements, colour-independent
    </td>
  </tr>
  
  <tr>
    <td>
      Other vector
    </td>
    
    <td>
      every other visible vector, split into one row per colour
    </td>
  </tr>
</tbody>
</table>

However many elements a group holds, it takes one row and the user configures it once. This is the dialog they get after picking Open in Studio from the dropdown (Download saves straight to disk with no dialog).

Machine, processing mode and material sit at the top; together they decide which processing types this machine supports. The dropdown on the right of each row is that group's processing type.

## A complete example

Your `export` hook returns an SVG like this:

```xml
<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100">
  <rect x="4" y="4" width="192" height="92" fill="none" stroke="#FE0002"/>
  <path d="M20 30h160" fill="none" stroke="#2366FF"/>
  <circle cx="100" cy="65" r="20" fill="#2366FF"/>
</svg>
```

It only uses the first three groups, so the dialog shows three rows — Red line, Blue line and Fill vector, one element each. The user picks a processing type for each, and on confirm your file becomes:

```xml
<rect   … stroke="#FE0002" data-processing-type="VECTOR_CUTTING"/>
<path   … stroke="#2366FF" data-processing-type="VECTOR_ENGRAVING"/>
<circle … fill="#2366FF"   data-processing-type="FILL_VECTOR_ENGRAVING"/>
```

The attribute goes on each element that is actually processed, never on a `<g>` to be inherited. The file carries the processing type and nothing else — no power, speed or similar parameters. Studio applies the recommended parameters for whichever material the user picked in the dialog.

That is everything you need to make export work. The three sections below are detail — reach for them when an export does not come out the way you expected.

## The colour was not recognised

First check the notation is one the platform reads. Each element resolves in the order **inline style → <style> rule → element attribute**, and only inherits from its parent when all three are absent. That order follows SVG 2: a presentation attribute has specificity 0, so any CSS rule beats it.

Every one of these is recognised as a cut line:

```xml
<path stroke="#FE0002" fill="none"/>
<path stroke="#fe0002" fill="none"/>
<path style="stroke:#FE0002" fill="none"/>
<g stroke="rgb(254, 0, 2)" fill="none"><path/></g>

<style>.st0{fill:none;stroke:#FE0002}</style>
<path class="st0"/>

<defs><style><![CDATA[.str0{stroke:#FE0002;fill:none}]]></style></defs>
<path class="str0"/>
```

`<style>` works anywhere in the document — inside `<defs>`, or even after the elements it styles. CDATA wrapping is supported, as are class / id / type / attribute / descendant selectors and comma-grouped lists, ordered by specificity then document order. The one exception is `!important`, which does not participate: an inline value always wins.

Only these colour notations are parsed: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`, and numeric `rgb()` / `rgba()`. Alpha is ignored when matching, so `#FE0002FF`, `#FE000280` and `rgba(254,0,2,.5)` all group as `#FE0002` — a translucent red is still a cut line.

**Colour cannot be read** in four cases:

- external stylesheets (`<link>` / `@import`)
- declarations inside conditional rules such as `@media`
- CSS variables and `currentColor`
- unrecognised notations: named colours, `hsl()`, percentage `rgb()`

Those elements are not lost. They land in "Other vector", and the user assigns the processing type themselves.

## The groups do not match what you drew

**"Other vector" splits by colour.** Off-spec colours are not lumped together — each distinct colour gets its own row, which is where the green and purple rows at the bottom of the dialog above come from:

- the grouping colour takes **stroke over fill**
- the same colour written differently (`#22C55E` / `rgb(34,197,94)`) stays one row
- the same colour across several SVG files merges into one row
- every row's processing type is **empty by default** — the platform never guesses
- order: the four spec groups first, then other-vector rows by element count, most first

**A shape that is both blue-filled and red-stroked is split in two.** `fill="#2366FF"` plus `stroke="#FE0002"` expresses two operations — fill-engrave the interior, cut the outline — but the protocol allows only one processing type per element:

```xml
<!-- what you exported -->
<rect fill="#2366FF" stroke="#FE0002"/>

<!-- after the platform processes it -->
<rect fill="#2366FF" stroke="none" data-processing-type="FILL_VECTOR_ENGRAVING"/>
<rect fill="none"    stroke="#FE0002" data-processing-type="VECTOR_CUTTING"/>
```

The fill copy is inserted **before** the stroke copy, preserving the original fill-then-stroke paint order, so nothing looks different. The copy carries no `id`, and `marker-*` stays on the stroke copy only. The shape appears in both groups, so the element counts add up to more than you drew.

The split only happens when both sides are spec colours. A red stroke on a green fill is not split — green expresses no processing intent, so the whole shape groups as a cut line by its stroke.

## The shape did not appear at all

**Elements that participate**: `path` `rect` `circle` `ellipse` `line` `polyline` `polygon` `text`, plus `image` for bitmaps.

**Elements that do not**:

- shapes inside `<defs>` `<clipPath>` `<mask>` `<marker>` `<pattern>` `<symbol>` — they are definitions, nothing is painted
- elements with `display: none` or `visibility: hidden`, whether written as an attribute, an inline style, or a `<style>` rule
- elements with both `fill="none"` and `stroke="none"`

**<use> is the easiest trap to fall into.** The shape it draws never appears in any group, so it never receives a processing type: `<use>` itself is not a vector shape, and a referenced original sitting inside `<defs>` / `<symbol>` does not count either. If the whole drawing is assembled from `<use>`, the dialog shows no rows at all.

The sneakier case is a referenced original that is itself painted. With `<path id="p" …/>` plus `<use href="#p" x="20"/>`, the original groups normally and gets a processing type while the copy drawn by `<use>` gets none — one shape is cut, its duplicate is not. Emit the real shapes instead.

**Multi-file exports**: identical groups merge across files and an unparsable SVG is skipped on its own. With Open in Studio, standalone bitmap files (PNG / JPEG / WebP / GIF / BMP) are wrapped into an SVG `<image>`, so they show up under the "Bitmap" group too; anything else passes through untouched. Download always delivers your bytes as-is — no wrapping, no attributes. When no group can be produced at all — no SVG, or SVGs made entirely of the elements above — the dialog hides the "Processing type" section.

---

# Submit for Review & Publish

Once you've integrated the platform capabilities and verified everything in local preview, you're ready to publish from the Developer Console. There's no local packaging tool needed anymore — just produce static files using your own build process.

## 1. Prepare the Artifact

Build a static Web bundle that's ready to deploy (with the platform SDK already included in the page), then package it into a single `.zip` file (50 MB max).

> **Before packaging, confirm the artifact still includes the SDK**
>
> Your app depends on the `platform-sdk.js` script tag in the page to connect to platform capabilities in production. Some build configurations can cause the production entry page to drop this script, which results in "works fine in local preview, but export stops working after publishing." Before uploading, make sure the entry page in your production artifact is the same one you verified locally — and that it still includes the SDK.

## 2. Create the Application

Click "Create Application" in the Developer Console, and give your generator a name to serve as its **runtime identifier** (must start with a lowercase letter, and contain only lowercase letters, digits, and hyphens). This name is tied to the production subdomain and access path, and **cannot be changed after creation** — choose carefully. The card title shown to users is configured separately in the next step.

## 3. Configure Listing Details

Go to "Application List Details" on the app detail page, and fill in the card title, short description, and cover image. A live preview of the app card is shown on the right. This information determines how users see your app on the Creative Tools page, and **any changes here also require review**.

The preview has two channels: Atomm shows a 4:3 card, Studio shows a 1:1 square slot. **You only upload the 4:3 cover** — the square slot is centre-cropped from it automatically. Switch to the Studio tab to see the crop, and keep your subject away from the edges so nothing important gets cut.

## 4. Upload the Code Artifact

Switch to "Code Artifact" and upload your packaged `.zip` (containing `index.html` and other static files). For live local debugging during development, use the online DevTool — see [Local Debugging](/docs/devtool) for details.

## 5. Submit for Review

In "Submit for Review," the platform checks that both the listing details and the code artifact are complete. Once everything is ready, click "Submit for Review" — the listing changes and the new artifact are bundled into a single "pending change" and submitted together. The review result (approved / rejected, with reasons) is sent back to your console via a message.

> **No resubmission while under review**
>
> Once submitted, the application enters "Under Review." You'll need to wait for the result before submitting new changes.

> **Automatically published once approved**
>
> Once approved, the application is published automatically, and its runtime URL becomes `https://www.atomm.com/creativetools/community/generator/<生成器名称>` — users can open it directly from the generator gallery.

---

# FAQ

## Do I need to install a command-line tool?

No. Integration only requires adding a single line to import `platform-sdk.js` into your page. For debugging, just open the online DevTool in your browser and load your local service.

## Which tech stacks are supported?

Any of them. Plain HTML, Vite, Vue, React — anything that ultimately produces deployable static web files will work.

## What address should my local service use? Why won't my address load?

Preview loads your local service via `?local=` (only loopback addresses such as localhost / 127.0.0.1 are supported). `www.atomm.com` runs over https, and browsers only allow http for `localhost`; http addresses other than `localhost` are blocked by the mixed-content policy. Use `localhost`, or enable https for your local service.

## Platform capabilities aren't available, or the panel shows "Integration incomplete" — what should I do?

This means the page failed to load `platform-sdk.js`. Check that the script is included correctly and that your local service is reachable, then reload the page. Once the SDK handshake succeeds, the message will clear automatically.

## Can the generator name (runtime identifier) be changed?

No. The name becomes part of the runtime subdomain and access path and is tied to your live URL. It cannot be changed after creation, so choose it carefully.

## What happens if I don't integrate export functionality?

The export button is available to every generator (it appears wherever you place `data-atomm-export-button` in your app). If you haven't registered the `export` hook, users who click export will get "The app does not provide a download method," and this will get your submission rejected during review. To support export, you must register the export hook — you can test it in local preview by clicking "Export" to confirm it produces a file correctly.

---

# LLMs.txt

Let Claude Code, Cursor, Copilot and the like read the atomm platform's APIs and requirements themselves, instead of you relaying them a paragraph at a time.

[llms.txt](https://llmstxt.org) is a convention for documentation written to be read by large language models. This site serves two routes:

<table>
<thead>
  <tr>
    <th>
      Route
    </th>
    
    <th>
      What it holds
    </th>
    
    <th>
      Size
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="/llms.txt">
        /llms.txt
      </a>
    </td>
    
    <td>
      An index of every doc, with links
    </td>
    
    <td>
      ~750 tokens
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/llms-full.txt">
        /llms-full.txt
      </a>
    </td>
    
    <td>
      Every English doc concatenated into one file
    </td>
    
    <td>
      ~30k tokens
    </td>
  </tr>
</tbody>
</table>

Append `.md` to any docs URL to get that page as plain markdown — `https://dev.atomm.com/docs/quickstart.md` or `https://dev.atomm.com/zh/docs/quickstart.md`.

## Which one to hand over

- **Your agent can fetch URLs**: give it `/llms.txt` and let it pull only the pages it needs. Cheapest on context.
- **You want everything at once**: give it `/llms-full.txt`. Saves twenty-odd round trips, costs ~30k tokens of context.
- **You only care about one chapter**: give it that page's `.md` URL.

## Usage

Paste the URL into the conversation:

For example: read `https://dev.atomm.com/llms.txt` first, then wire up the export flow in this generator the way atomm requires.

The design system and the 3D preview requirements also ship as single files you can hand straight to an agent — see [Skills](/docs/ai/skills).

---

# Skills

A skill is a single-file spec written for a coding agent: no background, just what to build and what gets rejected at review. Hand the file over and the agent works from it — you don't have to restate the requirements in chat.

Two are published here, both downloadable:

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      What it covers
    </th>
    
    <th>
      When to hand it over
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="/design.md">
        design.md
      </a>
    </td>
    
    <td>
      The design system: semantic tokens, type, radii and spacing, component baselines, plus a contract and a self-check for agents. DESIGN.md format
    </td>
    
    <td>
      Whenever an agent writes generator UI
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/3d-preview-skill.md">
        3d-preview-skill.md
      </a>
    </td>
    
    <td>
      three.js 3D preview: architecture, interaction, render quality, acceptance checklist
    </td>
    
    <td>
      When the generator ships a 3D preview
    </td>
  </tr>
</tbody>
</table>

Both are also one click away from the top right of their own sections ([Design](/docs/design/overview), [3D Preview](/docs/3d-preview/overview)).

**design.md has to reach the agent together with the code it describes.** It carries the templates' full addresses and one hard rule: fetch the matching template before writing any markup. How you hand it over depends on whether your agent can fetch a URL.

- **It can fetch.** Give it `design.md` alone — `https://dev.atomm.com/design.md`. It reads the decision table on [Layout](/docs/design/layout), fetches the skeleton it needs (swapping in the layout it picked — for example `https://dev.atomm.com/templates/layout-3-generate.skeleton.html`) and builds on that file.
- **It cannot fetch.** Paste in `design.md` *and* the one **skeleton** that matches your layout. Without the template the agent is required to stop and ask you for it rather than invent one — the difference between a slow answer and a wrong one.

Either way the project ends up with two files:

```text
your-project/
├── design.md                      # the spec — the agent reads this first
└── index.html                     # a copy of the skeleton for your layout
                                   #   <style>  tokens + component classes — don't rewrite them
                                   #   match the structure and the class names; the logic is yours
```

**Fetch one template, not all five.** They share the same stylesheet, and it is most of every skeleton by weight — so fetching them all costs context and adds nothing. Pick your base with the decision table on [Layout](/docs/design/layout); if you later need a block only another layout has, fetch that one then.

Don't hand over a design-file link or screenshots instead. A screenshot carries the look but none of the numbers, so the agent guesses every colour, size and spacing — differently each time. The templates have the numbers.

## Handing it to Claude Code

Save it as `SKILL.md` under your project's skills directory and the agent loads it on its own when the task calls for it:

```text
.claude/skills/atomm-3d-preview/SKILL.md
```

The 3D preview file already downloads as `SKILL.md` — create the directory and drop it in.

## Handing it to other tools

Cursor, Copilot and friends: keep the file in the repo (say `docs/atomm-3d-preview.md`) and `@`-reference it in chat. For a one-off, pasting the whole file into the conversation works too.

## How this differs from LLMs.txt

- [LLMs.txt](/docs/ai/llms-txt) indexes the whole documentation set. It fixes "the agent doesn't know what atomm can do."
- A skill is the spec for one job. It fixes "the agent knows, but what it built won't pass review."

Building a 3D preview? Hand over both: llms.txt to learn the platform, the skill to get the details right.

---

# Overview

The design system is two things, handed to a coding agent together:

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      What it is
    </th>
    
    <th>
      How to use it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="/design.md">
        design.md
      </a>
    </td>
    
    <td>
      The spec as a single DESIGN.md-format file: tokens, component specs, design intent, a contract for agents at the top and a self-check at the end
    </td>
    
    <td>
      Put it in the project and have the agent read it first
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="/docs/design/layout">
        Five layout templates
      </a>
    </td>
    
    <td>
      One per generator layout, each in two HTML files: a <strong>
        skeleton
      </strong>
      
       (structure + stylesheet) and a <strong>
        runnable
      </strong>
      
       one (behaviour inlined as well)
    </td>
    
    <td>
      Read the skeleton and copy it into your project; take the runnable one to see the example work
    </td>
  </tr>
</tbody>
</table>

**The pages below are written for people** — the same tokens and components, with demos you can touch. Changes happen in one place: `design.md` is the single source of truth, and the docs pages and templates follow it.

## Why templates, not descriptions

There used to be a written spec only. The same file handed to different agents produced good UI one day and poor UI the next, because every agent was **rebuilding** the 28px input, the property-card header row and the select's keyboard contract from prose, and rebuilding always varies. The agent's job is now **reuse**: the template already has the right skeleton, components and behaviour, so the work left is content and whatever your generator adds on top. That is what makes the output steady.

A template is deliberately **one file**: no second stylesheet or script to copy alongside it, no relative path to get right, and double-clicking it runs it in a browser.

## Skeleton, skin and behaviour

The spec has three layers, and the contract section of `design.md` keeps them apart:

- **Skeleton — must match**: the five layouts and their region widths, where the tabs / Fabrication Tips / zoom / export sit, control heights (24 / 28 / 32 / 40), radii (4 / 6 / 8 / 12), the closed state set, the keyboard and screen-reader contract each control owes, and every [platform constraint](/docs/design/platform). All of it is judged on what renders — the framework, the tags and the class names are yours.
- **Skin — default, replaceable**: every colour value and the type sizes. The values shipped here come from the platform's own token export, so they match its surfaces; you may bring your own neutrals and accent as long as the result stays light, text that carries meaning clears 4.5:1, every control state stays distinct, and you **change token values, never token names**.
- **Behaviour — yours**: what the generator actually makes, which parameters it exposes, what Generate produces, how far zoom goes, what the history holds — none of it is specified. The runnable templates answer these one way so the example runs; treat those answers as a demo, not a requirement.

Review checks two things: the **skeleton** — the layouts, widths, control sizes and behaviour listed above — and the **platform constraints**: export goes through the platform button, the generator uses only the region it is given, the exported file is 1:1 actual size. The skin is advice.

## A workbench, not a storefront

The reference for a generator is the properties panel of a professional creative tool: quiet chrome, dense enough to work in, never decorated. Whoever is using it will run the same generator twenty times in an afternoon, changing one value each time. At that repetition rate the value of the interface is its **predictability**: controls stay in the same place, values stay legible, and the twentieth transition looks exactly like the first.

```html
<div class="spec-body on-canvas" style="display:grid;place-items:center"><div class="panel-demo"><div class="prop-card"><button type="button" class="prop-card-header" aria-expanded="true">Size<svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="prop-card-body"><div class="field-row"><label>Width</label><span class="input-number"><input value="200" readonly><span class="unit">mm</span></span></div><div class="field-row"><label>Columns</label><span class="input-number"><input value="6" readonly></span></div><div class="field-row"><label>Randomness</label><div class="control"><input class="slider" type="range" min="0" max="100" value="35" data-unit="%"><span class="value">35%</span></div></div></div></div><div class="prop-card"><button type="button" class="prop-card-header" aria-expanded="true">Style<svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="prop-card-body"><div class="field-row"><span class="field-label" id="d-shape">Shape</span><span class="select-wrap"><button type="button" class="select" role="combobox" aria-haspopup="listbox" aria-expanded="false" aria-labelledby="d-shape"><span>Circle</span><svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="select-list" role="listbox" aria-labelledby="d-shape" hidden><div class="select-option" role="option" aria-selected="true">Circle<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Square<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Hexagon<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Star<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div></div></span></div><div class="field-row"><label>Show ticks</label><span class="switch"><input type="checkbox" checked><span class="track" aria-hidden="true"></span><span class="knob" aria-hidden="true"></span></span></div></div></div></div></div>
```

**A real slice of the parameters rail**: white property cards standing on a `bg-subtlest` panel, header rows at 12 / 500, field rows at 12 / 400, grey-filled borderless 28px inputs aligned to the end edge. Click a header to collapse the card, drag the slider and the value follows — the spec describes controls in every state, and you only really understand a state you can touch.

What it is not: not a marketing page, not a dashboard, not a consumer app. No hero moment, no gradients, no glass, no glow, no illustrated empty state, no entrance animation. Those belong to products that still have to convince you to stay. This one already has your attention.

---

# Platform constraints

This chapter is not a matter of style — these are the conditions of running inside atomm. Review checks the skeleton and this chapter: ignore the skin and you can still publish; ignore this chapter and the submission fails review.

**Export must go through the platform button.** Place `<div data-atomm-export-button></div>` in the export slot and register an `atomm.lifecycle.on('export', …)` hook. A submission with no export hook is rejected automatically.

The slot is where the templates put it: the footer of the parameters rail, or the canvas's bottom-end corner when there is no rail. The SDK renders the button, and you theme it only through the documented `--atomm-export-*` variables — the templates set width 100%, height 32px, radius 6px and the brand colours, which is exactly the `button-primary` shape. During development you may render a fallback button inside the slot; the SDK takes precedence when present. See [Export](/docs/export).

```html
<div class="spec-body on-canvas" style="display:grid;place-items:center"><div class="panel-demo"><div class="note">…property cards…</div><div style="margin-top:auto"><button type="button" class="btn btn-primary btn-block">Export</button></div></div></div>
```

A full-width 32px button inside the rail footer's 16px padding. It does not move while content scrolls, so nobody ever has to go looking for it.

**Treat the exported file as machine-facing.** 1:1 real dimensions, `mm` units, a viewBox in mm coordinates. Cut-line colours are mapped to machine processes by the device and do not follow the interface palette; see the [SVG export colour spec](/docs/export/svg-color-spec). Reference images used for preview never enter the drawing.

**The top bar belongs to the platform** — brand, account, credits. Do not rebuild it, do not imitate it, do not add a second one. Your own controls (project name, save, history) go in the header of your lead rail.

**You render inside the region the platform allocates.** You cannot cover the platform chrome, you do not know the viewport, and the stacking context is entirely yours: one overlay layer plus one for toasts is enough, and `z-index` caps at 3.

---

# Layout

Generators combine two questions — **what goes on the canvas** (left) and **what does it look like** (right) — into one of five layouts. The platform's own generators cover all five; yours starts from the template closest to it.

## The five templates

<table>
<thead>
  <tr>
    <th>
      #
    </th>
    
    <th>
      Template
    </th>
    
    <th>
      Left
    </th>
    
    <th>
      Right
    </th>
    
    <th>
      Use it when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      1
    </td>
    
    <td>
      <a href="/templates/layout-1-params.html">
        layout-1-params.html
      </a>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      320 params
    </td>
    
    <td>
      Nothing to pick or generate; the user only adjusts values
    </td>
  </tr>
  
  <tr>
    <td>
      2
    </td>
    
    <td>
      <a href="/templates/layout-2-templates.html">
        layout-2-templates.html
      </a>
    </td>
    
    <td>
      320 templates
    </td>
    
    <td>
      320 params
    </td>
    
    <td>
      One left-side job: browse and pick a template
    </td>
  </tr>
  
  <tr>
    <td>
      3
    </td>
    
    <td>
      <a href="/templates/layout-3-generate.html">
        layout-3-generate.html
      </a>
    </td>
    
    <td>
      320 generate, docked
    </td>
    
    <td>
      320 params
    </td>
    
    <td>
      Start from an input (prompt, style, image), then tune
    </td>
  </tr>
  
  <tr>
    <td>
      4
    </td>
    
    <td>
      <a href="/templates/layout-4-floating.html">
        layout-4-floating.html
      </a>
    </td>
    
    <td>
      360 generate, floating
    </td>
    
    <td>
      none
    </td>
    
    <td>
      Pick a style, set the run up in a dialog, nothing to tune afterwards
    </td>
  </tr>
  
  <tr>
    <td>
      5
    </td>
    
    <td>
      <a href="/templates/layout-5-multi.html">
        layout-5-multi.html
      </a>
    </td>
    
    <td>
      64 tools + 320 panel
    </td>
    
    <td>
      320 params
    </td>
    
    <td>
      Several left-side jobs: generate, templates, import
    </td>
  </tr>
</tbody>
</table>

If you cannot decide between 3 and 4, there is one question: is anything adjusted *after* generating? If yes, 3. If the result is final, 4.

```html
<div class="lmap-grid"><div class="lmap"><div class="lmap-box"><i class="r" style="width:28%"></i><b></b></div><b class="on">1</b> No left rail + params</div><div class="lmap"><div class="lmap-box"><i style="width:28%"></i><i class="r" style="width:28%"></i><b></b></div><b class="on">2</b> Templates 320 + params</div><div class="lmap"><div class="lmap-box"><i style="width:28%"></i><i class="r" style="width:28%"></i><b></b></div><b class="on">3</b> Generate 320 docked + params</div><div class="lmap"><div class="lmap-box"><i class="f"></i><b></b></div><b class="on">4</b> Generate 360 floating, no params</div><div class="lmap"><div class="lmap-box"><i style="width:6%"></i><i style="width:28%"></i><i class="r" style="width:28%"></i><b></b></div><b class="on">5</b> Tools 64 + panel 320 + params</div></div>
```

Five combinations, one skeleton: something to pick or generate on the left, the result in the middle, what to adjust on the right, and export (the dark block) always bottom-right.

Each template comes in two forms. The **skeleton** (`<layout>.skeleton.html`) is the structure plus the full stylesheet with the script block removed — read this one when you write markup, because nothing in it competes with the layout and the tokens for attention. The **runnable** form (the same URL without `.skeleton`) has the behaviour inlined as well, for seeing the example work; what its controls do is a demo, not the spec. Both are a single HTML file with no second file to copy alongside.

Every control in it works — reset, the unit toggle, drag-to-change on numeric fields, zoom, the select, collapse, the Fabrication Tips walkthrough, the second-level views. The export button is the one stand-in: it says what the platform would do. Try them below, then download one and drop it into your project.

- [layout-1-params.html](https://dev.atomm.com/templates/layout-1-params.html)
- [layout-2-templates.html](https://dev.atomm.com/templates/layout-2-templates.html)
- [layout-3-generate.html](https://dev.atomm.com/templates/layout-3-generate.html)
- [layout-4-floating.html](https://dev.atomm.com/templates/layout-4-floating.html)
- [layout-5-multi.html](https://dev.atomm.com/templates/layout-5-multi.html)
## Regions

<table>
<thead>
  <tr>
    <th>
      Region
    </th>
    
    <th>
      Width
    </th>
    
    <th>
      What is in it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Platform top bar
    </td>
    
    <td>
      64
    </td>
    
    <td>
      The platform draws it — never add a second one
    </td>
  </tr>
  
  <tr>
    <td>
      Tool rail
    </td>
    
    <td>
      64
    </td>
    
    <td>
      Layout 5 only: one icon per left-side panel
    </td>
  </tr>
  
  <tr>
    <td>
      Left rail
    </td>
    
    <td>
      320, or 360 when floating
    </td>
    
    <td>
      What there is to add or to generate: templates, styles, a prompt, an import
    </td>
  </tr>
  
  <tr>
    <td>
      Canvas
    </td>
    
    <td>
      everything the rails leave
    </td>
    
    <td>
      The preview, plus four overlays: view tabs, Fabrication Tips, zoom, and export when there is no parameters rail
    </td>
  </tr>
  
  <tr>
    <td>
      Parameters rail
    </td>
    
    <td>
      320
    </td>
    
    <td>
      The stack of property cards, with export pinned at the bottom
    </td>
  </tr>
</tbody>
</table>

Rails are **fixed width**. The canvas absorbs every resize: when the window gets wider, the parameters rail does not.

Docked regions have no gap and no radius between them — a docked rail meets the canvas at a single 1px `stroke-default` line. The floating rail is the one exception: a white card, 12px radius, `shadow-100`, inset 16px from the canvas's top, start and bottom edges.

**Left rails collapse** to a 40px pill in the canvas's top-start corner (rail title plus the panel icon), and the canvas grows. In layout 5 the panel collapses by clicking the already-selected tool.

**The parameters rail** is always 320px and always the same three bands:

- **Header row** — unit toggle at the start, Reset at the end
- **Middle** — a scrolling stack of property cards
- **Footer** — the export button, pinned so nobody has to scroll to find it

Derived results (usage, part count, duration) are annotations on the canvas, or one card at the bottom of the stack. They never get a column of their own.

## The four corners of the canvas

The canvas carries four overlays and nothing else: view tabs at the top centre, the Fabrication Tips capsule at the top end, the zoom cluster at the bottom start. The fourth is export, and it appears at the bottom end only when there is no parameters rail. Overlays do not move on hover.

Zoom is a **free value**, not a set of steps: the wheel and a two-finger pinch scale the canvas continuously and anchor on the pointer, dragging the canvas pans it, the readout is a menu button whose menu lists a few levels as shortcuts, and fit measures the canvas and re-centres. Which levels the menu lists, and how far the range goes, is yours to decide.

A lead rail can hold a **second level**: "View all" on a section, or the history row at the rail's foot, replaces the rail's content with a back row and a three-column grid of 90px tiles. The canvas does not change and no dialog opens; Back is the only way out.

```html
<div class="canvas-demo"><div style="position:absolute;inset-block-start:12px;inset-inline:12px;display:flex;justify-content:center"><div class="segmented segmented-tabs" role="group" aria-label="View"><button type="button" aria-pressed="true">2D design</button><button type="button" aria-pressed="false">3D preview</button><button type="button" aria-pressed="false">Export</button></div><button type="button" class="btn-tips" style="position:absolute;inset-inline-end:0;inset-block-start:0"><svg class="icon icon-20" viewBox="0 0 20 20" aria-hidden="true"><path d="M7.5 15.5h5M8.5 17.8h3M10 2.2a5 5 0 0 1 3 9c-.6.5-.9 1.1-.9 1.8H7.9c0-.7-.3-1.3-.9-1.8a5 5 0 0 1 3-9Z"></path></svg>Tips</button></div><div style="position:absolute;inset-block-end:12px;inset-inline-start:12px" class="zoom-cluster"><button type="button" aria-label="Zoom out"><svg class="icon" viewBox="0 0 16 16"><path d="M4 8h8"></path></svg></button><button type="button" aria-haspopup="true" aria-expanded="false" data-zoom-trigger>100%</button><button type="button" aria-label="Zoom in"><svg class="icon" viewBox="0 0 16 16"><path d="M8 4v8M4 8h8"></path></svg></button><button type="button" aria-label="Fit to canvas"><svg class="icon" viewBox="0 0 16 16"><path d="M2 6V2h4M10 2h4v4M14 10v4h-4M6 14H2v-4"></path></svg><span class="tooltip" aria-hidden="true">Fit to canvas</span></button></div><div class="select-list zoom-menu" role="menu" aria-label="Zoom level" hidden style="position:absolute;inset-block-end:48px;inset-inline-start:48px"><button type="button" class="select-option" role="menuitem">50%</button><button type="button" class="select-option" role="menuitem">75%</button><button type="button" class="select-option" role="menuitem">100%</button><button type="button" class="select-option" role="menuitem">200%</button><button type="button" class="select-option" role="menuitem">400%</button></div><div style="position:absolute;inset-block-end:12px;inset-inline-end:12px;width:140px"><button type="button" class="btn btn-primary btn-block">Export</button></div></div>
```

The view switch is a **segmented control**, not a tab strip: two or three mutually exclusive views (2D design / 3D preview / Export). More than three means the canvas is carrying too much. The capsule at the top end opens the Fabrication Tips walkthrough and nothing else.

## Property cards

Parameters are grouped **by object or by function** into property cards: white, `stroke-divider` border, an 8px radius on all four corners and `shadow-100`, stacked 12px apart on the `bg-subtlest` panel. A card is a header row plus the field rows under it. The header row is one `<button aria-expanded>` across the full width, title at the start and disclosure chevron at the end. The card itself is a `<section>` pointed at that header with `aria-labelledby`.

Cards with few parameters stay open; cards with many may start collapsed. Collapsing changes two things and nothing else: `hidden` on the body, and the chevron's rotation. No height animation.

A **field row** is `label ⋯ control`, 8px vertical and 16px horizontal padding, label in `text-primary`, control aligned to the end. The kind of value decides the control: a number takes a 92px input, a choice a 110px select, a range a slider with the number beside it, on/off a switch, a colour a 24px swatch.

```html
<div class="spec-body on-canvas" style="display:grid;place-items:center"><div class="panel-demo"><div class="prop-card"><button type="button" class="prop-card-header" aria-expanded="true">Style<svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="prop-card-body"><div class="field-row"><span class="field-label" id="l-shape">Shape</span><span class="select-wrap"><button type="button" class="select" role="combobox" aria-haspopup="listbox" aria-expanded="false" aria-labelledby="l-shape"><span>Circle</span><svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="select-list" role="listbox" aria-labelledby="l-shape" hidden><div class="select-option" role="option" aria-selected="true">Circle<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Square<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Hexagon<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Star<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div></div></span></div><div class="field-row"><label>Stroke width</label><span class="input-number"><input value="3" readonly><span class="unit">mm</span></span></div><div class="field-row"><span class="field-label">Color</span><button type="button" class="swatch" aria-label="Color"><i style="background:var(--color-red-default)"></i></button></div><div class="field-row"><span class="field-label">Fill mode</span><div class="segmented"><button type="button" aria-pressed="true">Option A</button><button type="button" aria-pressed="false">Option B</button></div></div></div></div><div class="prop-card"><button type="button" class="prop-card-header" aria-expanded="false">Decoration<svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="prop-card-body" hidden><div class="field-row"><label>Show ticks</label><span class="switch"><input type="checkbox" checked><span class="track" aria-hidden="true"></span><span class="knob" aria-hidden="true"></span></span></div></div></div></div></div>
```

The second card starts collapsed: the header row stays, the chevron flips, the card is one row tall. Click the header to open it.

## Flow and states

The layout has to make the flow obvious: **pick or input → configure → generate → review → export**. Live-preview generators redraw as a slider moves, so they have no generate step; adding a Generate button to one is a defect.

The preview has three states and all three need designing:

- **Empty** — examples or a hint, never a blank rectangle
- **Computing** — a stage name, a number, and a way to cancel; never an indefinite spinner
- **Done** — zoom, pan, compare, regenerate

Errors belong beside the control that caused them, together with the next action. A toast at the top of the screen is where errors go to be missed.

## Sizing and scrolling

Your width is the region the platform allocates, not the viewport, so adapt with container queries. Below 960px the three regions stack, canvas first and rails after, and the export button stays pinned to the bottom.

Rails scroll inside themselves with thin scrollbars. Never introduce horizontal scrolling, and never nest one scroll container inside another. A panel that fills its space *and* scrolls needs **both** `flex: 1` and `min-height: 0`. `flex: 1` makes it grow; `min-height: 0` lets it shrink below its content. Without the second, a flex child keeps its default `min-height: auto`, refuses to shrink, and overflows instead of scrolling. Every scroll container in the templates carries the pair.

---

# Components

Every interactive element supports the same closed state set: default, hover, active, focus-visible, disabled, loading, selected, error. There is no ninth state; a control that seems to need one needs rethinking instead.

Heights are **skeleton**: 28 for the input family, 32 for buttons, segmented controls and icon buttons, 40 for the one large call to action, 24 for icon plates and swatches. Every component below has a class of the same name in the `<style>` block of every [template](/docs/design/layout) — using those classes is the shortest path, and building the same sizes and states in your own framework is just as valid.

## Buttons

```html
<div class="col"><div class="row"><button type="button" class="btn btn-primary">Export</button><button type="button" class="btn btn-secondary"><svg class="icon" viewBox="0 0 16 16"><path d="M3 8a5 5 0 1 0 1.5-3.6M3 3v3h3"></path></svg>Reset</button><button type="button" class="btn btn-ghost">Cancel</button><button type="button" class="btn btn-danger">Delete</button><button type="button" class="btn btn-primary" disabled>Export</button><button type="button" class="btn btn-primary" aria-busy="true">Export</button></div><div class="row" style="background:var(--color-bg-editor);padding:12px;border-radius:var(--radius-large)"><button type="button" class="btn btn-primary btn-lg" style="width:288px">Generate</button><button type="button" class="btn-icon" aria-label="Zoom in"><svg class="icon" viewBox="0 0 16 16"><path d="M8 4v8M4 8h8"></path></svg></button><button type="button" class="btn-tips"><svg class="icon icon-20" viewBox="0 0 20 20" aria-hidden="true"><path d="M7.5 15.5h5M8.5 17.8h3M10 2.2a5 5 0 0 1 3 9c-.6.5-.9 1.1-.9 1.8H7.9c0-.7-.3-1.3-.9-1.8a5 5 0 0 1 3-9Z"></path></svg>Tips</button></div></div>
```

The top row is six 32px shells, disabled and loading included; the bottom row is the 40px call to action, an icon-only button and the Tips capsule.

- `button-primary` — near-black, 32px, answers most questions. The platform's own Export button has exactly this shape
- `button-primary-large` — 40px and full width, for the one call to action in a lead rail
- `button-secondary` — white, with a border that darkens on hover
- `button-ghost` — transparent until hovered

**Destructive actions use the secondary shell with red-default text and a confirmation, never a solid red fill.** Loading keeps the button's width, swaps in a spinner and sets `aria-busy`.

Labels are verbs (Generate, Export, Reset), never OK or Submit. Icon-only buttons are 32px squares on an 8px radius, white on the canvas. The Tips button in the canvas's top-end corner is the system's second and last capsule: 32px, white, `stroke-default` border, a 20px lightbulb and the word — it has to read as help, not as one more action.

## The input family: grey fill, no border

```html
<div class="panel-demo" style="width:100%;gap:8px"><div class="prop-card"><div class="field-row"><label>Default</label><span class="input-number"><input value="200" readonly><span class="unit">mm</span></span></div><div class="field-row"><label>Hover · deeper fill</label><span class="input-number" style="background:var(--color-bg-active)"><input value="200" readonly><span class="unit">mm</span></span></div><div class="field-row"><label>Focus · white + 1px stroke-active</label><span class="input-number" style="background:var(--color-bg-default);border-color:var(--color-stroke-active)"><input value="200" readonly><span class="unit">mm</span></span></div><div class="field-row"><label>Placeholder</label><span class="input-number"><input placeholder="0"><span class="unit">mm</span></span></div><div class="field-row"><label>Disabled</label><span class="input-number"><input value="200" disabled><span class="unit">mm</span></span></div><div class="field-row"><label>Error</label><span class="input-number"><input value="480" readonly aria-invalid="true"><span class="unit">mm</span></span></div><div class="field-note" style="color:var(--color-red-default)">Width cannot exceed 300 mm.</div></div></div>
```

`input-field`: 28px tall, 92px wide, `bg-control` fill, no border, 6px radius, text in `text-secondary` with tabular figures. The error message sits beside the field, not only in a toast.

**The unit is pinned to the field's end, not carried inside the value**: 10px in `text-tertiary`, a separate element. Numbers then line up at the start edge and units at the end, and switching mm ↔ inch rewrites the two independently. A unit inside the value moves as the number grows, and reorders under RTL bidi.

A numeric field carries its starting value in `value` and `inputmode="decimal"`. Numeric fields support horizontal drag: press and drag to change the value, Shift for ten-times steps, Alt for fine steps, and a movement under 3px counts as a click. Use `setPointerCapture` so dragging outside the panel keeps the gesture, invert the direction in RTL, and keep Shift + ↑/↓ as the keyboard equivalent. Never show native spinners: the targets are tiny and the register is wrong.

The prompt box in a generate rail is the same family grown up: 8px radius, 10/12 padding, a character counter in `text-disabled` at the bottom-end corner.

## Select

The trigger is the input box at 110px with a `text-tertiary` chevron that flips when the list opens. The list is a floating surface, so unlike the docked panels it takes a border, an 8px radius and `shadow-200`.

```html
<div class="row" style="align-items:flex-start;min-height:190px"><span class="select-wrap"><button type="button" class="select" role="combobox" aria-haspopup="listbox" aria-expanded="true" aria-label="Shape"><span>Circle</span><svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="select-list" role="listbox" aria-label="Shape"><div class="select-option" role="option" aria-selected="true">Circle<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false" data-active>Square<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Hexagon<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div><div class="select-option" role="option" aria-selected="false">Star<svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m3.5 8.5 3 3 6-7"></path></svg></div></div></span><div class="note" style="max-width:340px">Click the trigger to close and reopen it, and click an option to select it. Open, the trigger goes white with a 1px `stroke-active` border — the same state as focus — and the chevron flips.</div></div>
```

**Two signals that never collide, and each is legible alone.** The fill says *where you are*: pointer and keyboard share it, so exactly one row is ever filled. The `brand-default` checkmark plus 500 weight says *what is chosen*, and it still reads with no fill under it. Above, Circle is selected and Square is where the pointer sits.

The row highlight gets a 12% step of its own because the 6% and 8% panel fills both vanish on a popup's white ground.

Rows are 32px on a 4px radius, 10px inline padding, 12px text in `text-primary`. The list is 6px-padded, at least as wide as the trigger, and caps at seven rows before it scrolls with a thin scrollbar. Above three options a select beats a segmented control; below three, the segmented control beats a select.

### The contract this owes

A native `<select>` gives the keyboard, the screen reader and the platform picker away for free. Styling the popup means writing all of that yourself. Every template already ships it as `upgradeSelects` in its script block: **port that, do not re-derive it.**

It is written as progressive enhancement, so the control works before the script runs: the markup ships a real `<select>` inside a `<span class="select-field" data-select>`. The script hides that element, builds the trigger and the list, and keeps the native one as the value's source of truth — form submission and your own `change` listeners keep working untouched.

```html
<div class="rules"><div class="rule"><b>1</b>Focus never leaves the trigger. <code>aria-activedescendant</code> points at the active option — moving focus into the list is how you end up stranding it on <code>body</code> when the list closes.</div><div class="rule"><b>2</b><code>role="combobox"</code> and <code>aria-expanded</code> on the trigger, <code>role="listbox"</code> on the list, <code>role="option"</code> and <code>aria-selected</code> on each row.</div><div class="rule"><b>3</b>Closed: ↓ ↑ Enter Space Home End or any character opens it.</div><div class="rule"><b>4</b>Open: ↓↑ move, Home/End jump to the ends, Enter or Space commits, Escape closes without changing the value, Tab closes, an outside click closes, type-ahead jumps.</div><div class="rule"><b>5</b>Focus returns to the trigger on close, and the active row scrolls inside the list's own box rather than the page's.</div><div class="rule"><b>6</b>The list mounts on <code>body</code> with <code>position: fixed</code> — left in place, a scrolling parameters rail clips it — and repositions on scroll and resize.</div><div class="rule"><b>7</b>It flips above the trigger when the space below runs out, and aligns to the trigger's end edge in RTL.</div><div class="rule"><b>8</b>On narrow touch screens fall back to the native <code>&lt;select></code>: you give up the system picker otherwise, and 32px rows are small under a thumb.</div></div>
```

Everything above is implemented in `upgradeSelects`, in every template's script block. It is the one piece of a template you keep: the rest is demo wiring you replace with your own state.

## Switch

```html
<div class="row"><label class="switch"><input type="checkbox" checked><span class="track" aria-hidden="true"></span><span class="knob" aria-hidden="true"></span></label><label class="switch"><input type="checkbox"><span class="track" aria-hidden="true"></span><span class="knob" aria-hidden="true"></span></label><label class="switch"><input type="checkbox" disabled><span class="track" aria-hidden="true"></span><span class="knob" aria-hidden="true"></span></label><span class="note">36 × 20 track · 14px knob · travels 16px</span></div>
```

`stroke-default` off, `brand-default` on. The track is below the 24px target minimum, so the field row's `<label for>` is the larger target that makes it reachable — every template wires the switch that way.

The track and the knob are decoration painted over a real `<input type="checkbox">`; every layer needs `pointer-events: none` and `aria-hidden`.

## Slider

```html
<div class="panel-demo" style="width:100%"><div class="prop-card"><div class="field-row"><label>Corner radius</label><div class="control"><input class="slider" type="range" min="0" max="20" value="6" data-unit=" mm"><span class="value">6 mm</span></div></div><div class="field-row"><label>Density</label><div class="control"><input class="slider" type="range" min="0" max="100" value="40" data-unit="%"><span class="value">40%</span></div></div><div class="field-row"><label>Disabled</label><div class="control"><input class="slider" type="range" min="0" max="100" value="40" data-unit="%" disabled><span class="value">40%</span></div></div></div></div>
```

**Never alone**: the value always appears as a number at the end of the row, and when precision matters pair it with an input. A 3px track in `track-off`, the filled part in `brand-default`, a 12px thumb with a white centre and a 2px brand ring. Step and range come from the model's real constraints; a silently clamped value is a bug the user cannot see.

## Segmented control

```html
<div class="row"><div class="segmented segmented-tabs" role="group" aria-label="View"><button type="button" aria-pressed="true">2D design</button><button type="button" aria-pressed="false">3D preview</button></div><div class="segmented"><button type="button" aria-pressed="true">mm</button><button type="button" aria-pressed="false">inch</button></div><div class="segmented"><button type="button" aria-pressed="true">Option A</button><button type="button" aria-pressed="false">Option B</button><button type="button" aria-pressed="false" disabled>Option C</button></div></div>
```

A 32px `bg-hover` track, 2px padding, 6px radius; items are `12-medium` in `text-secondary`, and the active item is white on a 4px radius with `shadow-100`; a 1px `stroke-divider` line separates adjacent inactive items. The container takes `role="group"` with a name, each option a `<button aria-pressed>`. Use it for two or three mutually exclusive views; above three, use a select. It is not a tab strip and does not carry page navigation.

## Thumbnails and the tool rail

```html
<div class="row" style="align-items:flex-start;gap:32px"><div class="thumb-grid" style="padding:0;grid-template-columns:repeat(2,140px)" role="listbox"><button type="button" class="thumb" role="option" aria-selected="true"><span class="thumb-card"><svg viewBox="0 0 112 112" fill="none" stroke="currentColor" stroke-width="2"><circle cx="56" cy="56" r="48"></circle><circle cx="56" cy="56" r="36" stroke-dasharray="4 6"></circle></svg></span><span class="thumb-label">Classic circle</span></button><button type="button" class="thumb" role="option" aria-selected="false"><span class="thumb-card"><img src="https://picsum.photos/seed/atomm-doc-en-lg-1/280/280" alt width="280" height="280"></span><span class="thumb-label">Square frame</span></button></div><div class="thumb-row" role="listbox"><button type="button" class="thumb thumb-sm" role="option" aria-selected="true"><span class="thumb-card"><svg viewBox="0 0 70 70" fill="none" stroke="currentColor" stroke-width="2"><path d="M35 8l22 14v26L35 62 13 48V22z"></path></svg></span><span class="thumb-label">Minimal</span></button><button type="button" class="thumb thumb-sm thumb-round" role="option" aria-selected="false"><span class="thumb-card"><svg viewBox="0 0 80 80"><circle cx="40" cy="40" r="38" fill="currentColor" opacity=".12"></circle></svg></span><span class="thumb-label">Antique gold</span></button><button type="button" class="thumb thumb-sm" role="option" aria-selected="false"><span class="thumb-card"><img src="https://picsum.photos/seed/atomm-photo/180/180" alt width="180" height="180"></span><span class="thumb-label">photo.png</span></button></div><nav class="gen-rail gen-rail-tools" style="height:auto;border-radius:var(--radius-large);border:1px solid var(--color-stroke-default)"><button type="button" class="rail-item" aria-pressed="true"><span class="plate"><svg class="icon" viewBox="0 0 16 16"><path d="M8 2l1.4 3.6L13 7l-3.6 1.4L8 12 6.6 8.4 3 7l3.6-1.4Z"></path></svg></span>Generate</button><button type="button" class="rail-item" aria-pressed="false"><span class="plate"><svg class="icon" viewBox="0 0 16 16"><rect x="2.5" y="2.5" width="4.5" height="4.5" rx="1"></rect><rect x="9" y="2.5" width="4.5" height="4.5" rx="1"></rect><rect x="2.5" y="9" width="4.5" height="4.5" rx="1"></rect><rect x="9" y="9" width="4.5" height="4.5" rx="1"></rect></svg></span>Templates</button></nav></div>
```

A template thumbnail is a 140px white card: 8px radius, `stroke-divider` border, `shadow-100`. An inline SVG sits inset 14px; a photo fills the card edge to edge. Style tiles are the same card at 90px with no shadow (SVG inset 10px), and a round subject keeps the square card with a circular image inside it. **Selection is a 2px brand-default ring** drawn over the card, so the content never resizes; hover is `stroke-default`.

The tool rail is 64px wide with 40px plates. The selected tool is `brand-default` with a white glyph.

## Platform-fed blocks

Two pieces of UI draw their data from the platform rather than from your generator: the material the preview is rendered on, and the user's history. The templates ship them working with placeholders so they sit in the right place from day one; wire the data when the capability is open to you.

```html
<div class="row" style="align-items:flex-start;gap:24px"><div class="panel-demo" style="width:320px"><div class="prop-card"><button type="button" class="prop-card-header" aria-expanded="true">Surface<svg class="icon" viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg></button><div class="prop-card-body"><div class="material-grid" role="group" aria-label="Surface"><button type="button" class="material" aria-pressed="true" aria-label="Basswood"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="currentColor" opacity=".08"></rect></svg></button><button type="button" class="material" aria-pressed="false" aria-label="Oak"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="currentColor" opacity=".14"></rect><path d="M8 0v57M20 0v57M32 0v57M44 0v57" stroke="currentColor" stroke-width="3" opacity=".12"></path></svg></button><button type="button" class="material" aria-pressed="false" aria-label="Walnut"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="currentColor" opacity=".35"></rect><path d="M6 0v57M18 0v57M30 0v57M42 0v57M54 0v57" stroke="currentColor" stroke-width="3" opacity=".15"></path></svg></button><button type="button" class="material" aria-pressed="false" aria-label="Birch"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="currentColor" opacity=".05"></rect></svg></button><button type="button" class="material" aria-pressed="false" aria-label="Brushed steel"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="currentColor" opacity=".18"></rect><path d="M0 4h57M0 12h57M0 20h57M0 28h57M0 36h57M0 44h57M0 52h57" stroke="currentColor" stroke-width="1" opacity=".18"></path></svg></button><button type="button" class="material" aria-pressed="false" aria-label="Textured steel"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="currentColor" opacity=".22"></rect><path d="M0 57 57 0M-10 40 40-10M17 67 67 17" stroke="currentColor" stroke-width="2" opacity=".15"></path></svg></button><button type="button" class="material" aria-pressed="false" aria-label="Black acrylic"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="currentColor" opacity=".9"></rect></svg></button><button type="button" class="material" aria-pressed="false" aria-label="Orange acrylic"><svg viewBox="0 0 57 57"><rect width="57" height="57" fill="var(--orange-500)"></rect></svg></button></div></div></div><button type="button" class="btn btn-primary btn-block">Export</button></div><div style="width:288px;padding:16px;background:var(--color-bg-default);border:1px solid var(--color-stroke-divider);border-radius:var(--radius-xlarge);box-shadow:var(--shadow-100)"><button type="button" class="rail-back"><svg class="icon" viewBox="0 0 16 16" aria-hidden="true"><path d="m10 4-4 4 4 4"></path></svg><span>My history</span></button><div class="history-grid" role="listbox" aria-label="History" style="margin-top:12px"><button type="button" class="history-item" aria-pressed="true" aria-label="Result 1"><svg viewBox="0 0 80 80"><circle cx="40" cy="40" r="38" fill="currentColor" opacity=".12"></circle><circle cx="40" cy="40" r="28" fill="none" stroke="currentColor" stroke-width="2"></circle></svg></button><button type="button" class="history-item" aria-pressed="false" aria-label="Result 2"><img src="https://picsum.photos/seed/atomm-doc-en-hist-1/180/180" alt width="180" height="180"></button><button type="button" class="history-item" aria-pressed="false" aria-label="Result 3"><svg viewBox="0 0 80 80"><circle cx="40" cy="40" r="38" fill="currentColor" opacity=".2"></circle><circle cx="40" cy="40" r="28" fill="none" stroke="currentColor" stroke-width="2"></circle></svg></button><button type="button" class="history-item" aria-pressed="false" aria-label="Result 4"><svg viewBox="0 0 80 80"><circle cx="40" cy="40" r="38" fill="currentColor" opacity=".12"></circle><circle cx="40" cy="40" r="28" fill="none" stroke="currentColor" stroke-width="2"></circle></svg></button><button type="button" class="history-item" aria-pressed="false" aria-label="Result 5"><img src="https://picsum.photos/seed/atomm-doc-en-hist-4/180/180" alt width="180" height="180"></button><button type="button" class="history-item" aria-pressed="false" aria-label="Result 6"><svg viewBox="0 0 80 80"><circle cx="40" cy="40" r="38" fill="currentColor" opacity=".2"></circle><circle cx="40" cy="40" r="28" fill="none" stroke="currentColor" stroke-width="2"></circle></svg></button></div><button type="button" class="btn btn-secondary btn-block" style="margin-top:12px">Load more</button></div></div>
```

**Surface** is a property card at the bottom of the stack: 57px tiles four to a row, one selected with a 2px `text-primary` ring 2px outside the tile. It changes how the preview renders, never what exports. **History** is a second level inside the lead rail: a back row, 90px tiles three to a row, Load more beneath. Tiles follow the thumbnail rule: an inline SVG sits inset 10px, a photo fills the tile.

## Dialogs

```html
<div class="spec-body on-canvas" style="padding:24px;display:grid;place-items:center"><div class="dialog" style="position:static;display:block;margin:0"><div class="dialog-header"><span>Fabrication Tips</span><svg class="icon icon-20" viewBox="0 0 20 20" aria-hidden="true"><circle cx="10" cy="10" r="7.5"></circle><path d="M10 9.2v4.6M10 6.6h.01"></path></svg><span class="spacer" aria-hidden="true"></span><span class="sr-only">1 / 3</span><button type="button" class="btn-icon btn-icon-sm" aria-label="Close"><svg class="icon" viewBox="0 0 16 16"><path d="m4 4 8 8M12 4l-8 8"></path></svg></button></div><div class="dialog-media" style="height:120px">Illustration</div><div class="dialog-body"><div class="tip-slide"><h3 id="real-world-units">Real-world units</h3><p>All dimensions are physical (mm / inch) and match the exported file 1:1 — what you set is what gets cut.</p></div></div><div class="dialog-footer"><div class="dots"><i aria-current="true"></i><i></i><i></i></div><span class="spacer" aria-hidden="true"></span><button type="button" class="btn btn-secondary" disabled>Back</button><button type="button" class="btn btn-primary">Next</button></div></div></div>
```

Native `<dialog>` with `showModal()`: 480px wide, 12px radius, `shadow-300`, scrim `bg-overlay` (70% black). On a short viewport the body scrolls; header and footer stay put. Header 16/24: title in `16-semibold`, a 20px info glyph in `text-tertiary` beside it, the 24px close button at the end, hairline below. Then an optional media band in `bg-control`, and a footer with pagination dots at the start and buttons at the end. Most things put in dialogs do not belong there: errors go beside their control, progress goes in the preview, settings go in the parameters rail. Fabrication Tips is the canonical dialog.

```html
<div class="spec-body on-canvas" style="padding:24px;display:grid;place-items:center"><div class="dialog dialog-generate" style="position:static;display:block;margin:0"><div class="dialog-header"><span class="dialog-thumb"><svg viewBox="0 0 80 80" fill="none" stroke="currentColor" stroke-width="2"><circle cx="40" cy="40" r="36"></circle><path d="M28 50c4-16 20-16 24 0"></path></svg></span><span class="dialog-heading"><span>Antique bronze</span><span class="tag-row"><span class="tag">1:1</span><span class="tag">Transparent background</span></span></span><button type="button" class="btn-icon btn-icon-sm" aria-label="Close"><svg class="icon" viewBox="0 0 16 16"><path d="m4 4 8 8M12 4l-8 8"></path></svg></button></div><div class="dialog-body"><div class="form-field"><span class="form-label">Reference image</span><label class="dropzone"><span class="plate"><svg class="icon" viewBox="0 0 16 16"><path d="M8 11V2M5 5l3-3 3 3M2 12v2h12v-2"></path></svg></span><strong>Click or drag an image here</strong><small>Your photo, logo or artwork becomes the coin face · max 10MB</small></label></div><div class="form-field"><label class="form-label" for="cd-prompt">Describe your design <em>(optional)</em></label><span class="textarea"><textarea id="cd-prompt" rows="2" placeholder="e.g. A geometric fox head with clean, minimal lines…"></textarea></span></div></div><div class="dialog-footer"><span class="spacer" aria-hidden="true"></span><button type="button" class="btn btn-secondary">Cancel</button><button type="button" class="btn btn-primary">Generate</button></div></div></div>
```

The generate dialog (layout 4). The dark `bg-inverse` header repeats the pick: a 66px thumbnail, the name in `16-semibold`, one `tag` per fact the choice already fixed. The body stacks form fields — the one place where a `form-label` sits above its control rather than beside it, because a 480px dialog has room for a full-width drop target and a 320px rail does not. Picking a style tile opens this, so the tile itself never starts the call.

## Alerts, links, helper text

Alerts put the tint behind the message and the solid on the icon, with `text-primary` words, next to whatever they describe (see [Colour](/docs/design/color)). Links take `blue-default` and keep their underline — colour alone is not a link affordance. Helper text under a field is `12-regular` in `text-tertiary` and explains a constraint rather than restating the label.

**Be stingy.** Anything that fits in a unit suffix should not become a sentence — `20 %` beats "percentage of a single tile's edge length". Anything readable from the results should not be repeated in the parameters rail. The ideal end state is a parameters rail with two or three genuinely constraining notes left in it.

---

# Colour

The palette is written in two layers. **Primitives** hold the raw values and are the only place a hex appears; **semantic tokens** reference them and say what a colour is *for*, and components reference the semantic layer only. That is what makes a reskin a change to a dozen lines rather than to every component.

The whole colour layer is **skin**: the values here are the platform default and the five templates ship with them; a generator may replace the set. What does not change is the structure — the role each token plays, and the contrast each role has to clear.

## The neutral ramp

```html
<div class="ramp"><button type="button" class="chip" data-hex="#ffffff"><span class="chip-sw" style="background:#ffffff;border-bottom:1px solid var(--color-stroke-divider)"></span><span class="chip-meta"><span class="chip-name">neutral-0</span><span class="chip-hex">#ffffff</span><span class="chip-num">cards, white controls</span></span></button><button type="button" class="chip" data-hex="#fcfcfd"><span class="chip-sw" style="background:#fcfcfd"></span><span class="chip-meta"><span class="chip-name">neutral-25</span><span class="chip-hex">#fcfcfd</span><span class="chip-num">docked panels</span></span></button><button type="button" class="chip" data-hex="#f6f6f7"><span class="chip-sw" style="background:#f6f6f7"></span><span class="chip-meta"><span class="chip-name">neutral-50</span><span class="chip-hex">#f6f6f7</span><span class="chip-num">the plate under a swatch</span></span></button><button type="button" class="chip" data-hex="#eeeff1"><span class="chip-sw" style="background:#eeeff1"></span><span class="chip-meta"><span class="chip-name">neutral-100</span><span class="chip-hex">#eeeff1</span><span class="chip-num">control fill</span></span></button><button type="button" class="chip" data-hex="#e7e8ea"><span class="chip-sw" style="background:#e7e8ea"></span><span class="chip-meta"><span class="chip-name">neutral-200</span><span class="chip-hex">#e7e8ea</span><span class="chip-num">the ground, disabled fill</span></span></button><button type="button" class="chip" data-hex="#d6d8db"><span class="chip-sw" style="background:#d6d8db"></span><span class="chip-meta"><span class="chip-name">neutral-300</span><span class="chip-hex">#d6d8db</span><span class="chip-num">strokes, off track</span></span></button><button type="button" class="chip" data-hex="#b9bbc0"><span class="chip-sw" style="background:#b9bbc0"></span><span class="chip-meta"><span class="chip-name">neutral-400</span><span class="chip-hex">#b9bbc0</span><span class="chip-num">hover stroke, disabled text</span></span></button><button type="button" class="chip" data-hex="#85878b"><span class="chip-sw" style="background:#85878b"></span><span class="chip-meta"><span class="chip-name">neutral-500</span><span class="chip-hex">#85878b</span><span class="chip-num">tertiary text 3.60:1</span></span></button><button type="button" class="chip" data-hex="#3d3e42"><span class="chip-sw" style="background:#3d3e42"></span><span class="chip-meta"><span class="chip-name">neutral-800</span><span class="chip-hex">#3d3e42</span><span class="chip-num">secondary text 10.68:1</span></span></button><button type="button" class="chip" data-hex="#292a2d"><span class="chip-sw" style="background:#292a2d"></span><span class="chip-meta"><span class="chip-name">neutral-900</span><span class="chip-hex">#292a2d</span><span class="chip-num">brand</span></span></button><button type="button" class="chip" data-hex="#171719"><span class="chip-sw" style="background:#171719"></span><span class="chip-meta"><span class="chip-name">neutral-950</span><span class="chip-hex">#171719</span><span class="chip-num">primary text 17.90:1</span></span></button></div>
```

Eleven near-neutral greys; click to copy a hex. The token export's ramp has fourteen steps — 600, 700 and 1000 belong to the platform's own editor chrome (grid lines, the shadow base), so a generator region never reaches for them. The three lightest (0 / 25 / 100) carry card, panel and control fill; the three darkest (800 / 900 / 950) carry secondary text, the brand colour and primary text.

## A neutral workbench with one dark accent

Panels are `bg-subtlest`, cards on the panels are pure white, and the ground the preview stands on is `bg-editor` — **three steps darker than the panels**. The ground is the floor of the room and the panels are furniture standing on it; a preview reads as an object placed on that floor. Controls take a third grey, `bg-control`, one step lighter than the ground — a recess in a white surface rather than the floor itself.

```html
<div class="spec-body on-canvas" style="padding:0;display:flex;height:180px;border:1px solid var(--color-stroke-default);border-radius:var(--radius-large);overflow:hidden"><div style="flex:1;display:grid;place-items:center;color:var(--color-text-tertiary);font-size:12px">bg-editor</div><div style="width:200px;background:var(--color-bg-subtlest);border-inline-start:1px solid var(--color-stroke-default);padding:12px;display:flex;flex-direction:column;gap:8px"><div class="prop-card" style="padding:8px 12px;font-size:12px;color:var(--color-text-tertiary)">bg-default</div><div style="font-size:11px;color:var(--color-text-tertiary);text-align:center">bg-subtlest</div></div></div>
```

Three surfaces a step or two apart are enough to separate floor, panel and card. Docked regions carry no shadow — only tone and a 1px `stroke-default` line.

`brand-default` is a near-black (`neutral-900`). It carries the primary button, the filled part of a slider, a switch in its on state, the selected tool in the rail and the selection ring on thumbnails. **Hover lightens it one step to neutral-800 and press darkens it to neutral-950** — a press always lands darker than rest.

`emphasize-default` (`atomm-600`) is the platform's red and the one exception to a neutral chrome: **at most one emphasized action per screen**, on the thing that carries a cost or a consequence. The platform's own generators leave Generate on `brand-default`, so no template ships an emphasized button.

## Four text steps

```html
<div class="ladder"><div class="ladder-row"><span class="ladder-tok">text-primary</span><span class="ladder-sample" style="color:var(--color-text-primary)">Field labels, card titles, values, headings</span><span class="ladder-cr">17.90:1</span></div><div class="ladder-row"><span class="ladder-tok">text-secondary</span><span class="ladder-sample" style="color:var(--color-text-secondary)">Text inside inputs and selects, button labels on white, thumbnail labels</span><span class="ladder-cr">10.68:1</span></div><div class="ladder-row"><span class="ladder-tok">text-tertiary</span><span class="ladder-sample" style="color:var(--color-text-tertiary)">Helper text, placeholders, "View all", inactive rail items</span><span class="ladder-cr">3.60:1</span></div><div class="ladder-row"><span class="ladder-tok">text-disabled</span><span class="ladder-sample" style="color:var(--color-text-disabled)">Disabled labels, character counters</span><span class="ladder-cr">1.92:1</span></div></div>
```

The first two clear 4.5:1 on every surface in the system. **text-tertiary does not** — 3.60:1 on white, 3.13:1 on the control fill. It follows that tertiary carries only text a reader can afford to miss: a helper line, a placeholder, an inactive label. Never a value, never a message, never a label a decision rests on. Disabled is not meant to be read at all.

## Three strokes

```html
<div class="stroke-demo"><div class="sd"><span class="sd-swatch" style="background:var(--color-bg-default);border:1px solid var(--color-stroke-divider)"></span><div><b style="font-weight:500">stroke-divider</b> · 8% ink<div class="note">The border of a property card, the line under a card header, the edge of a floating panel. Hairline: it separates, it does not outline.</div></div></div><div class="sd"><span class="sd-swatch" style="background:var(--color-bg-default);border:1px solid var(--color-stroke-default)"></span><div><b style="font-weight:500">stroke-default</b> · neutral-300<div class="note">The edge of a docked rail, a secondary button, a thumbnail on hover, the pill-shaped Fabrication Tips button.</div></div></div><div class="sd"><span class="sd-swatch" style="background:var(--color-bg-default);border:1px solid var(--color-stroke-strong)"></span><div><b style="font-weight:500">stroke-strong</b> · neutral-400<div class="note">The hover step for anything that has a stroke-default border.</div></div></div></div>
```

Inputs have **no border at rest**: the grey fill is the affordance. A border appears only on focus, and then it is `stroke-active`.

### Three neutral fills

They look close and they are not interchangeable:

```html
<div class="row"><div style="width:150px;height:56px;border-radius:var(--radius-medium);background:var(--color-bg-hover);display:grid;place-items:center;font-size:11px;color:var(--color-text-secondary)">bg-hover · 6%</div><div style="width:150px;height:56px;border-radius:var(--radius-medium);background:var(--color-bg-active);display:grid;place-items:center;font-size:11px;color:var(--color-text-secondary)">bg-active · 8%</div><div style="width:150px;height:56px;border-radius:var(--radius-medium);background:var(--color-bg-highlight);display:grid;place-items:center;font-size:11px;color:var(--color-text-secondary)">bg-highlight · 12%</div></div>
```

6% is the hover step on a panel, 8% is a pressed or selected state there, and 12% is the row highlight inside a floating list. The first two land at 1.10–1.14:1 on the white ground of a popup and simply disappear, which is why a floating row has a step of its own — a menu row you cannot see is a menu row you cannot use.

## Status

The chrome is neutral: `brand-default` carries everything that needs weight, and `emphasize-default` is rationed to one action per screen.

```html
<div class="col"><div class="alert alert-info"><svg class="icon" viewBox="0 0 16 16"><circle cx="8" cy="8" r="6.5"></circle><path d="M8 7.5v4M8 5h.01"></path></svg><p>Parameters were recomputed against the latest model constraints.</p></div><div class="alert alert-success"><svg class="icon" viewBox="0 0 16 16"><circle cx="8" cy="8" r="6.5"></circle><path d="m5 8 2 2 4-4"></path></svg><p>File exported, 200 × 120 mm.</p></div><div class="alert alert-warning"><svg class="icon" viewBox="0 0 16 16"><path d="M8 2.5 14.5 13.5H1.5z"></path><path d="M8 7v3M8 12h.01"></path></svg><p>A 0.1 mm line really is a hair on screen. That is correct.</p></div><div class="alert alert-error"><svg class="icon" viewBox="0 0 16 16"><circle cx="8" cy="8" r="6.5"></circle><path d="m5.5 5.5 5 5M10.5 5.5l-5 5"></path></svg><p>Width cannot exceed 300 mm.</p></div></div>
```

Status colours work in pairs: **the tint is the fill, the solid is the icon, and the words stay text-primary** (15–17:1 on every tint). Coloured text on a coloured tint is the most common accessibility mistake in status messaging — and it would fail here, since `green-default` and `warning-default` measure 2.6–2.7:1 on their own tints. `stroke-surround` is a solid blue at 4.76:1 — often the only sign of where the keyboard is, so it clears 3:1 on its own with room to spare.

## Reskinning

If you replace the palette:

- Stay light — the ground darker than the panels, never dark mode.
- Recompute every text step against every surface it sits on, and keep the two that carry meaning (`text-primary`, `text-secondary`) at 4.5:1 or better.
- Keep `stroke-divider` / `stroke-default` / `stroke-strong` distinguishable from each other and from the fills.
- Change values, not names. Variables like `--color-brand-default` are published to every generator; renaming one is a breaking change.

---

# Typography

**Inter** throughout, three weights, line heights in even pixels. The token export names a style by its metrics and ships no role aliases, so the table below is the mapping: which kind of thing takes which style. Seven of the export's twenty styles appear inside a generator region — the rest belong to the platform's own marketing and landing pages.

<table>
<thead>
  <tr>
    <th>
      Style
    </th>
    
    <th>
      Metrics
    </th>
    
    <th>
      Carries
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        16-semibold
      </code>
    </td>
    
    <td>
      16 / 600 / 22
    </td>
    
    <td>
      Dialog titles only
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        14-medium
      </code>
    </td>
    
    <td>
      14 / 500 / 20
    </td>
    
    <td>
      Buttons, rail headings ("Templates", "AI Generate")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        12-medium
      </code>
    </td>
    
    <td>
      12 / 500 / 16
    </td>
    
    <td>
      Property-card titles, segmented items
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        12-regular
      </code>
    </td>
    
    <td>
      12 / 400 / 16
    </td>
    
    <td>
      Field labels, values inside inputs, select text, helper text, alert and dialog body
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        11-regular
      </code>
    </td>
    
    <td>
      11 / 400 / 16
    </td>
    
    <td>
      Thumbnail labels, "View all"
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        10-medium
      </code>
    </td>
    
    <td>
      10 / 500 / 14
    </td>
    
    <td>
      The selected tool-rail label
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        10-regular
      </code>
    </td>
    
    <td>
      10 / 400 / 14
    </td>
    
    <td>
      The unit suffix, and a tool-rail label at rest
    </td>
  </tr>
</tbody>
</table>

```html
<div class="ladder"><div class="ladder-row"><span class="ladder-tok">16-semibold</span><span class="ladder-sample" style="font:600 16px/22px var(--font-sans)">Fabrication Tips</span><span class="ladder-cr">16 / 600 / 22</span></div><div class="ladder-row"><span class="ladder-tok">14-medium</span><span class="ladder-sample" style="font:500 14px/20px var(--font-sans)">Generate</span><span class="ladder-cr">14 / 500 / 20</span></div><div class="ladder-row"><span class="ladder-tok">12-medium</span><span class="ladder-sample" style="font:500 12px/16px var(--font-sans)">Size</span><span class="ladder-cr">12 / 500 / 16</span></div><div class="ladder-row"><span class="ladder-tok">12-regular</span><span class="ladder-sample" style="font:400 12px/16px var(--font-sans)">Corner radius</span><span class="ladder-cr">12 / 400 / 16</span></div><div class="ladder-row"><span class="ladder-tok">11-regular</span><span class="ladder-sample" style="font:400 11px/16px var(--font-sans)">Classic circle</span><span class="ladder-cr">11 / 400 / 16</span></div><div class="ladder-row"><span class="ladder-tok">10-medium</span><span class="ladder-sample" style="font:500 10px/14px var(--font-sans)">Templates</span><span class="ladder-cr">10 / 500 / 14</span></div><div class="ladder-row"><span class="ladder-tok">10-regular</span><span class="ladder-sample" style="font:400 10px/14px var(--font-sans)">mm</span><span class="ladder-cr">10 / 400 / 14</span></div></div>
```

Each style at its real size, carrying the kind of thing it is for. Only two of the seven are above 12px, and the four 10–12px steps differ by weight rather than by size — that is what keeps a 320px rail readable without making it tall.

## The panel is built on 12px

Labels, values and card titles all share 12px. The hierarchy inside a card comes from **weight** (card title 500, field label 400) and from **position** (header row above, field rows below), not from size. 14px is reserved for the two things that have to read from across the room: a button and a rail heading.

```html
<div class="row" style="align-items:flex-start"><div class="panel-demo" style="width:280px"><div class="gen-rail-title">Templates <span style="float:inline-end;color:var(--color-text-disabled);font-size:11px;font-weight:400">label · 14 / 500</span></div><div class="prop-card"><button type="button" class="prop-card-header" aria-expanded="true">Size <span style="color:var(--color-text-disabled);font-weight:400">field-strong · 12 / 500</span></button><div class="prop-card-body"><div class="field-row"><label>Width <span style="color:var(--color-text-disabled)">field · 12 / 400</span></label><span class="input-number"><input value="200" readonly><span class="unit">mm</span></span></div></div><div class="field-note">note · 12 / 400 · text-tertiary</div></div><button type="button" class="btn btn-primary btn-block">Generate <span style="opacity:.6;font-weight:400">label · 14 / 500</span></button></div></div>
```

Three layers inside one card: **card title 12 / 500 / text-primary**, **field label 12 / 400 / text-primary**, **value inside the input 12 / 400 / text-secondary**. What separates them is weight and colour, not size — so the panel never grows taller as it grows richer.

Raising the field register to 14 makes every row 4px taller and a 320px rail lose a card of content. Field labels, values and helper text all share `12-regular`, so a generator that needs bigger text moves the **whole register** up one step — to `14-regular` — and accepts the taller rows. There is no way to raise one of them and not the others, which is the point.

## Numbers

Values always use `tabular-nums`: equal-width digits keep 200, 3 and 12 aligned in a column of 92px inputs, and a value does not jitter sideways as it changes. The unit sits at the end of the same field as its own element, in `10-regular`; it never becomes a column of its own.

---

# Shapes

The token export defines nine radii; a generator region uses six of them, each tied to a kind of thing. The pairing is **skeleton**: a reskin does not change it. (The other three — `tiny` 2, `xxlarge` 16, `xxxlarge` 24 — belong to the platform's own surfaces.)

- `rounded.none` (0) — the bottom two corners of an expanded property card's header row (collapsed, the header is the whole card and takes all four)
- `rounded.small` (4px) — tags, the 24px icon plates in section headers, the active item of a segmented control
- `rounded.medium` (6px) — every control: input, select, button, segmented track, swatch
- `rounded.large` (8px) — thumbnail cards, the zoom cluster, icon buttons, the collapsed pill, the 40px tool plate, and property cards
- `rounded.xlarge` (12px) — dialogs and the floating rail

```html
<div class="shape-row"><div class="shape-box" style="height:24px;border-radius:var(--radius-small)">24 · sm 4</div><div class="shape-box" style="height:28px;border-radius:var(--radius-medium)">28 · md 6</div><div class="shape-box" style="height:32px;border-radius:var(--radius-medium)">32 · md 6</div><div class="shape-box" style="height:40px;border-radius:var(--radius-large)">40 · lg 8</div><div class="shape-box" style="height:56px;width:120px;border-radius:var(--radius-large)">card · lg 8</div><div class="shape-box" style="height:64px;width:120px;border-radius:var(--radius-xlarge)">dialog · xl 12</div></div>
```

Radius follows height: 28 and 32px controls take 6px, the 40px call to action takes 8px, floating containers take 8 and 12, and a property card takes 8 on all four corners. The pairing matters more than the numbers — a 40px button at 6px looks unfinished, and at 20px it looks like a different product.

`rounded.circle` is the export's `100px`, not `9999px`: it only reaches a pill on something narrower than 200px, which every fully-round thing here is — a 36px switch track, a 12px thumb, the 68px Tips capsule. It is for true circles: the switch knob, the slider thumb, status dots. **Two capsules exist in the system and no more**: the switch track, because a rounded-rectangle switch reads as a checkbox, and the Tips button, which has to read as help rather than as one more action. Every other button is a rounded rectangle.

Corners are the only shape device. No notches, no angled cuts, no decorative borders, no gradient strokes.

---

# Elevation & Depth

Depth comes from **surface tone and hairlines first, shadow second**. Docked regions carry no shadow at all: three tones — panel (`bg-subtlest`), white card, grey canvas — plus 1px lines already keep them apart. Shadows go only to things that genuinely leave the plane.

<table>
<thead>
  <tr>
    <th>
      Token
    </th>
    
    <th>
      Value
    </th>
    
    <th>
      Used for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        shadow-100
      </code>
    </td>
    
    <td>
      <code>
        0 4px 12px rgba(11,11,13,.06), 0 0 4px rgba(11,11,13,.06)
      </code>
    </td>
    
    <td>
      Floating rail, property cards, collapsed pill, thumbnail cards, the active segment, switch knob, slider thumb
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        shadow-200
      </code>
    </td>
    
    <td>
      <code>
        0 16px 32px rgba(11,11,13,.06), 0 2px 8px rgba(11,11,13,.06)
      </code>
    </td>
    
    <td>
      Dropdown lists
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        shadow-300
      </code>
    </td>
    
    <td>
      <code>
        0 40px 80px rgba(11,11,13,.06), 0 2px 8px rgba(11,11,13,.06)
      </code>
    </td>
    
    <td>
      Dialogs
    </td>
  </tr>
</tbody>
</table>

```html
<div class="spec-body on-canvas" style="padding:0"><div class="elev-grid" style="padding:24px"><div class="elev-box" style="box-shadow:var(--shadow-100)">shadow-100</div><div class="elev-box" style="box-shadow:var(--shadow-200)">shadow-200</div><div class="elev-box" style="box-shadow:var(--shadow-300)">shadow-300</div></div></div>
```

Three steps and no fourth: needing one usually means something that belongs flat on the panel has been lifted off it. Every step is two layers — an offset shadow gives direction, a zero-offset one gives a white card an edge even on a white panel — and all three share a single shadow colour at 6%. `shadow-100` is also the smallest step there is: knobs and thumbs take it, and nothing in the system takes anything smaller. No shadow is ever animated, and nothing lifts on hover.

## Focus is its own layer

Keyboard focus is a 2px `stroke-surround` outline with a **2px offset**. The offset is load-bearing: it separates the ring from the control's own fill, so the ring is as visible on a near-black button as on a white one. Setting it to 0 is exactly why focus rings disappear on primary buttons.

```html
<div class="focus-demo"><button type="button" class="btn btn-primary ring">Export</button><button type="button" class="btn btn-secondary ring">Reset</button><span class="note">offset 2px</span><button type="button" class="btn btn-primary ring0" style="margin-inline-start:24px">Export</button><span class="note">offset 0 — the ring hugs the dark fill and nearly vanishes</span></div>
```

The input family is the exception: inputs and selects show focus by **turning their fill white and drawing a 1px stroke-active border**. They are already a filled box; a ring around one reads as two boundaries.

---

# Motion

<table>
<thead>
  <tr>
    <th>
      Token
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        motion.fast
      </code>
    </td>
    
    <td>
      150ms
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        motion.base
      </code>
    </td>
    
    <td>
      200ms
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        motion.easing
      </code>
    </td>
    
    <td>
      <code>
        cubic-bezier(0.2, 0, 0.38, 1)
      </code>
    </td>
  </tr>
</tbody>
</table>

Motion confirms that something changed. It never carries meaning on its own and it never makes the user wait.

```html
<div class="rules"><div class="rule"><b>1</b>Interactive feedback — hover, press, toggle, a border changing colour: <code>fast</code>.</div><div class="rule"><b>2</b>Content transitions — rail collapse, dialog enter and exit: <code>base</code>.</div><div class="rule"><b>3</b>Animate <code>opacity</code>, <code>transform</code> and colour — never a layout property. The GPU is busy rendering your preview; animating <code>height</code> or <code>width</code> drops frames.</div><div class="rule"><b>4</b>Nothing exceeds <code>base</code>. Nothing bounces, overshoots or lingers.</div><div class="rule"><b>5</b>Generation progress is not an animation. It is a number and a stage name.</div><div class="rule"><b>6</b>No entrance animation on load.</div><div class="rule"><b>7</b><code>prefers-reduced-motion: reduce</code> collapses every duration to zero. Nothing is lost, because no state is conveyed by motion alone.</div></div>
```

A property card collapses by changing `hidden` and the chevron's `transform`, with no height animation. A segmented control switches with a 150ms change of fill and shadow. Every state change in the demos on these pages uses the three values above.

---

# Iconography

**Icons are inlined as stroked SVG, never an icon font.**

The probability of an icon font failing to load from a CDN is not small (network policy, sandboxes, offline), and the failure mode is bad: icon-only buttons become empty boxes, or degrade into a substitute glyph that is stylistically wrong. Given how often icons appear, betting on an external dependency is not worth it.

```html
<div class="icon-grid"><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="m4 6 4 4 4-4"></path></svg>Expand</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="m6 4 4 4-4 4"></path></svg>View all</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="M8 4v8M4 8h8"></path></svg>Zoom in</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="M4 8h8"></path></svg>Zoom out</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="M2 6V2h4M10 2h4v4M14 10v4h-4M6 14H2v-4"></path></svg>Fit</div><div class="icon-cell"><svg viewBox="0 0 16 16"><rect x="2" y="3" width="12" height="10" rx="1.5"></rect><path d="M6 3v10"></path></svg>Collapse</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="M3 8a5 5 0 1 0 1.5-3.6M3 3v3h3"></path></svg>Reset</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="M8 2l1.4 3.6L13 7l-3.6 1.4L8 12 6.6 8.4 3 7l3.6-1.4Z"></path></svg>Generate</div><div class="icon-cell"><svg viewBox="0 0 16 16"><rect x="2.5" y="2.5" width="4.5" height="4.5" rx="1"></rect><rect x="9" y="2.5" width="4.5" height="4.5" rx="1"></rect><rect x="2.5" y="9" width="4.5" height="4.5" rx="1"></rect><rect x="9" y="9" width="4.5" height="4.5" rx="1"></rect></svg>Templates</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="M8 10V3M5 6l3-3 3 3M3 11v2h10v-2"></path></svg>Import</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="m4 4 8 8M12 4l-8 8"></path></svg>Close</div><div class="icon-cell"><svg viewBox="0 0 16 16"><path d="m3.5 8.5 3 3 6-7"></path></svg>Selected</div></div>
```

Specification: `viewBox="0 0 16 16"` (20 for the tips lightbulb); `fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round`. Colour always comes from the parent's text token — an icon with its own colour is an icon that is wrong in the next state.

## Three hit-area steps

```html
<div class="hit"><div class="hit-cell"><div class="hit-box" style="width:24px;height:24px"><svg width="16" height="16" viewBox="0 0 16 16"><path d="m4 4 8 8M12 4l-8 8"></path></svg></div>24 · minimum</div><div class="hit-cell"><div class="hit-box" style="width:32px;height:32px"><svg width="16" height="16" viewBox="0 0 16 16"><path d="M8 4v8M4 8h8"></path></svg></div>32 · default</div><div class="hit-cell"><div class="hit-box" style="width:40px;height:40px"><svg width="16" height="16" viewBox="0 0 16 16"><path d="M8 2l1.4 3.6L13 7l-3.6 1.4L8 12 6.6 8.4 3 7l3.6-1.4Z"></path></svg></div>40 · tool plate</div></div>
```

Icon-only controls use 24 / 32 / 40, with 32 the default. **There is no step below 24.** The glyph inside is free to be smaller: a 24px plate and a 32px button both carry a 16px glyph. When a control has to *look* smaller than its target — a switch track, a slider, an 11px text link — keep the visual size and pad the hit area to 24, with an equal negative margin so the layout does not move.

## Three kinds of icon, three obligations

- A **decorative** icon beside its own text label takes `aria-hidden` so it is not announced twice.
- An **interactive** icon-only button takes an `aria-label` describing the action, not the picture ("Zoom in", not "plus").
- An **indicative** icon carrying state needs screen-reader text, because colour and shape alone convey nothing.

**Directional** icons — arrows, undo, indent — need a class that RTL can flip. Clocks, checkmarks, play buttons, logos and charts with a time axis must never be flipped. Prefer up/down chevrons where there is a choice: they need no flipping, which is why the property-card disclosure points up and down rather than left and right.

---

# Direction (RTL)

The platform renders your generator in a document whose `dir` follows the user's locale, and several supported locales read right to left. Mirroring is not optional, and there is no second stylesheet: the layout has to flip itself.

Written the modern way this is nearly free. Every one-sided value uses a logical property — `margin-inline-start`, `padding-inline-end`, `inset-inline-start`, `text-align: start`; symmetric shorthands need no attention; flex and grid mirror themselves, and adding `flex-row-reverse` for RTL flips a layout that had already flipped.

```html
<div class="dir"><div class="dir-rail"><div class="prop-card"><div class="field-row"><label>Width</label><span class="input-number"><input value="200" readonly><span class="unit">mm</span></span></div><div class="field-row"><label>Density</label><div class="control"><input class="slider" type="range" min="0" max="100" value="40" data-unit="%" style="width:70px"><span class="value">40%</span></div></div><div class="field-row"><label>Show ticks</label><span class="switch"><input type="checkbox" checked><span class="track" aria-hidden="true"></span><span class="knob" aria-hidden="true"></span></span></div></div></div><div class="dir-canvas"><div class="dir-fixed" style="direction:ltr"><div class="dir-board"><svg viewBox="0 0 132 96" width="132" height="96"><path d="M0 48h132M44 0v96M88 0v96"></path><path d="M8 8l16 12" stroke-width="2"></path></svg></div></div><div class="zoom-cluster" style="position:absolute;inset-block-end:10px;inset-inline-start:10px"><button type="button" aria-label="Zoom out"><svg class="icon" viewBox="0 0 16 16"><path d="M4 8h8"></path></svg></button><button type="button">100%</button><button type="button" aria-label="Zoom in"><svg class="icon" viewBox="0 0 16 16"><path d="M8 4v8M4 8h8"></path></svg></button></div><div style="position:absolute;inset-block-start:10px;inset-inline-end:10px"><button type="button" class="btn-tips"><svg class="icon icon-20" viewBox="0 0 20 20" aria-hidden="true"><path d="M7.5 15.5h5M8.5 17.8h3M10 2.2a5 5 0 0 1 3 9c-.6.5-.9 1.1-.9 1.8H7.9c0-.7-.3-1.3-.9-1.8a5 5 0 0 1 3-9Z"></path></svg>Tips</button></div></div></div>
```

Switch to RTL: the parameters rail moves to the right, labels and controls swap sides in every row, the slider fills the other way, the switch knob travels -16px, and the zoom cluster and the Tips capsule swap corners. All of that is interface, and it mirrors. **The artboard stays put.**

**Canvas content is never mirrored.** Lock the layer that holds the artboard to `direction: ltr`; the logical properties inside always resolve to the left, so the artboard's orientation and the exported file's are independent of the interface around them. The lock stops at the artboard: **the overlays on the canvas are interface, not artifact**, so they mirror with everything else — in RTL the zoom cluster and the Tips capsule belong on the mirrored side. Locking the whole canvas region would strand a right-to-left reader's controls on the wrong edge.

## What changes, item by item

- The slider's webkit fill uses `linear-gradient(to right …)` and needs `to left` in RTL.
- The drag-to-change direction inverts: dragging toward the start edge increases the value.
- A dropdown positioned by JS aligns to the trigger's **end** edge rather than copying `left`.
- Do not centre a floating hint with `inset-inline-start: 50%` plus `translateX(-50%)`; use `inset-inline: 0; margin-inline: auto`.
- The progress bar's `transform-origin` switches sides.
- The switch knob starts from `inset-inline-start` but travels with `translateX(16px)`; `transform` is physical, so RTL needs `-16px`.
- A number and its unit read as one run. In an RTL paragraph direction "6 mm" reorders to "mm 6". A numeric field is safe — its unit is a separate element pinned to the end — but a readout that concatenates them, like the value beside a slider, takes `unicode-bidi: plaintext`. Any transform that means "move forward" has to decide its own direction.

Set `dir="rtl"` and walk the whole flow before submitting.

---

# Accessibility

The floor, not the ceiling:

- **Every interactive target is at least 24×24px** (WCAG 2.2 SC 2.5.8), and the templates hold to it with none left over. Check the width too — icon-only buttons are square. Where the visual is deliberately smaller — the 20px switch track, the 12px slider thumb, an 11px text link — the templates keep the visual size and grow the **hit area** with padding plus an equal negative margin, so the target reaches 24 without the row getting taller. `--min-target` is the value they all reference; change it in one place and every one of them follows.
- **Verify contrast per pairing, never assume it.** Recompute the key pairings after a reskin, including the worst case of small text on the control fill. `text-tertiary` sits below AA by design, so it never carries a value, a message, or a label a decision rests on.
- **Keyboard reaches everything a mouse reaches**, in visible order. Dialogs trap focus while open and return it to the trigger on close. A hand-built listbox owes the contract a native `<select>` gives away; see [Components](/docs/design/components).
- **[hidden] needs restoring.** Any component that sets `display: flex` or `grid` overrides the browser default `[hidden] { display: none }`. Ship `[hidden] { display: none !important }` in the base stylesheet — a collapsed panel leaking into view is usually this.
- **Meaning never rides on colour, shape or motion alone.** A red border needs a message; a spinner needs text; a selected thumbnail needs its ring, not just a tint.

---

# Rules

The conclusions of the previous chapters, compressed into something you can check line by line. The first part is the contract at the top of `design.md`; the second is the self-check at the end of it, which an agent should run against its own output and fix before submitting.

## Ten rules

```html
<div class="rules"><div class="rule"><b>1</b>The layout starts from one of the five templates. Refine it and combine blocks across layouts freely — but keep the skeleton: rails are fixed-width, the canvas takes everything else.</div><div class="rule"><b>2</b>The parameters rail is 320px; parameters live in property cards; export is pinned to the rail's bottom.</div><div class="rule"><b>3</b>View tabs sit top-centre of the canvas, the tips button top-end, the zoom cluster bottom-start.</div><div class="rule"><b>4</b>Controls are 28 (inputs, selects), 32 (buttons, segmented, icon buttons), 40 (the one big call to action).</div><div class="rule"><b>5</b>Radii are 6 on controls, 8 on cards and panels, 12 on dialogs. No pills except the switch track and the Tips button.</div><div class="rule"><b>6</b>Inputs are grey-filled with no border; focus draws a 1px <code>stroke-active</code> border. Selection is a 2px brand ring, never colour alone.</div><div class="rule"><b>7</b>Panel text is 12px; only buttons and rail headings are 14px. No raw hex — every colour is a <code>--color-*</code> variable.</div><div class="rule"><b>8</b>Export goes through <code>data-atomm-export-button</code> and the <code>export</code> hook. No top bar of your own.</div><div class="rule"><b>9</b>Icons are inline stroked SVG. Every interactive target is at least 24×24 and shows a pointer cursor. Nothing conveys meaning by colour or motion alone.</div><div class="rule"><b>10</b>Nothing exceeds 200ms, nothing bounces, nothing animates on load.</div></div>
```

These ten cover most rejections. The skeleton (layout and sizes, as they render) must match; the skin (colour, type sizes) is a default you may replace as a set — changing values, never names; what the generator does is not the spec's business.

## Self-check

- The page is one of the five layouts; every rail width is 64 / 320 / 360 and the parameters rail is 320.
- View tabs are top-centre of the canvas, the Tips capsule top-end, the zoom cluster bottom-start; export is in the rail footer or the canvas's bottom-end corner and stays put while content scrolls.
- There is no top bar of your own and no second overlay layer; `z-index` never exceeds 3.
- Every control height is 24, 28, 32 or 40; inputs and selects are 28, buttons 32, the one large call to action 40.
- Every radius is 4, 6, 8, 12 or a true circle, except the bottom two corners of an expanded property card's header row, which are square; the switch track and the Tips button are the only capsules.
- Inputs are grey-filled with no border at rest, white with a 1px `stroke-active` border on focus, 92px wide; selects 110px.
- Parameters are inside property cards with a disclosure header; rows are `label ⋯ control` with 8/16 padding.
- No raw colour appears in component CSS; every colour is a `--color-*` variable and every hex in `:root` is in the palette (or your declared reskin).
- Panel text is 12px, buttons and rail headings 14px, thumbnail labels 11px, rail labels 10px (or your declared scale applied consistently).
- Selected states have a 2px brand ring or a checkmark, not colour alone; every error has a message beside its control.
- Every interactive target is at least 24×24; every icon-only button has an `aria-label`; every decorative icon is `aria-hidden`.
- Every control that reacts to a click shows `cursor: pointer`, every text field a caret, everything disabled `not-allowed`; a value readout keeps the default arrow.
- Icons are inline SVG with `stroke: currentColor`; no icon font is loaded.
- Sliders show their value as a number; switches are real checkboxes with `pointer-events: none` on their decoration; selects follow the combobox contract or are native.
- Nothing animates longer than 200ms, nothing animates on load, and `prefers-reduced-motion` zeroes every duration.
- `data-atomm-export-button` exists and the `export` lifecycle hook is registered; the exported file is 1:1 in mm.
- The flow works with `dir="rtl"`: rails, overlays, slider fill and switch knob all mirror; the canvas content does not.
- Below 960px the regions stack, the canvas comes first, export stays pinned, and there is no horizontal scrolling.

## Do's and don'ts

### Layout

- **Do** pick one of the five templates and keep its regions and widths.
- **Do** put export where the template puts it — rail footer, or bottom-end of the canvas.
- **Don't** add a top bar, a second overlay layer, or a column for derived results.
- **Don't** put a Generate button on a live-preview generator.

### Controls

- **Do** group parameters into property cards with a disclosure header and `label ⋯ control` rows.
- **Do** keep the state set closed; a control that seems to need a ninth state needs rethinking.
- **Do** write out the keyboard and screen-reader contract before replacing a native control, then repay it item by item.
- **Don't** give inputs a border at rest, and don't use native spinners.
- **Don't** fill a destructive button with red; use the secondary shell with `red-default` text and a confirmation.
- **Don't** let a decorative layer take pointer events away from the control underneath it.

### Colour and type

- **Do** reference `--color-*` variables everywhere; a raw hex in a component is a bug.
- **Do** keep the ground (`bg-editor`) darker than the panels, and white cards on the panels.
- **Do** recompute the text steps against every surface if you reskin.
- **Don't** invent a size between the export's steps; move the whole field register from `12-regular` to `14-regular`, or leave it.
- **Don't** convey state by colour alone — a selected thumbnail has a ring, an error has a message.

### Engineering

- **Do** give a panel that fills its space *and* scrolls both `flex: 1` and `min-height: 0` — one without the other is the overflow bug.
- **Do** mount popovers on `body` with `position: fixed`.
- **Do** inline icons as stroked SVG and inherit their colour.
- **Don't** rely on a classic scrollbar taking no space; use a thin one.
- **Don't** animate a layout property (width, height, inset); `opacity`, `transform` and colour are the safe set.