Colibri Design System

This document defines the visual identity that every Colibri surface (repo README, GitHub Pages, Obsidian vault) shares. R73 writes the target; R74 is the round that implements any gaps between current state and target.

See also: surfaces.md for where each surface lives and colibri-system.md for the identity this design system expresses.

1. Design principles

  1. Legitimate, not flashy. Colibri is about cryptographic audit trails and constitutional governance. The design should feel precise, measured, rigorous — not playful, not gimmicky. Closer to a scientific instrument than a consumer app.
  2. One mark, many surfaces. The hummingbird + Greek overlay appear consistently on the repo README, GitHub Pages hero, and Obsidian vault cover. Users recognize Colibri at a glance.
  3. Greek is the vocabulary, English is the voice. 15 concepts live in Greek letters because Greek is precise and tradition-laden. Prose is in English because clarity wins. The design treats Greek as a mark and English as the explanation.
  4. Motion has meaning. Every animation represents something real: the pipeline moving, the Merkle tree building, a layer of legitimacy lighting up. No decorative motion.
  5. Honest density. Colibri’s docs are detailed and technical. The design does not hide that — it frames it. Generous whitespace; no cramming.

2. The hummingbird mark

2.1 Meaning

A colibri (hummingbird) is the smallest bird that can still hover and defy expectations. The name was chosen because the project does a disproportionate amount of legitimacy work for its size. The mark is literal: a hummingbird in flight.

2.2 Two forms

Form File Use
PNG master docs/assets/images/colibri-mark.png (R74 commit from assets/colibriv0.png) Hero background, high-fidelity large-scale contexts
SVG glyph docs/assets/images/colibri-logo.svg Favicon, inline navigation icon, small UI, wherever scaling matters

The PNG is 640×640, 8-bit RGB, 62 KB. It is the “canonical artwork” — the SVG is a simplification for technical constraints.

2.3 Do and don’t

Do:

  • Use the PNG for hero backgrounds ≥ 400px
  • Use the SVG for anything ≤ 200px or any context that scales
  • Keep the mark’s aspect ratio 1:1
  • Give the mark at least 1× its own width of breathing room
  • Use the mark on a calm background (white, near-black, or the hero gradient)

Don’t:

  • Recolor the mark’s interior gradient (the breast feathers have a specific green-purple transition; don’t change it)
  • Rotate or flip the mark
  • Skew the mark
  • Apply drop shadows (the hero uses a subtle atmospheric light, not shadows)
  • Use the mark inside a filled shape that crops the wings

2.4 Current status

  • SVG: present at docs/assets/images/colibri-logo.svg. 2.9 KB.
  • PNG: untracked file at assets/colibriv0.png (640×640, 62 KB). R74 task: move to docs/assets/images/colibri-mark.png, commit, update hero CSS to use the PNG as background.

3. Color palette

3.1 Core palette

Name Hex Role
--cb-ink #0E1013 Primary text on light backgrounds; hero background in dark mode
--cb-paper #FAFAF7 Primary background in light mode
--cb-gold #C29B3F Primary accent — used sparingly for the “AMS” wordmark tail, active links, selected Greek letters
--cb-sage #7A9B85 Secondary accent — used for legitimacy axis signals, success states
--cb-plum #4A3E5E Tertiary accent — used for intelligence axis signals, reflection states
--cb-copper #B86B3C Tertiary accent — used for execution axis signals, action states

3.2 Axis colors

The three axes get three distinct accent colors so that pipeline diagrams and status indicators read at a glance:

  • Execution: copper (--cb-copper)
  • Intelligence: plum (--cb-plum)
  • Legitimacy: sage (--cb-sage)

This mapping is used in:

  • Concept cards in the Greek overlay
  • Roadmap wave diagrams
  • Writeback signal icons
  • Session seal headers

3.3 Neutral scale (for body text, borders, subtle UI)

Name Hex Role
--cb-gray-0 #FAFAF7 same as paper
--cb-gray-1 #ECECE7 subtle backgrounds, card borders
--cb-gray-2 #C8C7C1 borders, dividers
--cb-gray-3 #8E8D87 secondary text, captions
--cb-gray-4 #3D3C38 primary text on paper
--cb-gray-5 #1C1C1A near-black for high-contrast text

3.4 Dark mode

When prefers-color-scheme: dark or an .theme-dark class is applied:

  • Swap --cb-paper ↔ --cb-ink
  • Keep accent colors the same (--cb-gold, --cb-sage, --cb-plum, --cb-copper) but increase luminance by ~10% for contrast on dark backgrounds
  • Use a subtle atmospheric gradient on the hero (dark indigo at top to near-black at bottom)

3.5 Implementation status per surface

The design system targets four surfaces, but not every surface carries every element. This table records the live-vs-N/A status as of R75 so that contributors know where to check their work.

Surface Element Status Notes
GitHub Pages .cb-hero hummingbird mark LIVE R74.3.1 ring centered; verified via live CSS --cb-ring-size: clamp(380px, 52vw, 560px).
GitHub Pages Color palette (copper / plum / sage / gold) LIVE assets/css/custom.css?v=r74-3-1.
GitHub Pages Greek-letter ring hover LIVE R74.3 polar placement, 0.78 opacity baseline, gold-bloom on hover.
Obsidian vault Design palette N/A Obsidian theme is user-local; the vault tracks content, not visual identity.
Obsidian vault Hummingbird mark N/A Vault has no landing page.
Repository README Logo reference LIVE assets/colibri-mark.png (PNG master, linked from README hero block).
Worktrees — N/A Ephemeral; no UI surface.

Brand coherence across surfaces. The repository is the source of truth for every visual asset (PNG master, SVG glyph, custom.css, colibri-hero.js). GitHub Pages is the canonical render of that source of truth — any change to the design shows up on Pages first. The Obsidian vault is a content-only mirror: it receives the prose from docs/ but does not reproduce the hero, palette, or Greek overlay. Worktrees share nothing visual; they exist only as ephemeral code surfaces. If a design element is mentioned in this document but does not appear in the table above, it is a spec target, not a live surface.

4. Typography

4.1 Type scale

Role Size Weight Line height
Hero title 64px / 4rem 800 1.0
Page title (H1) 48px / 3rem 700 1.15
Section (H2) 32px / 2rem 700 1.2
Subsection (H3) 24px / 1.5rem 600 1.3
Body 17px / 1.0625rem 400 1.6
Caption / small 14px / 0.875rem 400 1.5
Code 15px / 0.9375rem 400 1.5

4.2 Font families

Role Family Fallback
Display (hero, H1–H2) "Playfair Display", "Cormorant Garamond", serif system serif
Body "Inter", "Segoe UI", sans-serif system sans
Greek letters "GFS Didot", "Linux Libertine", serif system serif — must have full Greek coverage
Code "JetBrains Mono", "Fira Code", monospace system mono

The body family is the default from just-the-docs theme if the custom font is unavailable — any of these will work. The important constraint is that the Greek family must include α–ω glyphs.

4.3 Latin + Greek mixing

When a paragraph mixes Latin and Greek (which is most of this project’s prose), ensure both read at the same optical size. If the body font doesn’t carry Greek, the Greek letters should be wrapped in a span that switches to the Greek font:

<span class="cb-greek">α</span> System Core

The .cb-greek class in custom.css switches font family and adjusts letter-spacing.

5. The hero block

The hero block is the first thing any reader sees on docs/index.md. R70 introduced it; R74 polishes it.

5.1 Structure 

┌───────────────────────────────────────────────────────────┐
│                                                           │
│              [logo stage — animated]                      │
│                                                           │
│                    Colibri AMS                            │
│        Skill-driven · Cryptographically auditable         │
│              · Legitimate by design                       │
│                                                           │
│   An MCP orchestration runtime uniting task execution,    │
│   multi-model routing, audit trails, and Merkle-anchored  │
│   proof generation. Phase 0 specification is complete —   │
│   15 Greek concepts, 28 agent-ready tasks, zero code      │
│   shipped yet.                                            │
│                                                           │
│    [ First Session ]  [ Agent Bootstrap ]  [ MCP Tools ]  │
│                                                           │
│   Hover the hummingbird to reveal the 15 Greek layers.    │
│                                                           │
└───────────────────────────────────────────────────────────┘

5.2 Hero layers (z-index stack)

  1. Atmospheric gradient (lowest) — subtle top-to-bottom gradient from --cb-paper to --cb-gray-1. In dark mode: near-black to deep indigo.
  2. Feather texture — very low-opacity repeating feather pattern. Fades out to flat below the hero.
  3. Hummingbird mark — PNG master, centered, with gentle hover animation.
  4. Greek overlay — 15 cards that fade in on mark hover.
  5. Title + tagline + subtitle — text block.
  6. CTA buttons — primary (gold), secondary × 2 (ink outline).

5.3 Hero CSS variables

The hero uses these custom properties; override them to re-theme without touching the HTML:

:root {
  --cb-hero-bg-start: var(--cb-paper);
  --cb-hero-bg-end: var(--cb-gray-1);
  --cb-hero-mark-size: 280px;
  --cb-hero-mark-hover-scale: 1.05;
  --cb-hero-title-size: 4rem;
  --cb-hero-tempo: 8s;           /* base animation unit T */
  --cb-hero-greek-fade: 0.5;     /* fraction of T */
}

6. The 15-card Greek overlay

6.1 Purpose

The overlay is a tactile way to introduce the 15 concepts. Each card represents one letter. On hover (desktop) or tap (mobile), a card reveals its concept name, axis, and a one-sentence promise.

6.2 Layout

15 cards in a 5×3 grid, radiating from the hummingbird mark. Positions are fixed in CSS with a “starburst” geometry: the 15 cards surround the mark at angles 0°, 24°, 48°, …, 336° (24° apart). This works because 360° / 15 = 24°.

           γ        δ
       β              ε
    α                    ζ
    ξ     [MARK]         η
    π                    θ
       ν              ι
           μ        λ  κ

(Schematic; actual positions pick aesthetic balance over strict radial order.)

6.3 Card contents

Each card has three lines:

<letter>
<concept name>
<axis accent dot> <promise in 8 words>

Example:

α
System Core
● Single-process MCP server with middleware + SQLite

6.4 pretext integration

The card widths are computed using the @chenglou/pretext library. Pretext measures the text before the card is laid out and picks a width that avoids awkward line breaks. The measurement runs at page load; the widths are then frozen.

This matters because the 15 cards have 15 different concept names of different lengths, and visual symmetry is broken if each card picks its own width independently. pretext lets them share a width constraint across the whole grid.

The existing implementation is in docs/assets/js/colibri-hero.js. R74’s job is to verify it still works and extend it to handle the new (target) content.

6.5 Animation

Base unit T = 8 seconds.

Event Duration Curve
Mark hover enter → overlay fade-in start 0.25 T (2s) cubic-bezier(0.2, 0.9, 0.3, 1)
Cards fade in, one after another 0.5 T over 15 cards (~27ms per card) linear
Cards hold at full opacity 2 T (16s) —
Cards fade out if mouse leaves 0.25 T (2s) cubic-bezier(0.5, 0, 0.8, 0.5)
On card click: pin + expand detail 0.5 T (4s) cubic-bezier(0.2, 0.9, 0.3, 1)

The 7-second “full reveal” timing matches the 7 stages of the β Task Pipeline — a small meaning-bearing motion.

7. Background textures

7.1 Feather pattern

A very low-opacity (~4%) repeating feather texture appears only on the hero. Below the hero, the background is flat.

Where to get the pattern:

  • Extract from assets/colibriv0.png by desaturating and increasing contrast
  • Tile at 256×256
  • Serve as docs/assets/images/feather-tile.png

7.2 No other textures

Non-hero backgrounds are flat paper (light mode) or ink (dark mode). Do not add gradient or noise to body text backgrounds — it hurts readability and clashes with the hero’s meaning.

8. The “one system” feeling

The human’s R73 complaint was: “по документации не чувствуется что это одна система” (“the docs don’t feel like one system”).

The design-level fixes are:

  1. Consistent mark. The same hummingbird appears on every surface. Seeing it repeatedly = pattern recognition = “one system”.
  2. Consistent Greek vocabulary. Every page that mentions a concept uses the Greek letter first, name second. (“α System Core”, not “System Core (α)”.)
  3. Axis color tagging. Anywhere a concept is mentioned outside prose, its axis color is applied to a 4px dot or underline. Over time readers associate copper = execution, plum = intelligence, sage = legitimacy.
  4. Consistent prose voice. R73 fixes CLAUDE.md, AGENTS.md, and docs/index.md so their voices converge. Formal, precise, first-person plural (“we”) only in manifestos.
  5. Consistent navigation. Every page links back to colibri-system.md as the canonical vision.
  6. Consistent frontmatter. Every doc carries round, parent, updated, and (for concept/reference docs) colibri_code. Readers can grep for any of these.

Design alone cannot make the docs feel like one system. The design works with the editorial fixes in R73 and the lint fixes in R74.

9. Do / don’t — quick reference

Do Don’t
Use Greek letters as identifiers Use emoji in place of Greek letters
Use axis colors for signals only Use axis colors for decoration
Use the PNG mark for large hero Use PNG for small UI (SVG instead)
Animate to communicate (not decorate) Add motion “to feel alive”
Let the mark breathe Crop the wings or add busy shadows
Use the cb-* CSS variables Hard-code colors in custom files
Use pretext for card layout Pick card widths manually
Use Playfair Display only for display Use Playfair Display for body

10. Implementation status (R73)

Item Status R74 task?
Hero HTML in docs/index.md Present (R70) Review — might need Greek overlay update
docs/assets/css/custom.css Present (R70, 10.5 KB) Add palette vars, tempo vars, PNG bg rule
docs/assets/js/colibri-hero.js Present (R70, 13.1 KB) Verify pretext layout; add keyboard focus handling
docs/assets/images/colibri-logo.svg Present (R70, 2.9 KB) Keep; possibly adjust to match PNG
assets/colibriv0.png Untracked R74 task: move to docs/assets/images/colibri-mark.png and commit
Feather texture tile Missing R74 task: extract from PNG and commit
Design system document This file (R73) —
Color palette in CSS Partial R74 task: formalize with cb-* vars
Greek overlay pretext layout Working (R70) Review for the 15 target concepts
Dark mode Not implemented R74 task: add prefers-color-scheme support

R73 ships this document only. R74 implements the tasks listed above.

Part of the R73 unification corpus. Governed by colibri-system.md.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.