264 lines
12 KiB
Markdown
Executable File
264 lines
12 KiB
Markdown
Executable File
# 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? |
|