generated from coulomb/repo-seed
71 lines
3.9 KiB
Markdown
71 lines
3.9 KiB
Markdown
# 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.
|