Files
craft-libs/docs/craft-framework.md
T
aiongg f04b5867fa Color panel look (fix round): channel rows at production density with content-sized fields and the colour band of size.ramp.bar; readout letters and fold; framed edited well; gamut warning beside its swatch; ramp a control tall
- PaintUi::measure: a composite measures a child as PaintUi::child shows it.
- SliderField::field_sizing; the Inline field takes its measured width.
- Slider: the triangle starts under the colour band; TrackLook::ramp is size.ramp.bar.
- NumberField: a field that rounds what it commits is sized at those places; a mixed field is sized as with a value.
- ColorReadout: a wrapping row, the hex field then R, G, B fields after their letters, each content-sized.
- SwatchPair::frame_active; ColorWarningChip::beside.
2026-11-13 19:26:50 +00:00

123 KiB

Craft framework

The Craft framework is the shared layer under every Craft app: the design system, shells, canvas core, host convention and feature families, supplied by craft-libs as one dependency.

Porting an existing app onto the framework: porting.md.

Contents

1. Overview

1.1 What the Craft framework is

The Craft framework is the shared layer under every Craft app, supplied by craft-libs as one library. It holds the design system, shells and canvas core, the host convention and the feature families. The framework builds each feature once and uses it everywhere, so copies cannot drift apart in look, behaviour, accessibility and translation.

1.2 Framework and design system

Term Meaning
Craft framework The whole shared layer
Design system Tokens, themes and component layers. One part of the framework
UI library The design-system layers every family uses, with no document concept: six crates (craft-ui-contract to craft-ui-shell) and the craft-ui facade that re-exports them (3.2)
Family A set of features a developer looks for together (colour, layers, timeline). One crate each

App engineers need the framework: sections 2 and 3. Component and theme authors need the design system: sections 4 to 8.

1.3 Principles

  • Apps ask for meaning. A raised surface, a primary button, muted text. Never a colour or pixel size. A lint checks app code (8).
  • Apps keep their layout and conventions. The code and behaviour of the building blocks are shared (4.5).
  • Behaviour follows the industry original. Without one, it follows the app's existing behaviour. Where an app draws one kind of component several ways, the library has one.
  • Apps own the document. Features hold no document state or undo history.
  • Accessibility and translation are required (7). A missing translation never blocks.
  • Colour management goes through craft-cms. A missing capability is added there.

2. Installation

The gallery shows every registered story of every crate with a ui feature, under every theme. Themes switch at run time. It needs Rust 1.95 or later.

git switch craft-framework
cargo run --profile gallery -p craft-ui-gallery
  • The gallery profile is release optimisation with incremental builds; cl build gallery builds the debug gallery instead. Both are described in development.md, with the story renderer (cl render), which writes one component's stories to PNG files without building the gallery.
  • Update with git pull and rebuild.
  • Candidate fonts are optional: check out a craft-fonts repository and set CRAFT_FONTS_DIR=<absolute path> before building (craft-fonts-build).

2.2 Depend on craft from an app

An app has one dependency, one pin and one import root.

[dependencies]
craft = { git = "https://github.com/storytold/craft-libs", rev = "...", features = [
    "ui", "color", "layers", "theme-store", "platform-clipboard",
] }
use craft::prelude::*;
use craft::color::ui::{ColorPicker, SwatchPalette};

The facade's rules and features are in 3.3.

An app that has no eframe App of its own implements ShellApp and starts with shell::app::run (start_web on the web), which installs the runtime and drives every frame. Both need the facade's ui-app feature.

Host the runtime from your own eframe App

An app with its own eframe App calls the hooks in craft::ui::shell::embed. app::run's driver calls the same hooks, so both kinds of app run the same code.

When eframe method Call
Once, when the app is created with the CreationContext embed::install(ctx, InstallSpec, &UiFonts): the runtime, then the app's fonts. Returns the font Stack.
Each frame raw_input_hook embed::before_input(ctx, |output| { ...; input }): the closure receives the FrameOutput of the frame before (fired commands, announcements, chrome toggles) and returns the FrameInput for this frame (RootEnv, command states, the Host).
Each frame logic, after the app's own logic embed::logic(ctx, || decision): the root window's close path. The closure runs only when the root window was asked to close, and returns CloseDecision::Close or Hold.
Each pass ui, before the app's UI embed::before_ui(ctx, frame): hands the runtime the native window on Windows, and fits the root window to its monitor once. Needs ui-app.
Each pass ui, where the app draws its own document canvas Optional: ui::runtime::focus::host_canvas(ctx, id, KeyUse::CANVAS) declares it as the window's canvas (Tab row below).
Each pass ui, last Optional: ui::runtime::keys::with_window_intents(ctx, rtl, |intents| ...) reads the keys no component took (below).

install takes over these parts of the context for the whole window, not only for framework components:

What Effect on the app's own egui code
Tab Bare Tab moves framework focus and never reaches egui, unless the focused framework stop keeps Tab or an app's own widget has the focus (below), or nothing has the focus in a window that registered no focus stop: egui then moves its own focus into the app's widgets. A window with stops but no Tab entry (on the Mac, where Tab reaches only text fields by default) keeps the Tab from egui, which would otherwise focus framework controls the platform's rule skips. With RootEnv::tab_toggles_chrome, Tab toggles the chrome in a window that shows a document canvas, with nothing focused or the canvas focused, and arrives in FrameOutput::chrome_toggles. The canvas is a framework canvas, or the app's own egui canvas declared each pass with ui::runtime::focus::host_canvas. With nothing focused, the canvas is the key target: a canvas that keeps Tab (KeyUse::CANVAS.with_keep(KeepKeys::Tab)) gets the press in egui's input, as when it is focused, and nothing toggles.
F6 F6 and Shift+F6 move between panes and never reach egui. They are the defaults of the commands window.nextPane and window.previousPane (NavCommand): a default chord that another command binds is that command's, and the overrides move or unbind them (CommandInput::overrides). An app whose own shortcut table keeps F6 unbinds them there.
Escape Plain Escape (Alt and Shift may be held) goes to the focused framework stop and its scopes; with no framework stop focused, it goes to the window as Intent::Cancel. It reaches egui only while an app's own widget has the focus (below). An Escape the runtime takes outside a captured framework press also ends egui's own drag in that pass, as egui's Escape does.
F10, Alt+letter Taken while a framework menu bar is registered: F10 (window.focusMenuBar, bound and yielded as F6 is) focuses the bar, Alt+letter opens a menu (not on macOS).
Edit chords Taken while a framework editor is focused. With nothing focused, the edit chords and egui's copy, cut and paste events of the commands in the window canvas's edit set (KeyUse::edits, host_canvas) stay in egui's input for it, and no command fires with them. Otherwise egui's copy, cut and paste events become the ⌘C/X/V chord for the app's commands, unless an app's own widget has the focus (below). While egui holds a label text selection, copy and cut stay egui's, and egui copies the selection.
IME Taken while a framework editor owns the IME: its events and PlatformOutput.ime are the runtime's. Otherwise they stay egui's, for the app's own TextEdit or IME code.
An app's own focused widget While egui focus is on a widget no framework component made, or an egui popup is open, and no framework press or drag is captured, Tab, Shift+Tab, Escape and egui's clipboard events stay in egui's input for it, and the runtime routes nothing for them. While egui focus is on such a widget, the arrows and Tab move egui focus among the app's widgets as egui does; while a framework stop has the focus, egui's arrow moves are off.
Releases The release of every key the runtime took is taken too.
Focus surrender The runtime moves its own focus on press (8.3): a press a framework component takes moves focus to it; a press no component takes drops the framework's focus. egui's click-away never takes the framework's focus. egui's surrender option (InputOptions::surrender_focus_on) stays the app's and governs the focus of the app's own widgets, as in egui alone: a press no component takes leaves that focus to egui's rule.
Clicks egui's click options (InputOptions::max_click_dist, max_click_duration) stay the app's, for its own widgets. A framework component clicks and drags by the framework's press lifecycle: a release within the slop (HitSizes::slop), whatever its duration. Read a component's click with contract::clicked(&response) or its output's clicked(); egui's Response::clicked() on a component's response also needs a click by egui's options.
Zoom keys egui's keyboard zoom is off. The interface scale is RootEnv::scale.
Quit shortcuts egui's quit shortcuts are cleared. Quit goes through the close path.
Close path The runtime's window host owns the root window's close request. embed::logic asks the app through its closure, then hands the close to the platform quit where there is one (macOS).
Input pacing One press per pass: extra presses in one frame wait for the next passes. A press outside an open framework menu closes the menu and goes no further. After an OS resize of the window, the held pointer is released.

The window's keys are the ones the runtime routes to no component: an Escape or a plain Enter while no framework stop is focused, and the arrows' nudge. with_window_intents offers them to its closure while nothing has framework focus. The closure takes what it handles (Intents::take(Intent::Cancel); Intent and the other types Intents reads are in ui::runtime::keys) and returns whether it took anything; the rest stays for later readers. A framework scope that ran earlier in the pass takes them first (an open dialog takes the Escape that closes it), so the app reads them last in its UI to see what no component took. App code that read Key::Escape, Key::Tab, F6 or F10 from egui while none of its own widgets had focus reads these intents and FrameOutput::chrome_toggles instead; its own focused widgets and popups keep reading Tab and Escape from egui.

Framework dialogs the app keeps as values run on a DialogHost: the app calls run(ui) once per pass after its own UI and reads results with take.

2.3 Build, test and render a component

Inside craft-libs, every local cargo command goes through tools/cl, which gives every build the same feature set so the framework is built once per target directory (development.md):

What Command
Check the crate you changed cl check <crate>
Run its suite and trials cl test <crate>, or cl test <crate> -- <filter>
One component's stories as PNG files cl render <crate> <Component> (ui for the library's own components)
The gallery cl build gallery (debug), or cargo run --profile gallery -p craft-ui-gallery

Writing a component, its stories and its trials: authoring.md. Moving an app's UI onto the framework: porting.md.

3. Architecture

3.1 Crate tiers

Tiers describe dependency direction. A crate depends only on lower tiers. They are separate from the design-system layers in 4.1.

Tier 3  craft              facade: re-exports and forwards features
          |
Tier 2  families           craft-color, craft-draw, craft-layers, ...
          |
Tier 1  UI library         craft-ui-contract, -widgets, -panels, -canvas, -patterns, -shell; the craft-ui facade
          |
Tier 0  engines, services  craft-behavior, craft-theme, craft-i18n, craft-settings, craft-cms, craft-host, ...

Rules:

  • Tier 0 needs no egui. A tier-0 crate that converts to egui types does so behind a feature: craft-theme's ecolor, craft-host's ui, craft-keymap's egui.
  • The UI library names no document concept and never depends on a family.
  • A family keeps core types at the crate root and egui UI in ui behind the ui feature, and may be UI-only.
  • No family's ui depends on another family's ui, except on craft-color, the base family any family may use (crates/craft/tests/families.rs checks it). A widget two other families share moves down to the UI library.

3.2 The UI library crates

The UI library is six crates along the design-system layers (4.1), plus the craft-ui facade. An arrow points from a crate to a crate it depends on.

graph TD
    ui["craft-ui (facade)"] --> shell & patterns & canvas
    shell["craft-ui-shell<br/>app shell, title bar, eframe entry"] --> panels
    patterns["craft-ui-patterns<br/>ready-made dialogs, presets, preferences, dock areas"] --> panels
    canvas["craft-ui-canvas<br/>canvas, tools, canvas controls, full-window dialogs"] --> panels
    panels["craft-ui-panels<br/>sections, dialogs, docking, rails"] --> widgets
    widgets["craft-ui-widgets<br/>components: buttons to tables"] --> contract
    contract["craft-ui-contract<br/>runtime, style, fonts, primitives, contract, layout, test kit"] --> behavior & theme
    behavior["craft-behavior<br/>behaviour cores, no egui"] --> theme["craft-theme<br/>tokens and themes, no egui"]
Crate Layer Holds Also depends on
craft-ui-contract 2 to 4 The runtime (per-pass services and the one egui adapter), style, fonts, primitives, the component contract and its pipeline, layout services, and the test kit (testing) craft-host, craft-keymap, craft-window, craft-quit, craft-i18n, craft-font-catalog, craft-fonts-build, craft-ui-macros
craft-ui-widgets 5 Components: buttons, choices, display, forms, lists, menus, notices, text fields, value drags, pickers, tabs, tables, graphs, bars, and the layout components Stack, Row, Grid
craft-ui-panels 5 Sections, dialogs and the dialog host, docking, rails, and the canvas data patterns read without the canvas craft-quit
craft-ui-canvas 5 and 6 Canvas with its tool host, tools, rulers and navigator; the canvas controls; the full-window dialogs that show a canvas
craft-ui-patterns 6 Ready-made dialogs (form dialogs, PDF export), presets, preferences, dock areas and panels craft-pdf (the PDF export dialog)
craft-ui-shell 7 AppShell, the title bar, and with app the eframe entry point craft-window
craft-ui The facade: re-exports the six crates under one root, so craft_ui::buttons is craft_ui_widgets::buttons. With testing, craft_ui::testing gathers every crate's test helpers the six crates
  • Each crate above the contract re-exports the modules of the crates below it at its root, so code inside the library writes crate::contract::… in any crate.
  • Every crate outside the library that uses it (the families, the services with a ui feature, the gallery, the story renderer and the craft facade) depends on the facade craft-ui. Apps do too, through craft::ui.
  • Each crate has its own testing feature and its own integration binary (tests/it), which runs the shared suite over the types that crate registers. The facade's it binary holds the checks that need every crate linked: the components index and the API map.
  • craft-ui-macros holds the derives every crate uses; craft-ui-test-kit holds test kits the crates' integration binaries share.

3.3 The craft facade

  • Every public UI type is re-exported at <crate>::ui; every core type at the crate root: craft::color::ui::ColorPicker, craft::color::Palette.
  • craft::prelude holds AppInfo, Host, Section, Tokens, DialogStack and Outcome. There are no other preludes.
  • A feature can move between crates as long as craft::<family> stays.

Feature names: ui is the only UI feature name in every crate, and screen-testing adds stories and snapshot tests. The full table is in Appendix B.

Native-only modules use #[cfg(not(target_arch = "wasm32"))]. A crate that cannot build for wasm says so in its first doc line, and the facade gates it.

3.4 Crate taxonomy

Kind Role Crates
Facade One dependency for apps craft
UI library Shared UI infrastructure (3.2) craft-ui (facade), craft-ui-contract, craft-ui-widgets, craft-ui-panels, craft-ui-canvas, craft-ui-patterns, craft-ui-shell, craft-ui-macros, craft-behavior
Domain families Features with core logic and egui UI craft-color, craft-draw, craft-imaging, craft-layers, craft-browse, craft-text, craft-font-manager, craft-pages, craft-review, craft-table, craft-timeline; planned: craft-code
Infrastructure services Egui-free logic that families and apps share craft-theme, craft-theme-store, craft-host, craft-i18n, craft-settings, craft-keymap, craft-menu, craft-automation, craft-update, craft-cms, craft-ai-core, craft-atomic, craft-docpath, craft-font-catalog, craft-font-store, craft-font-subset, craft-pdf, craft-prepress, craft-proof
Formats and codecs Clean-room readers and writers craft-audio, craft-crw, craft-jpeg, craft-media, craft-doc, craft-ecproj-format, craft-pcraft-format, craft-vectorcraft-format
Platform adapters One operating-system, window-system or browser service each craft-platform, craft-dialogs, craft-window, craft-win32, craft-quit, craft-print, craft-web-api, craft-web-host; next: craft-gpu
Tooling Not shipped in apps craft-ui-gallery, story-render, feature-root, craft-ui-bench, craft-ui-test-kit, craft-design-lint, craft-plate-test, craft-fonts-build, craft-media-testkit

One crate allows unsafe code, wrapping foreign calls behind a safe API so no other crate needs unsafe: craft-win32 (the Win32 window-procedure subclassing and window-handle calls). The workspace lint table sets unsafe_code = "forbid"; craft-win32 sets it to deny and allows it in lib.rs, and the design-lint rule contract/unsafe-allow names it. The benchmark's counting allocator (craft-ui-bench, src/alloc.rs) is the other allowed site. The HarfBuzz FFI behind craft-font-subset is outside the workspace (craft-font-subset).

Services and adapters may carry a ui feature (craft-keymap, craft-update, craft-dialogs) but name no document concept. Module tables: Appendix B.

3.5 The host convention: services in, edits out

craft-host is a small egui-free crate. The app builds a Host once and installs it on the egui context. Every feature reads it with Host::of(ui). No feature takes an i18n or settings parameter.

fn setup(ctx: &egui::Context, app: &App) {
    Host::builder(app.info())
        .i18n(app.i18n.clone())
        .settings(app.settings.clone())
        .commands(app.keymap.clone())
        .files(app.files.clone())
        .jobs(Arc::new(craft::host::ThreadJobs))
        .install(ctx);
}
Rule Detail
Services in Identity, language, settings sections, commands, files and jobs. Each is a trait the app or a library crate implements.
Document data in Each feature defines one small trait (TimelineModel, LayerTree) that the app implements on its document view. Features own no document state
Edits out Features return edit events (Begin, Update, Commit, Cancel, Set). The app applies them to its own undo stack
Dialogs A feature dialog is a value the app opens on the library's DialogHost. Its result is a DialogResult<T> (Ok(T) or Cancel) the app takes on a later pass. No feature opens its own window

The remaining service rules (settings keys, words, commands, files) are in Appendix B. The examples show the shape, not settled APIs.

Cancel and Escape. Esc during a gesture ends it with Cancel { reason: Escape }. The app restores the value it held at Begin and makes no undo step.

match event {
    EditEvent::Begin { id, .. } => self.mark = Some(doc.undo_mark(id)),
    EditEvent::Update { value, .. } => doc.preview(FILL, value),
    EditEvent::Commit { after, .. } => doc.apply(Edit::set(FILL, after)),
    EditEvent::Cancel { reason, .. } => match self.mark.take() {
        Some(m) if !reason.document_moved() => doc.restore(m),
        _ => {}
    },
    EditEvent::Set { after, .. } => doc.apply(Edit::set(FILL, after)),
    _ => {}
}

Interrupted gesture. Besides Esc, other events end a gesture with Cancel; the CancelReason says which: Refused, Dismissed, Escape, Blur, Removed, HostChanged, UndoDuringGesture. For HostChanged and UndoDuringGesture, reason.document_moved() is true: the document changed under the gesture, so the app keeps it as it is, because a restore would also take back that change. The handler above covers all of them.

Error. A failing service call returns a typed error, and the feature shows it in its own UI without an edit. File calls return Result<_, FileError>. A dismissed picker answers Picked::Cancelled, not an error; a picker that cannot open answers Picked::Unavailable(cause).

Async job. Work runs on the host's Jobs, never on a thread a feature starts. JobQueue adds priorities, one job per key, replacement and cancellation. Dropping a key sets the job's cancel flag, and a cancelled job's result is never delivered.

queue.submit(photo_id, Priority::VISIBLE, move |cancel| decode(&path, cancel));
while let Some(Finished { key, result }) = queue.try_recv() { show(key, result) } // on a later pass

3.6 Runs and passes

A pass shows the whole UI once. egui may repeat a pass within a frame (a discard pass); only the frame's last pass is painted. Within a pass, a container's contents run twice: a measuring run, then the real run. Both runs of a pass give the same result.

Content runs in every pass, and its sizes come from this pass. Layouts also read some state earlier passes left, for example a scroll area's offset and its last view and extent (step 4 and the scroll bars read them) and the sizes layout memory keeps (runtime::layout_memory; a changed size asks for a discard pass). The one exception to running in every pass is out-of-view content.

Layout memory. A record of layout memory holds a measure or a text. A body whose inputs did not change takes its kept measurement instead of running a measuring run. A text that a measuring run found for content outside the body (a value readout beside a story, for example) is kept with the measurement: layout_memory::emit_text hands it forward, layout_memory::text reads it, and a body that takes its kept measurement gives the text its measuring run found. A real run that finds another text marks the kept transcript as changed.

Out-of-view content. Content inside a scroll area that is out of view this pass does not run. It keeps what it last showed: the extent it had in the last pass that showed it, which changes only in a pass that shows the content, and the stops it registered there. One mechanism (runtime::lazy, one store) serves every use:

  • Only content that meets the view runs. A Lazy child out of view registers the focus records of its last real run again in its place (its stops, the scopes it pushed and the roving groups of its stops; focus::Transcript), so Tab and F6 reach its stops; Tab onto one runs the child and the reveal scrolls it in.
  • Lazy::new(key, estimate).show(ui, |ui| ..) wraps a large child of a scroll body (a card, a section of an app panel). Out of view it takes its remembered extent, also after the scroll area's room changed, and its closure does not run. It is a child in flow: in a Grid or spread Row body it holds one cell, its content is the one child that takes the cell, and out of view it takes the cell at its remembered extent. A card keyed by itself, not by its row, keeps its extent when a change of the column count regroups the rows. A child no pass showed yet takes its estimate (that long along the axes the area scrolls, nothing across them), so a first show runs only the children in view. It runs when its extent meets the view, and while a stop from its last run holds keyboard focus or is the target of a focus request. .reveal(true) in a pass asks its scroll body to glide until the child starts at the view's start, whether it ran yet or not: the offset follows the child's place on the motion service's follow curve (a Travel motion, so reduced motion jumps), while estimates before it resolve; a wheel, drag or other move of the body ends the glide. The key names the child among every Lazy of its scroll area. Outside a scroll area a Lazy always runs.
  • The first run of a pass decides which children run, so the measuring run and the real run lay out the same children.
  • Every scroll input moves the offset at step 4, before the content runs, so the decision sees the offset the pass paints. Wheel, page keys and reveals arrive there directly. A thumb drag, a track press or an AccessKit scroll action is sensed after the content ran: the pass queues it for step 4 and asks for a discard pass, so the move shows in the same frame.
  • A scroll position the framework holds is also named by content: the first child at or after the view's start and its place in the view (lazy::Anchor, kept with the offset). When extents before that child change (estimates replaced by real extents, rows regrouped), the offset follows the child and the pass runs again, so the content in view does not move. An offset bound to the app (Component::scroll) is the app's plain offset, and a region that follows its end follows the end.
  • A scroll area that does not run (a tab switched away) keeps its children's entries, and its content extent lives beside its offset (ScrollState) with the same lifetime, so it shows again at the same offset after any length of hide; one that runs drops the entries of the children it did not reach.
  • A collection builds the rows in view, plus its lead, anchor, renaming and grabbed rows. Its rows are no Tab entries (Tab moves past the collection, arrows move its lead), so a row out of view has no stops to keep. It places the rows it does not build by the extents they had when last built, from the same store, and its output lists the rows in view and the kept rows. Rows it never built take its item layout's estimate, as a Lazy takes its own, so a long list is never built whole. A reveal (a requested one, a key move, type-ahead, a rename) places the row by measured heights: before the rows are built, the collection builds and measures the rows that will share the view with the revealed row, up to it, that no pass built yet, and the build takes those measures, so the row shows wholly in the pass that reveals it.
  • Each built row is a run of the collection's item component, or, for a collection that sets Collection::MEMBERS (a tab strip's tabs, a colour table's cells), a member of the collection's own run: sensed with its parts in its arena, updated, painted and finished at its row, and reported as an access sub-node of the collection with its parts' nodes under it, with no run of its own. Its output gives the item event, as a run's does. Selection, activation, drags and AccessKit requests on the row are the collection's either way.
  • The access tree covers the view, by the same rule: content that runs reports its access nodes (a collection's built rows and their section headings included). A component that lays out section rows as its own parts (TileGrid's group headings and tail rows) reports the nodes of those in view. Content out of view (Lazy children and collection rows) is absent from the access tree until it scrolls in. AccessKit scroll actions still reach it, because they move the offset.
  • Content that was never shown has only its estimate and no stops: Tab reaches it once it was shown. An app brings it into view with .reveal(true).

3.7 One egui revision

craft-libs pins one revision of an egui fork for every egui crate ([patch.crates-io] in the root Cargo.toml). Two revisions in one build would give two incompatible Tokens and Ui types. craft::egui_fork::{GIT, REV} name the fork and revision, and craft::egui_fork::check_lockfile checks that an app's Cargo.lock takes every egui package from them; an app's xtask calls it. An app must also patch egui to the same fork, because [patch] applies only at the workspace root.

The fork. This branch pins github.com/aiongg/egui at 5493e3aa. That revision is the storytold egui fork's pinned revision (6d518fc7, the pin on storytold craft-libs main) plus 22 commits the framework needs:

  • TextEditState::preedit, and a new IME context ends the old composition
  • InteractOptions::enabled (disable one widget of an enabled Ui) and InteractOptions::activate_on_space
  • Memory::request_focus_with_filter
  • Response::describe_for_accessibility public, accessible names for ScrollArea scroll bars, Context::set_accesskit_focus, Context::register_accesskit_parent public
  • a pointer press goes to the widget under the press position
  • DragAndDrop::aborted_by_escape
  • Popup swallows the press outside it that closes it
  • Context::set_layer_order
  • OpenType features per text section (epaint)
  • IdTypeMap::insert_temp_boxed keeps the allocation of a value taken out, and Context::ptr_eq
  • Context::pass_mark, pass_records_since and replay_pass_records: a settled region replays its last pass's records
  • egui_kittest's eframe harness runs App::raw_input_hook before each pass, as eframe does, so an app's embed::before_input runs in its tests

The fork's PATCHES.md describes each patch and whether it is proposed upstream.

What it means for landing. Before craft-libs main can take the framework, these commits must be on the storytold egui fork and craft-libs must pin that revision; until then a build of this branch fetches egui from github.com/aiongg/egui. The storytold fork's main has commits the pin lacks, so the commits move onto whichever storytold revision the team picks, and craft::egui_fork::GIT changes with the pin (9.7).

4. Design system

The design system decides how apps look and how components compose. Its readers build components, themes and app looks.

4.1 Component layers

Each layer reads only the layer below it. The right column names the crate that holds the layer (3.2); the crate docs number the layers from the bottom, with tokens and behaviour as layers 0 and 1 and the app as layer 8.

Shells       title bar, rails, body and bars as slots; presets per kind of app          craft-ui-shell
  ^
Patterns     panel, dialog, inspector, dock area, options bar, status bar, title bar    craft-ui-patterns, craft-ui-canvas
  ^
Composites   field rows, property rows, headers, lists, tabs, toasts, menus             craft-ui-widgets, craft-ui-panels
  ^
Controls     buttons, fields, sliders, checkboxes, selects, swatches, tooltips          craft-ui-widgets
  ^
Primitives   surface, state layer, focus ring, divider, stack, interactive area, text, icon, handle
             (with the runtime, style and contract under them)                          craft-ui-contract
  ^
Tokens       scales, ramps, seeds, contrast, size presets, themes                       craft-theme, no egui

4.2 Ownership

Concern Owner Responsibility
Token model, themes, resolution, validation craft-theme The design language as data, with no egui
Theme files, machine-local library, suite selection craft-theme-store selection.json, lock and revision protocol, watcher, client
Tokens to egui styles craft_ui::style (craft-ui-contract) The one place data becomes egui styling, stock widgets included
Behaviour craft-behavior, craft_ui::runtime::{focus, keys} (craft-ui-contract), craft_ui::edit (craft-ui-widgets) Press, drag, navigation and edit events with no egui; focus and keys per pass; undo adapters
Generic components and shells The UI library crates Reusable UI
Domain components Family crates Feature UI on the UI library
Gallery, story renderer, lint craft-ui-gallery, story-render, craft-design-lint Inspect and enforce the system (8)

4.3 Generic or family component

A component goes in the UI library when both hold:

  1. Its inputs are general data: values, ranges, points, text, a list of rows, or a small trait.
  2. It names no document concept: layer, colour model, gradient, path, clip, page.

Otherwise it goes in the family crate that owns the concept. A component that two families need moves down to the UI library once its inputs are general.

Inside the library, a component goes in the lowest crate whose layer it belongs to: a control or composite in craft-ui-widgets; a section, dialog, dock part or rail in craft-ui-panels; anything that needs Canvas in craft-ui-canvas; an assembly of other components (a pattern) in craft-ui-patterns.

Borderline cases (curve editor, histogram, preset browser, menus, canvas overlays) and where the code places them are in Appendix A.

4.4 Patterns and shells

A pattern is a reusable region of a window. It works in any shell and decides nothing about the rest of the window: panel, dialog, inspector, dock area, options bar, status bar, title bar, rails.

A shell composes a whole window. It orders slots (title bar, top bars, rails, body, bottom bars), decides which show, scopes ids and state per window, and draws no bar or panel itself. Slots take patterns.

Shell State
Canvas: fixed document canvas, document tabs, tool rail, panel dock. Photo, vector, design, figure, PDF and CAD apps Built
Workspace: equal panels in named workspaces. Film, effects and sound apps Planned
Office-style: ribbon in the top slot, backstage view, task panes Planned

Docking details are in Appendix A.

4.5 Per-app look and feel

An app has one layout in every theme and size. A theme never changes the layout. Different arrangements are workspaces, which are separate from themes. Studio, for example, is Pro's layout with Studio colours and the Comfortable size.

The app decides The framework shares
Layout and placement, following its industry original Components and their behaviour
Conventions: menus, shortcuts, tool behaviour Family patterns: dock and tool rail, ribbon
Default density: Compact or Comfortable Focus and Tab order, Esc cancels, one undo step per drag
Default theme and mode: dark for creative apps, light for office-style apps Themes, high contrast, translation, screen-reader support
Colour overrides for its own look The token model that carries them

4.6 Customization ladder

Use the first step that works.

  1. Density. Compact or Comfortable.
  2. Size overrides. The app ships a sizes.json that overrides base sizes (for example size.control.md). A base override carries to every size derived from it. To change one component, pin that component's token. Overrides stay within the validator's limits.
  3. Component tokens. One named value changes a component app-wide.
  4. Builder options. Options cover structural differences. A new need gets a new option, not a new component.
  5. Per-app colour overrides. A theme file can carry a section per app. Values are theme roles or literal colours, so themes, dark mode and high contrast keep working.
  6. One-off app components. A last resort, built from shared pieces. Allowed and not policed.

4.7 Themes

Ten built-in themes with 17 mode variants; the suite default is ArtCraft. A two-mode theme is one theme with a variant per mode, and a mode can carry a partial seeds override so each mode derives its own colours. Picking a two-variant theme sets both modes. A theme can name an icon pack that replaces the base icons it covers. The gallery is also the base of a theme editor. The themes are listed in Appendix A.

5. Foundations

Foundations are the values every component reads. This section holds concepts only. Which component uses which token is in Appendix A.

5.1 Colour

seeds -> ramps -> semantic tokens -> pins -> contrast pass -> resolved Tokens -> theme bridge
  • Seeds. Neutral, accent and four status hues (good, warn, bad, info).
  • Ramps. 12 steps per seed per mode, in OKLCH, on a fixed lightness curve.
  • Semantic tokens. Mapped to ramp steps by meaning (groups below).
  • Pins. Any token can be set by hand.
  • Anchoring. Unpinned background greys keep their distance from the theme's panel colour, so they follow a pinned panel. Text greys stay on the curve.
  • Contrast pass. Derived colours move to the minimums in 5.7.

Semantic tokens fall in eight groups: surface, text, line, accent, status, state, canvas overlay and data. The tokens of each group are in Appendix A.

Accent fills that carry text use the strong pair: the accent moved in lightness only as far as white text needs.

A disabled component looks one of two ways (Component::DISABLED). A control whose look is chrome (a button, a field, a slider) takes its style's Disabled state: text.disabled ink and the disabled fills, and the data colours it shows (a tone dot on a picker, a swatch icon, a gradient ramp) paint at Opacity::DISABLED, so they dim and keep their hues: its Draw paints them so, and so do a content painter's data paths (ContentPainterCx::data_shapes, picture, checker, ramp). A component that shows data (a picture, a colour, a plot, a tile), or paints data with a content painter's bare painter, declares DisabledLook::Faded: step 13 paints its enabled look, faces included, at Opacity::DISABLED, so its data dims with the rest. The children it shows stay outside its fade and show their own disabled look.

5.2 Typography

App text maps to the nearest named role. A real new need gets a new role. No role serves a single use.

Role Use Compact (size / line, pt) Comfortable
Caption Small print 10.5 / 14 11.5 / 16
Label Control labels 11.5 / 16 12.5 / 18
Body Body text 12 / 16 13 / 18
Body strong Emphasised body text (semibold) 12 / 16 13 / 18
Title Panel and dialog titles (semibold) 13 / 18 14 / 20
Heading Section headings (semibold) 15 / 20 17 / 24
Body large Large regular text, such as a prominent field 15 / 20 16 / 22
Mono Code and numbers: number fields, timecodes, tables 11.5 / 16 12.5 / 18

The Text size setting scales the roles only (0.83x, 1x, 1.17x, 1.33x), rounded to 0.5 pt. Control heights, icons and faces do not scale. The interface font setting can use the OS UI face; mono stays the suite's.

5.3 Iconography

  • Sets. Phosphor is the base set. The gallery's active set defaults to Lucide. A theme may supply an icon pack that replaces the base icons it covers; missing icons fall back to the base set.
  • Strokes. 1.25 pt at the small size, 1.5 pt at medium and large.

5.4 Dimensions

Sizes are runtime tokens. The rule runs from the general to the specific:

  1. A scale holds the allowed values: spacing 0, 2, 4, 6, 8, 12, 16, 20, 24, 32; radius 0, 2, 3, 4, 6, 8, 12 and full; strokes hairline, 1, 1.5, 2, 3.
  2. Semantic role tokens pick from the scale by meaning: control height, icon size, gap, padding, radius, bar height.
  3. Components derive their own dimensions from the role tokens in their style: a role, or a role times a ratio named in the component's style with the rule it comes from. There are no component-specific theme values.

Components name semantic tokens and never a pixel value or shape of their own. Appendix A says which component takes which role. Only drawing details (stroke widths, chevron geometry, dash lengths) stay constants.

Semantic role tokens (pt).

Role Compact Comfortable
Control height sm / md 20 / 24 24 / 30
Icon sm / md / lg 12 / 16 / 20 14 / 18 / 22
Gap inline / row / stack / section 4 / 4 / 6 / 12 6 / 6 / 8 / 16
Padding control / panel / dialog 6 / 8 / 16 8 / 12 / 20
Radius control / surface / window / panel 3 / 4 / 6 / 0 6 / 8 / 12 / 0
Stroke thin / medium / thick / heavy 1 / 1.5 / 2 / 3 1 / 1.5 / 2 / 3
Radius button / pill full / full full / full
Bar title / tab / status / options 32 / 26 / 24 / 36 38 / 30 / 30 / 42
Panel header 28 34
Rail width / button 40 / 30 50 / 36

Push buttons take the button radius and the pill-shaped parts take the pill radius. Both are fully rounded by default and square in Classic, and each clamps to half the part's height.

Themes never set sizes. The Size preset sets them, and apps may override them within validator limits. Adwaita, Breeze, Soft and Classic define their own corner radii and edge style (flat or bevel; only the Surface primitive reads the edge). These change how a component is drawn, not its geometry, placement or the workspace structure.

5.5 Elevation

Shadow levels exist for popups, dialogs, floating panels and knobs. A bevel edge has none.

5.6 Motion

Durations are Fast (80 ms, hover and press feedback), Normal (150 ms, most state changes) and Slow (250 ms, large surfaces opening or moving). Easings are Standard, Enter and Exit. Reduced motion sets every duration to zero.

5.7 Appearance and contrast

5.7.1 Settings

Nine settings: theme (per mode), mode, contrast, size, text size and reduced motion are suite settings; interface font, direction and UI scaling are app settings. Options, effects and storage are in Appendix A.

5.7.2 Precedence

Each field resolves on its own, in this order:

app override  ->  suite choice (selection.json)  ->  app default
 (preferences)      (set once any app picks it)     (shipped by the app)
  • Theme, mode, size. An override replaces one field, not a whole profile: an app can override only its size and still follow the suite's theme and mode. An override of the theme replaces both slots of the theme pair; a slot may name the app default.
  • Contrast, reduced motion, text size. Suite choice only, then the built-in default (system, system, 1x). The app has neither default nor override.
  • Interface font, direction, UI scaling. App settings only.
  • System values. system resolves against what the OS reports. Mode falls back to the app's fallback mode, contrast to standard and motion to full.
  • Unknown theme. An unknown theme id falls back to the app default's slot, then to ArtCraft.

5.7.3 Contrast

Standard contrast follows each theme's design. Derived colours reach the minimums. Pinned colours that fall short are kept and reported (craft-theme check, the gallery token browser, a "Low contrast" label in the theme picker), never rewritten. High contrast fixes every failing pair in the table, pinned or not.

Class Pairs Standard High
Text Text normal, muted, faint on surfaces and state fills; text on selected fills; accent text; status foregrounds; text on accent, strong accent and status solids 4.5:1 7:1
Non-text cue Focus line; accent solid, check and radio marks on control surfaces; overlay stroke on its halo; marquee on its dash 3:1 4.5:1
State cue Accent border of selected controls; selected anchor outline on its fill; curve and channel colours on their plot none 4.5:1
Control edge Field and button borders, slider tracks none 3:1
Active popup row The active row of a menu or list popup 1.12:1 3:1
No rule Dividers, hover and pressed fills, disabled text and fills none none
Exempt Guides, smart guides, path outlines and box lines: bare lines in a colour the user chooses none none

6. Components

This section points to the component index. Examples and every state of each component are in the gallery (2.1). Which tokens a component reads is in Appendix A.

6.1 What every component provides

  • A builder API with semantic props only: no colour, pixel size or corner shape of its own. The idiom is Type::new(required).option(..).show(ui). Panels take &mut Model in new. A dialog's per-pass answer is an Outcome; on the host it returns a DialogResult<T>.
  • Gallery stories for every state.
  • Everything in the checklist in 7.1.

Fill and content sizing

Fill propagates down a column whose width is given: a content-sized container (a Stack::new()) shown in a Stack given its width passes that width on, so a child that fills takes it, and the container with it. Where the width comes from content (a menu, popover or dialog body, a Row, a Grid, a fill container held in such a column) the column is a content column: it holds the children that fill, they never set its width, and they are shown across the width it settles on. A leaf declares that it fills with fills(); a container declares it with Sizing. A content-sized container may name a least width (ContainerProps::least_width) and a wrap width (ContainerProps::wrap_width) from size roles: its content is at least the one, and a wrapping text inside breaks its lines at the other where its room is wider, so a dialog opens at one width and only content that cannot wrap widens it. A host that shows arbitrary components (the gallery, a dialog body) offers them fill width with fill_width(), and a story that fills both axes takes its room from testing::stage, and a canvas story as tall as its content (a text being edited) from testing::stage_fitting.

Along a height its parent sizes from its content, a container that fills takes its content height, at most the room it is offered. Content taller than that room takes the room, and the children that fill share it, so a list scrolls above the bar under it. Inside a scrolling body the room is unbounded; a host offers a finite one with room_height (a gallery card offers the view's height).

6.2 Index

components-index.md lists every registered component and pattern of the UI library crates with its shape, module and purpose. It is generated from the component registry (cl cargo run -p craft-ui-gallery --bin components-index), and the facade's components_index trial fails when the file is out of date. contract-api.md lists the public items of the shared modules (contract, runtime, style, primitives, layout, layout_components, testing) and of craft-behavior.

6.3 Family components

Crate Components
craft-color ColorPicker, ColorArea, ColorWheel, ColorDisc, ColorRamp, ColorPopover, SwatchPair, SwatchPalette
craft-draw GradientSwatch, GradientEditor, GradientPalette, gradient line, TransformFields, transform box, bezier paths, crop frame, perspective crop quad, pen draft
craft-imaging LevelsEditor, CurveEditor, Histogram, warp grid
craft-layers Layers panel, rows, filter bar, thumbnails
craft-browse Tile grid, media bin, places, thumbnails, relink

Other families (3.4) add theirs as they land.

7. Accessibility and translation

7.1 Required for every component

A component is not complete until each item has a story or test.

  • Keyboard. Every control works from the keyboard. Behaviour follows the suite's own apps first, WAI-ARIA authoring patterns where no app has a convention.
  • Visible focus. A keyboard-only focus ring, always visible.
  • AccessKit. Roles, names and values on every widget (button, spin button, slider, text input, combo box, list option, radio, dialog, menu item, tab, tree item).
  • RTL. Chrome mirrors. Sliders, number fields and key chords never mirror.
  • Reduced motion. Animations resolve to zero.
  • Translation. Words come from the catalog (7.2).
  • Edit lifecycle. Value controls report begin, update, commit, cancel and set. Esc restores the value held before the gesture. A drag or typing run is one undo step.

Keyboard conventions:

  • Tab visits fields only in dialogs and every control elsewhere.
  • A swatch palette and a guide set are one Tab stop with arrow keys inside. A tab strip is one Tab stop.
  • Ctrl+Tab focuses a dialog's title row.
  • Cmd or Ctrl+] and [ move the focused row in every reorderable list. F2 renames. Enter runs the row's default action.
  • A step over a closed list control (an arrow, Home, End, the wheel, an AccessKit increment or decrement on Select or ComboBox) stops on the enabled entries marked as stepped (Entry::stepped, on by default) and skips the rest, such as a "Load…" command row. A value on none of those entries (mixed, or an entry only the open list offers) offers both steps: forward lands on the first stop, back on the last. contract::step_stops and contract::step_stop are the one rule every list control uses.

7.2 Translation rules

  • Library words (button labels, dialog text, error text) are rows in the shared craft-i18n catalog (common.tsv). App labels win. Apps do not translate library words themselves.
  • The app installs its translator through the host once per language change.
  • Lookup order: the language's row, the English row, the built-in English.
  • A translation with a missing placeholder is ignored.
  • No test requires a translation to exist.

7.3 Goals beyond the required list

These guide design where no rule exists. They are not acceptance criteria.

  • Size and Text size let users enlarge the interface without changing layout.

8. Tests and gates

8.1 What gets a test

Every test names the regression it guards against: a plausible change to the code that would break something without anyone noticing. If no such change comes to mind, there is no test.

Test:

  • Shared mechanisms that many components rely on: the contract pipeline, measuring, focus and key routing, undo grouping, the suite's own checks. Test each once, at the mechanism.
  • Logic with real room for mistakes: layout and room sharing, state machines, gesture sequences, geometry, parsing and saving our own file formats.
  • A bug that was hard to find, where the fix isn't obvious from the code.

Don't test:

  • Code you can verify by reading it: a few lines, a single branch, a swap, a clamp, a short loop with no state.
  • Wiring: a button runs its command, a key calls a model function, a modifier picks copy instead of move.
  • Defaults, getters and mappings.
  • What the type system already guarantees.
  • Library behaviour: egui, std, serde or any other dependency.
  • Exact strings, values or sizes.
  • One test per combination of cases.
  • Per-component repeats of what the shared suite already checks on that type. The suite runs its shared cases on every type registered as a component; a pattern gets only the pattern trial.

Where a test goes:

  • A component gets its own trial only for behaviour that is unique to it and not trivial.
  • Check behaviour at the level the user meets it, through the component, not in the helpers it calls. When a user-level test already goes through a helper's code path, the helper has no test of its own.

New code follows the same rule. A new feature adds tests only for logic with real room for mistakes. A bug fix adds a test only when the bug was hard to find. A review finding needs no test case of its own.

8.2 Gates

Gate What it holds Where
Shared suite The shared cases (required states, shows, access, Tab, values, mixed, activation, text size, motion, language, text input, container and collection cases) on every type registered as a component; the pattern trial on every pattern Each library and family crate's tests/it binary (authoring.md)
Trials Behaviour unique to a component or mechanism (8.1) The same binaries
Gallery Stories for every state of every component of every crate with a ui feature. Keep it in step with the features each app enables craft-ui-gallery; its own trials cover the viewer's saved layouts and the Overview's cards
Components index docs/components-index.md matches the registrations The facade's components_index trial
API map migration/api-map/*.toml have the shape the migration tools read (9.8) The facade's api_map trial
Token dumps Text files of resolved tokens per theme-mode variant, contrast (standard, high) and size (Compact, Comfortable). Rewrite with UPDATE_DUMPS=1; the dumps of the workspace stay under a line budget crates/theme/tests/dumps
Facade checks The craft features table matches the member crates; no family's ui depends on another family's ui; the egui fork check crates/craft/tests
Theme check craft-theme check <file>: contrast report, adjustments, invalid fields The craft-theme binary
Design lint craft-design-lint check (syn), check-clippy and structure (layer map, imports, exceptions, clones) 8.3

Text dumps of every token are the regression gate for the theme. The story renderer (cl render) writes a component's stories to PNG files for a before-and-after look; no test compares pictures.

How to run each locally, and which of them CI runs, is in development.md.

8.3 Design lint

  • Rules: literal-size/*, raw-colour/const, style-mutation, tooltip/stock, clippy/inner-allow.
  • Exemption marker: // design: allow(reason). Empty, invalid and unused markers are findings.
  • Baselines and --deny-unused are supported.
  • Exit 0 clean, 1 findings, 2 error.

9. Migration and landing

How apps move onto the Craft framework, and how the work lands in craft-libs. This is a procedure document. The design is in 1 to 8.

9.1 Migration strategy

Everything is built in craft-libs first: build each feature once, in one place, and use it one way. A feature one app has today is built in the library even when no second app needs it yet. Work goes step by step, so each step ends in a library the apps can use. It does not go family by family.

  • PhotoCraft migrates first. It has the most UI and features. Its port branch runs on the library while the library grows.
  • VectorCraft migrates second. It shares the Canvas shell and most of PhotoCraft's skeleton. If the two ports look alike, the library is general enough.
  • Other apps follow, each adopting the steps it needs.
  • One branch per port. The port adopts each step as it lands and deletes the code the step replaces. The app's main branch switches once, when the port merges.
  • A gap is library work. A gap an app finds is fixed in the library first. The port then deletes its own code. No app workaround.
  • Review in small PRs. Keep hand-written architecture changes in small, independently buildable PRs. Treat generated dumps and icon assets as reviewable data.

9.2 Acceptance checklist

Every app-port step passes all of these before it counts as done:

  • Tests are green.
  • Every story of the step's components is complete (7.1).
  • Screenshot comparison of the app's upstream build against the port covers each screen, and every difference a user would notice has a recorded decision. Users see no significant difference, or slightly more polish.
  • Design lint is clean.
  • The conformance test is clean.
  • The app's duplicate implementation is removed. Where the app drew one kind of component several ways, the port uses one.

9.3 Steps

Step Delivers Depends on Status
0 PhotoCraft adopts the types the library already has; gaps become library work none done
1 Foundations: ui feature names, craft-host, module moves into family crates, the craft facade, gallery and word registry over every crate, one egui revision 0 done
2 Dialog framework: typed results, parameter and command dialogs, size dialogs, prompts, unsaved guard, startup modal queue; text and number control gaps 1 done
3 Shell (dock, panel menus, floating frames, workspaces, start screen, focus regions), keymap completion, canvas core, options bar cells, testing tools 2 done
4 Files, preferences, text and fonts, colour, previews and jobs 2, 3 done
5 Common controls, system services, value formatting, guides and About, align bars 2 done
6 6a: layers, presets, history, navigator, browsing. 6b: pages, timeline, review, tables 2, 3, 4 (6a); 2, 3, 5 (6b) 6a done; 6b built, fix pass pending
7 Canvas tools and the image-editing workspaces 3, 4, 6a built
GPU craft-gpu: GPU device, diagnostics, memory budget and the GPU canvas surface; PhotoCraft moves its GPU display onto it 2, 3 next
8 Office-style shell, audio, code editor and console, slideshow 2, 3; 6b timeline for audio planned

Size: about 185 library tasks, plus about 28 PhotoCraft tasks and about 20 VectorCraft tasks. Step 3 is about 30 library tasks, step 4 about 35, step 6 about 44.

9.4 Critical path

2 --> 3 --> 4 --> 6a --> 7 --> PhotoCraft full port --> VectorCraft full port
       |     |
       |     +--> 5 (off the path: PhotoCraft needs only guides and About)
       +--> 6b, 8 (off the path for PhotoCraft)
  • Step 2 gates every feature that opens a dialog.
  • Step 3 gates the canvas tools (7), the colour droppers and text editor (4), and every panel (6) through the dock's panel-menu host.
  • Step 4's colour and font pickers gate the stroke, shape and text work in 7.
  • Step 6a gates PhotoCraft's panels and the brush presets in 7.
  • Steps 5, 6b and 8 run beside the path when capacity is free. Their inputs are other apps' code.

9.5 What each step delivers

Step 0: adopt existing types. PhotoCraft swaps widgets it shares in kind with the library for the library's. Each difference becomes a gap row. The port has recorded 108 gap rows. At least 26 are closed with a merged library change and 34 are scheduled in a later step. They range from a missing option on a slider row to a floating frame with no title-bar move, which is why the shell and common controls come before the tools.

Step 1: foundations. No pixel changes.

  • The UI feature is ui in every crate, plus screen-testing.
  • craft-host carries the services every feature reads.
  • Domain code moves out of the UI library into craft-draw, craft-imaging, craft-color and craft-print.
  • The craft facade gives one dependency and one pin.
  • The gallery and word registry cover every ui crate.
  • Each app's xtask checks the egui revision.

Step 2: dialog framework. A feature dialog is one value an app pushes and one result it reads.

  • Delivers: DialogHost with typed DialogResult, ParamDialog, command forms, image and canvas size dialogs, confirmation prompts, UnsavedChangesDialog, properties and report dialogs, PointPicker, Remembered<T>, craft-update's dialogs on the stack.
  • PhotoCraft adopts: the stack for every dialog, parameter dialogs for filters, size dialogs, prompts, the unsaved guard, remembered options.
  • PhotoCraft deletes: its dialog host and routing, parameter-dialog builder, field map, size-dialog code and prompt helpers.

Step 3: shell, testing tools, canvas core, options bar.

  • Delivers: dock host and commands, panel menus, floating frames, Window menu and Arrange, named workspaces, start screen, region focus, shortcuts dialog, the keymap catalog as source of truth, zoom and navigation, cursors, snapping, raster display, the on-canvas tool host, options bar cells with scrubbing, craft-automation, the render harness.
  • PhotoCraft adopts: the library dock, workspaces, ScreenMode, the shortcut catalog and dialog, canvas navigation, the tool host, options bar cells, automation.
  • PhotoCraft deletes: its dock, panel-menu popups, floating card frames, shortcuts table, zoom ladder, cursor host, momentary-key and snapping code, options bar cell code, screenshot queue and control channel.
  • VectorCraft maps to library components during this step. Its gaps feed the specs of steps 4 to 7.

Step 4: files, preferences, text and fonts, colour, previews.

  • Delivers: the file service, New Document, export dialogs, print, file intake; preferences over a settings document with AppearancePage and recovery; font picker, canvas text editor, style panels; colour picker dialog, droppers, samplers, screen picker, swatch panel, palettes, CMS additions; preview panes and job progress.
  • PhotoCraft deletes: its file dialogs, most preferences code, recovery and path code, family picker, colour panel and picker bodies, job UI.
  • VectorCraft adopts steps 1 to 4 on its port branch in one pass.

Step 5: common controls, system services, value formatting, guides, About. A small step for PhotoCraft.

  • Delivers: sortable tables, chips, date and tree pickers, linked fields, mixed values, split button, breadcrumb, rating; clipboard, file watcher, default-app registration, temp files, Save flow; dates, byte sizes and elision; New Guide and Guide Layout dialogs, About, align bars.
  • PhotoCraft adopts guides, About, align bars, linked size fields, clipboard and the Save flow.

Step 6: layers, presets, history, browsing (6a); pages, timeline, review, tables (6b). 6a is on PhotoCraft's path. 6b serves other apps.

  • 6a delivers: LayersPanel over a LayerTree trait, channels, the preset model and menus, a history panel with one-edit steps and snapshots, navigator, scopes, actions, thumbnails, browsing. PhotoCraft's panels then all run in the library dock; it deletes its layer, history, navigator and histogram panels and its preset model.
  • 6b delivers: paged documents, timeline, comments and versions, spreadsheet tables. VectorCraft adopts layers and presets after 6a, and artboard lists after 6b.

Step 7: canvas tools and image-editing workspaces. PhotoCraft's last large deletion.

  • Delivers: transform, warp, selection and mask tools, vector and shape tools, crop, measure, brush, and the full-window editors (select and mask, liquify, filter gallery, fill from surroundings, perspective plane, wide-angle correction, layer style, adjustments).
  • PhotoCraft adopts every tool through the library tool host. Its port then runs the lint clean and passes conformance and the render matrix.
  • VectorCraft adopts the draw family and finishes its port.

GPU canvas. craft-gpu delivers the GPU device, diagnostics, memory budget and the GPU canvas surface. PhotoCraft's only task is to move its GPU display onto it. Nothing visible changes.

Step 8: office-style shell, audio, code editor, slideshow. Mostly other apps' code.

  • Delivers: ribbon, backstage view, keytips and the office-style preset; audio engine and mixer UI; code editor and console; slideshow presenter.

9.6 Documentation for each step

Each step also adds its families to the library docs: a page per family with the out-of-the-box recipe (the Host, the trait the app implements, the builder call, the Outcome) and a migration table from old path to new path.

9.7 Landing strategy

The size of the series, measured on 11 November 2026 as the difference between this branch (with the branches due to land on it) and its merge base with storytold craft-libs main (a8b996d2):

Measure Value
Files changed 4,371
Lines added about 508,000
Lines removed about 128,000, of which about 42,000 in the old crates/ui (moved into the library crates)
UI library, craft-behavior and craft-theme: lines added about 228,000
Generated token dumps (crates/theme/tests/dumps) about 17,000 lines
Docs and migration maps (docs/, migration/) about 38,000 lines
Icon set files about 700 (four sets: Phosphor, Lucide, Tabler, Carbon)
New crates 28

The numbers change once the branch moves onto current main. A review reads dumps, icons and the migration maps as data.

It lands as a series of upstream pull requests, one at a time, bottom-up. Each PR builds and passes CI alone. Apps pin craft-libs by commit, so a merged PR changes nothing in an app until the app moves its pin.

Order PR Contents
1 egui patches The fork's commits go to the storytold egui fork; craft-libs main moves its egui pin (3.7). Everything else depends on this
2 Icon sets Data only
3 Token model and themes craft-theme, craft-theme-store, craft-color. New crates; nothing depends on them yet
4 Library core craft-behavior, craft-ui-macros, craft-ui-contract (runtime, style, primitives, contract, test kit), craft-ui-widgets
5 Panels, canvas, patterns, shell craft-ui-panels, craft-ui-canvas, craft-ui-patterns, craft-ui-shell, the craft-ui facade, with craft-draw and craft-imaging
6 Host, facade and changes to existing crates craft-host, craft, and changes in craft-menu, craft-keymap, craft-window and craft-platform
7 Tooling The gallery, the story renderer, craft-design-lint

PR 5 replaces upstream's craft-ui crate (egui controls and icon catalogs) with the facade; 9.8 covers what that breaks.

Timing. A layer lands once PhotoCraft's port has used it in earnest. Bottom layers land first. Landing early stops drift from upstream. A landed layer's API is shared, and changes to it need the same care as any breaking change.

9.8 Breaking changes

The library replaces upstream's craft-ui crate, and changes public items in craft-menu, craft-keymap, craft-window and craft-platform. What exists for apps that move their pin:

  • The facade. crates/ui is the craft-ui package, a re-export facade over the six library crates, so an app keeps one dependency and craft_ui::… paths. Upstream craft-ui's modules capture, combo, direction, icons, ime, localized, panes, printing and theme are gone; buttons, docking, fonts, layout, tabs, testing and text keep their names and hold the library's types.
  • The API map. migration/api-map/*.toml, one file per family, lists each public type and function an app calls today: its old path, its new path, setter renames, and a status (same, moved, replaced with a note, removed, or pending). About 2,900 entries; 19 are still pending. The facade's api_map trial checks the files' shape. migration/check-crates.txt lists the domain crates and features a compile check builds.
  • No deprecated aliases. No old path is kept as a #[deprecated] alias or shim: an app's pin bump past PR 5 needs the app's code moved to the new paths in the same change. Whether the PRs should add aliases is a question for the team (9.9).

9.9 Status and open questions

What exists

Area State
Token model, ten built-in themes, store, bridge built
Primitives, controls, composites, patterns built
Canvas shell, docking with iconic column and flyouts, title bar built
Dialog frame, prompts, full-window dialogs, preferences window, typed dialog stack built
craft-color, craft-draw, craft-imaging, craft-layers, craft-browse, craft-automation, craft-pages, craft-review, craft-table, craft-timeline built
craft-host, the craft facade, one egui revision check built
UI library as six crates and the craft-ui facade, the API map built
Gallery with Components and Theme workspaces, Variants, app preview; the story renderer built
cl build loop with one feature set, dev and gallery profiles (development.md) built
Design lint, craft-theme check built
PhotoCraft Builds against the library through step 6a and is moving its dialogs onto it. Most panels, dialogs, canvas overlays and adjustment editors are still its own code, restyled by the theme
macOS The port builds on macOS; window, title bar and menu bar checks pass
Comparison Screenshots of 59 screens, current PhotoCraft beside the port, refreshed after each port batch

What is next

  1. The GPU canvas (craft-gpu).
  2. PhotoCraft's dialogs on the library, completing its port.
  3. VectorCraft's port, then the other apps.
  4. The upstream PR series, starting with the egui commits.

Questions for the team

Topic Question
Landing order Is the bottom-up order right, or should the token model and the library core land together? Should the apps' PRs follow each layer, or wait for the whole series?
Deprecated aliases No old path has a deprecated alias today; apps move with the API map in the pin bump that takes the library. Should the landing PRs add #[deprecated] aliases for the paths apps use (the icon-button and combo-box modules, the old rail and number-field types), and for how long: until every app has moved past them, or a fixed number of releases?
egui fork The library builds against github.com/aiongg/egui (19 commits over the storytold fork's pin, 3.7). Which of them go to upstream egui, which stay in the storytold fork, and onto which storytold revision do they move?
Facade name craft is the facade's name. If it clashes with an app crate, the alternative is craft-kit
Crate granularity The layout adds 28 crates to upstream's 42, seven of them the UI library and its facade. Is there a family that should merge, or a crate that should split?
Review load Is a series of about 508,000 added lines, much of it moved, generated or data, reviewable as laid out, or should it split further?

Appendix A. Component tokens

Maintainer reference. The rule is in 5.4 Dimensions: components name semantic tokens, and semantic tokens pick from the scale. This page lists which role each component takes.

Semantic colour tokens

Group Tokens
Surface background, canvas, canvas pattern, chrome, panel, raised, sunken, knob, scrim, shadow
Text normal, muted, faint, disabled, on accent, on strong, on selected, on status
Line divider, border, control edge, knob edge, mark, focus
Accent solid, hover, pressed, strong (+ hover, pressed), soft, text
Status good, warn, bad, info, each with fg, bg, border, solid
State hover, pressed, selected, selected hover, disabled fill, stripe
Canvas overlay stroke, halo, handle, marquee, guide, grid
Data 8 series; histogram R, G, B, luma

The strong accent pair fills the menu highlight, primary buttons and solid accent badges.

Appearance settings

Setting Options Changes Stored
Theme 10 built-ins or a JSON file, per mode (theme_light, theme_dark) Colours; shape for four themes Suite
Mode light, dark, system Palette Suite
Contrast standard, high, system (default) Contrast minimums Suite
Size Compact, Comfortable Heights, padding, gaps, type, corners Suite
Text size 0.83x, 1x, 1.17x, 1.33x Type only Suite
Reduced motion full, reduced, system (default) Animations to zero Suite
Interface font Suite face, System UI face App
Direction Language (default), LTR, RTL Mirroring; sliders, number fields and key chords never mirror App
UI scaling Auto, or 75 to 300 % (steps of 5 from 75 to 125, then 150, 175, 200, 250, 300) Whole-interface zoom App

UI scaling omits sizes that would shrink the window below the app's minimum on the current screen; the size in use stays listed. Every app has a "Reset UI Scaling" command. Pointers an app draws grow with the scale.

Built-in themes

Ten themes, 17 mode variants. The suite default is ArtCraft.

Theme Modes Look
ArtCraft light, dark Mid-grey panels; suite default
Pro light, dark Neutral greys
Pro Light Gray light Light grey panels
Graphite light, dark Near-black fields in dark
Studio light, dark PhotoCraft Studio colours
Solarized Dark dark Muted teal-tinted dark
Adwaita light, dark Rounded, light grey; radii 6 / 9 / 12
Breeze light, dark Flat; 5 px corners
Soft light, dark Low contrast (declared); corners rounder by +1 / +2 / +2
Classic light Square, bevelled; 1 pt bevel, all radii 0

Generic or family placement

Component Placed in Reason
Button, Slider, List, Tab strip craft-ui-widgets General inputs
Menu craft-ui-widgets (menu) Takes rows and shortcuts; the app supplies the commands
Preset browser craft-ui-patterns (patterns::presets) Works on a generic preset library model
Canvas overlays: grid, guides, smart guides, marquee, rulers craft-ui-canvas (canvas, canvas_controls) Draw over any canvas; no document type
Crop frame, gradient overlay, transform box, bezier paths craft-draw Need shape and gradient types
Colour picker, wheel, swatch palette craft-color Need colour models
Levels editor, curve editor, histogram, warp grid craft-imaging Need image-adjustment types
Layers panel craft-layers Needs the LayerTree trait

Docking details

  • Panels live as tabs in an expanded dock column or as icons in a collapsed (iconic) column, never both.
  • A click on an icon opens its group in a flyout beside the column.
  • Dialogs move by their title only.
  • A floating panel group has square corners and the floating shadow.

Radius roles

Role Components
radius.control Fields, small controls, buttons that are not pills
radius.surface Popups, menus, dialogs
radius.window Windows, dialogs
radius.panel Docked panels and side columns; themes round them or keep them square
radius.button Push buttons. full in the built-in size sets; Classic sets it to 0
radius.pill Switch and slider tracks and knobs, progress bars, badges. Clamps to half the part's height; Classic sets it to 0

A theme with its own shape replaces the radii or adds an offset to control, surface and window. Panel, button and pill are not offset.

shape.knob is the shape of a value track's thumb (Slider, RangeSlider): round, the control's glyph across, or tab, an upright tab the control's icon side tall. Classic sets tab.

shape.wells is the shape of a colour well that stands on its own (SwatchPair's foreground and background): square, with the small radius, or round, a circle. Adwaita, Breeze and Soft set round.

Size roles

Role Components
size.control.sm, size.control.md Controls, fields, buttons
size.icon.sm, size.icon.md, size.icon.lg Icons; md is the glyph of a tool strip and of a panel footer's actions (GlyphRole::Tool), lg of a tool rail (GlyphRole::ToolRail). A stroke-set icon draws its line stroke.icon of its side
size.icon.glyph_sm, size.icon.glyph_md The glyph in an icon-only button (GlyphRole::Control, the default; a container sets another with ContainerProps::child_glyphs)
size.bar.title, size.bar.tab, size.bar.status, size.bar.options, size.bar.options_narrow Title bar, document tab bar, status bar, options bar
size.panel_header Panel headers
size.popup_min Least width of a popup surface (menus only; popup lists such as Select and ComboBox take their anchor's width)
size.scroll_fade Length of the fade at an edge of a scroll region past which its content continues
size.groove Groove of a value track
size.ramp.bar Colour band: a gradient ramp drawn as a bar of its own or as the face of a value track
size.ramp.groove Thin band along a ramp: the span between two thumbs of a gradient's thumb row
size.rail.width, size.rail.button Tool rail and panel rail
size.length.field.sm, size.length.field.md Text or value field, one width per control size: a field in a small options bar is narrower than one in a dialog
size.length.number.sm, size.length.number.md Number field and the number cell over a slider, one width per control size
size.length.track, size.length.short Value track, short field
size.row.text A row that shows text only: one body line and space.gap.tight; read-only display tables take it, lists the user picks from keep control-high rows
size.notice.width Width of a toast card where the room allows
size.dialog.least, size.dialog.wrap A dialog's content: the least width it opens at, and the line length its paragraphs wrap at (LeastWidth::Dialog, WrapWidth::Dialog); content that cannot wrap widens it past that
size.dialog.button, size.dialog.side_button Least width of a dialog's footer button and of a button in its column beside the body
size.story.height, size.story.width_min, size.story.width_max The stage a story of a canvas control draws its canvas on: its height and the range of its width; width_min is also the least width of a column of a story grid
size.hit.edge The band inside the edge of a canvas's view in which a tool that autoscrolls on hover scrolls the view (a Polygonal Lasso's rubber band), at most a quarter of the view's shorter side
size.thumb.card The picture side of a tile card at zoom 1 (tile grids, preset browsers, the start screen)
size.thumb.sample.sm, size.thumb.sample.md, size.thumb.sample.lg The sample beside each thumbnail size choice in a panel's options dialog (Layers, Channels, Paths): larger than the panel's thumbnails, so the choices read apart (PictureSize::Sample)
space.gap.*, space.pad.* Gaps between and padding inside components

Both size sets (crates/theme/sizes/compact.json and comfortable.json) hold every role above. A field holds a number of characters, so size.length.field, size.length.number and size.length.short grow with the text size by the same factor as the type; size.length.track holds no text and keeps its length. NumberField is at least size.length.number at its control size wide; apps set other widths per field.

Appendix B. Crate and module layout

Maintainer reference. The concepts are in 3. Architecture. Crates are alphabetical, and modules are alphabetical inside each crate. The State column says whether a module exists in the repository, is planned, or is next, and in which migration step (see Migration and landing). Crates without an entry (the file-format envelopes, craft-doc, craft-proof, craft-web-api, craft-web-host, craft-media-testkit) are described in their README.

Conventions:

  • Crates are craft-<family>, one word where possible. No -ui or -core suffix on a family. The UI library's crates are craft-ui-<layer>.
  • Modules are nouns, one level below the crate root. ui is the only module that nests a second level (craft_pages::ui::table).
  • Types carry their full name (LayersPanel, not layers::Panel), so they read the same wherever they are imported.
  • In a family crate, a module ui::x is the egui side and a bare x is core.

29 crates are new relative to storytold main: craft, craft-automation, craft-behavior, craft-browse, craft-color, craft-design-lint, craft-draw, craft-font-subset, craft-host, craft-imaging, craft-layers, craft-pages, craft-review, craft-table, craft-theme, craft-theme-store, craft-timeline, craft-ui-bench, craft-ui-canvas, craft-ui-contract, craft-ui-gallery, craft-ui-macros, craft-ui-panels, craft-ui-patterns, craft-ui-shell, craft-ui-test-kit, craft-ui-widgets, craft-win32 and story-render. craft-ui keeps upstream's package name as the library's facade. craft-gpu is the next step, and craft-code is planned.

Facade features

Feature Meaning
ui The family's egui side, on craft-ui. The only UI feature name in every crate. The facade's ui turns on ?/ui for every enabled family
screen-testing Stories and snapshot tests; implies ui
egui Converts a crate's types to egui's without craft-ui, where that is the whole feature (the model is craft-theme's ecolor)
serde, collab, per-service features Keep their names. craft-platform has one feature per service (job, clipboard, ...)

Host service rules

Rule Detail
Settings keys Each feature exports a serde struct with a const KEY, which the app embeds in its settings file through craft-settings
Words Library words are rows in the shared craft-i18n catalog, looked up through the host
Commands A feature exports its command catalog. The app registers it with craft-keymap
Files Features ask the host to pick, read and write. Native apps implement the service natively; web apps implement it over the browser

Where each concept lives

Concept Crate Module (facade path) More
Tokens, themes, contrast craft-theme craft_theme suite-themes.md
Tokens to egui styling craft-ui-contract craft_ui::style 4.2
Component contract, pipeline, Lazy, list entries craft-ui-contract craft_ui::contract authoring.md, contract-api.md
Passes, focus, keys, layout memory, out-of-view content craft-ui-contract craft_ui::runtime 3.6
Behaviour cores, edit events, dock model craft-behavior craft_behavior ui-docking.md
Services an app installs craft-host craft_host (craft::host) 3.5
Components craft-ui-widgets craft_ui::{buttons, pickers, list, …} components-index.md
Dialogs and the dialog stack craft-ui-panels, craft-ui-canvas (full-window) craft_ui::dialog ui-dialogs.md
Docking parts; dock areas and task panes craft-ui-panels; craft-ui-patterns craft_ui::docking; craft_ui::patterns::dock ui-docking.md
Canvas, tools, canvas controls craft-ui-canvas craft_ui::{canvas, canvas_controls}
Ready-made dialogs, presets, preferences craft-ui-patterns craft_ui::patterns
App shell, title bar, eframe entry craft-ui-shell craft_ui::shell 4.4
Test kit: fixture, suite, stories, snapshots craft-ui-contract (and each crate's helpers) craft_ui::testing authoring.md, 8
Story viewer; story renderer craft-ui-gallery; story-render development.md
Lint rules craft-design-lint 8.3
egui fork check craft craft::egui_fork 3.7

craft

The facade. New on the branch (step 1).

Module Holds State
egui_fork Lockfile check: the egui revision matches the library's exists
prelude AppInfo, Host, Section, Tokens, DialogStack, Outcome exists
crate re-exports One module per crate, features forwarded exists

craft-ai-core

Shared data model for AI connections, roles, requests and jobs. No egui.

Module Holds State
capability Modalities and what can be done to data exists
catalog, model, picks Models, what each can do, which to suggest for a job exists
connection, consent, endpoint, secret Where work is sent, what leaves the machine and whether the user agreed, secrets that cannot print exists
conformance, mock Checks every provider must pass; a scripted provider for tests exists
draft, store The "add a connection" form model; the shared versioned store exists
error, ids, job, history Error type, validated ids, job progress, request history exists
models Downloadable model manager planned, step 4
payload, provider, request, role, spec The provider trait, requests and payloads, roles, declarative routes exists
ui::models, ui::settings Model download UI; AI settings page planned, step 4

craft-atomic

Crash-safe atomic file writing. One module at the root; exists.

craft-audio

Audio file I/O and codecs (WAV and AIFF read and write, FLAC encoding) and waveform peaks, from upstream (README). Step 8 adds the audio device, meter ballistics and the mixer UI.

Module Holds State
buffer, layout, pcm, read, track, wav, write Sample buffers, channel layouts, file reading and writing exists
peaks Waveform peaks exists
db dB value text planned, step 8
meter Meter ballistics planned, step 8
output Output stream and device setup planned, step 8
ui::controls Fader and pan knob planned, step 8
ui::meter Level meter planned, step 8
ui::mixer Channel strip mixer planned, step 8
ui::panner Surround panner planned, step 8
ui::piano_roll Piano-roll note editor planned, step 8
ui::response Frequency response plot and editor planned, step 8
ui::waveform Waveform view planned, step 8

craft-automation

Control channel, screenshot queue, profiler and recorded actions for tests and scripting. Native only. New on the branch.

Module Holds State
actions, ui::actions Recorded actions and the actions list exists
control Automation control channel exists
args Command-line values and environment fallbacks of the control channel exists
protocol JSON-lines wire format and parameter validators exists
security Tokens, the auth handshake and transport limits exists
server Loopback JSON-lines TCP transport (native) exists
client JSON-lines client for tests and command-line tools (native) exists
synthetic Synthetic pointer and keyboard input: ui.click, ui.move, ui.key, ui.type exists
dialogs ui.dialog.set, ui.dialog.confirm and ui.dialog.cancel over a DialogHost exists
profiler Frame profiler exists
screenshot Screenshot request queue exists
trace Frame timing trace exists

craft-behavior

The behaviour cores of the UI library (layer 1), with no egui and no Context: press lifecycle, ValueDrag, navigation, item layouts, edit events, overlay placement, fitting and the dock model (ui-docking.md). Public modules, with the main types at the crate root: anchor, arrangement, canvas, codec, columns, command, cursor, divider, doc_key, dock, edit_history, editor, eviction, fit, flow, focus, geometry, grid, hit, input, intent, item_layout, item_marquee, item_source, keys, label_column, layout_memory, monitor, motion, nav, one_press, overlay, part, pixel_size, placement, press, quantity, role_rule, scroll, selection, sense, sizing, typing, value, value_drag, wheel. Every public item is listed in contract-api.md.

craft-browse

Thumbnails, media bin, tile grid, places and in-app file browsing. New on the branch.

Module Holds State
browser, ui::browser In-app file browser planned, step 4
places, ui::places Folder places tree exists
thumbs Thumbnail loader and cache exists
ui::bin Media bin browser exists
ui::compare Image compare tile exists
ui::grid Thumbnail tile grid exists
ui::relink Linked files and relink dialog exists

craft-cms

Colour management: ICC v2 and v4 profiles, transforms, rendering intents. No egui.

Module Holds State
builtin, synth Built-in and synthetic CMYK profiles exists
clut, curve, lut3d, lutfile Lookup tables, tone curves, display LUTs, creative LUT files exists
convert CMYK models and gamut conversions the colour dialogs need exists
gamut Gamut checks against a proof profile exists
math Matrices, XYZ and Lab, chromatic adaptation exists
pipeline, transform Evaluation pipelines; transforms with intents and black point compensation exists
profile, write ICC profile model and reader; v4.3 writer exists

craft-code

Code editor field and console. UI-only family. New crate.

Module Holds State
ui::console Script console panel planned, step 8
ui::editor Syntax-coloured code field (syntax colours as a data.code.* token family) planned, step 8

craft-color

Colour for apps: picker, wells, swatch tables, ramps, hex field. New on the branch.

Module Holds State
display Display transform on craft-cms exists
gray Grey level of a colour exists
harmony Colour harmony and saved themes exists
hex Hex text for colours exists
mode What a colour area and its strip show exists
palette Palette data exists
ui::area, ui::strip 2D colour area and its strip exists
ui::choice Colour choice: named colours plus Custom exists
ui::disc, ui::wheel, ui::ramp Colour disc, wheel and ramp exists
ui::droppers, ui::eyedropper, ui::samplers, ui::screen_picker Dialog droppers, eyedropper tool, sample points, screen picker exists
ui::harmony Harmony wheel exists
ui::hex, ui::readout Hex field and channel readout exists
ui::lut_picker LUT picker exists
ui::paint_chip Paint chip exists
ui::paints Paint list planned, step 4
ui::pair Foreground and background swatch pair exists
ui::palette Swatch palette exists
ui::panel Colour panel modes and menus exists
ui::picker, ui::popover The colour picker and its popover exists
ui::picker_dialog The complete colour picker dialog exists
ui::profile_prompts Profile mismatch prompts exists
ui::swatches Swatch panel exists
web Web-safe colours exists

craft-crw

Clean-room decoder for one camera raw format. tables holds frozen entropy-code data. Exists; no change.

craft-design-lint

Lint for app UI code: the clippy template that blocks stock egui widgets and raw colours, and the syn checker for literal sizes. New on the branch.

Module Holds State
baseline Baseline files for existing findings exists
clippy Check that an app's clippy.toml carries the template exists
config Lint configuration exists
markers // design: allow(reason) markers exists
report Findings output exists
rules Rule implementations exists

craft-dialogs

Native file and message dialogs that never block the event loop.

Module Holds State
filter File-type filters matching any letter case exists
macos macOS presentation exists
native Native dialogs on a worker thread exists
save Save and Save As flow with guards exists
service File dialog service behind the host's files exists
ui::file_list, ui::path_field File list picker; path field with Browse exists

craft-docpath

Decides whether a stored path or URL refers to a local file. Exists.

Module Holds State
links Linked files, for relink exists
names Safe file names exists

craft-draw

Vector and shape tools, pen, stroke, gradient, crop, measure, symmetry, brush presets and free transform. UI-only family. New on the branch (step 1).

Module Holds State
ui::add_beside, ui::artboard Add-beside buttons; artboard tool, bar and properties exists
ui::brush_presets, ui::brush_settings Brush preset picker, cards and chip; brush settings panel exists
ui::connector Connector tool, overlay and bar exists
ui::corner Corner radius widgets exists
ui::crop Crop frame and crop tool exists
ui::gradient Gradient swatch, editor, palette and on-canvas gradient line exists
ui::measure Ruler tool, bar and box distances exists
ui::pattern, ui::picture_fill Pattern fill picker; picture fill options exists
ui::pen Pen draft and bezier paths exists
ui::shape, ui::shape_drag Shape properties panel and options bar; shape drag tool and Create Shape dialog exists
ui::slice Slice tool, overlay, bar and dialogs exists
ui::stroke Stroke editor, button and preview exists
ui::symmetry Paint symmetry guides, menu and transform exists
ui::transform Free transform box and transform fields exists

craft-font-catalog

Installed fonts: discovery on every platform, family and style lookup, shared loading. Exists.

Module Holds State
catalog Every installed face, found by any of its names exists
env, fontconfig, registry Font folders, fontconfig folders, registry-listed faces exists
scan Face records from font files exists
suitcase Classic suitcase font files exists
system The platform's font service exists

craft-font-manager

Search and filters over font indexes, installed fonts by family, and the font manager panel.

Module Holds State
axes Variable font axes exists
filter Search by family, category, language, script exists
glyphs Glyphs panel exists
index The font indexes exists
installed Installed fonts grouped by family exists
missing Document fonts and missing-fonts dialog exists
panel, ui The egui FontsPanel and its story exists
picker Font picker: families, filters, previews, stars, recents, similar fonts (feature font-picker) exists
store What the panel needs from the font store exists

craft-font-store

The font store: indexes, exact lookup, verified installs into the suite's font folder. Exists.

Module Holds State
http The one HTTPS client exists
index, source, sources Font indexes, one source's file and URLs, built-in sources exists
pin The index commit and hash this build trusts exists
store Store folder, consent, installs, manifest, removal exists
verify Checks a file against its index entry exists

craft-font-subset

The one font subsetter, on HarfBuzz: glyph closure, CFF and CFF2, variable-font instancing, licence-aware renaming and WOFF2. Native only. New on the branch. The HarfBuzz calls go through harfbuzz-subset-sys, a Rust package on storytold's HarfBuzz fork (storytold/harfbuzz, branch rust-subset-15.0.0, rust/harfbuzz-subset-sys): it compiles the fork's own HarfBuzz 15.0.0 src/ and holds the raw declarations and their safe wrappers. The workspace pins it by commit.

Module Holds State
crate root subset (renamed WOFF2 for previews), subset_renamed, encode_woff2; cut_face (one face cut to a character set, every feature kept, for build-time interface faces); embed_permission (what the OS/2 fsType lets an exported document embed) exists
closure Characters a shaper may need beyond the text exists
codepoints The canonical codepoint list of on-demand preview URLs exists

craft-fonts-build

Build-script support that embeds optional faces from an app's build.rs. Exists.

Module Holds State
cmap, coverage Which characters a face maps exists
embed, manifest Face selection and the generated table; with subset, interface faces cut to the catalogs' characters by craft-font-subset exists
sha256 Hash for served file names exists

craft-gpu

GPU device, diagnostics and memory budget, plus the GPU canvas surface. New crate; native.

Module Holds State
budget Memory budget and probes next
canvas GPU canvas display surface next
device Device setup and diagnostics next
health Device loss, fallback and upload guard next
vector Vector canvas renderer next

craft-host

The Host bundle and service traits. Egui-free (egui only under ui, for install). New on the branch (step 1).

Module Holds State
root Host, HostBuilder, Host::of, install exists
services AppInfo, SectionStore, Section, Commands, Jobs, ThreadJobs, InlineJobs and defaults exists
files File service exists

craft-i18n

Translations: embedded catalogs, lookup with fallback, plurals, numbers for a region, language names, locale, search folding, collation. No egui.

Module Holds State
catalog Reading a catalog (the shared common.tsv holds library words) exists
collate Locale sorting for lists people see exists
fold Case- and accent-insensitive search matching exists
format Numbers, percentages and counts for a region exists
number Reading numbers people type exists
region, scripts Formatting region; scripts, direction and Han forms of a language exists
size Sizes and measures with a unit exists

craft-imaging

Raster image editing. New on the branch (step 1). Core at the root, widgets in ui.

Module Holds State
layer_style Layer style blending model exists
selection Selection model exists
trace Mask outline tracing exists
ui::adjust Levels editor and the colour adjustment editors exists
ui::live_preview Live preview of an adjustment: keys, lanes, proxy plan
ui::blend_keys Blend-mode key picker exists
ui::blur_pins Blur pins on the canvas exists
ui::channels Channels panel exists
ui::fill Fill-from-surroundings workspace exists
ui::filter_gallery Filter gallery workspace exists
ui::layer_style Layer style page and effect list exists
ui::liquify Push-and-warp (liquify) workspace exists
ui::mask_view Mask and selection overlay views exists
ui::scopes Scope panel: histogram, vectorscope, clipping exists
ui::select, ui::select_mask, ui::selection Outline selection tools; select-and-mask workspace; ants, matte and quick-mask overlay exists
ui::transform_preview Live transform preview exists
ui::vanishing_point, ui::wide_angle Perspective plane and wide-angle correction workspaces exists
ui::warp Warp grid; mesh, pin and perspective warp exists

craft-jpeg

Clean-room decoder for 12-bit and arithmetic-coded JPEG. Exists.

craft-keymap

Chords, keymaps, conflicts, overrides and shortcut-set import; the Keyboard Shortcuts dialog under ui.

Module Holds State
chord Keys, modifiers, chords and text forms exists
command, commands Commands with parameters; command words for the host exists
editor Shortcut editor model with undo, recorder, conflicts exists
egui Key conversion and dispatch exists
import Import of another application's shortcut set exists
keymap Catalog with defaults, overrides, dispatch exists
layout Chord meaning on the active keyboard layout exists
profiles Named override sets exists
reserved Chords the OS takes first exists
scope Where a binding works exists
ui Shortcuts dialog exists
ui::import_offer First-launch import offer exists
ui::router Focus gate and key owners exists

craft-layers

Layers panel and its parts. UI-only family. New on the branch.

Module Holds State
ui::filter Layer filter bar exists
ui::options Layers panel options dialog exists
ui::panel LayersPanel over a LayerTree trait exists
ui::rows Blend, opacity and lock rows exists
ui::thumbs Layer and mask thumbnails exists

craft-media

Bit-level I/O and clean-room MP4/MOV and Matroska/WebM demuxers and muxers. Exists.

Module Holds State
bitstream Bit reading and writing exists
isobmff MP4 and MOV (ISO base media) exists
matroska MKV and WebM exists

craft-menu

Menus for macOS, Windows, Linux and the web, with shortcuts from craft-keymap.

Module Holds State
bar The menu bar drawn with egui exists
context Panel and context menus from command entries exists
driver Events from the platform menu in, menu bars out exists
help, language Help menu kit; language menu exists
keymap Shortcuts and checked states from the keymap exists
keytips Alt keytips planned, step 8
layout Platform layouts of an app's menus exists
mac macOS menu bar exists
model Menu tree and flat rows exists
palette Menu commands as command-palette entries exists
recent Recent files, over the host's files planned, step 3
ribbon Ribbon with backstage, gallery, customize dialog and quick access toolbar planned, step 8

craft-pages

Page geometry, setup, ranges, numbering and paged-document UI. New crate.

Module Holds State
layout Paged layout: rectangles, columns, facing pages exists
numbering Page numbering styles exists
range Page range parsing exists
setup Page setup model exists
show Slideshow playback planned, step 8
ui::access Accessibility bridge for a canvas of pages exists
ui::column_bar Column width bar exists
ui::flatten_preview Transparency flattener options and preview planned, step 4
ui::grid Page grid overlay exists
ui::header_footer Header and footer zones exists
ui::list Page and artboard list exists
ui::margins Margin handles on rulers exists
ui::marks Text frame marks overlay exists
ui::preview Page preview overlay exists
ui::range Page range field exists
ui::reading Reading view exists
ui::setup Page setup dialog exists
ui::show Presenter window, transitions, timer, pen and laser planned, step 8
ui::sync_views Synchronised side-by-side views exists
ui::table Document tables: edges, properties, size picker, cell selection exists
ui::text_selection Text selection layer over rendered pages exists
ui::thumbnails Page thumbnail strip exists
ui::view Paged document view exists

craft-pdf

Shared PDF reading, rendering and optional writing. Exists.

Module Holds State
link Which link targets may become clickable links exists
raster Bounded RGBA8 raster output exists
read Bounded opening and interpreter guards exists
write PDF authoring exists

craft-plate-test

Print-colour test scenes and PDF structure checks. Exists (gs, judge, reference, report, scene, structure, tiff).

craft-platform

Small platform lifecycle services, one cargo feature per service. No craft-ui.

Module Holds State
appearance Desktop colour, contrast and motion preferences exists
autosave Autosave exists
clock Clock service exists
ui::recovery Crash recovery planned, step 4
browser Browser downloads exists
clipboard Clipboard with synthetic input and size limits exists
clock Injectable clock exists
default_app Default app registration exists
dialog_outcome, dialogs Dialog results with evidence; picker creation on the UI thread exists
job Background jobs and preview jobs planned, step 4
logs Crash and command logs exists
open OS open requests, drops, open and reveal exists
pacing Frame pacing and work budgeting exists
pen Pen input: pressure, tilt, eraser end planned, step 3
process Bounded output capture for one-shot programs exists
screen Screen colour sampling exists
session Reopen last session exists
temp Private temp files exists
usage Resource usage readout exists
watch File change watcher exists

craft-prepress

Ink model, plates from a PDF, coverage, ink limits, composite preview. Exists.

Module Holds State
cms, composite Process colour conversion; composite from plates exists
coverage, ink, plates Ink coverage, ink model, page separation exists
flatten Display list for the transparency flattener exists

craft-print

System PDF print spooler (Unix and Windows) and the print dialog.

Module Holds State
browser Browser print planned, step 4
progress, sheets, ticket, windows Worker events, sheets of a print-ready PDF, print ticket, Windows spooler exists
spool Spooler front end for the print dialog planned, step 4
ui Printer selection and job feedback exists
ui::layout Print layout sheet planned, step 4

craft-quit

Quits an app the platform's way.

Module Holds State
close Routes an egui window close through the platform quit exists
macos, menu terminate: on macOS; the app menu with a Quit that asks first exists

craft-review

Comments, annotations, signatures, versions and revisions; collaboration behind collab. New crate.

Module Holds State
annotate, ui::annotate Page annotation tool exists
collab (feature) Presence, voting, chat, join by code, with ui::chat, ui::presence, ui::vote exists
comments, ui::comments, ui::thread Comments panel and threads exists
revisions, ui::revisions Revision compare list exists
signature, ui::signature Signature pad exists
versions, ui::versions Version history panel exists

craft-settings

Shared settings storage: platform folders, config.toml, atomic saves, recovery, migration. No egui.

Module Holds State
document TOML documents, per-section parsing, comment-preserving merges exists
error Reports and errors exists
migrate Schema migrations and import of older files exists
paths Choosing the configuration folder exists
profiles Settings profiles exists
recovery Keeping damaged and previous files exists
remember Remembered<T>: last-used options for dialogs, panels and tools exists
store In-memory store exists

craft-table

Spreadsheet grid and related UI. UI-only family. New crate.

Module Holds State
ui::chart Chart painting exists
ui::conditions Condition builder exists
ui::error_tag Error-checking tag exists
ui::fields Field list pane exists
ui::filter Filter buttons exists
ui::grid Spreadsheet cell grid exists
ui::outline Row and column outline exists
ui::refpick Cell reference picking exists
ui::slicer Slicer filter chips exists
ui::stats Selection statistics exists

craft-text

Text processing below the composer, and text UI.

Module Holds State
bidi Bidirectional text (UAX #9) exists
find Find and replace exists
hyphen Hyphenation exists
linebreak Knuth-Plass line breaking exists
lists Bullet paragraph layout exists
quotes Smart quotes exists
segment Line-break opportunities exists
spell Spelling check exists
styles Named style list exists
ui::character, ui::style_panel Character format controls; text style panel exists
ui::columns, ui::hyperlink, ui::notes Columns dialog, hyperlink dialog, rich-text notes exists
ui::paragraph Paragraph format dialog planned, step 6
ui::editor Canvas text editor exists
ui::find Find bar exists
ui::styles Named styles panel planned, step 6
ui::ruler, ui::tabs_dialog Text ruler with tab stops; tab stops dialog exists
ui::spelling Spelling dialog exists

craft-theme

The theme model: colour, scale and token primitives, semantic tokens, contrast rules, the theme file format, built-in themes, and the craft-theme check command. No egui. New on the branch.

Module Holds State
app_sizes An app's size overrides (sizes.json) exists
builtins The ten built-in themes exists
color, color_model sRGB, OKLab and OKLCH with gamut mapping; colour models a picker edits in; hex helpers exists
components Component tokens, one struct per family exists
contrast WCAG contrast and repair exists
derive, ramp Seeds to ramps to tokens; 12-step ramps exists
dump, explain, report Token text dump, why each colour has its value, contrast sweep exists
format Theme file schema version 1: parse, validate, write exists
resolve Theme and appearance to concrete tokens exists
scale Space, radius, stroke, elevation, motion, opacity exists
selection The user's pick: theme per mode, mode, contrast, motion, size, text size exists
sizes Size sets exists
theme, tokens, values What a theme supplies; semantic tokens; tunable numbers exists

craft-theme-store

The suite's theme files, machine-local library and shared selection, with a lock and revision protocol for concurrent apps. New on the branch.

Module Holds State
backend, dir, disk Where the files live; atomic-rename disk store exists
client, watch App side of the selection protocol; folder watcher exists
copy Import as copy exists
selection, store selection.json and the lock and revision protocol; the theme library exists
testing Fixtures for adapter tests exists
ui::appearance AppearancePage: the whole appearance settings page planned, step 4

craft-timeline

Time, clips, keyframes, markers, frame cache, playback clock, and timeline UI. New crate.

Module Holds State
cache Frame cache with prefetch exists
clips Clip editing model exists
clock Playback clock and follow modes exists
frames Playback frame server exists
markers Markers exists
rates Media format presets exists
timecode Timecode and durations exists
ui::clips Clip editing UI exists
ui::graph Keyframe graph editor exists
ui::keyframes Keyframe lane exists
ui::markers Marker UI exists
ui::overview Overview strip exists
ui::panel Timeline panel with track headers exists
ui::preview Video frame painter and preview panel exists
ui::render_queue Render queue list exists
ui::ruler Time ruler exists
ui::timecode Timecode fields and readout exists
ui::transport Transport bar exists

craft-ui

The facade of the UI library (3.2). It re-exports the modules of the six library crates under one root: every craft_ui::<module> path below names the module of the crate listed. patterns::canvas adds NavigatorPanel from craft-ui-canvas. With testing, craft_ui::testing gathers the test helpers of every crate and library_registrations lists the registrations of the library's own crates; app turns on craft-ui-shell's app.

craft-ui-bench

Release-mode benchmark of the library's performance scenarios: the scenario list, the measurement and the report, with a counting allocator. Not published.

craft-ui-canvas

Module Holds State
canvas The Canvas container: tool host, tools, pasteboard, split views, rulers, navigator and NavigatorPanel, cursors, raster display, and its test helpers (ToolFixture, tool_story, canvas_story) exists
canvas_controls Leaves a Canvas body shows: brush cursor, grid, pixel grid, guides, smart guides, marquee, outline, line preview exists
dialog craft-ui-panels' dialog, plus FullWindowDialog and its parts exists

craft-ui-contract

The base of the library (layers 2 to 4). The testing feature adds testing, with the snapshot renderer.

Module Holds State
contract The component traits, context types, PaintUi, Looks, the pipeline and its steps, the mount and overlay hosts, Lazy, Entry and the list step rule exists
fonts Font definitions and the script coverage policy exists
layout Layout services: LabelColumn, ColumnGroup, the Grid cursor, arrange exists
primitives Painters, Draw, the sensing core, the text adapter, ImeSurface exists
runtime Per-pass and per-frame services (focus, keys, layout memory, lazy content, overlays, windows) and the one egui adapter exists
style The state set and its resolver, style parts, ComponentStyle, UiTokens, StyleCx, the style cache exists
testing The fixture, the suite runner, the story types, dumps and the snapshot renderer exists
words The words! macro, from craft-ui-macros exists

The story viewer (desktop and web) over the registered stories of every ui crate. Not published. One cargo feature per domain crate whose stories it links; apps, the default, links them all.

Module Holds State
chrome The options bar, the dock of panels and the window that holds them; the Overview (the cards of one level), a component's tab (one card per story group) and the Variants view; StoryBody, a story in its embedded shell exists
viewer The viewer's state and the data its chrome shows: the catalog of components by level, their story groups (a story's group = "..", shown under its title = ".."), the saved dock layouts exists
theme The theme workspace: panels that explain a theme and its appearance exists
mock The mock editor window: shell, title bar, rails, dock, document tabs, canvas and dialogs exists
bin/components-index, bin/contract-api Write components-index.md and contract-api.md exists
story-render (crate crates/story-render) Renders a component's stories to PNG files, offscreen, linking only the crates its features name exists

craft-ui-macros

The derives and macros of the UI library: Component, Props, ComponentStyle, Pattern, CommandSet, EnvValue, TokenGroup, words, stories and trials. Apps use them through craft-ui.

craft-ui-panels

Module Holds State
canvas_data The canvas data patterns read and write without the canvas: guides and the navigator's panel options exists
dialog Dialog, DialogFrame, BlockingOverlay, Prompt and its configurations, DialogStack, DialogHost (ui-dialogs.md) exists
docking SplitArea, Splitter, DockGroup, floating groups, the dock column, drop resolution and the dock commands (ui-docking.md) exists
rails PanelRail, ToolRail, FlyoutButton, ToolbarDrawer exists
sections TitleRow, FooterBar, Section, GroupBox, Panel exists

craft-ui-patterns

Module Holds State
patterns::dock DockArea, DockPanels, PaneArea, WorkspaceSwitcher exists
patterns::form_dialogs Form dialogs, among them PdfExportDialog over craft-pdf's settings exists
patterns::panels Inspector, CommandPalette, Tour exists
patterns::preferences PreferencesWindow and its pages exists
patterns::presets The preset browser over a generic preset library model exists

craft-ui-shell

Module Holds State
shell AppShell and its presets, TitleBar, captions, ScreenMode, ToastHost; with app, app::run exists; office-style preset planned, step 8

craft-ui-test-kit

Test kits the library crates' integration binaries share: components written with the derives, and a frame driver for child viewports. Its registrations are its own, so no library suite runs them. Not published.

craft-ui-widgets

Module Holds State
bars Bar and BarItems: the bar container and its strip of command items; AlignBar, BreadcrumbBar, ConstraintFields, the status readout exists
buttons Button, IconButton, ToggleButton, SplitButton, Link exists
choice Checkbox, Switch, RadioGroup, Segmented, Rating exists
controls Disclosure exists
display Badge, Kbd, Progress, Spinner, Text, Icon, Picture, Divider exists
edit Undo adapters over EditHistory, panel events and DialogValue exists
form Field, FieldGroup, SliderField exists
graph NodeGraph, Node, NodeKind exists
layout_components Stack, Row, Grid exists
list List and its rows: ListRow, FindingsList, EventList, UndoList exists
menu Menu presets with MenuItem rows, menu-bar keys and mnemonics exists
notices Notice, the settings notices and the notice center exists
pickers Select, ComboBox, TreePicker, Autocomplete, DatePicker, IconPicker exists
popover Popover, PopupList, Tooltip, DropVeil exists
story_kit Story helpers that show components (props, story_props) exists
table Table and MetadataTable exists
tabs TabStrip, Tab, DocumentTabs exists
text TextField<C> and NumberField on the text part exists
tile_grid Tile and ThumbnailSlider exists
value_drag Slider, RangeSlider, AngleDial, PointPicker, ThumbRow, on ValueDrag exists

craft-update

Release checking, downloading, installing and self-updating for the app suite and the launcher.

Module Holds State
app, suite, version, pins Apps, releases and versions exists
desktop_entry, detect, distro, folders, install, manifest, msi_*, packages, paths, platform, portable, process, queue, status Installing, detecting and removing apps exists
dialog Startup update prompt exists
http, proxy, release, source, time Network access and release lookup exists
protocol Vocabulary jobs and results report in exists
self_update, updater Launcher self-update; the update flow of an egui app exists

craft-win32

The Win32 window-procedure subclassing and window-handle calls that need unsafe, behind a safe API; empty on other platforms. It is the one crate that allows unsafe code (3.4).

craft-window

Decides who draws the window frame, makes an app-drawn strip act as the title bar, and keeps the window list, placement and restore.

Module Holds State
desktop Desktop and backend detection exists
layout Window button layout per desktop exists
list, menu Open windows; the Window menu exists
mac macOS traffic lights, measured exists
place Cascaded placement kept on screen exists
policy Frame policy exists
restore Window restore exists
title_bar An app strip as the title bar exists
viewports Immediate viewports per window exists