39 lines
4.1 KiB
Markdown
39 lines
4.1 KiB
Markdown
# Design-system Phase 1 implementation
|
|
|
|
Date: 2026-10-19. Status: engine and opt-in legacy integration implemented; Phase 2 component recipes/studio remain unimplemented.
|
|
|
|
## Delivered
|
|
|
|
- New dependency-free, browser-safe `@wrnexus/design-system` package and structural JSON Schema v1.
|
|
- Typed token validation with a bounded CSS grammar, stable diagnostic codes and paths.
|
|
- Explicit token aliases, type checks, reference cycles/missing-reference checks, ordered system inheritance and bounded traversal.
|
|
- Mode/density overrides, retained legacy bindings, resolved values and source/reference provenance.
|
|
- Deterministic token CSS, optional owner scope and collision detection.
|
|
- Legacy adapter and opt-in `theme.designSystem` configuration in the existing styles pipeline; SSR and production consume the existing resolved theme representation.
|
|
- Explicit application token/default/cookie/accent preferences retained. Imported systems suppress the implicit accent default so it cannot overwrite the brand; explicitly configured and selected accents still work.
|
|
- Data-only CLI commands: `wrnexus design validate|inspect|compile system.json`, with optional mode, density and registry inputs.
|
|
- Usage documentation, a square-system example, workspace dependencies and a narrowly updated public API baseline for the new package.
|
|
|
|
See [package documentation](../../packages/design-system/README.md) for the actual supported format and APIs. Canonical token fields are intentionally smaller than the eventual complete studio specification. Unsupported future fields fail explicitly rather than being silently ignored.
|
|
|
|
## Compatibility choices
|
|
|
|
No UI component source, prop, event, slot, behavior, CSS rule or SSR insertion order was changed. Tokens map through existing `--wrn-*` variables. Existing hard-coded component styles and explicit variants retain their behavior. The engine does not yet compile component recipes, so it does not introduce the later recipe-vs-local-style precedence problem. Recipe insertion/specificity still requires a Phase 2 proof before hooks are advertised as stable.
|
|
|
|
The runtime adapter emits mapped legacy variables only. Standalone token CSS emits namespaced design variables as well. Avoid loading both outputs without intentionally managing their cascade. Density selection is compile/config time; scoped overlay propagation and runtime density controls are not implemented.
|
|
|
|
## Verification
|
|
|
|
- Combined engine, CLI, styles, UI and SSR suites: 323 passing tests, no failures at the initial full verification. Subsequent targeted validation tests are recorded with the final delivery.
|
|
- Browser-target bundling verifies no filesystem/provider dependency in the engine entry.
|
|
- CLI smoke test validates the saved square-system example.
|
|
- A compiled legacy Button is rendered through SSR extraction and checked in happy-dom: imported tokens apply, explicit application overrides win, mode switching updates geometry, and removing opt-in restores current baseline values.
|
|
- New source lint and formatting checks are run separately.
|
|
- Native Edge headless invocation on this host returned no document output. The reliable cascade check is a DOM simulator check, not native-browser or screenshot certification.
|
|
- Workspace-wide type checking remains blocked by errors outside the new engine/CLI module, including existing build/auth typing and CSR/dev-server/UI test typing. A focused engine/theme/CLI type check isolates this delivery.
|
|
- The global public API checker also detects pre-existing API drift in other packages. The baseline addition is limited to `@wrnexus/design-system`; unrelated APIs were not silently accepted by regenerating the entire baseline.
|
|
|
|
## Phase 2 entry work
|
|
|
|
Implement versioned component descriptors and additive owner/part hooks for the representative families. Verify state mapping and actual variants from sources; introduce recipe compilation only after nested ownership, specificity, SSR/development/production, CSP, explicit instance props, application overrides and overlay-context fixtures pass. Add native-browser screenshots for the three contrasting systems before claiming visual coverage.
|