Visual Identity v3

Purpose

This is the contributor-facing reference for visual decisions across the aDNA documentation surface. If you are authoring an asset — a hero image, a section icon, an inline diagram, an OG card — this document tells you which palette to draw from, which typography scale to use, what stroke-width matches the existing vocabulary, and how to prompt the image generator so the result does not look like marketing.

v3 register pivot (ADR-032, ratified 2026-06-04). aDNA.network has evolved from the minimalist teal/amber “Rust/Tauri” register (v2) to the Science-Stanley “Ghibli-pixel” / Tokyo Night warm register — cozy bio-digital retro-futurism: warm, hand-crafted, hopeful, dense narrative detail. The shift carries the project’s public-good ethos through warmth + craft rather than cold restraint. What stays constant: purpose over decoration, currentColor inheritance, AA contrast, reduced-motion, honest affordances. What changes: the palette (Tokyo Night, dark-first — §1) and the imagery register (illustrative SS-Ghibli pixel art is now allowed — §4). The v2 baseline crystallized M5.3 D11 (cycles 101–110); this v3 supersedes its palette + imagery sections.

Companion documents:

• The aDNA Universal Standard — what to build.
• The Design Rationale — why it is built that way.
• This document — what it should look like and how to make it match.

1. Color palette

aDNA.network draws from the Tokyo Night palette, dark-first — a deep navy base carrying a purple brand accent, cyan links/data, and a warm amber for lighting. All colors are CSS custom properties in src/styles/branding.css (brand) + src/styles/tokens.css (neutrals); consume them via var(--color-*) rather than hex literals. Token names are preserved from v2; their values were repointed (ADR-032).

Brand tokens

Semantic mappings

Neutrals (Tokyo Night, dark-first)

Defined in src/styles/tokens.css. Dark is the default register (ADR-032); light mode keeps near-white neutrals so the secondary register stays usable.

Rules

1. Consume tokens, not hex. New components MUST reference var(--color-*) so dark/light and brand changes propagate. (Illustrative image assets are the deliberate exception — §4.)
2. Two signals, one warm accent. Purple carries brand/identity; cyan carries links/data/connections. Amber is reserved for sparing warm lighting — never large surface areas, never body text.
3. Dark-first. Dark is the default; light mode is the supported secondary. Verify AA contrast in both modes for every text/link pairing.
4. Status colors (--color-error, --color-success, --color-warning, --color-info) are pre-defined and tuned for both modes; do not introduce new status hues without operator gate.

2. Typography

Font stack

Variables: --font-display, --font-body, --font-mono. JetBrains Mono is loaded font-display: optional so a slow first-paint never blocks rendering — system monospace is acceptable until cached.

Scale (modular 1.25 ratio with viewport fluidity via clamp)

Rules

1. Never hard-code font-size. Always consume from the scale.
2. Display font for headings; body for prose. Mono only for code, file paths, and identifiers.
3. Weight discipline. Display headings use 600. Body prose uses 400 with 600 for emphasis.

3. Spacing

A 4px-base scale exposed as CSS custom properties.

Layout constants:

Border-radius scale: --radius-sm through --radius-xl plus --radius-full (9999px for pills). Default for cards is --radius-md; default for buttons is --radius-sm.

4. Image-prompt conventions

aDNA.network is a methodology project, and under v3 it carries the Science-Stanley “Ghibli-pixel” register (ADR-032): cozy bio-digital retro-futurism — warm, hopeful, hand-crafted, dense narrative detail. This relaxes the v2 abstract-only guardrail: illustrative pixel-art scenes (lab desks, node-maps, connected vaults, helices) are now in-scope. What does not relax: no baked text, no human faces, purpose over decoration, and AA contrast on any composited text.

Hard guardrails

1. No text inside images. Generators (Imagen included) hallucinate glyphs; text inside hero PNGs degrades to gibberish at OG-card scale. Strip the prompt of typography, captions, labels, titles. Composite any title as live SVG/CSS text (responsive + carries the accessible name) or via PIL after generation — never baked into the gen.
2. No human faces. The runner sets person_generation="dont_allow". Use scene-level / bird’s-eye framing (desks, maps, vaults, helices), not portraits.
3. Hopeful, not dystopian. Warm task lighting + cool monitor glow; intellectually curious mood. No sterile empty sci-fi, no dark dystopia, no photographic stock-photo aesthetic, no marketing gradients on content.
4. Dual-resolution craft. Human/physical elements = high-fidelity 32-bit painterly pixel; AI/digital constructs = chunky 16-bit sprites; DNA/active-science motifs = sharp glow-emission vector pixels. No uniform pixel scaling, no flat vector UI.

Prompt skeleton (Imagen 4)

The canonical style tail lives in the runner (GHIBLI_TAIL in runners/e1_hero_adna_network_gen.py) — reuse it; do not re-derive. A prompt = [SCENE_MOTIF] + GHIBLI_TAIL:

[SCENE_MOTIF — one bird's-eye / isometric scene: a cozy lab desk with a
glowing node-map; a constellation of connected nodes; a DNA-helix resolving
into a network; an isometric town of connected vault-buildings]
+ GHIBLI_TAIL (detailed 32-bit pixel art, cozy studio-ghibli aesthetic,
soft dithered shading; Tokyo Night palette — base #1a1b26 / #24283b, purple
#9d7cd8, cyan #7dcfff, warm amber #e0a84c lighting; dual-resolution rule;
hopeful mood; ABSOLUTELY NO TEXT / NO LETTERS / NO LOGOS; no human faces;
wide 16:9; anti-patterns: no flat vector UI, no sterile sci-fi, no dystopia)

• Palette in-prompt — base navy #1a1b26 / #24283b; purple #9d7cd8; cyan #7dcfff; warm amber #e0a84c (lighting only).
• One scene, not a checklist — a single coherent motif beats a busy collage at hero / thumbnail scale.

Post-generation pipeline

1. Imagen 4 Ultra background generation at full resolution (16:9 hero; 1:1 OG card).
2. PIL text overlay for any text required (OG card titles, hero captions). Done out-of-band per asset.
3. Astro <Image> from astro:assets produces responsive .webp variants at build time at widths matching layout breakpoints (640 / 960 / 1280 / 1408 for heroes).

Cost discipline

Imagen 4 Ultra is $0.04/call; Imagen 4 Fast ($0.02) is the exploration / fallback tier when Ultra returns transient 429/503 capacity errors (the runner retries with backoff, then you pass --model imagen-4.0-fast-generate-001). Per-cycle budgets are recorded in each mission’s Image-Gen Budget Tracker; cumulative spend is tracked at the campaign master + STATE.md. Hard cap at $50 per phase (set at v8 P5 entry).

5. Icon vocabulary

The site uses a 6-icon set covering the canonical section taxonomy. Each icon is a hand-designed SVG at site/src/assets/icons/icon_{name}.svg. The set was authored at cycle 103 and refined at cycle 106.

Set inventory

Motif rules

1. Stroke-width 1.6. Matches diagram-component vocabulary (TriadDiagram + ConvergenceFunnel use the same width).
2. stroke="currentColor" + no fill. The icon inherits the parent text color; that lets nav active-states and dark-mode parity work automatically.
3. fill="none" on outlines. Solid fills create visual heaviness at 14–16px nav scale.
4. Straight shafts + explicit chevron arrowheads (NOT curved Bézier arrows or partial arrowheads) — discovered at cycle 103, validated at cycle 106. Curves lose detail below 16px.

Wiring discipline

Icons are imported as raw SVG strings via Vite’s ?raw query and embedded via set:html:

import iconLearn from '../../assets/icons/icon_learn.svg?raw';
// ...
<span class="group-icon" aria-hidden="true" set:html={iconLearn} />

• aria-hidden="true" because the adjacent text label carries the semantic meaning; the icon is a redundant recognition signal.
• Sized via wrapper span (.group-icon 16×16, .section-icon 14×14) — not inline <svg width=...> attributes.
• Spot-check the built dist/ HTML after wiring — grep for the icon class name to confirm all consumers actually render the icon (catches missed mappings, per cycle 106 finding).

6. Diagram component vocabulary

The site/src/components/diagrams/ library exists for build-time-rendered SVG diagrams of canonical aDNA structural concepts. Two components are live:

• TriadDiagram — WHAT / HOW / WHO triangle. Symmetric relationships; undirected edges.
• ConvergenceFunnel — Vault → Campaign → Mission → Objective top-down funnel. Asymmetric flow; directional arrows via SVG marker-end.

Live examples

Component contract

Every diagram component MUST:

1. Use inline SVG directly in the Astro template (not ?raw-imported) when labels or geometry depend on Props. Use ?raw-imported SVG when the asset is static (icons).
2. Set role="img" and an aria-labelledby attribute pointing to per-instance random-suffix <title> + <desc> IDs to prevent collision when multiple diagrams render on a page.
3. Provide <title> (short alt) + <desc> (sequential structural description) inside the SVG.
4. Inherit currentColor for strokes and text fills; use var(--color-bg) for node backgrounds.
5. Match the 1.6 stroke-width vocabulary (consistency with the icon set).
6. Define all Props as optional with safe canonical defaults — the minimum-viable consumption is <DiagramName /> with no props.
7. Match the Vault → Campaign → Mission → Objective convergence labeling (when applicable; per project CLAUDE.md Convergence Model table) and the WHAT / HOW / WHO triad labeling for the triad case.
8. Use <figure> wrapper + optional <figcaption> for caption.
9. Set viewBox to round multiples (320 wide is the established baseline; height adjusts to content).

When to use diagrams vs Mermaid

• Use a diagram component when (a) the concept is canonical aDNA (triad, convergence, OODA, lattice graph), (b) the diagram will recur across multiple pages, (c) you want zero runtime JS, or (d) you need precise control over the visual.
• Use MermaidDiagram when the diagram is one-off content-specific (a particular workflow, a particular relationship graph for one example), or when contributor velocity benefits from Mermaid’s text-based syntax.

7. Dark mode parity

Every visual decision MUST work in both modes. aDNA.network is dark-first (ADR-032): dark is the default register; light mode is the supported secondary. The mechanisms:

1. CSS custom properties switch on .dark class. Dark is applied by default for every visitor (<html class="dark"> + the inline theme script in BaseLayout.astro — dark unless the user toggled light); the toggle (DarkModeToggle.astro) persists the choice. The Tokyo Night register is the experience newcomers see; light is opt-in. All --color-* tokens have dark (default) + light resolutions.
2. SVG currentColor inheritance means a single SVG renders correctly in either mode automatically.
3. Illustrative image assets are not theme-switched. Hero / section PNGs are Tokyo-Night scenes tuned to read on the dark default; a top-down navy scrim guarantees AA title contrast independent of the asset. OG cards use a single dark composition.
4. Avoid hard-coded hex in components. A #9d7cd8 literal will not switch correctly; var(--brand-primary) / var(--color-*) will. (Image assets are the deliberate exception — §4.)

Brand-system v3 — dark-first + image-led hero (M5.10 / E1, ADR-032)

The homepage hero is image-led: a Tokyo-Night SS-Ghibli scene leads the fold with the title composited as live Space-Grotesk-Bold text over a darkened upper band (reverses the E1 c2 words-below demote). Rules:

• Scrim guarantees contrast. A top-down #1a1b26 navy scrim over the image’s upper band keeps the live <h1> at AA regardless of the underlying art; the title is real text (responsive + accessible name), never baked into the gen.
• Dark-first body. The whole page now defaults dark, so the hero no longer needs to self-scope .dark for a light body — the calm dark stage is the site default. Light mode remains a supported parity register below.
• Surface treatment, not marketing. A quiet purple/cyan glow (color-mix(... var(--brand-primary) …, transparent)) gives the stage depth — within the §1 palette, not a marketing gradient on content.

§2 type, the icon / diagram vocabularies, and the toggle mechanism are unchanged; §1 palette + §4 imagery are the v3 deltas.

8. Accessibility minima

9. Change discipline

This document is the canonical visual identity reference. Changes go through:

1. Persona Q&A in a D11 (or D18) decadal cycle.
2. Operator ratification at phase gate or mission-spec amendment.
3. Update to the relevant CSS tokens / Astro components / this document in the same commit batch.

For one-off asset additions (a new hero variant, a new icon for a future section), follow the prompt skeleton + post-generation pipeline above; record the image-gen log per ADR-026.

See also

• The Triad — the WHAT / HOW / WHO ontology this site IS organized around.
• The Convergence Model — the decomposition model the documentation surface IS built to enable.
• Design Rationale — why aDNA is structured the way it is.
• aDNA Universal Standard — the normative spec this surface demonstrates.