references/type-org-chart.md

Org Chart / Responsibility Map

Best for: human teams, agent teams, support escalation maps, role ownership, routing maps, and any hierarchy where the reader needs to know who owns what rather than just parent → child structure.

Use Org Chart instead of Tree when the nodes are people, agents, teams, roles, or accountable owners. A tree shows generic hierarchy. An org chart shows responsibility, invocation paths, and coverage gaps.

Layout conventions

• Root owner or front door at top center. Use one coral focal node for the person/team/agent that receives ambiguous work.
• Tier 1 nodes are departments, pods, queues, or primary routing buckets. Keep them horizontally aligned.
• Tier 2 nodes are responsible owners or specialists. If there are more than 8 specialists, group them under pod nodes instead of making one giant row.
• Use orthogonal connectors: vertical drop from parent → horizontal bus → vertical drops to children. No diagonal lines.
• Each node should answer three questions when space allows:
  1. Name — human-readable role/person/agent in Geist sans.
  2. How to invoke — Slack handle, queue, issue prefix, or trigger in Geist Mono.
  3. Scope — 2–4 terse ownership words, not a paragraph.
• Show non-Slack / not-yet-live owners with dashed optional styling rather than hiding them. Missing routes are operationally important.
• Put escalation / approval rules in a small side callout or footer strip, not as extra org nodes.

Node treatments

• Front door / command center: focal treatment (accent-tint + accent).
• Team / pod / department: backend treatment (white + ink).
• Individual agent / owner: store or external treatment depending on whether it is active in the system.
• Gap / needs setup: optional dashed treatment.
• Approval gate: security treatment, separate from reporting hierarchy.

Complexity budget

• Max visible org nodes: 12. If more, create an overview org chart plus separate detail charts per pod.
• Max depth: 4 tiers.
• Max direct reports under one parent: 5. If there are more, introduce grouping nodes.
• Max coral nodes: 1. The org chart's job is clarity, not highlighting everything.
• Max side callouts: 2.

Anti-patterns

• Using a swimlane when the user's real question is "who does what?" Swimlanes explain process; org charts explain ownership.
• Drawing every person/agent as an identical box. It hides the front door, specialists, gaps, and escalation paths.
• Cramming full job descriptions into nodes. Keep scope phrases short and move detail to summary cards below.
• Showing unavailable / not-yet-wired agents as normal active owners. Use dashed optional styling so gaps are visible.
• Repeating Slack handles in body paragraphs when a node sublabel can carry the invocation path.
• Floating legends in the org area. Use the standard bottom legend strip.

Examples

• assets/example-org-chart.html — minimal light
• assets/example-org-chart-dark.html — minimal dark
• assets/example-org-chart-full.html — full editorial