WRNexusJS/docs/plans/2026-10-19-design-system-phase-0-audit.md

Design-system Phase 0 audit and decisions

Historical snapshot: Phase 2 subsequently added 14 versioned core contracts and hooks. The linked coverage matrix is regenerated from current sources; see the Phase 2 implementation report for the newer status.

Date: 2026-10-19. Scope: static audit of the current working tree, including pre-existing uncommitted changes. No runtime behavior or visual accessibility certification is claimed. No production implementation was changed.

Completion and evidence

Phase 0 documentation deliverables are complete: current-source inventory, styling-source map, support matrix, proposed contracts, compatibility decisions, representative fixture requirements and Phase 1 work order. Runtime contract integration, screenshots and cascade proof belong to subsequent phases.

Regenerate inventory with node scripts/audit-design-system.mjs. Outputs: machine-readable coverage and readable matrix. Per-source hashes identify the audited content. Re-run after component edits; this report describes a moving working tree rather than a clean release baseline.

Observation	Evidence	Consequence
104 component sources, 104 reference entries, 104 catalog entries; names match	packages/ui/components, component-reference.json, component-catalog.json	Use current source declarations as catalog truth
Older inventory claims 891 components	docs/UI-COMPONENT-INVENTORY.md	Historical documentation is stale for this checkout; do not plan rollout against that number
All 104 sources contain local style blocks	Generated inventory	Recipe integration must handle component-local styles, not only ui.css
No source has the proposed data-wrn-part hook	Generated inventory	All 104 remain legacy-uncontracted; existing classes still provide customization
Global CSS contains literal geometry	packages/ui/ui.css, e.g. container max-width/padding	README claims that every value is a token overstate actual coverage
Button mixes token radius with literal padding, pill radius and state transforms	packages/ui/components/button.wrn	Add property bindings selectively; do not mechanically tokenize structural constants
Input/Select share field selectors; Select has extensive local field CSS	input.wrn, select.wrn, styles/SelectStyles.wrn	Audit shared-selector ownership and duplicate rules before recipe rollout
Card already exposes geometry/layout attributes and named slots	Card.wrn	Preserve explicit props and compose with them instead of introducing competing defaults
Modal has named internal regions and dialog semantics	Modal.wrn	Parts can be additive; actual mounting/focus behavior requires fixture verification
Registry filesystem helpers are server-only	packages/ui/src/registry.ts, src/index.ts	New authoring/build code must not leak into browser imports

Inventory extraction is heuristic. Token counts are local references, not computed-style coverage. Prop names come from generated reference metadata. Named slot extraction covers double-quoted names; absence is not proof of no slot. Literal-declaration counts identify review candidates, not defects. No component is promoted to recipe support by this scan.

Styling and delivery map

1. packages/styles/src/theme.ts resolves named themes, palette/accent configuration and token CSS. Existing tokens include semantic colors, geometry, dimensions, shadows, spacing and typography. ThemeTokens allows additional names.
2. packages/ui/ui.css provides shared global rules and structural styles. packages/ui/components/*.wrn and packages/ui/styles/*.wrn also contain styles.
3. packages/dev-server/src/assets.ts serves UI/theme assets in development; prod.ts serves built UI CSS in production.
4. packages/dev-server/src/runtime.ts constructs framework/UI/app global stylesheet additions, with inline/bundled variations (stylesIncludeUi, stylesIncludeFramework, inlineStyles).
5. packages/ssr/src/index.ts::extractWrnexusStyles extracts compiler-emitted styles, deduplicates by ID, orders layout -> page -> component, and emits after global stylesheets with CSP nonces.
6. Browser theme/accent preferences and SSR token selection already exist. The engine should adapt to this path rather than create a second competing preference runtime.

Important limitation: the UI README's statement that application CSS loads after UI CSS does not establish that it wins against extracted component CSS. Specificity, local declarations, inline styles, bundles and insertion points all matter. Dev/production computed-style fixtures are mandatory before specifying recipe delivery as stable API.

AI and agent integration audit

packages/mcp/src/index.ts currently declares inspection tools for routes, components, schema, diagnostics, runtime errors, dev status, docs and packages. Design draft/mutation tools do not exist there yet. Reuse its application-root and bounded-output model, and independently verify path/symlink containment for new writes.

packages/ai/package.json exports both the default client and ./platform. The default src/index.ts is an Anthropic text/stream client. src/platform.ts includes provider adapters (including OpenAI). Do not infer support solely from a README headline or advertised capability booleans: structured design output, validation, cancellation and repair need adapter-level verification in Phase 5. No live provider calls were made for this audit.

Contract decisions

The contract proposal defines versioning, ownership, parts, states, recipe resolution, legacy compatibility and fixture requirements. Initial decisions:

• Opt-in engine, unchanged baseline defaults and public component APIs.
• Canonical data-only specification with typed tokens and explicit aliases.
• Separate identity, mode, accent and density.
• Additive part hooks; preserve existing classes, props, slots, events and ejection.
• Per-component support statuses, including provider-owned regions.
• Explicit app theme values override imported defaults.
• No global layer rewrite, blanket !important, or new wrappers during Phase 0.
• Conditional recipes have deterministic ordering and provenance.
• Application-owned components are reported; the studio cannot guarantee their styling.

Prioritized risks and Phase 1 blockers

Priority	Risk	Required resolution
P0	Recipe CSS loses to extracted local styles	Establish insertion point and selector strategy; verify development/production and CSP
P0	System defaults override intentional existing props/themes	Define explicit/default provenance and adapter semantics; baseline/override fixtures
P0	Schema allows invalid references or executable imports	Data-only schema, typed resolver, alias-cycle/missing-reference errors
P1	Shared field selectors leak between components/scopes	Ownership audit and nested-scope fixture
P1	New authoring code enters browser bundles	Browser-safe export boundary and consumer import verification
P1	Scoped overlays inherit wrong theme	Verify mount behavior before claiming scope support
P1	Chart/canvas/provider visuals ignore CSS	Mark unsupported regions; design explicit provider adapters later
P1	Metadata drifts or broad string props imply invalid variants	Verify actual accepted variants during descriptor implementation
P2	Hash baseline mistaken for visual regression	Introduce rendered representative snapshots in Phase 2

Phase 1 implementation order

1. Add engine package with browser-safe schema/types and server build subpath; integrate workspace public API conventions.
2. Implement schema versioning, typed token values, references, inheritance resolution, provenance and stable diagnostics.
3. Implement deterministic CSS output and legacy theme adapter; no studio or provider dependency.
4. Resolve the cascade blocker using small baseline fixtures covering global/local/extracted styles, specificity, inline/bundled output, SSR and production.
5. Add CLI inspection/validation and an opt-in application configuration path.
6. Verify default appearance/API preservation and app override behavior; document supported output and remaining gaps.

Representative rollout and acceptance

Phase 2 begins with Button, Input, Select, selection controls, Card, Alert, Modal, navigation/menu and typography/layout. Exact current names come from the matrix, not invented component names. Phase 3 covers the rest by family. Provider-heavy Chart/FlowCanvas/DrawflowCanvas need separate capability boundaries.

Phase 0 gate: every current source has an explicit support status; discrepancies and styling paths are recorded; representative contracts and state constraints are specified; risks and Phase 1 acceptance work are ordered. This gate is satisfied by these artifacts. It does not mean the proposed hooks, engine, studio or agent tools exist. Proceed to Phase 1 in the next authorized implementation step.