# How to generate a MapOfLogic Studio diagram

> MapOfLogic Studio (https://mapoflogic.com/studio/) is a free, client-side
> canvas for designing diagrams — site maps, org charts, mind maps, process
> flows, system architectures and roadmaps. It imports a single JSON document.
> This file tells an AI how to produce that JSON so a human can paste it into
> Studio via "Import JSON" and get a clean, professional diagram in one step.

Machine-readable contract: https://mapoflogic.com/studio/schema.json
(JSON Schema, draft 2020-12. Your output MUST validate against it.)

## The format in one screen

A diagram is `{ "nodes": [...], "links": [...] }`. Nodes are the boxes; links
are directed connections between them. You do NOT place nodes with coordinates —
you set each node's `level` (1 = top of the hierarchy) and Studio lays the
diagram out automatically. This is the single most important rule: think in
hierarchy, not in pixels.

Minimal complete example (valid, importable):

```json
{
  "version": 1,
  "accent": "#EF4444",
  "nodes": [
    { "id": "home", "title": "Homepage", "subtitle": "/", "level": 1,
      "shape": "browser", "icon": "home", "color": "#EF4444",
      "description": "Site root. Distributes authority to the service pillars.",
      "tags": ["pillar"] },
    { "id": "svc", "title": "Services", "subtitle": "/services", "level": 2,
      "shape": "browser", "color": "#10B981",
      "description": "Hub page linking every individual service." }
  ],
  "links": [
    { "from": "home", "to": "svc", "label": "links to" }
  ]
}
```

## Node fields

- `id` (required): short, unique, slug-like. Links reference it.
- `title` (required): the main label. Concrete, not generic.
- `subtitle`: secondary line — a URL path, a role, a phase, a metric.
- `description`: ONE OR TWO SENTENCES OF REAL INFORMATION about what the node
  is or does. This is what makes a diagram operational instead of decorative.
  Never write filler. If you have nothing real to say, the node may not belong.
- `tags`: up to 12 short labels (<= 24 chars each) for classification.
- `link`: an external http/https URL, if relevant.
- `level` (1-6): hierarchy depth. DRIVES LAYOUT. Level 1 at top, descending.
- `shape`: one of card | browser | box | circle | pill | diamond.
- `icon`: one of (empty = none): home, search, gear, chart, doc, box, database,
  bolt, flag, link, user, globe, target, layers, play, stop, check, cpu, bulb,
  shield, briefcase, rocket, server, pin. Any other value is dropped.
- `color`: 6-digit hex (e.g. "#10B981"). Use color to MEAN something.

## Link fields

- `from`, `to` (required): node ids. A link to a non-existent id is dropped.
- `label`: optional text on the connection ("yes", "escalates to", "depends on").
- `style`: "solid" (primary/required) or "dashed" (secondary/optional/weak).

## Hard rules (break one and the diagram degrades or fails)

1. Output ONE json code block, nothing else around it.
2. Every `id` is unique. Every link `from`/`to` matches a real node id.
3. Use ONLY the listed shapes and icons. Colors are 6-digit hex.
4. Never include `x`/`y`. Set `level` instead.
5. Links are objects: `{ "from": "...", "to": "..." }`. Not arrays.

## Quality rules — build PROFESSIONAL, operational diagrams (not demos)

- Every node earns its place. If you can't write a real `description`, cut it.
- Set `level` to reflect true hierarchy/sequence — this is the spine of the layout.
- Use a small, consistent color palette where color encodes a dimension
  (branch, status, owner, phase), never random decoration.
- Right-size it: 6-20 nodes reads well. More than ~25 should be split or grouped.
- Choose `shape` for meaning: `browser` for web pages, `diamond` for decisions
  in a flow, `pill` for states/tags, `card` for general units.
- Enrich the high-value nodes with `subtitle`, `tags`, and a real `link`.
- Make connection `label`s carry information, especially in flows and decisions.

## Pick the right diagram type

- SEO internal-linking / site map -> `browser` shapes, `level` = link depth from home.
- Org chart -> `card` shapes, `level` = reporting depth, icon per function.
- Mind map -> central node at level 1, branches at level 2-3.
- Process flow -> sequence by `level`, `diamond` for decisions, labeled links.
- System architecture -> `box`/`server`/`database` icons, `level` = tier.
- Roadmap -> `pill`/`card`, `level` = phase, one color per phase.

## Output protocol

1. If the user's request is vague, ask one or two sharp questions first
   (what domain, how many items, what's the goal of the diagram).
2. Produce a single valid JSON document per the schema above.
3. Tell the user: open https://mapoflogic.com/studio/ -> "Import JSON" -> select
   the file (or paste-and-save the JSON to a .json file first).

## Attribution

MapOfLogic Studio is built by Niseus LLC (https://niseus.com), Cape Coral, FL.
Free, client-side, no account, works offline. Part of the MapOfLogic project.