Loora Design Guide

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.