# VizCharter

A local MCP server for Claude Code that generates **presentation-grade visualizations**: cloud architecture diagrams with 1100+ official AWS / GCP / Azure icons, charts and KPI dashboards, poster-style infographics — semantic containers and connectors, auto layout, and multi-format export (SVG, PNG, JPG, vector PDF).

No headless browser. Fully offline after install. Every diagram keeps a re-editable `.vizc.json` source next to its exports, so "open the Q2 platform diagram and add EventBridge" works months later.

## Install

```bash
claude mcp add vizcharter -- npx -y vizcharter
```

Requires Node ≥ 20. Everything (icon packs, fonts, rasterizer) ships in the package.

## Tools

| Tool | Purpose |
| --- | --- |
| `vizcharter_create` | Validate spec → auto-layout (ELK) → render → lint → export. Returns a PNG preview inline so the model can see and iterate. |
| `vizcharter_update` | Patch an existing `.vizc.json` (RFC 7386 merge patch) and re-render in place. |
| `vizcharter_export` | Re-export an existing diagram to more formats/scales. |
| `vizcharter_icons` | Fuzzy-search the bundled official icon packs (`"queue"` → SQS…). |
| `vizcharter_themes` | List built-in themes or validate custom brand overrides (WCAG-checked). |

## Spec example

```json
{
  "family": "architecture",
  "title": "Sample Platform",
  "theme": "vizcharter-light",
  "direction": "DOWN",
  "containers": [
    { "id": "edge", "type": "layer", "label": "Presentation Layer" }
  ],
  "nodes": [
    { "id": "cdn", "icon": "aws.cloudfront", "label": "Amazon CloudFront", "parent": "edge" },
    { "id": "fn", "icon": "aws.lambda", "label": "AWS Lambda" }
  ],
  "edges": [
    { "from": "cdn", "to": "fn", "kind": "sync", "label": "invoke" }
  ]
}
```

Every family also accepts an optional `meta` footer — `{ author, org, project, version, date, classification, source, note }` — rendered as a slim hairline band with an outlined classification chip. Ask for "authorship / version / confidential marking" and it appears, consistently, in every theme and export format.

Container types (`region`, `account`, `vpc`, `subnet`, `az`, `layer`, `group`) style themselves per theme — layers rotate through soft pastel tints, VPCs get vendor-convention borders. Edge kinds (`sync`, `async`, `config`, `data`) get distinct strokes and an auto-generated legend.

See `examples/earth2studio.vizc.json` for a full reference recreation.

## Themes & brand

`vizcharter-light` (default), `vizcharter-dark`, `aws` — palettes fuse a warm house brand (orange `#f78c4e`, sunburnt red `#f66568`, washed blue `#476b76`) with AWS squid ink + Cloudscape blue. Titles and section labels render in **Faktum** when the brand fonts are installed locally (`node scripts/fetch-assets.mjs --brand-fonts` — commercial font, gitignored and excluded from the npm package; Inter fallback otherwise). Base themes:

`vizcharter-light` (default), `vizcharter-dark`, `aws` (AWS Architecture Icons group conventions). Custom brand themes via `spec.themeOverrides`, validated with WCAG contrast checks.

## Development

```bash
npm install
npm test            # vitest suite (golden files, pixel checks, MCP integration)
npm run build       # tsc → dist/
node scripts/fetch-assets.mjs --icons   # maintainer-only: refresh bundled assets
node scripts/render-example.mjs examples/earth2studio.vizc.json /tmp/out.png
```

Icon assets are © their respective vendors, redistributed per each provider's architecture-icon usage terms. Fonts: Inter and JetBrains Mono (SIL OFL, licenses bundled).

## Spec families

- **`architecture`** — node/container/edge diagrams, ELK auto-layout, official vendor icons.
- **`chart`** — bar (plain/stacked/grouped), line, area, donut, pie, rose, venn (2–3 sets), KPI tile rows.
- **`canvas`** — infographics: poster templates (`sectioned-poster`, `comparison-columns`, `winding-roadmap`, `radial-hub` — see `vizcharter_templates`), freeform layers (wrapped text, shapes, icons), embedded chart/architecture specs, and a raw-SVG escape hatch.

## Documentation

- **[User Guide](docs/user-guide.md)** — install, the six tools, all three spec families with field reference, themes & brand, provenance, exports, lint codes.
- **[Contributor Guide](docs/contributing.md)** — architecture, workflow (tests *and* eyes on pixels), the gotcha ledger (ELK/resvg/font traps already paid for), how-to recipes.
- Design spec and implementation plans live in `docs/superpowers/`.

## Roadmap

- Client-brand theme files (`vizcharter.theme.json` loading), more canvas templates.
- PowerPoint-friendly exports; npm publish for `npx -y vizcharter`.