# Visual Framework — Aesthetic Axioms

Non-template design system. This file is the LLM's thinking framework — not a list of styles to pick from, but a set of immutable laws that govern every design decision.

---

## The Three Absolutes

1. **Restraint** — Remove until it hurts. Then remove one more thing.
2. **Contrast** — Hierarchy through scale and weight, never through color multiplication.
3. **Space Metaphor** — Every page has physical energy: gravity, tension, breathing.

### The Anti-Gaudy Imperative

> **When in doubt, remove. Never add.**

A document looks "cheap" or "土" when it has too many competing visual elements. The cure is always subtraction, never rearrangement.

**Red flags that a design is gaudy:**
- More than 3 decorative elements on a single body page
- Icons or emoji used as section header decoration (use typography instead)
- Decorative borders or frames around body content
- Pattern/texture backgrounds on body pages
- 3+ different hue families visible simultaneously
- Elements added "because there's empty space" rather than for function

**The fix is always:** Delete the decorative element. If the page still communicates its message clearly, it didn't need the decoration. If it doesn't, fix the typography hierarchy — not by adding more visual noise.

### 🚫 The Stock Image / Clipart / AI-Generated Decoration Ban

> **ABSOLUTE PROHIBITION: Do NOT embed stock photos, clipart, watercolor illustrations, AI-generated images (flowers, patterns, borders, frames, ornaments), or any decorative raster/vector artwork into PDF documents.**

This is the #1 source of "cheap" / "土" / "婚庆风" design. Examples of what is BANNED:
- ✘ Watercolor flowers / roses / floral corners / vine borders
- ✘ Gold/metallic decorative frames or borders
- ✘ Stock photo backgrounds (landscapes, textures, marble)
- ✘ Clipart illustrations (ribbons, bows, hearts, stars)
- ✘ AI-generated decorative artwork (DALL-E flowers, Midjourney patterns)
- ✘ Any `<img>` tag used for purely decorative (non-informational) purposes
- ✘ Unsplash/Pexels/Pixabay stock photos used as background or decoration

**What IS allowed:**
- ✔ Geometric shapes rendered in CSS/SVG (circles, lines, rectangles — from `geometry.md`)
- ✔ Typography-based decoration (oversized letters, watermark text, letter-spacing effects)
- ✔ Color blocks and gradients (within palette rules)
- ✔ User-provided photos/logos that are CONTENT (not decoration)
- ✔ Charts and data visualizations
- ✔ Diagrams that convey information

**The principle:** If removing an image doesn't reduce the information content of the document, that image is decoration and should be replaced with typography or geometric elements.

**Wedding invitations, event cards, certificates:** Use elegant typography + geometric accents (thin lines, minimal shapes) + generous whitespace. A beautifully typeset name in 48pt serif with 6pt letter-spacing is infinitely more elegant than watercolor roses.

---

## Color Axioms

### The 60-30-10 Law

Every design consists of exactly three tonal zones:

| Zone | Coverage | Role | Generated by |
|------|----------|------|-------------|
| **60% — Ground** | Background, margins, empty space | Sets mood; the viewer doesn't "see" it consciously | `--c-bg` from `design_engine.py` |
| **30% — Structure** | Cards, dividers, secondary areas | Provides architecture; same hue family as ground, different lightness | `--c-mid` |
| **10% — Emphasis** | Headlines, key numbers, one accent element | Draws the eye; the only place "color" lives | `--c-accent` |

### Saturation Discipline (HARD RULE)

All colors pass through `design_engine.py` which enforces:
- **Saturation range**: 0.05 – 0.25 (HSL). This is non-negotiable.
- **No pure primaries**: Pure red (#ff0000), blue (#0000ff), yellow (#ffff00) are forbidden.
- **Max 3 hues** in the entire document. Variations in lightness/saturation don't count as separate hues.

### Lightness Polarity

Only two lightness regimes exist. The middle is forbidden.

| Mode | Background L | Text L | Forbidden Zone |
|------|-------------|--------|----------------|
| **Dark** (Cinematic) | < 0.10 | > 0.85 | L between 0.30–0.70 for backgrounds |
| **Light** (Editorial) | > 0.95 | < 0.15 | L between 0.30–0.70 for backgrounds |

Muddy mid-tones (L 0.30–0.70) for backgrounds produce the "cheap web app" look. Never.

### What Color is NOT For

Color does not create hierarchy. Size and weight do.

| ❌ Wrong | ✅ Right |
|----------|---------|
| Blue heading, grey subheading, black body | All same hue; heading 900 weight 48px, sub 600 36px, body 400 16px |
| Colored tags/badges for categories | Monochrome tags with border weight variation |
| Gradient text on everything | Gradient text on exactly ONE hero element, nowhere else |

---

## Typography Axioms

### Weight is the New Color

Hierarchy comes from the contrast between extremes of weight:

| Element | Weight | Size Relative to Body |
|---------|--------|----------------------|
| Hero title | 100 (Thin) OR 900 (Black) | 4–6× body |
| Section heading | 700 | 2× body |
| Body | 400 | 1× (baseline) |
| Caption / metadata | 300 | 0.7× body |

The gap between hero and body must be **dramatic** — at least 4× size ratio. Anything less feels timid.

### Font Rules

- **Max 2 families per page**. One serif, one sans (or one display, one text). Never three.
- **Every `font-family` must end with a generic**: `sans-serif`, `serif`, or `monospace`.
- **For physical print (>500mm)**: Use `pt`/`mm` for font sizes, never `px`.

### Line-Height by Density

| Content Type | Line-Height | Why |
|-------------|------------|-----|
| Body text, paragraphs | 1.6–1.8 | Comfortable reading |
| Headings | 0.85–1.0 | Tight, sculptural — headings are visual objects, not sentences |
| Captions, metadata | 1.4 | Compact but readable |

---

## Space Axioms

### The Breathing Margin Rule (MANDATORY)

Every page must have **10–12% clear margin** on all edges. Nothing — no text, no decoration, no card — may enter this zone.

The exact percentage depends on content density:
- **Sparse content** (hero pages, covers): 15% is fine — lots of air
- **Standard content** (editorial, data): **12%** is the sweet spot
- **Dense content** (tables, stat grids): 10% minimum — tighter but still breathable

Default in `design_engine.py`: `inset: 10% 12%` (vertical 10%, horizontal 12%).

```
┌──────────────────────────────┐
│  10-12% margin (breathing)    │
│  ┌────────────────────────┐  │
│  │                        │  │
│  │    Content lives here  │  │
│  │    (76-80% of canvas)  │  │
│  │                        │  │
│  └────────────────────────┘  │
│  10-12% margin (breathing)    │
└──────────────────────────────┘
```

Decorative SVG backgrounds may extend into the margin zone (they're atmospheric, not content). But all readable elements respect it.

### Negative Space is Content

Empty space is not "wasted space." It's a compositional element:
- A poster with 50% whitespace communicates **confidence**
- A poster crammed to 90% communicates **desperation**
- The ratio of content to void sets the emotional tone

### Proximity Rule

Related items are close. Unrelated items are far. The gap between unrelated elements should be **at least 3× the gap between related ones**.

---

## Intent → Visual Translation

Five design intents. Each describes an **atmosphere** — the emotional field the viewer should feel. Intents do NOT prescribe specific parameters (font weight, line-height, SVG type, etc.). All concrete parameter mappings live in `briefs/creative.md` § Intent Mapping Table and `design_engine.py` INTENT_HUES/INTENT_HARMONY_MAP.

### Calm
Stillness. The viewer’s breathing slows. Vast open space, restrained palette, nothing competes for attention. Covers healthcare, wellness, meditation, and minimalist aesthetics. The design communicates through what it *removes*.

### Tension
Conflict. Sharp angles, dramatic contrast, elements that push against each other. Urgency, crisis, disruption. The page has physical energy — something is about to break or has already broken.

### Energy
Motion. Dense composition, slight rotations, warmth. Marketing, launches, social campaigns. The design vibrates — it wants to move off the page. Nothing is perfectly centered.

### Authority
Gravitas. Formal, deliberate, symmetrical. Government, finance, luxury, high-end corporate. Every element is placed with surgical precision. The design commands respect through restraint and weight.

### Warmth
Comfort. Rounded edges, generous spacing, earth tones. Food, lifestyle, home. The design feels like a warm room — inviting, soft, human.

---

> **Legacy mapping:** Serenity → Calm, Minimalism → Calm, Elegance → Authority. Old intent names are accepted as aliases in `design_engine.py` for backward compatibility.

---

## Advanced Visual Techniques

### Semantic-Topological Typesetting (Tension Score)

Text is not visually flat — its "weight" should mirror its emotional intensity. When a document has narrative arc (calm introduction → crisis → resolution), font weight should breathe with it.

**The Principle**: Assign a `tension_score` (0.0–1.0) to `Glass_Canvas` components. The engine maps this to a continuous font weight via Inter Variable font (300–900 axis).

**When it matters**:
- Documents with 3+ pages and clear emotional shifts
- Storytelling: case studies, pitch decks, manifestos
- The reader may not consciously notice, but the subconscious weight variation creates "texture" in the reading experience — the same way a film score operates below awareness

**When to skip**:
- Single-page posters (no arc to express)
- Data-heavy reports (numbers don't have "feelings")
- Short documents where all paragraphs share the same tone

### Cross-Page Visual Continuity (Continuous Flow)

Multi-page documents are not a collection of isolated posters — they're a journey. The background should reflect this.

**The Principle**: Instead of generating independent SVGs per page, generate ONE continuous bezier curve spanning the entire document height, then slice it per-page via SVG `viewBox`. The result: curves that exit one page's bottom edge seamlessly enter the next page's top.

**When to use `continuous_flow`**:
- Multi-page (2+) documents with narrative structure
- Journey/timeline documents
- Brand pieces where seamless sophistication matters
- Best paired with: `Warmth`, `Elegance`, `Serenity` intents

**When to use regular `flow` instead**:
- Single-page documents (continuous has no meaning)
- Each page is conceptually independent (not a story)

### Semantic Shape-Wrapping (Shaped_Canvas)

The most dramatic of the three techniques. Text wraps around invisible geometric shapes, and the negative space itself becomes the illustration.

**The Principle**: A floating `<div>` with CSS `shape-outside` creates a non-rectangular boundary for text flow. The empty void left by the shape is the design element.

**The key insight**: We're not adding an image — we're sculpting the TEXT into a shape. This is extreme minimalism: zero visual assets, maximum visual impact.

**When to use**:
- Pages that need a "wow" without images
- Section openers, cover alternatives
- Content that thematically connects to a shape (ocean → wave, progress → wedge)
- Pages with moderate text density (100–200 words) — the shape needs room

**When NOT to use**:
- Dense content pages (shape eats 30–40% of text area → overflow risk)
- Together with `Glass_Canvas` on the same page (backdrop-filter conflicts)
- More than one per page (visual chaos)

---

## Quality Litmus Tests

Before delivering, every page must pass these:

| Test | Method |
|------|--------|
| **3-meter test** | Can you read the headline from 3 meters away? (size hierarchy) |
| **Squint test** | Squint at the page — do you see clear dark/light zones? (contrast) |
| **Magazine test** | Could this be a page in Monocle, Kinfolk, or Cereal magazine? (taste) |
| **Removal test** | Can you remove any element without losing meaning? If not, you have too little. If yes, remove it. |
| **Color count** | Count distinct hues. If > 3, you've failed the color axiom. |
| **Saturation check** | Run `design_engine.py audit` — any S > 0.25 on non-accent = violation |
| **Breathing check** | Is there 15% clear margin on all edges? |
| **Consistency** | Do all pages share the same font pairing, color tokens, line thickness, and corner radius? |