Files
craft-libs/docs/craft-framework.md
T
aiongg 64e3e6f4e5 A scroll body keeps its content extent with its offset
The extent that bounds a body's offset lived in shown memory (`BodyView`),
which is evicted soon after a body stops showing, while the offset and its
anchor live in session memory (`ScrollState`). A body shown again after a
longer hide clamped its kept offset against an extent of 0 and came back
at the top. The extent now lives in `ScrollState` beside the offset, with
the same lifetime; `BodyView` keeps the view rect.

The anchor rule runs only in the run that lays the content out for the
view: a measure run places no Lazy children, so it would clear the anchor.
2026-11-12 14:32:38 +00:00

91 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.

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
craft-ui The kernel crate: the design-system layers every family uses, with no document concept
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 holds every theme. Themes switch at run time. It needs Rust 1.95 or later.

git switch design-system
cargo run --release -p craft-ui-gallery
  • Update with git pull and rebuild.
  • Candidate fonts are optional: check out the craft-fonts repository at branch design-system-fonts and set CRAFT_FONTS_DIR=<absolute path> before cargo run.

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.2.

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  craft-ui           kernel: tokens bridge, components, shells, dialogs, docking
          |
Tier 0  engines, services  craft-theme, craft-i18n, craft-settings, craft-cms, craft-host, ...

Rules: tier 0 has no egui except ecolor. craft-ui 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 depends on another family's ui; a widget two families share moves to craft-ui.

3.2 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 reference/crate-layout.md.

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.3 Crate taxonomy

Kind Role Crates
Facade One dependency for apps craft
Kernel Shared UI infrastructure craft-ui, craft-ui-macros
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-audio, 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-pdf, craft-prepress
Formats and codecs Clean-room readers and writers craft-crw, craft-jpeg, craft-media, craft-ecproj-format, craft-vectorcraft-format
Platform adapters One operating-system or window-system service each craft-platform, craft-dialogs, craft-window, craft-quit, craft-print; next: craft-gpu
Tooling Not shipped in apps craft-ui-gallery, craft-design-lint, craft-plate-test, craft-fonts-build

Services and adapters may carry a ui feature (craft-keymap, craft-update, craft-dialogs) but name no document concept. Module tables: reference/crate-layout.md.

3.4 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 kernel'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 reference/crate-layout.md. 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.5 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.

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, while a stop from its last run holds keyboard focus or is the target of a focus request, and while .keep(true) asks for it. 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, as its offset is kept, so it shows again at the same offset; 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.
  • 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. Mark content with .keep(true) when the app focuses it or scrolls to it before it was ever in view.

3.6 One egui revision

craft-libs pins one revision of the egui fork. Each app's xtask checks that its lockfile uses the same revision and fails with a clear message otherwise. Two revisions in one build would give two incompatible Tokens and Ui types.

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.

Shells       title bar, rails, body and bars as slots; presets per kind of app
  ^
Patterns     panel, dialog, inspector, dock area, options bar, status bar, title bar
  ^
Composites   field rows, property rows, headers, lists, tabs, toasts, menus
  ^
Controls     buttons, fields, sliders, checkboxes, selects, swatches, tooltips
  ^
Primitives   surface, state layer, focus ring, divider, stack, interactive area, text, icon, handle
  ^
Tokens       scales, ramps, seeds, contrast, size presets, component tokens, 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 The one place data becomes egui styling, stock widgets included
Behaviour craft-behavior, craft_ui::runtime::{focus, keys}, craft_ui::edit Press, drag, navigation and edit events with no egui; focus and keys per pass; undo adapters
Generic components and shells craft-ui Reusable UI
Domain components Family crates Feature UI on the kernel
Gallery, lint, conformance craft-ui-gallery, craft-design-lint, craft-plate-test Inspect and enforce the system (8)

4.3 Generic or family component

A component goes in craft-ui 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 craft-ui once its inputs are general.

Borderline cases (curve editor, histogram, preset browser, menus, canvas overlays) and where the code places them are in reference/component-tokens.md.

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 reference/component-tokens.md.

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 reference/component-tokens.md.

5. Foundations

Foundations are the values every component reads. This section holds concepts only. Which component uses which token is in reference/component-tokens.md.

5.1 Colour

seeds -> ramps -> semantic tokens -> pins -> contrast pass -> component tokens -> 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.
  • Component tokens. Derived from semantic tokens and pinnable. About 1,100 resolved tokens per variant.

Semantic tokens fall in eight groups: surface, text, line, accent, status, state, canvas overlay and data. The tokens of each group are in reference/component-tokens.md.

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

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, numbers in 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. Component tokens name a semantic token.

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 reference/component-tokens.md.

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 reference/component-tokens.md.

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

A content-sized column (a Stack::new(), a menu or popover body) holds the children that fill: they never set the column's 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 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.

6.2 Index

components-index.md lists every registered component and pattern of craft-ui with its shape, module and purpose. It is generated from the component registry.

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.3) 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.

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
Gallery Stories and variants for every component. It covers every crate with a ui feature. Keep it in step with the features each app enables
Token dumps Text files of resolved tokens per theme-mode variant, contrast (standard, high) and size (Compact, Comfortable), plus app sizes. Rewrite with UPDATE_DUMPS=1
Style dumps One egui style file per theme-mode
Component dumps One file per component in craft-ui, craft-color, craft-draw and craft-imaging
Story registry Every kernel story and its default args
Title-bar dumps The title bar's rendering
Screenshots Visual regression, screens, docking workflows, interface scale, font rendering, web fonts.
Conformance An app's real appearance setup against the library's reference, across the case matrix. Fails on a wrong theme, size or text size, a changed Style, or an app's own zoom or font override. allow(field, reason) makes an exception
Theme check craft-theme check <file>: contrast report, adjustments, invalid fields
Design lint craft-design-lint check (syn) and check-clippy

Text dumps of every token and component style are the regression gate.

The gallery's own tests (crates/ui-gallery/tests/it) cover the viewer's saved layout, the component filter and the mock editor's keys and menus. Run them with:

cargo test -p craft-ui-gallery

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 kernel 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 series totals:

Measure Value
Commits 1,107
Files changed 1,547
Lines added about 332,000
Lines removed about 5,000
Generated test dumps among the added lines (*/tests/dumps/*) about 105,000
Icon set files 540 (four sets)

The work is mostly additive. A review reads dumps and icons 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 patches go to the storytold egui fork; craft-libs main moves its egui pin. 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 craft-ui core Theme bridge, primitives, controls, edit lifecycle, behaviour
5 Composites, patterns, shells 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, craft-design-lint, conformance
GPU craft-gpu: GPU device, diagnostics, memory budget and the GPU canvas surface; PhotoCraft moves its GPU display onto it 2, 3
8 Office-style shell, audio, code editor and console, slideshow 2, 3; 6b timeline for audio

The egui patches are seven numbered changes (E22 to E28) on top of the fork's earlier patches:

  • the IME composition's pre-edit range on TextEdit state
  • a public accessibility description for Response
  • scroll-bar labels
  • an AccessKit focus report that leaves egui focus alone
  • a pointer press that goes to the widget under the press position
  • DragAndDrop::aborted_by_escape
  • Popup::swallow_outside_press, so the press that closes a popup does nothing else

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 deprecation care.

9.8 Breaking changes

About 100 public items in craft-ui, craft-menu, craft-keymap, craft-window and craft-platform are removed or renamed, counting every removed pub item, including items that moved to another crate.

Each PR that removes or renames a public item keeps the old name as a deprecated alias or shim until every app has moved past it, so an app's next pin bump still builds. A migration table from old path to new path goes with each PR. The old APIs apps use today (the icon-button and combo-box modules, the old rail and number-field types) stay #[deprecated] until the last app that uses them has migrated.

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
Gallery with Components and Theme workspaces, Variants, app preview built
Design lint, conformance test, 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 patches.

Questions for the team

Topic Question
Landing order Is the bottom-up order right, or should the token model and craft-ui core land together? Should the apps' PRs follow each layer, or wait for the whole series?
Deprecation window How long do deprecated aliases stay: until every app has moved past them (the plan), or a fixed number of releases?
egui patches Which of the seven patches go to upstream egui, and which stay in the storytold fork?
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 twenty crates to upstream's twenty-six. Is there a family that should merge, or a crate that should split?
Review load Is a series of about 330,000 added lines, mostly generated or additive, 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
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 General inputs
Menu craft-ui (menu) Takes rows and shortcuts; the app supplies the commands
Preset browser craft-ui (patterns::presets) Works on a generic preset library model
Canvas overlays: grid, guides, smart guides, marquee, rulers craft-ui (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.

Size roles

Role Components
size.control.sm, size.control.md Controls, fields, buttons
size.icon.sm, size.icon.md, size.icon.lg Icons
size.icon.glyph_sm, size.icon.glyph_md The glyph in an icon-only button
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 Gradient ramp drawn as a bar of its own
size.ramp.groove Gradient ramp drawn as the groove of a value track
size.meter Bar that shows a quantity as a filled share of a bordered groove
size.marker.width, size.marker.height Triangular pointer mark on the edge of a value track
size.thumb_row The least height of a list row that shows a thumbnail (layers, channels, links, thumbnail lists)
size.rail.width, size.rail.button Tool rail and panel rail
size.length.field, size.length.track, size.length.short, size.length.number Text or value field, value track, short field, number field over a slider
size.canvas.stage_height, size.canvas.stage_width_min, size.canvas.stage_width_max The stage a story of a canvas control draws its canvas on: its height and the range of its width
size.thumb.card The picture side of a tile card at zoom 1 (tile grids, preset browsers, the start screen)
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. NumberField is at least size.length.number 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).

Conventions:

  • Crates are craft-<family>, one word where possible. No -ui or -core suffix.
  • 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.

Twenty crates are new relative to upstream. Seventeen exist on the design-system branch: craft, craft-automation, craft-browse, craft-color, craft-design-lint, craft-draw, craft-host, craft-imaging, craft-layers, craft-pages, craft-review, craft-table, craft-theme, craft-theme-store, craft-timeline, craft-ui-gallery, craft-ui-macros. craft-gpu is the next step, and craft-audio and craft-code are 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

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, EditEvent, DialogStack, Outcome exists
story, words Stories and word tables of every enabled crate 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 device, meter ballistics and peaks, plus mixer UI. New crate.

Module Holds State
db dB value text planned, step 8
meter Meter ballistics planned, step 8
output Output stream and device setup planned, step 8
peaks Waveform peaks 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
profiler Frame profiler exists
screenshot Screenshot request queue exists
trace Frame timing trace exists

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-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 exists
sha256 Hash for served file names exists
subset Cutting a face to the characters the catalogs use 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 and component 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 UI library: runtime, style, fonts, primitives, the component contract, layout, components, patterns and the shell. The testing feature adds testing; app adds shell::app.

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
canvas The Canvas container: tool host, pasteboard, split views, rulers, navigator, cursors, raster display exists
canvas_controls Leaves a Canvas body shows: brush cursor, grid, pixel grid, guides, smart guides, marquee, outline, line preview exists
choice Checkbox, Switch, RadioGroup, Segmented, Rating exists
contract The component traits, context types, PaintUi, Looks, the pipeline and its steps, the mount and overlay hosts exists
controls Disclosure exists
dialog Dialog, DialogFrame, FullWindowDialog, BlockingOverlay, Prompt and its configurations, DialogStack, DialogHost (ui-dialogs.md) exists
display Badge, Kbd, Progress, Spinner, Text, Icon, Picture, Divider exists
docking SplitArea, Splitter, DockGroup, floating groups and the dock column (ui-docking.md) exists
edit Undo adapters over EditHistory, panel events and DialogValue exists
fonts Font definitions and the script coverage policy exists
form Field, FieldGroup, SliderField exists
graph NodeGraph, Node, NodeKind exists
layout Layout services: LabelColumn, ColumnGroup, the Grid cursor, arrange 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
patterns Inspector, CommandPalette, PreferencesWindow, DockArea, DockPanels, PanelSpec, NavigatorPanel, form dialogs, presets exists
pickers Select, ComboBox, TreePicker, Autocomplete, DatePicker, IconPicker exists
popover Popover, PopupList, Tooltip, DragBadge, DropVeil exists
primitives Painters, Draw, the sensing core, the text adapter, ImeSurface exists
rails PanelRail, ToolRail, FlyoutButton, ToolbarDrawer exists
runtime Per-pass and per-frame services (focus, keys, layout memory, lazy content, overlays, windows) and the one egui adapter exists
sections TitleRow, FooterBar, Section, GroupBox, Panel exists
shell AppShell and its presets, TitleBar, captions, ScreenMode, ToastHost, app::run exists; office-style preset planned, step 8
style The state set and its resolver, style parts, ComponentStyle, UiTokens, StyleCx, the style cache exists
table Table and MetadataTable exists
tabs TabStrip, Tab, DocumentTabs exists
testing The fixture, the suite runner and the story helpers 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

The story viewer (desktop and web) over the registered stories of every ui crate. Not published.

Module Holds State
chrome The options bar, the dock of panels and the window that holds them exists
viewer The viewer's state and the data its chrome shows 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 craft-ui: Component, Props, ComponentStyle, Pattern, CommandSet, EnvValue, TokenGroup, words, stories and trials. Apps use them through craft-ui.

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-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