core-hub/docs/specs/whynot-ui-adapter.md

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.