# Brand Diagram

> Turn your own brand's colours and type into a publishable, annotated diagram —
> then export it as one standalone HTML file with inline SVG and no JavaScript.

URL: https://brand-diagram.skillsafe.ai/
API: https://api.skillsafe.ai/v1/app-api (app slug `brand-diagram`)
API tutorial: https://brand-diagram.skillsafe.ai/api.html
Token management: https://brand-diagram.skillsafe.ai/tokens.html
Model: `gpt-terra` (currently resolves to `gpt-5.6-terra`)
Pricing: metered per run; the free lanes below cost nothing and need no account.

## What it is for

Most diagram tools give you their house style. This one starts from yours. You
paste the design material you already have — a stylesheet, a `:root` block, a
Style Dictionary or Figma token export, your design-system Markdown table, or a
whole exported HTML page — and the browser reads the palette and the families out
of it, maps them onto the ten semantic roles a diagram needs, derives the dark
variant, and measures the whole thing against WCAG AA. Then you describe what
should be drawn and get a real diagram in that skin.

The deliverable is a file you own: one `.html` with light and dark inline SVG, a
`prefers-color-scheme` swap, a print rule, and no script tag in it at all.

## Three stages, one work object

The work object is a diagram you are about to publish in your brand. The app has
one system prompt and one model, and routes on a `task` field in the run input.

| `task` | What the model does | What it returns |
| --- | --- | --- |
| `skin` | Judges your palette: which colour is the accent and which is an accident, what to demote, how to repair a contrast failure with the smallest change | The ten roles in light and dark, three font families with an `exact`/`fallback` verdict each, and a brand fidelity receipt |
| `design` | Chooses the diagram type from the shape of your material and writes the spec | A normalized diagram spec plus a fidelity ledger of what was merged, collapsed, dropped and kept |
| `annotate` | Adds the editorial layer to a diagram that already exists | At most two italic-serif callouts, the focal decision with a reason, the semantic pattern, and the screen-reader description |

Stage 2 runs in the skin from stage 1. Stage 3 runs on the spec from stage 2 and
is offered as a button on the result, not as a re-paste.

## What is free, with no account and no credits

A large part of the app never touches the model:

- **The token reader.** Resolves `var()` indirection, walks a Style Dictionary or
  Figma token tree to its leaf values, reads SCSS and LESS variables, Markdown
  tables and the `<style>` block of an exported page, and understands `#rgb`,
  `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()` and `hsla()`. It knows that a colour on
  `body` is your page background and the same colour on a `.cta` is your accent.
- **The WCAG audit.** Ten measured checks: ink on paper, muted on paper, soft at
  9px, accent separation and saturation, accent against ink, pure-white paper, the
  dark variant, three families, and whether each detected family can actually be
  embedded in the export. Translucent values are composited over their background
  before measuring, because a hairline at 12 per cent opacity is not the contrast
  its hex suggests.
- **The brief reader.** Suggests the diagram type from the shape of your text and
  builds a real draft from arrow chains (`Client -> Gateway -> Orders`),
  owner-prefixed step lists (`Design: brief, mock, review`), dated bullets,
  indented trees and numbered stages.
- **The renderer, the grammar linter and every export.** Editing the spec and
  re-drawing is free and instant, as many times as you like.

## The eleven diagram types

`flowchart` (shape carries type: oval terminus, rectangle step, diamond decision
with at most three labelled exits, dot merge) · `architecture` (two to four
labelled zones, mandatory above nine nodes) · `swimlane` (one owner per step,
cross-lane handoffs accented) · `sequence` (lifelines, ordered labelled messages) ·
`layers` (four to six bands, one focal) · `pyramid` and funnel (honest widths from
real values, or uniform steps and no values at all) · `nested` (three to five
rings, focal innermost) · `tree` and org chart (one root) · `timeline` (honest
spacing — unequal intervals stay unequal) · `quadrant` (both axes labelled with
both poles, every item placed) · `venn` (two or three sets, never four, one focal
overlap).

## The four output dials

- **Format** — the standalone HTML file is the primary export; SVG, Mermaid,
  Markdown, node and edge CSVs, the spec JSON, CSS custom properties and a
  `style-guide.md` are all generated from the same spec.
- **Size** — `doc-inline` (960x600, default), `doc-wide`, `slide-16x9`,
  `slide-4x3`, `social-og`, `social-square`, `print-a4-landscape`,
  `print-letter-landscape`. Each carries its own type ramp, so a projected slide
  gets 16px node names in 64px boxes rather than shrunken body-copy sizes.
- **Detail** — `faithful` (24 nodes, 32 edges), `balanced` (12 and 16, the
  default), `simplified` (7 and 9, no sublabels). Over budget, the degrade ladder
  runs in a fixed order and every cut is reported.
- **Audience** — `engineer` (exact names, ports, protocols, versions), `mixed`
  (component names and plain verbs), `executive` (capabilities and outcomes, no
  vendors or infrastructure).

## Accountability

The free reader's findings are sent into the paid run as facts, and every one must
come back reconciled: the model returns a `coverage` array with one entry per
finding id, marked `applied` or `set-aside` with a reason. The page then checks
that reconciliation and names anything the model never answered for. After a skin
run the WCAG audit is re-measured against what the model actually returned, so a
repair that was claimed but not made is visible rather than taken on trust.

## Raster export

The figure can be saved as a **PNG at twice its on-screen size**, or copied straight
to the clipboard as an image, from the buttons under the diagram. It is rasterised in
the browser from the SVG already on screen — no upload, no run, no cost — and it is
painted on the brand's paper colour rather than left transparent, because it is going
onto a white slide or into a dark thread. The `.svg` and the standalone `.html` remain
the better choice for a README or a docs build, where text should stay selectable.

**Changing the size is free.** The size dial above the figure re-renders it at
`doc-inline`, `doc-wide`, `slide-16x9`, `social-og` or `print-a4-landscape` in the
browser. `size` is consumed only at render time, so getting a slide version of a
diagram you already have costs nothing and does not re-run the model.

## What it does not do

- **It cannot fetch your website.** The page may only reach its own origin and the
  SkillSafe API, so "point it at my URL" is not on offer. Paste the stylesheet or
  the tokens — the same information without a screenshot's guesswork.
- **The export names your webfont rather than embedding it.** A licensed family
  stays licensed, and the file says which families a reader's machine will have to
  substitute.

## Persistence

Runs are saved to a declared `diagrams` collection on your SkillSafe account and
mirrored in the browser for instant paint. Semantic search over past diagrams is
live (title, diagram type and headline are the embedded fields). The skin from
your most recent run is restored on your next visit, so a returning user never
onboards their brand twice.

## Source and credit

Derived from **@cathrynlavery/diagram-design**
(https://skillsafe.ai/skill/@cathrynlavery/diagram-design/ ·
https://github.com/cathrynlavery/diagram-design), an MIT-licensed agent skill that
draws technical and product diagrams as standalone HTML with inline SVG. Its
grammar is used here with credit: the ten semantic colour roles and the inversion
rule, one accent, shape carries type, honest widths and honest spacing, the
italic-serif annotation callout with its dashed leader and landing dot, the
sketchy displacement variant, the node treatment table, and the four output dials.

The `style-guide.md` export is written in the shape that skill's own
`references/style-guide.md` uses, so it can be dropped into an installed copy and
every diagram the agent draws afterwards inherits the same brand.

This is a derived work and is not affiliated with that skill's author.