Start with AGENTS.md (the mental model, the ten things you write, the rules, how to verify). DESIGN.md is the contract; §1.15–§1.17 cover ripple rules, recomposition and the AI-facing surface.
Docs
- AGENTS.md: how to write and verify interfaces here
- DESIGN.md: the design contract, every number and acceptance
- registry.json: the widgets, their files, responses, recomposition and recipes
- README.md ↗: what amenui is, install and quick start
- docs/README.md: the documentation index: guides, references, design
- Architecture: the pipeline and what each module owns
Recipes
- A form: code in examples/form.rs
- A list with selection: code in examples/list.rs
- A dialog: code in examples/dialog.rs
- A page change with a shared part: code in examples/flow.rs
- Morph A into B: code in examples/morph.rs
- A custom material on one element: code in examples/material.rs
- The annotation layer on a subtree: code in examples/annotate.rs
- A counter with recomposition and a scoped ripple: code in examples/counter.rs
- A 3D object in a card: code in examples/mesh.rs
- A custom preset with its own transition: code in examples/preset.rs
- A chapter: one scene with actors that flow in: code in examples/chapter.rs
- Gestures: a bottom sheet and a floating box: code in examples/gesture.rs
- A menu with submenus and a safe zone: code in examples/submenu.rs
- A list that loads: code in examples/loading.rs
- A stack of cards that fans: code in examples/stack.rs
- A dot chart: code in examples/chart.rs
- Text on a form: code in examples/form3d.rs; depth, facing, thinning, words whole, the pointer on the surface (
El::form,form::Form,Form::hit)
Lab
The Lab (#lab) is a grid of small live experiments, one file each in the website repository's examples/lab/, written against the public API (amenui::experiment::Experiment); each has a page #lab-<name> with its formula and parameters (registry.json experiments). Each piece fills a 4:3 stage; the numbers open under [ params ]; seen cells run every frame (reduced motion: they rest).
- Lumen: light on text, tone by distance, outlines untouched (
El::pose) - Contours: iso-lines of noise plus a pointer bump (
field::Grid::contours) - Silk: marks advected by curl noise and a stirred flow (
field::Swarm,budget::grant) - Grown: Gray–Scott inside an element's true outline (
El::on_outline,field::GrayScott) - Mercury ↗: metaballs with a spring-followed ball (
field::Balls) - Flow: text on a waving path (
Pose::angle) - Loupe: text on a sphere, drag to spin
- Orbit ↗: Kepler orbits with pointer attraction
- Spring: the gesture spring, dragged and thrown
- Stack: the card stack in the lab's look
- Body: the landing page and first scene (
#body, the website'sexamples/body.rs): a passage gathers into a turning, luminous body of its own glyphs and back; full-bleed, markings in the picture; two rest states, glyph count conserved - Decode ↗:
El::decode, blocks over the true outline resolving coarse to fine (#decode) - Field map ↗:
El::stirrtrails andCmd::Stir, energy and flow that settle to zero; decoration loosens and drifts behind what moves (#stirr) - scribblr ↗: the thread material, plain at rest, loose ink as one line that knots and trails off and writes itself back;
El::tracelong paths, solid or dashed (#material-scribblr,#stirr) - Edge notes and readouts ↗:
El::tracking,El::whisper()in a small serif;gaze::EDGE,OSC,LEVELread the runtime and the field map (Ui::readout()); the Loose Thread preset withpost.binaryandpost.invert(#style-loose-thread) - Text on a form ↗:
Pose::zandPose::facing,El::form(FormFx),form::FormandForm::hit;Ui::glyph_atandEl::turnhit what is drawn (src/hit.rs) - Warm-up ↗:
Renderer::begin,Warmup::step, plain first, then the look arriving at rest and coming apart a little over 120 ms;Ui::prepare/Ui::ready(src/warmup.rs) - Audit ↗:
render --audit [--strict],drive::audit: text cut off, contrast, overlap, size, restlessness, text a material wears away, each with a fix;gaze::INK - Materials as source ↗: one WGSL file per material (
src/materials/<name>.wgsl);amenui add material <name>,Look::material_source;El::effect(Effect)andel::wrap_textput one on existing text - Sample sheets ↗:
sheet --material <name> --loose 1,0.5,0 --arrival, a material at several loosenesses and as it arrives, checked
Pages
Every documentation page as Markdown, at md/en/<page>.md and md/zh-Hans/<page>.md next to the web build (cargo run --release --bin md -- dist/md).
- Introduction: amenui is an interface framework that draws every pixel itself, written in Rust on wgpu; the same code runs in a native window and on the web.
- Installation: Pick the host your interface lives in.
- Command line: Components are distributed as source, the way shadcn/ui does it: you copy a component's file into your project and change it there.
- Your first view: A view is a function from state to an element tree; an update is a function from state and a message to a new state.
- Project structure:
- Forms: A form is state and messages, like everything else: the state holds every value, each widget sends a message for each edit, and update is the only place a va…
- The tree and messages: After every message the runtime calls view(&state) once, gets a new El tree, compares it with the last by key and lays out again only what changed.
- Layout: Layout is taffy's flexbox and grid, in logical pixels; elements do not shrink unless asked.
- Text: Text is set by parley and rasterised by swash; every atlas pixel holds coverage and the signed distance to the stroke, so every material draws a glyph by its…
- Materials and looseness: A material is how the second pass draws: plain, dottr, halftonr, charr, smudgr, carvr, glitchr, near, scribblr.
- Ripple rules: A press sends a front that by default reaches only the control pressed (Scope::Own); Scope::Container and Scope::Global reach further.
- Transforms: Two kinds: a morph (Cmd::Morph: one element breaks into cells that fly onto another's shape) and a flow (Cmd::Flow: what two pages share moves to its new pla…
- Presets: A style preset is data: theme, material and its numbers, annotation, interaction character, how scrolling looks, and a transition program.
- Annotation: The third pass is the annotation layer: frames, numbers, sizes, leaders and rulers drawn from the real layout, never loosened.
- 3D: el::scene3d(Scene3d) is one more element on the page: meshes are drawn off screen into shade, normals and depth, then become ink and nearness like glyphs, so…
- Particles: When a morph has many cells it is simulated on the GPU (a compute shader, or ping-ponging float targets), otherwise on the CPU, where a mesh side's cells sta…
- Languages: Each language has a message catalog (`assets/i18n/zh-Hans.
- Accessibility: The screen is drawn by the framework, so the runtime builds an accessibility mirror from the tree: every element's role (the WAI-ARIA role of the same name),…
- Performance: Draw only when something changed; draw only what changed (two boxes); scrolling moves, it does not lay out again; a long list builds only the rows that show;…
- Testing with render and the tree: render plays events on a fixed 60 Hz clock and draws the last frame and its tree; the same arguments give the same bytes.
- Theming and dark mode: A theme is a set of colours and the faces for display, body and monospace (style::THEMES).
- Right to left: A row lays out from the right when its direction is right to left: El::rtl(true) on the row (or any ancestor), or a locale that reads right to left.
- Registry schema: `registry.
- button: Perform an action.
- number: Set a value exactly: type it once focused, or step it with the arrow keys and the buttons on either side; drag across the value to scrub it.
- input: Enter one line or several (textarea).
- switch: Turn a setting on or off.
- slider: Pick a value roughly within a range.
- tabs: Switch between groups of content in the same place.
- choice: Choose one of a few mutually exclusive options.
- list: Show a set of items, one of which can be selected; it scrolls when there are many.
- card: Keep related content together in a bordered area.
- dialog: Show content that needs attention above the page.
- image: Show a picture at its own aspect ratio.
- divider: Separate two groups of content.
- scroll area: Show longer content in a fixed height, scrolled with the wheel; a thin bar at one side shows the position.
- menu: A button that shows the current option; pressing it lists every option in a layer below it.
- orbit: Turn a 3D view: drag to orbit, the wheel to dolly, the arrow keys once focused; a quick drag coasts to a stop.
- checkbox: Choose whether one option applies.
- radio: Choose one of a few visible options.
- select: Choose one option from a list that opens on demand.
- tooltip: A short description shown while a control is hovered or focused.
- popover: Rich content in a layer anchored to a button.
- toast: A brief notice in a corner that goes away by itself.
- progress: How far a task has come, or that it is going on.
- accordion: Sections that open and close under their headings.
- table: Rows of records with named columns.
- badge: A small label for a status or a count.
- avatar: Stands for a person by their initials (no pictures).
- skeleton: Holds the place of content that is still loading.
- breadcrumb: Where this page is in a hierarchy, each level a link back.
- pagination: Move between pages of results.
- sheet: A panel over one side of the window.
- context menu: Commands for what is under the pointer, opened where it is.
- command: Find and run a command by typing.
- toggle: A button that stays pressed, or a group of them.
- bottom sheet: A panel that rises from the bottom edge: dragged by its handle or body between detents, swiped down to dismiss.
- floating: A small box floating over an area (picture in picture): drag it anywhere; let go, the throw's projected end picks the nearest corner and a spring takes it th…
- caption: A small monospaced line under a live demo that prints the parameters driving it (read from the same fields, never typed by hand), each also a number control.
- nested menu: A menu whose rows open submenus, steered by where the pointer heads: moving toward an open submenu inside the triangle from its previous position to the subm…
- card stack: A stack of cards: hover or press one and the cards beneath fan out about their bottom-left corners, card n turning angle0 × falloff^n (42° × 0.
- dot chart: A series as a field of dots: each column filled from the axis up to the curve, a dot's size and brightness saying how much of it lies under the curve (the ar…
- AGENTS.md: amenui is a self-drawn interface framework in Rust (wgpu; the same code runs natively and on the web).
- llms.txt: Start with AGENTS.
- Registry: {
- Changelog: What changed, newest first.
Optional
- src/el.rs ↗: the element tree and its builders
- src/ui.rs ↗: the runtime
- src/drive.rs ↗: scripted input and the render tool
- src/field.rs ↗: fields: noise, bumps, metaballs, curl, grids, marching-squares contours, flows, swarms, masked Gray–Scott
- src/draw.rs ↗: drawings (
el::canvas): dots and strokes as shapes with true outlines - src/budget.rs ↗: the frame budget every small mark draws from
- src/wrap.rs ↗: text around true outlines (
.around(Around)); a piece beside an obstacle is justified flush on both edges, at mostAround::justify_maxems per gap (default 0.25), between Latin letters only withAround::justify_latin_letters(default off)