A local editor for @wrnexus/design-system. The authoring package adds an authoring surface; applications continue to use the existing theme adapter and components. Neither Studio code nor AI credentials are needed by an application.

Start

From the repository root:

bun run design:studio
bun run design:studio --app-root path/to/existing/application

Open the printed loopback URL (default port 4320; override DESIGN_STUDIO_PORT). Without --app-root, the Studio supports editing, previews and portable exports. The second form enables local revision bundles inside the specified application's .wrnexus/design-studio directory. It does not overwrite application configuration, publish or deploy.

Authoring workflow

Create a blank design, select one of the three complete presets, duplicate the current design, or inspect/import local JSON.
Edit named foundations in the base, mode or density layer. Token references use @token.name; legacy suffixes bind values to existing --wrn-* variables. Save a token explicitly or commit by leaving its input. Search includes names, types and bindings. Resolved values identify their actual source, including mode overrides.
Inspect any of the 104 contracts and its ownership limits. Edit allowed default part properties, or use the component recipe JSON editor for variants, compound conditions and states. The canonical source editor supports every engine-supported field.
Compare the current draft with a preset or the last applied design. Preview a composed page or seven gallery pages. Choose mode, density, viewport width and LTR/RTL. Frame widths scroll independently of the authoring workspace.
Review before/after values and affected paths. Export the validated design or apply a local revision bundle. Rollback changes the application's current pointer and preserves the working draft.

Raw canonical edits autosave after a short pause. Invalid JSON, invalid aliases and unsupported recipes retain the last valid preview. Undo/redo and local history preserve invalid revisions as well as valid ones. History keeps up to 25 revisions. Storage corruption/quota failures show a message and preserve in-memory work; export the raw draft if autosave is unavailable. Local storage is not collaborative storage or a backup. Multiple browser tabs do not merge drafts.

Imports and exports

Canonical JSON is the lossless format: all tokens, modes, densities, recipes and supported metadata round-trip. Documents requiring an external inheritance registry must be resolved with that registry before importing; the Studio reports missing parents rather than inventing them.

Legacy import accepts JSON shaped like { "default": "light", "themes": { "light": { "color-primary": "#112233" } } }. Known semantic bindings are typed using the engine preset vocabulary. Unsupported fields and unknown suffixes are listed. This importer never evaluates a JavaScript/TypeScript configuration or guesses a dynamic palette.

The exchange subset accepts grouped or flat scalar tokens with $type and $value, group type inheritance, $description, and {token.path} aliases. Supported types are color strings, dimension strings, numbers, font-family strings, font weights and duration strings. Structured color objects, composite typography/shadows/dimensions, extensions and assets are unsupported. Tokens without WrNexus bindings are reported as ambiguous; map their legacy suffix in Foundations before expecting component changes. This is not a full DTCG implementation. Review the preservation/ambiguity/unsupported lists before accepting an import.

Exports include canonical JSON, standalone compiled CSS, theme configuration, resolved flat exchange tokens and a compatibility report. Exchange exports intentionally flatten modes/aliases to the selected resolved values and do not contain component recipes. Canonical JSON remains the editable source of truth. Invalid drafts can only be exported as raw drafts.

Application revisions

Apply validates the full document and selected mode/density again on the server. The server only writes to the root configured at startup; the browser cannot select arbitrary filesystem paths. Each immutable revision includes system.json, system.css, theme.json, tokens.json, report.json and integration guidance. CURRENT.json selects the active revision. Applying from a stale base revision fails with WRN-STUDIO-CONFLICT; refresh Review to inspect the new target state. Rollback swaps the pointer with the previous revision, including returning a first apply to none.

To integrate a reviewed revision into an existing app, import its generated theme.json and assign it to the existing config's theme field, retaining any explicit app overrides:

import theme from "./.wrnexus/design-studio/revisions/<revision>/theme.json";
// In your existing WrNexus configuration:
// theme: { ...theme, themes: existingThemeOverrides }

The generated theme configuration uses the existing designSystem adapter, preserving instance props and explicit application token overrides. Alternatively use system.css as a standalone stylesheet. Do not load both paths unless you deliberately manage precedence. Existing app configuration is never automatically rewritten. Applications pin the imported revision; changing the Studio pointer alone does not rebuild or deploy them. /application-preview renders the selected on-disk revision through the normal theme adapter for local verification.

Isolation and limits

The shell uses a separate browser-safe model entry. Filesystem/compiler/SSR code exists only under the server entry. The server binds loopback, rejects non-local hosts/cross-origin requests and bounds JSON inputs. Preview documents contain only trusted shipped component markup and validated styling. Frames permit scripts for component behavior, omit same-origin privileges, block network/forms/fonts, and retain provider/native/content ownership boundaries. The preview cache retains 24 generated documents; Refresh regenerates an expired one.

The component gallery is a baseline of default states, not full provider or accessibility certification. The composed preview exercises form controls, InputNumber and dialogs. Existing DatePicker calendar interaction emitted a client expression diagnostic during browser exploration; it remains available in the default-state gallery and its component source/API is unchanged. External provider rendering, all populated interaction states, extra browsers, collaborative storage, agent mutations, package publication and deployment remain separate scopes.

Run bun test packages/design-studio/test for model, import/export, application and preview checks. See the Phase 4 implementation report in docs/plans for broader regression and browser verification.

Guided generation and locked decisions

Open Guided design for a progressive brief, three previewable alternatives, foundation mixing and word-based edits. Proposals are staged until reviewed and accepted into normal draft history. The default is local rules, with a documented phrase vocabulary; unsupported requests leave the draft unchanged. Local prose fields are context, not interpreted instructions. Canonical exports continue to use the existing engine schema.

Use foundation-group locks or JSON pointers such as /tokens/shape.control or /recipes/Button. Locks protect raw decisions and referenced effective token values across modes/densities, including aliases. Lock-violating raw edits remain recoverable; unlock explicitly before accepting them. Lock preferences persist independently of undo/redo. Generated proposals bind to the source and locks and become stale when either changes.

For optional LLM interpretation, configure ANTHROPIC_API_KEY on the server and run bun run design:studio --ai-model <explicit-provider-model-id>. Or inject an existing AI provider into createStudioHandler({ generationProvider, generationModel }). The browser receives provider/model metadata, never credentials. Only a generation action sends the brief, design and capabilities; ordinary editing/previews require no provider.

Provider proposals are bounded data-only patches, validated against the engine and contracts, with at most one repair and a 20-second deadline. Failures/cancellation preserve the draft and previous candidates. The brief, alternatives and provenance autosave separately and can be exported as a generation report. See the Phase 5 report for exact command semantics, fidelity, budgets, recovery and live-provider verification limits.

Agent operations (Phase 6)

The existing MCP server now has opt-in design tools for recoverable drafts, locks, token patches, page specifications, context, conformance, preview, diff, export, apply and reversion. Start the local workspace server with bun packages/mcp/src/stdio.ts --root=APPLICATION_ROOT --design-write; --design exposes read operations only. Existing default tools and APIs are unchanged.

See the Phase 6 operation and recovery guide for revision requirements, tool schemas, examples and limits. Explicit server subpaths are ./agents, ./agent-context, ./agent-pages and ./conformance; filesystem/compiler functionality stays outside the browser root export.

Run bun run scripts/evaluate-design-agents.ts for the six-page/twelve-preview deterministic evaluation. No model credentials are needed. Design bundles and exported .wrn pages require explicit app integration. No routes or deployments are modified. Standalone staging and installed-consumer verification are available; see release and upgrade guidance.

Installed packages and upgrades

The component gallery uses 104 populated, interactive samples. Icons, browser functions, chart and graph runtimes are included locally. Large examples get appropriate space; output events appear below the sample. Map and device samples use local content. Forms/uploads do not submit data, and preview links stay in the preview. Loading and failure states preserve the current draft.

The preset and comparison menus offer 13 starting systems: Square, Soft, Angular, Swiss, Forest, Ocean, Rose, Violet, Ember, Editorial, Terminal, Brutalist and Contrast. Each has light and dark modes and uses the existing component contracts. The original three engine presets and existing saved drafts retain their formats. Create new seeds an editable design from the selected preset (Swiss when none is selected).

Generation automatically previews the first valid proposal in the large preview. Reviewing another proposal switches that preview and labels it as an unchanged draft review. Use Show current draft to return, or Use reviewed proposal to save the design as an undoable draft revision. Export/apply remains separate.

The staged package ships an installed wrnexus-design-studio binary, a prebuilt browser client and explicit server/agent subpaths. MCP consumes Studio as an optional peer. See RELEASE.md for installed usage, verified shared design bundles, upgrade planning, migrations, recovery and the release gate. The new package/upgrade APIs are programmatic; existing Studio authoring controls and APIs remain available.