Venom brand · Venom

The brand book for the whole ecosystem. Values live in tokens.json; logos live in logos/. The design system artifact on claude.ai has live previews of the components and is where this is designed; this directory is the copy every repo builds from. When the two disagree, update both in one change.

Venom is an agent-friendly OS that lives in the terminal. The brand is black, bone and blood: a pure-black ground, bone-white type, one drop of red. It borrows the restraint of black-metal album covers (the venom palette of black-metal-theme-neovim is its seed), the editorial calm of a hand-built desktop, and, in its logos, the precision of an engraving: fine lines on black, with depth from repetition. Every product is a sibling: same ground, same type, its own edition signal.

00 — The family

Product	What it is	Edition signal	Mark element
Venom	the ecosystem, the org, the umbrella	`blood`	Fangs with arcs on one side
venom	the orchestrator of coding agents	`signal-venom` (`blood`)	Fangs with arcs on both sides: one task, many agents
venomx	the multiplexer agents can drive	`signal-venomx` (`ember`)	Fangs inside nested squares: the panes
venom-os	the bundle: `venom-os up`	`signal-venom-os` (`lichen`)	Fangs inside closed circles: the whole system

Write Venom (capital V) only for the ecosystem. Write products as their binary names, always lowercase, even at the start of a sentence: venom, venomx, venom-os, venom-desk, venom-mem. Set them in mono when they appear in running prose.
Never write “VenomX”, “Venom OS” or “VenomOS”.
Foundations (venom-spec, venom-std, venom-term) and smaller products (venom-desk, venom-mem) have no mark of their own: use the Venom mark with the name in plain mono. They inherit blood unless they get an edition later.

01 — Voice

Short, declarative, a little cold. Say what it does, show the command, stop.

Lead with the verb or the command: “Spawn three agents on three worktrees.” then venom spawn -n 3 --worktree.
“You” for the reader, “we” for the project. No exclamation marks, no emoji, no hype words (“revolutionary”, “magic”, “seamless”).
Agents are tools you orchestrate, not characters. Say “the agent”, “Claude Code”, “Codex”; never give them personalities.
One dark aside per page is fine, in the tagline style: orchestrate the swarm, keep the knife. Many fangs, one bite. Don’t stack them.
Headings in sentence case end without a period. Hero words in display are UPPERCASE.
Numbers and states are exact: “3 agents waiting for approval”, not “a few agents need you”.

02 — Colour

The ground is void (#000 in trve). It is not dark grey and not navy. Colour is rare and always means something.

Text: bone for content, bone-dim for secondary, muted for labels and timestamps. faint is for disabled text and syntax comments only; it fails 4.5:1 on purpose.
Surfaces step up from void → crypt (panes, code blocks) → grave (status bars, selected rows) → ash (selection, hover). Separate surfaces with rule hairlines, not shadows. There are no shadows.
blood is the brand in the UI. Use it for the $ prompt, one primary action per screen, and errors. Logos use the muted logo-* tokens instead (see 06). If a screen has more than ~3% red, it is too much.
Edition signals: inside a product, --vn-signal replaces blood for focus, active state and the session block (data-edition="venomx" in the components). Don’t mix two products’ signals on one screen, except in ecosystem pages that show the family.
Status always pairs a colour with a glyph, so it survives colour blindness and monochrome terminals: status-ok ●, status-warn ▲, status-danger ✕, status-info ◆, idle ○ in muted.
Agent states: running = status-info, waiting for approval = status-warn, done = status-ok, failed = status-danger, idle = muted.
Fills of blood, ember and lichen take on-blood, on-ember, on-lichen text (black in trve, white in bone).

Themes. trve (dark) is the default and the one screenshots use. bone (light) is tuned separately, not inverted: warm paper #f3f2f2, dried-blood ink #211212, darker signals so each holds 4.5:1. Every text/ground pair named in a token’s usage note passes 4.5:1 in both themes.

03 — Terminal theme

ansi-0 … ansi-15 are the 16 colours venomx hands to panes and venom-term uses for its widgets. Unlike black-metal (which deliberately mutes green and blue), Venom keeps diffs legible: ansi-1 red is blood, ansi-2 green is lichen, yellow is gold, blue is frost, cyan is verdigris. Background is void, foreground bone, cursor blood, selection ash.

Ship it as ZON through the config verbs, never by hand-editing:

.theme = .{
    .name = "venom-trve",
    .bg = "#000000", .fg = "#f1f1f1", .cursor = "#fc302e", .selection = "#2a2a2a",
    .signal = "#e78a43", // venomx: ember. venom: #fc302e. venom-os: #99bbaa
    .ansi = .{
        "#211816", "#fc302e", "#99bbaa", "#eecc6c", "#7799bb", "#a8a1de", "#5f8787", "#c1c1c1",
        "#505050", "#ff6b5e", "#ddeecc", "#fbcb97", "#a6c1dc", "#c7c1ee", "#8fb3b3", "#f8f7f2",
    },
},

For editors, point people at black-metal-theme-neovim’s venom variant: it is the parent palette.

04 — Type

Three families, each with one job, plus the logo lettering for names.

serif, Instrument Serif: the editorial voice.
- Upright regular for page and section titles (title): large, sentence case, a few words ending in a full stop. Agents in panes. Read the manual. One per section.
- Italic for one tagline line under a hero name. Never more than one line.
- Never for body, labels or UI.
display, Big Shoulders Display 800, UPPERCASE: short carved lines. Stat figures, one pull line per page, and product names in docs headers (display-xl, display-l). Never for body or UI.
mono, JetBrains Mono: everything else. Body, UI, docs, labels, code (body, body-strong, code, label). The product lives in a terminal, so the site and the docs read like one. JetBrains Mono also covers box-drawing and block glyphs for TUI frames.

Hero names on the web are not set in a font. Use the logo lettering (see Logos): the wordmark for Venom, the lowercase letters of the product’s lockup for a product, drawn with a hairline stroke in bone that stays the same width at any size. Where the lettering can’t be drawn (a TUI, plain Markdown), fall back to display.

Section labels are numbered like a manuscript: 01 SEE IT RUNNING, 02 MANIFESTO in label, the number in the edition signal, then a rule hairline to the edge. A single box-drawing or block glyph (▚ ╬ ▦ ┼ ▒) may close the line; never a status glyph (● ▲ ✕ ◆ ○), which carry meaning.

All three are Google Fonts; components/bundle.css imports them. In a TUI, the user’s terminal font wins; design for any monospace.

05 — Space, shape, borders

Spacing is a 4px step (space-1 … space-16). In a TUI, space-2 ≈ one cell: think in cells and rows.
Corners are square (radius-0). Inputs and badges get radius-1 (2px). Only floating surfaces (palette, tooltip) get radius-2.
Character comes from the fang cut, a 45° chamfer on one corner, used on the status bar session block. Use it at most once per component. UI stays flat, with no shadows.
Borders: border-hair in rule for structure, border-focus in the edition signal for the focused pane. Focus ring: 2px solid focus (= bone), offset 2px, 18:1 on void.
Layout: dense, left-aligned, grid of panes. Pages read top to bottom in numbered sections, like a README.

06 — Logos

Fine lines on a lot of black, with depth from repetition rather than weight. Each logo comes in two versions: a line mark for large sizes and a solid icon for small ones.

	Lockup	Icon
Venom
venom
venomx
venom-os

The page shows the -dark files in dark mode and the -light files in light mode.

Line mark (above 32px). Two fangs built from horizontal scanlines, which also read as a V. All lines are one neutral ink, logo-ink. Only the drop at the fang tip carries colour, in the product’s muted logo-* token. The lines around the fangs say what the product does:
- Venom: arcs on one side, all springing from the fang tip.
- venom: arcs on both sides, one task fanning out to many agents.
- venomx: three nested squares standing on a corner, the panes.
- venom-os: closed circles, the whole system.
Icon (32px and below). The same fangs cut into three or four solid bars inside one thick outline: one arc, two arcs, a diamond, a circle. The whole icon is in the product’s muted colour. Set the name beside it in mono. The outlines tell the products apart even in one colour, down to 16px.
Wordmark. Thin capitals with wide spacing and a perfectly round O for the ecosystem (VENOM). Product lockups use the same drawing in lowercase, the way the names are written everywhere else. It is lettering, not a font: never set running text in it. It is the hero name on the web: inline the paths and keep the stroke a hairline at any size (vector-effect: non-scaling-stroke), so a large name stays as fine as the mark. Titles are in serif.
Files live in logos/: *-mark-*.svg, *-icon-*.svg, *-lockup-*.svg, venom-wordmark-*.svg. -dark files go on void, crypt or grave; -light files go on the same grounds in the bone theme and have slightly heavier lines.
Colour. Logos use the muted logo-* tokens; the bright signals (blood, ember, lichen) stay in the UI. Venom and venom share a colour, so their arcs tell them apart.
Clear space: a quarter of the mark’s height on every side. Minimum size: lockup 64px tall, icon 16px.
Don’t: enlarge an icon past 32px (it starts to look like an insignia; the one exception is a platform avatar that is mostly seen small), thicken or outline the lines, colour the lines, add gradients or shadows, or use the mark on a photo.

In the terminal (splash, --version, doctor header), draw the fangs as scanlines in ansi-7, with the drop in the edition’s colour:

━━━━━━  ━━━━━━
 ━━━━━  ━━━━━    venomx 0.1.0
  ━━━━  ━━━━     terminal multiplexer for humans and agents
   ━━━  ━━━
    ━━  ━━
      ●          ● = the edition's colour

07 — Imagery

No stock photos, no 3D blobs, no glowing gradients, no robot illustrations. Show the real thing: screenshots of real sessions in the trve theme, or terminal recordings. Decoration, if any, is engraved line work or dithered 1-bit textures in bone on void, kept behind the content at low contrast.

08 — Components

Web and docs components are CSS only, prefixed vn-, and load after the token stylesheet. Wrap a product surface in data-edition="venom|venomx|venom-os" to switch the signal. The set is Button, Badge, SectionLabel, InstallBlock, Pane, StatusBar and Logo. Their CSS and live previews are in the design system artifact. TUI widgets in venom-term follow the same rules with the ANSI palette from 03.

Tokens

tokens.json lists every value with a usage note. Colour tokens have a value per theme (trve, bone), and edition and status tokens are aliases written {blood}. Name CSS custom properties after the tokens (--blood, --space-4, --font-mono) and never hard-code a hex value that has a token.