> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/website/website/design/01-overview.md).

# Design Overview

> **Last Updated**: 2026-02-27 **Status**: Canonical (v1.0) — extracted from landing page implementation
>
> This document is the shared design system for all Gotts web properties. It applies to: `gotts.ai`, `app.gotts.ai`, `portal.gotts.ai`, and all internal debug UIs (devenv, webenv). Protocol terminology used in UI copy: [prd/shared/glossary.md](/docs/prd-shared/glossary.md).

***

## Quick Reference

The 10 most-used tokens for zero-friction lookup:

| Token                          | Value                             |
| ------------------------------ | --------------------------------- |
| `--gold`                       | `#C9A84C`                         |
| `--black`                      | `#0A0A0A`                         |
| `--text` / `--text-dim`        | `#f5f5f7` / `#b8b8bc`             |
| `--gold-dim`                   | `rgba(201, 168, 76, 0.20)`        |
| `--glass-border`               | `rgba(255, 255, 255, 0.08)`       |
| `--ease-luxury`                | `cubic-bezier(0.22, 1, 0.36, 1)`  |
| `--font-serif` / `--font-mono` | Instrument Serif / JetBrains Mono |

**Gold text gradient** (one-liner):

```css
background: linear-gradient(
  to bottom,
  #f5edd8 0%,
  #e0c97a 35%,
  #c4993c 70%,
  #a07830 100%
);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
background-clip: text;
```

***

## Table of Contents

1. [Design Philosophy](#1-design-philosophy)
2. [Color System](#2-color-system)
3. [Typography](#3-typography)
4. [Glass Morphism System](#4-glass-morphism-system)
5. [PCB Card System](#5-pcb-card-system)
6. [Depth Model & Border Hierarchy](#6-depth-model--border-hierarchy)
7. [Layout & Spacing](#7-layout--spacing)
8. [The Landing-to-App Spectrum](#8-the-landing-to-app-spectrum)
9. [Animation & Motion](#9-animation--motion)
10. [Micro-interaction Catalog](#10-micro-interaction-catalog)
11. [Component Library](#11-component-library)
12. [Pattern Library](#12-pattern-library)
13. [Data Visualization](#13-data-visualization)
14. [Scrollbar, Focus & Selection](#14-scrollbar-focus--selection)
15. [Film Grain & Texture](#15-film-grain--texture)
16. [Custom Cursor](#16-custom-cursor)
17. [Code Styling](#17-code-styling)
18. [Iconography](#18-iconography)
19. [Responsive Strategy](#19-responsive-strategy)
20. [Accessibility](#20-accessibility)
21. [Copy Standards](#21-copy-standards)
22. [Appendices](#appendices)

***

## 1. Design Philosophy

Gotts is institutional infrastructure for autonomous agents. The visual language must communicate three things simultaneously: **safety** (this is a vault — the safest place for sovereign capital), **precision** (every number, every address, every transaction is exact), and **sophistication** (this is premium financial infrastructure, not a toy).

### 1.1 Core Principles

1. **Obsidian & Gold** — Near-black surfaces with restrained gold accents. Gold is earned, not decorative. Every gold element should signal something meaningful: interactivity, status, or emphasis.
2. **Engineering Aesthetic** — PCB traces, hexagonal connectors, octagonal clip-paths, monospaced data. The design says "precision-engineered" without saying it. Hardware metaphors ground abstract financial concepts.
3. **Glass Over Black** — Layered transparency creates depth without color. Glass cards float above the obsidian base. Backdrop blur separates content layers while maintaining the monochrome foundation.
4. **Typography as Hierarchy** — Three fonts, three purposes, zero ambiguity. Serif for authority and beauty. Mono for data and truth. Sans for everything humans need to read comfortably.
5. **Motion as Meaning** — Every animation is luxury-eased with deliberate pacing. Nothing snaps. Nothing bounces. Elements glide into position like vault doors — smooth, weighted, inevitable. Stagger delays create reading order.
6. **Restraint** — The most important principle. Dark surfaces need empty space to breathe. Gold loses its power when overused. The best Gotts screens are the ones with the most negative space.

### 1.2 Brand Voice in Visual Design

* **Not** crypto-bro neon. **Not** fintech gradient pastels. **Not** web3 maximalist noise.
* **Yes** private banking. **Yes** Bloomberg terminal. **Yes** Porsche configurator.
* Think: What would a Swiss vault's digital interface look like if it were designed by engineers who also love typography?

***

## 2. Color System

### 2.1 Foundation Palette

The foundation is near-black with carefully chosen surface elevations.

| Token         | Value     | Usage                                            |
| ------------- | --------- | ------------------------------------------------ |
| `--black`     | `#0A0A0A` | Page background, deepest surface                 |
| `--surface`   | `#111111` | Elevated sections (manifesto, FAQ, footer)       |
| `--surface-2` | `#161616` | Secondary elevation (sidebar, panel backgrounds) |

**Rule**: Never use pure `#000000`. The `0A0A0A` black has enough warmth to prevent the "hole in the screen" effect while remaining perceptually black.

### 2.2 Gold System

Gold is the brand color. It carries all accent, interactive, and emphasis duties.

| Token         | Value                      | Usage                                                       |
| ------------- | -------------------------- | ----------------------------------------------------------- |
| `--gold`      | `#C9A84C`                  | Primary brand gold — headlines, active states, primary CTAs |
| `--gold-dim`  | `rgba(201, 168, 76, 0.20)` | Borders at rest, subtle dividers                            |
| `--gold-mid`  | `rgba(201, 168, 76, 0.40)` | Borders on hover, scrollbar thumb                           |
| `--gold-glow` | `rgba(201, 168, 76, 0.05)` | Hover backgrounds, ghost button fills                       |

**Gold Gradient** (horizontal, for rules and decorative lines):

```css
--gold-gradient: linear-gradient(
  to right,
  #462523 0%,
  #cb9b51 22%,
  #f6e27a 45%,
  #f6f2c0 50%,
  #f6e27a 55%,
  #cb9b51 78%,
  #462523 100%
);
```

**Gold Text Gradient** (vertical, for hero and section title emphasis):

```css
--gold-text-gradient: linear-gradient(
  to bottom,
  #f5edd8 0%,
  #e0c97a 35%,
  #c4993c 70%,
  #a07830 100%
);
```

Apply via:

```css
.gold-text {
  background: var(--gold-text-gradient);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
}
```

**Outlined Numbers** — Large display numbers use text-stroke instead of fill:

```css
.stat-outlined {
  color: transparent;
  -webkit-text-stroke: 1.5px rgba(201, 168, 76, 0.6);
}
```

> **Migration note**: The UI package currently uses `#E8B84B` for gold. The canonical gold is **`#C9A84C`** — it reads more refined on dark backgrounds. Update `packages/ui/src/styles/tokens.ts` and `packages/ui/src/styles.css` to use `#C9A84C`. All rgba alpha variants should use `201, 168, 76` as the RGB base.

### 2.3 Text Colors

| Token          | Value                       | Usage                                             |
| -------------- | --------------------------- | ------------------------------------------------- |
| `--text`       | `#f5f5f7`                   | Primary text — headings, body copy, data values   |
| `--text-dim`   | `#b8b8bc`                   | Secondary text — descriptions, nav links, labels  |
| `--text-muted` | `rgba(184, 184, 188, 0.90)` | Tertiary text — metadata, timestamps, helper text |

> **Migration note**: UI package uses `#a1a1a6` for text-dim which is too dark. Adopt `#b8b8bc`.

### 2.4 Metal Accents

These colors establish the reputation tier progression and add tonal variety.

| Token          | Value     | Context                                        |
| -------------- | --------- | ---------------------------------------------- |
| `--bronze`     | `#7A5C28` | Tier II (Basic) accent                         |
| `--copper`     | `#8B5E3C` | Warm metal, secondary emphasis                 |
| `--silver`     | `#A0A0A8` | Tier III (Verified) accent, forensic/neutral   |
| `--amber`      | `#E8A020` | Tier V (Sovereign) accent, warning states      |
| `--green-dark` | `#3D6B4F` | Muted success/positive (landing page contexts) |

### 2.5 Tier Color System

The five reputation tiers each have a distinct metal color. This is the primary way color communicates hierarchy in Gotts.

| Tier | Name       | Color  | Hex       | Bottom Accent Shadow                   |
| ---- | ---------- | ------ | --------- | -------------------------------------- |
| I    | Unverified | Gray   | `#4A4A4A` | none                                   |
| II   | Basic      | Copper | `#8B5E3C` | `0 2px 10px rgba(139, 94, 60, 0.30)`   |
| III  | Verified   | Silver | `#A0A0A8` | `0 2px 10px rgba(160, 160, 168, 0.25)` |
| IV   | Trusted    | Gold   | `#C9A84C` | `0 2px 14px rgba(201, 168, 76, 0.35)`  |
| V    | Sovereign  | Amber  | `#E8A020` | `0 2px 14px rgba(232, 160, 32, 0.35)`  |

Tier cards get a 3px bottom border in their tier color, with a glow shadow on hover. Sovereign (Tier V) is the only tier that uses amber rather than gold, creating visual distinction between "brand gold" and "earned gold."

### 2.6 Semantic Colors

For app contexts (dashboards, forms, data displays):

| Token       | Value     | Usage                                                     |
| ----------- | --------- | --------------------------------------------------------- |
| `--success` | `#34d16a` | Positive balance changes, confirmed transactions, gains   |
| `--error`   | `#ef4444` | Failed transactions, negative balances, validation errors |
| `--warning` | `#f59e0b` | Pending states, impersonation mode, caution               |
| `--info`    | `#4a7fb5` | Informational badges, neutral highlights                  |

**Alpha variants for backgrounds and borders:**

| Token              | Value                      |
| ------------------ | -------------------------- |
| `--success-border` | `rgba(52, 209, 106, 0.30)` |
| `--success-bg`     | `rgba(52, 209, 106, 0.06)` |
| `--error-border`   | `rgba(239, 68, 68, 0.30)`  |
| `--error-bg`       | `rgba(239, 68, 68, 0.05)`  |
| `--warning-border` | `rgba(245, 158, 11, 0.30)` |
| `--warning-bg`     | `rgba(245, 158, 11, 0.05)` |
| `--info-border`    | `rgba(79, 143, 234, 0.30)` |
| `--info-bg`        | `rgba(79, 143, 234, 0.05)` |

> **Migration note**: The UI package uses `#3d6b4f` for success and `#c74b50` for error. These are too muted for app data displays. Adopt `#34d16a` / `#ef4444` / `#f59e0b` from the devenv which have been validated for readability against dark backgrounds. Reserve `#3d6b4f` (green-dark) for landing page/marketing contexts where a more subdued green is appropriate.

### 2.7 Token Colors (DeFi-specific)

For displaying token balances, pool compositions, and charts:

| Token | Hex       | Notes                    |
| ----- | --------- | ------------------------ |
| ETH   | `#627EEA` | Ethereum Foundation blue |
| WETH  | `#8B7EEA` | Lighter purple variant   |
| USDC  | `#2775CA` | Circle brand blue        |
| USDT  | `#26A17B` | Tether brand green       |
| DAI   | `#F5AC37` | MakerDAO gold            |
| WBTC  | `#F09242` | Bitcoin orange           |
| UNI   | `#FF007A` | Uniswap pink             |

Fallback for unknown tokens: `#888888`.

***

## 3. Typography

### 3.1 Font Stack

Three fonts, three roles, strict separation.

| Font                 | Family                                  | Weight(s)              | Role                                                                     |
| -------------------- | --------------------------------------- | ---------------------- | ------------------------------------------------------------------------ |
| **Instrument Serif** | `'Instrument Serif', serif`             | 400 (regular + italic) | Display headings, hero text, product names, section titles, stat numbers |
| **JetBrains Mono**   | `'JetBrains Mono', monospace`           | 300, 400               | Data labels, addresses, navigation, buttons, tags, code, metadata        |
| **General Sans**     | `'General Sans', system-ui, sans-serif` | 300, 400, 500          | Body copy, descriptions, prose paragraphs, form labels                   |

**Loading**:

```html
<link
  href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=JetBrains+Mono:wght@300;400&display=swap"
  rel="stylesheet"
/>
<link
  href="https://api.fontshare.com/v2/css?f[]=general-sans@300,400,500&display=swap"
  rel="stylesheet"
/>
```

> **Migration note**: The devenv currently uses Inter. Replace with General Sans across all app pages to unify with the landing page. Inter is a good UI font but it's generic — General Sans has more character and aligns with the brand's precision-meets-elegance position.

### 3.2 Type Scale

Base font size: `18px` on `html`.

| Name              | Size                       | Font  | Weight | Leading | Tracking          | Usage                                                |
| ----------------- | -------------------------- | ----- | ------ | ------- | ----------------- | ---------------------------------------------------- |
| **Display**       | `clamp(68px, 9vw, 148px)`  | Serif | 300    | 1.05    | `-0.02em`         | Hero titles ("No safer place.")                      |
| **Section Title** | `clamp(40px, 5.5vw, 82px)` | Serif | 300    | 1.15    | `-0.015em`        | Section headings ("Reputation is capital.")          |
| **Card Title**    | `clamp(28px, 2.8vw, 44px)` | Serif | 300    | 1.08    | normal            | Product/feature card headings                        |
| **Subsection**    | `22px`                     | Serif | 400    | 1.25    | normal            | In-card titles, FAQ questions                        |
| **Body Large**    | `clamp(15px, 1.4vw, 19px)` | Sans  | 400    | 1.65    | normal            | Hero sub, section intros                             |
| **Body**          | `15px`                     | Sans  | 400    | 1.78    | normal            | Paragraphs, descriptions                             |
| **Body Small**    | `14px`                     | Sans  | 400    | 1.65    | normal            | Card descriptions, secondary copy                    |
| **Label**         | `11px`                     | Mono  | 400    | 1.4     | `0.15em`          | Nav links, tags, eyebrows, buttons (uppercase)       |
| **Micro**         | `10px`                     | Mono  | 400    | 1.5     | `0.15em`-`0.20em` | Section tags, timestamps, metadata (uppercase)       |
| **Nano**          | `8px`                      | Mono  | 400    | 1.2     | `0.15em`-`0.20em` | PCB labels, badge text, tooltip metadata (uppercase) |

### 3.3 Tracking Constants

| Token                  | Value             | Usage                                                |
| ---------------------- | ----------------- | ---------------------------------------------------- |
| `--tracking-display`   | `-0.02em`         | Display titles                                       |
| `--tracking-heading`   | `-0.015em`        | Section titles                                       |
| `--tracking-uppercase` | `0.15em`          | All uppercase mono text (labels, buttons, tags)      |
| `--tracking-wide`      | `0.18em`-`0.30em` | Extra-wide spacing (product glyphs, standard labels) |

### 3.4 Leading Constants

| Token               | Value  | Usage                                        |
| ------------------- | ------ | -------------------------------------------- |
| `--leading-display` | `1.05` | Display headings                             |
| `--leading-heading` | `1.15` | Section headings                             |
| `--leading-card`    | `1.08` | Card title headings                          |
| `--leading-body`    | `1.65` | Body text (generous for readability on dark) |

### 3.5 Italic Convention

`<em>` in headings renders as Instrument Serif italic with the gold text gradient. This is the primary tool for emphasis in display type. The italic creates a calligraphic quality that reads as confident and timeless.

```css
.section-title em {
  font-style: italic;
  background: var(--gold-text-gradient);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}
```

Pattern: The first line of a display heading is set in roman. The second line is italic with gold gradient. Example: "No safer" (roman) / "*place.*" (italic gold).

### 3.6 The `<strong>` Convention

In dark-theme body text, `<strong>` means **"brighter, not bolder."** Weight stays at 400-500; the shift is from `--text-dim` to `--text`. This is the opposite of the web default — bold weight adds too much visual noise on dark backgrounds, but a luminance bump provides readable emphasis without breaking the typographic texture.

```css
strong {
  color: var(--text);
  font-weight: 400;
}
```

**Rule**: In body copy, never use `font-weight: 600` or `700`. If you need emphasis, promote the color from `--text-dim` to `--text` (or `--gold` for actionable emphasis). Reserve weight changes for headings and buttons only.

### 3.7 Manifesto Typography

Centered italic serif at a large responsive size, used for editorial callouts and philosophical positioning:

```css
.manifesto-quote {
  font-family: "Instrument Serif", serif;
  font-size: clamp(24px, 3.2vw, 50px);
  font-weight: 300;
  font-style: italic;
  line-height: 1.45;
  color: var(--text);
  max-width: 1060px;
  margin: 0 auto 64px;
}
```

`<strong>` words within the manifesto quote render in gold gradient at roman weight:

```css
.manifesto-quote strong {
  font-style: normal;
  font-weight: 400;
  background: var(--gold-text-gradient);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
}
```

### 3.8 The `g-gold` Inline Pattern

`<span class="g-gold">` renders the brand name in solid `var(--gold)` within body copy — just the flat gold color for inline brand references. Not for headings (use the gold text gradient) or interactive elements (use the full gold system).

### 3.9 Typography Rules

* Addresses and tx hashes are **always** monospace, **always** paired with a copy button.
* Numeric values (NAV, TVL, yield, share price) are **always** monospace.
* Never truncate numeric values mid-number. Truncate addresses at 6+4 chars with copy affordance.
* USD equivalents are sans-serif and secondary weight, placed below or beside the primary on-chain value.

***

## 4. Glass Morphism System

Glass is the primary surface treatment. Every card, panel, modal, and elevated container uses glass.

### 4.1 Glass Tokens

```css
:root {
  --glass-bg: rgba(14, 14, 14, 0.65);
  --glass-border: rgba(255, 255, 255, 0.08);
  --glass-blur: blur(12px) saturate(150%);
  --glass-shadow:
    0 8px 32px rgba(0, 0, 0, 0.12), inset 0 1px 0 rgba(255, 255, 255, 0.1),
    inset 0 -1px 0 rgba(0, 0, 0, 0.05);
}
```

### 4.2 Glass States

**Rest**:

```css
.glass {
  background: var(--glass-bg);
  backdrop-filter: var(--glass-blur);
  border: 1px solid var(--glass-border);
  box-shadow: var(--glass-shadow);
}
```

**Hover** — border goes gold, faint gold tint:

```css
.glass:hover {
  border-color: rgba(201, 168, 76, 0.45);
  background: rgba(201, 168, 76, 0.04);
  backdrop-filter: blur(14px) saturate(160%) brightness(1.02);
  box-shadow:
    0 0 48px rgba(201, 168, 76, 0.08),
    0 12px 40px rgba(0, 0, 0, 0.15),
    inset 0 1px 0 rgba(201, 168, 76, 0.16),
    inset 0 -1px 0 rgba(0, 0, 0, 0.08);
}
```

**Active/Selected** — stronger gold border and glow:

```css
.glass.active {
  border-color: rgba(201, 168, 76, 0.55);
  background: rgba(201, 168, 76, 0.04);
  box-shadow:
    0 0 28px rgba(201, 168, 76, 0.13),
    0 8px 32px rgba(0, 0, 0, 0.12),
    inset 0 1px 0 rgba(201, 168, 76, 0.18),
    inset 0 -1px 0 rgba(0, 0, 0, 0.05);
}
```

### 4.3 Gold Edge Line

A subtle horizontal gradient line at the top of glass cards that brightens on hover:

```css
.gold-edge::before {
  content: "";
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  height: 1px;
  background: linear-gradient(90deg, transparent, var(--gold), transparent);
  background-size: 200% 100%;
  opacity: 0.15;
  transition:
    opacity 450ms var(--ease-cinematic),
    background-position 800ms var(--ease-luxury);
}
.gold-edge:hover::before {
  opacity: 1;
  background-position: -100% 0;
}
```

### 4.4 App Context Adaptation

For data-dense app pages (devenv, portal), the glass system adapts:

* **Glass background**: Shift from `rgba(14, 14, 14, 0.65)` to `rgba(18, 22, 28, 0.70)` — slightly bluer to reduce eye strain during extended use
* **Base background**: Shift from `#0A0A0A` to `#0D1117` — GitHub-dark warmth for long coding sessions
* **Surface elevation**: `#161A20` (surface), `#1E2430` (surface-2) — cooler undertones for functional UI
* **Glass border**: `rgba(42, 48, 64, 0.75)` — slightly more visible for better panel delineation in dense layouts

The gold accent system remains **identical** in app contexts. Gold is gold everywhere.

***

## 5. PCB Card System

The PCB (printed circuit board) card is Gotts's signature component. It communicates "precision-engineered" through visual metaphor.

### 5.1 Geometry

```css
.pcb-card {
  --cut: 16px; /* corner chamfer size — 12px on mobile, 10px on small mobile */
  clip-path: polygon(
    var(--cut) 0%,
    calc(100% - var(--cut)) 0%,
    100% var(--cut),
    100% calc(100% - var(--cut)),
    calc(100% - var(--cut)) 100%,
    var(--cut) 100%,
    0% calc(100% - var(--cut)),
    0% var(--cut)
  );
}
```

This creates an octagonal silhouette — cut corners that evoke IC chip packaging.

### 5.2 SVG Border System

Instead of CSS borders (which can't follow clip-paths), PCB cards use an SVG overlay:

| Element                         | Rest Opacity               | Hover Opacity |
| ------------------------------- | -------------------------- | ------------- |
| Outer edge (`stroke`)           | `rgba(201, 168, 76, 0.25)` | `0.45`        |
| Inner edge (5px inset)          | `rgba(201, 168, 76, 0.10)` | `0.15`        |
| Corner dots (r: 1.8)            | `rgba(201, 168, 76, 0.30)` | `0.55`        |
| Trace lines (dashed 3 6)        | `rgba(201, 168, 76, 0.12)` | `0.18`        |
| Pin rings (r: 3.5, spaced 56px) | `rgba(201, 168, 76, 0.18)` | `0.30`        |
| Pin dots (r: 1, inside rings)   | `rgba(201, 168, 76, 0.15)` | `0.25`        |

### 5.3 3D Perspective

PCB cards have a subtle 3D tilt at rest that flattens on hover:

```css
.pcb-card {
  perspective: 900px;
}
.pcb-card-inner {
  transform: rotateX(1.2deg) rotateY(-0.6deg);
  transition: transform 600ms var(--ease-luxury);
}
.pcb-card:nth-child(even) .pcb-card-inner {
  transform: rotateX(0.8deg) rotateY(0.5deg);
}
.pcb-card:hover .pcb-card-inner {
  transform: translateY(-4px) rotateX(0) rotateY(0);
}
```

### 5.4 PCB Corner Labels

Tiny uppercase mono labels positioned at card corners (top-right, bottom-left):

```css
.pcb-label {
  position: absolute;
  font-family: var(--font-mono);
  font-size: 8px;
  letter-spacing: 1.5px;
  text-transform: uppercase;
  color: rgba(201, 168, 76, 0.18);
  z-index: 3;
  transition: color 600ms var(--ease-luxury);
}
.pcb-card:hover .pcb-label {
  color: rgba(201, 168, 76, 0.4);
}
.pcb-label.top-right {
  top: 10px;
  right: 28px;
}
.pcb-label.bottom-left {
  bottom: 10px;
  left: 28px;
}
```

These labels name the card's functional role (e.g., "GTS-P01", "AGENTS", "FEES", "MCP").

### 5.5 App Context Usage

In app contexts, PCB cards are used for **summary statistics** and **hero metrics** — not for every card. Regular data cards use standard glass styling. PCB treatment is reserved for:

* Protocol overview stats (32 agents, 15 layers, 154 tools, 0% fees)
* Key financial figures (TVL, volume, yield)
* Identity/reputation summary cards

### 5.6 Hardware Metaphor Vocabulary

The full PCB visual grammar. Apps typically need only the first three; the full set is landing-only.

| Element                                                      | App Context? |
| ------------------------------------------------------------ | ------------ |
| Octagonal silhouette (`clip-path`)                           | Yes          |
| Outer edge (primary SVG border)                              | Yes          |
| Corner labels (mono 8px, model numbers)                      | Yes          |
| Inner edge (secondary SVG border, 5px inset)                 | Optional     |
| Corner dots (SVG circles at each chamfer corner)             | Optional     |
| Diagonal gradient (subtle gold tint overlay)                 | Optional     |
| Trace lines (dashed SVG lines between elements)              | Landing only |
| Pin arrays (ring + dot, spaced 56px)                         | Landing only |
| Hexagonal connectors (SVG hexagons between layers)           | Landing only |
| Vertical spine (dashed gold line with traveling light pulse) | Landing only |

***

## 6. Depth Model & Border Hierarchy

### 6.1 Z-Layer Depth Model

Six formal depth levels, from page base to overlay:

| Level   | Name              | Background                                              | z-index | Examples                                      |
| ------- | ----------------- | ------------------------------------------------------- | ------- | --------------------------------------------- |
| **z-0** | Page base         | `#0A0A0A` (landing) / `#0D1117` (app)                   | 0       | Body background                               |
| **z-1** | Section elevation | `var(--surface)` + `border: 1px solid var(--gold-dim)`  | 1       | Manifesto, FAQ, full-bleed sections           |
| **z-2** | Cards             | Glass default (`rgba(14,14,14,0.65)`)                   | 1-2     | Glass cards, PCB cards, product cards         |
| **z-3** | Elevated cards    | Hover/active gold tint (`rgba(201,168,76,0.04)`)        | 2-3     | Hovered cards, active stat cards              |
| **z-4** | Navigation        | `rgba(10,10,10,0.55)` → `rgba(10,10,10,0.90)` on scroll | 200     | Fixed nav bar                                 |
| **z-5** | Overlays          | `rgba(0,0,0,0.92)`                                      | 10000   | Modals, film grain (9997), cursor (9998-9999) |

### 6.2 Border Hierarchy

Three tiers of borders, never interchanged:

**Tier 1 — Section dividers** (warm, brand):

```css
border-top: 1px solid var(--gold-dim); /* rgba(201,168,76,0.20) */
border-bottom: 1px solid var(--gold-dim);
```

**Tier 2 — Card borders** (neutral, structural):

```css
/* Rest */
border: 1px solid rgba(255, 255, 255, 0.08);
/* Hover → gold */
border-color: rgba(201, 168, 76, 0.45);
/* Active → stronger gold */
border-color: rgba(201, 168, 76, 0.55);
```

**Tier 3 — Internal dividers** (near-invisible, within cards):

```css
border-bottom: 1px solid rgba(255, 255, 255, 0.04);
```

**Rule**: Section dividers use `--gold-dim` (warm). Card borders use `rgba(255,255,255,0.08)` (neutral). Internal dividers use `rgba(255,255,255,0.04)` (near-invisible). Never mix tiers.

***

## 7. Layout & Spacing

### 7.1 Page Container

```css
.section {
  max-width: 1320px;
  margin: 0 auto;
  padding: 120px 56px;
}
```

| Breakpoint       | Max Width | Horizontal Padding |
| ---------------- | --------- | ------------------ |
| Desktop (>960px) | 1320px    | 56px               |
| Tablet (<=960px) | 100%      | 24px               |
| Mobile (<=600px) | 100%      | 20px               |
| Small (<=380px)  | 100%      | 16px               |

### 7.2 Spacing Scale

| Token            | Value  | Usage                                                                           |
| ---------------- | ------ | ------------------------------------------------------------------------------- |
| `--spacing-page` | `32px` | Page-level padding (main content area)                                          |
| `--spacing-card` | `24px` | Internal card padding                                                           |
| `--spacing-gap`  | `16px` | Gap between sibling elements in a section                                       |
| `--spacing-seam` | `2px`  | Gap between glass cards in grids (creates the "PCB trace" visual between cards) |

### 7.3 Grid Patterns

**2-column equal split** (products, why-now, standards):

```css
grid-template-columns: 1fr 1fr;
gap: 2px; /* seam gap */
```

**3-column** (developer resources, brain cycles):

```css
grid-template-columns: repeat(3, 1fr);
gap: 2px;
```

**4-column** (stat strips):

```css
grid-template-columns: repeat(4, 1fr);
gap: 0;
```

**The 2px seam** is a signature pattern. Where most design systems use 16-24px gaps between cards, Gotts uses 2-3px — creating the illusion that cards are components on a single PCB with trace lines running between them.

### 7.4 Border Radius

| Token           | Value    | Usage                                   |
| --------------- | -------- | --------------------------------------- |
| `--radius-sm`   | `2px`    | Standard radius — cards, inputs, badges |
| `--radius-md`   | `4px`    | Slightly larger — rare                  |
| `--radius-full` | `9999px` | Pills, avatar containers                |

Sharp edges are the brand. No `border-radius` values above `4px` except `9999px` pills.

### 7.5 Section Tags

Every section opens with a tag line:

```css
.section-tag {
  display: flex;
  align-items: center;
  gap: 14px;
  font-family: var(--font-mono);
  font-size: 10px;
  letter-spacing: 0.15em;
  text-transform: uppercase;
  color: var(--gold);
}
.section-tag::before {
  content: "";
  width: 20px;
  height: 1px;
  background: var(--gold);
}
```

This creates the "--- THE LEDGER" pattern seen throughout the landing page. In app contexts, section headers use this same pattern.

### 7.6 Navigation

```css
nav {
  height: var(--nav-h); /* 68px desktop, 60px tablet */
  background: rgba(10, 10, 10, 0.55);
  backdrop-filter: saturate(180%) blur(20px);
  border-bottom: 1px solid rgba(201, 168, 76, 0.07);
}
nav.scrolled {
  background: rgba(10, 10, 10, 0.9);
}
```

Nav links: JetBrains Mono, 11px, uppercase, `--tracking-uppercase`, with gold underline animation on hover.

***

## 8. The Landing-to-App Spectrum

### 8.1 The Spectrum

The Gotts visual language operates on a spectrum from **ceremonial** (landing page) to **functional** (devenv/portal):

| Quality           | Landing Page             | App Pages                               |
| ----------------- | ------------------------ | --------------------------------------- |
| Base background   | `#0A0A0A`                | `#0D1117`                               |
| Surface color     | `#111111`                | `#161A20`                               |
| Surface-2         | `#161616`                | `#1E2430`                               |
| Glass border      | `rgba(255,255,255,0.08)` | `rgba(42, 48, 64, 0.75)`                |
| Body font         | General Sans             | General Sans                            |
| Gold system       | Identical                | Identical                               |
| PCB cards         | Everywhere               | Hero stats only                         |
| Film grain        | Yes                      | No                                      |
| Custom cursor     | Yes                      | No                                      |
| Reveal animations | Yes (staggered)          | Fade-in only (250ms)                    |
| Section padding   | 120px                    | 32px                                    |
| Card padding      | 48-56px                  | 24px                                    |
| Font base weight  | 400                      | 500 (slightly bolder for small UI text) |

### 8.2 App Page Layout

```
+--[Sidebar 240px]--+--[Main Content]-------------------------------------------+
|                    | +--[AccountBar 68px]------------------------------------+ |
| [Logo]             | | Connected: 0xDe...Ad | Bal: 10,000 ETH | [Disconnect]| |
|                    | +------------------------------------------------------+ |
| [Nav Group]        |                                                          |
|   Chain Controls   | +--[Page Header]---------------------------------------+ |
|   Balances         | |  --- CHAIN CONTROLS                                  | |
|   Swap             | |  Anvil Development Chain                             | |
|   Liquidity        | +------------------------------------------------------+ |
|   Pool Explorer    |                                                          |
|   Transactions     | +--[Glass Card]----+ +--[Glass Card]----+               |
|   Events           | | Block: 142       | | Gas: 0 gwei      |               |
|                    | | Mining: Auto     | | Base Fee: 1 gwei |               |
|                    | +------------------+ +------------------+               |
+--------------------+----------------------------------------------------------+
```

* **Sidebar**: `w-60` (240px) or `w-14` (56px) collapsed. Active nav link: `border-l-2 border-l-gold bg-surface-2 text-gold`.
* **Main content**: Scrollable area with `animate-page-in` on route change.
* **Page header**: Uses the section-tag pattern from the landing page.

### 8.3 Data Display Conventions

1. **All numeric values in monospace** — balances, addresses, hashes, block numbers, timestamps
2. **All labels in mono uppercase** — column headers, field names, section tags
3. **Prose text in General Sans** — descriptions, explanations, help text
4. **Serif for page titles only** — the main heading on each page. Not for card titles in app context (serif at small sizes loses legibility)
5. **Gold for interactive elements** — clickable text, active tabs, selected filters, primary actions
6. **Status colors for data** — green for gains/confirmed, red for losses/errors, amber for pending/warning

### 8.4 Decision Matrix

Which pattern sets apply for each page type:

| Pattern Set                     | Marketing / Landing | Dashboard / Portal   | Devenv / Debug        | Docs    |
| ------------------------------- | ------------------- | -------------------- | --------------------- | ------- |
| Gold system (colors, gradients) | Full                | Full                 | Full                  | Full    |
| Typography (3 fonts, scale)     | Full                | Full                 | Full                  | Full    |
| Easing curves                   | Full                | Full                 | Full                  | Full    |
| Glass card system               | Full                | Full                 | Full                  | Full    |
| Button system                   | Full                | Full                 | Full                  | Partial |
| PCB cards (octagonal, SVG)      | Full                | Hero stats only      | Hero stats only       | No      |
| Section composition templates   | Full                | Adapted              | Adapted               | No      |
| Film grain / texture            | Yes                 | No                   | No                    | No      |
| Custom cursor                   | Yes                 | No                   | No                    | No      |
| Ambient keyframes               | Full                | Minimal (live pulse) | Minimal (block pulse) | No      |
| Scroll reveal                   | Full stagger        | Page fade-in (250ms) | Page fade-in (250ms)  | No      |
| Three.js background             | Yes                 | No                   | No                    | No      |
| Ticker / marquee                | Yes                 | No                   | No                    | No      |
| Hex connectors / spine          | Yes                 | No                   | No                    | No      |

### 8.5 Contract Interaction Styling

Read functions get a green-tinted left border:

```css
.read-section {
  background: rgba(52, 209, 106, 0.02);
  border-left: 2px solid rgba(52, 209, 106, 0.15);
}
```

Write functions get an amber-tinted left border:

```css
.write-section {
  background: rgba(245, 158, 11, 0.02);
  border-left: 2px solid rgba(245, 158, 11, 0.15);
}
```

### 8.6 Transaction Action Colors

| Action    | Color        | Class             |
| --------- | ------------ | ----------------- |
| Swap      | `blue-400`   | `text-blue-400`   |
| Liquidity | `green-400`  | `text-green-400`  |
| Approval  | `amber-400`  | `text-amber-400`  |
| Transfer  | `purple-400` | `text-purple-400` |

***

## 9. Animation & Motion

### 9.1 Easing Curves

Three curves for three speeds:

| Token              | Value                              | Duration | Usage                                                   |
| ------------------ | ---------------------------------- | -------- | ------------------------------------------------------- |
| `--ease-luxury`    | `cubic-bezier(0.22, 1, 0.36, 1)`   | 600ms    | Large reveals, hero animations, glass state transitions |
| `--ease-cinematic` | `cubic-bezier(0.16, 1, 0.3, 1)`    | 450ms    | Standard transitions, FAQ accordions, menu opens        |
| `--ease-hover`     | `cubic-bezier(0.25, 0.1, 0.25, 1)` | 300ms    | Micro-interactions: buttons, links, borders             |

**Transition tier shortcuts**:

```css
--t-premium: 600ms var(--ease-luxury);
--t-standard: 450ms var(--ease-cinematic);
--t-micro: 300ms var(--ease-cinematic);
```

### 9.2 Scroll Reveal

Elements enter the viewport with a staggered fade-up:

```css
.reveal {
  opacity: 0;
  transform: translateY(24px);
  transition:
    opacity 0.9s var(--ease-luxury),
    transform 0.9s var(--ease-luxury);
}
.reveal.visible {
  opacity: 1;
  transform: translateY(0);
}
```

**Stagger delays** (for sibling elements): `.d1` (100ms) through `.d8` (940ms), incrementing by 120ms.

**Variants**: `.reveal-left` (translateX), `.reveal-scale` (scale).

**IntersectionObserver config**: `{ threshold: 0.07, rootMargin: '0px 0px -32px 0px' }`

### 9.3 App-Specific Animations

```css
/* Page transition */
@keyframes devenv-fade-in {
  from {
    opacity: 0;
    transform: translateY(6px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* Balance change flash */
@keyframes balance-flash-up {
  0% {
    color: var(--success);
    text-shadow: 0 0 8px rgba(52, 209, 106, 0.4);
  }
  100% {
    color: inherit;
    text-shadow: none;
  }
}

@keyframes balance-flash-down {
  0% {
    color: var(--error);
    text-shadow: 0 0 8px rgba(239, 68, 68, 0.4);
  }
  100% {
    color: inherit;
    text-shadow: none;
  }
}

/* Block mining pulse */
@keyframes block-pulse {
  0% {
    transform: scale(1.15);
    color: var(--gold);
  }
  100% {
    transform: scale(1);
    color: inherit;
  }
}

/* Stale data indicator */
@keyframes stale-pulse {
  0%,
  100% {
    opacity: 1;
  }
  50% {
    opacity: 0.4;
  }
}
```

### 9.4 Ambient Animations (Landing Only)

Subtle background life, **excluded from app contexts**:

* **Stat number pulse**: Opacity oscillates 0.75 → 0.88 over 6s
* **Flywheel rings**: Concentric circles rotating CW/CCW at 12-48s periods
* **Stack spine pulse**: Gold light travels down the execution stack over 4s
* **Hex connector pulse**: Fill opacity oscillates with staggered delays
* **Film grain**: SVG feTurbulence at 10% opacity, `mix-blend-mode: soft-light`
* **Three.js particles**: Gold-tinted points with slow orbital motion

The only ambient animation in apps is the "live" pulse indicator on streaming data.

### 9.5 Reduced Motion

```css
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
  .reveal,
  .reveal-left,
  .reveal-scale,
  .gold-rule {
    opacity: 1;
    transform: none;
  }
  .ticker-track {
    animation: none;
  }
  #bg {
    display: none;
  }
}
```

All animations and transitions are disabled; reveal elements shown immediately; Three.js background hidden; ambient animations stopped.

### 9.6 Motion Rules

* No purely decorative animations.
* All animations respect `prefers-reduced-motion`.
* No looping animations except skeleton shimmer, delay countdown, and `livePulse` (streaming indicator).
* Animation library: **CSS + minimal requestAnimationFrame for number interpolation** (no Framer Motion in v1).
* Prefer streaming over polling. Use SSE subscriptions for frequently-updating data.

***

## 10. Micro-interaction Catalog

### 10.1 Interactive State Machine

Every interactive element follows this state progression:

| Transition         | Property Changes                                                              | Duration / Easing                     |
| ------------------ | ----------------------------------------------------------------------------- | ------------------------------------- |
| **Rest → Hover**   | `translateY(-2px)` to `-4px`, border → gold (`0.45`), bg → gold tint (`0.04`) | `var(--t-standard)` (450ms cinematic) |
| **Hover → Active** | `translateY(1px) scale(0.985)`                                                | 80ms                                  |
| **Rest → Focus**   | `outline: 2px solid rgba(201,168,76,0.60); outline-offset: 3px`               | Instant                               |
| **Rest → Expand**  | `flex: 1` → `flex: 1.8` (tier cards)                                          | `var(--t-premium)` (600ms luxury)     |

### 10.2 Specific Interactions

| Interaction           | Element               | Effect                                                        |
| --------------------- | --------------------- | ------------------------------------------------------------- |
| Nav link underline    | `.nav-links a::after` | `scaleX(0)` → hover: `scaleX(1)`                              |
| Link button gap       | `.btn-link`           | `gap: 8px` → hover: `gap: 14px; color: #e0c97a`               |
| Accordion icon rotate | `.faq-q-icon`         | open: `rotate(45deg); background: rgba(201,168,76,0.1)`       |
| Stat number pulse     | `.m-stat-num`         | `animation: statPulse 6s ease-in-out infinite; opacity: 0.75` |
| Gold rule reveal      | `.gold-rule`          | `scaleX(0)` → `.visible`: `scaleX(1)` at 1.2s luxury          |
| Nav scroll opacity    | `nav`                 | `rgba(10,10,10,0.55)` → `.scrolled`: `rgba(10,10,10,0.90)`    |
| Logo mark hover       | `.nav-logo-mark`      | `scale(1.06); drop-shadow(0 0 8px rgba(201,168,76,0.35))`     |
| Ticker pause          | `.ticker-track`       | `:hover { animation-play-state: paused; }`                    |

***

## 11. Component Library

### 11.1 Buttons

#### Gold Button (Primary CTA)

```css
.btn-gold {
  font-family: var(--font-mono);
  font-size: 10.5px;
  letter-spacing: var(--tracking-uppercase);
  text-transform: uppercase;
  padding: 15px 38px;
  background: var(--gold);
  color: var(--black);
  border: none;
  min-height: 48px;
  transition:
    opacity var(--t-micro),
    transform var(--t-micro),
    box-shadow var(--t-micro);
}
.btn-gold:hover {
  opacity: 0.92;
  transform: translateY(-2px) scale(1.01);
  box-shadow:
    0 4px 16px rgba(201, 168, 76, 0.2),
    0 1px 3px rgba(201, 168, 76, 0.1);
}
```

#### Outline Button (Secondary CTA)

```css
.btn-outline {
  font-family: var(--font-mono);
  font-size: 10.5px;
  letter-spacing: var(--tracking-uppercase);
  text-transform: uppercase;
  padding: 15px 38px;
  background: rgba(201, 168, 76, 0.06);
  border: 1px solid var(--gold-mid);
  color: var(--gold);
  backdrop-filter: blur(8px);
  min-height: 48px;
}
.btn-outline:hover {
  background: rgba(201, 168, 76, 0.12);
  border-color: rgba(201, 168, 76, 0.55);
  transform: translateY(-2px) scale(1.01);
}
```

#### Ghost Button (Tertiary)

```css
.btn-ghost {
  background: transparent;
  border: none;
  color: var(--text-dim);
}
.btn-ghost:hover {
  background: var(--gold-glow);
  color: var(--gold);
}
```

#### Link Button (Text-only with arrow)

```css
.btn-link {
  font-family: var(--font-mono);
  font-size: 11px;
  letter-spacing: 0.18em;
  text-transform: uppercase;
  color: var(--gold);
  display: inline-flex;
  align-items: center;
  gap: 8px;
}
.btn-link:hover {
  gap: 14px;
  color: #e0c97a;
}
```

#### App Button Sizes

| Size | Height | Padding     | Font Size |
| ---- | ------ | ----------- | --------- |
| `sm` | 36px   | `8px 20px`  | `9px`     |
| `md` | 44px   | `12px 32px` | `10.5px`  |
| `lg` | 48px   | `15px 38px` | `11px`    |

#### Semantic Button Variants (App Context)

| Variant   | Border Color              | Text Color       | Hover BG                   |
| --------- | ------------------------- | ---------------- | -------------------------- |
| `danger`  | `rgba(239, 68, 68, 0.4)`  | `var(--error)`   | `rgba(239, 68, 68, 0.1)`   |
| `warning` | `rgba(245, 158, 11, 0.4)` | `var(--warning)` | `rgba(245, 158, 11, 0.15)` |
| `success` | `rgba(52, 209, 106, 0.3)` | `var(--success)` | `rgba(52, 209, 106, 0.08)` |

#### Pill Buttons (Compact, for inline actions)

```css
.btn-max-pill {
  font-family: var(--font-mono);
  font-size: 10px;
  padding: 2px 8px;
  border-radius: 9999px;
  background: rgba(201, 168, 76, 0.1);
  border: 1px solid rgba(201, 168, 76, 0.2);
  color: var(--gold);
}
```

### 11.2 Inputs

```css
input {
  background: rgba(14, 14, 14, 0.8);
  border: 1px solid var(--gold-dim);
  padding: 14px 16px;
  border-radius: 2px;
  font-family: var(--font-mono);
  font-size: 12px;
  letter-spacing: 0.04em;
  color: var(--text);
  transition: border-color var(--t-micro);
}
input:focus {
  border-color: var(--gold);
  outline: none;
}
input.error {
  border-color: var(--error-border);
}
input::placeholder {
  color: var(--text-muted);
}
```

Number inputs hide spinners globally. Amount inputs pair with percentage pill buttons (25%, 50%, 75%, Max).

### 11.3 Badges

```css
.badge {
  font-family: var(--font-mono);
  font-size: 7.5px;
  letter-spacing: 0.1em;
  text-transform: uppercase;
  padding: 2.5px 7px;
}
```

Tier badge variants: Each tier gets `background: rgba(tierColor, 0.20)` and `color: tierColor`.

### 11.4 Cards

| Type                       | Padding                      | Notes                                                                               |
| -------------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| **Standard (Glass)**       | `var(--spacing-card)` (24px) | Glass system from §4. Sharp corners (`--radius-sm: 2px` max).                       |
| **Stat Card (Landing)**    | `44px 36px`                  | Large serif number + mono label. Number can be outlined or solid gold.              |
| **Product Card**           | `56px 48px`                  | Product glyph + serif title + sans description + mono feature list.                 |
| **Tier Card (Expandable)** | Varies                       | Flex-based, expand on hover (`flex: 1` → `flex: 1.8`). Bottom border in tier color. |

### 11.5 Tables (App Context)

```css
th {
  background: var(--black);
  border-bottom: 1px solid var(--gold-dim);
  font-family: var(--font-mono);
  font-size: 11px;
  letter-spacing: 0.08em;
  text-transform: uppercase;
  color: var(--text-muted);
  font-weight: 600;
  padding: 10px 12px;
}
tr {
  border-bottom: 1px solid var(--glass-border);
}
tr:hover {
  background: rgba(201, 168, 76, 0.04);
}
tr.expanded {
  background: rgba(201, 168, 76, 0.03);
}
```

### 11.6 Tabs

```css
.tab {
  font-family: var(--font-mono);
  font-size: 11px;
  letter-spacing: 0.14em;
  text-transform: uppercase;
  color: var(--text-muted);
  padding: 14px 28px;
  border-bottom: 1px solid var(--gold-dim);
}
.tab:hover {
  color: var(--text);
}
.tab.active {
  color: var(--gold);
  background: rgba(201, 168, 76, 0.06);
  border-bottom-color: var(--gold);
}
```

### 11.7 Accordions / FAQ

```css
.accordion-trigger {
  font-family: var(--font-serif);
  font-size: 19px;
  color: var(--text);
  padding: 22px 0;
  border-top: 1px solid var(--gold-dim);
}
.accordion-trigger:hover {
  color: var(--gold);
}
.accordion-icon {
  width: 22px;
  height: 22px;
  border: 1px solid var(--gold-dim);
  border-radius: 50%;
  color: var(--gold);
}
.accordion-icon.open {
  transform: rotate(45deg);
  background: rgba(201, 168, 76, 0.1);
}
```

Content uses `max-height` animation at 450ms cinematic easing.

### 11.8 Tooltips

```css
.tooltip {
  background: rgba(13, 17, 23, 0.95);
  border: 1px solid rgba(201, 168, 76, 0.2);
  backdrop-filter: blur(12px);
  padding: 8px 12px;
  font-family: var(--font-mono);
  font-size: 11px;
  color: var(--text-dim);
}
```

### 11.9 Data Display Triad

The single most repeated pattern: **serif number + mono label**. Used for hero stats, manifesto stats, counter strips, why-now metrics, security layer counts, and MCP tool counts.

**Canonical form** (outlined number):

```css
.stat-num {
  font-family: "Instrument Serif", serif;
  font-size: clamp(52px, 5.5vw, 80px);
  font-weight: 300;
  color: transparent;
  line-height: 1;
  -webkit-text-stroke: 1.5px rgba(201, 168, 76, 0.6);
}
.stat-label {
  font-family: "JetBrains Mono", monospace;
  font-size: 11px;
  letter-spacing: var(--tracking-uppercase);
  text-transform: uppercase;
  color: var(--text-muted);
}
```

**Variant: Solid gold** (manifesto stats, counter strips):

```css
.stat-num-solid {
  font-family: "Instrument Serif", serif;
  font-size: clamp(44px, 5vw, 68px);
  font-weight: 300;
  color: var(--gold);
  line-height: 1;
  opacity: 0.75;
}
```

### 11.10 Feature List Pattern

Mono list items with 3px gold dot bullets and near-invisible dividers:

```css
.product-features li {
  font-family: "JetBrains Mono", monospace;
  font-size: 11px;
  letter-spacing: 0.04em;
  color: var(--text-muted);
  line-height: 1.5;
  padding: 10px 0;
  border-bottom: 1px solid rgba(255, 255, 255, 0.04);
  display: flex;
  align-items: baseline;
  gap: 10px;
}
.product-features li::before {
  content: "";
  width: 3px;
  height: 3px;
  background: var(--gold);
  border-radius: 50%;
  flex-shrink: 0;
}
```

### 11.11 Loading States

**Skeleton screens**: Use `--gold-dim` shimmer animation:

```css
@keyframes shimmer {
  0% {
    background-position: -200% 0;
  }
  100% {
    background-position: 200% 0;
  }
}
.skeleton {
  background: linear-gradient(
    90deg,
    rgba(201, 168, 76, 0.04) 25%,
    rgba(201, 168, 76, 0.08) 50%,
    rgba(201, 168, 76, 0.04) 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s ease-in-out infinite;
}
```

**Spinner**: Single rotating ring in gold:

```css
.spinner {
  width: 20px;
  height: 20px;
  border: 1.5px solid var(--gold-dim);
  border-top-color: var(--gold);
  border-radius: 50%;
  animation: spinCW 0.8s linear infinite;
}
```

### 11.12 Empty States

Dashed `--gold-dim` border pattern with centered icon and mono label:

```css
.empty-state {
  border: 1px dashed var(--gold-dim);
  padding: 48px 24px;
  text-align: center;
}
.empty-state-label {
  font-family: "JetBrains Mono", monospace;
  font-size: 11px;
  letter-spacing: var(--tracking-uppercase);
  text-transform: uppercase;
  color: var(--text-muted);
}
```

### 11.13 Error States

**Inline validation** (inputs): `border-color: var(--error-border)` with `font-family: var(--font-mono); font-size: 11px; color: var(--error)` message.

**Error boundary cards**: `background: var(--error-bg); border: 1px solid var(--error-border); border-left: 3px solid var(--error)`.

**Toast errors**: Standard toast with error semantic colors — `border-color: var(--error-border)`, left accent border in `var(--error)`.

### 11.14 Modals

Overlay: `background: rgba(0, 0, 0, 0.92)`. Content uses glass styling. Close button is outline style with mono uppercase text. Closes on Escape key, close button click, or backdrop click. Body overflow set to `hidden` when open.

### 11.15 Toggle Switch

```css
.toggle {
  width: 32px;
  height: 18px;
  border-radius: 9999px;
  border: 1px solid var(--glass-border);
  background: transparent;
}
.toggle.active {
  background: rgba(201, 168, 76, 0.25);
  border-color: rgba(201, 168, 76, 0.4);
}
.toggle-knob {
  /* 12px gold circle, translateX on toggle */
}
```

### 11.16 Status Indicators

* **Live dot**: 6px circle, `var(--success)` with pulse animation
* **Connected**: Small green StatusIndicator + mono "Connected" label
* **Stale data**: `animate-stale-pulse` on timestamps older than 60s
* **Impersonation banner**: Amber background (`rgba(245, 158, 11, 0.1)`), amber border, amber text

***

## 12. Pattern Library

Recurring compositions used on the landing page. Patterns marked "Landing only" should not be ported to app contexts.

### 12.1 Ticker / Marquee Strip (Landing only)

Infinite-scroll horizontal ticker with gold dot separators. Content duplicated for seamless loop. Pauses on hover. `animation: tickerScroll 120s linear infinite`.

### 12.2 Scroll Indicator (Landing only)

Hero scroll hint with breathing gold line: `animation: lineBreath 2.4s`.

### 12.3 Hexagonal Connector System (Landing only)

SVG hexagons between stacked layers with fill pulse and `:has()` hover interaction.

### 12.4 Vertical Spine + Flow Pulse (Landing only)

Dashed gold spine with a traveling light pulse: `animation: stackPulseDown 4s`.

### 12.5 Focal Emphasis (Landing only)

`stack-pcb--focal` layer with gold glow animation and heightened padding.

### 12.6 Counter Strip

4-column grid with gold-dim dividers, pulsing serif numbers, and mono labels:

```css
.manifesto-counter-strip {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  gap: 0;
  border-top: 1px solid var(--gold-dim);
}
.mcs-item {
  padding: 40px 28px;
  text-align: center;
  border-right: 1px solid var(--gold-dim);
}
```

Counter numbers animate from 0 using JS (1900ms cubic ease-out) triggered by IntersectionObserver at threshold 0.3.

### 12.7 Ring Label

Categorized section headers with color variants:

```css
.ring-label {
  display: flex;
  align-items: baseline;
  gap: 16px;
  padding: 16px 0 12px;
  border-bottom: 1px solid var(--gold-dim);
}
.ring-label-num {
  font-family: "JetBrains Mono", monospace;
  font-size: 10px;
  letter-spacing: 0.2em;
  text-transform: uppercase;
  color: var(--gold);
}
.ring-label-name {
  font-family: "Instrument Serif", serif;
  font-size: 18px;
  color: var(--text);
}
```

### 12.8 Big Outlined Numbers (Landing only)

Massive outlined serif numbers for section accents: `clamp(110px, 16vw, 210px)`, `font-weight: 300`, `-webkit-text-stroke: 1.5px rgba(201, 168, 76, 0.50)`.

### 12.9 Brain Cycle Cards

3-column grid with numbered mono labels, serif titles, and arrow-bulleted step lists. Standard glass card with 2px seam gap.

### 12.10 Flywheel Visual (Landing only)

4 concentric rotating rings with gold dots and centered "G". Rings rotate CW/CCW at 12-48s periods.

### 12.11 Section Composition Templates

Four standard section compositions:

| Template        | Layout                                                | Used For                           |
| --------------- | ----------------------------------------------------- | ---------------------------------- |
| **Standard**    | Tag + title + body + content grid                     | Products, Security, MCP, Developer |
| **Split Intro** | 2-column: tag+title left, body right (bottom-aligned) | Products, Developer Resources      |
| **Centered**    | Everything centered, narrow max-width body            | Manifesto, Why Now, Uniswap, CTA   |
| **Full Bleed**  | 100% width, circuit-bg texture optional               | Manifesto, Why Now, FAQ            |

Standard section: `max-width: 1320px; margin: 0 auto; padding: 120px 56px;`

### 12.12 Code Snippets

```css
.code-block {
  font-family: var(--font-mono);
  font-size: 11px;
  line-height: 1.7;
  background: rgba(0, 0, 0, 0.55);
  border: 1px solid rgba(201, 168, 76, 0.12);
  padding: 18px 20px;
  white-space: pre;
  overflow-x: auto;
}
```

### 12.13 Footer

Gold gradient `::before` line, serif logo with mark, mono copyright, animated links with gold underline on hover.

***

## 13. Data Visualization

### Chart Styling

Charts use recharts with custom styling that matches the glass system:

```js
const CHART_TOOLTIP_STYLE = {
  background: "rgba(22, 26, 32, 0.95)",
  border: "1px solid rgba(201, 168, 76, 0.2)",
  backdropFilter: "blur(12px)",
  borderRadius: "2px",
  padding: "8px 12px",
  fontFamily: "'JetBrains Mono', monospace",
  fontSize: "11px",
};

const CHART_AXIS_TICK = {
  fontFamily: "'JetBrains Mono', monospace",
  fontSize: 10,
  fill: "var(--text-muted)",
};

const CHART_GRID_STROKE = "rgba(201, 168, 76, 0.06)";
```

### SVG Data Visualization

For custom visualizations (liquidity histograms, composition bars):

* **Current/active data**: Gold at 0.7 opacity
* **In-range data**: Blue at 0.5 opacity (using `var(--info)`)
* **Out-of-range**: Blue at 0.3 opacity
* **Grid lines**: Gold, dashed, 0.06 opacity
* **Hover tooltip**: Same glass styling as chart tooltips

### Composition Bar

Horizontal stacked bar showing token ratios. 8px height, rounded, uses token colors. Gold indicator for zero-reserve edge case.

***

## 14. Scrollbar, Focus & Selection

### Scrollbar

```css
::-webkit-scrollbar {
  width: 3px;
}
::-webkit-scrollbar-track {
  background: transparent;
}
::-webkit-scrollbar-thumb {
  background: rgba(201, 168, 76, 0.4);
  border-radius: 3px;
}
::-webkit-scrollbar-thumb:hover {
  background: rgba(201, 168, 76, 0.5);
}
```

Width is 3px on landing, 2px in apps.

### Focus

```css
:focus-visible {
  outline: 2px solid rgba(201, 168, 76, 0.6);
  outline-offset: 3px;
}
```

Enhanced focus for buttons:

```css
.btn-gold:focus-visible,
.btn-outline:focus-visible {
  outline-offset: 4px;
  box-shadow: 0 0 0 6px rgba(201, 168, 76, 0.08);
}
```

### Selection

```css
::selection {
  background: rgba(201, 168, 76, 0.25);
  color: var(--text);
}
```

***

## 15. Film Grain & Texture

### Landing page only:

**Film grain** (fixed overlay):

```css
body::after {
  content: "";
  position: fixed;
  inset: 0;
  background: url("data:image/svg+xml,...feTurbulence...");
  background-size: 182px;
  opacity: 0.1;
  mix-blend-mode: soft-light;
  pointer-events: none;
  z-index: 9997;
}
```

**Circuit board texture** (on specific sections):

```css
.circuit-bg::before {
  background: url("texture.png") repeat;
  background-size: 600px;
  opacity: 0.1;
  mix-blend-mode: luminosity;
  filter: contrast(1.8);
}
```

These textures are **excluded from app contexts** — they add visual noise that interferes with data readability.

***

## 16. Custom Cursor

### Landing page only:

```css
@media (hover: hover) and (pointer: fine) {
  /* Gold dot (5px → 8px on hover) */
  .c-dot {
    position: fixed;
    width: 5px;
    height: 5px;
    background: var(--gold);
    border-radius: 50%;
    pointer-events: none;
    z-index: 9999;
  }
  .c-dot.hover {
    width: 8px;
    height: 8px;
  }

  /* Gold ring (28px → 52px on hover) */
  .c-ring {
    position: fixed;
    width: 28px;
    height: 28px;
    border: 1px solid rgba(201, 168, 76, 0.4);
    border-radius: 50%;
    pointer-events: none;
    z-index: 9998;
  }
  .c-ring.hover {
    width: 52px;
    height: 52px;
  }
}
```

Ring follows dot with damping: `rx += (dx - rx) * 0.11` per requestAnimationFrame. Hidden on touch devices. **Excluded from app contexts** — custom cursors are impractical for dense UIs.

***

## 17. Code Styling

| Token           | Color                       | Usage    |
| --------------- | --------------------------- | -------- |
| `.code-comment` | `rgba(161, 161, 166, 0.55)` | Comments |
| `.code-kw`      | `var(--gold)`               | Keywords |
| `.code-str`     | `#e0c97a`                   | Strings  |
| `.code-num`     | `var(--amber)`              | Numbers  |

***

## 18. Iconography

* **Icon library**: Lucide React (outline style, 1.5px stroke weight)
* **No emojis** — anywhere, ever. Use Unicode symbols from `packages/tui/src/icons.ts` for TUI output.
* **Token icons**: Colored circles (8px diameter) with the token color from §2.7, or small SVG logos when available
* **Arrows**: Use `→` (Unicode arrow) in monospace text, Lucide `ArrowRight` in buttons
* **Status**: Green circle for active, gray for inactive, amber for pending
* Default sizes: 16px (inline), 20px (standalone), 24px (feature)
* Icons are **always** accompanied by a label or tooltip — never used as the sole meaning carrier

***

## 19. Responsive Strategy

Gotts targets desktop-first. The primary personas (agent operators, developers, depositors) work at desktops. Mobile is supported but not the primary breakpoint.

### 19.1 Breakpoints

| Name        | Max Width | Key Changes                                              |
| ----------- | --------- | -------------------------------------------------------- |
| **Desktop** | >960px    | Full layouts, 2-3 column grids, sidebar visible          |
| **Tablet**  | <=960px   | Stack to 1 column, hamburger nav, reduce padding to 24px |
| **Mobile**  | <=600px   | Full stack, 20px padding, buttons go full-width          |
| **Small**   | <=380px   | 16px padding, single-column stat strips                  |

### 19.2 Responsive Rules

1. PCB card `--cut` reduces: 16px → 12px → 10px as viewport shrinks
2. On tablet, hero stat cards collapse PCB borders and use CSS borders instead
3. Tier cards stack vertically on tablet (no expand-on-hover, unlock text always visible)
4. Flywheel rings reduce from 340px → 200px → 160px
5. Hero actions stack vertically on mobile, go full-width
6. Nav height: `68px` desktop, `60px` tablet (`--nav-h`)

### 19.3 Per-Product Responsive Targets

| Product      | Mobile               | Tablet         | Desktop                |
| ------------ | -------------------- | -------------- | ---------------------- |
| Landing page | Full support         | Full support   | Full support (primary) |
| App          | Read-only (explorer) | Reduced layout | Full support (primary) |
| Portal       | Wizard only          | Full support   | Full support           |

**App responsive rules**: Tables collapse to card-list view on `< md`. Side nav collapses to bottom tab bar on `< md`. Chart components hide on `xs`. Write actions require `>= sm`.

***

## 20. Accessibility

Target: **WCAG 2.1 AA** for all three products.

### 20.1 Contrast Ratio Audit

| Foreground                              | Background      | Ratio   | WCAG AA | Usage Guidance                                                      |
| --------------------------------------- | --------------- | ------- | ------- | ------------------------------------------------------------------- |
| `--gold` `#C9A84C`                      | `#0A0A0A`       | \~7:1   | Pass    | Safe for labels, headings, buttons. Avoid for body text below 14px. |
| `--text-dim` `#b8b8bc`                  | `#0A0A0A`       | \~11:1  | Pass    | Safe for all sizes including body text.                             |
| `--text` `#f5f5f7`                      | `#0A0A0A`       | \~19:1  | Pass    | Safe everywhere. Primary body text color.                           |
| `--text-muted` `rgba(184,184,188,0.90)` | `#0A0A0A`       | \~10:1  | Pass    | Safe for metadata, timestamps.                                      |
| `--gold` `#C9A84C`                      | `#0D1117` (app) | \~6.5:1 | Pass    | Same guidance as landing.                                           |

**Rule**: Gold is safe for labels, headings, and buttons (all above 14px or bold). Use `--text-dim` or `--text` for body text below 14px. Never use `--gold-dim` for readable text — it's decorative only.

### 20.2 ARIA Patterns

* `<nav>` element for primary navigation
* `<button aria-label="Menu">` for hamburger toggle
* `aria-hidden="true"` on decorative elements (stack connectors, spine)
* `role="dialog" aria-modal="true"` on modals
* Keyboard Escape closes modals

### 20.3 Touch & Pointer

```css
@media (hover: none) {
  .c-dot,
  .c-ring {
    display: none;
  }
}
button {
  touch-action: manipulation;
  min-height: 48px;
}
```

### 20.4 General Requirements

| Requirement            | Implementation                                                                                           |
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
| Color contrast         | All text/background pairs meet 4.5:1 (normal) or 3:1 (large text)                                        |
| Keyboard navigation    | All interactive elements focusable. Tab order matches visual order. Modal trap focus.                    |
| Screen reader support  | All icons have `aria-label` or are `aria-hidden` when decorative. Tables have proper `thead`/`th scope`. |
| Focus indicators       | Visible gold focus ring on all interactive elements (see §14).                                           |
| Color-only information | Positive/negative yield never relies on color alone — `+`/`-` prefix and directional icon required.      |
| Animation              | All motion respects `prefers-reduced-motion` (see §9.5).                                                 |
| Truncated text         | All truncated addresses/hashes provide the full value via tooltip or copy affordance.                    |
| Form labels            | All form inputs have explicit `<label>` associations. No placeholder-only labels.                        |

***

## 21. Copy Standards

UI copy follows the protocol terminology defined in [prd/shared/glossary.md](/docs/prd-shared/glossary.md). Key rules:

* Use "vault" not "fund" or "pool" when referring to ERC-4626 vaults
* Use "agentId" (camelCase) not "agent ID" or "agent id"
* Use "share" not "token" for ERC-4626 vault share tokens
* Use "NAV" (all caps) not "nav" or "net asset value" in data contexts; spell out on first mention in prose
* Use "am-AMM" (hyphenated) not "am AMM" or "amamm"
* Use "proxy announcement" not "pending transaction" for time-delayed proxy entries
* Use "reputation tier" not "level" or "rank"
* Use "claim milestone" not "earn badge" or "unlock achievement"
* Use chain names from [prd/shared/chains.md](/docs/prd-shared/chains.md) — "Base" not "base", "Ethereum" not "ETH mainnet"
* Error messages: always state what happened + what the user can do. Never "Something went wrong." Always "Transaction simulation failed — the vault may have reached its deposit cap. Try a smaller amount."

***

## Appendices

### Appendix A: CSS Custom Properties (Complete Reference)

```css
:root {
  /* Foundation */
  --black: #0a0a0a;
  --surface: #111111;
  --surface-2: #161616;

  /* Gold */
  --gold: #c9a84c;
  --gold-dim: rgba(201, 168, 76, 0.2);
  --gold-mid: rgba(201, 168, 76, 0.4);
  --gold-glow: rgba(201, 168, 76, 0.05);

  /* Gradients */
  --gold-gradient: linear-gradient(
    to right,
    #462523 0%,
    #cb9b51 22%,
    #f6e27a 45%,
    #f6f2c0 50%,
    #f6e27a 55%,
    #cb9b51 78%,
    #462523 100%
  );
  --gold-text-gradient: linear-gradient(
    to bottom,
    #f5edd8 0%,
    #e0c97a 35%,
    #c4993c 70%,
    #a07830 100%
  );

  /* Text */
  --text: #f5f5f7;
  --text-dim: #b8b8bc;
  --text-muted: rgba(184, 184, 188, 0.9);

  /* Metals */
  --bronze: #7a5c28;
  --copper: #8b5e3c;
  --silver: #a0a0a8;
  --amber: #e8a020;
  --green-dark: #3d6b4f;

  /* Tiers */
  --tier-unverified: #4a4a4a;
  --tier-basic: #8b5e3c;
  --tier-verified: #a0a0a8;
  --tier-trusted: #c9a84c;
  --tier-sovereign: #e8a020;

  /* Semantic */
  --success: #34d16a;
  --error: #ef4444;
  --warning: #f59e0b;
  --info: #4a7fb5;

  /* Semantic alpha */
  --success-border: rgba(52, 209, 106, 0.3);
  --success-bg: rgba(52, 209, 106, 0.06);
  --error-border: rgba(239, 68, 68, 0.3);
  --error-bg: rgba(239, 68, 68, 0.05);
  --warning-border: rgba(245, 158, 11, 0.3);
  --warning-bg: rgba(245, 158, 11, 0.05);
  --info-border: rgba(79, 143, 234, 0.3);
  --info-bg: rgba(79, 143, 234, 0.05);

  /* Typography */
  --font-serif: "Instrument Serif", serif;
  --font-mono: "JetBrains Mono", monospace;
  --font-sans: "General Sans", system-ui, sans-serif;

  --tracking-display: -0.02em;
  --tracking-heading: -0.015em;
  --tracking-uppercase: 0.15em;
  --tracking-wide: 0.18em;

  --leading-display: 1.05;
  --leading-heading: 1.15;
  --leading-card: 1.08;
  --leading-body: 1.65;

  /* Spacing */
  --spacing-page: 32px;
  --spacing-card: 24px;
  --spacing-gap: 16px;
  --spacing-seam: 2px;

  /* Radius */
  --radius-sm: 2px;
  --radius-md: 4px;

  /* Easing */
  --ease-luxury: cubic-bezier(0.22, 1, 0.36, 1);
  --ease-cinematic: cubic-bezier(0.16, 1, 0.3, 1);
  --ease-hover: cubic-bezier(0.25, 0.1, 0.25, 1);

  /* Transition tiers */
  --t-premium: 600ms var(--ease-luxury);
  --t-standard: 450ms var(--ease-cinematic);
  --t-micro: 300ms var(--ease-cinematic);

  /* Glass */
  --glass-bg: rgba(14, 14, 14, 0.65);
  --glass-border: rgba(255, 255, 255, 0.08);
  --glass-blur: blur(12px) saturate(150%);
  --glass-shadow:
    0 8px 32px rgba(0, 0, 0, 0.12), inset 0 1px 0 rgba(255, 255, 255, 0.1),
    inset 0 -1px 0 rgba(0, 0, 0, 0.05);
  --glass-hover-border: rgba(201, 168, 76, 0.45);
  --glass-hover-bg: rgba(201, 168, 76, 0.04);
  --glass-active-border: rgba(201, 168, 76, 0.55);

  /* Nav */
  --nav-h: 68px;
}
```

### Appendix B: App Context Overrides

For data-dense app pages, these overrides create a cooler, more functional base while preserving the gold accent system:

```css
:root {
  --black: #0d1117;
  --surface: #161a20;
  --surface-2: #1e2430;
  --glass-bg: rgba(22, 26, 32, 0.7);
  --glass-border: rgba(42, 48, 64, 0.75);
}
```

Everything else (gold, text, easing, glass hover/active, typography) remains identical to the base system.

### Appendix C: Do's and Don'ts

#### Do

* Use 2px seam gaps between sibling glass cards (the PCB trace effect)
* Let serif do the speaking in headlines — keep them large and sparse
* Use gold text gradient on italicized second lines of display headings
* Give monospace data generous letter-spacing (0.02em minimum for numbers)
* Use inset box-shadows on glass for depth (the top-light, bottom-dark pair)
* Transition gold border opacity, not border color (smoother on dark backgrounds)
* Use `font-weight: 300` for Instrument Serif — it's designed to be light
* Use the Data Display Triad (serif number + mono label) for all metrics
* Use the `<strong>` convention (color promotion, not weight) in body text
* Use the three-tier border hierarchy consistently

#### Don't

* Use rounded corners (>4px) on any element — sharp edges are the brand
* Use emojis — anywhere, ever
* Use more than 3 gold accents in a single viewport (restraint)
* Apply film grain or custom cursor to app pages
* Use bright background colors — everything is black/transparent/glass
* Use drop shadows without inset shadows (they look disconnected on dark)
* Use Inter, Roboto, or system fonts — always load General Sans
* Use `font-weight: 700` on Instrument Serif — it only comes in regular
* Use `border-radius: rounded-lg` or similar — max is `2px` except pills (9999px)
* Use gold (`#C9A84C`) for small body text below 14px — use `--text-dim` or `--text` instead
* Mix border hierarchy levels
* Use `font-weight: 700` in body text — the strong convention is color, not weight

### Appendix D: Migration Checklist

When applying this design system across packages:

#### `packages/ui/src/styles/tokens.ts`

* [ ] Update gold from `#E8B84B` → `#C9A84C`
* [ ] Update all rgba gold values to use `201, 168, 76` base
* [ ] Update textDim from `#a1a1a6` → `#b8b8bc`
* [ ] Update textMuted from `rgba(161, 161, 166, 0.7)` → `rgba(184, 184, 188, 0.90)`
* [ ] Add success/error/warning/info semantic colors

#### `packages/ui/src/styles.css`

* [ ] Mirror all token changes in the `@theme` block
* [ ] Update glass variable RGB values

#### `packages/devenv/ui/src/index.css`

* [ ] Replace `--font-sans: 'Inter'` with `'General Sans'`
* [ ] Add General Sans font import to HTML template / Vite config
* [ ] Update `--color-gold` to `#C9A84C`
* [ ] Keep the blue-shifted base (`#0d1117`) — this is the intentional app adaptation
* [ ] Keep the brighter semantic colors (success/error/warning) — validated for data readability

#### All packages

* [ ] Replace any Inter font references with General Sans
* [ ] Ensure all gold alpha values use `201, 168, 76` RGB (not `232, 184, 75`)
* [ ] Standardize border-radius to `2px` (`--radius-sm`) — no rounded corners except pills

***

## Open Questions

| Question                                            | Priority | Notes                                                           |
| --------------------------------------------------- | -------- | --------------------------------------------------------------- |
| Custom icon set — commission or derive from Lucide? | High     | Custom vault/agent/TEE icons needed for the app                 |
| Figma source file location and access               | High     | Design source should live in a shared Figma workspace; link TBD |
| Logo and wordmark artwork                           | High     | Final SVG assets needed before implementation                   |