# Canvas: Application Mode Application-mode is one of Gakaso's two project kinds (the other is diagram mode — see `/canvas/diagram-mode.md`). It is a tldraw-based infinite canvas populated with **semantic shapes**: UI components that carry both visual style and machine-readable meaning. ## Two classes of canvas objects Gakaso's application canvas distinguishes two kinds of objects on the same surface: ### 1. Semantic shapes (`gks-*`) Design-authoring primitives with an explicit component type and role. Each carries a semantic ID (`gks-{type}-{uuid}`) plus style, layout, and semantic metadata, and is rendered using the project's design-system variants rather than as a raw drawing. Implemented semantic shape types include: `screen`, `button`, `card`, `nav`, `header`, `footer`, `sidebar`, `modal`, `form`, `table`, `text`, `image`, `list`, `container`. Use these when you are *authoring* a UI from scratch — they are what code export and design-token application operate on. ### 2. Faithful frames (`gks-frame`) A platform-neutral, high-fidelity primitive used when **importing already-existing UI** rather than authoring new UI. A `gks-frame` holds only neutral visual facts — fill, stroke, corner radius, shadow, opacity, typography, image — plus an original `nodeType` field that records what the source element actually was (e.g. `button`, or a native platform type), so it can later be mapped back to the right native component on read-back. Faithful frames are not bound to HTML/CSS; the same primitive is meant to represent a native iOS/Android element just as well as a web element. Use `gks-frame` objects when the task is "bring this real UI into Gakaso and let a human edit it without losing fidelity," not when the task is "design something new." See `/mcp/faithful-roundtrip.md` for the full import → edit → read-back flow. ## Creating a component: exact call shape `gakaso_add_component` takes `{ projectId, component }`, where `component` is: ``` { id?: string, // auto-generated (a UUID) if omitted type: string, // e.g. "button", "card", "gks-node", "gks-edge" — see /canvas/diagram-mode.md for diagram types name: string, bounds: { position: { x: number, y: number }, size: { width: number, height: number } }, style?: { ... }, // free-form style properties props?: { ... }, // type-specific properties (e.g. edge sourceId/targetId — see /canvas/diagram-mode.md) parentId?: string, // nest under an existing container pageId?: string, // default: "main" for gakaso_add_component (note: the faithful-import tools default to "default" instead — see /mcp/faithful-roundtrip.md; check which page id you're actually targeting) } ``` Note `bounds` is a **nested** `{ position, size }` object here, not flat `x`/`y`/`width`/`height` — the faithful round-trip tools use a flat shape instead, so don't copy geometry payloads between the two families without reshaping them. ## Editing model - Canvas edits (position, size, style, semantic metadata) sync in real time via a CRDT (Y.js) so multiple humans/agents can operate on the same canvas concurrently. - Objects can carry a linked **context** (a requirement reference plus a design rationale string) that shows up in `gakaso_export_design_spec`, `gakaso_export_intermediate`, and the descriptions in `gakaso_get_computed_a11y_tree`. You don't set this directly as a field on `gakaso_add_component` — it's populated when `gakaso_import_requirements` auto-links an imported requirement to a matching canvas object (by name/pattern matching). If a human gives you formal requirements text alongside a build request, importing it via `gakaso_import_requirements` first (before or after creating the matching components) is what wires that traceability up — creating components alone does not. - Layout support includes an auto-layout model (direction, gap, padding, min/max sizing, fill/hug/fixed sizing — set via `style`/`props` and inspectable via `gakaso_get_computed_styles`) and responsive breakpoints (`gakaso_set_breakpoints` / `gakaso_get_responsive_layout`), plus variants (`gakaso_create_variant` / `gakaso_switch_variant`, e.g. default/hover/active/disabled/error) for stateful components. - Multiple pages can exist per project (`gakaso_create_page` / `gakaso_list_pages` / etc.); each project can also have multiple canvas objects nested via `parentId` (containers). ## How you, as an agent, typically touch this Rather than driving the browser UI, you operate on application-mode canvases through MCP tools — creating/updating/deleting components (`gakaso_add_component` / `gakaso_update_component` / `gakaso_delete_component`, or the batch variants for many at once), querying by type or metadata (`gakaso_query_components`), grouping (`gakaso_group_components`), aligning/distributing (`gakaso_align_components` / `gakaso_distribute_components`), applying variants, and reading back computed styles or a11y information for verification (`gakaso_get_computed_styles`, `gakaso_get_computed_a11y_tree`, `gakaso_a11y_check` / `gakaso_audit_accessibility`). The full tool catalog is in `/mcp/overview.md`; the categories most relevant to application-mode canvases are "canvas components/pages" and "design tokens." If you are generating a UI from a natural-language request rather than editing an existing one, also read `/design/diagram-intelligence.md`'s companion resource — `gakaso://manuals/design-principles` — before laying anything out; it encodes structured design guidance (visual hierarchy, spacing, typography, color, accessibility, and more) intended specifically for agents producing UI or diagrams without a human designer in the loop. ## Real-time collaboration cues When a human and an agent (or multiple agents) are on the same canvas simultaneously, agent cursors are visually distinguished from human cursors (a distinct icon plus the agent's name), so humans can tell at a glance which changes are being made by which actor.