Enforce shared WebUI primitive adoption

2026-08-18 10:42:55 +02:00
parent 5e9234d4b6
commit 5efb0eea6f
4 changed files with 267 additions and 4 deletions
@@ -0,0 +1,52 @@
+# Shared WebUI Primitive Inventory
+
+This 2026-08-18 inventory records the implementation state after the first
+product-wide toolbar, grid, form-section, and dialog-anatomy migration. It is
+evidence for prioritization, not a substitute for the normative
+[interface pattern language](../architecture/INTERFACE_PATTERN_LANGUAGE.md).
+
+## Implemented And Enforced
+
+| Contract | Adoption evidence | Ownership now enforced |
+| --- | ---: | --- |
+| `ActionToolbar` and groups | 39 source files | Raw module-prefixed toolbar elements and local toolbar component definitions are rejected. |
+| `ContentGrid` | 15 source files | Former `dashboard-grid` and `settings-grid` wrappers are rejected. |
+| `FormGrid` and `FormLayout` | 53 source files | Former `form-grid` and `admin-form-grid` wrappers are rejected; equal-column dialog and editor grids were migrated even when they had module-prefixed names. |
+| `FormSection` | 2 representative source files | The reusable section API, variants, responsive action placement, and heading anatomy are Core-owned; broader adoption is incremental. |
+| `DialogActions` | Every Core `Dialog` footer | Footer wrapping and alignment are no longer repeated by consumers. |
+| `DialogForm` | 6 source files | Raw `*-dialog-form` form wrappers are rejected. |
+| `DialogSection` | 6 source files | Repeated dialog field/content grouping is available as a shared primitive. |
+
+`tools/checks/check-shared-webui-primitives.py` verifies Core exports and
+ownership, representative consumers, the absence of the retired raw anatomy,
+and composition of every `Dialog` footer through `DialogActions`.
+
+## Remaining Promotion Candidates
+
+The post-migration scan found 101 uses of 30 non-Core grid class names across
+54 files. Most are intentionally domain-specific; repeated groups identify the
+next useful primitives:
+
+| Priority | Remaining pattern | Evidence | Proposed contract |
+| --- | --- | ---: | --- |
+| 1 | Metric-card groups | `metric-grid`: 29 uses in 25 files | `MetricGrid` or `MetricGroup` owning 1–4/auto-fit columns, compact spacing, inset mode, and narrow stacking around the existing `MetricCard`. |
+| 2 | Property/description lists | `admin-details-grid`: 13 uses in 11 files | Semantic `DescriptionList` with compact/default density, 1–2 columns, wrapping, and narrow collapse. |
+| 3 | Assignment/picker groups | `admin-assignment-grid`: 5 uses in 4 files | A selection/assignment layout only after its list, search, empty, and permission variants are compared; plain geometry can already use `ContentGrid`. |
+| 4 | Filter and search rows | Toolbars are centralized, but filter fields, result counts, bulk selection, and action grouping still vary | `FilterBar` composed from `ActionToolbar`, with an explicit search region, filters, result summary, and bulk actions. |
+| 5 | Dialog sizing exceptions | Dialog consumers still use 62 module class tokens across 53 files; 26 module/Core CSS files contain dialog/modal width declarations needing review | Migrate standard widths to `Dialog size`; retain only documented full-canvas, preview, chooser, and domain-editor exceptions. |
+| 6 | State and collection anatomy | Loading components exist, but empty/error/retry/action placement is not yet one composition | A composable `StatePanel`/`CollectionState` covering empty, recoverable error, permission block, partial result, and next action without hiding domain consequences. |
+
+The other custom grids are mostly bounded domain visualizations or unequal-track
+editors: conflict mappings, import mapping, campaign review facts, charts,
+calendar time views, connector synchronization, records lists, and definition
+editors. They should remain module-owned unless a second domain demonstrates
+the same semantics and interaction contract. A shared primitive should not be
+created merely because two implementations both use CSS Grid.
+
+## Next Audit
+
+The next bounded slice should implement the metric and description-list
+contracts, migrate their consumers, and then classify dialog width declarations
+as standard-size migrations or registered exceptions. After that, compare
+filter/search rows before defining their composition; their accessibility and
+bulk-selection behavior matter more than visual similarity.