Loora Design Guide

Loora Design Guide

Create real, editable Loora designs through the MCP tools. Treat the Canvas document—not generated code—as the source of truth. Work like a designer: understand the product, establish a system, build coherent sections, inspect the render, and refine the weak parts.

Gate the MCP surface first

Inspect the callable Loora tools before creating or mutating anything. Require:

• createPage, insertNodes, and patchNodes for new design authoring
• createComponent and createInstance for reusable component work
• setTokens for tokens or themes
• setAnimations and animateNodes for motion
• branch lifecycle tools for branch work

If a required tool is absent, stop before createDesign or any partial mutation. createDesign creates only an empty record; it is not a successful Canvas design. Report the missing tools and the manifest/session mismatch. Do not substitute HTML, JSX, browser clicks, or repeated speculative calls.

If a callable tool exposes nested arguments such as ref, nodes, or patch as unknown, treat that as a schema-display limitation, not permission to guess. Use the schema reference below.

Load references by action

For a one-field text or spacing patch, read mcp-schema.md plus the target node; do not load every design reference.

Follow the core loop

1. Check capability and orient. Confirm the required authoring tools are callable. Call getUsage if budget matters. Call listDesigns, select the target explicitly, then call getDesignContext. For an existing design, inspect the relevant area with readTree, readNode, or searchNodes.
2. Protect the target. Confirm whether the user intends Main or a branch. Carry the same designId and optional draftId through every call. For a broad or speculative redesign, prefer a new branch. Never silently switch targets.
3. Form a visual direction. Extract the audience, job, content hierarchy, mood, constraints, and required states from the request. If the prompt is underspecified, choose a coherent direction and state it briefly; do not default to a generic dashboard.
4. Establish the system. Reuse existing tokens, themes, components, spacing, and typography. For a new design, define a small token set and reusable components before repeating them. Use semantic, human-readable node names.
5. Build in meaningful batches. Use createPage for the Page and its initial hierarchy. Use insertNodes for later sections, patchNodes for atomic refinements, and moveNodes for source structure. Prefer flex/grid with fill and hug; reserve absolute positioning for intentional overlays or artwork.
6. Inspect after meaningful edits. Call getScreenshot on the affected Page or node. With image vision, compare the pixels against the brief and design-craft.md. Without image vision, use the renderer result plus readTree/readNode as described in tool-workflows.md and state that pixel quality was not visually judged. A successful mutation alone is not proof.
7. Refine surgically. Fix the largest verified problem first. With vision, use visible hierarchy, spacing, contrast, alignment, content, and responsive behavior. Without vision, fix only structural issues supported by reads or renderer metadata; do not invent pixel problems.
8. Verify structure. Re-read the affected tree or nodes. Confirm component instances, interactions, token references, responsive overrides, and target revision. Use viewPage or viewNode for a canonical Loora link.
9. Finish deliberately. If working on a branch, compare it with Main before proposing or applying it. Do not apply, close, or delete anything without the user's authority. Use exportCode only when the user needs a one-way implementation artifact.

Preserve Canvas semantics

• Send structured nodes and fields. Never insert HTML, JSX, Tailwind classes, arbitrary CSS, or code nodes.
• Keep the three schema layers separate: the outer tool envelope, a NodeRef or descriptor locator, and the typed field value. Never move fields between those layers.
• Keep IDs distinct: designId selects a design, draftId selects a branch, pageId selects a Page, componentId selects a component, a NodeRef selects an existing node, and descriptor ref is only a temporary label.
• Use temporary descriptor ref values only inside a single create/insert payload. Save the permanent IDs returned in refs for later calls.
• Use the exact NodeRef returned by readTree for component descendants. instancePath is meaningful; do not replace it with an empty array.
• Edit a component source to change all instances. Patch an instance descendant only for a deliberate visual or content override. Do not structurally insert inside an instance.
• Use Page or component state definitions plus declarative interactions for behavior. Do not simulate application state with hidden duplicate trees when a typed state and action expresses it.
• Use tokens for repeated colors, numbers, and fonts. Use components for repeated structures with shared identity, not merely because two rectangles look similar.
• Set mode on every container that will lay out children. A frame may flow within its parent while still defaulting its own children to absolute positioning.
• Read before patching collection fields. Preserve existing Page/component states, interactions, animation lists, and an existing patch for the same breakpoint unless replacement is intentional.
• Keep motion restrained and purposeful. Prefer the provided presets. Always judge the static composition before animating it.
• Treat deleteNodes, deleteDesign, and closeBranch as destructive. Obtain explicit confirmation, then pass the required confirmed: true.

Work efficiently

• Start with one context call, not a chain of broad reads.
• Read only the subtree being changed. Use searchNodes to locate known copy or names.
• Create a whole coherent section in one nested payload, but split very large pages by section so errors and refinements stay local.
• Batch independent node patches into one patchNodes call.
• Use getScreenshot at useful milestones, not after every field.
• Inspect at the Page's intended desktop width and at least one narrow width when responsive behavior matters.
• Report what changed, which target was used, whether verification was visual or structural, and any remaining uncertainty. Include the returned Loora URL when useful.

Handle failure without thrashing

• On schema rejection, read the error path from the outer envelope inward, then compare it with mcp-schema.md and the live tool schema. Correct one coherent payload; do not retry variants at random.
• If mutation tools disappear from the callable surface, stop. Do not create an empty design and hope later calls become available.
• On an invalid or stale ID, re-read the nearest tree and use returned IDs.
• On a locked node, stop and tell the user unless unlocking it is clearly part of the request.
• On a read-only branch, inspect its status. Reopen a proposed branch only when the user wants further edits.
• On merge revision drift, call compareBranch again. Never reuse stale revisions or guess conflict resolutions.
• On CANVAS_UNAVAILABLE, explain that the legacy design is unsupported; do not attempt to reconstruct or overwrite it.
• On screenshot failure, preserve the successful structured edit, inspect the reported error or skipped images, and be explicit that visual verification is incomplete.
• On usage or plan limits, stop repeated calls and report the exact returned code and remaining work.