LLMs & AI Agents

Feed this specification to your AI coding agent (Cursor, Windsurf, Copilot, or Claude Code) to build with @filekit-studio/sketch and @filekit-studio/diagram without hallucinated props or unstyled canvases.

Click Copy Markdown in the top right to copy the entire specification into your clipboard, or use the dropdown to download AGENTS.md or .txt.

1. Quick Installation & Peer Dependencies

bun add @filekit-studio/sketch @filekit-studio/diagram
# or: npm i @filekit-studio/sketch @filekit-studio/diagram

Framework Support: React 18 and React 19.
Next.js: Fully compatible with Next.js 14, 15, and 16 (App Router and Pages Router).
Client Isolation: When rendering inside the Next.js App Router, mark wrapper components with "use client".

2. Critical Invariant: Stylesheet Imports

MANDATORY: You must import a stylesheet once at your app root or in the component file. Without CSS, toolbars, property panels, and popups will render unstyled.

TypeScript (TSX)

// Pick one theme stylesheet:
import "@filekit-studio/sketch/styles.css";      // Modern Tailwind CSS v4 styling (Default)
// or:
import "@filekit-studio/sketch/classic.css";     // Classic clean wireframe styling
import "@filekit-studio/sketch/neumorphic.css";  // Soft extruded neumorphic styling

3. Package 1: `@filekit-studio/sketch` (Interactive Whiteboard)

Primary Embed Component

TypeScript (TSX)

"use client";

import { SketchEditor, SketchViewer } from "@filekit-studio/sketch";
import "@filekit-studio/sketch/styles.css";

export function ArchitectureBoard() {
  return (
    // CONTAINER RULE: Always provide an explicit height or bounded viewport.
    <div className="w-full h-screen min-h-[600px] overflow-hidden">
      <SketchEditor
        theme="system"               // "light" | "dark" | "system"
        className="w-full h-full"
        showGuideButton={true}        // Optional: mount guide button in header
        guideHref="/docs"             // Optional: link for guide button
        onOpenGuide={() => {}}        // Optional: click callback instead of navigation
      />
    </div>
  );
}

`<SketchEditor />` Props Reference

Prop	Type	Default	Description
`initialElements`	`SketchBoardElement[]`	Starter shapes	Initial elements to mount on the board.
`theme`	`"light" \| "dark" \| "system"`	`"system"`	Visual theme. Auto-detects dark/light if `"system"`.
`className`	`string`	`undefined`	Container CSS classes.
`readOnly`	`boolean`	`false`	Read-only mode; disables editing tools and transformation.
`uiConfig`	`Partial<SketchUIConfig>`	All enabled	Granular toggles for 54 toolbar and dock buttons.
`showGuideButton`	`boolean`	`false`	Mounts a guide button directly to the left of the theme toggler.
`guideHref`	`string`	`undefined`	Target link for the guide button.
`onOpenGuide`	`() => void`	`undefined`	Intercepts click on guide button to trigger custom dialog.

Architecture Stencils (675+ Vector Logos)

Keyboard shortcut: Ctrl + I / Cmd + I.
11 Categories: All, AI & Machine Learning, Frontend & UI, Backend & Runtimes, Databases & Storage, Cloud & DevOps, Authentication & Security, Tools & Utilities, Design & Media, Blockchain & Web3, Hardware & IoT.
Display modes: Badge Card (rounded icon + name tag) or Pure Logo (isolated icon tile).

Multi-Format Vector Export

TypeScript (TSX)

import {
  exportToSvg,
  exportToPng,
  exportToPdf,
  downloadBlob,
} from "@filekit-studio/sketch/export";

// Lossless SVG
const svg = await exportToSvg(elements, { theme: "dark", padding: 40 });

// Lossless PNG at 2x retina scale
const png = await exportToPng(elements, { scale: 2, background: true });
downloadBlob(png, "architecture.png");

// Vector PDF
const pdf = await exportToPdf(elements, { pageSize: "a4", landscape: true });
downloadBlob(pdf, "architecture.pdf");

4. Package 2: `@filekit-studio/diagram` (Diagram-as-Code)

Declarative Architecture Syntax

TypeScript (TSX)

"use client";

import { Diagram, type DiagramData } from "@filekit-studio/diagram";
import "@filekit-studio/sketch/styles.css";

const systemData: DiagramData = {
  title: "Cloud Native Event Pipeline",
  direction: "LR", // "LR" (left-to-right) | "TB" (top-to-bottom) | "RL" | "BT"
  nodes: [
    { id: "edge", label: "Cloudflare Ingress", shape: "diamond", color: "amber", badge: "EDGE" },
    { id: "api", label: "Core Gateway Pod\n(Node.js)", shape: "rounded", color: "indigo", badge: "K8S" },
    { id: "db", label: "Aurora Database\n(PostgreSQL)", shape: "cylinder", color: "emerald", badge: "DATA" },
    { id: "cache", label: "Redis Cluster", shape: "cylinder", color: "rose", badge: "CACHE" }
  ],
  edges: [
    { from: "edge", to: "api", label: "HTTPS / mTLS", color: "#f59e0b" },
    { from: "api", to: "db", label: "Read / Write Pool", color: "#10b981" },
    { from: "api", to: "cache", label: "In-Memory Hit", color: "#ec4899" }
  ],
  groups: [
    { id: "vpc", label: "AWS us-east-1 VPC Subnet", nodeIds: ["api", "db", "cache"], color: "purple" }
  ],
  layout: {
    direction: "LR",
    edgeRouting: "elbow", // "elbow" | "smooth" | "straight"
    nodeSpacing: 95,
    rankSpacing: 220,
    clusterSpacing: 220,
    groupPadding: 56
  }
};

export function SystemDesign() {
  return (
    <Diagram
      data={systemData}
      theme="system"
      height={460}
      interactive={true}
    />
  );
}

5. Spacing, Geometry & Layout Specification

The auto-layout engine applies deterministic Sugiyama/Dagre layered ranking:

JSON

{
  "layout": {
    "direction": "LR",
    "nodeSpacing": 95,
    "rankSpacing": 220,
    "clusterSpacing": 220,
    "groupPadding": 56,
    "intraRankSpacing": 120,
    "defaultNodeWidth": 210,
    "defaultNodeHeight": 90,
    "padding": 90,
    "edgeRouting": "elbow"
  }
}

Spacing Parameters Glossary

Parameter	Default	Mechanics & Guidance
`nodeSpacing`	`95`	Perpendicular gap between sibling nodes on the same rank. Compact: `50`; Spacious: `100–120`.
`rankSpacing`	`220`	Distance between sequential columns/layers. Always keep `rankSpacing >= 200` when edge badges carry protocol labels (e.g. `[ HTTPS / mTLS ]`) to prevent node card overlap.
`clusterSpacing`	`220`	Clearance gap between compound group frames. Prevents multi-VPC boxes from colliding.
`groupPadding`	`56`	Internal cushion inside compound group frames around member nodes.
`intraRankSpacing`	`120`	Distance between ranks strictly located inside a compound group frame.
`defaultNodeWidth`	`210`	Baseline node width in pixels. Override per node via node `width`.
`defaultNodeHeight`	`90`	Baseline node height in pixels. Override per node via node `height`.
`padding`	`90`	Global canvas margin surrounding the entire diagram graph.

6. Shapes, Colors & Routing Reference

Supported Node Shapes (`shape`)

"rounded": Rounded corner card (microservices, pods, lambdas).
"rect": Sharp corner rectangle.
"diamond": Decision points, API gateways, load balancers, WAF.
"cylinder": Databases, storage buckets, ACID stores, Redis.
"stadium": Capsule/pill for queues, topics, or endpoints.
"cloud": External third-party networks, internet ingress.
"parallelogram": I/O data pipelines and stream buffers.
"hexagon": Hexagonal architecture adapters.

Semantic Colors (`color`)

"indigo", "purple", "emerald", "amber", "rose", "sky", "cyan", "zinc".

Routing & Obstacle Evasion

edgeRouting:
- "elbow" (Default): 90° orthogonal elbow bends with smooth rounded radii. Highest readability.
- "smooth": Continuous Bezier spline curves.
- "straight": Direct geometric ray lines.
Corridor Seeking: Connectors spanning across distant tiers automatically find open vertical clearance gutters between columns.
Submerged Passthrough Tunneling: When a connector must traverse underneath an intermediate node, it dims to a 50% dashed stroke (X-ray passthrough effect) and returns to a 100% solid stroke upon clearing the shape boundary.

7. Agent Guardrails & Negative Constraints (DO NOT DO)

❌ DO NOT omit the CSS import: Never render <SketchEditor /> or <Diagram /> without importing @filekit-studio/sketch/styles.css.
❌ DO NOT use unconstrained auto-height: Always give the canvas container an explicit bounded height (e.g., className="h-[600px] w-full" or h-screen).
❌ DO NOT compress rank spacing with long edge labels: If edge labels exceed 15 characters, maintain rankSpacing >= 220 to prevent label chips from overlapping node cards.
❌ DO NOT manually compute (x, y) coordinates for @filekit-studio/diagram: Let the layout engine position nodes automatically.
❌ DO NOT mutate element IDs directly: Always use immutable updates or let the controller handle element lifecycle.

1. Quick Installation & Peer DependenciesCopy Anchor Link

2. Critical Invariant: Stylesheet ImportsCopy Anchor Link

3. Package 1: @filekit-studio/sketch (Interactive Whiteboard)Copy Anchor Link

Primary Embed ComponentCopy Anchor Link

<SketchEditor /> Props ReferenceCopy Anchor Link

Architecture Stencils (675+ Vector Logos)Copy Anchor Link

Multi-Format Vector ExportCopy Anchor Link

4. Package 2: @filekit-studio/diagram (Diagram-as-Code)Copy Anchor Link

Declarative Architecture SyntaxCopy Anchor Link

5. Spacing, Geometry & Layout SpecificationCopy Anchor Link

Spacing Parameters GlossaryCopy Anchor Link

6. Shapes, Colors & Routing ReferenceCopy Anchor Link

Supported Node Shapes (shape)Copy Anchor Link

Semantic Colors (color)Copy Anchor Link

Routing & Obstacle EvasionCopy Anchor Link

7. Agent Guardrails & Negative Constraints (DO NOT DO)Copy Anchor Link

On this page

1. Quick Installation & Peer Dependencies

2. Critical Invariant: Stylesheet Imports

3. Package 1: `@filekit-studio/sketch` (Interactive Whiteboard)

Primary Embed Component

`<SketchEditor />` Props Reference

Architecture Stencils (675+ Vector Logos)

Multi-Format Vector Export

4. Package 2: `@filekit-studio/diagram` (Diagram-as-Code)

Declarative Architecture Syntax

5. Spacing, Geometry & Layout Specification

Spacing Parameters Glossary

6. Shapes, Colors & Routing Reference

Supported Node Shapes (`shape`)

Semantic Colors (`color`)

Routing & Obstacle Evasion

7. Agent Guardrails & Negative Constraints (DO NOT DO)