Canvas Formatting Standards

Topic: JSON Canvas Spec 1.0 Formatting Standards for Quartz

💡 Best Practices (Patterns)

• Grid Alignment: Snap all x and y coordinates strictly to multiples of 20px. Round group coordinates to 100px for visual harmony.
• Z-Order Array Indexing: Order the nodes array logically: Groups (Layer 0) → Text (Layer 1) → Files/Links (Layer 2). The first node in the JSON array renders at the absolute bottom.
• Implicit Spatial Containment: Define group membership strictly by geometry, not explicitly by parent-child fields. A node belongs to a group ONLY if its (x, y, width, height) is 100% within the group’s boundary.
• Semantic Palette: Restrict colors to semantic presets 1–6 (e.g., 1 Red for critical, 4 Green for stable). Use hex codes only as deliberate escape hatches.
• Explicit Edge Routing: Always explicitly declare fromSide and toSide (top, right, bottom, left) to prevent layout chaos. Ensure directional edges use toEnd: "arrow".
• MANDATORY Visual Feedback Loop: You must deploy to Quartz and screenshot the result at least once per canvas. Overlaps, clipping, and truncated labels are invisible in JSON and require rendered validation.
• ID Prefix Conventions: Use strict kebab-case prefixes for component identification. Standardize on grp-{name}, txt-{name}, f-{name}, lnk-{name}, and e-{from}-{to}.
• Safe Group Padding: Calculate the first child’s Y-coordinate using group_y + group_pad (40px) + label_area (60px). Failing to account for the label area causes immediate text collision.

🔧 Layout Patterns

• Hub-and-Spoke (Mind Map): Central node radiating outward to categorized groups. Ideal for module maps and dependency graphs.
• Kanban Columns: Vertical, side-by-side lanes. Best suited for pipeline status tracking.
• Flowchart: Top-to-bottom or left-to-right pipelines. Designed for sequential data or decision trees.
• Convergence Funnel: Multiple independent source nodes targeting a single output. Optimal for migrations and aggregation.

🚨 Anti-Patterns & Gotchas

• ❌ Aesthetic Coloring: Do not assign colors randomly. Bypassing semantic presets breaks visual consistency.
• ❌ Implicit Edge Routing: Never omit edge sides. Forcing the renderer to guess causes crossed wires.
• ❌ Inverted Z-Order: Do not place groups at the end of the nodes array. This completely occludes child nodes.
• ❌ Absolute File Paths: Do not use full system paths. Paths must be strictly relative to the Quartz content/ directory.
• ❌ Label Truncation: Do not size file nodes under 400px wide. Narrow nodes truncate link titles.
• ❌ Nested Groups: Do not attempt group-inside-group definitions. JSON Canvas Spec 1.0 lacks nested support.
• ❌ JSON Comments: Do not leave // or /* in the payload. Quartz will fail to parse the canvas.

🚀 Quick Start & Integration

• Enable via quartz.config.yaml using the github:quartz-community/canvas-page plugin.
• Embed inside markdown using standard transclusion: ![[canvas-name.canvas]].
• Keep .canvas files under 50KB to avoid excessive Quartz build-time parsing overhead.