WRNexusJS/docs/plans/2026-10-19-design-system-engine-and-studio.md

# Design System Engine and Design Studio

Date: 2026-10-19. Status: architecture plan; phases 0–7 delivered within the scopes documented below. The user requested phase-by-phase delivery.

Implementation progress: [Phase 0 audit](2026-10-19-design-system-phase-0-audit.md), [Phase 1 engine](2026-10-19-design-system-phase-1-implementation.md), and [Phase 2 core contracts, recipes and three presets](2026-10-19-design-system-phase-2-implementation.md). [Phase 3 complete catalog rollout](2026-10-19-design-system-phase-3-implementation.md) is delivered. [Phase 4 local Design Studio](2026-10-19-design-system-phase-4-implementation.md) is delivered. [Phase 5 guided generation, alternatives and decision locks](2026-10-19-design-system-phase-5-implementation.md) is delivered. [Phase 6 MCP operations, agent context and conformance](2026-10-19-design-system-phase-6-implementation.md) is delivered. [Phase 7 shared packages, upgrades and release preparation](2026-10-19-design-system-phase-7-implementation.md) is delivered as a locally verified packaging candidate; the subsequent [release blocker clearance](2026-10-19-release-blocker-clearance.md) records passing repository production and installed-consumer gates. Publication remains held at the user’s request; registry/version verification belongs to the separately authorized publication workflow.

## Product outcome

Users can import a brand, start from presets, answer guided questions, or describe an appearance. They can compare coherent alternatives, refine individual decisions, apply the result to existing WrNexus components, share it across applications, and ask agents to build consistent pages. The engine works without the studio or an AI provider. Applications consume compiled output, not the authoring tool.

## Architecture and ownership

All authoring surfaces edit one versioned specification: questionnaire / visual editor / agent / import -> specification -> resolve and validate -> compile tokens and recipes -> existing components -> previews and application build.

| Owner                             | Responsibility                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------- |
| Proposed `@wrnexus/design-system` | Schema, resolution, validation, compilation, migrations, design contracts       |
| `@wrnexus/styles`                 | Existing token compatibility, stylesheet delivery, SSR and preference switching |
| `@wrnexus/ui`                     | Behavior, parts, states, recipe integration                                     |
| Proposed `@wrnexus/design-studio` | Guided setup, editing, previews, drafts, history                                |
| `@wrnexus/cli`                    | Inspect, validate, compile, compare, apply, migrate                             |
| `@wrnexus/mcp`                    | Structured agent access to the engine                                           |
| `@wrnexus/ai`                     | Optional provider adapter, subject to verifying actual implementation           |

Keep browser-safe exports separate from filesystem/compiler/provider subpaths. No new package is created in Phase 0.

## Canonical specification

Begin with data-only JSON and a published schema. A future typed authoring helper must normalize to the same document. Include:

- Identity: stable ID, name, description, schema version and independent system version.
- Foundations: primitive colors, font families, spacing, dimensions, radius, border widths, elevation and motion.
- Semantic roles: text, surface, action, feedback, border and focus tokens.
- Typography: heading/body roles, sizes, weights, line heights and tracking.
- Recipes: component parts, variants, sizes, states and compound conditions.
- Composition: containers, grids, breakpoints, section rhythm and density.
- Modes: explicit semantic overrides, including light and dark.
- Assets: font/icon/image references, provenance and licensing metadata when supplied.
- Policies: locked values, allowed exceptions and unsupported combinations.
- Guidance: usage descriptions and examples for humans and agents.
- Compatibility: engine and component-contract requirements.
- Provenance: imports, generation context and revision references.

Tokens have types, aliases and validated values. Detect missing references, cycles, unknown parts and invalid conditions. Separate subjective intent from resolved values. Unspecified values inherit documented defaults. Compilation is deterministic; AI generation is not. Migrations preserve original files and produce reviewable diffs. Assets are references rather than silently embedded payloads.

## Component integration

Preserve existing props, events, slots, semantics, discovery, application shadowing and ejection. Define versioned contracts for parts, variants, sizes, states, slots, capabilities and constraints. Support global foundations, component defaults, variant recipes, state recipes, scoped systems, instance exceptions and custom implementations.

Square buttons use radius zero. Angular/tilted recipes must preserve readable copy, hit area, visible focus, icons, loading and pressed effects. Do not overwrite interaction transforms blindly. Tokens cannot represent arbitrary markup changes; ejection and application-owned components remain supported escape hatches.

Resolution and CSS cascade are separate concerns. Establish explicit recipe resolution order and verify emitted selector specificity, stylesheet order and component-local styles before adding recipe CSS. Do not migrate all existing CSS into cascade layers without a compatibility proof.

## Compatibility and runtime

- Adoption is optional; current applications retain current defaults.
- Map resolved values to existing `--wrn-*` variables.
- Existing explicitly configured theme values override imported system defaults.
- An inspector explains the source of every resolved value.
- Keep design-system identity, mode, accent and density as separate axes.
- Scoped systems must carry context into dialogs, menus and other externally mounted content.
- SSR selects the correct system and mode before first paint; browser switching agrees with SSR.
- Ejected/custom components have explicit support status; never assume complete control.
- Compiled output remains usable without AI credentials, studio code or network generation calls.

## Design Studio

| Area         | Features                                                            |
| ------------ | ------------------------------------------------------------------- |
| Start        | Create, import, duplicate, open, select preset                      |
| Brief        | Product, audience, tone, constraints, references                    |
| Foundations  | Color, typography, spacing, shape, elevation, motion                |
| Components   | Parts, variants, sizes, states, approved exceptions                 |
| Preview      | Component gallery, composed pages, responsive views, comparisons    |
| Review/apply | Validation, source diff, affected components, save, apply, rollback |

Include live valid previews, undo/redo, draft autosave, token/component search, inherited-value inspection, locked decisions, side-by-side directions, mode/density/viewport/RTL controls, accessible keyboard editing, unsupported-feature reporting and portable exports. Preserve invalid partial input while showing the last valid preview. Local revision history comes first; collaborative storage is separate scope.

## Guided workflow

Ask progressively: what is being built, who uses it, whether a brand exists, desired visual feeling, preferred geometry, density, surface treatment and fixed constraints. Show visual choices rather than relying only on adjectives. Generate three distinct directions on identical preview content. Users can combine selected decisions and refine through natural language; every combination is revalidated.

## Import/export

Initial imports: existing WrNexus theme configuration, canonical JSON, a documented subset of a token exchange format, and manually mapped brand values. Later: CSS variables, reference images/documents and connected design tools. Mapping reports preserved, ambiguous, unsupported and missing values. Image extraction is interpretive. Canonical round trips are guaranteed; other formats have fidelity reports.

Export canonical JSON, compiled CSS, integration configuration, exchange tokens, component guidance, validation/compatibility reports and versioned reusable packages. Package publication and deployment are separate actions from local application.

## AI and agent integration

Requests include brief, references, component capabilities, current system, locks, modes, constraints, requested alternatives, budgets and cancellation. Workflow: inspect -> draft/patch -> validate -> bounded repair -> isolated preview -> available checks -> compare -> apply selected revision. Preserve the last valid draft on failure/cancellation. Record provider/model and prompt-template versions without storing credentials.

Provide compact generation context with approved tokens, components, variants, composition rules and examples. Add conformance diagnostics for unsupported variants and avoidable hard-coded values, with explicit exceptions. Verify actual `@wrnexus/ai` capabilities instead of trusting inconsistent README claims.

Proposed agent operations: inspect, capabilities, create draft, propose patch, validate, preview, diff, apply, revert and export. Mutations include a base revision, detect conflicts, and return stable diagnostic codes and affected paths. Read operations work without AI credentials. Filesystem operations remain within the configured application root. Do not implicitly deploy or publish.

## Quality gates

Validate types/references/cycles; engine and contract compatibility; recipe/state resolution; cascade and scope; contrast and visible focus; keyboard scenarios; reduced motion; long text/localization/RTL; narrow screens; disabled/loading/invalid/selected states; SSR/hydration; overlay inheritance; screenshots; CSS size and compile/preview cost; AI lock preservation and repair limits; import fidelity and migrations. Automated checks do not establish full accessibility or aesthetic quality. Isolate previews and constrain untrusted CSS/assets; imports must not execute code.

## Delivery sequence

| Phase | Deliverables                                                                                  | Gate                                                        |
| ----- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| 0     | Source/catalog audit, styling map, coverage matrix, contracts, precedence decisions, fixtures | Supported/unsupported scope and Phase 1 blockers documented |
| 1     | Schema, resolver, validator, compiler, theme adapter, CLI inspection                          | Deterministic output and legacy compatibility               |
| 2     | Representative component recipes and three systems                                            | Identical markup; behavior and visual checks pass           |
| 3     | Catalog rollout by family                                                                     | Explicit support status for every entry                     |
| 4     | Studio editor, previews, history, import/export                                               | Complete non-AI creation/application workflow               |
| 5     | Guided generation, alternatives, locks, natural-language edits                                | Valid recoverable drafts and reviewable application         |
| 6     | MCP operations, generation context, conformance/evaluation                                    | Agent creates multiple consistent pages                     |
| 7     | Shared packages, upgrades, migrations and release workflow                                    | Predictable reuse across applications                       |

Start integration with buttons, text inputs, selection controls, cards, alerts, navigation, dialogs/menus and typography/layout. Token inheritance alone is not complete recipe coverage.

## First proof milestone

Render one unchanged application as square/compact/outlined, soft/spacious/restrained and angular/expressive/high-contrast. Include navigation, form, dialog, loading/error states, light/dark and narrow screens. Require API compatibility, explainable resolved values, consistent switching, preserved keyboard/focus, agent inspection/editing and no studio/AI runtime dependency.

## Later scope

Shared workspaces, roles, comments, approval workflows, hosted synchronization, brand libraries, visual reference extraction, design-tool sync, organization reporting, marketplace and broader custom-component registration. Real-time collaboration needs a separately designed identity/storage/conflict model.

## Phase 0 artifacts

See [audit and decisions](2026-10-19-design-system-phase-0-audit.md), [component contract specification](2026-10-19-design-system-component-contracts.md), and the generated [coverage matrix](../design-system/component-coverage.md).