Spec

Theme manifest spec

The theme contract keeps generated Excalidraw diagrams portable across agents, renderers, and brand styles. A theme is both machine-readable tokens and agent-readable instructions.

Files in a theme package

File	Required	Purpose
`theme.json`	yes	Manifest: name, version, inheritance, metadata, semantic roles.
`palette.json`	yes	Machine-readable color tokens used by renderers and MCP tools.
`palette.md`	yes	Agent-readable guidance explaining when to use each token.
`typography.json`	no	Font family, sizes, line height, and emphasis policy.
`elements/*.json`	no	Per-element defaults such as box, arrow, and callout styles.
`layouts/*.md`	no	Composition presets such as concept cards, pipelines, and layered stacks.
`preview.png`	recommended	Preview image for registries and docs.

Minimal manifest

{
  "name": "my-brand",
  "version": "0.1.0",
  "description": "Brand theme for ACME Co.",
  "extends": "default-sketchy"
}

Full manifest

{
  "name": "my-brand",
  "version": "1.2.0",
  "description": "Brand theme for ACME Co.",
  "extends": "default-sketchy",
  "author": "Jane Doe <jane@acme.com>",
  "homepage": "https://github.com/acme/excalidraw-theme-my-brand",
  "license": "MIT",
  "preview": "preview.png",
  "roles": {
    "ink": "#1a1a1a",
    "paper": "#fff8f3",
    "accent": "#ff5722",
    "accent_alt": "#ffa000",
    "evidence_bg": "#f5f5f5",
    "evidence_text": "#212121",
    "muted": "#9e9e9e"
  }
}

Required fields

Field	Type	Constraint
`name`	string	kebab-case; should match the npm package suffix after `theme-`.
`version`	string	semver.

Semantic roles

Role	Meaning	Required
`ink`	Primary text and strokes.	yes
`paper`	Main background.	yes
`accent`	The argument color. Use one accent per diagram.	yes
`muted`	Secondary text, grid lines, dividers.	yes
`accent_alt`	Secondary accent for explicit comparison diagrams.	no
`evidence_bg`	Background for code, JSON, and concrete evidence artifact boxes.	no
`evidence_text`	Text inside evidence artifacts.	no
`warning`	Soft warning state.	no
`danger`	Hard error state.	no

Inheritance

A child theme can extend default-sketchy or another theme. Resolution merges in this order, with child values winning:

palette.json deep-merged key by key.
typography.json deep-merged key by key.
elements/*.json replaced file by file.
layouts/*.md replaced file by file.

Versioning

Change	Bump
Typo fix in `palette.md`, no token value changed.	PATCH
Add a semantic role, layout, or element override.	MINOR
Change existing colors or typography in a way that shifts renders.	MAJOR

Pin theme versions in CI golden-image pipelines when exact render reproducibility matters.