Composition

How color, typography, and spacing work together. Individual foundations define each axis. Composition defines how they interact.

Purpose x Surface Matrix

Composition rules are organized by purpose (what the page does) and surface (what medium it’s on). The same surface can serve different purposes with different composition logic. A homepage (persuade) and a case study (inform) are both web pages, but they compose differently.

Surface Registers

Each web-page purpose type has a dominant emotional register that describes how it earns trust. Registers are not enforceable rules. They guide judgment calls when the coupling rules don’t prescribe an answer. Brand values are expressed through concrete guardrails (coupling rules, ceilings, floors), not declared as labels on composition cells.

With 60%+ of traffic arriving from LLMs with intent already shaped, each page must earn trust within its own scroll. The register describes the trust-earning sequence built into the page’s composition.

Defined Cells

For implementation patterns (hero sections, stats rows, trust bars, CTA strips), see categories/web-components/page-sections.md.

Persuade x Web Page

For homepages, landing pages, and campaign pages. Narrative pacing with coupling rules.

Narrative Roles

Each section on a persuasive page serves a role in the story. The role determines its visual treatment.

Arc Rules

• Every page needs a hook and a close
• At most one turn (the earned accent moment)
• Max 3 consecutive low-energy sections before a turn or visual break
• The turn should follow at least one evidence section

Minimal Arc (Short Pages)

Pages with 3-6 sections (product, solution, partner pages) use a reduced arc: Hook → Evidence(s) → Close. No turn required – the page is too short for the earned accent to land. Hook and close remain mandatory.

Coupling Rules

Color, type, and spacing aren’t independent on a persuasive page. They’re coupled. All spacing values are responsive – mobile gets less padding to avoid wasting screen real estate.

Color to spacing: Visual weight needs room.

Color to typography: Background changes how text reads.

• Tinted or dark backgrounds: body line-height 1.65-1.75 (looser than 1.6 default)
• Tinted or dark backgrounds: max line-length 65ch (tighter than 75ch default)
• Dark backgrounds: body letter-spacing +0.01em to +0.03em

Type to spacing: Larger headings need more room.

Section Role Tokens

Pre-mixed CSS custom properties for narrative role backgrounds. Use these instead of hardcoding hex/HSL values.

Dark-on-dark differentiation: hook uses hsl(262, 30%, 8%) and close uses hsl(262, 30%, 6%) – both midnight-purple tinted, subtly different from the page background (neutral.950 = hsl(240, 10%, 4%)).

Ghost vs Ghost-on-Dark Buttons

Rule of thumb: if the section uses --section-hook-bg or --section-close-bg, use ghost-on-dark.

Logo Display Mode

Whitespace Principle

Generous whitespace is the primary signal of quality on persuasive pages. Perceived luxury correlates with empty space (spatial color efficacy research). When in doubt, add more space, not more content.

See rules/visual-rules.yml -> composition.persuade-web-page for the machine-consumable version.

Narrate x Web Page

For long-form editorial essays, design retrospectives, case narratives. Not persuade (no funnel). Not inform (not flat). The reader follows a journey with depth.

This purpose type was created when the evolution essay needed composition rules and no existing type fit. The framework grew to accommodate a surface it couldn’t serve.

Structure

Narrate uses episodes, not narrative roles. Episodes are prose + figure pairs, repeatable in any order.

Key Differences from Persuade

• Color is illustrative, not atmospheric. Color appears inside figures (specimens, before/after comparisons), not as section background tints. Between figures, the page is neutral.
• No marketing patterns. No CTA buttons in prose. No gradient strips. No card grids as content. The page is an essay.
• Body text is 1.125rem at 1.7 line-height. Looser than the 1.6 base default.
• The closing is an invitation, not a conversion. The reader leaves thinking, not clicking.

When to Use Narrate

Design essays, retrospectives, case studies with depth, process documentation that tells a story. If the piece has a beginning, middle, and end and the reader should experience the journey (not just scan for information), it’s narrate.

See rules/visual-rules.yml -> composition.narrate-web-page for the machine-consumable version.

Site-Level Composition

Page-level composition governs sections within a page. Site-level composition governs how pages relate to each other across a visit. Individual pages are self-contained (each earns trust within its own scroll), but visitors who navigate between pages will notice if every page uses identical composition. The site needs an arc too.

Page Hierarchy

Not all pages have equal visual weight. Tier controls two things: hero scale (how loud) and color budget (how many accent moments a page can earn). A third axis, hero posture, is separate and is covered in Hero Posture below.

The homepage owns the full-scale hero with gradient strip. If secondary pages also use full-scale heroes, the homepage loses its primacy and the site feels like a collection of landing pages rather than a coherent product. Default posture is the tier’s baseline, not a requirement. Individual pages override posture when the visitor’s posture differs from the tier default (see Hero Posture).

Hero Posture

Posture controls how the hero reads, not how loud it is. The three postures map to three visitor jobs. Pick posture based on why the visitor is on the page, not what tier the page sits in.

All three postures are expressions of the same brand pillars (Precision, Masterful, Refined, Pioneering) at different intensities. Posture picks weight, not warmth. Verdigris does not soften its voice across surfaces; it just dials intensity.

Authoritative is the full-weight expression and the default for product-evaluation pages. The dark background creates visual weight and signals serious infrastructure. A data center VP clicking through /platform expects this.

Belonging is the brand pillar Refined expressed at identity level. Says “this is who we are,” not “this is what we sell.” Reserved for identity pages. More than two belonging heroes across a site dilutes the About page’s singular role and turns brand teal into wallpaper.

Restrained is the low-intensity expression for pages where full authoritative weight would over-sell. An industry landing arriving from search, a careers page, a partner page. Light background, dark text, teal still used as precise accent, typography still understated. Not warmth, not photography-forward, not “here is how we help your world.” Restrained means less weight, same pillars.

Posture is independent of scale. A secondary-scale hero can be authoritative (product page) or restrained (industry page). Don’t read the table left-to-right: tier picks scale, posture picks intensity, and the two decisions are made separately.

Cross-Page Turn Scarcity

The turn moment (earned accent) is powerful because it’s rare. At page level, the rule is “at most one turn per page.” At site level: at most one turn per 3-page navigation depth. In practice, this means the homepage gets the turn and secondary pages do not, unless the visitor is deep enough (3+ clicks from homepage) that the earlier turn has faded.

If every page has a turn, the accent becomes wallpaper. The scarcity rule preserves its emotional impact.

Accent Diversity

When multiple pages do use accent moments (homepage + a deep product page), they must use different palette regions. If the homepage turn uses midnight-purple (energy region), the product page turn should use cyber-yellow (results region) or skip the turn. Two identical accents in a session feels like a template, not a design.

Purpose De-Escalation

Visitors typically move from high-energy pages (persuade) toward low-energy pages (convert, inform). The visual intensity should de-escalate to match. Intensity is the combination of scale (full > standard > minimal > none) and posture (authoritative > belonging > restrained); reducing either axis de-escalates.

Navigation Continuity

Header and footer are the compositional spine, consistent across every page.

• Header: lightest element on every page. Breathing room. No per-page header styling. The header provides orientation; the page provides expression.
• Footer: always dark. Provides closure. Same structure across pages. The footer is the site’s consistent ending, not a per-page design surface.
• Breadcrumb / wayfinding: uses teal as functional color (trust region). Not decorative.

These invariants make page-level variation feel coherent. Without them, a dark homepage followed by a light product page feels like two different sites.

Entry Point Awareness

Not every visitor starts at the homepage. With 60%+ arriving from LLMs, many land on secondary or tertiary pages. Site-level composition must accommodate this:

• Every page works standalone (the self-contained rule from page-level composition)
• But pages also work in sequence (the de-escalation and scarcity rules above)
• When in conflict, standalone wins. A product page must earn its own trust even if the visitor skipped the homepage.

See rules/visual-rules.yml -> composition.site-level for the machine-consumable version.

Spoken Voice

How Verdigris sounds when content is spoken aloud. Extends the written voice rules from Assist x Chat to any surface with audio output: video narration, AI assistant speech, ad voiceovers, accessibility.

Voice Pillars

The same brand pillars that govern written voice govern spoken voice. Each maps to a concrete vocal quality.

Single Voice, Purpose-Adapted

One primary voice builds brand recognition (like teal). Style parameters adapt by purpose.

Voice Brief Format

A voice brief is the spoken equivalent of a color token: a declarative description that a TTS pipeline resolves into audio. The brief should be specific enough to reproduce consistently.

voice.brand.primary:
  age_range: [pending stakeholder decision]
  gender: [pending stakeholder decision]
  qualities:
    - calm authority without coldness
    - measured pace, unhurried but not slow
    - clear enunciation, no mumbling or trailing off
    - natural breath pauses at clause boundaries
    - steady pitch with subtle emphasis on key data
  anti-qualities:
    - no vocal fry or uptalk
    - no filler words (um, uh, like, you know)
    - no breathy or ASMR quality
    - no announcer energy or radio voice
    - no synthetic flatness (must sound like a person)
  reference_prompt: "The voice of a senior engineer presenting
    findings to a board. They know the data cold. They respect
    the audience's time. They are confident without performing
    confidence."

Demographic Attributes

Gender, age, and accent carry cultural weight. These attributes require stakeholder input and cannot be decided by design-system logic alone.

Constraints

• Voice must pass the same “no personality theater” test as written Assist x Chat content
• Pace must stay within 140-170 wpm (floor: comprehension; ceiling: rushed feeling)
• No background music or sound design in voice-only content. Music is a separate design decision.
• Reduced-motion users who have opted out of animation should not receive auto-playing audio. Audio requires explicit user action.
• All spoken content must have a text transcript (accessibility, EU AI Act Article 50 for AI-generated speech)

Visual Signature

The Verdigris visual signature derives from the product: 8,000 samples per second of electrical data, made visible. The signature is not a logo treatment or an illustration style. It is a family of data-derived visual patterns that only an electrical intelligence company can produce.

Canonical Brand Visualizations

These are the official visual signature elements. They appear on marketing pages, in Remotion videos, and as design system specimens. Each is grounded in real electrical engineering concepts.

What Is NOT a Brand Visualization

• Generic sine waves with no harmonic content (could be any company)
• Particle systems or dot fields not derived from electrical data
• Abstract gradient meshes (the Stripe look)
• Network/node graphs that don’t represent actual circuit topology
• Waveforms used as pure decoration without connection to section content

Canvas-Rendered Text

Some brand effects require rendering text to Canvas rather than DOM. This is a significant architectural decision with accessibility, performance, and SEO implications.

When to use Canvas text:

• Character-level effects that CSS cannot achieve (per-character displacement, SDF morphing, text as clipping mask)
• Text that must interact with Canvas visualizations (labels positioned on waveform data points)
• Effects requiring sub-pixel character positioning (Pretext measurement)

When NOT to use Canvas text:

• Body copy, paragraphs, any text meant to be read at length
• Navigation, buttons, form labels, or any interactive text
• Text that needs to be selectable, translatable, or indexed by search engines
• Anything that can be achieved with CSS transforms, opacity, or clip-path

Mandatory requirements for Canvas text:

1. Every Canvas text element must have an identical HTML fallback, hidden when Canvas is active
2. The HTML fallback must use the same typography tokens (font family, weight, size, color)
3. prefers-reduced-motion: reduce must show the HTML fallback and hide the Canvas
4. The Canvas element must have role="img" and aria-label matching the text content
5. No Canvas text in the critical rendering path. Fonts load first, Canvas initializes after.

Named Text Effects

Three named effects are part of the visual signature. Each has exact specifications for timing, color, and behavior. These effects are exclusive to the Demonstrate x Web Page composition cell (Technology/Signal page). They do not appear on the homepage, product pages, or any other page type. The homepage earns its impact through composition restraint, not Canvas effects.

Attention budget: At most 2 animated elements visible in any single viewport at any time. The ambient waveform counts as one if its opacity exceeds 10%. Named effects count when actively animating (not after completion). The resolution slider counts when the user is interacting with it.

Reading constraint: Heading text must reach full legibility (final color, complete letterforms) before expected reading completion. For headings under 40 characters, fully legible within 600ms. For longer headings, within 800ms. If the full effect duration exceeds the legibility deadline, text resolves first and ambient glow/color continues after.

1. Measurement Bar Reveal

Characters materialize from 1px vertical bars (oscilloscope cursor metaphor) that widen to reveal the full letterform.

2. Harmonic Typography

Large display text where digit shapes are clipping masks revealing live waveform data scrolling behind them.

3. Waveform-to-Text Reveal

Section heading starts as a continuous oscilloscope trace spanning the full text width, then resolves into readable letterforms.

Ambient Waveform Layer

A persistent 60Hz sine wave that runs behind page content at low opacity. This is the page’s “heartbeat” – the AC power frequency made visible.

The ambient layer appears only on dark-background sections. On light backgrounds (Context, Proof, light-mode Evidence), the waveform layer is hidden – the section’s neutral background does the work. This prevents a teal tint from contaminating neutral breathing-room sections.

Constraints:

• Rendered as a single Canvas layer behind all content
• Never more than 20% opacity (reduced from 25% – it’s ambient, not a feature)
• On dark sections: contrast ratio of foreground text vs (background + wave at peak opacity) must meet WCAG AA for large text (3.0:1)
• prefers-reduced-motion: static thin line at 8% opacity, no animation
• The waveform frequency (60Hz visual cycles per screen width) is a design constant, not adjustable per page
• The ambient layer counts toward the attention budget (see Named Text Effects) when its opacity exceeds 10%

Interactive Data Visualization

Data visualizations on marketing pages follow different rules than dashboards.

Technology Page Composition Cell

The Technology/Signal page is a new composition cell: Demonstrate x Web Page.