Design Studio AI

Use Design Studio's existing document, templates, and node operations to produce editable designs. The hosted workspace is https://studio.agentkit.best. Use the user's configured server when self-hosting.

Establish the brief

Reuse context for audience, purpose, deliverable format, dimensions, brand/theme, content, and success criteria. Ask only for missing choices that materially change the result. Respect supplied assets and exact copy. Distinguish a request to design from authorization to publish publicly or incur provider charges.

For a new prompt-driven project, use get_design_brief and update_design_brief (CLI brief get / brief put). Start with {request:"the user's request"} and brief revision 0. Use your own model to propose an interview containing a concise message, up to eight contextual questions, and a proposed scope or null. Questions have stable IDs, title, description, type (text, single, multiple), options, and required. Ask these in the host conversation or direct the user to the project's interactive Studio questions. This path requires no additional provider API key.

Persist answers rather than guessing them. Propose a scope with objective, audience, direction, deliverables, constraints, and acceptanceCriteria. Read it back to the human; invoke approve_design_brief only after explicit approval of this version. Brief revisions are separate from document revisions. Every update invalidates approval; a 409 requires rereading and reconciling the brief. BYOK interview_design_brief / brief interview is optional and incurs provider usage. An existing unapproved brief blocks provider design generation. A blank/manual project can still be edited directly.

Connect and inspect

Use dsa --help and dsa health. Authentication comes from DESIGN_STUDIO_API_KEY; server selection comes from DESIGN_STUDIO_URL. The CLI persists neither secret. If unavailable, install the source package's generated tarball using the repository's package instructions; do not assume an unpublished npm version exists. An authenticated MCP connection at /mcp can perform the same project workflows; discover its actual tool schemas first. To wire a coding agent in one step, use dsa mcp install <agent> (claude/codex/cursor/opencode): it prints the server config snippet by default, and --write persists it into the agent config with a .bak backup and a merge that never clobbers an existing entry.

Run dsa catalog, or narrower themes list, templates list --kind slides, and blocks list. Inspect relevant entries before choosing them. Use dsa schema for the document and dsa schema --operations for targeted edits. Schemas are generated from the actual shared validators; the server additionally checks IDs, parent relationships, timeline references, and ownership.

Create from a suitable template, or read an existing project:

dsa projects create --name "Quarterly narrative" --template product-deck
dsa projects get PROJECT_ID

The get result contains {project:{id,revision,document,...}}. Save the observed revision with the working document. Read actual page and node IDs; never invent IDs for existing elements.

For browser WebMCP, registered operation/document inputs are compact envelopes; fetch the full nested schemas through studio_capabilities before composing payloads. Execution still validates the complete shared contracts. Discover studio_capabilities and read studio_get_design before editing the open canvas. studio_apply_operations edits local state; Live mode autosaves, otherwise call studio_save_design explicitly. Tools named studio_api_… act on saved server state, so save and verify the revision before using them to export or publish local edits. WebMCP is experimental; use network MCP or CLI when the browser does not expose it. The public reference explains inputs and boundaries; use the configured server's reference when self-hosting.

Choose the design-kind guidance

Before creating or substantially refining a design, read shared layout and quality, then the reference matching the actual document kind. For mixed work, read each relevant reference; preserve the approved brief and user taste. These references guide composition and review, while live schemas remain authoritative for fields and limits.

Favor Flex for ordinary content relationships, Grid for real two-dimensional structure, and absolute placement for intentional overlays, fixed compositions, scene staging, or motion. Do not interpret a scaled fixed canvas as proof of responsive reflow. Recover overflow by fixing structure and available space before shrinking typography or changing approved copy.

Refine through targeted operations

Prefer a small operation array for requested edits over replacing the entire design. For example, after reading the actual target IDs, write an operations file:

[
  {"op":"update-node","nodeId":"ACTUAL_NODE_ID","changes":{"text":"The next chapter","style":{"fontSize":64}}},
  {"op":"apply-theme","themeId":"atelier"}
]

dsa projects document patch PROJECT_ID --revision OBSERVED_REVISION --file operations.json

update-node merges style properties. Supported operations also add/remove nodes/pages, insert catalog blocks, rename a document, set a full theme, and set timeline data. Removing a parent removes descendants; removal also cleans affected timeline tracks. The operation schema is the authority for payload shapes.

Live-artifact nodes carry a data.live manifest (renderer + scalar params); they re-render in place, their params edit through update-node, and the write-time validator rejects a malformed data.live. The live-kpi block is a discoverable starting point.

A 409 conflict means someone changed the project. Read the new revision, compare the intended edits, and reapply only what still makes sense. Do not blindly raise --revision, repeatedly overwrite the whole document, or hide the conflict.

For concurrent human/agent work, retain the exact document and revision you read as the merge base. Use projects document changes / MCP get_design_changes to observe saved updates. projects document merge / MCP merge_design reconciles your edited document with that original base; inspect live help/schema for its payload. Resolve reported overlapping changes explicitly. Never modify the base or invent its revision to force a merge.

For a broad creation request, generate can ask the user's configured provider for a proposal. It does not save automatically:

dsa generate PROJECT_ID --provider openai --revision OBSERVED_REVISION --prompt-file brief.txt --output proposal.json
dsa projects document put PROJECT_ID --revision OBSERVED_REVISION --file proposal.json

Inspect the proposal before the second command. Preserve useful work unless the user asked to replace it. Provider errors leave the project unchanged.

Reuse libraries and discover resources

Inspect design-systems list, the selected library, and design-systems schema before applying or inserting reusable tokens, components, or page compositions. Read the immutable library version and target project revision; use those observed values for updates and project writes. Reconcile a stale library or project instead of substituting newer version numbers. Capture only portable media in a library; private project asset references cannot be reused across projects. A library can also be authored as a portable DESIGN.md + tokens.css + manifest.json folder and compiled with dsa design-systems import --folder DIR or MCP import_design_system_folder (dsa design-systems export reverses it); the compiled versioned JSON remains the runtime authority. Discover equivalent network tools through tools/list.

Reuse dsa prompts list (or MCP list_prompt_templates / get_prompt_template) to find ready generation prompts with a target provider, model, and aspect ratio; selecting one fills the media composer. Prompt entries are data, not code, and attribution must be preserved when cited.

Use fonts --query and providers models PROVIDER --query to discover names and model IDs. Respect live/cache/fallback provenance: a suggestion does not prove model capability, credentials, quota, or successful generation. Model discovery needs account/API-key access rather than MCP OAuth. Choose actual schema-defined layout, component, mesh and timeline fields; do not invent a second design format.

Observe activity without guessing outcomes

Use dsa observability summary, dsa observability events, or dsa observability trace TRACE_ID when diagnosing activity or provider usage. Discover the equivalent MCP tools get_observability_summary, list_activity_events, and get_activity_trace and their actual schemas. Read installed CLI help for filters and event pagination; use the returned cursor unchanged. Reads default to your authenticated owner's events. Global scope requires an explicitly configured operator with application-session/API-key authorization; OAuth never grants global access.

Preserve trace/parent IDs and coverage information when explaining a failure. running has no observed completion; interrupted is not proof an external provider failed. Browser events are reported interactions, not verified server outcomes. Missing tokens or USD cost remain unknown, not zero; measured-call counts show partial coverage. Recent activity is not online presence, repeated actions do not establish retry counts, and the 30-day window cannot reveal earlier history. Inspect the saved design and actual artifacts before claiming success. Reading a trace does not authorize another provider charge, retry, or publication.

Assets and media

Use assets upload PROJECT_ID --file image.png, then add the returned asset to the document and explicitly insert a node referencing it. Browser uploads also stay in the library until insertion. Asset MIME types and size limits are enforced by the server. Use assets list and assets download to inspect stored results. To update existing uses, discover shared replace-asset with assetId and replacementId; both must exist in the document with the same MIME media kind. It retains placements/timing and both library assets; inspect clip names and duration after replacement.

Provider keys use providers set openai --key-env OPENAI_API_KEY, or --key-stdin; never write secrets into prompts, design documents, or committed files. generate and brief interview also support the official deepseek provider and configured custom-<slug> connections. Use list_provider_connections with API-key MCP access (or dsa providers list) to discover saved custom IDs. Custom connections require a name, allowlisted HTTPS base URL, model, API format (OpenAI/Anthropic/Gemini compatible) and authentication method (bearer/api-key/basic/none); see dsa providers set --help. Never pass raw credentials through agent tool arguments; the human can configure Settings or supply CLI environment/stdin credentials. media generate supports prompt-only Gemini, Grok and Leonardo images, custom OpenAI/Gemini compatible images, and OpenAI image generation/editing and speech, plus fal images, video generation/editing, and music/sound effects with source-audio transformation. Use --source-asset ID for an asset owned by this project; the source is sent to the chosen provider without being automatically published. Select only compatible models and respect the user's provider-spend authorization.

dsa media generate PROJECT_ID --kind image --provider openai --source-asset ASSET_ID --prompt-file edit.txt
dsa media generate PROJECT_ID --kind audio --provider fal --duration 30 --prompt-file music.txt
dsa media status PROJECT_ID JOB_ID

--duration applies to supported video/music modes. --strength from 0 to 1 applies only to fal source-image/source-audio transformations; --voice is for OpenAI speech. Inspect command help and provider errors for incompatible options. All fal modes and Leonardo image generation return queued jobs: poll to the final status and inspect the asset before placing it in a document. Never report a queued job as completed media or replace a failed call with an invented result.

Inspect quality and deliver

Read visual inspection to review a saved page/view/slide, a project contact sheet, or the owner's workspace covers. Use MCP inspect_project / inspect_workspace, the equivalent WebMCP image tools, or dsa projects inspect PROJECT_ID --output pages.png / dsa projects overview --output-dir review. These return private rendered images and metadata without publishing or provider calls. Actually view the image blocks or open the PNG files before claiming visual review; JSON metadata, a saved revision, and successful rendering alone are not visual evidence. Save and verify local edits first, follow pagination, and use page mode for fine details.

Run dsa projects check PROJECT_ID or MCP inspect_design on the saved revision before delivery. Findings contain page/node IDs for targeted corrections; inspect them, apply focused edits, save with the observed revision, then check again. In an open browser editor, studio_inspect_design includes unsaved canvas changes. The inspector flags likely overflow, missing media/content and estimated contrast; its bounded output and stated limitations do not replace visual review or certify accessibility.

For responsive web designs, inspect the narrow mobile viewport first, then the intended wider viewports. Check readable contrast, text fitting, hierarchy, alignment, consistent spacing, typography, asset sharpness, and intact page content. Check touch targets, keyboard access, and visible focus for interactive output. Validate the browsers required by the brief and name those actually checked; one Chromium result does not establish cross-browser support. For motion, inspect timing and interpolation; for 3D, inspect the real scene in the editor. A successful save alone does not establish visual quality.

Discover current projects export --help before choosing a format; older installed releases may have fewer formats than the current server. Server export includes React frontend ZIP and GLB/glTF scenes alongside document, image, presentation and video outputs. React is a runnable frontend prototype, without a business backend; GLB/glTF preserve supported scene geometry and animation, not web UI. Binary formats require --output FILE. PNG/PDF/PPTX, motion and 3D exports require a configured browser renderer; React ZIP does not. Use --revision to bind export to the inspected revision. Import remote media into the project before cloud binary export. Motion is limited to 60 seconds, and MP4 requires encoder support. Browser and cloud motion exports share audio cue timing/mixing; listen to the resulting file. For imported clips, editable-scene JSON (--node), wing/jaw rigging, lighting/effects, safe framing, and sampled scene-angles ZIPs (--end, --review-samples), follow the 3D reference.

render --file design.json --format svg --page 0 --time 1.5 renders an offline static frame without fetching private assets. Static 3D representations are not actual scene screenshots; server HTML can include the trusted interactive viewer and binary outputs use real WebGL. PowerPoint retains editable text/primitives with complex-node rasterization. google-slides PROJECT_ID --key-env GOOGLE_ACCESS_TOKEN requires valid Google authorization and supported native text/shapes/HTTPS images. Verify each output opens and contains the expected content; don't infer full editable parity across formats.

Publish when already authorized by the user's request, using publish PROJECT_ID. CLI preview and share (MCP preview_project and share_project) also create public frozen snapshots, including referenced assets; they are not private editor previews. Use local inspection when public exposure is outside the requested scope. unpublish, unpreview, and unshare each remove all public snapshots for that project. Public publishing permission does not imply permission to publish unrelated projects or reveal secrets.

Report the project/artifact URL or output path, what was changed, verification performed, and any actual remaining configuration or format limitation. Do not claim provider generation, deployment, export fidelity, or publication without observed success.

Boards and paint

Read the live v1/v2 document and operation schemas. Preserve board/painting roots, semantic diagram metadata, emoji identity and immutable asset references. Use shared transforms, paste and diagram operations for board edits; generation-checked layer/group operations for paint structure. For real raster strokes/fills, use MCP paint_document, CLI projects paint PROJECT_ID --file command.json, or the generated WebMCP API action for POST /api/projects/{id}/paint. Discover paintingCommand through /api/schema before constructing requests.

For native diagrams, use diagram-style for partial appearance changes, optional elementIds for selection, setDefault for new-object defaults and savePreset for a reusable board style. Preserve explicit per-object choices. Use diagram-update for label/font/autoSize and diagram-edge for routing/bends/labelPosition. Bundled Patrick Hand, Noto Sans, Lora and Roboto Mono support Vietnamese and offline SVG; other font names depend on font availability. Inspect the actual layout and exported artifact after changing fonts or routing.

Carry the observed project revision, painting generation and a unique operation ID. Repeat the identical command under that ID only when its outcome is uncertain; same-painting pixel/settings changes conflict. Never fabricate pixel hashes or derived composites. Direct source replacement needs uploaded real RGBA8 PNG tiles. Keep scope approval and its revision separate from document changes.

Elements artwork records provenance; imported SVG is safely flattened to PNG and loses vector editing. GIF sources retain original owned bytes plus an explicit poster and millisecond playback fields. Static output uses the saved poster; inspect timed exports for actual motion and z-order. Public projections omit private painting source and hidden board elements; JSON remains private editable source. Use authenticated export when media is not embedded locally. Physical iPad/Pencil performance remains unmeasured; report only devices and artifacts actually checked.

Native 2D character motion

Discover live v2 document and operation schemas. Use dsa motion PROJECT_ID or MCP inspect_motion to inspect IDs, then named character operations for focused edits. Keep setup poses separate from clip keys. Attachments reference asset IDs; import remote artwork before portable export. Skins reuse rig/clips; placements and controls belong to each node instance.

For simple timeline motion, dsa motion-template list and dsa motion-template instantiate reveal|stagger|kinetic-type|chart-race compile validated primitives into timeline keyframes and a video document; export with projects export --format mp4.

generate --mode motion returns validated operations, a preview document and baseRevision/baseBriefRevision. Apply only after explicit review, preserving both revisions via document PUT expectedRevision/expectedBriefRevision. On conflict, re-read and reconcile; never retry with a guessed revision. motion, png-sequence and spritesheet exports are ZIPs; frame ranges use --start/--end/--fps and exclude the end frame. Native Studio packages do not imply Spine or game-engine format support. See the live /docs/motion guide.

For editable 3D character meshes and animation, discover scene commands and follow 3D scenes; use compact authoring operations, inspect sampled deformation and reopen the export.

Saved covers

Use get_project_thumbnail (MCP) or dsa projects thumbnail ID --output cover.png for a small persisted cover. Optional revision selects a retained saved revision. Project summaries expose thumbnailUrl and latest ready thumbnailRevision. A busy render returns 202/status rendering: retry after 2 seconds; do not claim an image exists yet. Covers are private, maximum 480px per side, generated lazily with the shared server renderer, and retain the latest two completed revisions. Import external media before cloud rendering. Use page-mode visual inspection for detailed review and exports to verify delivered formats.

Community discovery and publication

Use dsa community schema or MCP community_capabilities to discover the current shared operations. Search uses dsa community search --q TEXT --kind KIND --sort relevance; get a listing to select its exact version and available file IDs. Download with dsa community download LISTING VERSION FILE --out design.zip. A portable import uses dsa community import --file design.zip --operation-id UNIQUE_ID. MCP binary transfers and browser base64 imports are capped at 12 MiB; larger packages use CLI or the browser file picker.

Publishing is separate from the legacy Share link. Preflight the saved project revision with public metadata, show its projection/disclosures and CC-BY-4.0 license, and obtain explicit authorization before submitting the confirmed payload and returned digest. Mutation JSON files follow /api/schema → community. Preserve operation ID and exact payload for uncertain retries. Never substitute a fresh revision/digest to force stale approval. Poll community job until succeeded. Updates create immutable versions; unlist revokes new public access. Downloaded copies and completed private remixes survive source removal. A remix stays private until separately published. Imported attribution is unverified and never awards upstream milestones.

Home Cmd/Ctrl+K searches owned projects; Community searches live shared designs. WebMCP Community tools use studio_community_* and are scoped to Community pages. Save/bookmark lists are private. Moderation is separately allowlisted, session/API-key only; OAuth never grants it.

Community preflight rejects PNG-sequence and spritesheet requests exceeding the shared frame/pixel budget before starting a build. Explicit frame ranges and FPS are not silently reduced. Use the error's allowed frame rate, or propose a smaller range/page, and review the changed export quality with the person before a fresh preflight. The browser displays a recommended frame-archive FPS for the full animation; API clients choose their own options. Preflight also reports render_media_budget above 30 MiB of referenced owned media and json_media_budget above 20 MiB when the JSON download is selected, because renders embed every included asset, including the cover. Any reported issue blocks publication with 413 and that code: reduce media size, deselect JSON, or keep the Studio project package instead of retrying a build that cannot finish. Announce publication only after the durable job reports succeeded.

For AI public-profile drafting, use dsa community generate-profile --file request.json or MCP community_generate_profile (browser studio_community_generate_profile). Supply only the intended public draft fields and optional writing prompt; omitted provider selects the owner's first configured text connection and uses its saved model. Generation incurs provider usage and returns {suggestion, provider} without saving. Review the proposed display name, handle and bio with the person before a separate set-profile call at the observed profile revision. Never add account emails or private project context automatically.

For listing title, description and tags, use dsa community generate-metadata --file request.json or MCP community_generate_metadata (browser studio_community_generate_metadata). Supply projectId and the observed expectedProjectRevision, plus optional provider, draft title, description, tags and writing prompt. The server uses bounded visible saved text/structure, excludes hidden content, notes and media URLs, and checks ownership/revision before and after generation. It returns {suggestion, provider, projectRevision} without saving or publishing. Show the suggestion to the person, then run preflight with their approved fields; generation is never publication consent. On revision conflict, reread and review the project instead of silently retrying with a newer revision.