Draw in your colours

Map archgram's colour roles to your design tokens, and let archgram check they are readable.

archgram draws in black and white by default. Colour appears only in the technology logos and in what happens on a flow, a green border on a card a request passes and red where a step refuses it. To match your design system, map archgram's colour roles to your design tokens.

With your agent#

Ask for your colours, and the agent finds them and writes the mapping.

Draw the architecture in our colours.

It looks for your design tokens first, then your styling code (CSS custom properties, a Tailwind theme, Sass variables), then colours you name. It keeps your diagram monochrome unless you ask for colour in the icons. Without a request for colours, it draws in archgram's own.

By hand#

Your colours reach archgram through two files.

Your tokens, as a resolver in the W3C Design Tokens format (2025.10). If you keep tokens already, use your own resolver.
A mapping, archgram.theme.json at your project's root, which names the resolver and the token for each of archgram's roles.

A resolver with the colours inline, at docs/diagrams/theme/archgram.resolver.json:

json

{
  "version": "2025.10",
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [{ "color": { "$type": "color",
          "canvas": { "$value": "#fafaf9" }, "card": { "$value": "#ffffff" },
          "badge": { "$value": "#f5f5f4" }, "border": { "$value": "#d6d3d1" },
          "line": { "$value": "#78716c" }, "text": { "$value": "#1c1917" },
          "muted": { "$value": "#57534e" }, "success": { "$value": "#15803d" },
          "danger": { "$value": "#b91c1c" } } }],
        "dark": [{ "color": { "$type": "color",
          "canvas": { "$value": "#0c0a09" }, "card": { "$value": "#1c1917" },
          "badge": { "$value": "#292524" }, "border": { "$value": "#44403c" },
          "line": { "$value": "#78716c" }, "text": { "$value": "#fafaf9" },
          "muted": { "$value": "#a8a29e" }, "success": { "$value": "#4ade80" },
          "danger": { "$value": "#f87171" } } }]
      },
      "default": "light"
    }
  },
  "resolutionOrder": [{ "$ref": "#/modifiers/theme" }]
}

And the mapping beside your package.json:

json

{
  "version": 1,
  "resolver": "docs/diagrams/theme/archgram.resolver.json",
  "roles": {
    "canvas": "color.canvas", "card": "color.card", "badge": "color.badge",
    "card-edge": "color.border", "connector": "color.line", "frame": "color.line",
    "text": "color.text", "text-muted": "color.muted", "signal-core": "color.card",
    "icon-core": "color.text", "icon-ai": "color.text",
    "icon-build": "color.text", "icon-client": "color.text",
    "signal-pass": "color.success", "signal-refusal": "color.danger"
  },
  "themes": {
    "light": { "inputs": { "theme": "light" } },
    "dark": { "inputs": { "theme": "dark" } }
  }
}

The mapping sits at the root because archgram reads a theme's files only in the mapping's folder and below it.

The roles#

Map by meaning, not by name. A role the mapping leaves out keeps archgram's colour.

Role	Your colour for
`canvas`	The page background
`card`	A raised surface, such as a card or a panel
`badge`	A subtle surface, such as a muted background
`card-edge`	Borders
`connector`, `frame`	A stronger border or a muted line, readable as a line
`text`, `text-muted`	Main and secondary text
`signal-core`	The card surface
`icon-core`, `icon-ai`, `icon-build`, `icon-client`	Main text, to keep the diagram monochrome, or a colour for each kind of part
`signal-pass`, `signal-refusal`	Success and danger, green and red

Check it#

npm exec -- archgram theme check archgram.theme.json

pnpm exec archgram theme check archgram.theme.json

yarn archgram theme check archgram.theme.json

It prints each role's colour in light and dark, with the token it came from.

light:
  badge          #f5f5f4  {color.badge}
  canvas         #fafaf9  {color.canvas}
  card           #ffffff  {color.card}

archgram holds your colours to the same contrast as its own, in both themes, and refuses a pair that falls short.

archgram.theme.json /themes/dark: dark: `text-muted` on `card` is 1.46:1, below 4.5:1
2 problems in the theme archgram.theme.json

Map a stronger token for that role, or leave the role out to keep archgram's colour.

Draw with it#

npm exec -- archgram build docs/diagrams/architecture.archgram.yaml --theme-file archgram.theme.json

pnpm exec archgram build docs/diagrams/architecture.archgram.yaml --theme-file archgram.theme.json

yarn archgram build docs/diagrams/architecture.archgram.yaml --theme-file archgram.theme.json

The mapping replaces the spec's palette. Every field of the mapping is in the spec format.