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, Phase 1 engine, and Phase 2 core contracts, recipes and three presets. Phase 3 complete catalog rollout is delivered. Phase 4 local Design Studio is delivered. Phase 5 guided generation, alternatives and decision locks is delivered. Phase 6 MCP operations, agent context and conformance is delivered. Phase 7 shared packages, upgrades and release preparation is delivered as a locally verified packaging candidate; the subsequent release blocker clearance records passing repository production and installed-consumer gates. The subsequent user-authorized private release published and integrity-verified all 58 packages. The standalone component site is prepared for VM deployment; Git pushes are deferred until authentication is restored.

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, component contract specification, and the generated coverage matrix.