plasmic-designer

# Plasmic Designer Skill Version: 1.3.3 Control Plasmic Studio through Chrome DevTools MCP to build and modify production-ready interfaces. ## Arguments `$ARGUMENTS` should contain a **project ID** as the first word, followed by the design request. Example: `/plasmic-designer j2Bm3mrbGNKsXVW3Wf5KpP Add a hero section to the Homepage` If no project ID is provided, or if the conversation references multiple projects and it's unclear which one to use, ask the user to confirm the project ID before proceeding. ## Setup The studio base URL is `https://studio.plasmic.app` by default. Only use `http://localhost:3003` if the user explicitly mentions localhost, a local dev server, or a local environment. 1. **Navigate to the project** using `navigate_page` to open `{baseUrl}/projects/{projectId}/` 2. **Wait for studio to load and identify the session** — the studio takes a few seconds to initialize. Poll until `window.PLASMIC_AI_TOOLS` is available, then call `identify()` once, before any other tool. ```javascript async () => { for (let i = 0; i < 30; i++) { if (window.PLASMIC_AI_TOOLS) { return await window.PLASMIC_AI_TOOLS.identify({ model: "<model>", client: "<client>", outputFormat: "<json|xml>", }); } await new Promise((r) => setTimeout(r, 1000)); } return { success: false, error: { message: "Studio failed to load." }, }; }; ``` Fields (all required): - `model` — Model name as known to the agent (e.g. `claude-opus-4-7`, `anthropic/claude-sonnet-4-6`, `gpt-5.3-codex`). - `client` — AI client/CLI invoking the tool (e.g. `claude-code`, `claude-code@1.x`, `opencode`, `cursor`, `cline`). - `outputFormat` — Preferred format for tool output, `"json"` or `"xml"`. Pass `"unknown"` for any required string field you cannot reliably identify. If `success` is false, inform the user and stop. ## Workflow Follow an explore-first pattern for every request: 1. **Understand** — `read` the current state before changing anything; prefer reusing existing components over new HTML. 2. **Plan** — For complex requests, break the work into steps before acting. 3. **Execute** — Make changes with the appropriate tools. 4. **Verify** — `read` to confirm structural changes; Optionally, `take_screenshot` to confirm the result visually. Tools edit a page or component without opening its arena, so `navigate` to it first. ## Using the tools The toolset is exposed at runtime and is the source of truth — **introspect it, don't rely on a hardcoded list.** `_meta` is a `Record<string, CopilotToolMeta>` keyed by tool name: ```ts interface CopilotToolMeta { toolName: string; title: string; description: string; inputSchema: JSONSchema7; // JSON Schema (draft-07) outputSchema: JSONSchema7; // shape of a successful `output` } ``` Read a compact tool catalog once with `evaluate_script`. Omit schemas from this initial result because they are much larger: ```javascript () => Object.fromEntries( Object.entries(window.PLASMIC_AI_TOOLS._meta).map( ([name, { title, description }]) => [name, { title, description }], ), ); ``` Before using a tool, inspect its `inputSchema` and treat it as authoritative for field names, required fields, enums, and nesting, for example `() => window.PLASMIC_AI_TOOLS._meta.read.inputSchema`. Inspect only the relevant `outputSchema` when its result shape matters. Call a tool with an async arrow function (tools return Promises), passing one input object that conforms to its schema: ```javascript async () => await window.PLASMIC_AI_TOOLS.<toolName>({ /* fields per window.PLASMIC_AI_TOOLS._meta.<toolName>.inputSchema */ }); ``` Every call resolves to a `CopilotToolCallResult`: ```ts type CopilotToolCallResult = | { success: true; output: string } | { success: false; error: { message: string; type: "TOOL_NOT_FOUND" | "EXECUTION_FAILED" }; }; ``` Check `success` each time; on a UUID error, re-read for fresh UUIDs and retry. Call `read` before any mutation to get project structure and the UUIDs every other tool needs. Its output is usually XML: parse it for UUIDs, props, variants, and slots, and read selectively (specific components/elements) on large projects. After a successful mutation the canvas updates automatically. ## Legacy Data Query Migration Only when asked, read `references/query-migration.md` before migrating. Migrate only the named query; for a component-wide request, assess every `legacyDataQueries` entry. ## Components & Variants ### Reusing Existing Components When you read a component, review its props, variants, slots, element tree and per-variant style overrides before using it. To use a component in insertHtml: ```html <plasmic-component data-plasmic-component="ComponentName" data-plasmic-project="importedProjectId" data-plasmic-name="primaryCta" data-props='{"propName":"value","variantGroup":"optionName"}' style="margin: 16px;" > <slot name="slotName">Slot content here</slot> </plasmic-component> ``` - `data-plasmic-component` must exactly match the component name from `read()` (case-sensitive). - `data-plasmic-project` (optional) is the id of the imported project the component comes from. Omit it for components in the current project; set it to use a component from an imported project. - `data-plasmic-name` (optional) names this component instance in the tree. It's a semantic name picked up by Plasmic codegen to override the element in the generated code. - `data-props` is a JSON object for both props and variant activations. Boolean variants: `"group": true`. Enum variants: `"group": "optionName"`. - `<slot name="slotName">` children fill named slots; its children become the slot content. - **Only layout/position styles work on instances**: width, height, min/max sizing, margin, position, top/left/bottom/right, z-index, order, align-self, flex-grow/shrink, opacity, display (only `none`), transform, and transition properties. Background, padding, color, font, border, etc. are ignored on instances — use `changeElement` on the component's root element instead. This is a Plasmic platform constraint, not a preference. ## Dynamic Data Text, attributes, and component props can be bound to runtime data — `$props`, `$state`, `$ctx` (page params/query), `$queries` / `$q` (data query results), and repetition locals (`currentItem`, `currentIndex`). - Write bindings as inline `{{ jsExpr }}` interpolation. Content is static by default; wrapping JS in `{{ }}` makes it dynamic (also used for non-string literals, e.g. `"{{ 10 }}"`). - Before binding, `read({ dataContext: [{ componentUuid, elementUuid }] })` to see which paths exist, then drill in with `paths` / `maxArrayItems`. Reference only paths it returns. - Repetition: `data-repeat="{{ $q.myQuery.data }}"` in `insertHtml`, or `repeat: { collection: "..." }` in `changeElement`; bind the subtree with `{{ currentItem.* }}`. The repeated element is duplicated once per item, so put row or wrapping layout on its parent. - Visibility: `data-visible-if="{{ ... }}"` / `data-visibility="displayNone"`, or `visibility: { showIf: "..." }` in `changeElement`. - A prop wired to the enclosing component's prop reads back as `{{ $props.<name> }}`, and a link-to-page destination as its URL with dynamic parts inlined (e.g. `/products/{{ $state.slug }}`). ## HTML Code Guidelines Before generating HTML, read `references/html-constraints.md` for the full set of rules. The key points: - Use `<style>` blocks with BEM-style class names instead of inline styles. - Use flex layout exclusively (Plasmic does not support CSS Grid). - Include `@media` queries for responsive breakpoints — `read` the project's breakpoints (with `screenBreakpoints`) first. - Use Google Fonts (single name, no fallback lists). - Use inline SVG for icons, `https://placehold.co` for placeholder images. - To use an existing image or icon asset, reference it as `src="var(--image-<asset-uuid>)"` on an `<img>` or `<svg>` tag respectively. - `<slot-target name="slotName">default content</slot-target>` defines a named slot when building a reusable component; slots cannot be nested. - No JavaScript, no vendor prefixes, no `data:image/svg+xml`, no `currentColor`, no `:root`. ## Design Quality Before generating designs, read `references/design-guidelines.md` for aesthetic principles and design thinking guidance. ## Design Tokens Read the project's tokens before generating designs, then: - Prefer existing tokens over hardcoded values for consistency. Reference them as `var(--token-<uuid>)`. - If a token's value doesn't match the design intent, use a hardcoded value instead — design accuracy matters more than token reuse. - Not every value needs a token. Use them for deliberate design decisions (brand colors, type scale), not incidental one-off values. ## Modifying Existing Components - **Small changes** (color, spacing) — apply directly with `changeElement` or `insertHtml`. - **Significant changes** to widely-used components — describe the proposed changes and ask the user before proceeding, since edits can cascade across the project. - **Variant-scoped changes** — when possible, scope changes to a specific variant to avoid breaking other usages. ## Response Format - Be brief and action-oriented. Lead with what you did. - Summarize changes in 1-2 sentences. - Don't repeat the user's request or give lengthy explanations unless asked.