Status and feedback

The design-system Banner — a persistent, inline notice about the surface it stands with (offline, sync failed, stale data, a blocked record). **Not a floating toast.** Toasts do not exist in this system; a transient confirmation (e.g. "SR-1042 deleted") belongs in the Modeline, never here. AppBanner sits inline, above scroll, describing a *persistent* condition. WHERE it stands is its host's clause (`RecordsScreen.d.ts` THE BANNER'S RANK AGAINST THE FACES, `DetailView.d.ts` THE SURFACE NOTICE IS THIS COMPONENT'S SLOT); a host that used to bleed it across a surface insets it to that surface's padding. THE CONTAINED BANNER (`Banner.d.ts`, 2026-09-29, #896) is a TINTED PLATE: the tone's fill at DesignTokens.rS corners, padded 10 × 12 and sized by its content, with no border, hairline or shadow (the tint alone separates it from the card or ground beneath). A leading 16 glyph — KitGlyph.warning by default for AppBannerTone.danger, none by default for AppBannerTone.info — stands 10 before the message on its FIRST line. The message wraps and is never truncated (12.5 at the body line height, weight 400); an optional lead opens it at the em weight ("**Blocked since Sep 22.** Check valve 2 failed its test."). The meta, the one ghost action and the dismiss "✕" trail at the plate's inline end, aligned to its top. The 2px start edge, the strip's bottom hairline and the 40 minimum height are DELETED. Both tones are live regions (`Semantics(liveRegion: true)`) so assistive tech announces the notice as it appears. ```dart AppBanner( message: 'Working offline. Changes sync on reconnect.', glyph: KitGlyph.cloudOff, ) AppBanner( tone: AppBannerTone.danger, lead: 'Blocked since Sep 22.', message: 'Check valve 2 failed its test.', actionLabel: 'Retry', onAction: retry, ) ```

The design-system StatusPill — a tinted plate carrying a short word or figure (+ optional leading 12px glyph) in the tone's ink. For LIVE, transient, or derived state only. A stored status stays a word in its cell; this widget never re-encodes a value. ```dart AppStatusPill(tone: StatusTone.caution, label: 'Syncing…') AppStatusPill( tone: StatusTone.positive, glyph: KitGlyph.trendUp, data: true, label: '+12%', ) ```

The design-system StatusMark — a stored status as its WORD beside an 8px square marker (DesignTokens.rMark), or, for AppStatusMarkTone.blocked, the filled danger tag. The word renders in DesignTokens.ink60, the UI font at the HOST's size: style is the host's text style, and the word takes its size (and line height) — a table cell passes nothing and the word reads at DesignTokens.body, the cell's own size; a larger host passes its value style. Color and family are the mark's, never the host's. The blocked tag is always the label role (12/500), whatever the host. Semantics: ONE node reading the word alone. The marker is excluded — it is the word's glyph, and a reader hearing "square" before every status would be hearing decoration. ```dart AppStatusMark(label: 'In progress', tone: AppStatusMarkTone.active) AppStatusMark(label: 'Blocked', tone: AppStatusMarkTone.blocked) ```

The design-system Progress — the live-operation loader. An optional accent micro-label (the state word — "generating", "queued") over a 2px indeterminate track: a 28%-wide DesignTokens.accent bar sweeping a DesignTokens.accentTint rail, one sweep per DesignTokens.tMove × 5.75 (1.15s in graphite), easing with DesignTokens.easeIn. A record mid-operation server-side renders this in its row's status slot AND its detail's build state — the same treatment both places, so "building" reads identically everywhere. Division of labor (the spec states it once): content whose SHAPE is known but not yet fetched is `AppSkeleton`; a live operation the user is watching is AppProgress; never a spinner in either seat. Indeterminate only — a determinate percentage stays host anatomy (a table's progress cell, a detail fact's inline bar), not a knob here. Under reduced motion (reducedMotionOf — the framework flag OR the platform's own Reduce Motion) the bar rests static at the inline start and no AnimationController is ever created; under RTL the sweep mirrors (start → end is a reading direction). The sweep is a LOOP period, so it keeps the stock DesignTokens.tMove multiple at the desk. The track is decorative to assistive tech; the widget announces label through its own `Semantics` node when one is given. ```dart const AppProgress(label: 'generating') const AppProgress(label: 'queued') const AppProgress() // track alone — the word is carried elsewhere ```

App-bar sync control. A split pill: the main zone fires a one-tap manual sync (and is the retry affordance when a cycle failed); the trailing caret zone opens the detail panel. The main zone is enabled in EVERY phase, `syncing` included: a tap during an in-flight cycle is the user's request that the engine promotes to a visible, spinning cycle, so onSyncNow must tolerate being called while a cycle runs (the sync worker's `runOnceFromUser` does — it promotes and queues, never double-runs). **Icon-only at every window class** (`design-system/components/navigation/ AppBar.prompt.md`, pin `839c92d`), and it **rests on the sync glyph** — the idle-with-nothing-queued state is not a ✓. Both were labeled/checked until 2026-08-12: a verb beside the glyph competed with the bar's one labeled control (the slab primary) and made the pill's width jump between window classes, and a checkmark reads as a status readout, which is not something a field user taps — so the force-a-sync affordance vanished exactly when the queue was empty. Up-to-date is stated by the tooltip and the absent badge. `offline` and `failed` still swap the glyph: those are conditions, not a completed job. Drops into a scaffold's header-bar action slot. Consumes plain streams plus an onSyncNow callback, so it carries no dependency on the sync engine. Optionally takes onCancelOne / onDiscardAll / onEvacuateOne callbacks for the detail panel's row-resolution affordances; each is independently null-able, and an unwired one renders no control at all rather than a disabled one.

The design-system EmptyState — a centered "nothing here" surface stating what the view would show plus exactly one way out. Anatomy (per `EmptyState.d.ts` / `.prompt.md`): a title (a flat fact, e.g. "No records match." — never an apology), an optional one-line message (cause or consequence, e.g. "4 filters applied." — never decoration), and an optional single actionLabel + onAction pair rendered as one ghost/outline AppButton (the primary action of the empty surface; the accent slab belongs to the app bar, never here). **No illustration, no decorative icon** — the constitution bans both for this surface, and the spec's Flutter mapping calls this out explicitly: "no `Illustration` slot exists on purpose." There is no icon slot on this widget at all. Centers itself in whatever space its parent gives it (typically the body of a list/table/detail view once loading resolves to zero rows). Adaptation strategy: **scale** (density only — the same anatomy at every M3 window class). ```dart AppEmptyState( title: 'No records match.', message: '4 filters applied.', actionLabel: 'Clear filters', onAction: clearFilters, ) const AppEmptyState(title: 'No photos on this record.') ```

The kit's face for a router with no screen to show: the cause stated flat and one way out, to the start location. A whole route surface: it brings its own Scaffold, because a router's error page is pushed with no chrome above it. ```dart GoRouter( routes: ..., errorBuilder: (context, state) => AppRouteFace( reason: AppRouteFaceReason.notFound, location: state.uri.path, onHome: () => context.go('/'), ), ); ```

The design-system Skeleton — a structural loading placeholder. Renders a flat block filled with DesignTokens.ink4, radius DesignTokens.rS (a true circle for AppSkeletonVariant.circle), in the shape of the content that will load. **Never a spinner** — the constitution's "loading = structural placeholders" rule: compose several AppSkeletons (or AppSkeletonLine for a text-line stack) in the real layout's geometry so the loading state previews the coming content. Carries a quiet opacity pulse (1.0 → 0.45, looping, easing via DesignTokens.easeIn / DesignTokens.easeOut) — no shimmer sweep, no stagger. The pulse is **disabled under reduced motion** (reducedMotionOf — the framework flag OR the platform's own Reduce Motion); the block renders static (opacity 1.0) instead. The pulse is a LOOP period, so it keeps the stock DesignTokens.tMove multiple at the desk rather than riding the desk's tighter band. The widget is `ExcludeSemantics`d — it is decorative chrome, not content; wrap the loading region itself in a live-region `Semantics` at the call site if an announcement is wanted. ```dart // A detail-view hero placeholder. const AppSkeleton(variant: AppSkeletonVariant.block, width: 320, height: 160) // An avatar placeholder. const AppSkeleton(variant: AppSkeletonVariant.circle, width: 40, height: 40) // A text-line stack (see AppSkeletonLine for the convenience wrapper). const AppSkeleton(width: 120) ```

Convenience wrapper: a stack of AppSkeletonLine.lines text-line placeholders, gapped by kSkeletonLineGap, the last line rendered at 60% width (mirrors the web Skeleton's `lines` prop — a paragraph tapering to its final line). ```dart const AppSkeletonLine(lines: 3) ```

The design-system BulkBar — a contextual bar that appears while rows are selected, replacing (or docking above) the surface it describes. Styled AS a selection object, per the constitution's selection grammar: a 2px DesignTokens.edge-wide accent start-edge spanning the bar's full height, over a DesignTokens.rowSel tint wash — the same encoding a selected table row carries, so the bar reads as "this IS the selection," not a floating toolbar. Anatomy, leading to trailing: a leading ✕ (AppIconButton) that clears the selection (onExit), the selection count in the data font at em weight (DesignTokens.dataEm) plus a noun label, a flexible spacer, and the caller-supplied actions — **outline (or ghost) `AppButton`s only**. There is never an accent slab here: the bar already carries the one accent statement (the start edge), and bulk operations are peers, not a single primary action. A destructive bulk action (e.g. Delete) is a danger-tone outline button; the caller confirms or offers undo, this widget never gates the tap itself. AppBulkBar renders unconditionally for whatever count it's given — the "hide at zero" rule from the spec is the **caller's** concern (a host simply stops building this widget when its selection empties), matching the Widget-slot composition policy: no `showX` boolean paired with a value prop. Adaptation strategy: **scale** (density only — the same anatomy at every M3 window class; on compact widths the actions cluster wraps rather than truncating, same as `AppButton` rows elsewhere in the kit). The bar is a live region (`Semantics(liveRegion: true)`) so assistive tech announces the selection count as it changes. ```dart AppBulkBar( count: 3, onExit: () => setState(() => selection.clear()), actions: [ AppButton(variant: AppButtonVariant.outline, label: 'Assign', onPressed: assign), AppButton(variant: AppButtonVariant.outline, label: 'Export', onPressed: export), AppButton( variant: AppButtonVariant.outline, tone: AppButtonTone.danger, label: 'Delete', onPressed: delete, ), ], ) ```

The design-system Modeline — the estate's TRANSIENT message band (`Modeline.d.ts`, transient-only since 2026-08-24 Phase D). A thin hairline strip locked at the `--mode-h` 28px component height. It DRAWS only while it has something to carry — a message with its one actionLabel (the Undo pattern: a reversible destructive action offers undo here instead of a confirm dialog), or, in the footer's ONE sanctioned case, live work-state segments (the form's save-bar line). The standing records segments, the posture word, and the band's scope segment are DELETED — the counts restated what the surface shows, and the scope leads the bar's subtitle (`AppScaffold.scope`). **THE SILENT REGION** (`Modeline.d.ts` SILENT REGION, THE COLLAPSE IS KEYED PER KIT; #483). Silent, the strip draws nothing and reserves no height, but it is NOT removed: the same element — and the same `liveRegion` semantics node — stays mounted, so a message arriving is a text change inside a region assistive tech already knows, never a region mounting WITH its first message (announced unreliably). A zero-size box will not do on this kit: a semantics node whose rect is empty is dropped from the tree. So the strip keeps its full 28px LAYOUT and is laid OVER the surface's edge — above a footer's bottom edge, below a band's top edge — unclipped, painting nothing and taking no hits, while its reserved height is zero. A host therefore keeps an AppModeline mounted for as long as its surface can message; mounting it on demand is the same defect by another route. The strip ENTERS AND LEAVES on the sheet band (AppMotion.move; a jump-cut under reduced motion): its reserved height grows or shrinks while it fades, and the leaving strip keeps the message it was carrying until it has gone. No clip is ever involved — a clip would empty the region's rect for the flight and drop the node this widget exists to keep. AppModeline owns no `Timer` and no auto-dismiss clock. The host decides when a message appears and clears it (e.g. a delayed callback that sets message back to null after ~6 seconds). The live region is the MESSAGE ALONE — never the action, because an interactive element inside a live region is re-announced by everything around it — and never the ambient segments. **An overflowing message ellipsizes; the action keeps its room** (`Modeline.d.ts`, #760): the message is the one shrinking item, the action never yields, and in the segmented footer the message yields before the segments. **A message may be dismissed** (`Modeline.d.ts`, 2026-10-11, #1342): with onMessageDismiss wired and a message carried, the strip's LAST item is a quiet "Dismiss" ✕ after the action, and Escape with focus inside the strip calls it too. **Two postures** (AppModelinePosture): the footer at the surface's bottom edge, or the band the shell composes under the app bar. One channel per view, never both. ```dart AppModeline( message: '3 records deleted', actionLabel: 'Undo', onAction: undoDelete, onMessageDismiss: clearMessage, ) AppModeline(segments: ['2 required', '1 invalid']) // form save bar ```

The strip's single trailing action — a compact data-font accent affordance (`.fo-mode__act`), NOT an `AppButton`: a 44px control would inflate the geometry-locked 28px strip. PUBLIC since 2026-08-24: this grammar is also the app bar's TRANSIENT affordance (the dashboard's relocated arrange-gesture Undo — `Dashboard.d.ts` "a transient data-font accent 'Undo' affordance"), so the records chrome renders the same atom rather than a second implementation or a full `AppButton` in the wrong type role. A bar host passes minHeight (`DesignTokens.ctl`) so the hit region meets the touch floor the 28px strip cannot host.