Theme Accent Mode Density

Contrast

Text against what it sits on. Below 4.5:1 fails WCAG AA for body text — the check a reviewer runs on any surface that takes a tone.

Waiting for the first preview to report its palette.

Corners

Sets all three radii at once. The individual values are under Geometry.

Brand 5

The accent seam an app actually brands itself through. Change these and you have made the decision a real `DesignTokens.graphite(...)` call makes.

accent The one voice of color — a BRAND SLOT — as a FILL (`--accent`, `Brand.d.ts` THE ACCENT'S TWO JOBS, #1689): a surface painted with the accent under [onAccent] (a slab, the FAB, a count badge, a checked box's face, an on switch's track, an active toggle's face, a pin head, a band under `chrome: accent`) and every wash mixed from it ([accentTint], [accentSel], [focusHalo], [groundGridInk], the deep chrome). Drawn ON a surface, the accent is [accentInk]. onAccent Foreground color painted on top of [accent]. accentInk THE ACCENT'S INK (`--accent-ink`, #1689): the accent drawn ON a neutral or washed surface — text and links, a glyph or icon, a border, an edge or underline, a selection start-edge, the focus ring and a field's focused border, a radio's dot, a status marker, a progress bar or spinner, the chart's lead series, the palette's `accent` ink. THE BOUNDARY OF A FILLED STATE IS INK: a checked box, an on switch and an active toggle draw their edge in it over the [accent] fill. Absent from the brand it IS [accent], byte for byte; a brand whose accent is a high-luminance hue states a darker ink of the same hue, and the plane-contrast gate holds this, not the fill, to the card and the ground (`contrastFloorViolations`). accentTint The accent at 9% (16% dark) — ID chips, the active row's wash, an applied chip, an applied-but-closed control (`--accent-tint`, derived from [accent]). accentSel The accent at 11% (18% dark) — the rail's FILLED INDICATOR (M3), laid over the GROUND, a step stronger than [accentTint] because the ground is darker than the card (`--accent-sel`, derived from [accent]).

Geometry 15

Square or rounded, and how heavy every line is. The radius row above the controls sets all three corners at once, because "what does square feel like" is one decision rather than three numbers.

rXs Radius for chips, checkboxes, tags, badges (`--r-xs`, 2). rS Radius for controls: buttons, fields, map pins and clusters (`--r-s`, 3). rM Radius for surfaces: cards, menus, dialogs (`--r-m`, 4). rL Radius for a sheet's leading corners, the largest surfaces (`--r-l`, 8). rMark Radius for a status marker, a legend swatch (`--r-mark`, 1). rPill THE PILL FLOOR (`--r-pill`, #1102): 0 in every corners set but [CornerStyle.round], where it is 999 and clamps to height / 2. A pill-capable control reads [controlRadius] or [chipRadius], never this directly. hairline Hairline stroke width. iconStroke Icon stroke weight. focusW Focus ring stroke width (solid [accentInk], offset [focusOffset]). focusHaloW The width of a FIELD's focus halo (`--focus-halo-w`, 3): a focused field takes the [accentInk] border plus [focusHalo] this wide OUTSIDE the box — the idiomatic Flutter form is a [BoxShadow] with this `spreadRadius` and zero blur. ctl Control height: buttons, toolbar (44 comfortable · 32 compact). fld Field box height: text fields, selects, date fields (`--fld`, 44 comfortable · 36 compact) — a field box stays a step taller than a control at the desk. navh Nav row height (44 comfortable · 34 compact). rowV Table row vertical padding (density knob): 14 comfortable (a 48 row) · 10 compact (a 40 row). barH The app bar's height (`--bar-h`, 64 comfortable · 56 compact) — the frame's one band, on the ground.

Surfaces 17

Everything the app is painted ON — the ground behind the content (the frame paints it too), the cards over it, the well inset in a card, and the washes that show state.

sur The GROUND (`--sur`): the app background, and the frame — the app bar and the rail paint it, with no fill, rule or shadow of their own. paper The CARD (`--paper`): tables, panes, charts, forms, sheets, menus — the plane every job sits on, a step above [sur]. paperW Sidebar / rail wash (`--paper-w`) — retiring with the rail wash (#892). well The WELL (`--well`): inset fills inside a card — photo plates, quote blocks, tracks, avatar blocks, neutral tags. ink4 State layer: hover wash, pressed, chip trays — opaque, over the card. cardEdge The card's hairline edge (`--card-edge`) — a LITERAL per theme, not an alias: in dark it is the card's RIM, its own value, because a shadow cannot lift a card off a near-black ground. cardSelEdge The selected record card's start-edge bar (`--card-sel-edge`): 0, or [edge] under [SelectionMark.edge]. surfaceEdge The frame a tile, sheet, panel or docked pane draws around itself (`--surface-edge`, aliasing `--card-edge` — every one a card now). hair Row + minor separators inside a card. hairS Structural: table header rule, sheet edges, a divider that must read. rowHover Table row hover wash. groundHover The state layer ON THE GROUND (`--ground-hover`, #892): the rail's hover, a ghost control on the bar. [ink4] is a CARD state layer and sits above the ground's value, so on the ground it vanishes; this steps the ground itself toward the ink — `color-mix(in srgb, var(--ink) 6%, var(--sur))`, derived in each factory from its own ink and ground, so the separation knob moves it with [sur]. groundGridInk The grid's line color (`--ground-grid`: the accent at 10%). groundGridSize The grid's pitch (`--ground-pattern-size`, 24). rowSel Table row selected wash. expandBg Expanded-row detail well. scrim Modal/sheet scrim.

Bands 10

The rail's head and the view bar beside it (one band across the top at 960 and wider), a pushed screen's bar, the compact bar and the compact nav bar — the band's fill, its rule, its hover and active faces, the resting field box on it, and the ink and accent control that sit on it. The rail's tree and its footer stay on the ground.

chrome A band's fill (`--chrome`): the app bar, the app band, the rail outside a drawer, the compact nav bar. chromeField A FIELD BOX's resting fill on a band (`--chrome-field`, #1186 — `AppBar.d.ts` ON A BAND): the search field resting on an accent or deep band takes this tonal step of the band — the on-chrome ink at 14% over [chrome] — with no border, and lift to [paper] while focused. Under [ChromeTone.ground] it is the field's ordinary paper fill, so nothing changes there. chromeHair A rule on a band (`--chrome-hair`). chromeHover A band's state layer (`--chrome-hover`). chromeSel The active nav item's face on a band (`--chrome-sel`). onChrome Text and glyphs on a band (`--on-chrome`). onChrome60 Secondary ink on a band (`--on-chrome-60`): meta, counts, borders. onChromeAccent An accent control on a band (`--on-chrome-accent`) — inverted under an accent or deep band (the #338 accent-on-accent cases). onChromeAccentInk The accent as INK on a band (`--on-chrome-accent-ink`, #1689): a lit glyph, an edge or a ring on the chrome. [accentInk] under a ground band; under an accent or deep band it inverts with the fill and IS [onChromeAccent]. [onChromeScope] maps [accentInk] onto it. onChromeOnAccent The ink on that control (`--on-chrome-on-accent`).

Text and controls 11

The ink ramp, the control outlines and the field's focus halo. Every pair the panel can break is watched by a contrast badge above.

ink Primary text. ink60 Secondary text. ink40 Tertiary: labels, counts, glyphs, placeholders — never body text. ink20 DIM MARKS, never text (`--ink20`): an unfilled priority bar, the grab bar, a stepped-back chart bar, the crosshair. btnBorder Default button outline. btnBorderHover Button outline on hover. fieldBorder A field's box (`--field-border`): text fields, selects, date fields, the combobox, the ref tile, the search field — the 3:1 boundary. chkBorder Checkbox border — the 3:1 boundary. focusHalo A FIELD's focus halo color (`--focus-halo`): the accent at 20%, derived from [accent] — the FILL, since a halo is a wash (#1689) — so a brand's halo follows its accent. focusHaloDanger A focused field IN ERROR (`--focus-halo-danger`, #896; `TextField.d.ts` THE FIELD STATES): [focusHalo]'s halo in the danger, the danger at 20%. edge Selection/cursor start-edge indicator width.

Status 7

The three voices that mean something — danger, caution and ok — each as a foreground and a surface wash, danger with a border as well.

danger Danger/error foreground — someone must act. dangerTint Danger/error surface wash — the filled tag and the banner a demanding status takes. dangerEdge Danger/error border. caution The caution ink (`--caution`, #922): the StatusPill caution plate's word and the chart tier's caution tone (a donut segment, a gauge band, an aging segment). ONE number on both kits — the token's oklch value converted, never a color this kit derives. Accent-independent. cautionTint The caution plate's wash (`--caution-tint`) — [caution] at the token's alpha, so the plate composites on whatever surface it sits on. ok Success/resolved foreground — the estate's one green (`--ok`). Accent-independent like [danger]; appears only where resolution or success is stated (StatusPill positive, resolved chips), never as a third decorative voice. okTint Success/resolved surface wash (`--ok-tint`).

Data 5

The default pin head, its glyph and its halo, and the group bands. A pin's category color comes from the palette, named in the theme seed.

pinFill The head of a pin that names neither a category nor a status (`--pin-fill: var(--accent)`; `MapView.d.ts` ONE CHANNEL PER JOB). It IS the themed accent by definition. pinFg The glyph on [pinFill] (`--pin-fg: var(--on-accent)`); a palette fill takes its own [KitPaletteColor.on]. pinHalo The 1.5px ring OUTSIDE a pin head's rim, so any fill reads on any basemap (`--pin-halo`: the paper at 85%; `MapView.d.ts` EVERY FILL IS LEGIBLE ON EVERY BASEMAP). group0 Level-0 group header band. group1 Level-1 group header band.

Map 11

The basemap's roles — land, water, parks, roads and their casings, buildings, labels — and the pending pin's gray. A raster basemap keeps its own imagery; these paint the map's plate and any kit-drawn map.

mapLand Land — the map's plate (`--map-land`). mapWater Water (`--map-water`). mapPark Parks and green space (`--map-park`). mapRoad A minor road's fill (`--map-road`). mapRoadEdge A minor road's casing (`--map-road-edge`). mapRoadMajor A major road's fill (`--map-road-major`). mapRoadMajorEdge A major road's casing (`--map-road-major-edge`). mapBuilding Building footprints (`--map-building`). mapLabel Place and road labels (`--map-label`). mapLabelWater Water labels (`--map-label-water`). pinPending A PENDING pin's head (`--pin-pending`, #894): the StatusMark `pending` tone on a pin with no category, whose fill says its status — and the hollow status badge's border beside one (`MapView.d.ts` ONE CHANNEL PER JOB, #972). [accent], [ok] and [danger] carry the other three. Clears 3:1 on [mapLand]; never text.

Scrollbars 6

Every scroller's bar: the thumb at rest and while hovered or dragged, the strip it rides, and the desk bar's thickness, side gap and corners. The desk half shows only while a fine pointer is attached; at touch the platform's own overlay keeps its size.

scrollbarThumb The scrollbar thumb at rest (`--scrollbar-thumb`, aliasing [ink40]): the muted-ink role, which clears the 3:1 a draggable control needs on [sur] and [paper] — never the state layer, which Material's Android thumb reads by default and which cannot be seen on [sur]. scrollbarThumbHover The thumb while hovered or dragged (`--scrollbar-thumb-hover`, aliasing [ink60]) — one ink level up; the thumb never grows. scrollbarTrack The strip the thumb rides (`--scrollbar-track`): transparent in graphite, so the thumb reads against the surface it scrolls. A theme may fill it. scrollbarSize The DESK scrollbar thumb's thickness (`--scrollbar-size`, 8). Applied only while a fine pointer is attached; at touch the platform's overlay keeps its own. scrollbarInset The clear gap on either side of the desk thumb (`--scrollbar-inset`, 2) — `ScrollbarThemeData.crossAxisMargin` — so a scroller's bar takes [scrollbarSize] + 2 × this. scrollbarRadius The thumb's corner radius (`--scrollbar-radius`, aliasing [rS]): the control radius, so a theme that moves [rS] moves its thumbs with no widget edit.

Advanced 6

Real controls that are not decisions — motion durations, the focus ring offset, the touch floor. Opens collapsed on purpose.

tQuick Quick transition duration — chevrons, hovers, checks. tMove Move transition duration — sheets, rail, menus. tDraw Draw transition duration (`--t-draw`) — the chart entrance band, the draw-in choreography's clock. tStagger Per-mark entrance offset (`--t-stagger`) — the delay each successive mark takes on top of the entrance band; the per-mark offset clamps at 20 steps, so a large series never trails past the band. focusOffset Focus ring offset. touch Minimum hit-target floor. Follows the POINTER, not the density knob alone (rhythm.css): 44 at comfortable (touch surfaces — never shrink below on touch), 32 at compact, which only ever applies with a fine pointer attached. Density-resolving this is what lets the control set — and a control-bearing table row — densify together (V-16).

Take it with you

The Dart that reproduces what you are looking at. It is a real constructor call, because the configurator edits a real preset — what you copy is what an app can paste.

Components

Identity and media

How a record shows who and what it is — the avatar whose hue is derived from the name, who else is here (the presence stack and the badge on a focused item), the id chip, and the media header including its real no-image fallback.

Spec of record: design-system/components/data/Avatar.d.ts

Knobs

Live

Real widgets, built from the real kit. Turn a knob and it rebuilds; the theme bar above applies the design system's own tokens — including anything you changed under Customize — and the device selector uses the same sizes the golden baselines gate on, so what you see here is what CI holds the widget to.

Press Focus on any preview to take it to the full window — at a desktop width that renders most devices at 1:1, which is when the widget's own controls become clickable. The bar always states the device and the scale, so a shrunk preview says it is shrunk. Esc leaves.

Device

family_identity

Knobs

Theme

Accent Mode Density

Dart for these values

family_identity()

What it is made of

The widgets this screen assembles, with their full API below. They used to live on a second entry of their own; one thing you choose gets one page.

AppAvatar widget

Full dartdoc

The design-system Avatar — the identity block. A square at the chip and badge radius (DesignTokens.rXs) carrying a person's initials (or their image when one exists), sitting in the leading slot of thread cards, feed posts, tagged chips, and account rows. Identity, never status. Sanctioned size steps with their initial sizes: 32→11 · 28→10 · 22→9 · 20→9 · 16→8 (feed/compose · card/composer · reply · level-3 · tagged chip). Non-interactive; name is the semantic label. ```dart const AppAvatar(name: 'Adeyemi Okafor', size: 32) const AppAvatar(name: 'You', hue: AppAvatarHue.mono) AppAvatar(name: me.name, image: NetworkImage(me.avatarUrl)) ```

AppAvatardefault constructor

Knob	Type	Default	What it does
hue	AppAvatarHue identity · mono	AppAvatarHue.identity	Identity hue (default) or the monochrome block.
image	ImageProvider?	null	Avatar image; cover-fit, initials fallback on failed load.
name *	String	—	Full display name — the initials source, the hash input, and the semantic label.
size	double	28	Edge length. Sanctioned steps: 16 · 20 · 22 · 28 · 32.

AppPresenceStack widget

Full dartdoc

The faces of the OTHER people in a scope (`Presence.d.ts` PresenceStack): one AppAvatar each, a 2px gap and no overlap, at most max slots with the last one the `+N` overflow block. The whole stack is ONE button opening an anchored list that names every member and whether they are viewing or editing. Empty renders nothing. Pass it to `AppHeaderBar.presence` — the one place a floorplan shows presence: ```dart AppHeaderBar( title: 'Work order', presence: AppPresenceStack( members: ref.watch(presenceProvider(scope)).members, ), syncStatus: sync, ) ```

AppPresenceStackdefault constructor

Knob	Type	Default	What it does
max	int	3	Slots before the overflow; the `+N` block takes the last one.
members *	List<PresenceMember>	—	The other people here, in display order.
size	double	24	Face size: sanctioned 24 · 28.

AppPresenceBadge widget

"Sam Lee is editing" on an item another person has in focus (`Presence.d.ts` PresenceBadge): a 16 face and the sentence on the well plate. A list row, a form field and a markup annotation all use this one badge. label replaces the sentence; the face is unchanged.

AppPresenceBadgedefault constructor

Knob	Type	Default	What it does
label	String?	null	A host's own wording, in place of the sentence.
member *	PresenceMember	—	The person holding the focus.

AppIdChip widget

Full dartdoc

The design-system IdChip — how a record says its name. Renders id (e.g. `WO-2041`, `SR-1042`) in DesignTokens.dataS (the small mono/data face) on a faint DesignTokens.accentTint square, radius DesignTokens.rS. This is the system's **ID grammar**: one per row, leading position — never a pill, never used for statuses (a status is a word per the constitution's "encode once" rule). Two modes: * **Static** (default, onTap null) — a plain labeled chip, not interactive. No Semantics button role, no focus/hover/press paint. * **Tappable** (onTap set) — some ID chips navigate to the record they name. Becomes a real focusable/tappable target with the state contract: enabled · hover (DesignTokens.ink4 wash, pointer enhancement only) · focus-visible (1px solid accent, zero offset) · pressed (1px translateY). The tap target is expanded to at least DesignTokens.touch even though the visual chip is compact. title feeds a Tooltip and, for the tappable form, the accessible name; for the static form it is exposed as a plain Semantics label. ```dart const AppIdChip(id: 'WO-2041') AppIdChip(id: 'SR-1042', onTap: () => openRecord('SR-1042')) ```

AppIdChipdefault constructor

Knob	Type	Default	What it does
id *	String	—	The record ID text, e.g. `WO-2041`. Rendered in DesignTokens.dataS, one line, never wrapped.
onTap	VoidCallback?	null	Fires when the chip is tapped. Null renders the static (non-tappable) form — no Semantics button role, no hover/focus/press paint.
title	String?	null	Tooltip text and accessibility hint. Falls back to id for the Semantics label when null.

AppMediaHeader widget

Full dartdoc

The design-system media header — a hero image band with a bottom scrim and slotted overlay content. Any surface, zero domain knowledge: image is a stored image reference fed verbatim to AppImage's resolution ladder (`staged://` / `asset:` / `http(s)://` / origin-relative / blank), and overlay is a caller-built widget (title / status / actions) laid over the scrim. A blank/absent image renders the hairline-framed glyph placeholder — the band keeps its height so a layout does not jump between records with and without a photo. Anatomy (bottom to top): the image layer (over an DesignTokens.ink4 void, BoxFit.cover by default), a bottom-anchored scrim gradient (DesignTokens.scrim → transparent, enabled by default so overlay text stays legible over arbitrary photo pixels), the overlay slot inset from the band's start + bottom edges, and a bottom structural hairline framing the band off the content below. **Scrim.** The gradient rises from DesignTokens.scrim at the bottom to transparent at mid-band. Set scrim false to drop it (e.g. when the overlay carries its own background, or there is no overlay). With no overlay the scrim still paints when enabled — callers usually pass `scrim: false` there. **Placeholder.** When image is blank the band renders a centered DesignTokens.ink40 image glyph over an DesignTokens.paperW wash — the same "no image, identity only" grammar as the cell/gallery thumbs, at band scale. The overlay still renders over the placeholder. State/semantics: purely presentational — it renders and never navigates. When onTap is set the whole band becomes a button (e.g. open a full-screen viewer); the accessible name comes from semanticLabel. Reduced motion (reducedMotionOf — the framework flag OR the platform's own Reduce Motion) drops the Hero flight, and so does the desk posture, where navigation cuts. ```dart AppMediaHeader( image: observation.photoRef, // '' → framed placeholder heroTag: 'obs-image-${observation.id}', overlay: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text(observation.title, style: onScrimTitleStyle), Text(status, style: onScrimSubStyle), ], ), onTap: openViewer, semanticLabel: 'Observation photo', ) ```

AppMediaHeaderdefault constructor

Knob	Type	Default	What it does
fit	BoxFit	BoxFit.cover	How the image inscribes the band (default BoxFit.cover; pass BoxFit.contain to letterbox the full image over the DesignTokens.ink4 void).
height	double	_defaultHeight	The band height in logical pixels. Fixed so a layout does not jump between records with and without a photo.
heroTag	Object?	null	Optional Hero tag for the image layer. When set (and neither reduced motion nor the desk posture holds — at the desk navigation cuts, with "no flight at all") the photo flies between this band and the surface it opens — and, sharing one tag per record, between a list/map preview and the detail…
image	String	''	The stored image reference, fed verbatim to AppImage's resolution ladder. Blank (the default) renders the framed glyph placeholder.
onTap	VoidCallback?	null	Tap callback — when set the whole band becomes a button (e.g. open a full-screen viewer). Null renders a non-interactive band.
overlay	Widget?	null	Overlay content laid over the scrim, inset from the band's start + bottom edges (a title, a status word, an actions row). Null renders no overlay.
scrim	bool	true	Whether the bottom scrim gradient paints (DesignTokens.scrim → transparent). Default true — keeps overlay text legible over arbitrary photo pixels. Set false when there is no overlay or the overlay carries its own background.
semanticLabel	String?	null	The accessible name for the band when onTap is set. Null falls back to a generic label.

PhotoViewer widget

Full dartdoc

The full-screen zoomable photo viewer body — a plain paper surface under an AppHeaderBar close control, the image inscribed `contain` inside an InteractiveViewer (pinch/drag zoom up to 4x). Normally reached via openPhotoViewer; public so a host with its own route table can mount it there instead. **No sync control here, deliberately.** The "every view carries it" convention names views; this is a lightbox over one image — a modal dismissed with an ✕, in the same family as a dialog or a sheet, none of which take the control either. The surface underneath it has one.

PhotoViewerdefault constructor

Knob	Type	Default	What it does
imageRef *	String	—	The image's storage reference — any AppImage ladder shape.
title	String?	null	The header title; null renders the default.

Where it lives

Class	File
AppAvatar	packages/app_widgets/lib/src/kit/data/avatar.dart
AppPresenceStack	packages/app_widgets/lib/src/kit/data/presence.dart
AppPresenceBadge	packages/app_widgets/lib/src/kit/data/presence.dart
AppIdChip	packages/app_widgets/lib/src/kit/data/id_chip.dart
AppMediaHeader	packages/app_widgets/lib/src/kit/data/media_header.dart
PhotoViewer	packages/app_widgets/lib/src/patterns/photo_viewer.dart