ADR 0009 — One variant API for every inventory component

• Status: Accepted (2026-10-23)
• Binds: G6.2, north star (one inventory, instantiation + override props), invariants 4, 5, 6
• Research: RQ5 (cva pick) · Structure reference (read only): HMS PageContainer.tsx + PageContainer.spec.md variant selector shape

Context

HMS had 11 page-chrome approaches and 61 PageContainer-exempt comments with 9+ reasons (routes.md I1). Each component invented its own prop names for look, state and size. Devs cannot pick from one inventory if every entry speaks a different prop language.

Decision

1. Four style axes, same names everywhere (built with cva)

• Variant classes map only to semantic utilities and --token-* values (invariant 4). No raw colour, px, rem or ms in a variant definition.
• density defaults from UnifiedSettingsProvider (was SettingsProvider, ADR 0014 addendum); a prop overrides it for one instance.
• mode never changes the variant; it changes behaviour and state visuals.
• A component that has no meaning for an axis does not declare it (no dead props).

2. Inventory props = { instantiation, overrides }

Every inventory entry (@/inventory, task 022) exposes:

type InventoryProps<I, O> = {  instantiation: I;          // required, typed: what this instance IS (entity, columns, i18n namespace, data source key)  overrides?: Partial<O>;    // optional, typed: per-instance deviations (variant, mode, size, density, slots, labels)};

• instantiation is data and wiring. overrides is look and local behaviour. The axes of §1 live in O.
• Strings in either are i18n keys, never text (Cardinal #23).
• Pages compose only inventory entries with these two props (invariant 5). A page that needs a deviation not expressible in overrides extends the entry's O type — it does not fork the component (invariant 6).
• SitePage* and PortalPage* mirrors share the same I/O types (BRIEF quality bar).

3. The role gate is not a variant

PortalPage gates the role once (invariant 14, HMS I14 anti-pattern). Role is never a prop axis; layouts resolve org + session only.

Rejected alternative

• tailwind-variants (RQ5): rejected — a second variant dialect beside shadcn's cva.
• Free-form props per component (HMS): rejected — the source of I1 / I13 drift.
• Exempt comments for components that do not fit: rejected — extend O instead.

Consequences

• One docs template per entry: instantiation table, overrides table, axes, gallery link (G10.2).
• The inventory registry spec can check every entry declares instantiation and that site/portal mirrors share types.

Check

! rg -n 'PageContainer-exempt|tailwind-variants' ddx-web/srcrg -n 'cva\(' ddx-web/src/components | head

• ddx-documentation — dudoxx-web-boot

adr/

• ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides
• ADR 0002 — Auth: better-auth 1.7 in ddx-api
• ADR 0003 — Route shape: org slug, role, [entity]/[id], ?view=
• ADR 0004 — Database split: one Postgres 18 instance, six databases
• ADR 0005 — Frameworks and the approved dependency table
• ADR 0006 — API clients come from one factory
• ADR 0007 — Typed service container (DI / IoC)
• ADR 0008 — Singleton scope: what may live at module level
• ADR 0009 — One variant API for every inventory component
• ADR 0010 — Media path: presigned URLs from ddx-api after the org check
• ADR 0011 — Media proxy: MinIO only through ddx-api
• ADR 0012 — Density names: compact | cosy | large
• ADR 0013 — Platform super-admin acts as org-admin of the target org
• ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api
• ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain
• ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue
• ADR 0017 — Layered BFF: one route table, route classes, read models
• ADR 0018 — Cluster node registry, node identity, hot plug
• ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read
• Debug overlay

deploy/

• Deploy runbook — dudoxx-web-boot
• Entity kernel — guide
• Feature map — what each role can do
• Component inventory
• Naming constitution — dudoxx-web-boot
• Observability — one log layout, one key set
• Pattern reference — P1-P23 and groups A-K
• Port map — dudoxx-web-boot

research/

• RQ1 — Which release is "latest", and does it differ from the canon?
• RQ10 — SSE through the Next.js BFF route handler (desk half)
• RQ11 — Dev latency baseline: cold compile per route + next-server RSS
• RQ2 — Route group or dynamic org slug?
• RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix
• RQ4 — Separate databases or separate schemas?
• RQ5 — Which frameworks beyond shadcn earn a place?
• RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?
• RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?
• RQ8 — Media path: presigned URLs vs streaming through the BFF
• Template triage — create-nextjs code in ddx-web
• Settings — guide
• Local setup — dudoxx-web-boot
• Shell tree — SiteShell and PortalShell
• SSE event catalog
• Version pins — dudoxx-web-boot