Quality bar

RavenRS components are meant to be used in production applications, at the level users expect from commercial component vendors. This page defines what "done" means for a component, which checks enforce it, the performance budgets, and where each component stands today.

Definition of done for a component#

A component is ✅ in PARITY.md only when all of these hold:

1. API. Typed builder methods with defaults that look right without configuration. Values come in through Binding<T>, events go out through closures. Every public item has rustdoc, and the type has a runnable example. Growable enums are #[non_exhaustive].
2. States. Rest, hover, pressed, focused (keyboard ring), disabled, selected or checked where it applies, empty, loading and error where it applies, and overflow (long text, many items, a tiny viewport).
3. Screen readers. It sets a role and state with Semantics, and every control has a name: from its text, a label, a FormField or a Tooltip. The gallery audit (examples/component-gallery/tests/accessibility.rs) fails on any unnamed control.
4. Keyboard. Reachable with Tab. Enter and Space activate. Arrow keys, Home and End follow the WAI-ARIA Authoring Practices pattern for that widget. Escape closes overlays.
5. Themes. Built only from semantic tokens, so it is correct in Raven Dark, Light and Glass. Text meets WCAG AA contrast, which ravenrs-style tests for every theme.
6. Edge cases. Empty data, a single item, huge counts, non-ASCII text, out-of-range values (clamped, never panicking) and a zero-size viewport.
7. Performance. Meets the performance contract and stays inside the budgets below. Large collections are virtualized.
8. Tests. At least one behavior test that drives it through Ui (pointer and keyboard). Property tests for any pure logic. A golden image for any component whose drawing is non-trivial.
9. Docs and demo. A section in the component gallery that shows its variants and states.

Enforced checks#

scripts/check.sh --full runs every check below, and nothing ships unless it passes. The project uses no hosted CI, so this script is the gate. Without --full it is the quick check for each pull request: rustfmt, and clippy and the tests of the packages the change reaches (scripts/changed-packages.py).

GPU tests skip themselves, with a message, on machines without a GPU adapter. To accept an intended visual change, regenerate the golden images with RAVENRS_UPDATE_GOLDEN=1 cargo test -p ravenrs --test visual, then review the PNG diff in the commit. A failing run writes *.actual.png next to the golden image.

Release checks, run by hand before each publish:

• cargo semver-checks against the previous release.
• cargo llvm-cov for coverage, at 75% line coverage as of 0.1. Coverage is a signal, not a target.

Applications built with RavenRS#

The rules above that a machine can check also bind applications, through ravenrs-lint. It reads an application's syntax tree and denies, like the compiler: literal colors and font sizes, spacing off the 4px grid, button captions without a verb, icon buttons without a name, more than one primary button in a view, State::new and blocking work in body or build, and files over 600 lines. Every rule is an error, and every exception needs a written reason. cargo ravenrs-lint --init adds the strictest rustc and Clippy levels, the test that runs the rules on cargo test, and the instructions coding agents read; cargo ravenrs-lint --gate is the one command that says the work is done.

A rule a machine can check goes into ravenrs-lint, not only into this page or the skill.

Performance method#

Optimizing guarantees nothing; a gate that fails on regressions does. There are two instruments, and the skill is the runbook for both.

The gate counts the work of each scene with a real runtime and a real renderer, offscreen: builds, layouts, placements, paints, shaping, allocations in the UI, draw calls and why they split, instances, bytes uploaded, glyphs rasterized, atlas resets. These numbers are exact, so any difference from perf/baseline.json fails, improvements included: they have to be accepted with gate --bless, which shows up in the diff. Each run repeats itself and fails if the two passes disagree, and it fails without a GPU. On the screens of real applications (app-*), allocations are only reported, since they depend on the app's data and the clock. Ceilings in the scene registration keep repeated blessing from eroding the budget. Outside macOS, only ceilings bind. scripts/perf-plant.py proves it works by planting regressions.

Frame time is measured apart, before each release, with scripts/perf-time.sh: the best p99 of three processes, because noise on a laptop almost only adds time. On battery the result is invalid. ravenrs-perf cold measures what warm numbers hide, the first time a screen opens.

Budgets for the reference machine, a 14" MacBook Pro with M2 Pro and a 120 Hz screen, at p99:

Time is guaranteed only for the registered scenes on that machine. Counters reflect the same logic everywhere, but a latency on another machine does not follow from them. The system compositor is outside the measurement, and Metal's clock is coarse: short passes often read as zero.

What was measured#

On the reference machine at 1280x800 at 2x, with nothing else running. CPU time in milliseconds at p99, per frame:

The "before" column was measured with the same scenes before the work on the core. A Lottie playing went from a rebuild of the whole screen per frame to none. The finance dashboard opening for the second time went from 25.4 ms to 1.1 ms in its worst frame.

The calculator scene measures examples/calculator as it is, a small screen that stays the same between versions. A click on it, on the same machine: 0.16 ms on the CPU, 0.13 ms recording the GPU's work, 41 instances in 41 draw calls.

Where things stand:

• Scrolling and animating no longer depend on the size of the screen. Only what can be seen is painted and sent to the GPU.

• A rebuild still follows the size of the screen. About 2.7 µs per element, and layout is now 75% of that. The 4 ms budget holds up to about 1,500 elements. The real screens measured have 200 to 420. Beyond that, the next step would be invalidation by subtree, which changes the API of View and BuildCx.

• The GPU is not the bottleneck. Under 2 ms in every scene.

• Batching does little on small screens. Text and shapes alternate, so the calculator needs one draw call per instance. It costs nothing visible today, and painting order would have to be kept by any fix.

• Resizing a window with charts. Bars and gridlines are quads now, with no picture to draw or send; a line with more points than columns draws only what can be told apart; and a picture covers only what it draws. The chart scenes, dragging the window to a new width each frame, p99 of CPU and of recording the GPU's work, before and after:

  Scene	CPU before	CPU now	Recording before	Recording now
  chart, a line of 5,000 points	26.0	13.9	7.2	5.7
  chart-bars, three series of 12 bars	5.5	0.1	6.3	0.1
  chart-board, area, bars, doughnut and line	7.2	5.5	4.7	3.2
  chart-sankey, ten flows between ten nodes, as quads and curves		0.04		0.1

  The finance dashboard went from 19.7 ms to 7.4 ms on the same measure. Lines, areas and slices stay pictures: each scene fits the 16.67 ms of a rebuild, and curves would be drawn again into the atlas on every frame, hover included, at a cost of about 1/26 of a frame per window-sized shape (see below). This comparison was reasoned from those limits, not measured.

• Not measured: the delay from input to the screen in a real window, the system compositor, and other machines.

• Not done: the gate does not yet fail a public component missing from every scene's covers.

How much the renderer can draw#

ravenrs-perf capacity grows each kind of work until a frame stops fitting, counting until the GPU finishes, at 2560x1600. On the reference machine:

The real screens measured use 500 to 1,400 instances, so the renderer has about 20 times the room they need. It is not what limits a screen; a rebuild is.

Shapes of curves share a coverage atlas of at most 8192x8192. Past that, the main pass splits to draw another page, so nothing is left out, at the cost of a pass per page.

Performance contract#

Each component answers for these, through a scene in crates/ravenrs-perf/src/scenes/ listing it in covers:

1. A scene at its worst realistic case, using only the public API. Simple components can share one.
2. A class: static, virtualized, animated or picture.
3. Scale: going from N to 10N items, a virtualized component's counters grow at most 1.2 times.
4. No useless work: an interaction that does not change text shapes nothing, and an animation builds nothing.
5. Idle: no wakes without an animation running or when paused.
6. Cold cost declared for a picture: its cache key and what it does with large data.
7. Ceilings on draw calls, batch breaks and allocations per interaction.

Performance budgets#

Measured with cargo bench (criterion) on an Apple M-series laptop, release profile. Budgets assume a 60 Hz frame (16.7 ms).

Charts are pictures made on the CPU, so their cost is paid when the data or the size changes, and not on other frames: a rebuild that produces the same shapes keeps the same texture. Measured in WebAssembly on Node 24 with the -Oz profile, without SIMD, on the same laptop:

Dragging a window's edge redraws every visible chart on each frame, so more than a few at once, or a long series, go over 16.7 ms while it lasts.

The size of a WebAssembly build, after wasm-opt -Oz:

Link-time optimization drops what an app does not call, so the feature costs an app without charts about 0.2 KB gzipped. Turning it off saves compile time, not download size. An app that does use charts pays about 105 KB gzipped, its own demos included.

The DataGrid caches the query result and reruns it only when the data or the query changes, so these costs are paid once per user action, not every frame. Version 0.1 broke the budget in three cases (search at 47 ms, filter at 31 ms, text sort at 23 ms). They were fixed by parsing filters once per query, matching text case-insensitively without allocating, computing sort keys only for matching rows, and replacing text comparisons with precomputed ranks.

Component audit#

Status against the definition of done. Behavior names the test suites that drive the component. Visual marks golden-image coverage. Every component sets screen reader semantics, covered by accessibility (widgets) and the gallery audit. Right-to-left layout is missing for every component and is tracked once, in the gaps below.

✅ means the WAI-ARIA keys for that widget work and a test covers them. 🟡 means it is reachable and activatable but the full pattern is missing or untested.

Defects found and fixed during this audit:

• RadioGroup, SegmentedControl and Stepper had no keyboard support beyond Tab. Tabs, ToggleGroup, every menu, the Select list and the Calendar grid lacked their arrow-key patterns, and Calendar days could not take focus at all.
• Tab could leave an open Dialog or Sheet for the page behind it; focus now stays inside and returns to the opener on close.
• Focus moved by code hid the focus ring even when the user was navigating by keyboard.
• AspectRatio content with modifiers (for example Spacer::new().background(...)) collapsed to zero height.
• The DataGrid query exceeded the frame budget on 100k rows (see above).

Known gaps#

These block a "commercial-grade" label and are prioritized ahead of new components of the same family:

1. Right-to-left layout. Parley shapes bidirectional text, but layouts do not mirror.
2. Remaining keyboard patterns in the 🟡 rows above: Ribbon key tips.
3. Visual coverage. Golden images exist for 7 scenes. Overlays and navigation have none yet.
4. Screen reader depth. Text fields do not expose caret position or selection, and the web mirror is rebuilt whole when the tree changes. Tested with macOS VoiceOver's API (System Events) and the browser's DOM; not yet with NVDA, Narrator or Orca.