banhaten 0.1.2 → 0.2.0

package/docs/design-system/design-system-test-missing-items.md

@@ -0,0 +1,368 @@
+# Design System Test Missing Items
+
+Last updated: 2026-06-13
+
+This inventory is generated from the current background design-system tests. It mirrors the playground Missing mode and includes both red true-missing marks and purple approximation marks.
+
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[].gaps`).
+
+Total background tests: 24
+Total marked items: 132
+True missing items: 64
+Approximation marks: 68
+
+## How To Read This
+
+- **Date logged** is the date this documentation snapshot was generated.
+- **Mark** is `Red` for a true missing reusable item and `Purple` for a close local composition, token, icon, or image approximation.
+- **Reference source** is the uploaded/supplied reference image used for that background test.
+- **Item source** is the gap list in `playground/src/app/backgrounds/registry.ts`.
+- **Alternative / closest look** records the nearest Banhaten primitive, component, token, or placeholder available today.
+
+## Accounting Workspace Setup Background
+
+Reference source: `playground/public/references/accounting-workspace-setup-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[accounting-workspace-setup].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | onboarding workspace shell | Closest look: a local app shell using raised surfaces, border/radius/shadow tokens, and background gradients until an onboarding shell pattern exists. |
+| 2026-06-07 | Purple | component | step progress indicator | Closest look: Steps or ButtonGroup-style primitives with tokenized pill bars. |
+| 2026-06-07 | Purple | layout/composition pattern | setup form step card | Closest look: actual Banhaten Input, Select, Textarea, RadioCard, and Button primitives inside a local raised form layout. |
+| 2026-06-07 | Purple | layout/composition pattern | inferred cropped continuation | Closest look: infer the cropped lower setup fields with Banhaten Select, RadioCard, and Button primitives. |
+
+## Debt Payoff Background
+
+Reference source: `playground/public/references/debt-payoff-background.svg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[debt-payoff].gaps`)
+Date logged: 2026-06-12
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-12 | Red | layout/composition pattern | finance workspace shell | Closest look: local planning workspace shell using Banhaten surfaces, border, radius, shadow, sidebar, toolbar, Table, Button, Input, Badge, and Progress primitives. |
+| 2026-06-12 | Red | component | planning sidebar navigation | Closest look: grouped Menu-style rows with Input search, Badge counts, icon slots, selected state, and Button actions until an app-sidebar component exists. |
+| 2026-06-12 | Purple | component | debt table and pagination | Closest look: Banhaten Table, Input, Badge, typography, spacing, border, and compact Pagination-like controls composed locally. |
+| 2026-06-12 | Purple | component | strategy comparison controls | Closest look: RadioCard or ButtonGroup-style choice rows, Toggle, Button, Badge, and tokenized summary cards composed locally. |
+| 2026-06-12 | Purple | icon asset | finance brand and navigation glyphs | Closest look: Lucide or CSS placeholders inside tokenized icon wrappers until exact finance/product assets are supplied. |
+
+## AI Growth Marketing Background
+
+Reference source: `playground/public/references/ai-growth-marketing-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[ai-growth-marketing].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Purple | image asset | scenic meadow backdrop | Closest look: a tokenized CSS scenic approximation until a final raster background asset exists. |
+| 2026-06-07 | Red | layout/composition pattern | floating report dashboard scene | Closest look: a local absolute-positioned app shell using Banhaten dark surfaces, borders, spacing, radius, and shadow tokens. |
+| 2026-06-07 | Red | component | report sidebar navigation | Closest look: Menu, Badge, Avatar, Button, typography, and icon wrappers composed into a sidebar until an app-sidebar component exists. |
+| 2026-06-07 | Red | component | AI report dashboard cards | Closest look: tokenized surfaces plus local chart/table compositions until dashboard cards and chart components are first-class. |
+| 2026-06-07 | Purple | icon asset | AI provider and company marks | Closest look: Lucide or CSS placeholders inside tokenized icon wrappers until the exact brand/provider assets are added. |
+| 2026-06-07 | Purple | token | near-black overlay and chart glow | Closest look: existing dark theme surfaces, subtle borders, brand/sky accents, and component shadow tokens. |
+
+## Benefits Enrollment Background
+
+Reference source: `playground/public/references/benefits-enrollment-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[benefits-enrollment].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | angled benefits screen shell | Closest look: local rotated stage using Banhaten background, border, radius, and shadow tokens. |
+| 2026-06-07 | Red | component | enrollment progress header | Closest look: Steps-style composition with tokenized markers, connector lines, and label typography. |
+| 2026-06-07 | Red | component | personal details review card | Closest look: raised surface, header row, Button action, and nested definition-list panel composed with Banhaten tokens. |
+| 2026-06-12 | Purple | component | definition-list review rows | Closest look: Banhaten Attribute rows inside a tokenized review card surface. |
+
+## CRM Intelligence Background
+
+Reference source: `playground/public/references/crm-intelligence-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[crm-intelligence].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | background shell | Closest look: layout primitives with background, border, radius, and shadow tokens; no reusable background shell yet. |
+| 2026-06-07 | Red | layout/composition pattern | deal card | Closest look: card-like surface composed from Avatar, Badge, Button, typography, and spacing tokens. |
+| 2026-06-07 | Red | component | icon tile | Closest look: icon-only Button or a small Badge/Icon wrapper using radius, border, and background tokens. |
+| 2026-06-07 | Purple | icon asset | brand logo mark | Closest look: Lucide/CSS placeholder in a tokenized icon tile until the brand asset exists. |
+| 2026-06-07 | Red | component | media upload | Closest look: FileUpload expanded component, or Input/Button composition with dashed border tokens. |
+| 2026-06-07 | Red | component | segmented control | Closest look: Tabs segment variant or ButtonGroup with selected state. |
+| 2026-06-12 | Purple | component | switch | Closest look: Banhaten Toggle or ToggleField with local sizing around the reference layout. |
+| 2026-06-07 | Purple | image asset | meeting thumbnails | Closest look: Avatar/Image placeholders plus Badge or Tag for service/status marks. |
+| 2026-06-07 | Red | layout/composition pattern | checklist panel | Closest look: Checkbox or CheckboxCard rows inside a tokenized surface. |
+
+## Model Overview Background
+
+Reference source: `playground/public/references/model-overview-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[model-overview].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | modal-over-background scene | Closest look: centered raised surface with local overlay/backdrop CSS, radius, and shadow tokens. |
+| 2026-06-07 | Red | component | model overview detail panel | Closest look: PageHeader, Badge, Button, Table/list rows, and tokenized surface. |
+| 2026-06-07 | Purple | icon asset | Mistral logo | Closest look: token-colored icon tile or CSS mark until the exact provider asset is added. |
+| 2026-06-07 | Purple | image asset | blurred hero and provider list | Closest look: background image slot or Avatar/icon placeholders inside a muted surface. |
+| 2026-06-07 | Purple | token | backdrop blur and modal elevation | Closest look: shadow-component-default plus local backdrop blur; needs a named elevation token. |
+
+## MCP Settings Background
+
+Reference source: `playground/public/references/mcp-settings-background.svg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[mcp-settings].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | settings-page shell | Closest look: app shell composed from Menu, Input, Button, Avatar, and surface tokens. |
+| 2026-06-07 | Red | component | connect-tool picker | Closest look: RadioCard or CheckboxCard variant with icon, label, and selected state. |
+| 2026-06-07 | Red | component | numbered setup steps | Closest look: Steps component plus code/card surface composition. |
+| 2026-06-07 | Purple | icon asset | tool and navigation icons | Closest look: Lucide icons inside tokenized icon wrappers. |
+| 2026-06-07 | Purple | image asset | account avatar badge | Closest look: Avatar with nested Badge or icon overlay. |
+| 2026-06-07 | Purple | token | reference shell border softness | Closest look: border-subtle, large radius, and component shadow. |
+
+## Inference Providers Background
+
+Reference source: `playground/public/references/inference-providers-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[inference-providers].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | inference settings workspace shell | Closest look: app-shell composition using raised surfaces, subtle borders, large radius, side rail, tabs, and typography tokens. |
+| 2026-06-07 | Red | component | expandable provider configuration table | Closest look: local table grid with Badge, Input, status-dot, and typography primitives until expanded rows are supported by Table. |
+| 2026-06-12 | Purple | component | switch control | Closest look: Banhaten Toggle or ToggleField inside the provider table rows. |
+| 2026-06-07 | Purple | layout/composition pattern | top navigation and side rail | Closest look: composed breadcrumb, tabs, avatar, icon buttons, and side rail using current Banhaten primitives. |
+| 2026-06-07 | Purple | icon asset | provider brand marks | Closest look: Lucide or CSS placeholders inside tokenized icon slots until exact provider marks are supplied. |
+| 2026-06-07 | Purple | component | status dots and settings fields | Closest look: Badge, Input, small dot indicators, and text rows composed with existing spacing and color tokens. |
+
+## Profile Menu Background
+
+Reference source: `playground/public/references/profile-menu-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[profile-menu].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | oversized profile menu scene | Closest look: Menu inside a raised surface, with duplicated shells kept local to the background. |
+| 2026-06-07 | Purple | token | large radius and reflection elevation | Closest look: largest radius tokens plus shadow-component-default; needs a larger elevation token. |
+| 2026-06-07 | Red | component | account header row | Closest look: Avatar, typography, and Badge inside a MenuLabel/header surface. |
+| 2026-06-07 | Red | component | jumbo menu item with accessories | Closest look: MenuItem with Avatar, Badge, and action slots; needs an oversized variant. |
+| 2026-06-07 | Purple | icon asset | reference icon family | Closest look: Lucide icons in MenuItemIcon slots. |
+| 2026-06-07 | Purple | image asset | avatar and hand cursor | Closest look: Avatar fallback plus Pointer icon placeholder. |
+
+## Investor Profile Background
+
+Reference source: `playground/public/references/investor-profile-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[investor-profile].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | investor profile scene | Closest look: raised card-like surface using Avatar, Button, Badge, and typography tokens. |
+| 2026-06-07 | Purple | token | large card radius and soft elevation | Closest look: largest radius tokens and shadow-component-default. |
+| 2026-06-07 | Red | component | profile summary card | Closest look: definition list inside a raised/subtle surface with Badge or icon wrappers. |
+| 2026-06-07 | Purple | image asset | avatar artwork | Closest look: Avatar fallback with token colors. |
+| 2026-06-07 | Purple | icon asset | verification and brand marks | Closest look: Badge/Icon wrappers or Lucide placeholders. |
+
+## Compose Email Background
+
+Reference source: `playground/public/references/compose-email-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[email-compose].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | compose modal shell | Closest look: raised modal surface with Input, Textarea, and Button primitives. |
+| 2026-06-07 | Red | component | person chip | Closest look: Tag or Badge composed with Avatar and status icon. |
+| 2026-06-07 | Purple | image asset | contact avatars | Closest look: Avatar fallback until final images are provided. |
+| 2026-06-07 | Purple | icon asset | verified badge and model mark | Closest look: Badge/Icon wrapper with Lucide or CSS mark. |
+| 2026-06-07 | Red | component | inline template variable | Closest look: Tag or Badge styled as an inline chip. |
+| 2026-06-07 | Purple | token | large composer radius/elevation | Closest look: radius-3xl/6xl and shadow-component-default. |
+| 2026-06-07 | Red | component | split send button | Closest look: ButtonGroup or adjacent Button plus icon Button. |
+
+## Investment Savings Background
+
+Reference source: `playground/public/references/investment-savings-background.png`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[investment-savings].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Purple | layout/composition pattern | purple investment calculator card | Closest look: a local surface composition using Badge, typography, divider, spacing, radius, and active brand tokens. |
+| 2026-06-09 | Purple | component | purple amount range selector | Resolved with reusable Banhaten Slider pill variant using the brand tone, grip thumb, and tick marks. |
+
+## Transaction Details Background
+
+Reference source: `playground/public/references/transaction-details-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[transaction-details].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | component | transaction detail sheet | Closest look: a raised surface composed from Button, Badge, Avatar, typography, spacing, radius, and shadow tokens until a reusable transaction-detail component exists. |
+| 2026-06-07 | Purple | layout/composition pattern | purple composed detail pieces | Closest look: existing primitives and local tokenized wrappers. Purple marks identify pieces that are acceptable compositions, not red missing components. |
+
+## Refund Simulation Background
+
+Reference source: `playground/public/references/refund-simulation-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[refund-simulation].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Purple | token | warm canvas and large elevation | Closest look: grouped background, large radius, and shadow-component-default. |
+| 2026-06-07 | Red | layout/composition pattern | simulation conversation shell | Closest look: raised surface with Avatar rows, typography, and spacing tokens. |
+| 2026-06-07 | Red | component | refund progress timeline | Closest look: Timeline or Steps with success icons and connector rail. |
+| 2026-06-07 | Red | component | customer and agent message rows | Closest look: Avatar and text stack rows inside a conversation surface. |
+| 2026-06-07 | Purple | icon asset | customer identity glyph | Closest look: Avatar fallback with User icon. |
+| 2026-06-07 | Purple | image asset | agent blue mosaic avatar | Closest look: Avatar fallback with tokenized CSS pattern. |
+
+## Stripe Demo Account Background
+
+Reference source: `playground/public/references/stripe-demo-account-background.png`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[stripe-demo-account].gaps`)
+Date logged: 2026-06-13
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-13 | Red | layout/composition pattern | payments dashboard shell | Closest look: local dashboard shell using Banhaten raised surfaces, border, radius, shadow, sidebar, Button, Input, and table-like spacing. |
+| 2026-06-13 | Red | component | payments sidebar navigation | Closest look: Menu-style rows with Input search, icon slots, selected state, and footer utility rows until an app-sidebar primitive exists. |
+| 2026-06-13 | Purple | component | summary KPI cards | Closest look: Card-like raised surfaces with Banhaten typography, border, radius, and compact spacing. |
+| 2026-06-13 | Purple | component | metric table cards | Closest look: local card composition with Button icon actions, avatar initials, and compact table rows using Banhaten tokens. |
+| 2026-06-13 | Purple | component | sales tabs and table | Closest look: Tabs-like underline navigation plus table/list rows with Banhaten spacing, dividers, and typography. |
+| 2026-06-13 | Purple | image asset | Stripe mark and account avatar | Closest look: CSS mark and Avatar-style placeholder using token colors until the exact Stripe and account image assets are supplied. |
+
+## Recent Orders Background
+
+Reference source: `playground/public/references/recent-orders-background.png`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[recent-orders].gaps`)
+Date logged: 2026-06-13
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-13 | Red | layout/composition pattern | orders dashboard workspace shell | Closest look: local orders workspace shell using Banhaten raised/subtle surfaces, border, radius, top navigation, search Input, Button, Badge, and layout spacing tokens. |
+| 2026-06-13 | Purple | component | orders intro and stat cards | Closest look: Card-like tokenized surfaces with Button, typography, progress-bar CSS, border, radius, and brand tokens. |
+| 2026-06-13 | Purple | component | orders table controls and rows | Closest look: ButtonGroup, Button, Badge, typography, dividers, and table-like grid rows composed locally until a richer orders table pattern exists. |
+| 2026-06-13 | Red | component | order detail panel | Closest look: raised detail surface with Button actions, definition rows, dividers, payment row, and local two-column address layout. |
+| 2026-06-13 | Purple | image asset | brand mark and customer avatar | Closest look: Lucide/CSS brand mark and Avatar fallback until exact product and customer image assets are supplied. |
+
+## Shipment List Background
+
+Reference source: `playground/public/references/shipment-list-background.png`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[shipment-list].gaps`)
+Date logged: 2026-06-13
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-13 | Red | layout/composition pattern | shipment management workspace shell | Closest look: local operational app shell using Banhaten raised surfaces, border, radius, shadow, sidebar, Button, and table-like spacing. |
+| 2026-06-13 | Red | component | shipment sidebar navigation | Closest look: Menu-style grouped rows, count Badge, typography, and icon slots until app-sidebar navigation becomes a reusable component. |
+| 2026-06-13 | Purple | icon asset | carrier brand mark | Closest look: token-colored CSS icon placeholder inside a Badge-like chip until the exact carrier mark is supplied. |
+
+## Delivery Tracking Background
+
+Reference source: `playground/public/references/delivery-tracking-background.png`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[delivery-tracking].gaps`)
+Date logged: 2026-06-13
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-13 | Red | layout/composition pattern | delivery tracking dashboard shell | Closest look: local consumer delivery page shell using Banhaten raised surfaces, borders, radius, spacing, shadow, Button, Badge, Avatar, and icon primitives. |
+| 2026-06-13 | Purple | image asset | map tile and delivery pin visual | Closest look: tokenized CSS map layers plus a Lucide MapPin inside a rounded image/card slot. |
+| 2026-06-13 | Purple | component | shipment detail card stack | Closest look: Card-like surfaces with Banhaten typography, Badge, Button, icon rows, dividers, and local item/totals/address compositions. |
+| 2026-06-13 | Purple | component | notification toggle stack | Closest look: Toggle-like switches and preference rows composed with Banhaten radius, accent colors, spacing, and typography tokens. |
+| 2026-06-13 | Red | component | consumer delivery timeline | Closest look: Timeline/Steps-style local composition with large icon nodes, status Badge, connector rail, and active-state halo. |
+| 2026-06-13 | Red | component | delivery rating control | Closest look: Lucide stars with Banhaten accent colors until a reusable rating input/display component is added. |
+| 2026-06-13 | Purple | image asset | courier avatar asset | Closest look: Avatar fallback treatment until a final courier portrait is available. |
+
+## School Assignments Background
+
+Reference source: `playground/public/references/school-assignments-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[school-assignments].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | school app workspace shell | Closest look: dark app shell using Menu, Input, Button, Avatar, and Table. |
+| 2026-06-07 | Purple | token | warm dark backdrop and oversized shadow | Closest look: dark theme background tokens plus component shadow. |
+| 2026-06-07 | Red | component | class switcher and student roster | Closest look: Select/Menu, Input, and Avatar list composition. |
+| 2026-06-07 | Red | component | assignments table | Closest look: Table component with Badge and Button/Icon cells. |
+| 2026-06-07 | Purple | icon asset | school, subject, and assignment glyphs | Closest look: Lucide icons in Badge, Menu, or icon wrappers. |
+| 2026-06-07 | Purple | image asset | teacher avatar | Closest look: Avatar fallback until the portrait asset exists. |
+
+## Audit Log Background
+
+Reference source: `playground/public/references/audit-log-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[audit-log].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | audit browser workspace shell | Closest look: app shell composed from tokenized chrome, sidebar, table area, backdrop, and modal surfaces. |
+| 2026-06-07 | Red | component | audit sidebar navigation | Closest look: Menu-style rows grouped with section labels, icon slots, and selected state. |
+| 2026-06-07 | Red | component | audit activity table | Closest look: Table/list rows composed with Checkbox, Badge, Avatar, Input, Button, and Pagination-like controls. |
+| 2026-06-07 | Red | component | log details modal | Closest look: raised surface using Button, Badge, Avatar, typography, dividers, and local definition-table rows. |
+| 2026-06-07 | Purple | icon asset | audit chrome and sidebar glyphs | Closest look: Lucide icons and CSS browser marks in tokenized icon wrappers. |
+| 2026-06-07 | Purple | image asset | audit author avatars | Closest look: Avatar fallback until production portrait assets are supplied. |
+| 2026-06-07 | Purple | token | audit blur and elevation | Closest look: background, border, radius, opacity, and component-shadow tokens plus local backdrop blur. |
+
+## Order Shipment Timeline Background
+
+Reference source: `playground/public/references/order-shipment-timeline-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[order-shipment-timeline].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | cropped order workspace shell | Closest look: app shell composed from Table, Badge, Button, Textarea, and Timeline. |
+| 2026-06-07 | Red | component | collapsible order panels | Closest look: Accordion with Table and Badge content. |
+| 2026-06-07 | Red | component | shipment selector cards | Closest look: RadioCard or ButtonGroup selected cards. |
+| 2026-06-07 | Red | component | note composer | Closest look: Textarea plus icon Button composition. |
+| 2026-06-07 | Red | layout/composition pattern | vertical shipment timeline | Closest look: Timeline component with custom order-fulfillment rows. |
+| 2026-06-07 | Purple | icon asset | carrier mark | Closest look: icon/logo placeholder in Badge or icon wrapper. |
+| 2026-06-07 | Purple | image asset | document preview | Closest look: FileUpload or attachment tile placeholder. |
+| 2026-06-07 | Purple | token | soft viewport fade | Closest look: local gradient overlay using background tokens. |
+
+## Data Source Browser Background
+
+Reference source: `playground/public/references/data-source-browser-background.jpg`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[data-source-browser].gaps`)
+Date logged: 2026-06-07
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-07 | Red | layout/composition pattern | desktop browser and app-shell scene | Closest look: app shell with toolbar/sidebar surfaces and background tokens. |
+| 2026-06-07 | Red | component | sidebar navigation with pinned list | Closest look: Menu, Input, and Badge rows; needs sidebar navigation. |
+| 2026-06-07 | Red | component | tab strip and recent menu | Closest look: Tabs plus Menu composition. |
+| 2026-06-07 | Purple | icon asset | Programa and vendor glyphs | Closest look: Lucide/CSS icons in tokenized wrappers. |
+| 2026-06-07 | Purple | image asset | Snowflake logo | Closest look: icon tile placeholder until the vendor logo asset exists. |
+| 2026-06-07 | Purple | token | browser chrome radius and elevation | Closest look: large radius plus shadow-component-default. |
+| 2026-06-07 | Red | component | dataset list panel | Closest look: Checkbox rows inside a Table/list surface. |
+
+## MarcoHR People Background
+
+Reference source: `playground/public/references/marcohr-people-background.png`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[marcohr-people].gaps`)
+Date logged: 2026-06-13
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-13 | Red | layout/composition pattern | HR workspace shell | Closest look: assemble the scene from Banhaten surfaces, spacing, radius, shadow, and existing primitives. |
+| 2026-06-13 | Red | component | HR sidebar navigation | Closest look: compose from Banhaten primitives and tokens until this becomes a first-class component. |
+| 2026-06-13 | Purple | component | people status tabs and controls | Closest look: compose from Banhaten primitives and tokens until this becomes a first-class component. |
+| 2026-06-13 | Purple | component | employee policy table | Closest look: compose from Banhaten primitives and tokens until this becomes a first-class component. |
+| 2026-06-13 | Purple | image asset | MarcoHR logo mark | Closest look: use Avatar, image slots, or tokenized placeholders until the final raster/vector asset exists. |
+
+## People Add Member Background
+
+Reference source: `playground/public/references/people-add-member-background.png`
+Item source: `playground/src/app/backgrounds/registry.ts` (`backgroundTests[people-add-member].gaps`)
+Date logged: 2026-06-13
+
+| Date logged | Mark | Type | Item | Alternative / closest look |
+| --- | --- | --- | --- | --- |
+| 2026-06-13 | Red | layout/composition pattern | HR workspace shell | Closest look: assemble the scene from Banhaten surfaces, spacing, radius, shadow, and existing primitives. |
+| 2026-06-13 | Red | component | HR sidebar navigation | Closest look: compose from Banhaten primitives and tokens until this becomes a first-class component. |
+| 2026-06-13 | Purple | component | people table with status rows | Closest look: compose from Banhaten primitives and tokens until this becomes a first-class component. |
+| 2026-06-13 | Purple | component | add-member side panel | Closest look: compose from Banhaten primitives and tokens until this becomes a first-class component. |
+| 2026-06-13 | Purple | component | worker-type radio stack | Closest look: compose from Banhaten primitives and tokens until this becomes a first-class component. |

package/docs/design-system/direction-and-localization.md

@@ -0,0 +1,23 @@
+# Direction and Localization
+
+Banhaten is Arabic and English-first, but text direction and language are separate contracts. Components resolve direction from an explicit `dir`, `DirectionProvider`, the nearest valid `[dir]` ancestor, or the document root—in that order. Direction changes layout, icon mirroring, and keyboard geometry; it never selects translated UI or accessibility copy.
+
+Use a request-known direction provider for server rendering so the server markup, hydration snapshot, and first paint agree:
+
+```tsx
+import { DirectionProvider } from "@/hooks/use-direction"
+import {
+  arabicPaginationMessages,
+  Pagination,
+} from "@/components/ui/pagination"
+
+<DirectionProvider dir="rtl">
+  <Pagination messages={arabicPaginationMessages} />
+</DirectionProvider>
+```
+
+`DirectionProvider dir="rtl"` works equally well with English, Arabic, Hebrew, Persian, or Urdu. Choose a component's `messages` catalog from the product locale, or pass its direct label props. The exported Arabic catalogs are conveniences, not RTL defaults.
+
+Without an explicit prop or provider, server output uses a stable LTR snapshot. After hydration, one shared subscription per document synchronizes consumers with the nearest nested boundary or document root. This avoids hydration mismatches and per-component document observers. For an RTL first paint, provide the request-known direction during SSR.
+
+Use logical CSS properties (`start`, `end`, `margin-inline`, `padding-inline`) and `dir="auto"` for user-authored copy. Test mixed-language content, punctuation, numbers, icon mirroring, arrow-key behavior, focus order, portal content, and screen-reader names in every supported direction and locale combination.

package/docs/design-system/form-recipes.md

@@ -0,0 +1,73 @@
+# Form Recipes
+
+## Labeled field with validation
+
+Compose `Field`, `FieldLabel`, `FieldControl`, `FieldDescription`, and `FieldError`. Associate the input with its label, keep help text stable, and announce errors only when validation has run.
+
+```tsx
+<Field invalid={Boolean(error)}>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <FieldControl>
+    <Input id="email" state={error ? "error" : "default"} />
+  </FieldControl>
+  <FieldDescription>Use your work email.</FieldDescription>
+  {error ? <FieldError>{error}</FieldError> : null}
+</Field>
+```
+
+## Selection and dates
+
+Use `Select` for a bounded option set, `Autocomplete` for searchable options, and `DatePicker`/`DateRangePicker` for calendar input. Controlled values are preferred when validation, persistence, or URL state owns the result.
+
+Do not emulate a date field with `Input`, a typed `@`, or a generic trailing icon. The Date Picker owns the calendar affordance, keyboard behavior, formatted value, and the same semantic density contract as the surrounding controls.
+
+## Golden recipe: collection filter bar
+
+Use the complete [`CollectionFilterBarDemo`](../../registry/examples/collection-filter-bar-demo.tsx) recipe for collection and search screens. It establishes the approved composition:
+
+- `ToolbarSearch` is full width and uses `shortcutKeys={["Mod", "F"]}` so Command and Control resolve by platform.
+- `DatePicker` owns the From and To fields.
+- `Select` owns Type and Order; `ToolbarSelect` is only a trigger-shaped primitive and is not a complete menu.
+- Every control declares `density="default"`; responsive width classes do not replace component height, padding, radius, or typography.
+- The Reset action uses the same density and resets all composed controls.
+
+```tsx
+<form aria-label="Collection filters" data-recipe="collection-filter-bar">
+  <ToolbarSearch
+    aria-label="Search bookmarks"
+    density="default"
+    shortcutKeys={["Mod", "F"]}
+    width="full"
+  />
+  <div className="flex flex-wrap items-end gap-3">
+    <DatePicker density="default" triggerProps={{ "aria-label": "From" }} />
+    <DatePicker density="default" triggerProps={{ "aria-label": "To" }} />
+    <Select density="default" value="Everything">{/* items */}</Select>
+    <Select density="default" value="Recently bookmarked">{/* items */}</Select>
+    <ToolbarButton density="default" type="reset" variant="link">Reset</ToolbarButton>
+  </div>
+</form>
+```
+
+## Golden recipe: results toolbar
+
+Use the complete [`ResultsToolbarDemo`](../../registry/examples/results-toolbar-demo.tsx) recipe for result counts, layout selection, and batch actions. `SegmentedControl` is the approved content-width primitive for small mutually exclusive values such as cards per row.
+
+```tsx
+<Toolbar aria-label="Bookmark results" layout="split" wrap>
+  <ToolbarText density="default"><strong>5,371</strong>&nbsp;bookmarks</ToolbarText>
+  <ToolbarSection align="end" wrap>
+    <SegmentedControl aria-label="Cards per row" defaultValue="4" density="default">
+      <SegmentedControlLabel>Cards / row</SegmentedControlLabel>
+      {[3, 4, 5, 6].map((count) => (
+        <SegmentedControlItem key={count} value={String(count)}>{count}</SegmentedControlItem>
+      ))}
+    </SegmentedControl>
+    <ToolbarButton density="default" variant="outline">Select</ToolbarButton>
+  </ToolbarSection>
+</Toolbar>
+```
+
+## RTL forms
+
+Set direction at the form or application boundary. Labels and helper text use logical alignment; OTP, calendar, pagination, and selection keyboard movement resolve the inherited direction. Localize labels, placeholders, validation messages, date formatting, and number formatting in the product layer.

package/docs/design-system/gap-promotion-policy.md

@@ -0,0 +1,21 @@
+# Gap promotion policy
+
+Every visual-QA background records missing components, assets, composition patterns, and tokens as structured gap metadata. The promotion report groups recurring needs across backgrounds and flags any normalized need seen in three or more distinct scenarios.
+
+Run:
+
+```sh
+npm --prefix playground run report:gap-promotions
+```
+
+The generated [Gap Promotion Report](./gap-promotion-report.md) is checked during background tests. Common needs are classified automatically; add `promotionKey` to a gap when two differently worded gaps represent the same reusable need or when a heuristic would group unrelated needs.
+
+A candidate does not automatically become a component. Promotion requires:
+
+1. Evidence from at least three backgrounds.
+2. A smallest-stable API and explicit fit/avoid guidance.
+3. Semantic density, state, accessibility, and RTL contracts where applicable.
+4. Migration of at least one real background away from its local fallback.
+5. Behavior and visual tests before resolved gap metadata is removed.
+
+The first application of this policy produced `SegmentedControl`, migrated the CRM Intelligence background to the shared primitive, and removed its former local segmented-control gap.