Atelier for gpui
Do not copy workarounds. If existing code wraps an Atelier component (a div with a
debug_selector, a hand-made tab stop) or copies a component's sizes and colours, do not
imitate it, even when it is right next to what you are writing: it predates a feature.
Use the component and its hook, and check with tools/check-adoption.sh (see
references/adopting.md).
Atelier is a Rust crate (atelier, gpui =0.2.2) that supplies one design language in three
candidate directions and the components that draw it. Glass is the adopted direction and
the default; Studio and Mono remain as alternatives, so never assume one look — read the tokens.
Read this page fully, then the reference for the part you touch.
| Read |
When |
| references/rules.md |
Always before writing or reviewing UI. The design rules and the review checklist. |
| references/choosing.md |
Deciding which control a concept gets: on/off, one of several, an amount, text, a command, a state — and what has no component yet. |
| references/tokens.md |
Choosing a colour, size, radius, spacing step, font, or a direction. |
| references/components.md |
Using buttons, controls, knobs, meters, layout containers, forms and preferences, keyboard focus, menus, node graphs, welcome-screen backdrops. |
| references/agent.md |
Anything that shows the AI: panel, transcript, tool calls, approvals, composer, entry points. |
| references/motion.md |
Animating anything, including handing one screen to the next; showing progress, loading or long-running tasks. |
| references/visualization.md |
Plots for sound: spectra, waveforms, spectrograms, vectorscopes, physical-model views. |
| references/plotting.md |
Plots for numbers on labelled axes: line, scatter, stem, histogram, fields with contours, 3-D surfaces, curves and point clouds. |
| references/app-icons.md |
Making or reviewing an app's icon or logo: the two-letter element mark. |
| references/adopting.md |
Adding Atelier to an app, or migrating an existing gpui UI (e.g. Auris Studio) onto it. |
Before writing code, look at the crate itself (src/ of the atelier dependency, or this
repository) and at the examples that compose it into whole screens: showcase (a DAW and the
component catalogue), agent_desktop (a coding-agent app), instrument_lab (physical-model
views), visualizer (analysers), node_editor (a ComfyUI-style node graph), plot_lab
(MATLAB-style 2-D and 3-D plots), training_dashboard (a TensorBoard-style training
dashboard with a Gradio-style inference playground), ambient (a welcome screen over liquid metal or an
ambient scene: aurora, silk dunes, clouds of colour, caustics, a low sun, a galaxy, jellyfish,
a shoal of fish, a formation of light points or a growing garden) and
auris_screens (Auris's project chooser and AI compose
window, with the hand-off between them) preferences (a settings window: pages, forms,
status bar, keyboard navigation) and control_legend (every concept beside the control that
handles it, as in references/choosing.md).
Do not invent a builder method because its name seems plausible: check the source.
Non-negotiables
- Tokens, never literals. Read
cx.theme() (use atelier::ActiveTheme). No rgb(...),
hsla(...) or hex in application UI; the only exceptions are document data such as a track's
own colour. Sizes come from theme.density, theme.spacing, theme.shape,
theme.typography; a missing role is added to the theme, not hard-coded at the call site.
- One primary per decision area.
Button::primary() is the default commit (the Enter
action), not "the important-looking button".
- The AI has one colour.
colors.agent / agent_wash / ButtonVariant::Agent /
Tone::Agent mark only what the agent did or is doing. Never use them for decoration.
- State is never colour alone. Pair status colour with a mark, an icon or a word
(
AgentStatus::mark, badges with labels).
- Selection is the item's own fill, never a leading edge bar.
- Desktop, not web. Arrow cursor on controls; visible menus for secondary commands;
every icon-only button has a
.tooltip(...) when its meaning is not obvious.
- Keyboard reach. Every control is reachable with Tab and pressed with Enter/Space; build
on Atelier's components (they do it) and never on a bare
div with on_click. A
single-key shortcut never fires on a focused control (key context AtelierControl).
- Extend, don't copy. If Atelier lacks an icon, slot or hook, use its open doors
(
IconSource, .control(..), a container's .id(..), TitleBar::window_controls) or add
it here; never re-implement a component by copying its sizes and colours.
- Every direction, both appearances. Check a change under Studio, Glass and Mono in light
and dark (
cargo run --example showcase -- --direction glass --appearance light).
Finish by running the review checklist in references/rules.md.
1---2name: atelier-gpui3description: Design language and component kit for gpui (Rust) creator tools with built-in AI agents — themes/tokens, buttons, controls, knobs, meters, layout, the agent side panel, chat transcript, tool calls, approvals and composer, audio visualisations, 2-D and 3-D plots (wgpu-shaded), node-graph editors, and welcome-screen backdrops (liquid metal, ambient scenes, palettes). Use when building, redesigning or reviewing gpui UI that depends on the `atelier` crate (Auris Studio and other gpui creator apps), when adding an AI assistant panel or chat to a gpui app, or when asked which design candidate (Studio, Glass, Mono) or token to use, or when making an app icon or logo (two-letter element marks such as Auris Studio's "Au"). Do not use for non-gpui UI.4metadata:5 source: https://skillmd.com/skills/uthree/atelier-gpui6---78# Atelier for gpui910> **Do not copy workarounds.** If existing code wraps an Atelier component (a `div` with a11> `debug_selector`, a hand-made tab stop) or copies a component's sizes and colours, do not12> imitate it, even when it is right next to what you are writing: it predates a feature.13> Use the component and its hook, and check with `tools/check-adoption.sh` (see14> [references/adopting.md](references/adopting.md)).1516Atelier is a Rust crate (`atelier`, gpui `=0.2.2`) that supplies one design language in three17candidate **directions** and the components that draw it. **Glass is the adopted direction** and18the default; Studio and Mono remain as alternatives, so never assume one look — read the tokens.19Read this page fully, then the reference for the part you touch.2021| Read | When |22| --- | --- |23| [references/rules.md](references/rules.md) | Always before writing or reviewing UI. The design rules and the review checklist. |24| [references/choosing.md](references/choosing.md) | Deciding which control a concept gets: on/off, one of several, an amount, text, a command, a state — and what has no component yet. |25| [references/tokens.md](references/tokens.md) | Choosing a colour, size, radius, spacing step, font, or a direction. |26| [references/components.md](references/components.md) | Using buttons, controls, knobs, meters, layout containers, forms and preferences, keyboard focus, menus, node graphs, welcome-screen backdrops. |27| [references/agent.md](references/agent.md) | Anything that shows the AI: panel, transcript, tool calls, approvals, composer, entry points. |28| [references/motion.md](references/motion.md) | Animating anything, including handing one screen to the next; showing progress, loading or long-running tasks. |29| [references/visualization.md](references/visualization.md) | Plots for sound: spectra, waveforms, spectrograms, vectorscopes, physical-model views. |30| [references/plotting.md](references/plotting.md) | Plots for numbers on labelled axes: line, scatter, stem, histogram, fields with contours, 3-D surfaces, curves and point clouds. |31| [references/app-icons.md](references/app-icons.md) | Making or reviewing an app's icon or logo: the two-letter element mark. |32| [references/adopting.md](references/adopting.md) | Adding Atelier to an app, or migrating an existing gpui UI (e.g. Auris Studio) onto it. |3334Before writing code, look at the crate itself (`src/` of the `atelier` dependency, or this35repository) and at the examples that compose it into whole screens: `showcase` (a DAW and the36component catalogue), `agent_desktop` (a coding-agent app), `instrument_lab` (physical-model37views), `visualizer` (analysers), `node_editor` (a ComfyUI-style node graph), `plot_lab`38(MATLAB-style 2-D and 3-D plots), `training_dashboard` (a TensorBoard-style training39dashboard with a Gradio-style inference playground), `ambient` (a welcome screen over liquid metal or an40ambient scene: aurora, silk dunes, clouds of colour, caustics, a low sun, a galaxy, jellyfish,41a shoal of fish, a formation of light points or a growing garden) and42`auris_screens` (Auris's project chooser and AI compose43window, with the hand-off between them) `preferences` (a settings window: pages, forms,44status bar, keyboard navigation) and `control_legend` (every concept beside the control that45handles it, as in [references/choosing.md](references/choosing.md)).46Do not invent a builder method because its name seems plausible: check the source.4748## Non-negotiables4950- **Tokens, never literals.** Read `cx.theme()` (`use atelier::ActiveTheme`). No `rgb(...)`,51 `hsla(...)` or hex in application UI; the only exceptions are document data such as a track's52 own colour. Sizes come from `theme.density`, `theme.spacing`, `theme.shape`,53 `theme.typography`; a missing role is added to the theme, not hard-coded at the call site.54- **One primary per decision area.** `Button::primary()` is the default commit (the Enter55 action), not "the important-looking button".56- **The AI has one colour.** `colors.agent` / `agent_wash` / `ButtonVariant::Agent` /57 `Tone::Agent` mark only what the agent did or is doing. Never use them for decoration.58- **State is never colour alone.** Pair status colour with a mark, an icon or a word59 (`AgentStatus::mark`, badges with labels).60- **Selection is the item's own fill**, never a leading edge bar.61- **Desktop, not web.** Arrow cursor on controls; visible menus for secondary commands;62 every icon-only button has a `.tooltip(...)` when its meaning is not obvious.63- **Keyboard reach.** Every control is reachable with Tab and pressed with Enter/Space; build64 on Atelier's components (they do it) and never on a bare `div` with `on_click`. A65 single-key shortcut never fires on a focused control (key context `AtelierControl`).66- **Extend, don't copy.** If Atelier lacks an icon, slot or hook, use its open doors67 (`IconSource`, `.control(..)`, a container's `.id(..)`, `TitleBar::window_controls`) or add68 it here; never re-implement a component by copying its sizes and colours.69- **Every direction, both appearances.** Check a change under Studio, Glass and Mono in light70 and dark (`cargo run --example showcase -- --direction glass --appearance light`).7172Finish by running the review checklist in [references/rules.md](references/rules.md).