---
name: design-os-studio
description: "Use when working with DESIGN:OS Studio (designos-studio, designos, designos-mcp, designos-diff) — native Rust/wgpu Figma .fig v106 read/write engine, Agentic PTY Chat UI, 11-stage Spec Reader, Dev Mode codegen, and headless GPU screenshot QA."
---

# DESIGN:OS Studio (`design-os-studio`)

Native GPU-accelerated interface design studio (`wgpu` Metal / Vulkan / DX12 + `tiny-skia`), enterprise Figma `.fig` v106 binary read/write engine, native Agentic PTY Chat UI (`Claude Code` · `Codex` · `Antigravity`), 11-stage `PRODUCT:OS Spec Driven v2` Reader, multi-target Dev Mode code generator, and Model Context Protocol server (`designos-mcp`) built in 100% Rust.

## When to Use

Activate this skill when the user asks to:
- `"Apply a declarative NodeSpec JSON onto the DESIGN:OS Studio canvas, export a verified Figma .fig v106 binary archive, and capture a headless GPU screenshot."`
- `"Open the 11-stage PRODUCT:OS Spec Driven v2 Reader (--panel specs) or Agentic PTY Chat UI (--rail agents) and verify User Stories, Gherkin scenarios, and g1..g5 gates."`
- `"Inspect a .fig or .designos document in Dev Mode, generate React/Tailwind/CSS/SwiftUI/Compose code, or run perceptual visual diffing with designos-diff."`
- `"Package native cross-platform installers (.dmg, -setup.exe, .deb) for designos-studio, designos, designos-mcp, and designos-diff."`

## Progressive Disclosure Routing (`What loads when`)

1. **Always Loaded**: `skills/design-os-studio/SKILL.md` (this router — keeps context lean at ~120 lines).
2. **On Demand — Agent Rules & Tool Pack**: Load [`rules.md`](./rules.md) (`skills/design-os-studio/rules.md`) for the generated 7-step build-verify-fix workflow, per-tool schemas/error codes, `NodeSpec` schema reference, and design-quality rules.
3. **On Demand — Prompt & CLI Recipes**: Load `docs/cookbook.md` when selecting multi-step workflows, headless screenshot flags, or MCP server patterns.
4. **On Demand — Installation & Release Packaging**: Load `docs/install.md` and `docs/releasing.md` when building or installing `.dmg`, `-setup.exe`, or `.deb` packages.
5. **On Demand — Diagnostics**: Load `commands/doctor.md` or run `python3 scripts/self_check.py` when verifying repository or skill health.
6. **On Demand — Ecosystem Discovery**: Load `llms.txt` when cross-referencing companion `DESIGN:OS` engines.

## Core Binaries & CLI Surface

| Binary | Role | Key Flags / Subcommands |
| :--- | :--- | :--- |
| `designos-studio` | Native GPU/CPU Desktop Studio & Headless Visual QA Runner | `--open-id <id>`, `--select <name>`, `--zoom <pct>`, `--gpu`, `--size <WxH>`, `--screenshot <out.png>`, `--rail <files\|assets\|agents\|specs\|variables\|components>`, `--tab <design\|prototype\|dev>`, `--dev-lang <react\|tailwind\|css\|swiftui\|compose>`, `--panel <specs\|variables\|cmdk\|main-menu\|color-picker>`, `--tool-mode <comment>` |
| `designos` | Agent-First CLI for Spec Apply, `.fig` Binary Export & Comment Loops | `--apply-spec <spec.json>`, `--export-fig <out.fig>`, `--export-spec <out.spec.json>`, `--inspect-json`, `--comments-json`, `--add-comment <text>`, `--reply-comment <id> --message <msg> --resolve` |
| `designos-mcp` | Local stdio Model Context Protocol Server | `--workspace <dir>` (`designos_open_file`, `designos_apply_spec`, `designos_export_fig_file`, `designos_generate_code`, `designos_list_comments`, etc.) |
| `designos-diff` | Perceptual SSIM & Structural Diff CLI | `compare <ref.png> <actual.png> --out <diff.png>` |

<!-- designos-mcp-tools:begin -->
<!-- Generated by `cargo run -p designos-mcp --bin gen-tool-docs`. Do not edit by hand. -->

| Tool (`36` total) | Mode | Required Args | Description |
| --- | --- | --- | --- |
| `designos_get_document` | read-only | — | Summarize the current in-memory document: pages, counts, shared styles (fill, text, effect, grid) with their values, and undo state. |
| `designos_get_libraries` | read-only | — | List this file's local publishable assets, enabled libraries (with pinned and latest versions and update_available), and disabled libraries in the active library root. |
| `designos_get_metadata` | read-only | — | Return a sparse XML node hierarchy (IDs, types, names, page-space bounds, layout, component/variant props, text previews, and lint issue counts) for a page or subtree. |
| `designos_search_design_system` | read-only | `query` | Search components, component sets, shared styles, and variables across this file and its enabled libraries, returning ranked instance-ready references and NodeSpec examples. |
| `designos_list_nodes` | read-only | — | List node summaries in numeric ID order. Query matches names case-insensitively; parent_id filters direct children. Use next_offset to paginate. |
| `designos_get_node` | read-only | `node_id` | Read the full native node including geometry, paints, text, bindings, and child IDs. |
| `designos_get_variables` | read-only | — | Read variable definitions and collections. With node_id, also resolve that node's direct bindings using inherited collection modes. |
| `designos_generate_code` | read-only | `language`, `node_id` | Generate developer handoff code or SVG for a layer using resolved variable values. Returns source text; writes no files. |
| `designos_create_node` | mutating | `kind`, `parent_id` | Create one layer in a container; defaults to x/y=0, width/height=100. Supports undo. Text is only valid for text layers. Changes are in memory until saved. Content added to, removed from or moved in an instance slot is kept when the main component changes. |
| `designos_update_node` | mutating | `node_id` | Update specified fields of one non-page layer. Coordinates are parent-relative. Replacing text clears text runs and list ranges. Supports undo; changes remain in memory until saved. |
| `designos_delete_node` | mutating | `node_id` | Remove a non-page layer and its entire subtree. Supports undo; changes remain in memory until saved. Content added to, removed from or moved in an instance slot is kept when the main component changes. |
| `designos_list_comments` | read-only | — | List canvas comment threads enriched with resolved world coordinates, target node ID/name/kind, and top-level frame ID/name. Filter by resolved state, page_id, or node_id. |
| `designos_add_comment` | mutating | `text` | Pin a new comment thread to a node (with local offset x/y) or page coordinates. Supports undo. |
| `designos_reply_comment` | mutating | `text`, `thread_id` | Append a reply message to an existing canvas comment thread and optionally mark it resolved/unresolved. Supports undo. |
| `designos_resolve_comment` | mutating | `thread_id` | Mark a canvas comment thread resolved (default true) or unresolved (false). Supports undo. |
| `designos_apply_spec` | mutating | `spec` | Build a complete UI subtree from a declarative NodeSpec (supports EaseUI BrainWave 2.0 presets like easeui-screen/easeui-card/easeui-button-primary, $easeui.* tokens, and Auto-Layout 5.0 row/column/wrap/hug/fill) in a single atomic undoable step together with the variables it creates. Replies with bindings_created, styles_linked and warnings (for example DEPRECATED_EASEUI_TOKEN). Content added to, removed from or moved in an instance slot is kept when the main component changes.  Examples: 1) Token-bound frame with auto-layout: {"parent_id":1,"spec":{"kind":"frame","name":"Hero","layout":{"direction":"column","gap":16,"padding":[24,24,24,24]},"fill":"var:Color/Surface","children":[{"kind":"text","name":"Title","text":"Welcome"}]}} 2) Component instance with variant and overrides: {"parent_id":1,"spec":{"kind":"instance","name":"PrimaryCTA","component":"Button","variant":{"Size":"lg","State":"default"},"overrides":[{"path":"Label","text":"Continue"}]}} 3) Component instance with filled slots: {"parent_id":1,"spec":{"kind":"instance","name":"SettingsCard","component":"Card","slots":{"header":[{"kind":"instance","component":"CardHeader"}],"body":[{"kind":"instance","component":"FormRow"}],"footer":false}}} |
| `designos_export_spec` | read-only | `node_id` | Export a node and its descendants as a declarative NodeSpec JSON tree, enriched with Dev Mode status/annotations and any canvas comment threads pinned within the subtree. |
| `designos_set_dev_status` | mutating | `node_id` | Set a layer's Dev Mode handoff status ('ready', 'completed', or 'clear') and/or append a developer annotation. Supports undo. |
| `designos_export_fig_file` | mutating | `output_path` | Export the current session document to a Figma binary .fig container (with fig-kiwi header and deflate chunks) inside the workspace. |
| `designos_query_xpath` | read-only | `selector` | Query layers in a page or subtree with a streaming single-pass XPath evaluator, node budget, cursor pagination, compact rows, and solver-backed linter predicates (has-problem, is-bound, has-hardcoded, @problems, @inProgress).  Examples: 1) Truncated text: {"selector":"//TEXT[has-problem('text-truncated')]"} 2) Hard-coded fills inside a frame: {"selector":"//FRAME[@name='Card']//*[has-hardcoded('fills/0')]"} 3) Layers an agent is working on: {"selector":"//*[@inProgress]"} |
| `designos_lint` | read-only | — | Run the unified solver-backed geometric, text, token, and structural design linter on a page, specific node subtrees, or the active page. |
| `designos_get_guidelines` | read-only | — | List available design guideline topics or return the guideline document for a topic ('design-system', surface guides, 'archetypes', 'archetype:<id>', or 'rules'). |
| `designos_import_web_capture` | mutating | — | Import a .webcapture.json / .capture.json bundle (or inline capture JSON) into a page as an editable auto-layout frame tree in one undoable step, returning the ImportReport. |
| `designos_undo` | mutating | — | Undo the latest successful edit in this session; returns changed=false if the stack is empty. |
| `designos_lint_fix` | mutating | — | Apply deterministic fixes for auto-fixable lint findings on a page, specific node subtrees, or the active page in a single undo step. |
| `designos_redo` | mutating | — | Redo the most recently undone edit in this session; returns changed=false if the stack is empty. |
| `designos_get_screenshot` | read-only | — | Render a node, a set of nodes on the same page, or a page-space rectangular region and return it inline as MCP image content (PNG or JPEG), automatically downsized to max_long_edge (default 1024). |
| `designos_set_in_progress` | mutating | `node_ids`, `value` | Flag or clear root frames as in progress while an agent works on them (work state, not an undo step). |
| `designos_apply_batch` | mutating | `ops` | Execute 1..=200 write operations (apply_spec, insert/create, update, move, delete, set_slot, set_variables, set_style, set_in_progress) as a single atomic transaction and one undo group. Later ops may reference nodes created by earlier ops via '$prev', '@<as>', or '@<as>/<name path>'. With dry_run=true, computes and returns created IDs, name_to_id map, touched_roots, and touched_bounds without mutating the document or publishing a live patch. Pass idempotency_key to deduplicate retries (a key names one logical write; after a reconnect, call designos_get_node before trusting a replayed id). Note: in a live Studio session, if the editor remaps a colliding ID on replay, the reply holds the session IDs until the next canvas reload. Examples: (1) create + $prev: {"ops":[{"op":"create","parent":1,"kind":"frame","name":"Header"},{"op":"create","parent":"$prev","kind":"text","text":"Title"}]}; (2) apply_spec with as + @handle/Child update: {"ops":[{"op":"apply_spec","as":"hero","spec":{"kind":"frame","name":"Hero","children":[{"kind":"text","name":"Child","text":"Hi"}]}},{"op":"update","node":"@hero/Child","opacity":0.9}]}; (3) set_slot: {"ops":[{"op":"set_slot","node":"@card","slot":"body","fill":[{"kind":"text","text":"Body"}]}]}; (4) dry_run: {"dry_run":true,"ops":[{"op":"insert","kind":"rectangle","name":"Box"}]}. |
| `designos_get_design_context` | read-only | `node_id` | Return generated code in the target language, Dev Mode hints (variables with CSS/platform code syntax, linked styles, component instances/properties, annotations, dev status, Code Connect stub), and an inline screenshot (scale 0.5, max_long_edge 1024), with an XML outline fallback when the subtree exceeds 5,000 nodes or generated code exceeds 40,000 characters. |
| `designos_configure_session` | mutating | — | Configure per-session MCP options for the automatic mutating-call lint issues block (issues.mode: preset \| errors_only \| off, issues.preset, issues.max_items: 1..=100) and auto_fix settings. Persists across reconnects in the session directory and resets on document switch. |
| `designos_get_app_state` | read-only | — | Return the pre-fetched design context block. Sections: freshness, document, depth-3 target frames outline, variables summary, components and libraries, active style, and rules pack, plus session state. Pass include_selection=true ONLY when the user explicitly asks about their canvas selection. |
| `designos_open_file` | mutating | `path` | Import a .designos, .designos, .fig, SVG or Figma REST JSON file inside the workspace into this isolated session. Does not control an open editor. Unsaved changes require discard_changes=true. |
| `designos_save_file` | mutating | `path` | Save this session to a .designos file inside the workspace. Existing files are not overwritten unless overwrite=true. Parent directory must exist. |
| `designos_render_png` | mutating | `node_id`, `path` | Rasterize a frame or layer to a NEW .png file inside the workspace using DESIGN:OS Studio's deterministic renderer. Existing files are never overwritten. |
| `designos_new_document` | mutating | `name` | Start a blank document with one page. Unsaved changes require discard_changes=true. |
<!-- designos-mcp-tools:end -->

## Core Execution Workflow

1. **Inspect Context**: Use `designos <file> --inspect-json` or `designos_get_document` via MCP to inspect pages, frames, tokens, and handoff status before mutating.
2. **Execute Deterministically**: Apply declarative `NodeSpec` JSON (`--apply-spec`) with Auto-Layout 5.0 (`relayout_subtree`), or roundtrip directly to standard Figma `.fig` v106 binary archives (`--export-fig`).
3. **Verify Visually & Epistemically**: Capture a headless GPU render (`--gpu --screenshot out.png`), run `designos-diff` when comparing against a reference, and run `python3 scripts/self_check.py`.

## Quality Bar & Anti-Scope

### It's working if...
- `python3 scripts/self_check.py` prints `ok: design-os-studio self-check passed (design-os-studio)` and exits `0`.
- `cargo test --workspace` passes all 823 automated unit, golden, and parity tests with 0 failures.
- Headless GPU/CPU screenshots render with 1:1 Figma UI3 dark chrome (`#1e1e1e`), unified Phosphor Icons, and `0.0%` static viewport CPU usage.
- Execution remains 100% local with zero external telemetry (`PRIVACY.md`).

### When NOT to use
- Multi-user cloud-hosted SaaS whiteboarding requiring real-time WebRTC cursor presence across browser tabs without local files.
- 3D rigid-body CAD modeling or mechanical STL slicing (use `design-os-3d-blender` instead).
- Paperboard folding dielines and spot-color pre-press PDF separations (use `design-os-origami` instead).