ouroboros-ui — Documentation

Token-first design system for egui — the shadcn/ui design language reimplemented natively in Rust. Not a web port: same vocabulary (semantic tokens, neutral zinc aesthetic, 4px scale), egui-native immediate-mode rendering.

This is the full documentation set: how the system is built, how to use it, and a reference page for every component.

▶ Live storybook — every component and token, running in your browser (WebAssembly). Source: examples/storybook.rs.

Start here

Foundation reference

Component reference

Every component has its own page under components/, grouped by layer:

• Atoms — 23 leaf components that paint with tokens only.
• Cells — 7 row/item building blocks.
• Molecules — 14 compositions of atoms.
• Organisms — 14 full UI sections.
• Graph — the node-editor peer layer (reactflow-style on egui::Scene).

See the component catalog for the complete index.

Run the storybook

The storybook is the living visual reference — every token and component rendered, with a Dark/Light mode toggle.

cd ouroboros-ui
cargo run --example storybook

At a glance

• egui / eframe 0.34.1 · egui_extras 0.34 · egui-phosphor 0.12 (Light variant)
• Rust pinned to 1.92.0 (rust-toolchain.toml)
• Standalone crate — zero coupling to the Ouroboros monorepo workspace
• License: MIT © Type Zero Labs

Usage

How to depend on, bootstrap, and call ouroboros-ui.

Add the dependency

The crate is standalone (its own workspace) and not yet published to crates.io. Depend on it by git (or path, if vendored as a sibling):

[dependencies]
ouroboros-ui = { git = "https://github.com/type-zero-labs/ouroboros-ui" }
# or, vendored locally:
ouroboros-ui = { path = "../ouroboros-ui" }

You also need egui/eframe at the matching minor (0.34); the toolchain is pinned to Rust 1.92.0 (rust-toolchain.toml).

Bootstrap the theme

Install the theme once when the egui context exists (in eframe::App setup). This registers the bundled fonts and applies the palette — without it, text falls back to egui defaults and Theme::get returns Theme::default().

#![allow(unused)]
fn main() {
use eframe::egui;
use ouroboros_ui::{Mode, Theme};

struct App { mode: Mode }

impl App {
    fn new(cc: &eframe::CreationContext<'_>) -> Self {
        Theme::install(&cc.egui_ctx, Mode::Dark);   // fonts + palette, once
        Self { mode: Mode::Dark }
    }
}
}

Switch mode at runtime with apply (no font re-registration):

#![allow(unused)]
fn main() {
if toggled {
    self.mode = match self.mode { Mode::Dark => Mode::Light, Mode::Light => Mode::Dark };
    Theme::apply(ctx, self.mode);
}
}

See theming.md for the four palettes and what install/apply touch.

The builder pattern

Every component — atom to organism — follows the same shape:

#![allow(unused)]
fn main() {
Component::new(required_args)
    .setter(value)   // chainable, returns Self
    .show(ui)        // consumes self, paints, returns egui::Response
}

So call sites read top-to-bottom and optional props are explicit:

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::{Button, ButtonVariant};
use ouroboros_ui::egui_phosphor::light::FLOPPY_DISK;

let resp = Button::new("Save")
    .variant(ButtonVariant::Default)
    .icon_left(FLOPPY_DISK)
    .show(ui);

if resp.clicked() {
    // …
}
}

Many components offer shorthand setters in addition to the generic one — e.g. Button::new("x").secondary().sm() is the same as .variant(ButtonVariant::Secondary).size(Size::Sm). Check each component page.

Importing

Components are grouped by layer; pull from the layer module:

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::{Button, Input, Text, Icon, Badge, Switch};
use ouroboros_ui::cells::{ListItem, PropertyRow, MenuItem};
use ouroboros_ui::molecules::{Field, Card, Alert, Tabs, RadioGroup};
use ouroboros_ui::organisms::{Splitter, PanelSpec, Dialog, Table, TreeView, Toast};
}

Foundation re-exports live at the crate root:

#![allow(unused)]
fn main() {
use ouroboros_ui::{Mode, Size, Theme};                 // common
use ouroboros_ui::theme::typography;                   // type styles
use ouroboros_ui::tokens::{core, layout};              // primitives
use ouroboros_ui::auto_layout::{AutoLayout, MainAlign, CrossAlign};
use ouroboros_ui::egui_phosphor::light;                // icon glyphs
}

Common recipes

A labelled form field

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Field;
use ouroboros_ui::atoms::Input;

Field::new("Display name")
    .hint("Shown to other players")
    .show(ui, |ui| { Input::new(&mut self.name).show(ui); });
}

A toolbar row with a trailing action

#![allow(unused)]
fn main() {
use ouroboros_ui::auto_layout::{AutoLayout, CrossAlign};

AutoLayout::horizontal()
    .gap(core::SPACE_2).cross_align(CrossAlign::Center)
    .hug(|ui| { Text::new("Scene").role(TextRole::Heading).show(ui); })
    .fill(|ui| {})                                  // spacer
    .hug(|ui| { Button::new("Add").sm().show(ui); })
    .show(ui);
}

Reading the theme in your own widget

#![allow(unused)]
fn main() {
let theme = Theme::get(ui);
let stroke = egui::Stroke::new(core::BORDER_THIN, theme.border);
}

Prefer composing existing atoms over painting yourself — and if you do paint custom chrome, you are effectively writing an atom, so it must use tokens (see guards.md).

Run / develop

cd ouroboros-ui
cargo run --example storybook   # the living visual reference
cargo test                      # unit tests + the two atomic-design guards
cargo fmt                       # CI runs `cargo fmt --check`
cargo clippy

Before pushing: run cargo fmt — the project’s CI checks formatting and will fail an unformatted branch.

Architecture

ouroboros-ui is built in seven layers. The lower three are tokens (data); the upper four are components (atomic design). The single rule across the whole stack: a layer may reference the layer below it, and nothing below knows the layer above.

┌─────────────────────────────────────────────────────────────┐
│  organisms   splitter, dialog, table, tree_view, toast…      │  full UI sections
│      ↓ compose                                                │
│  molecules   field, card, alert, tabs, radio_group…          │  compositions of atoms
│      ↓ compose                                                │
│  cells       list_item, menu_item, property_row, table_row…  │  row/item building blocks
│      ↓ compose                                                │
│  atoms       button, input, text, icon, surface, badge…      │  leaf widgets (paint here)
│      ↓ read                                                   │
│  component   ButtonTokens, BadgeTokens…  (tokens::component)  │  per-component overrides
│      ↓ read                                                   │
│  semantic    Theme { background, primary, border, ring… }    │  shadcn vocabulary
│      ↓ read                                                   │
│  core        ZINC_950, SPACE_4, RADIUS_MD, TEXT_BASE…        │  raw primitives (const)
└─────────────────────────────────────────────────────────────┘

  ┌── graph ──┐  peer layer (node editor on egui::Scene) — reads the same tokens,
  └───────────┘  but is the one place outside atoms allowed to paint. See below.

The crate root re-exports the four most-used names so consumers don’t reach deep:

#![allow(unused)]
fn main() {
pub use theme::typography::{TypeStyle, Weight};
pub use theme::Mode;
pub use tokens::core::Size;
pub use tokens::semantic::Theme;
pub use egui_phosphor; // icon glyphs, no separate dependency
}

The token layers (data)

1. core — raw primitives

src/tokens/core.rs. Pure consts with no meaning: the Zinc neutral ramp (50→950), the Teal brand ramp (200→600), status hues, the 4px spacing scale, radius scale, shadows, type sizes, control/icon sizing, motion durations + easing, opacity.

Nothing here references anything. It is a leaf. The only non-trivial logic is the Easing curve math and two helpers (disabled_color, hover_t) that every atom shares so state transitions are identical. See tokens.md.

2. semantic — the shadcn vocabulary

src/tokens/semantic.rs. The Theme struct maps shadcn’s semantic names (background/foreground, primary, muted, accent, destructive, border, ring, plus domain status pairs) onto core primitives. No raw colors live here — every field is a core::* reference. Four palettes: dark(), light(), zinc_dark(), zinc_light(). See theming.md.

3. component — per-component overrides

src/tokens/component.rs. A thin struct per component holding the exact values it paints with, derived from semantic (never from core). This lets one component be retuned — a denser button, a louder input focus — without touching global tokens. ButtonTokens and BadgeTokens are the worked examples; most components default straight to semantic tokens and never need a struct here.

The component layers (atomic design)

4. atoms

src/atoms/. The smallest components — the only layer allowed to paint primitives (painter.rect_filled, galley, etc.). Each atom is a builder that paints exclusively with foundation tokens; no hardcoded colors, sizes, radii, fonts, or motion. An atom may compose smaller atoms (e.g. Button composes Icon + Text).

5. cells

src/cells/. Compound row/item building blocks that sit between molecules and organisms — a property row, a list/menu/tree item, a table row, a toolbar button. Cells compose, never paint.

6. molecules

src/molecules/. Components composed only from atoms (and smaller molecules) plus auto_layout. Molecules compose, never paint.

7. organisms

src/organisms/. Full UI sections composed from cells, molecules, and atoms. Overlay organisms use egui containers for placement: Dialog → Modal, Toast → Area, Popover/DropdownMenu/Select/Menubar → Popup::menu. The casing is either a token Surface atom (Toast, Toolbar, bordered Table) or themed egui visuals driven by Theme tokens (the Modal/Popup-based ones) — placement is egui’s job, the look is always tokens.

graph — the node-editor peer layer

src/graph/. A peer layer beside the four above — a reactflow-style node editor (GraphView) built on egui::Scene. It is the one place outside atoms that paints: a node graph needs grid dots, bezier wires, handle circles and a marquee, none of which the atom vocabulary covers. The atomic-design rules don’t fit it, so it has its own invariant instead — paint, but only through tokens:

• It may call the painter, but every value still flows through a token (colors from Theme resolved into GraphTokens, geometry from core). The no_raw_values guard is extended to scan src/graph, so it has the same purity contract as atoms.
• The no_painter_in_molecules guard deliberately skips it — painting here is allowed.

Internally it splits into a paint tier (viewport/grid/edge/handle/resizer) and a compose tier (node/controls/minimap/toolbar/search, which reuse Surface + atoms). And it follows a data-model-agnostic contract: the caller owns the node/edge data, the library owns only view-state and reports back intents. Full docs: components/graph.

The primordial law

An organism is built only from molecules and atoms. A molecule is built only from atoms and smaller molecules. Nothing above the atom layer hand-rolls a primitive — if a piece needs painting, it becomes an atom first.

This is not a style preference; it is mechanically enforced by two test guards that run with cargo test:

• tests/no_raw_values.rs — scans src/atoms/** and src/graph/**, fails on hardcoded Color32::from_rgb, named Color32 constants, or raw FontId::new. Atoms (and the graph layer) must source colors from Theme/core and fonts from theme::typography.
• tests/no_painter_in_molecules.rs — scans src/cells/**, src/molecules/**, src/organisms/**, fails on any painting call (ui.painter(), .rect_filled(), .circle_stroke(), Shape::*, …). Above atoms you compose; you never paint. src/graph is deliberately not scanned — it is the sanctioned exception that paints (still via tokens, enforced by no_raw_values).

The consequence: the missing-piece-becomes-an-atom discipline keeps the atom set complete and every higher layer pure composition. See guards.md.

Why a Rust/egui design system at all

The Ouroboros Studio (authoring IDE) and the engine HUD are both egui apps. A shared, token-driven component library means:

• One visual language across engine HUD and studio chrome (the auto_layout module even mirrors the engine HUD’s LayoutDirection/MainAlign/SizeMode vocabulary).
• Theme-able — swap Mode::Dark/Light (or the zinc-neutral variants) at runtime with no consumer changes, because everything resolves through Theme::resolve.
• Auditable — the guards make “did someone hardcode a color” a CI failure, not a code-review judgment call.

Builder pattern everywhere

Every component, at every layer, follows the same shape:

#![allow(unused)]
fn main() {
Component::new(required_args)
    .setter(value)   // chainable, returns Self
    .setter(value)
    .show(ui)        // consumes self, paints, returns egui::Response
}

This gives fluent call sites, makes optional props obvious, and keeps the return value a plain egui::Response so components drop into any egui layout. See usage.md.

Standalone by design

ouroboros-ui is its own cargo workspace with zero dependency on the parent monorepo. It can be cloned, built, and storybooked in isolation. The trade-off: shared vocabulary with the engine HUD (auto_layout) is re-declared, not imported, to avoid the coupling.

Tokens — core primitives

src/tokens/core.rs. The bottom layer: raw const values with no semantic meaning. The semantic layer maps meaning onto these; nothing here references anything else. Every value was decided interactively, value-by-value, against shadcn.

Design rule: atoms never read a raw hex. They read either a core::* primitive (for structural values like spacing/radius) or a Theme field (for colors). The no_raw_values guard enforces it.

Color ramps

Neutral base — Zinc (cool-neutral)

The temperature of every gray surface/border/text token. Tailwind/shadcn zinc, 50→950.

Brand — Ouroboros turquoise (Teal)

The primary hue: buttons, progress/slider fill, switch-on, focus ring, selection. Kept light (300/400 in dark) per brand. The zinc ramp is left untouched, so a pure-zinc theme stays available (see Theme::zinc_dark).

Status hues — Tailwind 500

The semantic layer composites the soft *_bg variants by applying ~15% alpha (STATUS_BG_ALPHA = 38) to these.

Spacing — 4px base

Tailwind numeric keys (key N = N × 4px). Contiguous 1–6, then 8/10/12 for larger gaps. Used for padding, gaps, margins.

SPACE_0 is the semantic “no gap / no padding” sentinel (tight tables, full-bleed).

Corner radius

shadcn classic base (0.5rem). FULL is the pill/circle sentinel.

RADIUS_NONE is the “square corners” sentinel (full-bleed rows, flush panels).

Shadows

Dark-tuned (high alpha to read on the zinc background).

shadow(offset, blur, spread, color) is a const fn builder for elevations beyond the fixed triple (egui’s Shadow is foreign, hence a free fn not an inherent constructor).

Typography primitives

Raw values only — the typography layer composes these into named styles.

Type sizes (px) — dense IDE calibration; body anchors at TEXT_BASE (14).

Line-height multipliers (× font size): LEADING_TIGHT 1.2 (headings/display), LEADING_NORMAL 1.45 (body), LEADING_RELAXED 1.6 (long-form).

Letter-spacing (px) — scale is inverse to size for legibility (big titles stay NORMAL, smaller text gets wider tracking): TRACKING_TIGHT −0.25, TRACKING_NORMAL 0, TRACKING_SM 0.4, TRACKING_MD 0.6, TRACKING_LG 0.8, TRACKING_WIDE 1.0.

Sizing

Control heights — CONTROL_SM 26 · CONTROL_MD 32 · CONTROL_LG 38. Icon box — ICON_SM 14 · ICON_MD 16 · ICON_LG 20 · ICON_XL 24. Strokes — BORDER_THIN 1 (divider) · BORDER_FOCUS 2 (focus ring) · RING_OFFSET 2 (gap to ring). Hit target — HIT_MIN 32 (minimum interactive size).

Size enum — the shared control scale

One source of truth for every form control’s footprint, so density (compact toolbar vs. roomy panel) is expressible uniformly.

#![allow(unused)]
fn main() {
pub enum Size { Sm, Md /* default */, Lg }
}

¹ defined in theme::typography (keeps core a leaf — see typography.md).

Motion

Animation durations (seconds) + easing curves. egui drives hover/focus transitions by duration (ctx.animate_*); Easing shapes the progress.

Durations — DURATION_INSTANT 0 · DURATION_FAST 0.10 · DURATION_NORMAL 0.18 · DURATION_SLOW 0.30. Delays — DURATION_DELAY_SHORT 0.15 · DURATION_DELAY_LONG 0.50.

Easing enum

#![allow(unused)]
fn main() {
pub enum Easing { Linear, EaseOut /* default */, EaseInOut, Spring, Bounce }
}

Easing::apply(t) maps a normalized progress t ∈ 0..=1 through the curve.

Opacity & overlays

Shared helpers

Two functions every atom uses so state is identical everywhere:

#![allow(unused)]
fn main() {
/// Blend a color to its disabled appearance (alpha × OPACITY_DISABLED).
/// Atoms gate it behind `if !enabled` so the veil is applied exactly once.
pub fn disabled_color(c: Color32) -> Color32

/// Eased hover progress in 0..=1 for a widget — animates `hovered` over
/// DURATION_FAST, shaped by EaseOut. Pass a stable id (e.g. response.id).
pub fn hover_t(ctx: &egui::Context, id: egui::Id, hovered: bool) -> f32
}

These are the reason hover/disabled states look the same across the whole library: the math lives in one place, not copy-pasted into 23 atoms.

Theming — semantic tokens & modes

src/tokens/semantic.rs + src/theme/mod.rs. The semantic layer maps shadcn’s vocabulary onto core primitives; the theme layer resolves a palette for a Mode and installs it into the egui context.

No raw colors live in this layer. Every Theme field references a core::* primitive. That keeps the brand hue swappable in one place.

The Theme struct

A resolved palette — every color token the design system exposes. Grouped:

Surfaces (layered)

Dark mode layers the zinc ramp by elevation: background 950 → card/popover 900 → muted 800.

Interactive

Borders & focus

Status (solid + soft bg)

Each status has a solid hue and a soft *_bg (the hue tinted to ~15% alpha).

The four palettes

Theme::default() is dark().

Note on light mode: the crate README and a Mode doc-comment still describe Light as a “stub that resolves to Dark.” That is stale — Theme::light() is fully populated and Theme::resolve(Mode::Light) returns it. Light mode works today.

Mode & resolution

#![allow(unused)]
fn main() {
pub enum Mode { Dark /* default */, Light }
}

The system always resolves through Theme::resolve(mode) so a palette can change without touching consumers:

#![allow(unused)]
fn main() {
impl Theme {
    pub fn resolve(mode: Mode) -> Self;   // Dark => dark(), Light => light()
}
}

resolve covers the two Mode variants (dark/light). The zinc-neutral palettes are opt-in via the constructors directly — install them with apply after resolving, or store them yourself.

Installing the theme

Call once at startup, then optionally re-apply to switch mode at runtime.

#![allow(unused)]
fn main() {
use ouroboros_ui::{Mode, Theme};

// In eframe::App::new / setup:
Theme::install(ctx, Mode::Dark);   // registers fonts + applies the palette
}

install does two things:

1. typography::register(&mut fonts) — loads the bundled Iosevka faces + Phosphor icons.
2. Theme::apply(ctx, mode) — applies visuals, stores the resolved theme, sets text styles.

Switching mode at runtime

apply reapplies the palette without re-registering fonts — use it for a Dark/Light toggle:

#![allow(unused)]
fn main() {
Theme::apply(ctx, Mode::Light);
}

apply also flips egui’s own ThemePreference so built-in chrome (clear color, native scrollbars) follows the mode, and wires panel/window/extreme/faint fills + the five egui TextStyles (Heading→h2, Body/Button→body, Monospace→code, Small→caption).

Reading the theme inside a widget

Components fetch the installed theme from the context (falling back to Theme::default()):

#![allow(unused)]
fn main() {
let theme = Theme::get(ui);              // from a &Ui
let theme = Theme::get_from_ctx(ctx);    // from a &Context
}

The theme is stored in egui’s temp data under Id::NULL. Every atom calls Theme::get at the top of its show to know what to paint with — this is the mechanism that makes the whole library theme-reactive for free.

Adding a new semantic token

1. Add the field to Theme in semantic.rs.
2. Populate it in all four constructors (dark, light, zinc_dark, zinc_light), referencing only core::* — never a raw color (the guard will reject raw colors in atoms, and convention keeps semantic clean).
3. Consume it from an atom via Theme::get(ui).your_token.

If the value is component-specific (one button variant, one input state), prefer a tokens::component struct over a global semantic field — see architecture.md.

Typography

src/theme/typography.rs. Registers the bundled fonts and exposes composite type styles (family + size + line-height + tracking) for the named roles. Sizes and leadings come from core; this layer composes them into usable styles.

Faces

Two type families are vendored under assets/fonts/ and embedded with include_bytes!:

• Iosevka (UI) — five weights: Light, Regular, Medium, SemiBold, Bold.
• IosevkaTerm (code/keyboard) — Regular, Bold.
• Phosphor Light — icon glyphs, via egui-phosphor.

Each weight is registered under its own named FontFamily::Name, so a TypeStyle can target an exact face. The default Proportional stack is Iosevka Regular; Monospace is IosevkaTerm. Phosphor is appended as an icon fallback to every face, so inline icons resolve no matter which type style renders them.

#![allow(unused)]
fn main() {
pub enum Weight { Light, Regular, Medium, SemiBold, Bold }
}

Named type styles

Each function returns a TypeStyle { family, size, line_height, tracking }. Build an egui::FontId with .font_id(); the line-height and tracking are applied by the text atom when it lays out the galley.

Notes on the choices:

• Body and label default to Light, not Regular — the dense IDE aesthetic. Reach for the _strong (Medium) variants when a line needs to assert itself.
• Headings keep normal tracking; the smaller the text, the wider the tracking (legibility scale is inverse to size, defined in core).
• kbd is Bold mono because a Medium mono weight isn’t vendored, and Bold reads as a key cap anyway.

TypeStyle

#![allow(unused)]
fn main() {
pub struct TypeStyle {
    pub family: FontFamily,   // includes weight (named family)
    pub size: f32,
    pub line_height: f32,     // px = size × leading
    pub tracking: f32,        // extra px per glyph
}

impl TypeStyle {
    pub fn font_id(&self) -> FontId;   // family + size
}
}

line_height and tracking are not part of egui’s FontId, so they are carried on the TypeStyle and applied by the Text atom during layout. That is why text should go through the Text/Heading atoms rather than raw ui.label — only the atoms honor the full type style.

Icons

#![allow(unused)]
fn main() {
pub fn icon_font(size: f32) -> FontId;   // Phosphor glyph at `size`
}

Phosphor glyphs are PUA codepoints resolved via the proportional stack’s icon fallback. Atoms call icon_font instead of building a FontId by hand. Glyph constants come from the re-exported crate:

#![allow(unused)]
fn main() {
use ouroboros_ui::egui_phosphor::light::GEAR;   // a &'static str glyph
}

The Icon atom is the normal way to render one; the raw font is for atoms that fold an icon into a larger galley (e.g. Button).

The Size → type-style mapping

The mapping from the shared control Size scale to a type style lives here, not in core, so the token layer stays a leaf (theme may reference tokens, not the reverse):

#![allow(unused)]
fn main() {
impl Size {
    pub fn text_style(self) -> TypeStyle {
        match self {
            Size::Lg => body_strong(),       // roomy controls
            Size::Sm | Size::Md => label(),  // dense controls
        }
    }
}
}

Layout & auto-layout

Two pieces: layout tokens (src/tokens/layout.rs) — fixed dimensions and z-order roles a layout reads — and the AutoLayout engine (src/auto_layout.rs) — a Figma-style flow layout for egui.

Layout tokens

egui is immediate-mode (no CSS grid), so these are primitives a component or helper reads. Tune them to the real studio shell.

Panels (px)

Content grid

GRID_COLUMNS 12 · GRID_GUTTER 16 (= SPACE_4) · CONTAINER_MAX 1200 (max readable width before centering).

Breakpoints (window width, px)

Component-level thresholds: FIELD_HORIZONTAL_MIN 480 (a Field goes side-by-side at/above this, else stacks), PROPERTY_LABEL_WIDTH 120 (fixed label column for PropertyRow), TABLE_ROW_HEIGHT 28.

SizeClass

#![allow(unused)]
fn main() {
pub enum SizeClass { Compact, Normal, Wide }
SizeClass::from_width(available_width) -> SizeClass
}

Classifies an available width against the breakpoints (< NORMAL → Compact, < WIDE → Normal, else Wide) so a component can adapt density.

Layer — z-order roles

Stacking roles for floating surfaces, mapped onto egui::Order. Ordered base → tooltip.

#![allow(unused)]
fn main() {
pub enum Layer { Base, Dropdown, Popover, Modal, Toast, Tooltip }
}

egui’s order set is coarse; finer ordering within a layer is by creation/priority.

AutoLayout — Figma-style flow

A flexbox-like flow layout for egui that mirrors the exact vocabulary of the studio’s HUD model (ouroboros-hud::model) — LayoutDirection, MainAlign, CrossAlign, Gap, Padding, SizeMode — so designers get one mental model across the engine HUD and the studio UI. It is re-declared (not imported) to keep ouroboros-ui standalone.

Model

Padding — all(v) or symmetric(x, y); fields top/right/bottom/left.

Sizing — mode × min/max

Each child’s main-axis size is a Sizing: a mode plus optional min/max floors and ceilings (min wins over max, like the HUD solver). Constructors are const: Sizing::fixed(px) / ::hug() / ::fill(), then .min(px) / .max(px) / .clamped(min, max).

Hug measures content against the budget: a greedy child (one that expands to available_width) measures as the whole budget — for “should fill” controls use Fill (optionally clamped) instead of Hug.

Builder

#![allow(unused)]
fn main() {
AutoLayout::horizontal()  // or ::vertical()
    .gap(8.0)                          // fixed gap…
    .gap_auto()                        // …or space-between
    .gap_cross(8.0)                    // gap between wrapped lines (defaults to main gap)
    .pad(12.0)                         // .padding(Padding) / .pad_xy(x, y)
    .main_align(MainAlign::Center)
    .cross_align(CrossAlign::Center)
    .wrap()                            // reflow onto new lines (horizontal only)
    .allow_overflow()                  // opt out of budget clamping + cell clipping
    .fixed(28.0, |ui| { /* icon */ })  // child with fixed main size
    .fill(|ui| {})                     // flexible spacer / growing child
    .fill_min(220.0, |ui| {})          // fill that floors at 220px
    .fill_clamped(80.0, 160.0, |ui| {})// fill clamped to [80, 160]px
    .hug(|ui| { /* button */ })        // child sized to content
    .hug_max(240.0, |ui| {})           // hug capped at 240px
    .child(SizeMode::Fill, |ui| {})    // explicit form…
    .sized(Sizing::fill().min(120.0), |ui| {}) // …or with a prebuilt Sizing
    .show(ui) -> Response
}

Example — toolbar with a trailing button

#![allow(unused)]
fn main() {
AutoLayout::horizontal()
    .gap(8.0).pad(12.0).cross_align(CrossAlign::Center)
    .fixed(28.0, |ui| { Icon::new(GEAR).show(ui); })
    .fill(|ui| {})                 // spacer pushes the next child to the end
    .hug(|ui| { Button::new("Save").show(ui); })
    .show(ui);
}

Example — responsive columns (fill_min)

Two form columns that share the panel but never collapse below a readable width — when the panel is squeezed under 2 × 220 + gap, the cells keep their floors and the frame clips as a last resort instead of overlapping:

#![allow(unused)]
fn main() {
AutoLayout::horizontal()
    .gap(24.0)
    .fill_min(220.0, |ui| left_column(ui))
    .fill_min(220.0, |ui| right_column(ui))
    .show(ui);
}

Example — stat grid (wrap)

One row when wide, reflowing to 2–3 lines when narrow; each cell floors at 72px and the fills on a line share that line’s remainder:

#![allow(unused)]
fn main() {
AutoLayout::horizontal().wrap().gap(8.0).gap_cross(8.0)
    .fill_min(72.0, |ui| stat(ui, "STR"))
    .fill_min(72.0, |ui| stat(ui, "AGI"))
    // … 4 more cells
    .show(ui);
}

How it works

Child closures are FnMut: they run once invisibly to measure (a sizing_pass ui), then once for real at computed cells. The algorithm:

1. Measure pass A (bounded) — render each Fixed/Hug child invisibly, bounded on both axes by the frame’s budget (the available space), and clamp Hug by its min/max. Content can never measure wider than the panel it lives in.
2. Resolve Fill — distribute the leftover main-axis space among Fill children, min/max-aware: whoever clamps is pinned and its excess is redistributed among the rest (the HUD solver’s distribute_fill).
3. Measure pass B — measure each Fill child’s cross size at its resolved main size, so wrapping content (labels, alerts) reports its real height.
4. Container sizing — the frame never exceeds a finite budget: with Fill, Gap::Auto, or non-Start align it claims the available main axis; otherwise it hugs content, clamped to the budget.
5. Distribution — leftover space goes to: Auto → even gaps between children; Fill children → already consumed; otherwise → a start offset per MainAlign.
6. Render — allocate the frame, then place each child in an explicit cell rect. Each cell is clipped as a last resort (with a small bleed for focus rings): with correct sizing it never bites, it only stops legitimate overflow (e.g. floors inside a panel squeezed below their sum) from painting over siblings.

allow_overflow() opts out of both the budget clamp and the cell clipping — the legacy behavior, for the rare container that scrolls itself.

Wrap

wrap() (horizontal only) reflows children onto new lines when they don’t fit — Figma’s “wrap”. Line breaking is greedy over each child’s intrinsic contribution (Fixed/Hug → natural size, Fill → its min or 0), with at least one child per line; then each line is laid out like a non-wrapping row, so a Fill child takes the remainder of its line. Spacing between lines comes from gap_cross(px) (defaults to the main gap). Not supported by the rect-returning layout() path.

Responsive contract (anti-ratchet)

The frame’s budget comes from the parent — a Splitter panel rect, a window — which is exogenous to the content. Because measurement is bounded by that budget and never feeds back into it, layout is idempotent per frame: dragging a panel out and back yields the same rects, with no ratchet (content can’t “remember” the widest it ever was). Inside a scroll axis there is no finite budget; measurement is effectively unbounded there and Fill resolves to its floor.

Cost note: every child renders twice (measure + real). It is cheap for typical toolbar/row counts, but don’t nest deeply with heavy children in a hot per-frame path.

Governance — use first, extend second, create last

This is the law of the design system. architecture.md explains how the system is built; this page rules how it is consumed and grown. Every rule here is mechanically enforced (see Enforcement) — a violation is a red build, not a review nit.

The rule in one sentence

Studio UI is built from ouro_ds components. If a component is missing a capability, you contribute it to the DS — you never hand-roll raw egui chrome and never hardcode a color outside a canvas.

The studio (and every studio crate) is a consumer. The DS is the single place visual decisions live, so one fix retunes every screen, the Dark/Light toggle keeps working everywhere, and “did someone hardcode a color” stays a CI failure instead of a judgment call.

Decision ladder

When you need a piece of UI, walk this ladder top-down and stop at the first rung that works.

1. Use — the catalog first

The DS has 71 components across atoms → cells → molecules → organisms plus the graph peer layer. Before building anything, check whether it already exists:

• Component catalog — every component documented by layer, with design intent, API, and usage examples.

• The storybook — the living visual reference, every component and token rendered:

  cargo run --example storybook
  

Most “I need a custom widget” cases are an existing component plus a builder you hadn’t seen (Text alone has roles, .muted(), .color(), .wrap(), .underline(), .italic()).

2. Extend — a new builder on an existing component

If the component exists but lacks one capability, add a builder setter to it instead of forking or hand-rolling. Real example: the studio needed checkable View-menu rows; instead of ui.checkbox(..) inside a menu, MenuItem gained .checked(bool) — a check mark when true, a reserved slot when false so siblings stay aligned. One small PR, and every menu in every studio crate can now have toggle items.

An extension still walks the contribution pipeline below (tokens → storybook → test → doc), just scoped to the new setter.

3. Create — a new component

Only when use and extend genuinely don’t fit: the piece is a new shape, not a variant of an existing one. Follow the component contribution pipeline — starting with the spec-lite paragraph that says why the first two rungs were not enough.

What is forbidden in studio chrome

The studio’s ds_governance guard scans every studio crate and hard-fails on the patterns below. This table is the exact mirror of that guard — the substitution is always a DS component or a theme token.

ui.menu_button is allowed — as a container. egui owns the popup placement; the rows inside it are cells::MenuItem / atoms::Divider, never raw widgets.

Escapes

Two sanctioned escape hatches, both designed to be visible — never silent.

CANVAS_ALLOWLIST — content rendering is not chrome

Some studio modules render content: world viewport canvases, node-graph surfaces, sprite previews. There, a color is data (a tile’s terrain hue, an event wire), not a design decision — painting pixels is the feature. These paths are listed in the CANVAS_ALLOWLIST of the studio guard (crates/ouroboros-studio/tests/ds_governance.rs):

ouroboros-studio/src/modules/events/canvas.rs
ouroboros-studio/src/modules/interface/canvas.rs
ouroboros-studio/src/modules/world/ui/map_canvas/
ouroboros-level-editor/src/render/
ouroboros-sprite-studio/src/render/
ouroboros-visualizer/src/render/

Inside the allowlist, the color/paint class is exempt. The chrome class is not — a toolbar over a canvas is still built from DS components. A stale allowlist entry (file moved or renamed) fails the guard, so the list can’t rot.

// ds-allow: <reason> — the one-off escape

For a single legitimate exception, annotate the line (or the line directly above):

#![allow(unused)]
fn main() {
// ds-allow: egui demo window needs its own raw label for the comparison screenshot
ui.label("raw egui baseline");
}

The reason is mandatory — a bare ds-allow: is itself a violation. The annotation is the review trail: every escape is grep-able and visible in the diff, so a reviewer can challenge it.

Component contribution pipeline

How a new component (or an extension to one) enters the DS. The mad.component skill in claude-skills walks these steps guided.

0. Spec-lite

One paragraph: the concrete use case, and why use and extend are not enough. This goes in the PR description. If you can’t write the paragraph, you’re on the wrong rung of the ladder.

1. Pick the layer

• atom — it needs to paint primitives (fill, stroke, galley). Atoms are the only layer allowed to touch the painter.
• cell / molecule / organism — it composes existing pieces. These layers never paint — enforced by the no_painter_in_molecules guard. If you reach for a painter here, stop: the missing piece becomes an atom first.
• graph — the node-editor peer layer; paints, but only through tokens.

See architecture.md for the full layer model.

2. Tokens first

Any new visual value (a color, a spacing, a radius, an overlay alpha) becomes a token before it is used: a core primitive in src/tokens/core.rs, surfaced through a Theme field in src/tokens/semantic.rs if it carries meaning. Never a literal in the component — the no_raw_values guard rejects it.

3. Builder pattern

Every component, every layer, the same shape:

#![allow(unused)]
fn main() {
Component::new(required_args)
    .setter(value)   // chainable, returns Self
    .show(ui)        // consumes self, returns egui::Response
}

4. Storybook

Add an entry to the Page enum and a page (or extend the existing page) in examples/storybook.rs. Without a demo there is nothing to validate visually — and nothing for the next person walking rung 1 to find.

5. Test

A kittest test in tests/atoms.rs (or the layer’s suite): the Harness + Theme::install pattern — at minimum a smoke render, ideally an interaction or layout assertion.

6. Doc

A page in docs/components/<layer>/<name>.md following the page template, plus a line in the catalog index. For an extension: update the existing page’s API table.

7. Green build

cargo test                                  # includes the guards
cargo clippy --all-targets -- -D warnings
cargo fmt

8. Ship

PR against ouroboros-ui (develop) → merge → bump the ui/ submodule in the studio repo (with the follow-up studio PR adopting the new API, when applicable).

Enforcement

The ladder is not honor-system. Three layers of machinery:

The DS’s own guards (this repo, run in CI)

• tests/no_raw_values.rs — atoms and graph paint only with tokens: no literal Color32, no named color consts, no raw FontId / stroke / radius.
• tests/no_painter_in_molecules.rs — cells / molecules / organisms compose, never paint.

Both run with cargo test, and CI runs the full test suite — the guards are part of the gate, not optional extras. Details: guards.md.

The studio guard (consumer side)

crates/ouroboros-studio/tests/ds_governance.rs in the studio repo — hard fail, two classes:

1. Chrome class — the raw-widget patterns from the table above, scanned across every studio crate. Escape: // ds-allow: <reason>.
2. Color/paint class — literal Color32 values and FontId construction outside the CANVAS_ALLOWLIST.

Clippy disallowed_methods

The studio’s clippy.toml disallows the constructors clippy can resolve by path — egui::ComboBox::*, egui::DragValue::new, egui::Slider::new — so those are caught at lint time with a pointer back to this document. The guard test covers the method-call patterns (ui.label(..)-style) that clippy cannot.

Guards & conventions

The atomic-design rules are not honor-system — two test guards in tests/ enforce them, and they run with cargo test (so a violation is a red build, not a review nit). This page documents exactly what they catch and how to add a component without tripping them.

Guard 1 — atoms (and graph) paint only with tokens

tests/no_raw_values.rs → test atoms_use_only_tokens. Recursively scans src/atoms/**/*.rs and src/graph/**/*.rs and fails on any hardcoded design value. Comments are stripped first, so prose mentioning a pattern is fine.

The graph layer is allowed to paint (a node editor needs grid dots, wires, handles), but it is held to the same purity contract as atoms — its colors resolve from Theme (via GraphTokens) and geometry from core. That is why this guard scans it too.

The numeric checks are heuristic: tokens are named consts, so an argument starting with a letter or ( is accepted; a leading digit means a raw value and trips the guard. (Color32 as a bare type is fine — only Color32:: followed by an uppercase name or from_ is flagged.)

Sizes/radii/spacing passed positionally elsewhere aren’t all machine-checkable — those are caught in review. The guard covers the high-frequency mistakes.

Guard 2 — above atoms you compose, never paint

tests/no_painter_in_molecules.rs → test molecules_compose_never_paint. Scans src/cells/, src/molecules/, and src/organisms/ (despite the file name) and fails on any direct painting call:

ui.painter(   .painter()   rect_filled   rect_stroke   circle_filled
circle_stroke   layout_no_wrap   layout_job   .galley(   Shape::line
hline(   vline(

The rule: if a cell/molecule/organism needs to paint something, the missing piece becomes an atom (atoms are the only layer allowed to paint — see src/atoms/surface.rs, the painting primitive everything composes for fills/borders).

src/graph is deliberately not scanned by this guard. The node-editor layer is the sanctioned exception that paints directly (grid/wires/handles/marquee) — painting there is by design. It is still held to token purity by Guard 1, which does scan it.

The conventions behind the guards

1. Builder + show(ui) -> Response. Every component, every layer. Required args in new, optional props as chainable setters, show consumes self and returns an egui::Response.
2. Read the theme at the top of show. let theme = Theme::get(ui); — this is what makes a component react to mode switches for free.
3. State transitions go through the shared helpers. Hover via core::hover_t, disabled via core::disabled_color, so every component animates identically.
4. Domain extensions are marked. Where the system extends shadcn (status variants, Size densities), the addition is ours by intent — base variants/anatomy follow shadcn.
5. New component → storybook page. Every new component or variant gets an entry in examples/storybook.rs; without a demo there is nothing to validate visually.

Adding a component without tripping the guards

A new atom

1. src/atoms/<name>.rs — builder struct, show(self, ui) -> Response.
2. Source all colors from Theme::get(ui) / core::*, fonts from typography, strokes/radii from core::*. No Color32::from_, no FontId::new, no raw-digit Stroke::new/CornerRadius::same/.expand.
3. Animate state with core::hover_t / core::disabled_color.
4. Register in src/atoms/mod.rs (pub mod + pub use).
5. Add a storybook page.
6. cargo test (guard 1 must stay green) + cargo fmt.

A new cell / molecule / organism

1. File under the right layer dir; builder + show.
2. Compose atoms only — no painting calls from the forbidden list. If you reach for a painter, stop and extract an atom first.
3. Use auto_layout / egui layout for arrangement; use Surface (atom) for any fill/border/casing.
4. Overlay organisms place with egui Modal/Area/Popup; the casing is either a Surface atom or themed egui visuals driven by Theme tokens — never hand-painted.
5. Register in the layer mod.rs, add a storybook page, cargo test + cargo fmt.

Running the guards

cargo test                              # both guards + unit tests
cargo test --test no_raw_values         # atoms-only
cargo test --test no_painter_in_molecules

A failure prints every offending path:line with the suggested token, so fixes are mechanical.

Component catalog

60 components across four atomic-design layers, plus the graph peer layer (node editor). Each has its own page with design intent, anatomy, variants/states, API, and usage examples. Layer rules: atoms paint, everything above composes; the graph layer is the sanctioned exception that paints (still via tokens). See guards.

Atoms

23 leaf components — the only layer that paints primitives. Each is a token-driven builder.

Typography & content

• Text — body/label/caption text honoring the full type style
• Heading — display→h-levels titles
• Icon — a Phosphor glyph at a token size
• Kbd — keyboard key cap

Actions

• Button — the worked-example atom; 6 variants, 3 sizes, icons, loading
• Toggle — a pressable on/off button

Form controls

• Input — single-line text field
• Textarea — multi-line text field
• NumericField — numeric input with step
• Checkbox — boolean check
• Radio — single-choice dot
• Switch — on/off slider
• Slider — range selector

Display & feedback

• Badge — status/label pill
• Avatar — user image/initials
• Progress — determinate progress bar
• Spinner — indeterminate loading
• Skeleton — content placeholder
• Tooltip — hover hint

Structural

• Surface — the painting primitive (fill/border/radius/shadow) everything composes
• Divider — horizontal/vertical rule
• ColorSwatch — a painted color chip
• SplitterHandle — drag handle for resizable panels

Cells

8 compound row/item building blocks. Compose atoms; never paint.

• ListItem — selectable list row
• MenuItem — menu row (icon + label + shortcut)
• PropertyRow — inspector row (fixed label column + control)
• ResponsiveRow — inspector row that stacks label↔control when narrow
• TableCell — a single table cell with alignment
• TableRow — a row of table cells
• ToolbarButton — dense toolbar control
• TreeNode — tree row with expand/select

Molecules

14 compositions of atoms (and smaller molecules).

Forms

• Field — label + control wrapper (+ FieldGroup, FieldSet, FieldSeparator)
• InputGroup — input with prefix/suffix slots
• SearchField — input preset for search
• ColorField — color input field
• VectorField — multi-component numeric (x/y/z) field
• RadioGroup — grouped radios
• ToggleGroup — segmented toggle buttons
• CheckboxCard — checkbox as a selectable card
• RadioCard — radio as a selectable card

Containers & navigation

• Card — styled surface container
• Alert — inline banner (default/success/warning/error/info)
• Tabs — tab switcher (default/pill)
• Breadcrumb — navigation trail
• Collapsible — expand/collapse section

Organisms

14 full UI sections composed from cells, molecules, and atoms.

Layout shells

• Splitter — the single layout primitive: screen root + resizable panes (PanelSpec, with fixed(px) non-resizable chrome bands)
• Panel — docked panel chrome: bg + flush edge border + header/footer + padded scroll body (PanelEdge)
• Sidebar — navigation panel
• Toolbar — top/bottom tool bar
• Menubar — application menu bar

Overlays

• Dialog — modal dialog
• Popover — floating anchored surface
• DropdownMenu — menu in a popup
• Toast — transient notification
• Select — select/combo dropdown

Data & views

• Table — column-defined data table (Column, ColWidth)
• TreeView — hierarchical tree (TreeItem)
• TabView — tabbed content view
• Accordion — stacked collapsible sections (AccordionCtx)

Graph

The graph peer layer — a reactflow-style node editor on egui::Scene. The one place outside atoms that paints (still via tokens). Caller owns the data; the library owns view-state and reports intents.

• Graph layer overview — invariant, two tiers, data-model contract, lifecycle
• identity — NodeId/PortId/NodeKindId/PortSide/Port/Connection
• canvas — GraphView, GraphCtx, GraphResponse
• state — GraphViewState + drag structs
• tokens — GraphTokens
• node — NodeFrame/NodeResult/NodeStatus + ctx.node
• edge — EdgeStyle/EdgeResult + ctx.edge
• handle — HandleSpec/HandleVariant (ports)
• search — NodeSearch palette
• viewport — standalone world↔screen transform helper
• extras — grid, resizer, minimap, toolbar, controls

Page template

Every component page follows the same structure: what it is → Design (purpose, anatomy, variants/sizes/states, tokens consumed, a11y) → API (builder methods) → Usage (minimal + realistic examples) → Composition → Notes.

Avatar

Layer: atom · Path: src/atoms/avatar.rs · Exports: avatar::{Avatar, AvatarSize}

A circular avatar that renders centered, uppercased initials over a muted-filled disc. This wave is initials-only — image loading is a documented later addition. The diameter and the type style both scale together with [AvatarSize].

Design

• Purpose / when to use — represent a user/entity compactly when you have no image. Reach for it in lists, headers, mention chips. Do NOT use it for arbitrary iconography (that is Icon).

• Anatomy — a filled circle (theme.muted) + a centered initials galley in theme.foreground. Initials are uppercased at render time.

• Variants / sizes / states — three sizes, no interactive states (sense is hover only):

  Size	Diameter token	Type style
  Sm	core::CONTROL_SM (26px)	typography::caption()
  Md (default)	core::CONTROL_MD (32px)	typography::label()
  Lg	core::CONTROL_LG (38px)	typography::body_strong()

• Tokens consumed — theme.muted (disc fill), theme.foreground (initials), core::CONTROL_* (diameter), typography styles via theme::typography.

• Accessibility — none beyond the bare Response; it allocates with Sense::hover() and emits no widget_info.

API

AvatarSize (enum): Sm, Md (default), Lg.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Avatar;

Avatar::new("JD").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::{Avatar, AvatarSize};

let resp = Avatar::new("ab").size(AvatarSize::Lg).show(ui); // renders "AB"
if resp.hovered() { /* … */ }
}

Composition

Atom: paints directly with tokens (circle_filled + a layout-job galley). It does not compose other atoms; the initials galley is built inline rather than via Text.

Notes

• Initials are .to_uppercase()d internally — pass any case.
• The galley uses extra_letter_spacing = style.tracking and is centered both axes.
• No truncation/length cap: long strings will overflow the disc; pass 1–2 chars.

See tokens · theming · typography.

Badge

Layer: atom · Path: src/atoms/badge.rs · Exports: badge::{Badge, BadgeVariant}

A static, non-interactive pill label with the shadcn variant set plus three domain status variants (Success/Warning/Info). Variant resolves to a [BadgeTokens] bundle (fill/foreground/border/underline); the atom paints a rounded pill, an optional leading status dot, and a centered text galley.

Design

• Purpose / when to use — annotate state, count, or category inline (e.g. “Beta”, “3”, a status dot). It is read-only; for a clickable chip use Button or Toggle.

• Anatomy — pill rect (radius = half-height) → optional fill → optional border stroke → optional leading dot (in foreground) → centered text galley.

• Variants / sizes / states — no hover/focus/disabled (sense is hover only).

  Variants (BadgeVariant): Default, Secondary, Destructive, Outline, Ghost, Link, Success, Warning, Info. Each maps to a BadgeTokens::* constructor; Link carries underline = true.

  Size	Padding (x, y)	Text style
  Sm	(SPACE_1, SPACE_1)	caption()
  Md (default)	(SPACE_2, SPACE_1)	caption()
  Lg	(SPACE_3, SPACE_1)	label()

• Tokens consumed — BadgeTokens (fill/border/foreground/underline, per variant), core::SPACE_1..3 (padding/gap/dot), core::BORDER_THIN (border + underline stroke). Fill/border are only painted when alpha > 0.

• Accessibility — none beyond the bare Response; no widget_info.

API

BadgeVariant (enum): Default (default), Secondary, Destructive, Outline, Ghost, Link, Success, Warning, Info.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Badge;

Badge::new("New").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::{Badge, BadgeVariant};

Badge::new("Online").success().dot().show(ui);
Badge::new("Deprecated").variant(BadgeVariant::Destructive).show(ui);
}

Composition

Atom: paints the pill and builds the text galley inline with token fonts/colors. Does not compose Text or Icon.

Notes

• The dot uses core::SPACE_2 diameter and is filled with bt.foreground.
• Link is the only variant that draws an underline (via BadgeTokens.underline).
• Pill corner radius is computed from the final rect height, so it stays fully rounded at any size.

See tokens · theming · typography.

Button

Layer: atom · Path: src/atoms/button.rs · Exports: button::{Button, ButtonVariant}

A labeled, optionally-iconed click control with the shadcn variant set. Icon(s) and label render as a single galley with each section valign-centered, so mixed icon/text fonts share one optical baseline. Fill/foreground/border come from [ButtonTokens]; hover/press/disabled/focus all come from motion/opacity/border tokens, so light+dark and every state stay token-driven.

Design

• Purpose / when to use — the primary click affordance. Use icon_only() for toolbar buttons, loading(true) for in-flight actions. For a two-state pressable use Toggle; for a boolean setting use Switch.

• Anatomy — filled rect (variant fill) → animated hover overlay → press overlay → optional border stroke → focus ring (on focus) → centered content galley (icon-left, label, icon-right) or an indeterminate spinner arc when loading.

• Variants / sizes / states

  Variants (ButtonVariant): Default, Secondary, Destructive, Outline, Ghost, Link. Each maps to a ButtonTokens::* constructor; Link underlines its label.

  Size	Height	Icon size	Pad-x	Text style
  Sm	CONTROL_SM 26	ICON_SM 14	SPACE_3	Size::text_style()
  Md (default)	CONTROL_MD 32	ICON_MD 16	SPACE_4	…
  Lg	CONTROL_LG 38	ICON_LG 20	SPACE_4	…

  States: hover (theme.hover_overlay ramped by core::hover_t), pressed (theme.press_overlay), focused (focus ring), disabled (enabled(false) → colors via core::disabled_color, sense drops to hover), loading (spinner arc, clicks ignored, width preserved).

• Tokens consumed — ButtonTokens (fill/foreground/border/radius/underline), theme.hover_overlay, theme.press_overlay, theme.ring, core::SPACE_2 (icon gap), core::BORDER_THIN/BORDER_FOCUS, core::hover_t, core::disabled_color, core::Size, typography::icon_font.

• Accessibility — emits WidgetInfo::labeled(WidgetType::Button, enabled, label). Focus ring via focus::focus_ring_rect. Hit target = full allocated rect (square when icon_only).

API

ButtonVariant (enum): Default (default), Secondary, Destructive, Outline, Ghost, Link.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Button;

if Button::new("Save").show(ui).clicked() {
    // …
}
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Button;
use ouroboros_ui::egui_phosphor::light;

let saving = true;
let resp = Button::new("Save")
    .destructive()
    .icon_left(light::FLOPPY_DISK)
    .loading(saving)
    .show(ui);
if resp.clicked() && !saving { /* … */ }

// icon-only toolbar button
Button::new("").icon_left(light::GEAR).icon_only().ghost().sm().show(ui);
}

Composition

Atom: paints fill/overlays/border/ring directly. Builds icon+label as one inline LayoutJob (does NOT compose the Icon/Text atoms — single-galley alignment is intentional). The loading arc is the same form as the Spinner atom, inlined.

Notes

• loading(true) overrides clicks regardless of enabled; width is computed from the content galley so the button does not resize when toggled into loading.
• icon_only() drops the label from layout but the label string is still reported in widget_info — pass a meaningful label for a11y even with icon_only.
• The hover animation keys off id_source if set; give icon-only buttons in a loop a stable id_source to avoid animation cross-talk.

See tokens · theming · typography · guards.

Checkbox

Layer: atom · Path: src/atoms/checkbox.rs · Exports: checkbox::Checkbox

A boolean checkbox bound to a &mut bool, with an optional trailing label. The box is painted from tokens (border input; when on, primary fill + a centered check glyph in primary_foreground); the label is rendered via the Text atom. Supports an indeterminate (dash) presentation, focus ring, and disabled dim.

Design

• Purpose / when to use — toggle a single boolean, or one item in a multi-select set. For an on/off setting that reads like a switch use Switch; for mutually-exclusive options use Radio.

• Anatomy — square box (left, vertically centered) → optional primary fill when on → border stroke → hover veil → check/minus glyph when on → focus ring → optional label Text to the right.

• Variants / sizes / states

  Size	Box size
  Sm	ICON_SM 14
  Md (default)	ICON_MD 16
  Lg	ICON_LG 20

  States: checked (primary fill + light::CHECK), indeterminate (light::MINUS, takes visual precedence over checked, presentational only), hover (hover_t veil), focus (ring), disabled (disabled_color dim; sense drops to hover), non-interactive (interactive(false) — display-only, no toggle).

• Tokens consumed — theme.primary, theme.primary_foreground, theme.input, theme.foreground, theme.hover_overlay, theme.ring, core::RADIUS_SM, core::SPACE_2 (gap), core::BORDER_THIN, core::hover_t, core::disabled_color, typography::body, typography::icon_font.

• Accessibility — emits WidgetInfo::selected(WidgetType::Checkbox, enabled, on, label). Focus ring via focus::focus_ring_rect. Hit target spans box + gap + label.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Checkbox;

let mut agreed = false;
if Checkbox::new(&mut agreed).label("I agree").show(ui).changed() {
    // agreed flipped
}
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Checkbox;

// tri-state header in a select-all pattern
let mut all = false;
Checkbox::new(&mut all)
    .indeterminate(some_selected && !all)
    .label("Select all")
    .show(ui);
}

Composition

Atom: paints the box and glyph directly; composes the Text atom for the label inside a child Ui.

Notes

• Binding is &mut bool. On a click the atom flips *checked and calls mark_changed(), so check .changed().
• indeterminate(true) only changes the painted glyph (dash); it does not alter *checked. The consumer is expected to clear it on the next interaction.
• interactive(false) makes it display-only — clicks pass through (useful inside a clickable card).
• Label width reserves extra room for the role’s letter-spacing so it does not clip.

See tokens · theming · typography · guards.

ColorSwatch

Layer: atom · Path: src/atoms/color_swatch.rs · Exports: color_swatch::ColorSwatch

A swatch displaying an arbitrary Color32 (consumer data, not a theme token) in a token-bordered square or circle. Senses clicks so a parent can open a color picker. Modeled on Unity’s ColorField.

Design

• Purpose / when to use — the base of a color field: show the current color and let the user click to edit. The fill color is application data, not a token.
• Anatomy — a filled square (RADIUS_SM corners) or circle, with a theme.border stroke. Fill = the supplied Color32.
• Variants / sizes / states — square (default) or circle(). Size is a free f32 (default core::ICON_LG = 20px). Senses click but paints no hover/focus/disabled state.
• Tokens consumed — theme.border (stroke), core::RADIUS_SM (square corners), core::ICON_LG (default size). The fill is intentionally non-token (consumer color).
• Accessibility — bare Response from Sense::click(); no widget_info.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::ColorSwatch;
use egui::Color32;

ColorSwatch::new(Color32::from_rgb(220, 80, 80)).show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::ColorSwatch;

let mut color = some_color;
if ColorSwatch::new(color).size(28.0).circle().show(ui).clicked() {
    // open a picker, mutate `color`
}
}

Composition

Atom: paints fill + border directly with rect_filled/rect_stroke (or circle_*). Composes no other atoms.

Notes

• The fill is a raw Color32 from the consumer — it deliberately bypasses the token system, unlike every other painted atom.
• No picker is built in; show only returns the click. Wire it to your own color-editing UI.

See tokens · theming.

Divider

Layer: atom · Path: src/atoms/divider.rs · Exports: divider::{Axis, Divider}

A hairline rule in the border token, horizontal or vertical. Default thickness is core::BORDER_THIN; a horizontal divider fills the available width, a vertical one fills the available height. Color and weight are overridable.

Design

• Purpose / when to use — separate content groups, underline a tab indicator (thick()), or draw a red rule (destructive()). For an interactive resize band between panels use SplitterHandle.

• Anatomy — a single hline/vline stroke. Horizontal: width = ui.available_width(), allocated height = weight. Vertical: height = ui.available_height(), allocated width = weight.

• Variants / sizes / states

  Builder	Effect
  horizontal()	Axis::Horizontal, border color, BORDER_THIN.
  vertical()	Axis::Vertical, border color, BORDER_THIN.
  .thick()	Weight = BORDER_FOCUS (2px) — e.g. tab underline.
  .destructive()	Color = theme.destructive.
  .color(c)	Explicit color override (wins over destructive).

  No hover/focus/disabled states (sense is hover only).

• Tokens consumed — theme.border (default color), theme.destructive (when destructive()), core::BORDER_THIN (default weight), core::BORDER_FOCUS (when thick()).

• Accessibility — bare hover Response; no widget_info.

API

Axis (enum): Horizontal (default), Vertical.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Divider;

Divider::horizontal().show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Divider;

// tab underline indicator
Divider::horizontal().thick().color(theme.primary).show(ui);

// vertical separator in a toolbar row
Divider::vertical().show(ui);
}

Composition

Atom: paints a single stroke directly. Composes no other atoms.

Notes

• A horizontal divider greedily takes the full available width; place it where that is intended, or constrain the parent Ui.
• Axis is re-exported and reused by SplitterHandle.

See tokens · theming.

Heading

Layer: atom · Path: src/atoms/heading.rs · Exports: heading::{Heading, HeadingLevel}

A title rendered in the foreground token at one of four heading levels. Each level maps to a foundation typography type style (font, size, line-height, tracking). Sibling of Text, specialized for titles.

Design

• Purpose / when to use — section/page titles. For body copy, labels, captions, or code use Text.

• Anatomy — a single non-selectable egui::Label built from a RichText carrying the level’s font_id, line_height, tracking, and theme.foreground. Wrap mode is Extend (no wrap).

• Variants / sizes / states

  Level	Type style
  Display	typography::display() (largest)
  H1	typography::h1()
  H2 (default)	typography::h2()
  Heading	typography::heading() (smallest)

  No interactive states.

• Tokens consumed — theme.foreground (color), the per-level typography style (font/size/line-height/tracking).

• Accessibility — renders a non-selectable label; returns the Label’s Response.

API

HeadingLevel (enum): Display, H1, H2 (default), Heading.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Heading;

Heading::new("Settings").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::{Heading, HeadingLevel};

Heading::new("Welcome").level(HeadingLevel::Display).show(ui);
Heading::new("Section").heading().show(ui);
}

Composition

Atom: renders directly via egui::Label/RichText with token styling. Does not compose Text (it is a parallel specialization).

Notes

• Wrap mode is Extend — headings do not wrap; size the parent or keep titles short.
• Unlike Text, there is no color override; the color is always theme.foreground.

See tokens · theming · typography.

Icon

Layer: atom · Path: src/atoms/icon.rs · Exports: icon::Icon

A single Phosphor glyph at an icon-size token, in a theme color. The glyph is a &'static str constant from egui_phosphor::light (re-exported at the crate root). The font always comes from typography::icon_font — atoms never build a FontId directly.

Design

• Purpose / when to use — standalone iconography (status marks, decorative glyphs, list bullets). For an icon inside a button, prefer Button::icon_left/icon_right (single-galley alignment) rather than composing this atom.

• Anatomy — a non-selectable egui::Label with RichText::new(glyph).font(icon_font(size)).color(color).

• Variants / sizes / states

  Size shorthand	Token
  .sm()	ICON_SM 14
  .md() (default)	ICON_MD 16
  .lg()	ICON_LG 20
  .xl()	ICON_XL 24
  .size(f32)	arbitrary px

  Color: defaults to theme.foreground; .muted() → theme.muted_foreground; .color(c) → explicit. No interactive states.

• Tokens consumed — theme.foreground / theme.muted_foreground (color), core::ICON_SM..XL (size), typography::icon_font (font).

• Accessibility — rendered as non-selectable so the glyph never steals a click from an interactive parent. Returns the Label Response.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Icon;
use ouroboros_ui::egui_phosphor::light;

Icon::new(light::GEAR).show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Icon;
use ouroboros_ui::egui_phosphor::light;

Icon::new(light::CHECK_CIRCLE).lg().color(theme.success).show(ui);
Icon::new(light::INFO).muted().show(ui);
}

Composition

Atom: renders directly via egui::Label/RichText. Composes no other atoms. Note: Button/Toggle do not compose this atom — they inline the glyph into a single galley.

Notes

• glyph must be a &'static str (the Phosphor constants are). Arbitrary runtime strings will render whatever codepoints they contain in the icon font.
• .color() wins over .muted().

See tokens · theming · typography.

Input

Layer: atom · Path: src/atoms/input.rs · Exports: input::Input

A single-line text field over a &mut String. A token-painted box (fill muted, border input/destructive/ring, animated hover veil) wraps a frameless egui::TextEdit::singleline — egui owns the editing, the casing is all token. States: default / focus / disabled / error. (Size variants live here; leading-icon / labels belong to a Field molecule.)

Design

• Purpose / when to use — free-form single-line text entry. For multi-line use Textarea; for numbers use NumericField.

• Anatomy — filled rect (muted) → hover veil → inner frameless TextEdit (left-aligned, body font, foreground text, muted_foreground placeholder) → border stroke whose color/weight encodes state.

• Variants / sizes / states

  Size	Height	Pad-x
  Sm	CONTROL_SM 26	SPACE_3
  Md (default)	CONTROL_MD 32	SPACE_4
  Lg	CONTROL_LG 38	SPACE_4

  Border state (precedence): error → destructive @ BORDER_THIN; else focused → ring @ BORDER_FOCUS; else input @ BORDER_THIN. Disabled dims fill + border + text via disabled_color and uses add_enabled(false, …).

• Tokens consumed — theme.muted (fill), theme.input/theme.destructive/theme.ring (border), theme.foreground (text), theme.muted_foreground (placeholder), theme.hover_overlay, core::RADIUS_MD, core::BORDER_THIN/BORDER_FOCUS, core::hover_t, core::disabled_color, core::Size, typography::body.

• Accessibility — focus is egui’s TextEdit focus (the border switches to the ring). Width = ui.available_width().

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Input;

let mut name = String::new();
Input::new(&mut name).placeholder("Your name").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Input;

let mut email = String::new();
let invalid = !email.contains('@') && !email.is_empty();
let resp = Input::new(&mut email)
    .placeholder("[email protected]")
    .error(invalid)
    .id_source("email_field")
    .show(ui);
if resp.changed() { /* validate */ }
}

Composition

Atom: paints the box/border/veil directly and embeds a frameless egui::TextEdit in a child Ui. Composes no other DS atoms.

Notes

• Binding is &mut String; the returned Response is the inner TextEdit’s, so .changed()/.has_focus()/.lost_focus() reflect editing.
• Greedily takes ui.available_width() — constrain the parent for a fixed width.
• In a loop or repeated layout, set id_source so the field keeps focus/cursor across frames.

See tokens · theming · typography · guards.

Kbd

Layer: atom · Path: src/atoms/kbd.rs · Exports: kbd::Kbd

A keyboard-key chip: mono (kbd) text in a small token-bordered box — e.g. ⌘K, Ctrl, Esc. Modeled on shadcn’s Kbd.

Design

• Purpose / when to use — display a keyboard shortcut inline (menus, tooltips, command palettes). Read-only.
• Anatomy — rounded rect (muted fill + border stroke, RADIUS_SM) with (SPACE_2, SPACE_1) padding around a centered kbd-style galley in muted_foreground.
• Variants / sizes / states — none; single appearance, sense is hover only.
• Tokens consumed — theme.muted (fill), theme.border (stroke), theme.muted_foreground (text), core::RADIUS_SM, core::SPACE_2/SPACE_1 (padding), core::BORDER_THIN, typography::kbd.
• Accessibility — bare hover Response; no widget_info.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Kbd;

Kbd::new("Esc").show(ui);
Kbd::new("⌘K").show(ui);
}

Composition

Atom: paints the box and builds the text galley inline with the kbd type style. Does not compose Text, though TextRole::Kbd uses the same style.

Notes

• The whole string is rendered in one chip; for multi-key combos either pass "Ctrl+K" as one string or place several Kbds with separators.

See tokens · theming · typography.

NumericField

Layer: atom · Path: src/atoms/numeric_field.rs · Exports: numeric_field::NumericField

A scrubbable numeric input bound to a &mut f32, modeled on Unity’s Numeric Field. A token box wraps an egui DragValue (drag to scrub, click to type); the value is right-aligned. .stepper() flanks it with ghost −/+ icon buttons, and .suffix() appends a unit. The editing substrate is egui’s; the casing is token.

Design

• Purpose / when to use — numeric entry where dragging/scrubbing helps (positions, scales, counts). For a bounded value you mostly slide, use Slider; for text use Input.

• Anatomy — filled rect (muted) → hover veil → inner content: a right-aligned DragValue, optionally flanked by − (left) and + (right) ghost Buttons → border stroke encoding state.

• Variants / sizes / states

  Size	Height
  Sm	CONTROL_SM 26
  Md (default)	CONTROL_MD 32
  Lg	CONTROL_LG 38

  Border state (precedence): error → destructive; else focused → ring @ BORDER_FOCUS; else input. Disabled dims and disables the DragValue + stepper buttons.

• Tokens consumed — theme.muted, theme.input/theme.destructive/theme.ring, theme.hover_overlay, core::RADIUS_MD, core::SPACE_2 (inner inset), core::BORDER_THIN/BORDER_FOCUS, core::hover_t, core::disabled_color, core::Size.

• Accessibility — focus/keyboard come from egui’s DragValue; the border switches to the ring on focus.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::NumericField;

let mut scale = 1.0_f32;
NumericField::new(&mut scale).range(0.0, 10.0).speed(0.05).show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::NumericField;

let mut count = 3.0_f32;
NumericField::new(&mut count)
    .range(0.0, 99.0)
    .step(1.0)
    .stepper()
    .suffix(" items")
    .show(ui);
}

Composition

Atom: paints the box/border/veil directly and embeds an egui DragValue in a child Ui. Composes the Button atom (ghost, sm, icon-only) for the −/+ steppers.

Notes

• Binding is &mut f32. The stepper buttons mutate the value directly (clamped to range) when clicked; the returned Response is the DragValue’s.
• Stepper buttons get glyphs light::MINUS / light::PLUS; the + is pinned right and the value fills the remaining width.
• Width model: by default fills available_width clamped to NUMERIC_MIN_W..=FIELD_NUM_W (stepper floors higher at NUMERIC_STEPPER_MIN_W) so numbers stay column-aligned. .full_width() drops the cap; .fixed_width() ignores available_width entirely and pins NUMERIC_STEPPER_W — use it for steppers in resizable inspector panels where the box must not shrink under the value.

See tokens · theming · guards.

Progress

Layer: atom · Path: src/atoms/progress.rs · Exports: progress::Progress

A determinate progress indicator (fraction in 0..=1), rendered as a continuous bar, a stepped (segmented) bar, or a circular ring. Modeled on shadcn Progress / Unity Progress Bar. For indeterminate loading use Spinner.

Design

• Purpose / when to use — show known completion progress. Use the ring for compact/inline placement, steps for discrete stages, the bar for general progress.

• Anatomy

  • Bar (continuous): pill track (muted) + a primary fill rect from the left, width = track × fraction.
  • Bar (stepped): n equal pills with SPACE_1 gaps; the first round(fraction × n) are primary, the rest muted.
  • Ring: a muted circle stroke + a primary arc sweeping fraction × 360° from 12 o’clock.

• Variants / sizes / states

  Builder	Render
  new(fraction)	continuous bar, SPACE_2 tall, full width
  .steps(n)	n segments (≥1)
  .circular()	ring at CONTROL_LG (38px) diameter
  .circular_size(d)	ring at diameter d

  No interactive states (sense is hover).

• Tokens consumed — theme.muted (track), theme.primary (fill/arc), core::SPACE_2 (bar height / circular thickness via SPACE_1), core::SPACE_1 (segment gap & ring thickness), core::CONTROL_LG (default ring size).

• Accessibility — bare hover Response; no widget_info.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Progress;

Progress::new(0.42).show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Progress;

Progress::new(0.6).steps(5).show(ui);       // stepped bar
Progress::new(0.6).circular().show(ui);     // ring
}

Composition

Atom: paints rects/strokes/arc directly. Composes no other atoms.

Notes

• fraction is clamped on construction — out-of-range values are safe.
• The bar variant takes ui.available_width(); the ring is fixed-size.
• This is determinate only; there is no indeterminate bar — use Spinner.

See tokens · theming.

Radio

Layer: atom · Path: src/atoms/radio.rs · Exports: radio::Radio

A single radio button taking selected: bool (by value, not a binding) with an optional trailing label. It is a standalone atom: it reports clicks via its Response; the consumer (or a future RadioGroup molecule) owns single-selection. Circle is token-painted (border input; when selected, an inner primary dot); the label is rendered via the Text atom.

Design

• Purpose / when to use — one option within a mutually-exclusive group. For independent booleans use Checkbox.

• Anatomy — outline circle (left, vertically centered; border primary when selected else input) → hover veil → inner primary dot (radius × 0.5) when selected → focus ring → optional label Text.

• Variants / sizes / states

  Size	Circle size
  Sm	ICON_SM 14
  Md (default)	ICON_MD 16
  Lg	ICON_LG 20

  States: selected (border primary + inner dot), hover (hover_t veil), focus (ring), disabled (disabled_color; sense → hover), non-interactive (interactive(false) — display-only).

• Tokens consumed — theme.primary, theme.input, theme.foreground, theme.hover_overlay, theme.ring, core::SPACE_2 (gap), core::BORDER_THIN, core::hover_t, core::disabled_color, typography::body.

• Accessibility — emits WidgetInfo::selected(WidgetType::RadioButton, enabled, selected, label). Focus ring via focus::focus_ring_circle. Hit target spans circle + gap + label.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Radio;

#[derive(PartialEq)] enum Mode { A, B }
let mut mode = Mode::A;

if Radio::new(mode == Mode::A).label("Option A").show(ui).clicked() {
    mode = Mode::A;
}
if Radio::new(mode == Mode::B).label("Option B").show(ui).clicked() {
    mode = Mode::B;
}
}

Composition

Atom: paints the circle/dot directly; composes the Text atom for the label inside a child Ui.

Notes

• Unlike Checkbox/Switch, Radio does not take a &mut binding and does not mutate state — it only reports .clicked(). The caller updates the selected value. (No mark_changed; check .clicked(), not .changed().)
• Label width reserves extra room for the role’s tracking so it does not clip.

See tokens · theming · typography · guards.

Skeleton

Layer: atom · Path: src/atoms/skeleton.rs · Exports: skeleton::Skeleton

A loading placeholder block: a muted rounded rect that gently pulses (opacity) while content loads. Modeled on shadcn Skeleton. Implements Default.

Design

• Purpose / when to use — reserve layout space and signal loading before real content arrives. For an active spinner use Spinner; for known progress use Progress.
• Anatomy — a single muted-filled rounded rect (RADIUS_SM). When pulsing, its opacity oscillates via a sine of ui.input(time) between OPACITY_MUTED and 1.0, requesting a repaint each frame.
• Variants / sizes / states — width(f32) (default: ui.available_width()), height(f32) (default SPACE_4 = 16px), still() to disable the pulse. No interactive states (sense hover).
• Tokens consumed — theme.muted (fill), core::RADIUS_SM, core::SPACE_4 (default height), core::OPACITY_MUTED (pulse floor).
• Accessibility — bare hover Response; no widget_info.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Skeleton;

Skeleton::new().show(ui);                       // full-width pulsing line
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Skeleton;

// an avatar-sized still placeholder
Skeleton::new().width(32.0).height(32.0).still().show(ui);
}

Composition

Atom: paints one rect directly. Composes no other atoms.

Notes

• Default width is greedy (ui.available_width()); pass .width(..) for a fixed block.
• The pulse drives continuous repaints — call .still() for large grids of placeholders to avoid animating many at once.

See tokens · theming.

Slider

Layer: atom · Path: src/atoms/slider.rs · Exports: slider::Slider

A draggable numeric value over a range, bound to a &mut f32. A muted track + a primary filled portion + a primary thumb; drag or click anywhere on the track to set. Modeled on shadcn/Unity/O3DE sliders. For precise numeric typing use NumericField.

Design

• Purpose / when to use — pick a continuous (or stepped) value within a known range where coarse adjustment is fine. Default range is 0.0..=1.0.

• Anatomy — thin pill track (SPACE_1 tall, muted) → primary fill from left to thumb → circular primary thumb with a background stroke ring → hover veil on the thumb → focus ring on the thumb.

• Variants / sizes / states

  Size	Control height (thumb area)
  Sm	ICON_SM 14
  Md (default)	ICON_MD 16
  Lg	ICON_LG 20

  States: drag/click sets value (Sense::click_and_drag, mark_changed); hover (hover_t veil on thumb); focus (ring on thumb, only when enabled); disabled (disabled_color, sense → hover).

• Tokens consumed — theme.muted (track), theme.primary (fill + thumb), theme.background (thumb stroke), theme.hover_overlay, theme.ring, core::SPACE_1 (track thickness), core::BORDER_THIN, core::hover_t, core::disabled_color, core::Size.

• Accessibility — focus ring via focus::focus_ring_circle. (No explicit widget_info is set.)

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Slider;

let mut volume = 0.5_f32;
if Slider::new(&mut volume).show(ui).changed() {
    // volume changed
}
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Slider;

let mut zoom = 1.0_f32;
Slider::new(&mut zoom).range(0.25, 4.0).step(0.25).show(ui);
}

Composition

Atom: paints track/fill/thumb directly. Composes no other atoms.

Notes

• Binding is &mut f32; the value is clamped to range and (if step > 0) snapped. Check .changed().
• Greedily takes ui.available_width().
• Clicking anywhere on the track jumps the thumb to that position (not just dragging the thumb).

See tokens · theming · guards.

Spinner

Layer: atom · Path: src/atoms/spinner.rs · Exports: spinner::Spinner

An indeterminate loading arc: a ~270° stroked arc that rotates over time (requesting a repaint each frame). Size and color are tokens. Implements Default. For known progress use Progress.

Design

• Purpose / when to use — signal in-flight work of unknown duration. Inline or centered in a panel; the same arc form is inlined into Button::loading.
• Anatomy — a single 32-point polyline approximating a 0.75·TAU (270°) arc, stroked at BORDER_FOCUS, with the start angle = time × TAU so it spins.
• Variants / sizes / states — .sm() (ICON_SM 14), default ICON_MD 16, .lg() (ICON_LG 20), or .size(f32). Color defaults to muted_foreground, overridable via .color(c). No interactive states.
• Tokens consumed — theme.muted_foreground (default color), core::ICON_SM/MD/LG (size), core::BORDER_FOCUS (stroke width + radius inset).
• Accessibility — bare hover Response; no widget_info. Animates continuously (request_repaint).

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Spinner;

Spinner::new().show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Spinner;

Spinner::new().lg().color(theme.primary).show(ui);
}

Composition

Atom: paints the arc directly via a Shape::line polyline. Composes no other atoms.

Notes

• Calls ui.ctx().request_repaint() every frame it is shown — only render it while actually loading.
• The arc form is duplicated (not composed) inside Button::loading.

See tokens · theming.

SplitterHandle

Layer: atom · Path: src/atoms/splitter_handle.rs · Exports: splitter_handle::SplitterHandle

The draggable divider band between two Splitter panels. It fills its area as a drag hit-target and paints a centered hairline (token border) that fades to ring on hover/drag, setting the resize cursor. The owning Splitter organism reads the returned Response (drag delta, double-click) — the atom paints, the organism composes.

Design

• Purpose / when to use — only inside a Splitter organism, as the resize grip between panes. For a static rule use Divider.
• Anatomy — the full ui.max_rect() allocated as a click_and_drag hit-target → a centered border hairline (vline/hline) → on hover/drag/active, a ring overlay line at BORDER_FOCUS, ramped by hover_t. Sets ResizeHorizontal/ResizeVertical cursor while interacting.
• Variants / sizes / states
  • line: Axis — orientation of the visible rule: Vertical for a left/right (horizontal) split, Horizontal for a top/bottom (vertical) split.
  • .active(bool) — force the highlighted state (e.g. mid-drag, or when a neighbor is collapsed).
  • States: hover/drag highlight (cursor + ring fade), plus forced active.
• Tokens consumed — theme.border (hairline), theme.ring (highlight), core::BORDER_THIN (hairline weight), core::BORDER_FOCUS (highlight weight), core::hover_t (fade).
• Accessibility — sets the appropriate resize cursor while hovered/dragged; returns the full Response for the organism to interpret (drag_delta, double_clicked).

API

Axis — re-exported from Divider: Horizontal, Vertical.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::{SplitterHandle, Axis};

// inside a left/right split: visible rule is vertical
let resp = SplitterHandle::new(Axis::Vertical).show(ui);
if resp.dragged() {
    let dx = resp.drag_delta().x;
    // adjust the left pane width by dx
}
}

Composition

Atom: paints the hairline/highlight directly and sets the cursor. Composes no other atoms; it is itself composed by the Splitter organism.

Notes

• Pass the orientation of the visible line, not the split direction — Axis::Vertical for a horizontal (left/right) split. This is the documented gotcha.
• show consumes the whole ui.max_rect() as the hit-target; give it a dedicated child Ui sized to the desired grab width.

See tokens · theming.

Surface

Layer: atom · Path: src/atoms/surface.rs · Exports: surface::{Surface, SurfaceBorder, SurfaceFill}

The one place a “box” is painted — fill, border, radius, shadow, and padding — so molecules can compose a surface instead of hand-rolling an egui::Frame. Optionally interactive (clickable) and selected (ring border) for card-style selectors. Atoms may paint; molecules may not, so reach for this whenever you need a container.

Design

• Purpose / when to use — wrap any content group in a themed container: cards, panels, popovers, selectable tiles. This is the canonical container atom; do not build raw egui::Frames in higher layers.

• Anatomy — an egui::Frame with corner radius, inner margin (padding), optional fill, optional stroke, optional shadow; runs content inside. When interactive, re-interacts the painted rect for clicks and draws a border_strong outline on hover.

• Variants / sizes / states

  SurfaceFill: Card (default → theme.card), Muted (theme.muted), Background (theme.background), None (no fill).

  SurfaceBorder: None, Default (default → theme.border), Strong (theme.border_strong).

  Other knobs: radius(f32) (default RADIUS_LG), elevated() (adds SHADOW_MD), pad(f32) (default SPACE_4), interactive(), selected(bool).

  States: selected(true) overrides the border with a ring stroke at BORDER_FOCUS; interactive adds a border_strong hover outline.

• Tokens consumed — theme.card/theme.muted/theme.background (fill), theme.border/theme.border_strong (border), theme.ring (selected), core::RADIUS_LG (default radius), core::SPACE_4 (default padding), core::BORDER_THIN/BORDER_FOCUS, core::SHADOW_MD (elevation).

• Accessibility — when interactive, the rect is re-interacted with Sense::click(); the returned response carries the click. Non-interactive surfaces return the frame’s response.

API

SurfaceFill: Card (default), Muted, Background, None. SurfaceBorder: None, Default (default), Strong.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Surface;
use ouroboros_ui::atoms::Text;

Surface::new().show(ui, |ui| {
    Text::new("Card body").show(ui);
});
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Surface;

let mut chosen = false;
let r = Surface::new()
    .interactive()
    .selected(chosen)
    .elevated()
    .show(ui, |ui| { /* tile content */ });
if r.response.clicked() { chosen = !chosen; }
}

Composition

Atom: the only atom that exposes a content closure and paints the container box. Higher layers compose Surface rather than building egui::Frames — this is enforced by the layer rules (see guards).

Notes

• show returns egui::InnerResponse<R> — .inner is your closure’s value, .response is the surface’s (click-bearing when interactive).
• selected(true) takes precedence over any border(..) setting.
• For repeated/clickable surfaces in a list, set id_source to keep interaction stable.

See tokens · theming · guards.

Switch

Layer: atom · Path: src/atoms/switch.rs · Exports: switch::Switch

A boolean toggle bound to a &mut bool, with an animated sliding thumb. A pill track (primary when on, border_strong when off) holds a background-filled thumb that slides via animate_bool_with_time. All dimensions derive from tokens; includes a focus ring and disabled dim.

Design

• Purpose / when to use — an on/off setting that applies immediately (the “iOS toggle”). For a checkbox-style boolean (especially in forms/lists with labels) use Checkbox; for a pressable two-state button use Toggle.

• Anatomy — pill track → hover veil → circular thumb sliding left↔right with the animated t → focus ring. Track width = track_h + SPACE_4.

• Variants / sizes / states

  Size	Track height	Thumb diameter
  Sm	ICON_MD 16	ICON_SM 14
  Md (default)	ICON_LG 20	ICON_MD 16
  Lg	ICON_XL 24	ICON_LG 20

  States: on (primary track) / off (border_strong track — chosen over muted so the thumb stays legible in dark mode); hover (hover_t veil); focus (ring); disabled (disabled_color, sense → hover).

• Tokens consumed — theme.primary (on track), theme.border_strong (off track), theme.background (thumb), theme.hover_overlay, theme.ring, core::ICON_* (dims), core::SPACE_4 (track extra width), core::DURATION_FAST (thumb slide), core::hover_t, core::disabled_color, core::Size.

• Accessibility — emits WidgetInfo::selected(WidgetType::Checkbox, enabled, on, "") (no label). Focus ring via focus::focus_ring_rect.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Switch;

let mut dark = true;
if Switch::new(&mut dark).show(ui).changed() {
    // apply theme
}
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Switch;

let mut enabled = false;
Switch::new(&mut enabled).lg().id_source("notifications").show(ui);
}

Composition

Atom: paints track + thumb directly. Composes no other atoms. The Switch carries no label — pair it with a Text atom in a molecule/row for a labeled setting.

Notes

• Binding is &mut bool. On click it flips *on and calls mark_changed(); check .changed().
• The thumb position animates over DURATION_FAST keyed by id_source (or response.id) — set id_source for switches in loops to avoid animation cross-talk.
• Off-state track is border_strong, intentionally not muted, for dark-mode legibility.

See tokens · theming · guards.

Text

Layer: atom · Path: src/atoms/text.rs · Exports: text::{Text, TextRole}

A run of text at a typography role, in a theme color. Every visual comes from a token: font/size/line-height/tracking from a typography type style, color from the [Theme]. The DS’s universal text primitive; many other atoms compose it for their labels.

Design

• Purpose / when to use — all body copy, labels, captions, inline code, and key glyphs. For titles use Heading.

• Anatomy — a non-selectable egui::Label built from RichText with the role’s font_id + tracking + color, optional underline, and a wrap mode.

• Variants / sizes / states

  TextRole → type style:

  Role	Style
  Body (default)	typography::body()
  BodyStrong	body_strong()
  Label	label()
  LabelStrong	label_strong()
  Caption	caption()
  Code	code()
  Kbd	kbd()

  Color: theme.foreground (default), .muted() → muted_foreground, .color(c) → explicit. .wrap() enables wrapping (and line-height); .underline() for links; .italic() for asides/hints (combines freely, e.g. .muted().italic()). No interactive states.

• Tokens consumed — theme.foreground / theme.muted_foreground (color), the per-role typography style.

• Accessibility — rendered non-selectable so UI text never captures the pointer (it would steal clicks from interactive parents and show a text cursor).

API

TextRole (enum): Body (default), BodyStrong, Label, LabelStrong, Caption, Code, Kbd.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Text;

Text::new("Hello world").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Text;

Text::new("Saved").caption().color(theme.success).show(ui);
Text::new("A long paragraph that should wrap…").wrap().show(ui);
Text::new("No layers selected").muted().italic().show(ui);
}

Composition

Atom: renders directly via egui::Label/RichText with token styling. It is itself composed by Checkbox, Radio, and Tooltip for their labels.

Notes

• Default wrap mode is Extend (no wrap); line-height is only applied when .wrap() is set — applying leading to a single line inflates the row and decenters the glyph inside parents like buttons.
• .color() wins over .muted().

See tokens · theming · typography.

Textarea

Layer: atom · Path: src/atoms/textarea.rs · Exports: textarea::Textarea

A multi-line text field over a &mut String — the sibling of Input. A token-painted box (fill muted, border input/destructive/ring, animated hover veil) wraps a frameless multiline egui::TextEdit. Height derives from the requested row count.

Design

• Purpose / when to use — multi-line free text (descriptions, notes, JSON blobs). For single-line use Input.
• Anatomy — filled rect (muted) → hover veil → inner frameless multiline TextEdit (body font, foreground text, muted_foreground placeholder, SPACE_2 inset) → state border stroke.
• Variants / sizes / states
  • rows(n) (min 1, default 3) — sets height = n × body.line_height + 2·SPACE_2.
  • Border state (precedence): error → destructive; else focused → ring @ BORDER_FOCUS; else input. Disabled dims and uses add_enabled(false, …). (No size-scale variants, unlike Input.)
• Tokens consumed — theme.muted (fill), theme.input/theme.destructive/theme.ring (border), theme.foreground (text), theme.muted_foreground (placeholder), theme.hover_overlay, core::RADIUS_MD, core::SPACE_2 (padding), core::BORDER_THIN/BORDER_FOCUS, core::hover_t, core::disabled_color, typography::body.
• Accessibility — focus is egui’s TextEdit focus; the border switches to the ring on focus.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Textarea;

let mut notes = String::new();
Textarea::new(&mut notes).placeholder("Notes…").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Textarea;

let mut desc = String::new();
let resp = Textarea::new(&mut desc).rows(6).id_source("desc").show(ui);
if resp.changed() { /* … */ }
}

Composition

Atom: paints the box/border/veil directly and embeds a frameless multiline egui::TextEdit in a child Ui. Composes no other DS atoms.

Notes

• Binding is &mut String; the returned Response is the inner TextEdit’s.
• Height is fixed by rows (it does not auto-grow with content); width is ui.available_width().
• Unlike Input, there is no Size variant — only rows.

See tokens · theming · typography · guards.

Toggle

Layer: atom · Path: src/atoms/toggle.rs · Exports: toggle::Toggle

A two-state toggle button (distinct from Switch) bound to a &mut bool. It looks like a ghost button and fills with accent while on. Icon and/or label render as a single valign-centered galley, the same technique as Button. Modeled on shadcn Toggle.

Design

• Purpose / when to use — a pressable that latches on/off, like a formatting-bar “Bold” button. For an on/off setting that reads as a slider use Switch; for a non-latching action use Button.
• Anatomy — a rounded rect (RADIUS_MD) that is transparent off, hover_overlay on hover, and accent-filled when on; with a centered single galley of optional icon + optional label. Icon-only (no label) → square (height = CONTROL_SM).
• Variants / sizes / states — fixed height CONTROL_SM (26), icon size ICON_MD (16). No size variants. States: on (accent fill), hover (hover_overlay), disabled (disabled_color, sense → hover). No focus ring.
• Tokens consumed — theme.accent (on fill), theme.hover_overlay (hover), theme.foreground (content), core::CONTROL_SM (height), core::ICON_MD (icon), core::RADIUS_MD, core::SPACE_1 (icon↔label gap), core::SPACE_2 (pad-x), core::TRACKING_NORMAL, core::disabled_color, typography::body/icon_font.
• Accessibility — emits WidgetInfo::selected(WidgetType::Button, enabled, on, label).

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Toggle;
use ouroboros_ui::egui_phosphor::light;

let mut bold = false;
Toggle::new(&mut bold).icon(light::TEXT_B).show(ui);   // icon-only, square
}

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::Toggle;

let mut grid = true;
if Toggle::new(&mut grid).label("Grid").show(ui).changed() {
    // grid visibility flipped
}
}

Composition

Atom: paints the fill directly and builds icon+label as one inline LayoutJob (same single-galley approach as Button; does not compose Icon/Text).

Notes

• Binding is &mut bool; on click it flips *on and calls mark_changed() — check .changed().
• With no label, it renders icon-only and square; the id_source field exists but the on/hover fill is not animated (it is an instantaneous overlay, no hover_t).
• No focus ring (unlike Button/Switch).

See tokens · theming · typography · guards.

Tooltip

Layer: atom · Path: src/atoms/tooltip.rs · Exports: tooltip::Tooltip

A DS-styled hover tooltip attached to an existing Response. Tooltip::new("…").show(response) shows the text on hover, composing the Text atom inside egui’s on_hover_ui. Unlike every other atom, its show takes a Response (not a &mut Ui).

Design

• Purpose / when to use — attach explanatory hover text to any widget’s response (icon buttons, truncated labels, controls). Keep it short; for rich popovers build a molecule.
• Anatomy — egui’s hover container, with the body rendered by a single Text atom (default Body role / foreground color).
• Variants / sizes / states — none; shown only while the host response is hovered.
• Tokens consumed — indirectly via the Text atom (typography body, theme.foreground). The hover container chrome is egui’s default styling.
• Accessibility — uses egui’s on_hover_ui (hover-triggered).

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::atoms::{Button, Tooltip};
use ouroboros_ui::egui_phosphor::light;

let resp = Button::new("").icon_left(light::TRASH).icon_only().ghost().show(ui);
let resp = Tooltip::new("Delete").show(resp);
if resp.clicked() { /* … */ }
}

Composition

Atom: composes the Text atom for its body inside Response::on_hover_ui. Paints nothing itself.

Notes

• show takes and returns a Response — it wraps an already-shown widget rather than allocating in a Ui. This is the API outlier among the atoms.
• It returns the response, so you can chain .clicked()/.hovered() directly.

See tokens · theming · typography.

ListItem

Layer: cell · Path: src/cells/list_item.rs · Exports: list_item::ListItem

A selectable list row built from an optional leading icon, a title, and an optional subtitle. Modelled on the shadcn Item. Selection is a stateless input (selected: bool) and a click yields a plain [Response] — the consumer owns the selected index and reacts to .clicked().

Design

• Purpose / when to use — Vertically stacked, single-line-or-two rows in a list/panel where one item can be highlighted (file lists, asset pickers, project entries).

• Anatomy — A Surface (interactive, padded) wrapping a horizontal layout: optional Icon (muted) + a vertical stack of Text (title) and an optional muted caption Text (subtitle).

• Variants / states

  State	Effect
  default	Surface::fill_none().border_none() (transparent)
  selected (selected(true))	Surface::muted() fill
  hover/click	Surface::interactive() provides hover feedback + sense; the returned Response carries .clicked()

• Tokens / layout consumed — core::SPACE_2 (8px outer pad + icon→text gap), core::RADIUS_SM (4px). See tokens.

• Accessibility — Inherits the Surface’s interactive sense; selection state is purely visual (muted fill), so pair with a real selection model in the consumer.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::ListItem;
use ouroboros_ui::egui_phosphor::light;

ListItem::new("Cube").icon(light::CUBE).subtitle("Mesh").show(ui);
}

#![allow(unused)]
fn main() {
// realistic — a selectable list owning the selected index
let mut sel: usize = /* persisted state */ 0;
for (i, (icon, title, sub)) in [
    (light::CUBE, "Cube", "Mesh"),
    (light::STAR, "Light", "Point"),
    (light::GEAR, "Settings", "Project"),
].iter().enumerate() {
    if ListItem::new(*title)
        .icon(icon)
        .subtitle(*sub)
        .selected(sel == i)
        .id_source(("li", i))
        .show(ui)
        .clicked()
    {
        sel = i;
    }
}
}

Composition

Composes the Surface, Icon, and Text atoms only. It performs no painting — all visuals come from Surface (fill/border/interaction) and the atoms. Enforced by tests/no_painter_in_molecules.rs.

Notes

• Selection is input, not state: ListItem never remembers it. Drive it from a usize/HashSet in the parent and feed .selected(...).
• Give each row a distinct id_source (e.g. ("li", i)) so the interactive surfaces don’t collide.

MenuItem

Layer: cell · Path: src/cells/menu_item.rs · Exports: menu_item::MenuItem

A single menu row: optional leading icon, a label, and an optional right-aligned keyboard shortcut rendered as a Kbd. Modelled on the shadcn DropdownMenu item (.checked(..) mirrors the shadcn CheckboxItem). Clicking yields a [Response]; a disabled item drops its interactive sense.

Design

• Purpose / when to use — Rows inside dropdowns, context menus, and command lists where each entry pairs an action label with an optional accelerator.

• Anatomy — A Surface (transparent, padded) wrapping a horizontal layout: optional muted Icon + a Text label + (right-to-left) an optional Kbd shortcut.

• Variants / states

  State	Effect
  default (enabled(true))	Surface::interactive() — hover feedback + click sense
  disabled (enabled(false))	Surface is non-interactive (no hover/sense)
  with shortcut	trailing Kbd pinned right via Layout::right_to_left(Align::Center)
  checkable (checked(true))	leading check-mark Icon before icon/label (shadcn CheckboxItem)
  checkable (checked(false))	the mark’s slot (core::ICON_MD + core::SPACE_2) is reserved so checked/unchecked siblings stay aligned

• Tokens / layout consumed — core::SPACE_1 (4px outer pad), core::SPACE_2 (icon→label gap), core::RADIUS_SM (4px), core::ICON_MD (reserved check slot). See tokens.

• Accessibility — Disabled rows simply lose interactivity; they are not greyed by the cell itself.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::MenuItem;
use ouroboros_ui::egui_phosphor::light;

MenuItem::new("Copy").icon(light::COPY).shortcut("Ctrl C").id_source("mi_c").show(ui);
}

#![allow(unused)]
fn main() {
// realistic — a small context menu column
MenuItem::new("Copy").icon(light::COPY).shortcut("Ctrl C").id_source("mi_c").show(ui);
MenuItem::new("Paste").icon(light::CLIPBOARD).shortcut("Ctrl V").id_source("mi_v").show(ui);
MenuItem::new("Delete").icon(light::TRASH).id_source("mi_d").show(ui);
MenuItem::new("Disabled").enabled(false).id_source("mi_x").show(ui);
}

#![allow(unused)]
fn main() {
// checkable — a View-menu toggle section; unchecked rows keep the labels aligned
MenuItem::new("Show Grid").checked(show_grid).id_source("mi_g").show(ui);
MenuItem::new("Show Gizmos").checked(show_gizmos).id_source("mi_z").show(ui);
MenuItem::new("Snap to Grid").checked(snap).shortcut("Ctrl G").id_source("mi_s").show(ui);
}

Composition

Composes the Surface, Icon, Text, and Kbd atoms only. No painting — visuals come entirely from Surface + atoms. Enforced by tests/no_painter_in_molecules.rs.

Notes

• The shortcut is plain text (e.g. "Ctrl C"), rendered by Kbd; it does not bind a real accelerator — wire the key handling separately.
• Give each row a distinct id_source to avoid surface id collisions.
• checked only displays state — flip your own bool on .clicked(). Mixing checkable and plain rows in one menu is fine, but keep all rows of a toggle section checkable so the reserved slot keeps their labels aligned.

PropertyRow

Layer: cell · Path: src/cells/property_row.rs · Exports: property_row::PropertyRow

An aligned inspector row in the Unity-style two-column layout: a fixed-width muted label on the left and an arbitrary control on the right. The control is supplied as a closure at show time, so any widget (numeric field, color field, switch, …) can sit in the value column while labels stay vertically aligned across rows.

Design

• Purpose / when to use — Inspector / property panels where many heterogeneous controls must share a single aligned label gutter.
• Anatomy — A horizontal layout: a label slot of fixed label_width × core::CONTROL_MD holding a muted Text, followed by the consumer-provided control.
• Variants / states — None of its own; visual state lives in the control closure.
• Tokens / layout consumed — layout::PROPERTY_LABEL_WIDTH (default label column = 120px), core::CONTROL_MD (32px label slot height, matching the standard control height). See layout tokens and tokens.
• Accessibility — Label and control are separate widgets; the alignment is purely visual.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::PropertyRow;
use ouroboros_ui::atoms::NumericField;

let mut mass = 1.0_f32;
PropertyRow::new("Mass").show(ui, |ui| NumericField::new(&mut mass).speed(0.05).show(ui));
}

#![allow(unused)]
fn main() {
// realistic — a column of aligned inspector rows
let mut vals = [1.0_f32, 0.05, 0.6];
for (i, name) in ["Mass", "Drag", "Bounce"].iter().enumerate() {
    PropertyRow::new(*name).show(ui, |ui| {
        NumericField::new(&mut vals[i]).speed(0.05).show(ui)
    });
}
}

Composition

Composes the Text atom for the label; the value column is whatever the caller’s closure adds. No painting of its own — it only allocates the label slot and delegates. Enforced by tests/no_painter_in_molecules.rs.

Notes

• The control closure must return a Response (e.g. the inner widget’s show(ui) result); PropertyRow::show forwards it.
• The label slot height is fixed at core::CONTROL_MD (32px), so controls taller than that will not vertically center against the label.
• Keep label_width consistent across rows in the same panel (use the default) so labels line up.

ResponsiveRow

Layer: cell · Path: src/cells/responsive_row.rs · Exports: responsive_row::ResponsiveRow

The responsive sibling of PropertyRow. Wide, it keeps the Unity-style aligned label column with a right-anchored control; once the available width drops below INSPECTOR_ROW_STACK_MIN it stacks the label above a full-width control, so a squeezed side panel never clips the label↔control pair. The control is supplied as a closure at show time, like PropertyRow.

Design

• Purpose / when to use — Inspector / property panels that live in resizable side panels, where a fixed two-column row would clip when the panel is dragged narrow. For panels that never get narrow, the simpler PropertyRow is fine.
• Anatomy
  • Wide (available_width >= threshold): a label slot of label_width × core::CONTROL_MD holding a muted Text, then the consumer control anchored right (Layout::right_to_left) — the gap flexes on resize.
  • Narrow (available_width < threshold): a vertical stack — muted label, core::SPACE_1 gap, then the control filling the width.
• Variants / states — no visual variants; the single axis is the wide↔narrow switch driven by available width. Mirrors Field’s responsive orientation, with a lower default threshold tuned for inspector panels.
• Tokens / layout consumed — layout::PROPERTY_LABEL_WIDTH (default label column), layout::INSPECTOR_ROW_STACK_MIN (default stack threshold), core::CONTROL_MD, core::SPACE_1.
• Layering — cell: composes the Text atom + the consumer control; never paints (the no_painter_in_molecules guard scans cells).
• Accessibility — inherits from the embedded control.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::ResponsiveRow;
use ouroboros_ui::atoms::NumericField;

let mut mass = 1.0_f32;
ResponsiveRow::new("Mass").show(ui, |ui| {
    NumericField::new(&mut mass).speed(0.05).show(ui)
});
// Wide panel → "Mass    [ 1.0 ]" on one line; narrow panel → "Mass" above "[ 1.0 ]".
}

Composition

Cell: same two-column construction as PropertyRow in the wide branch, plus a vertical-stack branch chosen by ui.available_width() against the threshold. Composes the Text atom and the consumer-provided control.

Notes

• Stacking decision reads ui.available_width(), which is set by the parent panel/splitter — the same exogenous-budget model the rest of the layout uses.
• PropertyRow is not replaced: pick ResponsiveRow when the row sits in a resizable inspector that can get narrow; keep PropertyRow for fixed-width contexts (e.g. data-table value columns).

See tokens · theming · guards.

TableCell

Layer: cell · Path: src/cells/table_cell.rs · Exports: table_cell::{CellAlign, TableCell}

One cell of a table: a container that places its content (text by default, or an arbitrary widget) inside the column it is handed. A cell and a header are the same container — they differ chiefly in text weight (header = label_strong). Padding and alignment are token-driven; optionally a leading status dot (ColorSwatch) precedes the content. Carries a lifetime 'a because custom may borrow.

Design

• Purpose / when to use — Building block for the Table organism (and ad-hoc fixed-width row layouts). Use text(...) for the common case, custom(...) to embed any widget.

• Anatomy — A ui.with_layout(...) block: leading core::SPACE_2 pad, optional circular ColorSwatch status dot + core::SPACE_1 gap, then the content — a Text atom (weight/muted per flags) or the custom closure’s widget.

• Variants / states

  Modifier	Effect
  text(s)	text content (default)
  custom(add)	arbitrary widget content
  header()	Text::label_strong() (stronger weight)
  muted()	Text::muted() foreground (text content only; ignored for custom)
  status(color)	leading circular color dot, core::SPACE_2 diameter
  align: align(CellAlign) / center() / end()	content alignment within the cell

• Tokens / layout consumed — core::SPACE_2 (leading pad + status dot size), core::SPACE_1 (dot→content gap). See tokens.

CellAlign

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] — chooses the cell’s egui Layout:

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::{TableCell, CellAlign};

TableCell::text("Name").header().show(ui);          // header cell
TableCell::text("2.1 MB").end().show(ui);           // right-aligned value
TableCell::text("ref").status(theme.success).show(ui); // leading status dot
}

#![allow(unused)]
fn main() {
// realistic — building rows for the Table organism (see TableRow)
use ouroboros_ui::cells::{TableCell, TableRow};

TableRow::new([
    TableCell::text(&d.name),
    TableCell::text(&d.size).end(),
    TableCell::text(&d.status).status(color),
]);
}

#![allow(unused)]
fn main() {
// custom widget inside a cell
TableCell::custom(|ui| { Button::new("Open").show(ui); }).center().show(ui);
}

Composition

Composes the Text atom and (optionally) the ColorSwatch atom; custom cells embed whatever the closure adds. The cell never paints — alignment is an egui Layout, visuals come from the atoms. Enforced by tests/no_painter_in_molecules.rs.

Notes

• muted() is ignored for custom content (only text honors it).
• The cell fills the width it is handed; the surrounding column width is set by the Table organism (via egui_extras) — the cell itself does not size the column.
• 'a lifetime: a custom closure may borrow from the surrounding scope, which propagates through TableRow<'a>.

TableRow

Layer: cell · Path: src/cells/table_row.rs · Exports: table_row::TableRow

The row model for the Table organism: a Vec of TableCells plus row-level state (selected / selectable / key). It is a descriptor, not a renderer — TableRow has no show. The Table organism lays the cells out across the column widths (via egui_extras) and reads this state to drive selection. Carries lifetime 'a from its cells (a custom cell may borrow).

Design

• Purpose / when to use — Always paired with Table: construct one TableRow per data row and pass the collection to Table::rows(...).

• Anatomy — Fields (crate-visible, consumed by the organism): cells: Vec<TableCell<'a>>, selected: bool, selectable: bool (default true), key: Option<u64>.

• Variants / states

  Modifier	Effect
  selected(true)	row highlighted by the Table organism
  selectable(false)	row cannot be selected (default is selectable)
  key(u64)	stable identity for selection / tree operations

• Tokens / layout consumed — None directly; the organism applies row height (layout::TABLE_ROW_HEIGHT, 28px, or a size variant) and selection styling. See layout tokens.

API

There is no show — TableRow is consumed by Table::rows(...), not rendered standalone.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::{TableRow, TableCell};

TableRow::new([
    TableCell::text("width"),
    TableCell::text("1920").end(),
]);
}

#![allow(unused)]
fn main() {
// realistic — feeding the Table organism with selection
use ouroboros_ui::cells::{TableRow, TableCell};
use ouroboros_ui::organisms::{Table, Column};

let rows = data.iter().enumerate().map(|(i, d)| {
    TableRow::new([
        TableCell::text(&d.name),
        TableCell::text(&d.size).end(),
        TableCell::text(&d.status).status(d.color),
    ])
    .key(i as u64)
    .selected(selected == Some(i as u64))
});

Table::new()
    .columns([Column::auto(), Column::auto().end(), Column::remainder()])
    .rows(rows)
    .show(ui);
}

Composition

Composes TableCells only and holds plain state. It paints nothing and renders nothing on its own — rendering is the Table organism’s job. Consistent with the cells rule enforced by tests/no_painter_in_molecules.rs.

Notes

• Pure data: the cells are stored, not drawn, until the organism iterates them across columns.
• Provide a stable key when the table supports selection or tree state so identity survives reordering.
• The 'a lifetime flows from TableCell<'a> (a custom cell may borrow); keep borrowed data alive until the table is shown.

ToolbarButton

Layer: cell · Path: src/cells/toolbar_button.rs · Exports: toolbar_button::ToolbarButton

An icon toggle button with an optional hover tooltip, modelled on Unity/O3DE toolbars. It wraps the Toggle atom in icon mode and binds it to a &mut bool (the active state). When a tooltip is set the response is wrapped by the Tooltip atom. Carries lifetime 'a from the mutable borrow.

Design

• Purpose / when to use — Tool palettes / toolbars where each button is a momentary-or-sticky icon toggle (select / move / rotate, view modes, snapping flags).

• Anatomy — A Toggle in .icon(glyph) mode bound to the &mut bool, optionally decorated by a Tooltip over the resulting response.

• Variants / states

  State	Source
  active / inactive	the bound &mut bool (mutated in place by Toggle)
  tooltip on hover	present only when tooltip(...) was set

• Tokens / layout consumed — Inherited from the Toggle atom (sizing/fill); ToolbarButton adds none of its own. See tokens.

• Accessibility — Tooltip provides the textual label for an otherwise icon-only control; prefer always setting tooltip(...).

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::ToolbarButton;
use ouroboros_ui::egui_phosphor::light;

let mut active = true;
ToolbarButton::new(&mut active, light::CURSOR).tooltip("Select").id_source("tb0").show(ui);
}

#![allow(unused)]
fn main() {
// realistic — a horizontal tool palette over an array of flags
let mut state = [true, false, false];
ui.horizontal(|ui| {
    ToolbarButton::new(&mut state[0], light::CURSOR).tooltip("Select").id_source("tb0").show(ui);
    ToolbarButton::new(&mut state[1], light::ARROWS_OUT).tooltip("Move").id_source("tb1").show(ui);
    ToolbarButton::new(&mut state[2], light::ARROWS_CLOCKWISE).tooltip("Rotate").id_source("tb2").show(ui);
});
}

Composition

Composes the Toggle atom (icon mode) and, when a tooltip is set, the Tooltip atom. It paints nothing — all visuals come from Toggle. Enforced by tests/no_painter_in_molecules.rs.

Notes

• Binding: active is &mut bool — the toggle flips it in place; there is no selected/return-value to read for state, only .clicked() on the response for reacting to a press.
• Give each button an id_source (e.g. "tb0"); buttons sharing the same glyph would otherwise collide on the toggle’s auto id.
• Mutually-exclusive tools (radio-like) are the consumer’s responsibility — reset the other flags when one is clicked.

TreeNode

Layer: cell · Path: src/cells/tree_node.rs · Exports: tree_node::TreeNode

An indented hierarchy row: a depth-based indent, an optional expand/collapse caret, an optional icon, and a label. Modelled on Unity/O3DE tree views. Expansion and selection are inputs, not state — show returns the [Response] and the consumer toggles expand/selection itself.

Design

• Purpose / when to use — Scene graphs, file trees, outliners — any flattened hierarchy rendered row-by-row with per-row depth.

• Anatomy — A Surface (interactive, padded) wrapping a horizontal layout: indent space (depth × core::SPACE_4), a caret Icon (CARET_DOWN/CARET_RIGHT, small, muted) or an core::ICON_SM spacer when not expandable, optional muted Icon, then the Text label.

• Variants / states

  State	Effect
  default	Surface::fill_none().border_none()
  selected (selected(true))	Surface::muted() fill
  expandable + collapsed	light::CARET_RIGHT caret
  expandable + expanded	light::CARET_DOWN caret
  not expandable	core::ICON_SM spacer (keeps labels aligned with carets)
  indent	depth as f32 * core::SPACE_4 leading space

• Tokens / layout consumed — core::SPACE_4 (16px per depth level), core::SPACE_1 (4px outer pad + gaps), core::ICON_SM (14px caret slot), core::RADIUS_SM (4px). See tokens.

• Accessibility — Selection/expansion are visual inputs; pair with a real tree model.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::cells::TreeNode;
use ouroboros_ui::egui_phosphor::light;

TreeNode::new("Scene").icon(light::FOLDER).expandable(true).id_source("tn0").show(ui);
}

#![allow(unused)]
fn main() {
// realistic — a flattened tree with depths and selection
TreeNode::new("Scene").icon(light::FOLDER).expandable(true).id_source("tn0").show(ui);
TreeNode::new("Player").depth(1).icon(light::CUBE).expandable(false).selected(true).id_source("tn1").show(ui);
TreeNode::new("Camera").depth(1).icon(light::CUBE).id_source("tn2").show(ui);
TreeNode::new("Mesh").depth(2).icon(light::CUBE).id_source("tn3").show(ui);
}

Composition

Composes the Surface, Icon (caret + leading icon), and Text atoms only. It paints nothing — visuals come from Surface + atoms. Enforced by tests/no_painter_in_molecules.rs.

Notes

• expandable(expanded) does double duty: it both marks the node expandable and sets the caret direction. There is no separate “is expandable” flag — calling it at all makes the node expandable.
• Expansion/selection are not remembered by the cell. Drive them from a tree model and toggle on .clicked() (and detect a caret-vs-row click yourself if needed).
• Non-expandable rows reserve an core::ICON_SM spacer so their labels align with sibling carets.
• Caret glyphs come straight from egui_phosphor::light (CARET_DOWN / CARET_RIGHT).

Alert

Layer: molecule · Path: src/molecules/alert.rs · Exports: alert::{Alert, AlertVariant}

A status callout — an inline banner that surfaces a build result, validation outcome, or notice. The variant drives both the leading glyph and an accent color pulled from the active [Theme]. Analogous to the shadcn Alert / Unity Help Box.

Design

• Purpose / when to use — Communicate a contextual status (info / success / warning / error) inline in a panel. Not a toast; it stays in the layout flow.

• Anatomy — Surface container, padded SPACE_3 → horizontal row of a status Icon (accent-colored) + a vertical text stack of an optional accent Text title (body_strong) and the muted message body.

• Variants / states

  Variant	Glyph (egui_phosphor::light)	Theme color
  Info (default)	INFO	theme.info
  Success	CHECK_CIRCLE	theme.success
  Warning	WARNING	theme.warning
  Error	WARNING_CIRCLE	theme.error

• Tokens / layout consumed — core::SPACE_3 (surface pad), SPACE_2 (icon→text gap), SPACE_1 (title→message gap); colors from Theme. See tokens.

API

AlertVariant — Info (default), Success, Warning, Error.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Alert;

// minimal
Alert::new("Build finished in 2.3s.").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::{Alert, AlertVariant};

// realistic — titled error
Alert::new("Shader failed to compile.")
    .title("Notice")
    .variant(AlertVariant::Error)
    .show(ui);
}

Composition

Composes Surface + Icon + Text only, laid out with ui.horizontal / ui.vertical. It never paints primitives — see the guards.

Notes

• The message is required; the title is optional and renders in the variant accent color.
• Color resolution happens at show time via Theme::get(ui), so alerts re-theme automatically.

Breadcrumb

Layer: molecule · Path: src/molecules/breadcrumb.rs · Exports: breadcrumb::Breadcrumb

A horizontal path trail. Every item except the last renders as a link-style Button separated by caret icons; the last item is plain strong text (the current location). show reports which crumb was clicked this frame. Analogous to the shadcn Breadcrumb.

Design

• Purpose / when to use — Show hierarchical location (asset path, navigation trail) and let the user jump back to an ancestor.
• Anatomy — ui.horizontal row of: per non-last item a small link Button followed by a muted CARET_RIGHT Icon; the final item a body_strong Text.
• Tokens / layout consumed — none directly; relies on atom sizing (Button::sm, Icon::sm). See tokens.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Breadcrumb;

// minimal
Breadcrumb::new().items(["Home", "Library"]).show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Breadcrumb;

// realistic — react to a click
if let Some(i) = Breadcrumb::new()
    .items(["Assets", "Models", "Characters", "hero.fbx"])
    .show(ui)
{
    navigate_to_depth(i);
}
}

Composition

Composes Button (ButtonVariant::Link), Icon, and Text. It never paints — see the guards.

Notes

• Returns Option<usize> rather than a Response — the index is the actionable signal.
• Per-crumb button ids are derived via .id_source(("crumb", i)), so multiple breadcrumbs in one frame are safe.
• The last crumb is non-interactive by design (it’s the current node).

Card

Layer: molecule · Path: src/molecules/card.rs · Exports: card::{Card, CardSize}

An elevated Surface with an optional header (title + description + a top-right action slot), arbitrary content (a closure), and an optional footer separated by a divider. size scales the internal padding and gaps. Models the shadcn Card (Header / Content / Footer / CardAction).

Design

• Purpose / when to use — Group related content into a raised panel: a settings block, a summary, a property editor section.

• Anatomy — Surface::elevated() (padded by size) → vertical stack of:

  1. Header (only if title/description/action set): horizontal row of a vertical Heading title + muted caption Text description, with the action closure laid out right-to-left at the top-right.
  2. Content — your content closure, always run.
  3. Footer (if set): a Divider then your footer closure.

• Sizes

  CardSize	pad	header/footer gap
  Default	SPACE_4	SPACE_3
  Sm	SPACE_3	SPACE_2

• Tokens / layout consumed — core::SPACE_4 / SPACE_3 / SPACE_2 / SPACE_1; elevation from Surface. See tokens.

API

CardSize — Default (default), Sm.

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Card;
use ouroboros_ui::atoms::Text;

// minimal
Card::new().title("Compact").show(ui, |ui| {
    Text::new("Body content.").show(ui);
});
}

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Card;
use ouroboros_ui::atoms::{Button, Text};
use ouroboros_ui::egui_phosphor::light;

// realistic — header action + footer buttons + closure body
Card::new()
    .title("Project settings")
    .description("Manage your project preferences")
    .action(|ui| {
        Button::new("")
            .icon_left(light::DOTS_THREE)
            .icon_only()
            .ghost()
            .sm()
            .id_source("card_menu")
            .show(ui);
    })
    .footer(|ui| {
        ui.horizontal(|ui| {
            Button::new("Save").id_source("card_save").show(ui);
            Button::new("Cancel").ghost().id_source("card_cancel").show(ui);
        });
    })
    .show(ui, |ui| {
        Text::new("Card body content goes here.").show(ui);
    });
}

Composition

Composes Surface + Heading + Text + Divider. Body, action, and footer are caller-supplied closures. It never paints — see the guards.

Notes

• Card<'a> carries a lifetime: the action/footer closures are boxed (Box<dyn FnOnce(&mut Ui) + 'a>) and may borrow from the surrounding scope.
• content is a plain impl FnOnce(&mut Ui) (not boxed) and always runs, even with no header/footer.
• The header is omitted entirely when none of title/description/action are set.
• Give interactive widgets inside the slots stable id_sources when multiple cards share a frame.

CheckboxCard

Layer: molecule · Path: src/molecules/checkbox_card.rs · Exports: checkbox_card::CheckboxCard

A selectable card bound to a &mut bool: an interactive Surface wrapping a display-only Checkbox plus a label and optional description. The whole card is the click target — clicking anywhere toggles the bound bool (the inner checkbox is non-interactive, so there is no double-toggle).

Design

• Purpose / when to use — A larger, more legible alternative to a bare checkbox for opt-in settings, where a description helps.
• Anatomy — Surface::new().interactive().selected(checked) padded SPACE_3 → horizontal row of a display Checkbox (.interactive(false)) + a vertical stack of a body_strong Text label and an optional muted caption description.
• States — selected visual driven by Surface::selected(*checked); hover/press handled by Surface::interactive().
• Tokens / layout consumed — core::SPACE_3 (pad + checkbox→text gap). See tokens.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::CheckboxCard;

// minimal
let mut on = true;
CheckboxCard::new(&mut on, "Enable notifications").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::CheckboxCard;

// realistic — with description + stable id
CheckboxCard::new(&mut on, "Enable notifications")
    .description("Email + in-app alerts")
    .id_source("cc")
    .show(ui);
}

Composition

Composes Surface + Checkbox + Text. It never paints — see the guards.

Notes

• Two-way binding: show writes *self.checked = !*self.checked when the surface is clicked.
• The inner checkbox is mirrored display state (.interactive(false)), so it doesn’t compete for the click.
• Set id_source to avoid surface-id collisions when stacking multiple cards.

Collapsible

Layer: molecule · Path: src/molecules/collapsible.rs · Exports: collapsible::Collapsible

A caret-headed section that hides or reveals its content. Open state persists in egui temp memory keyed by id (or by the title), so it survives across frames. The content closure only runs when open. Analogous to the shadcn Collapsible / Unity Foldout.

Design

• Purpose / when to use — Inspector sections, settings groups, anything foldable to manage vertical density.
• Anatomy — A clickable header row: a muted caret Icon (CARET_DOWN when open, CARET_RIGHT when closed) + SPACE_1 + a body_strong Text title. When open, SPACE_2 then the content closure.
• States — open / closed, toggled by clicking the header. Persisted via ui.data temp storage under the resolved id.
• Tokens / layout consumed — core::SPACE_1 (caret→title), SPACE_2 (header→content). See tokens.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Collapsible;
use ouroboros_ui::atoms::Text;

// minimal
Collapsible::new("Rendering").show(ui, |ui| {
    Text::new("Material, shadows…").muted().show(ui);
});
}

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::Collapsible;
use ouroboros_ui::atoms::Text;

// realistic — open by default, explicit id
Collapsible::new("Transform")
    .default_open(true)
    .id_source("inspector::transform")
    .show(ui, |ui| {
        Text::new("Position / Rotation / Scale").muted().show(ui);
    });
}

Composition

Composes Icon + Text, with ui.interact over the header row’s rect for the click target. It never paints — see the guards.

Notes

• Open state lives in ui.data temp memory under the resolved id; the interaction id is id.with("header").
• The returned Response is the header (use .clicked() to react to toggles beyond the visual).
• If two collapsibles share a title, pass distinct id_sources to avoid shared open state.

ColorField

Layer: molecule · Path: src/molecules/color_field.rs · Exports: color_field::ColorField

A color editor bound to a &mut Color32: a ColorSwatch preview next to an editable hex Input. Clicking the swatch opens a full HSV/RGB/hex picker in a popover. Inspired by Unity / Figma color fields.

Design

• Purpose / when to use — Edit a single color value: a tint, a material albedo, a UI accent override.
• Anatomy — ui.horizontal row of: a ColorSwatch showing the current color, SPACE_2, then an Input holding the hex string (#RRGGBB). A popover menu anchored on the swatch hosts egui’s color_picker_color32.
• States — alpha editing optional via .alpha(true) (switches the picker’s Alpha mode from Opaque to OnlyBlend).
• Tokens / layout consumed — core::SPACE_2 (swatch→input gap), core::CONTROL_LG * 6.0 (picker popover max width). See tokens.

API

Usage

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::ColorField;
use egui::Color32;

// minimal
let mut c = Color32::from_rgb(26, 188, 156);
ColorField::new(&mut c).id_source("cf1").show(ui);
}

#![allow(unused)]
fn main() {
use ouroboros_ui::molecules::ColorField;

// realistic — alpha editing
ColorField::new(&mut c)
    .alpha(true)
    .id_source("material_albedo")
    .show(ui);
}

Composition

Composes ColorSwatch + Input, plus egui::Popup::menu hosting egui::color_picker::color_picker_color32 — a built-in egui widget, not a paint call. It never paints primitives directly — see the guards.

Notes

• Two-way binding: typing a valid hex into the input (Color32::from_hex) writes back into *color; the picker writes directly into *color.
• The hex string is recomputed from the bound color every frame as #{:02X}{:02X}{:02X} (RGB only — alpha is edited through the picker).
• Pass a unique id_source per field — the default "color_field" collides if several share a frame.
• The returned Response is the hex input’s, so .changed() fires on hex edits.

Field (family)

Layer: molecule · Path: src/molecules/field.rs · Exports: field::{Field, FieldGroup, FieldOrientation, FieldSeparator, FieldSet}

The form-layout family. Field wraps any control with a label and a hint/error line in one of three orientations. FieldGroup stacks fields with a standard gap; FieldSet groups them semantically under a legend; FieldSeparator divides groups with an optional inline label. FieldOrientation selects vertical / horizontal / responsive layout. Modeled on the shadcn Field primitives.