ui-work

# UI Work ## When To Use Use this for user-facing Flutter UI changes in `lib/`, including widgets, screens, navigation surfaces, settings rows, dialogs, and interaction behavior. ## Conventions - Reuse the patterns of nearby widgets, providers, notifiers, and helpers before adding an abstraction, and keep to the look the rest of the app has: Material You from `material_ui` as the base, with Apple's interaction conventions (continuous corners, sheets that snap between detents, a floating tab bar) built on Material widgets rather than Cupertino ones. Do not introduce a visual system for one screen or rewrite a layout the request does not need. - `.agents/rules.md` is binding here: the lint set (`child:` last, `const`, final locals), the superellipse corner API, and the widget-test facts under Testing Rules (`pumpAndSettle` never returns on `EditorView`, `dispose()` must not await, auto-dispose providers need a container-level hold, platform decisions are passed in as parameters). - Settings screens are built from the `ConfigToggleItem` family in `lib/widgets/config_item.dart`; the Settings Rows section of `.agents/architecture.md` says when a file-local helper or a named widget is warranted. - Every icon lives in `lib/icons/`, never the Material `Icons` font: reuse or add a glyph in `AppGlyphs` and show it with `GlyphIcon`, or with `AnimatedGlyph` where it fills on selection. Glyphs are outlined, except inside a filled button, where they take `fill: 1`. The Icons section of `.agents/architecture.md` covers shape roles, the stroke, the fill animation, and when to fill. - Modals dim what they cover with the Material 3 scrim (`ColorScheme.modalScrim`, `scrim` at 32%) and never blur it. Every modal brings its own scrim, including one opened from inside another, so do not make a barrier transparent to keep scrims from stacking. - A sheet's size belongs to its route, never to its content or call site: a bottom sheet rests at `SheetProps.detents`, and a side sheet is as tall as the window and as wide as `ModalSideSheetRoute` makes it from the window width (`lib/widgets/side_sheet.dart`, pinned by `test/widgets/side_sheet_width_test.dart`). Do not wrap a sheet's content in a fixed width or height to resize one sheet. - The keyboard animates `MediaQuery.viewInsets` every frame. Read MediaQuery by aspect (`paddingOf`, `viewInsetsOf`) rather than `MediaQuery.of`, and wrap the page of a new route type in `KeyboardInsetHold`; Keyboard Insets in `.agents/architecture.md` has the reasons. - A page full of images loads them once its route has settled and builds no rows past the viewport until then: `RouteSettledMixin` and `arrivalScrollCacheExtent`, described under Page Arrival in `.agents/architecture.md`. - A page that waits on its data as it arrives shows its illustration alone (`NullStatus` without a label, in a `NullStatusSwitcher`) until all of it is ready, never a skeleton screen; Page Arrival in `.agents/architecture.md` has the rule. - App bar buttons reach `CommonScaffold` as data (`primaryAction`, `iconActions`, `menuItems`) so it can fold them into its overflow menu; App Bar Actions in `.agents/architecture.md` has the rule. - A row's secondary actions open from a context menu, never a trailing more button; a list whose rows have one reorders in a sort mode, any other by a long press on the row. Row Actions And Sort Mode in `.agents/architecture.md` has the rule. - Quick edit belongs only on a page that edits a whole list or section, or one isolated item; never on one that edits a part of something other settings also write. Quick Edit in `.agents/architecture.md` has the rule. - A page or sheet opens on the navigator of the context it comes from, never on the root navigator unless Where A Route Opens in `.agents/architecture.md` allows it. - User-facing text goes through ARB; use `localization` when text changes are non-trivial. - An asynchronous control keeps four things apart: authoritative provider/domain state; display-only state such as a minimum progress duration; tap policy while work or a display hold is active; and failure/disposal cleanup, in `finally` for animations and timers. `CoreStatusButton` and the proxies delay test action are the reference implementations, described under User-Facing Core And Delay Feedback in `.agents/architecture.md`. ## Corner Radii All corner radii come from `lib/common/shape.dart`: a token, a derived value, or a named off-scale value passed to its builders. Never write a bare radius literal at a call site. The scale is picked by the component's **shortest side**. A radius that reads as a soft card at 64 dp tall reads as a pill at 24 and as a square at 400, so one radius everywhere is the wrong kind of consistency. | Token | Value | Shortest side | Use | | --- | --- | --- | --- | | `none` | 0 | - | square edges, and the flat side of a grouped run | | `xs` | 4 | inset blocks | tiles clipped inside an already rounded surface | | `sm` | 8 | up to 48 | chips, thumbs, swatches, small square tiles | | `md` | 16 | up to 64 | interactive chrome: inputs, menus, buttons, popups, FAB | | `lg` | 20 | 64 to 180 | mid-size cards: dashboard tiles, proxy node cards | | `xl` | 24 | full-bleed | anything spanning the whole width: list rows, grouped runs, group headers | | `xxl` | 28 | over 200 | sheets, dialogs, full-screen containers | | `full` | 1000 | - | pills and circles: buttons, tracks, indicators, progress, avatars | - `AppCorner` holds the scale as `double`; `AppRadius` mirrors it as `BorderRadius` with `all`, `top`, and `vertical` builders; `AppShape` mirrors it as `RoundedSuperellipseBorder`, `full` included, plus `circle`, `input`, and the `all`/`top`/`vertical`/`of` builders. Use `AppShape.full` for pills, never `StadiumBorder`; the Corner Radius section of `.agents/rules.md` explains why and lists the superellipse API per layer. - `AppCorner.fit(shortestSide)` snaps to the largest token at or under one third of the shortest side. Use it whenever the size comes from a `LayoutBuilder` or scales with text. - `ThemeData.withAppShapes` in `lib/common/shape.dart` already applies the scale to card, dialog, bottom sheet, snack bar, chip, menu, input, FAB, navigation indicator, progress, and the filled, text, outlined, elevated, and icon button themes. Do not restate those shapes at call sites, and leave `InputDecoration.border` unset so inputs inherit `AppShape.input`. `xl` and `lg` exist because one token cannot serve both size classes. A full-bleed surface is wide and short, so its corner must be larger than its height alone suggests or it stops reading as a card; everything full-bleed shares `xl` (`CommonSelectedListItem`, the profiles card, the outer corners of a grouped run in `DecorationListItem`, the proxy group header in `lib/views/proxies/list.dart`) and does not use `fit()`. This is the one deliberate overshoot of the one-third rule; the value stays under half a standard row so nothing clamps and every full-bleed surface renders the same radius. `lg` is for mid-size cards that are not full-bleed: a proxy node card at `ProxyCardType.min` is only about 64 tall, which caps its radius at 21, so `xl` would break on a setting the user can change at any time while `lg` clears all three heights and the smallest dashboard tile. Outlined inputs use `AppInputBorder`, not `ShapedInputBorder` from `package:material_ui`. The package border subtracts the floating label's notch as a flat band along the top edge, which takes the corner curve with it at any radius from 8 up. `AppInputBorder` clips the notch region and paints the full superellipse through it, as Flutter's own `OutlineInputBorder` does by shortening the arc. It needs no `contentPadding` compensation. Nested radii are derived, never tokens: concentric corners need `outer = inner + inset`, so name the inset and compute the outer value, as `_cardRadius` in `lib/widgets/popup.dart`, `thumbRadius + _kThumbInset` in `lib/widgets/tab.dart`, and the selection ring in `lib/widgets/palette.dart` do. Adding a token for one of these is how a scale grows without bound. A component the scale does not fit keeps its own value instead of growing the scale: name it once in the file and pass it to the `all`/`top`/`vertical` builders, as `_itemShape` in `lib/widgets/sidebar.dart` does with 10, between the chip-sized `sm` and the near-pill `md` on a 40 tall row. Reach for this only once the table and `fit()` are ruled out. ## Verification - A behavior change gets a focused widget test covering rendering states, taps, scrolling, and empty/error states, including the exception path of any async action. Run `flutter analyze` and `flutter test test/widgets/` plus the tests of the touched view. - The scans in `test/lint/` fail on the common UI mistakes and run as part of `flutter test`: an `IconButton` whose icon is an icon needs a `tooltip`; a field that constructs its own controller, notifier, or focus node is released in the same file; a public declaration nothing references is dead. `.agents/rules.md` explains each rule and its allowlist. ## Pitfalls - Do not mutate provider/domain state merely to smooth a transition. Keep presentation holds local and let real errors bypass them immediately. - Do not leave loading animations active when callbacks throw. - Do not manually edit generated localization or provider files.