Item Catalog — UX Baseline References¶

Mapping from each FE page to the chosen-variant React mockup under src/ux-exploration/item-catalog/ (produced by frontend-ux-direction, approved in ui-direction.md § Decisions on 2026-05-21). The action-flow HTML prototypes the UX-direction skill synthesised from are cited only for traceability.

The mockups are the visual + UX baseline, not the spec. They are throwaway: hardcoded strings, no i18n, no Orval, no routing, no permission gating, and no real-component imports for any of the M0-prerequisite stubs. Implementer tickets translate them into real architecture per docs/standards.md and docs/architecture.md. Anything in a mockup that contradicts the BE OpenAPI (openapi/openapi.json) is dropped — those discrepancies are tracked in be-feedback.md.

Page → chosen variant¶

Page	Chosen variant (source of truth for layout)	HTML prototype (background only)	Use as
ItemListPage	`src/ux-exploration/item-catalog/item-list-a.tsx`	`ux-tests/prototypes/action-flow-prototypes/02-production-list.html`, `05-product-catalog.html`	StatsBar above labelled FilterBar above `DataTable` above split-pagination card.
ItemDetailPage	`src/ux-exploration/item-catalog/item-detail-a.tsx`	`ux-tests/prototypes/action-flow-prototypes/11-product-detail.html`, `03-production-order-detail.html`	2-column grid (1fr main + 380 px side rail). Main: three InfoCards (Item information, Inventory parameters, Description & tags). Side rail: Audit + Activity-placeholder.
ItemCreatePage	`src/ux-exploration/item-catalog/item-create-a.tsx`	`ux-tests/prototypes/action-flow-prototypes/12-product-edit.html`	Single-column form with grouped Fieldset cards (Identity / Classification / Inventory / Description & tags). Sticky `<FormActions>` bar at the bottom.
ItemEditPage	`src/ux-exploration/item-catalog/item-edit-a.tsx`	`ux-tests/prototypes/action-flow-prototypes/12-product-edit.html`	Same shell as create-a. Identity fieldset shows code / storage_unit / item_type as disabled inputs with a "Locked fields" badge. Editable fieldsets below per `forms.md` § ItemEditForm. Composite-save dispatch per `docs/standards.md` § Composite Edits.
GroupListPage	`src/ux-exploration/item-catalog/item-group-list-a.tsx`	`ux-tests/prototypes/action-flow-prototypes/13-ingredient-groups.html`	StatsBar + FilterBar + `DataTable` + split pagination, like the item list. Row click routes to dedicated detail page. New / Edit via `<FormDialog>`; Delete via `<ConfirmDialog>`.
GroupDetailPage	`src/ux-exploration/item-catalog/item-group-detail.tsx`	— (layout adapted from `item-detail-a.tsx`)	Header card + 2-column grid. Main: items-in-group `DataTable` + split pagination. Side rail: Group metadata card + Audit card. Edit reuses the same `<ItemGroupForm>` in `<FormDialog>`.
ItemImportPage	`src/ux-exploration/item-catalog/item-import-a.tsx`	— (no HTML prototype; designed during UX-direction phase per IC-UC-06)	Horizontal `<Stepper>` across the top, single panel per step (Download template → Upload file → Review → Confirm). Errors in Step 2 block advancing.

The 7 chosen TSX files plus _stubs.tsx are mounted under the dev-only /ux/item-catalog/... aggregator route — they exist only to support side-by-side review during planning and implementation kick-off. The rejected *-b.tsx variants stay in the folder for reference until the last ticket lands, then the whole src/ux-exploration/item-catalog/ directory is removed (see § Lifecycle).

What to ignore in the mockups¶

These are intentional shortcuts in the prototypes. Implementer tickets must NOT preserve them:

Hardcoded English strings. Replaced by i18n keys per i18n-keys.md. Never hand-write user-facing copy in components.
Hardcoded example data arrays. Replaced by Orval hooks per data-fetching.md. The mockups embed example rows so the layout reads; real pages render from server state.
Inline MISSING_COMPONENT_* stubs from _stubs.tsx. Replaced by either an existing component (cross-checked against src/components/) or an M0 prerequisite ticket. See fe-plan.md § Component prerequisites for the validated list.
Inline <table> markup with local Th / Td / ActionBtn helpers. Replaced by the reusable <DataTable> (M0 prereq #1) per fe-plan.md § Component prerequisites and docs/standards.md. List pages pass a typed columns array, not row markup.
No <RequirePermission> / <PermissionGate> wrapping. Real implementations gate per pages.md § Permission tables and docs/standards.md § Permission-Gated UI.
No routing, no URL-bound search params. Real implementations read filter state from URL via Route.useSearch() per routes.md § Search-param schemas.
AppShell is wrapped on the dev /ux/... aggregator route only. Real pages are mounted under src/routes/_auth/catalog/... and the shell is owned by the route tree, not the page component.
CSS-variable colour references in the mockups for StatusBadge variants (--status-success-*, --status-warning-*, etc.) that aren't currently defined in src/styles/tokens.css — ui-direction.md § Cross-cutting decisions records this as a separate foundation concern. Implementer tickets use StatusBadge as-is; the badge's known limitation is fixed in a foundation ticket, not in this module.
Any field or action the BE OpenAPI does not expose. Cross-checked in Phase 1.5 of planning and tracked in be-feedback.md. Implementer tickets do not ship unsupported controls. The is_system flag is consumed for read-only state on the detail page but no FE action ever modifies it.
Responsive treatment. The chosen-variant TSX files were authored before the responsive policy in ../../responsive-strategy.md shipped, so they are desktop-only baselines — no <md/<sm adaptation, no <DesktopOnly> gate, no <DataCardList> swap, no Sheet-mode FilterBar. Implementer tickets must still adapt their real components to the per-page bucket declared in pages.md § Responsive buckets, leaning on the M8 RF foundation primitives (useBreakpoint, <DataCardList>, <FilterBar>-as-Sheet, Stepper vertical-at-md, FormActions reverse-stack, …). The TSX baselines themselves are refreshed with responsive overlays by GRF-114; until that ships, prefer the bucket table in pages.md over the TSX when the two disagree on phone behaviour.

Responsive variants (pending GRF-114)¶

The chosen-variant TSX files under src/ux-exploration/item-catalog/ synthesise layout, sections, and control set at desktop widths only. The per-page responsive contract lives in ./pages.md § Responsive buckets — that table is authoritative until GRF-114 updates the TSX prototypes to demo the responsive treatment side-by-side at sm / md / lg.

Per-page expectations the implementing tickets need to deliver even before the TSX is refreshed:

Page	Responsive deviation from current TSX
ItemListPage	Real implementation swaps `<DataTable>` ↔ `<DataCardList>` at `<md` and collapses `<FilterBar>` into a `Sheet` trigger at `<md`. TSX renders neither.
ItemDetailPage	2-col grid collapses to single column at `<md`; the side rail stacks below. TSX leaves the grid hard-coded at all widths.
ItemCreatePage	`<FormActions>` reverse-stacks with primary on top + full-width at `<sm`. TSX hard-codes a horizontal row.
ItemEditPage	Same as create plus locked-fieldset hint remains anchored to the top of the Identity card after stacking. TSX shows the row layout only.
GroupListPage	Same list-page swaps as ItemListPage. `<FormDialog>` for create/edit goes fullscreen at `<sm`. TSX renders the dialog modal at every width.
GroupDetailPage	Items-in-group `<DataTable>` swaps to `<DataCardList>` at `<md`; metadata + audit cards stack. TSX hard-codes the grid.
ItemImportPage	Real implementation renders `<DesktopOnly>` at `<sm` with continue-anyway; once continued, `<Stepper>` renders vertical at `<md`, `<FileDropzone>` swaps to tap-to-browse on touch, `<ImportErrorList>` rows stack. TSX is horizontal-only and has no soft-gate.

Lifecycle¶

The src/ux-exploration/item-catalog/ files exist as a visual baseline only until the chosen variants have been translated into real features/item-catalog/ code. Once every page in this module has shipped per its tickets, the worktree that lands the last page deletes src/ux-exploration/item-catalog/ and removes the corresponding rows from the /ux/... aggregator route under src/routes/_dev/.

The planner never modifies these files. The chosen variants are read structurally (sections, controls, imports) during planning; the rejected *-b.tsx variants are referenced only for traceability and are not opened during implementation.