banhaten 0.1.2 → 0.1.3

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/icons.md

@@ -0,0 +1,69 @@
+# Icons
+
+The interactive icon explorer is available in the app under the `Icons` section.
+
+## Recommendation Posture
+
+Start the decision with five serious candidates:
+
+- `Lucide`: best default for modern product UI, especially if we want light, consistent, stroke-based icons.
+- `Tabler Icons`: best coverage-first option. It has a huge set, outline/fill coverage, and a familiar 24px grid.
+- `Material Symbols`: best if we want Google-style recognizability and many built-in style axes.
+- `Radix Icons`: best for very dense component UI where 15px icons need to stay crisp.
+- `Phosphor`: best if we want expressive weight control, including thin, bold, fill, and duotone variants.
+
+Keep `Simple Icons` as a separate brand-logo source. It should not be the primary UI icon family.
+
+## Packs To Review
+
+| Pack | Prefix | License | Best for | Variants to compare |
+| --- | --- | --- | --- | --- |
+| Google Material Symbols | `material-symbols` | Apache-2.0 | Google-style UI, broad coverage | Regular, Rounded, Sharp, Outline, Outline Rounded, Outline Sharp |
+| Google Material Icons Classic | `ic` | Apache-2.0 | Existing Material Icons familiarity | Filled/Baseline, Outlined, Rounded, Sharp, Two tone |
+| Material Design Icons by Pictogrammers | `mdi` | Apache-2.0 | Maximum utility coverage | Single broad style |
+| Radix Icons | `radix-icons` | MIT | Dense controls, primitives, menus | Single 15px style |
+| Lucide | `lucide` | ISC | Clean SaaS/product UI | Single outline style |
+| Heroicons | `heroicons` | MIT | Tailwind-friendly apps | Outline 24, Solid 24, Solid 20, Solid 16 |
+| Tabler Icons | `tabler` | MIT | Broad app coverage | Outline, filled where available |
+| Phosphor | `ph` | MIT | Adjustable visual tone | Thin, Light, Regular, Bold, Fill, Duotone |
+| Remix Icon | `ri` | Apache-2.0 | Neutral line/fill system icons | Line, Fill |
+| Bootstrap Icons | `bi` | MIT | Bootstrap-adjacent apps | Mixed outline/fill names |
+| Fluent UI System Icons | `fluent` | MIT | Microsoft-like UI language | Regular, Filled |
+| Carbon Icons | `carbon` | Apache-2.0 | Enterprise/data tools | Fixed source sizes in packages |
+| Ant Design Icons | `ant-design` | MIT | Enterprise React products | Outlined, Filled, TwoTone |
+| Octicons | `octicon` | MIT | Developer tools, GitHub-like UI | 16px and 24px source sizes |
+| Feather Icons | `feather` | MIT | Minimal legacy outline style | Single outline style |
+| Iconoir | `iconoir` | MIT | Broad modern outline set | Single outline style |
+| Flowbite Icons | `flowbite` | MIT | Tailwind/Flowbite apps | Outline, Solid |
+| Ionicons | `ion` | MIT | Mobile/app UI | Outline, Filled, Sharp |
+| Simple Icons | `simple-icons` | CC0-1.0 | Brand logos only | Single-color brand marks |
+
+## Decision Criteria
+
+- Button icon clarity at 16px and 20px.
+- Menu, dropdown, and table icon legibility in dense rows.
+- Visual match with `default`, `rounded`, and `sharp` appearances.
+- Variant usefulness: filled states, two-tone states, sharp geometry, or rounded geometry.
+- Coverage for navigation, data, files, users, settings, alerts, billing, integrations, and brand logos.
+- Licensing and attribution obligations. Keep source license notices in the project when redistributing SVG/source files.
+
+## Sources
+
+- Google Material Icons repository: https://github.com/google/material-design-icons
+- Iconify collection API: https://iconify.design/docs/api/collection.html
+- Radix Icons: https://github.com/radix-ui/icons
+- Lucide: https://github.com/lucide-icons/lucide
+- Heroicons: https://heroicons.com
+- Tabler Icons: https://github.com/tabler/tabler-icons
+- Phosphor Icons: https://github.com/phosphor-icons/core
+- Remix Icon: https://www.remixicon.com
+- Bootstrap Icons: https://icons.getbootstrap.com
+- Fluent UI System Icons: https://github.com/microsoft/fluentui-system-icons
+- Carbon Icons: https://carbondesignsystem.com/elements/icons/code
+- Ant Design Icons: https://www.npmjs.com/package/@ant-design/icons
+- Octicons: https://primer.github.io/design/components/icon
+- Feather Icons: https://github.com/feathericons/feather
+- Iconoir: https://github.com/iconoir-icons/iconoir
+- Flowbite Icons: https://flowbite.com/icons
+- Ionicons: https://github.com/ionic-team/ionicons
+- Simple Icons: https://github.com/simple-icons/simple-icons

package/docs/design-system/registry-and-cli.md

@@ -0,0 +1,41 @@
+# Registry And CLI
+
+Banhaten publishes two registry shapes.
+
+| Artifact | Purpose |
+| --- | --- |
+| `registry/index.json` | Banhaten source of truth for the Banhaten CLI. Includes rich metadata for files, examples, dependencies, parts, RTL behavior, and design-system capabilities. |
+| `registry.json` | Generated shadcn-compatible export for tools that expect `https://ui.shadcn.com/schema/registry.json`. |
+
+Run `npm run registry:export` after editing `registry/index.json`.
+
+## Generated Files
+
+Installed files are generated source. `banhaten add` and `banhaten update` compare installed files to registry files and replace stale generated files by default. Use `banhaten diff` before updating when a project has local edits inside generated components.
+
+The token stylesheet is generated-owned too. `init`, `add`, and `update` refresh the managed Banhaten token block while preserving CSS outside the block.
+
+## CLI Commands
+
+```bash
+npx banhaten init
+npx banhaten add button input select
+npx banhaten diff
+npx banhaten update button
+npx banhaten list --json
+npx banhaten search input
+npx banhaten docs button
+npx banhaten view button
+```
+
+The CLI detects `packageManager` and common lockfiles before printing dependency install hints.
+
+## Schema Files
+
+Schema files live in `schema/`. The CLI copies them into `.banhaten/schema/` so generated `banhaten.config.json` can use a local `$schema` path instead of a fragile external domain:
+
+- `schema/config.schema.json`
+- `schema/registry.schema.json`
+- `schema/tokens.schema.json`
+
+Do not point package metadata or generated config at `banhaten.dev` unless that domain is live and serving the schema files.

package/docs/design-system/tabs.md

@@ -0,0 +1,53 @@
+# Tabs
+
+Tabs switch between peer views while keeping the user in the same context.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Tabs` (`225:9832`). It supports every variant in the matrix: `underline`, `segment`, and `rounded`; `md`, `sm`, and `xs`; full-width and hug-content layouts; LTR and RTL.
+
+## API
+
+```tsx
+<Tabs
+  variant="underline"
+  size="md"
+  fullWidth={false}
+  dir="ltr"
+  items={["Tab item", "Tab item", "Tab item", "Tab item", "Tab item"]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `underline`, `segment`, `rounded` | `underline` |
+| `size` | `md`, `sm`, `xs` | `md` |
+| `fullWidth` | `boolean` | `false` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `items` | `string[]` | five `Tab item` labels |
+| `activeIndex` | `number` | uncontrolled |
+| `defaultActiveIndex` | `number` | `0` |
+| `onActiveIndexChange` | `(index: number) => void` | none |
+
+## Token Contract
+
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into `registry/styles/globals.css` as a `--bh-*` token or alias first.
+
+- Backgrounds: `--bh-bg-neutral-subtle`, `--bh-bg-default`
+- Borders: `--bh-border-default`
+- Content: `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`
+- Shape: `--bh-radius-md-6`, `--bh-radius-lg-8`, `--bh-radius-full`
+
+## Pixel Rules
+
+- Text is Inter `15px / 24px`.
+- Active labels use weight `500`; inactive labels use weight `400`.
+- Segment and rounded containers use `2px` padding and `2px` item gaps.
+- Underline containers use a `1px` default bottom border and `16px` item gaps.
+- Active underline tabs use a `2px` `#245ded` bottom border.
+- Segment selected tabs use a pill radius; rounded selected tabs use `6px`.
+- Selected segment and rounded tabs use white fill plus `0 1px 1px rgba(15, 17, 20, 0.06)`.
+- `md` segment and rounded tabs are `40px` tall inside a `44px` container.
+- `sm` segment and rounded tabs are `36px` tall inside a `40px` container.
+- `xs` segment and rounded tabs are `32px` tall inside a `36px` container.
+- `md` underline rows are `56px`; `sm` and `xs` underline rows are `48px`.
+- Full-width tabs stretch equally inside their parent width.
+- RTL uses `dir="rtl"` on the tablist so the active first item appears on the right edge.

package/docs/design-system/token-governance.md

@@ -0,0 +1,38 @@
+# Token Governance
+
+Banhaten components must be built from Banhaten tokens. Component source may use:
+
+- Generated `--bh-*` semantic tokens.
+- Component aliases emitted by `scripts/component-token-aliases.mjs`.
+- shadcn alias bridge variables such as `--background`, `--foreground`, and `--ring` only when they point back to Banhaten tokens.
+- Documented exception-ledger values when the value is external, brand-owned, or required by a third-party primitive API.
+
+Do not add raw component styling literals directly to `registry/components`:
+
+- Raw color literals.
+- Raw `px`, `rem`, or `ms` values outside approved media-query breakpoints.
+- Raw opacity utilities such as `opacity-0` or `opacity-100`.
+- Raw z-index, ring width, duration, icon size, or compact spacing utilities.
+- Component-local `color-mix()` percentages.
+- Legacy `--ds-*` fallbacks.
+
+`npm run tokens:check` enforces the generated CSS contract and component token usage.
+
+## Exception Ledger
+
+The following exceptions are allowed only in token generation or documented alias source, not directly in component implementation:
+
+| Exception | Reason | Owner |
+| --- | --- | --- |
+| Social provider marks | Apple, Facebook, Google, LinkedIn, Twitter, and WhatsApp colors and icon geometry must preserve provider identity; color must still flow through `currentColor` and Banhaten social variables. | Component alias source and social button source |
+| Payment or illustrative mark geometry | Some Figma-matched marks use fractional geometry that cannot be expressed cleanly through the global spacing scale. | Component alias source |
+| Effect and shadow stops | The supplied token zips do not include effect tokens, so component shadow aliases document those values. | Component alias source |
+| Media-query breakpoints | CSS custom properties are not reliable in media-query conditions. | Component CSS with local comment |
+| Radix numeric offsets | Some Radix APIs require JavaScript numbers instead of CSS variables; comments must pair each number with its matching token. | Component source |
+| Expanded composition widths | Larger app compositions may expose public layout aliases or documentation-only layout aliases. | Expanded component docs |
+
+If a new literal is needed, add it to an alias or the exception ledger before using it.
+
+## Public Override Surface
+
+Stable override points are CSS variables emitted in `registry/styles/globals.css`. Prefer overriding component aliases rather than editing installed component source. Product teams should use local wrapper components for behavior and keep Banhaten files generated-owned.