Ardot Design Assistant

Ardot Design Assistant

Standard workflow for completing design tasks on .ardot files via the ardot MCP server. All canvas manipulation MUST go through ardot MCP tools.

Reference Files

Load on demand based on task type:

Preparation: (IMPORTANT: Ensure a Design File Is Open)

Before any canvas operation, make sure an Ardot design file is loaded in the editor. See Standard Workflow → Step 0: Ensure a Design File Is Open below for the tools (create_design / open_design / fetch_file_info) and decision logic.

Standard Workflow

Step 0: Ensure a Design File Is Open

Before any canvas operation, make sure an Ardot design file is loaded in the editor:

• create_design — Create a new blank Ardot design file and open it in the editor. Optionally accepts a fileName. If the user wants to start from scratch or no existing file is mentioned, call this first.
• open_design — Open an existing Ardot design file by URL or file ID. Accepts a fileUrl parameter (e.g. https://ardot.tencent.com/file/667788990055443 or bare ID 667788990055443). If the user provides a file link or ID, call this to load it.
• fetch_file_info — Fetch the current loaded file ID, after create_design or open_design has been called to get the file ID.

Decision logic:

1. If the user explicitly provides a file URL or ID → call open_design.
2. If the user asks to create a new design / start fresh → call create_design.(optionally with the given 'fileName').
3. If the editor already has a file loaded (determined in Step 1) → skip this step.
4. If call create_design produces an empty canvas, MAKE SURE SKIP fetch_editor_state at any workflow, the default PageID is 0:1, use it as the root container.

⛔ Hard gate — do NOT issue any other MCP call until the file is ready.

After calling create_design or open_design, the file loads asynchronously. You MUST wait for the context update / ready confirmation before issuing any other MCP call.

Never bundle create_design / open_design in the same parallel batch as fetch_editor_state, fetch_variables, or any other read — those reads will hit an empty or not-yet-loaded editor and return stale/empty state.

Correct order (two separate messages):

1. Message 1: create_design or open_design → wait for ready signal.
2. Message 2: subsequent reads (Step 1) — may be parallel, see below.

Exception: if Step 0 is skipped (a file is already loaded from a previous turn), Step 1 can be the first message of the turn.

Step 1: Read Existing State (parallel, conditional)

Read whatever state is relevant to the task. Issue all independent reads in a single message as parallel tool calls — do not serialize them.

Do NOT call fetch_style_guide_tags. The tag list is static — read ../../rules/style-guide-tags.md instead.

Step 2: Creative vs. Compositional

• Creative (new screen, page, dashboard, restyle) → proceed to Steps 3–4
• Compositional ("add a button", "move this") → skip to Step 5 and load design-rules.md

Step 3: Load Design Guidelines

Load one or more design-type guideline, first match wins:

guidelines-code.md / guidelines-tailwind.md are implementation guidelines and can be loaded alongside a design-type guideline when code generation is involved.

Steps 4–6: Style + Space + Inspection (parallel)

Issue these as a single parallel batch in one message — they have no mutual dependency:

• fetch_style_guide(tags) — pick 5–10 fitting tags from ../../rules/style-guide-tags.md (see the Selection Guidance section there).
• locate_available_space({width, height}) — required for new top-level screens; skip for pure modification tasks. Never overlap existing content.
• Inspection calls (only if modifying existing design and not already covered in Step 1): batch_read (find by pattern/ID, readDepth: 3 for component structure), capture_layout (detect problems), capture_screenshot (visual verify).

Skip any sub-call that doesn't apply to the current task. The point of parallel batching is to collapse independent reads into one round-trip, not to force every tool to run.

If a follow-up read depends on this batch's result (e.g. batch_read({readDepth: 3}) targeting a component discovered via an earlier batch_read), issue it as a separate message afterward. Most tasks don't need that.

Step 7: Execute Design

batch_edit with ≤ 25 ops per call. Build order: structure → content → style → verify. Ops: I() Insert, U() Update, C() Copy, M() Move, D() Delete, G() Image. For detailed syntax and examples, load references/ardot-workflow.md.

Step 8: Validate

Follow the Post-Generation Validation Pattern in design-rules.md. Use tiered validation — pick the lightest check that matches what the batch changed (T1 structural → capture_layout only; T2 content → skip; T3 visual → capture_screenshot only; T4 section-complete → both once; T5 final page → one screenshot). Do not run full dual-verification after every batch_edit. Enforce the convergence threshold: max 2 fix iterations per section, ignore ≤4px spacing noise, no subjective re-polishing once the section matches spec.

Specialized Workflows

When the task matches one of the following, load the linked reference and follow it strictly (do not improvise the procedure from SKILL.md):

• Slides / presentation / deck → choose workflow based on the current model. When the model is opus4.7, ask the user whether to use the agent teams workflow (clarify that it takes more time and consumes more tokens): if yes, use references/slides-agent-teams-workflow.md; if no, use references/slides-workflow.md. For other models, use references/slides-workflow.md directly. Mandatory design rules live in references/guidelines-slides.md.
• Website → style guide extraction → references/extract-style-guide-from-web.md
• Design → frontend code → references/design-to-code-workflow.md

Essential Constraints

These rules apply at all times. Full rule set and troubleshooting are in design-rules.md.

• Every node needs a name — assign meaningful names to all created nodes
• Keep float colors to 2 decimals — avoid long floating-point values
• Text is invisible by default — always set fill on text nodes
• Use fill for all colors — never use textColor, backgroundColor, color, or fillColor
• Use cornerRadius — not borderRadius
• Font weight must be numeric strings — "400", "700", not "bold"
• Alignment uses uppercase enums — counterAxisAlignItems: "CENTER", not alignItems: "center"
• Prefer flexbox layout — always set width and height on new frames explicitly
• Layout default sizing is FIXED — when setting layout to horizontal/vertical, must explicitly set width/height for dynamic sizing
• x/y are ignored in flexbox — if you need to set x/y on children of flexbox parents, also set layoutPositioning: "ABSOLUTE"
• fill_container requires flexbox parent — only valid when parent has layout
• hug_contents requires own flexbox layout — only valid on a node that itself has flexbox layout
• Default frame has white background — set fills: [] to remove
• Max 25 ops per batch_edit — split by logical sections
• Every I/C/R needs a binding name — document is predefined for root only
• No U() on copied descendants — copied nodes get new IDs; use descendants in C() instead
• No image node type — images are fills on frames; use G() with "stock" preferred
• Icon frames must set layout: "none" — and always capture_screenshot() to verify
• Create icons as components — then use I(parentId, {type: "ref", ref: "iconId"}) to insert instances
• Variable binding uses $ prefix — fill: "$primary-color", gap: "$spacing-small"
• Favor copying + updating over generating from scratch
• Parallelize independent reads — when multiple MCP read calls have no data dependency (e.g. fetch_editor_state + fetch_variables), issue them in a single message as parallel tool calls; do not serialize them. Exception: never bundle these reads in the same message as create_design / open_design — wait for the file-ready context update first
• Validate with tiered checks — match the tier to the batch type (see design-rules.md Post-Generation Validation Pattern); do NOT run full screenshot+layout after every batch_edit
• Text wrapping needs both — textAutoResize: "HEIGHT" AND width: "fill_container" (or fixed width)
• lineHeight — set lineHeight: "AUTO" for automatic (preferred) or lineHeight: 22 for explicit spacing