# whynot UI Adapter Spec

## Purpose

Map the whynot-design system into Core Hub without binding Core Hub to a single frontend framework or copying design behavior by hand.

## Source Contract

Core Hub consumes whynot-design as an external design contract:

- Layer 1: `colors_and_type.css`, `components.css`, and token files.
- Layer 2: Lit custom elements such as `<wn-button>`, `<wn-table>`, `<wn-sidebar>`, `<wn-page-header>`, `<wn-field-row>`, `<wn-tag>`, and `<wn-stage-dot>`.
- Layer 3: optional adapters or server-side partials for repeated patterns.
- IR: committed `whynot-design/ir/` tokens, component contracts, exemplars, and schemas.

Core Hub must not hand-edit whynot-design IR or fork tokens. Changes to shared visual language belong in whynot-design and flow through its adapter/drift process.

## Consumption Modes

| Mode | When to use | Core Hub stance |
|---|---|---|
| Static vendored assets | First prototype or server-rendered console. | Copy or package whynot CSS and `index.js` into Core Hub static assets with a repeatable sync command. |
| Custom elements directly | Default UI implementation mode. | Use `<wn-*>` tags in HTML/Jinja/HTMX/static pages; pass state through attributes and slots. |
| Framework adapter | Only when a stack wrapper removes meaningful repetition. | Generate scaffold/drift reports from whynot IR; never overwrite hand-authored behavior. |
| Bespoke component | Only for Core Hub-specific operational views not present in whynot. | Preserve whynot tokens, typography, spacing, and data-state semantics. |

## Component Mapping

| Core Hub need | Preferred whynot primitive |
|---|---|
| Application shell | `<wn-top-nav>`, `<wn-sidebar>` |
| Page title and actions | `<wn-page-header>` |
| Primary/secondary/ghost command | `<wn-button>` |
| Status, severity, task state, policy scope | `<wn-tag>`, `<wn-stage-dot>` |
| Dense registry/list surface | `<wn-table>` or table classes from `components.css` |
| Form row and filter controls | `<wn-field-row>`, `<wn-input>`, `<wn-select>`, `<wn-search-input>` |
| Warnings and blocked states | `<wn-banner>` |
| Empty/no-results state | `<wn-empty-state>` |
| Breadcrumb/context trail | `<wn-breadcrumb>` |
| Progress or migration stage | `<wn-pipeline>` where a true ordered stage model exists |

## Core Hub Adapter Rules

1. Tokens are generated or vendored deterministically; rerunning sync on unchanged whynot-design output should produce no diff.
2. Component behavior remains hand-authored in Core Hub only when it is Core Hub-specific.
3. Attribute names should follow whynot IR prop-to-attribute mappings.
4. Non-portable props from whynot IR must be surfaced as adapter drift, not silently ignored.
5. Adapter reports are snapshots, not logs; regenerate instead of appending.
6. Visual parity checks should use whynot-design exemplars for shared components and Core Hub screenshots for composed screens.
7. Core Hub screens must not introduce secrets into DOM state, local storage, test snapshots, or visual artifacts.

## Data-State Semantics

Use stable, low-cardinality state names across UI, API, and tests:

- lifecycle: `draft`, `active`, `disabled`, `archived`, `superseded`;
- task: `wait`, `todo`, `progress`, `done`, `cancel`;
- readiness: `unverified`, `ready`, `degraded`, `blocked`, `fallback`;
- migration: `validated`, `dry-run`, `imported`, `discrepancy`, `rolled-back`;
- severity: `info`, `warn`, `fail`, `critical`.

When an API value is richer than these UI states, preserve the raw value in the detail view and map only the visible status marker.

## First Adapter Deliverables

1. Static whynot asset sync plan or package dependency decision.
2. One console shell using whynot custom elements directly.
3. One registry table and one migration-run table with empty/loading/error states.
4. Playwright smoke that checks desktop and mobile screenshots for non-overlap and visible controls.
5. Drift/parity note that records the whynot-design git ref used by Core Hub.