12 KiB
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
- Restraint — Remove until it hurts. Then remove one more thing.
- Contrast — Hierarchy through scale and weight, never through color multiplication.
- 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-familymust end with a generic:sans-serif,serif, ormonospace. - For physical print (>500mm): Use
pt/mmfor font sizes, neverpx.
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.pyfor 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,Serenityintents
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_Canvason 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? |