@formant/aesthetics 0.1.2 → 0.1.4

package/DESIGN.md

@@ -0,0 +1,485 @@
+# Formant Design System
+
+## 1. Visual Theme & Atmosphere
+
+Formant's interface is a mission-control environment where data is the primary light source. The Deep Command canvas (`#0A0F11`) creates a near-void -- not darkness for aesthetic effect, but the operational darkness of a control room at 3am, where every illuminated element represents a signal that demands attention. Information emerges from this void through carefully calibrated luminance: Fog Green borders at the threshold of perception, Terminal Amber warnings that cut through like instrument readings, and the steady pulse of Horizon Glow guiding operators through complexity. This is not a dark theme applied to a light design. This is darkness as the native medium of industrial intelligence.
+
+The typography system uses three typefaces in strict roles. Space Grotesk handles all display and heading text -- a geometric sans with just enough character to feel architectural rather than generic. At headline sizes, it runs at weight 500-600 with tight letter-spacing (-0.02em), creating dense, confident blocks of text that read like engineering specifications rather than marketing copy. Inter serves as the body workhorse: weight 400 at 16px with 1.6 line-height for comfortable reading on dark backgrounds. JetBrains Mono completes the system as the data voice -- used for eyebrow labels, status tags, and telemetry readouts at 10-11px with 0.1-0.2em tracking and uppercase transform, creating the stenciled, instrument-panel aesthetic of a spacecraft HUD.
+
+The color system is deliberately narrow: nine named colors, each with an atmospheric origin. Deep Command and Slate Mist handle 70-80% of all surface area. Fog Green, Ethereal Teal, and Horizon Glow manage the atmospheric middle layer -- borders, active states, and interactive elements. Terminal Amber and Interface Iris appear in under 5% of the UI, reserved exclusively for moments requiring human attention: warnings, AI states, and system intelligence indicators. The border system is entirely opacity-based, using System Neutral at 10-40% opacity to create structure without visual noise -- like wireframes drawn in fog.
+
+**Key Characteristics:**
+- Dark-mode-native: `#0A0F11` (Deep Command) base, `#202428` (Slate Mist) cards, never light backgrounds
+- Three-typeface system: Space Grotesk (display), Inter (body), JetBrains Mono (data/labels)
+- Nine-color palette with atmospheric names: Deep Command, Slate Mist, Fog Green, Ethereal Teal, Horizon Glow, Terminal Amber, Interface Iris, Formant White, System Neutral
+- Opacity-based border system: `rgba(163,171,169, 0.1)` to `rgba(163,171,169, 0.4)` -- never solid borders
+- JetBrains Mono uppercase with wide tracking for eyebrow labels -- the mission-control HUD voice
+- Horizon Glow (`#ACC3B3`) as the sole interactive accent -- muted green, not a saturated primary
+- Terminal Amber (`#E8AB7F`) reserved strictly for warnings and attention-demanding labels
+- Interface Iris (`#8B8CF4`) reserved strictly for AI states and system intelligence
+- Fade-up entrance animations (0.7s ease, 24px translateY) with staggered 80ms delays
+- CSS custom properties importable from `formant-properties.css` (Version 2026.1)
+
+## 2. Color Palette & Roles
+
+### Primary Neutrals (70-80% of all usage)
+
+- **Deep Command** (`#0A0F11`, `rgb(10, 15, 17)`) -- `--formant-deep-command`: The void. Primary backgrounds, base layer, the darkness from which all data emerges. Not pure black -- an imperceptible blue-cool undertone that prevents harshness.
+- **Slate Mist** (`#202428`, `rgb(32, 36, 40)`) -- `--formant-slate-mist`: One step above the void. Card backgrounds, secondary surfaces, elevated panels. The lightest a surface should get.
+- **Formant White** (`#F2F3F4`, `rgb(242, 243, 244)`) -- `--formant-formant-white`: Primary text, headlines, and high-emphasis content. Not pure white -- the slight warm cast prevents eye strain on dark backgrounds.
+- **System Neutral** (`#A3ABA9`, `rgb(163, 171, 169)`) -- `--formant-system-neutral`: Body text, captions, secondary content. Also the base color for the opacity-based border system.
+
+### Atmospheric Accents (40-60% of remaining usage)
+
+- **Fog Green** (`#4B5E53`, `rgb(75, 94, 83)`) -- `--formant-fog-green`: Borders, dividers, muted accents, field name labels in data displays. The structural color -- present everywhere, visible nowhere.
+- **Ethereal Teal** (`#2C4142`, `rgb(44, 65, 66)`) -- `--formant-ethereal-teal`: Active states, hover backgrounds on panels, subtle surface elevation. The "something is happening here" indicator.
+- **Horizon Glow** (`#ACC3B3`, `rgb(172, 195, 179)`) -- `--formant-horizon-glow`: Primary CTAs, interactive elements, success states, links. The sole accent for user-driven actions. Muted, not saturated -- it guides without demanding.
+
+### Functional UI Accents (under 5% of all usage)
+
+- **Terminal Amber** (`#E8AB7F`, `rgb(232, 171, 127)`) -- `--formant-terminal-amber`: Warnings, eyebrow text, alarm labels, attention-demanding states. The amber glow of a critical instrument reading.
+- **Interface Iris** (`#8B8CF4`, `rgb(139, 140, 244)`) -- `--formant-interface-iris`: AI states, system intelligence indicators, auto-resolution patterns. Reserved for moments where the system acts autonomously.
+
+### Semantic Token Mappings
+
+**Backgrounds:**
+- `--formant-bg-primary`: Deep Command (`#0A0F11`)
+- `--formant-bg-secondary`: Slate Mist (`#202428`)
+- `--formant-bg-elevated`: Slate Mist (`#202428`)
+
+**Text:**
+- `--formant-text-primary`: Formant White (`#F2F3F4`)
+- `--formant-text-secondary`: System Neutral (`#A3ABA9`)
+- `--formant-text-muted`: System Neutral at 60% opacity (`rgba(163, 171, 169, 0.6)`)
+
+**Interactive:**
+- `--formant-accent-primary`: Horizon Glow (`#ACC3B3`)
+- `--formant-accent-secondary`: Ethereal Teal (`#2C4142`)
+- `--formant-accent-warning`: Terminal Amber (`#E8AB7F`)
+- `--formant-accent-ai`: Interface Iris (`#8B8CF4`)
+
+**Borders (opacity-based system on System Neutral base):**
+- `--formant-border-subtle`: `rgba(163, 171, 169, 0.1)` -- barely visible, structural
+- `--formant-border-default`: `rgba(163, 171, 169, 0.2)` -- standard dividers
+- `--formant-border-strong`: `rgba(163, 171, 169, 0.4)` -- emphasized boundaries
+
+**Status:**
+- Success: Horizon Glow (`#ACC3B3`)
+- Warning: Terminal Amber (`#E8AB7F`)
+- Error: Terminal Amber (`#E8AB7F`)
+- Info: Interface Iris (`#8B8CF4`)
+- AI Active: Interface Iris (`#8B8CF4`)
+
+## 3. Typography Rules
+
+### Font Families
+- **Display / Headlines**: `'Space Grotesk', sans-serif` -- `--formant-font-heading` -- loaded via Google Fonts at weights 300, 500, 600, 700
+- **Body / Interface**: `'Inter', sans-serif` -- `--formant-font-body` -- loaded via Google Fonts at weights 300, 400, 500, 600
+- **Monospace / Data**: `'JetBrains Mono', monospace` -- `--formant-font-mono` -- loaded via Google Fonts at weights 300, 400, 500
+
+### Weight Tokens
+- `--formant-weight-light`: 300
+- `--formant-weight-regular`: 400
+- `--formant-weight-medium`: 500
+- `--formant-weight-semibold`: 600
+- `--formant-weight-bold`: 700
+
+### Tracking Tokens
+- `--formant-tracking-tight`: -0.02em (display headlines)
+- `--formant-tracking-normal`: 0
+- `--formant-tracking-wide`: 0.02em
+- `--formant-tracking-wider`: 0.08em
+- `--formant-tracking-mono`: 0.1em (JetBrains Mono labels)
+
+### Line Height Tokens
+- `--formant-leading-tight`: 1.2 (headlines)
+- `--formant-leading-normal`: 1.6 (body text)
+- `--formant-leading-relaxed`: 1.75 (long-form reading)
+
+### Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing | Color | Notes |
+|------|------|------|--------|-------------|----------------|-------|-------|
+| Display | Space Grotesk | 96px (clamp 32-96px) | 300 | 1.2 (tight) | -0.02em | Formant White | Hero headlines, maximum impact |
+| H1 | Space Grotesk | 52px (clamp 24-52px) | 500 | 1.2 (tight) | -0.02em | Formant White | Page titles, section headers |
+| H2 | Space Grotesk | 32px (clamp 20-32px) | 500 | 1.2 (tight) | normal | Formant White | Sub-section headings |
+| H3 | Space Grotesk | 20px | 600 | 1.2 (tight) | normal | Horizon Glow | Feature titles, card headers -- accent colored |
+| Body Large | Inter | 17px | 400 | 1.75 (relaxed) | normal | System Neutral | Introductions, section descriptions, max-width 600px |
+| Body | Inter | 16px | 400 | 1.6 | normal | System Neutral | Standard reading text |
+| Body Medium | Inter | 14-16px | 500 | 1.6 | normal | System Neutral | Navigation, emphasized body |
+| Body Semibold | Inter | 14-16px | 600 | 1.6 | normal | Formant White | Strong emphasis, active states |
+| Caption | Inter | 12px | 400 | 1.6 | normal | System Neutral | Metadata, descriptions |
+| Eyebrow | JetBrains Mono | 10px | 400 | 1.4 | 0.2em | Terminal Amber | `text-transform: uppercase`. Section labels, category markers |
+| Tag Label | JetBrains Mono | 11px | 400 | 1.4 | 0.1em | (varies by tag type) | `text-transform: uppercase`. Status tags, badges |
+| Data Label | JetBrains Mono | 10px | 400 | 1.4 | 0.1em | System Neutral | `text-transform: uppercase`. Column headers in data displays |
+| Data Value | JetBrains Mono | 13px | 400 | 2.2 | normal | Formant White | Telemetry readouts, data table values |
+| Data Field | JetBrains Mono | 13px | 400 | 2.2 | normal | Fog Green | Field names in terminal-style data |
+| Button | Inter | 13px | 500 | 1.0 | 0.04em | (varies) | `text-transform: uppercase`. All button text |
+
+### Principles
+- **Three voices, strict roles**: Space Grotesk is the architectural voice (headlines that feel engineered). Inter is the human voice (body text that reads clearly on dark backgrounds). JetBrains Mono is the machine voice (data, labels, and system status).
+- **H3 is the accent headline**: Unlike H1/H2 which use Formant White, H3 uses Horizon Glow (`#ACC3B3`) at weight 600 -- the one place in the type hierarchy where color enters the heading system.
+- **Eyebrows are Terminal Amber**: The JetBrains Mono eyebrow pattern (10px, uppercase, 0.2em tracking, Terminal Amber) prefixed by a 24px horizontal rule is the section-opening pattern. Every major content block begins this way.
+- **Data display is its own typographic world**: JetBrains Mono at 13px with 2.2 line-height creates generously spaced terminal-style readouts where field names (Fog Green) and values (Formant White) are clearly distinguished.
+
+## 4. Component Stylings
+
+### Buttons
+
+**Primary (Horizon Glow)**
+- Background: `#ACC3B3`
+- Text: `#0A0F11` (Deep Command)
+- Padding: 12px 24px
+- Radius: 3px
+- Font: Inter 13px weight 500, `text-transform: uppercase`, `letter-spacing: 0.04em`
+- Hover: background shifts to `#ffffff`
+- Use: Primary CTA ("Request Architecture Audit ->")
+
+**Secondary (Outlined)**
+- Background: transparent
+- Text: `#ACC3B3` (Horizon Glow)
+- Padding: 12px 24px
+- Radius: 3px
+- Border: `1px solid #ACC3B3`
+- Font: Inter 13px weight 500, `text-transform: uppercase`, `letter-spacing: 0.04em`
+- Hover: background tints to Horizon Glow at ~10% opacity
+- Use: Secondary actions ("Deploy Physical Agent")
+
+**Ghost (Neutral)**
+- Background: transparent
+- Text: `#A3ABA9` (System Neutral)
+- Padding: 12px 24px
+- Radius: 3px
+- Border: `1px solid #A3ABA9`
+- Font: Inter 13px weight 500, `text-transform: uppercase`, `letter-spacing: 0.04em`
+- Hover: text and border lighten
+- Use: Tertiary actions ("View Documentation")
+
+**Accent (Warning)**
+- Background: `#E8AB7F` (Terminal Amber)
+- Text: `#0A0F11` (Deep Command)
+- Padding: 12px 24px
+- Radius: 3px
+- Font: Inter 13px weight 500, `text-transform: uppercase`, `letter-spacing: 0.04em`
+- Hover: background lightens
+- Use: Alert-driven actions ("Alert: Critical")
+
+### Status Tags
+
+**Mist Tag (Resolved/Verified)**
+- Background: `rgba(75, 94, 83, 0.3)` (Fog Green at 30%)
+- Text: `#ACC3B3` (Horizon Glow)
+- Border: `1px solid rgba(75, 94, 83, 0.4)`
+- Padding: 4px 12px
+- Radius: 2px
+- Font: JetBrains Mono 11px, `text-transform: uppercase`, `letter-spacing: 0.1em`
+
+**Teal Tag (Investigating)**
+- Background: `rgba(44, 65, 66, 0.4)` (Ethereal Teal at 40%)
+- Text: `#ACC3B3` (Horizon Glow)
+- Padding: 4px 12px
+- Radius: 2px
+- Font: JetBrains Mono 11px, `text-transform: uppercase`, `letter-spacing: 0.1em`
+
+**Amber Tag (Warning)**
+- Background: `rgba(232, 171, 127, 0.1)` (Terminal Amber at 10%)
+- Text: `#E8AB7F` (Terminal Amber)
+- Padding: 4px 12px
+- Radius: 2px
+- Font: JetBrains Mono 11px, `text-transform: uppercase`, `letter-spacing: 0.1em`
+
+**Iris Tag (AI Active)**
+- Background: `rgba(139, 140, 244, 0.1)` (Interface Iris at 10%)
+- Text: `#8B8CF4` (Interface Iris)
+- Padding: 4px 12px
+- Radius: 2px
+- Font: JetBrains Mono 11px, `text-transform: uppercase`, `letter-spacing: 0.1em`
+
+### System Alerts
+
+**Info Alert**
+- Background: `rgba(44, 65, 66, 0.3)` (Ethereal Teal at 30%)
+- Text: `#ACC3B3` (Horizon Glow)
+- Left indicator: 6px circle, Horizon Glow
+- Font: Inter 14px, weight 400
+- Use: Non-critical system messages, AI confidence reports
+
+**Warning Alert**
+- Background: `rgba(232, 171, 127, 0.08)` (Terminal Amber at 8%)
+- Text: `#E8AB7F` (Terminal Amber)
+- Left indicator: 6px circle, Terminal Amber
+- Font: Inter 14px, weight 400
+- Use: Pressure spikes, threshold breaches, human-attention-required
+
+**AI Alert**
+- Background: `rgba(139, 140, 244, 0.08)` (Interface Iris at 8%)
+- Text: `#8B8CF4` (Interface Iris)
+- Left indicator: 6px circle, Interface Iris
+- Font: Inter 14px, weight 400
+- Use: Pattern recognition, autonomous resolution, AI-driven actions
+
+### Form Inputs
+
+- Background: `#0A0F11` (Deep Command)
+- Border: `1px solid rgba(163, 171, 169, 0.2)`, radius 3px
+- Text: Inter 14px, Formant White (`#F2F3F4`)
+- Placeholder: `rgba(163, 171, 169, 0.5)` (System Neutral at 50%)
+- Focus: border changes to `#ACC3B3` (Horizon Glow)
+- Label: JetBrains Mono 10px, System Neutral, `text-transform: uppercase`, `letter-spacing: 0.15em`
+
+### Data Display (Terminal Style)
+
+- Font: JetBrains Mono 13px, line-height 2.2
+- Header row: System Neutral (`#A3ABA9`), `letter-spacing: 0.1em`
+- Field names: Fog Green (`#4B5E53`)
+- Standard values: Formant White (`#F2F3F4`)
+- Status values: color-coded -- Horizon Glow (resolved/online), Interface Iris (AI-verified/auto), Terminal Amber (compounding/warning)
+- Row separation: implicit through generous line-height, no visible dividers
+
+### Navigation
+
+- Position: fixed, height 64px
+- Background: `rgba(10, 15, 17, 0.85)` (Deep Command at 85% opacity)
+- Backdrop: `blur(16px)`
+- Links: Inter 14px weight 500, System Neutral text
+- Active/hover: text shifts to Formant White
+- CTA: Primary button (Horizon Glow) right-aligned
+- Logo: Formant geometric mark left-aligned
+- Responsive: nav links hidden below 900px
+
+### Image Treatment
+
+- Product screenshots and atmospheric photography on dark backgrounds
+- Cinematic wide-angle shots: misty landscapes, command consoles, operational environments
+- Video: background loop in hero, hover-to-play in visual library sections
+- Still photography: desaturated, atmospheric -- the "Generative Horizon" visual pillar
+
+## 5. Layout Principles
+
+### Spacing System
+
+| Token | Value | Pixels | Use |
+|-------|-------|--------|-----|
+| `--formant-space-1` | 0.25rem | 4px | Micro gaps, icon padding |
+| `--formant-space-2` | 0.5rem | 8px | Tight element spacing |
+| `--formant-space-3` | 0.75rem | 12px | Tag/badge internal padding |
+| `--formant-space-4` | 1rem | 16px | Standard element spacing |
+| `--formant-space-5` | 1.25rem | 20px | Comfortable spacing |
+| `--formant-space-6` | 1.5rem | 24px | Card internal padding |
+| `--formant-space-8` | 2rem | 32px | Section sub-spacing |
+| `--formant-space-10` | 2.5rem | 40px | Major element gaps |
+| `--formant-space-12` | 3rem | 48px | Section transitions |
+| `--formant-space-16` | 4rem | 64px | Section padding (mobile) |
+| `--formant-space-20` | 5rem | 80px | Section padding (tablet) |
+| `--formant-space-24` | 6rem | 96px | Section padding (desktop) |
+
+### Grid & Container
+
+- Max content width: 1200px, centered with `margin: 0 auto`
+- Horizontal padding: 40px (20px on mobile)
+- Hero: full viewport height (min 700px), centered single-column
+- Feature sections: 2-3 column grids for cards
+- Architecture layers: full-width stacked bands
+- Data displays: full-width terminal-style blocks
+
+### Section Pattern
+
+Every major content section follows this structure:
+1. **Section label**: JetBrains Mono 10px, Terminal Amber, uppercase, 0.2em tracking, prefixed by a 24px horizontal rule
+2. **Section title**: Space Grotesk 500, 32-52px (clamp), Formant White, tight leading
+3. **Section description**: Inter 17px, System Neutral, max-width 600px, 1.75 line-height
+4. **Content area**: specific to section type
+
+### Whitespace Philosophy
+
+- **Darkness IS the whitespace**: On Formant's Deep Command canvas, empty space isn't white -- it's the operational void between signal sources. The dark background provides natural section separation without dividers.
+- **Compressed headlines, expanded surroundings**: Space Grotesk at 52px with -0.02em tracking is dense and authoritative, but sits within 120px vertical section padding. The contrast between typographic density and spatial generosity creates the "architectural authority" of the brand.
+- **Section isolation**: Each content section is separated by 120px vertical padding with no visible borders or dividers. Horizontal gradient dividers (`linear-gradient(90deg, transparent, rgba(163,171,169,0.2), transparent)`) appear only between major thematic shifts.
+
+### Border Radius Scale
+
+| Token | Value | Use |
+|-------|-------|-----|
+| `--formant-radius-none` | 0px | Sharp edges, dividers |
+| `--formant-radius-sm` | 2px | Tags, badges, small elements |
+| `--formant-radius-md` | 4px | Standard containers, code blocks |
+| `--formant-radius-lg` | 6px | Larger cards, panels |
+| `--formant-radius-xl` | 8px | Featured cards, hero elements |
+| `--formant-radius-full` | 9999px | Circular avatars, status dots |
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Void (Level 0) | No shadow, `#0A0F11` background | Page background, deepest canvas |
+| Surface (Level 1) | `#202428` background, `1px solid rgba(163,171,169,0.1)` border | Cards, panels, elevated containers |
+| Interactive (Level 2) | `rgba(44,65,66,0.2)` background tint on hover | Hover states, active panels, icon cards |
+| Glow (Level 3) | `0 0 20px rgba(172,195,179,0.15)` | `--formant-shadow-glow`. Featured elements, primary CTAs on hover |
+| Standard (Level 1b) | `0 1px 2px rgba(0,0,0,0.05)` | `--formant-shadow-sm`. Subtle micro-elevation |
+| Elevated (Level 2b) | `0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06)` | `--formant-shadow-md`. Dropdowns, popovers |
+| Prominent (Level 3b) | `0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -2px rgba(0,0,0,0.05)` | `--formant-shadow-lg`. Modals, dialogs |
+
+**Shadow Philosophy**: On Formant's dark surfaces, traditional dark shadows are nearly invisible. Depth is communicated through two mechanisms: (1) background luminance stepping -- each level increases surface brightness from Deep Command (`#0A0F11`) through Slate Mist (`#202428`) to Ethereal Teal tints, and (2) the Horizon Glow shadow (`rgba(172,195,179,0.15)`), a brand-colored glow that makes featured elements emit the same muted green light as the primary accent. This creates a mission-control aesthetic where active elements literally glow against the operational void. Borders at varying opacities (10-40%) serve as the primary structural depth indicator, not shadows.
+
+## 7. Do's and Don'ts
+
+### Do
+- Use Deep Command (`#0A0F11`) as the base background for all surfaces -- dark-first is non-negotiable
+- Use the three-typeface system strictly: Space Grotesk for headlines, Inter for body, JetBrains Mono for data/labels
+- Apply JetBrains Mono uppercase with 0.1-0.2em tracking for ALL labels, tags, and eyebrows -- the HUD voice
+- Use Terminal Amber (`#E8AB7F`) for eyebrow labels prefixed by a horizontal rule -- the section-opening pattern
+- Use opacity-based borders (`rgba(163,171,169, 0.1-0.4)`) instead of solid colored borders
+- Reserve Horizon Glow (`#ACC3B3`) for interactive elements and CTAs only -- it's the guide, not decoration
+- Reserve Terminal Amber for warnings and attention states -- it's the alarm, not an accent
+- Reserve Interface Iris (`#8B8CF4`) strictly for AI-driven states -- it signals machine intelligence
+- Use `#F2F3F4` (Formant White) for primary text, not pure `#ffffff`
+- Keep border-radius between 2-8px -- the system is architectural, not playful
+- Use the section pattern: eyebrow -> headline -> description -> content
+- Use Formant's brand vocabulary: "The Interface" not "Dashboard", "Physical Agent" not "Robot"
+- Capitalize architectural entities: THE BRAIN, THE BODY, THE CONTEXT
+- Import `formant-properties.css` for all design tokens
+
+### Don't
+- Don't use light/white backgrounds -- Formant has no light mode
+- Don't use saturated, bright accent colors -- the palette is muted and atmospheric
+- Don't use bold (700) for Space Grotesk body text -- max weight for body is 600
+- Don't use solid colored borders on dark backgrounds -- always use the opacity-based system
+- Don't apply Terminal Amber or Interface Iris decoratively -- they are functional status colors only
+- Don't use pill-shaped buttons (9999px radius) -- buttons use 3px radius, architecturally sharp
+- Don't use "friendly" or bright SaaS aesthetics -- Formant is mission-control, not consumer software
+- Don't use sentence case for labels or tags -- JetBrains Mono labels are always uppercase
+- Don't say "Dashboard" -- say "The Interface" (active command, not passive viewing)
+- Don't say "Robot" -- say "Physical Agent" (intelligent entity, not hardware)
+- Don't say "Automation" -- say "Bounded Autonomy" (human-in-the-loop, not replacement)
+- Don't say "Demo" -- say "Architecture Audit" (diagnostic engagement, not a pitch)
+- Don't use large radius (12px+) on cards or containers -- the aesthetic is architectural precision
+- Don't use positive letter-spacing on Space Grotesk headlines -- tracking is tight (-0.02em) or normal
+- Don't introduce warm colors (orange, yellow, red) beyond Terminal Amber -- the palette is cool-atmospheric
+
+## 8. Responsive Behavior
+
+### Breakpoints
+
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Mobile | <600px | Single column, voice principles stack, palette rows stack, icon grid 3-col, container padding 20px, section padding 80px |
+| Tablet | 600-900px | Two-column grids begin, video grid 2-col, stills grid 2-col, voice principles 2-col |
+| Desktop | >900px | Full layout, multi-column grids, nav links visible, container padding 40px, section padding 120px |
+
+### Touch Targets
+- Buttons: 12px 24px padding provides comfortable 48px+ touch height
+- Navigation links: 14px font with adequate spacing
+- Tags: 4px 12px padding at minimum
+- Icon cards: generous padding with hover feedback (`translateY(-3px)`)
+
+### Collapsing Strategy
+- Hero: Display 96px -> 32px via `clamp()`, maintains viewport height (min 700px)
+- H1: 52px -> 24px via `clamp()`
+- H2: 32px -> 20px via `clamp()`
+- Navigation: horizontal links + CTA -> nav links hidden below 900px
+- Feature grids: 3-column -> 2-column -> single column stacked
+- Architecture layers: maintain full-width stacked layout at all sizes
+- Data displays: maintain terminal-style formatting, may horizontally scroll
+- Section padding: 120px -> 80px on mobile
+- Container padding: 40px -> 20px on mobile
+
+### Image & Video Behavior
+- Hero video: maintains full-viewport background at all sizes
+- Visual library: grid collapses from multi-column to single-column
+- Still photography: maintains atmospheric aspect ratios, stacks vertically
+- Videos: hover-to-play on desktop, tap-to-play on mobile
+
+### Animation Behavior
+- Fade-up animations maintained across all breakpoints
+- IntersectionObserver threshold: 10% visible, -40px root margin
+- Stagger delay: groups of 4 elements, 80ms incremental delay
+- Transition: `opacity 0.7s ease, transform 0.7s ease`
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Page background: Deep Command (`#0A0F11`)
+- Card background: Slate Mist (`#202428`)
+- Heading text: Formant White (`#F2F3F4`)
+- Body text: System Neutral (`#A3ABA9`)
+- Muted text: System Neutral at 60% (`rgba(163,171,169,0.6)`)
+- Primary CTA: Horizon Glow (`#ACC3B3`)
+- Warning: Terminal Amber (`#E8AB7F`)
+- AI state: Interface Iris (`#8B8CF4`)
+- Border (subtle): `rgba(163,171,169,0.1)`
+- Border (default): `rgba(163,171,169,0.2)`
+- Border (strong): `rgba(163,171,169,0.4)`
+- Glow shadow: `0 0 20px rgba(172,195,179,0.15)`
+
+### Example Component Prompts
+
+- **Hero section**: "Create a hero on `#0A0F11` background, full viewport height (min 700px). Eyebrow label: JetBrains Mono 10px, `#E8AB7F`, uppercase, letter-spacing 0.2em, preceded by a 24px horizontal rule in Terminal Amber. Headline: Space Grotesk 52px weight 500, line-height 1.2, letter-spacing -0.02em, `#F2F3F4`. Description: Inter 17px weight 400, line-height 1.75, `#A3ABA9`, max-width 600px. Primary CTA button: `#ACC3B3` bg, `#0A0F11` text, 12px 24px padding, 3px radius, Inter 13px weight 500 uppercase."
+
+- **Card**: "Design a card on `#202428` background with `1px solid rgba(163,171,169,0.1)` border, 4px radius. Hover: border changes to `rgba(172,195,179,0.3)`, background shifts to `rgba(44,65,66,0.2)`, `scale(1.01)`. Title: Space Grotesk 20px weight 600, `#ACC3B3`. Body: Inter 14px weight 400, `#A3ABA9`."
+
+- **Status tag**: "Build an AI status tag: `rgba(139,140,244,0.1)` background, `#8B8CF4` text, 4px 12px padding, 2px radius, JetBrains Mono 11px, uppercase, letter-spacing 0.1em. Text: 'AI ACTIVE'."
+
+- **System alert**: "Create a warning alert: `rgba(232,171,127,0.08)` background, `#E8AB7F` text. Left indicator: 6px circle in Terminal Amber. Body: Inter 14px weight 400. Text: 'Pressure spike detected on Line 7. Operator review required.'"
+
+- **Navigation**: "Create navigation: fixed position, 64px height, `rgba(10,15,17,0.85)` background with `backdrop-filter: blur(16px)`. Links: Inter 14px weight 500, `#A3ABA9` text, hover to `#F2F3F4`. Primary CTA right-aligned: Horizon Glow button. Bottom border: `1px solid rgba(163,171,169,0.1)`."
+
+- **Data display**: "Build a terminal-style data display: JetBrains Mono 13px, line-height 2.2. Header row: `#A3ABA9`, letter-spacing 0.1em. Field names: `#4B5E53` (Fog Green). Values: `#F2F3F4`. Status values: `#ACC3B3` for 'RESOLVED', `#8B8CF4` for 'AI-VERIFIED', `#E8AB7F` for 'WARNING'."
+
+- **Section opener**: "Create a section opener: (1) JetBrains Mono 10px, `#E8AB7F`, uppercase, 0.2em tracking, with a 24px horizontal rule prefix in the same color. (2) Space Grotesk weight 500, 32px (clamp 20-32px), `#F2F3F4`, line-height 1.2. (3) Inter 17px weight 400, `#A3ABA9`, line-height 1.75, max-width 600px."
+
+### Iteration Guide
+1. Always start with `#0A0F11` -- every surface begins from darkness
+2. Three typefaces, strict roles: Space Grotesk (announce), Inter (explain), JetBrains Mono (label/data)
+3. Borders are opacity-based: `rgba(163,171,169, 0.1/0.2/0.4)` -- never solid colors on dark
+4. Only three accent colors exist: Horizon Glow (interaction), Terminal Amber (warning), Interface Iris (AI)
+5. Buttons are 3px radius, uppercase Inter 13px -- architecturally sharp, never pill-shaped
+6. Tags are 2px radius, uppercase JetBrains Mono 11px -- the machine voice
+7. Every section begins with the eyebrow pattern: horizontal rule + JetBrains Mono + Terminal Amber
+8. Import `formant-properties.css` to get all tokens as CSS custom properties
+9. Use Formant vocabulary: The Interface, Physical Agent, Bounded Autonomy, Architecture Audit
+10. The glow shadow (`0 0 20px rgba(172,195,179,0.15)`) is the signature depth effect -- use it on featured CTAs and highlighted elements
+
+## 10. Voice, Tone & Brand Vocabulary
+
+### Voice Principles
+
+1. **Architectural Authority**: Speak with the precision of an engineer and the vision of an architect. Short, punchy, declarative sentences. Treat core entities (THE BRAIN, THE BODY, THE CONTEXT) as proper architectural constructs.
+2. **Cinematic Clarity**: Atmospheric yet grounded language. Use metaphors of light, mist, and horizons. Frame the future of operations as a single, unified pulse.
+3. **Mission Control Tone**: Calm, steady, grounded. Do not perform urgency or certainty. Frame challenges as a "Visibility Crisis" -- a loss of human meaning, not just data.
+4. **Compounding Intelligence**: Position the system as an irreplaceable asset that learns over time. "Success isn't hired -- it's configured."
+5. **Neutral Convener**: Formant is the essential meeting point. Speak with authority but without ego.
+
+### Brand Glossary
+
+| Formant Term | Replaces | Meaning |
+|---|---|---|
+| **The Interface** | "Dashboard" | Active command -- not passive viewing |
+| **Physical Agent** | "Robot" | Elevates hardware to intelligent entity |
+| **Bounded Autonomy** | "Automation" | Control, safety, human-in-the-loop precision |
+| **Algorithmic Propagation** | "Deployment" | Speed of intelligence, not hardware logistics |
+| **Architecture Audit** | "Demo" / "Sales Call" | Diagnostic engagement, not a pitch |
+| **Systemic Command** | (end-state) | From operational chaos to total command |
+
+## 11. Icon System
+
+### Specifications
+- Format: SVG, 64x64 viewBox
+- Stroke: 2px weight, `stroke-linecap: round`
+- Style: Open and atmospheric -- no fills in UI contexts
+- Default color: Horizon Glow (`#ACC3B3`)
+- Warning icons: Terminal Amber (`#E8AB7F`)
+- AI icons: Interface Iris (`#8B8CF4`)
+
+### Size Scale
+
+| Size | Pixels | Use |
+|------|--------|-----|
+| Inline | 16px | Inline with text |
+| Label | 24px | Next to UI labels |
+| Button | 32px | Inside buttons |
+| Card | 48px | Card illustrations |
+| Feature | 64px | Feature section icons |
+| Hero | 96px | Hero-level display |
+
+### Available Icons
+Physical Agent, Fleet, Mission, Guardrail, The Brain, Context, The Interface, Anomaly (amber), Resolution, Telemetry, Blueprint, Digital Twin, Operator, Horizon, Command, Propagate, FDE, Alarm (amber), Savings, Bounded Autonomy (iris)

package/formant-aesthetics.css

@@ -1310,6 +1310,20 @@ body > header input[type="search"] {
   width: 200px;
 }
 
+/* Headings inside site header - match logo styling */
+body > header h1,
+body > header h2,
+body > header h3 {
+  font-family: var(--font-display);
+  font-size: 1.25rem;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--theme-neutrals-3);
+  margin: 0;
+  line-height: 1;
+}
+
 /* Content headers - inside main, article, section (boxed styling) */
 main > header,
 article > header,

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@formant/aesthetics",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Classless CSS framework based on the Formant Design System. Styles standard HTML elements without requiring any classes.",
   "main": "formant-aesthetics.css",
   "files": [
     "formant-aesthetics.css",
-    "README.md"
+    "README.md",
+    "DESIGN.md"
   ],
   "scripts": {
     "serve": "npx serve .",