Visual Identity v2

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.

The guidelines crystallize the decisions ratified during M5.3 D11 (Visual Identity v2 + Image Regen; cycles 101–110). The shorter version: philosophy-before-feature minimalism + geometric restraint + currentColor inheritance + 1.6 stroke-width + abstract over figurative.

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 uses a restrained two-color brand palette (teal + amber) on a neutral light/dark foundation. All colors are defined as CSS custom properties in src/styles/branding.css; consume them via var(--color-*) rather than hex literals.

Brand tokens

Semantic mappings

Neutrals

Defined in src/styles/tokens.css. The neutrals are pure HSL with no hue, which lets the brand teal carry all the color signal:

Rules

1. Consume tokens, not hex. New components MUST reference var(--color-*) so dark-mode and brand changes propagate.
2. Brand teal carries the signal. Amber is reserved for sparing accent — never large surface areas, never body text.
3. 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 is a methodology project. Image generators default toward illustrative / aspirational output (people-on-laptops; gradient skies; abstract data streams). That entire register is wrong for this surface — see M5.1 D11 AVOID-2 (“marketing-style hero imagery”). The prompt discipline below keeps generated imagery in the philosophy-before-feature minimalism register established by M5.1 D11 LIFT-1.

Hard guardrails

1. No text inside images. Generators (Imagen 4 Ultra included) hallucinate glyphs at small sizes; text inside hero PNGs degrades to gibberish at OG-card scale. Strip the prompt of any words that ask for typography, captions, labels, or titles. If text is needed, composite it with PIL after generation.
2. No figurative people. No hands, faces, silhouettes, or postures. Diagrams and abstractions only.
3. No marketing gradients. Flat tones, geometric shapes, line art. No sunsets, no horizons, no data-streaks.
4. Restraint over richness. A single geometric motif with 3–5 elements outperforms a busy composition every time at thumbnail scale.

Prompt skeleton (Imagen 4 Ultra)

A minimalist geometric composition featuring [SINGLE_MOTIF]
in [PRIMARY_COLOR] on a [BACKGROUND], abstract structural
diagram style, line art with [STROKE_WEIGHT] strokes, no text,
no people, no gradients, restrained palette, 16:9 wide format.

• [SINGLE_MOTIF] — one of: connected nodes, nested rectangles, layered bands, concentric arcs, hexagonal tessellation, grid with callouts. Pick one. Do not list two.
• [PRIMARY_COLOR] — teal #0D7377 or dark teal #0A4F52. Amber sparingly.
• [BACKGROUND] — clean off-white, neutral light gray, or dark charcoal for dark-mode variants.
• [STROKE_WEIGHT] — thin, medium, or bold (avoid pixel widths in prompts; generators interpret loosely).

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. 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 light and dark mode. The mechanisms:

1. CSS custom properties switch on .dark class (toggled by DarkModeToggle.astro). All --color-* tokens have light + dark resolutions.
2. SVG currentColor inheritance means a single SVG renders correctly in either mode automatically.
3. Image assets are not theme-switched. Hero PNGs are tuned to read on both backgrounds; OG cards use a single neutral-friendly composition.
4. Avoid hard-coded hex in components. A #0D7377 literal will not switch correctly; var(--brand-primary) will.

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.