agemon 0.1.0 → 6.0.0

package/assets/skills/design/agemon-design/references/inspiration.md

@@ -0,0 +1,287 @@
+# Patterns Observed in Mature SaaS Interfaces
+
+Observational pattern analysis from production-grade SaaS landing pages, abstracted from source. All values extracted from real CSS. Section 6 ("What Mature Interfaces Never Do") is the highest-signal section — read it first.
+
+---
+
+## 1. Cross-Surface Patterns
+
+Universal rules observed across the full sample. Treat as proven conventions.
+
+| Pattern | Detail |
+|---------|--------|
+| **Product screenshots with real data** | Never mockups, illustrations, or abstract graphics. Show the actual product with realistic numbers and content. |
+| **Specific metrics in social proof** | "Build times went from 7m to 40s" beats "Trusted by thousands." Quantify the transformation. |
+| **Tabs or interactive sections for features** | Feature areas use tabs, toggles, or interactive demos — never identical 3-column card grids. |
+| **Dual CTAs in the hero** | Primary action (solid) + secondary action (outline/ghost). "Start for free" + "Get a demo" pattern. |
+| **One positioning statement** | Hero headline is a single sentence that defines what the product is. No paragraphs. |
+| **Logo strips of real companies** | "Trusted by" followed by 5-8 recognizable, specific company logos. |
+| **Minimal decoration** | Content IS the design. No ornamental gradients, blobs, or abstract shapes competing with the product. |
+| **Changelog/velocity proof** | At least one section proves the product ships fast — changelogs, release notes, version timelines. |
+| **Every section has a distinct layout** | No two adjacent sections share the same visual structure. Variety signals intentional design. |
+| **Centered hero alignment** | Center-aligned heroes dominate mature SaaS. Left-aligned is less common. |
+
+---
+
+## 2. Hero Section Archetypes
+
+Six recurring hero patterns. Each is named by structure, not by source.
+
+### Archetype A — Minimal text-only
+One large headline + subhead + 1-2 CTAs. No product visual in the viewport. Relies entirely on copy to communicate value. Works when the product name alone carries recognition or when the headline is provocative enough to pull the scroll.
+
+- Headlines: 5-10 words, sentence case
+- Subhead: 1-2 lines max, 18-20px, neutral-500
+- CTAs: dual (solid primary + ghost secondary) or single strong action
+- Below hero: immediate product proof (no filler sections)
+
+**When it breaks:** products without brand recognition or a strong category-defining statement — the missing visual leaves new users with nothing to anchor on.
+
+### Archetype B — Asymmetric headline + product screenshot
+Left-aligned headline block, right-aligned product UI or screenshot. Gives a document/editorial feel. Communicates "the product is the proof" without centering the hero on pure copy.
+
+- Layout: ~50/50 split or 40/60 text/visual
+- Visual: high-fidelity product screenshot, not illustration
+- Alignment: text left, visual right (rarely reversed)
+
+**When it breaks:** products with complex UIs that don't read quickly at a glance — the visual confuses instead of proving.
+
+### Archetype C — Product-first (full-width UI)
+Minimal headline above or beside a massive full-width product screenshot or embedded interactive demo. The product IS the hero. Copy is secondary.
+
+- Headline: minimal, often a single phrase or word
+- Visual: takes 60-80% of above-the-fold height
+- Can include real interactive elements, not just static images
+
+### Archetype D — Bento grid hero
+Positioning statement centered above a bento grid of product surfaces. Each card shows a different feature or UI. Communicates product breadth.
+
+- Grid: mixed card sizes — one large card + 2-3 smaller
+- Each card shows a distinct product surface
+- Typography: headline centered above the grid
+
+### Archetype E — Editorial figure
+Value propositions presented as numbered editorial figures ("FIG 0.2", "FIG 0.3"). Gives a technical publication feel. Strong for developer-focused products where "serious" positioning outweighs "approachable."
+
+- Section labels: uppercase monospace or small-caps
+- Layout: each figure gets a distinct visual treatment
+- No uniform card grid
+
+### Archetype F — Scrolling social proof strip
+Hero text centered, immediately followed by a horizontally scrolling logo strip (continuous loop, not static). Makes "trusted by" feel dynamic and high-volume.
+
+- Logos: monochrome or muted, not full-color
+- Motion: CSS scroll animation, pauses on hover
+- Placement: immediately below hero CTA block
+
+**When it breaks:** early-stage products without recognizable logos — an empty or weak strip signals the opposite of trust.
+
+---
+
+## 3. Feature Presentation Patterns
+
+No mature SaaS product uses identical card grids for features.
+
+### Tab-based feature sections
+- Horizontal tabs or pills at the top of a section
+- Each tab reveals completely different content (screenshot, demo, description)
+- Prevents the monotonous 3-column icon+heading+text grid
+
+**When it breaks:** more than 5-6 tabs — cognitive load exceeds the benefit of the interactive reveal.
+
+### Bento grid (varied card sizes)
+- Mixed card dimensions: one large card + 2-3 smaller cards
+- Each card shows a different product surface
+- Unequal sizing creates visual hierarchy within the grid
+
+### Editorial figures
+- Value propositions presented as numbered figures
+- Each figure gets a distinct layout treatment
+- Feels like a technical publication, not a marketing template
+
+### Product-first (screenshots as features)
+- Instead of describing features, embed the actual product
+- Interactive demos, live UI, or high-fidelity screenshots
+- The product IS the feature presentation
+
+### Alternating text + visual rows
+- Text on one side, visual (screenshot/demo) on the other
+- Sides alternate per row to create rhythm
+- Each visual is unique — chart, screenshot, code block
+
+### Key principle
+Every feature section should feel designed individually for that feature. If two feature blocks can be swapped without anyone noticing, the design is too uniform.
+
+---
+
+## 4. Social Proof Patterns
+
+| Pattern | Implementation |
+|---------|----------------|
+| **Logo strip** | Horizontal row of 5-8 company logos, monochrome or muted. "Trusted by" or "Used by teams at." |
+| **Specific metrics** | Metric + customer name: "7m to 40s build times" next to company logo. |
+| **Testimonial with identity** | Photo + name + title + company logo. Quote is specific, references the product feature. |
+| **Customer count** | "Join 50,000+ teams" or similar, placed near CTA. |
+| **Changelog as proof** | Release dates and features listed to show shipping velocity. |
+
+### What makes social proof work
+- **Specificity over volume** — one concrete metric beats "trusted by thousands"
+- **Recognizable logos** — users infer quality from the companies they recognize
+- **Real quotes with attribution** — name, role, company, photo. Generic praise without identity is worthless
+- **Proximity to CTAs** — social proof placed directly before or after the call to action
+
+---
+
+## 5. Signature Details by Pattern Type
+
+Concrete patterns observed in production. Each stands as a reusable technique.
+
+### Card and surface treatment
+- **Grid-line border aesthetic**: horizontal and vertical borders (`border-x`, `border-y` in Tailwind) with a custom grid-border color — creates a technical grid feel without background fills
+- **Inset shadow for sunken surfaces**: `box-shadow: 0 2px 6px 0 rgba(0,0,0,0.2) inset` — signals an embedded or input-like container
+- **Hairline card borders**: 1px `neutral-200` with a bottom-only `rgba(0,0,0,0.04)` shadow — separation without visual weight, common in card-heavy dashboard layouts
+- **Bento card sizing ratio**: ~2:1 dominant card to minor cards; never all cards equal size
+
+### Typography signatures
+- **Display italics**: italicized hero headline as a typographic accent — distinctive without added color
+- **Negative letter-spacing on all headings** (see Section 7 for exact values)
+- **Font weight distribution skewed to medium**: `font-weight: 500` as the dominant weight across UI, `600` for emphasis only, `700` reserved for hero scale
+- **Editorial section labels**: uppercase, tracked-out, small — "FIG 0.2" or "01 / OVERVIEW" style
+
+### Color signatures
+- **One accent, used sparingly**: accent color appears in CTAs and key interactive elements only — not in decorative elements
+- **Nearly colorless base UI**: neutral-first palette; color reserved for status and brand accent
+- **Dark mode via alpha overlays**: `color: rgba(255,255,255,0.9)`, `background: rgba(255,255,255,0.1)` on hover — avoids hardcoded dark-mode color values
+- **Tinted neutral grays**: never pure `#000` or `#fff` as text; always cool-toned (see Section 7)
+
+### Microinteraction signatures
+- **Ring-halo hover**: `box-shadow: 0 0 0 4px var(--neutral-200)` instead of background color change — reads as "glowing" selection
+- **Slide-up-fade entrance**: translate Y offset + opacity fade, 50ms staggered per item, 500ms duration
+- **Hover lift**: `translateY(-2px)` + shadow growth at `150-200ms ease-out`
+- **No `transition: all`**: always target specific properties — `transition: box-shadow, transform, opacity`
+
+### Spacing signatures
+- **Section rhythm**: 80-120px between sections
+- **Card internal padding**: 24-40px
+- **Card gaps**: 24-32px
+- **Nav height**: 64px
+- **Max content width**: 1080-1200px
+
+---
+
+## 6. What Mature Interfaces Never Do
+
+Confirmed absent across the full observed sample:
+
+| Anti-Pattern | Why It Fails |
+|-------------|-------------|
+| **Emoji icons in feature lists** | Looks unfinished. Production UIs use custom SVG icons or product screenshots. |
+| **Colored gradient text** | None use rainbow or multi-color gradient text. Even dark-themed interfaces avoid it. |
+| **Star ratings in testimonials** | Zero instances. All use quote + name + role + company. |
+| **Identical 3-column feature cards** | No section repeats the same card layout for features. Each section is bespoke. |
+| **Placeholder or generic text** | Every piece of text is specific to the product. No "lorem ipsum" energy. |
+| **Bouncy/elastic animations** | Motion is subtle and functional. No bounce, no wiggle, no playful easing. |
+| **Colored pill badges for metrics** | Metrics are displayed as plain text with clear hierarchy, not decorated badges. |
+| **ALL CAPS headings** | Sentence case or title case throughout. No uppercase headings. |
+| **Glassmorphism** | Not a single frosted-glass panel. Even dark-themed interfaces avoid it. |
+| **Abstract blob/orb decorations** | Intentional branded gradients exist. Generic decorative blobs do not. |
+| **Multiple competing accent colors** | One accent color, used consistently and sparingly. |
+| **"Powered by" or tool attribution** | No marketing page advertises its own stack in the footer. |
+| **Generic CTAs** | No "Learn more" or "Click here." Every CTA is specific: "Start for free", "Download", "Start Deploying". |
+| **Walls of text** | No section has more than 2-3 sentences. Copy is ruthlessly concise. |
+| **Pure black text** | None use `#000000`. Darkest text is cool gray — `#414552` or `#18181b` (zinc-900). |
+
+---
+
+## 7. Reference Token Values
+
+Values extracted from production CSS. Use as calibration for "what premium feels like in code." Where two observed systems differ significantly, both are shown with labels.
+
+### Type scale ranges observed
+
+```
+Hero (76-94px):     weight 700, line-height 1.05, letter-spacing -0.04em
+Section (48-56px):  weight 700, line-height 1.1,  letter-spacing -0.03em
+Card (24-32px):     weight 600, line-height 1.2,  letter-spacing -0.02em
+Body (16-17px):     weight 400, line-height 1.5,  letter-spacing normal
+```
+
+**Pattern A (medium-dominant)**: `font-weight: 500` as primary UI weight (120+ instances), `600` for emphasis only, `700` avoided entirely.
+**Pattern B (bold-dominant)**: `700` reserved for hero and section headings only; `400` for all body copy.
+
+### Spacing scales observed
+
+```
+Section gaps:      80-120px
+Card gaps:         24-32px
+Card padding:      24-40px
+Nav height:        64px
+Max content width: 1080-1200px
+Base unit:         4px
+```
+
+### Shadow stack examples
+
+**Blue-gray tinted shadows** (never pure black):
+```css
+/* Resting */ box-shadow: rgb(64 68 82 / 8%) 0px 2px 5px 0px;
+/* Hover */   box-shadow: rgb(64 68 82 / 8%) 0px 2px 5px 0px, rgb(64 68 82 / 8%) 0px 3px 9px 0px;
+/* Focus */   box-shadow: 0 0 0 4px rgb(1 150 237 / 36%);
+```
+
+**Ring-halo hover** (neutral, no blue tint):
+```css
+box-shadow: 0 0 0 4px var(--neutral-200, #e5e5e5);
+/* Tailwind: hover:ring-4 hover:ring-neutral-200 */
+```
+
+**Inset sunken surface**:
+```css
+box-shadow: 0 2px 6px 0 rgba(0,0,0,0.2) inset;
+```
+
+### Border-radius observed
+
+**Pattern A** (restrained):
+```
+Inputs: 4px | Buttons: 8px | Cards: 8-10px | Pills/badges: 999em
+```
+
+**Pattern B** (more generous):
+```
+Buttons: 8px (rounded-lg) | Cards: 12-16px (rounded-xl / rounded-2xl) | Badges: 9999px (rounded-full)
+```
+
+The difference teaches: card radius scales up proportionally with card size. Small cards (dashboard widgets) at 8px, large cards (feature showcase) at 12-16px.
+
+### Color tinted-neutral examples
+
+```
+Text primary:   #414552  (cool gray-700, NOT #000)
+Text secondary: #687385  (cool gray-500)
+Borders:        #d5dbe1  (cool gray-150)
+Surface:        #f6f8fa  (cool gray-50)
+Brand accent:   #625afa  (purple-500 — one example; substitute project accent)
+```
+
+**Dark mode via alpha** (avoids hardcoded dark-mode palette):
+```css
+color: rgba(255,255,255,0.9);           /* Tailwind: text-white/90 */
+background: rgba(255,255,255,0.1);      /* Tailwind: hover:bg-white/10 */
+```
+
+### Motion timing observed
+
+```
+Hover transitions:    150-200ms ease-out
+Entrance animations:  500ms duration, 50ms staggered delay per item
+Transform:            translateY(-2px) on hover lift
+Property targeting:   box-shadow, transform, opacity — never transition: all
+```
+
+**Font pairing pattern** (display + system + mono):
+```
+Display headings: Satoshi or equivalent geometric sans
+Body:             Inter or equivalent neutral sans
+Code/technical:   Geist Mono or equivalent monospace
+```

package/assets/skills/design/agemon-design/references/layout.md

@@ -0,0 +1,236 @@
+# Layout & Composition
+
+Spatial reasoning, grouping principles, and hierarchy discipline. Tools (Flex, Grid) come last.
+
+---
+
+## Gestalt Grouping Principles
+
+Perception organizes visual fields before conscious thought. Five laws govern how elements are read as groups:
+
+**Proximity** — Elements closer together are perceived as related. Spacing is the primary grouping signal. Use it before borders, cards, or background fills.
+
+**Similarity** — Elements that share shape, color, or size are perceived as the same kind of thing. Color-coding a column in a table exploits this; inconsistent icon weights break it.
+
+**Common Region** — Elements inside a shared boundary (card, background, border) form a group. Use sparingly — every card is a visual tax. Ask: does this content need isolation, or does proximity alone suffice?
+
+**Continuity** — The eye follows a line or curve through a layout. Aligning elements along an axis creates an implied path that guides the scan.
+
+**Closure** — The eye completes incomplete shapes. Use this to reduce clutter: a partially-visible element (card cropped at viewport edge) signals "more exists" without a label.
+
+### The primary rule: use spacing before structure
+
+Before reaching for a card, background swatch, or divider line, try creating the group with spacing alone. If it reads, stop there. Structure adds visual weight and complexity — earn it.
+
+---
+
+## Spacing Rhythm
+
+The most violated rule in UI. State it as an invariant:
+
+> **Space within a group < space between groups < space between sections.**
+
+Concrete: a form label 4px above its input, inputs in the same form 16px apart, the form itself 48px from the next section. If any of these relationships inverts, the grouping breaks.
+
+### Scale
+
+Use tokens from a defined set. Values come from the scale — never arbitrary.
+
+```css
+--space-xs:  0.25rem;   /* 4px  — label-to-input, icon-to-label */
+--space-sm:  0.5rem;    /* 8px  — items within a group */
+--space-md:  1rem;      /* 16px — related components */
+--space-lg:  1.5rem;    /* 24px — sibling sections */
+--space-xl:  2rem;      /* 32px — component-to-component */
+--space-2xl: 3rem;      /* 48px — section separations */
+--space-3xl: 4rem;      /* 64px — major page regions */
+--space-4xl: 6rem;      /* 96px — hero-to-content, above-fold breathing room */
+```
+
+Use `gap` for sibling spacing — eliminates margin collapse and is the correct mental model.
+
+Use `clamp()` for fluid spacing: `clamp(var(--space-lg), 4vw, var(--space-3xl))` scales without breakpoints.
+
+**WHEN IT BREAKS:** Very dense data tables and compact UI patterns (command palettes, menus) compress this rhythm deliberately. At 100% zoom the hierarchy still holds — the scale values shrink proportionally. Never collapse two adjacent levels to the same value.
+
+---
+
+## Visual Hierarchy
+
+### The Squint Test
+
+Stand back, defocus your eyes, or apply a blur filter to the design. The image resolves to blobs of light and dark, size and contrast — text becomes unreadable. What you see is the page at the perceptual level of a first glance (~200ms).
+
+At that level:
+
+1. One thing should dominate — the primary action or headline.
+2. A secondary cluster should appear next — supporting information.
+3. The page structure (navigation, footer, sidebar) should be lowest in perceived weight.
+
+Why it works: the human visual system applies a low-pass spatial frequency filter before conscious reading. The squint test simulates that filter. If hierarchy fails the squint test, users experience visual noise even if they cannot articulate why.
+
+### Measurable Ratios
+
+Four levels is the practical maximum for most UI. Beyond that, distinctions collapse.
+
+| Level | Role | Signal |
+|-------|------|--------|
+| Primary | Page-defining element (hero headline, main CTA) | Largest, highest contrast, most visual weight |
+| Secondary | Supporting structure (subheadings, section labels) | Minimum 1.5x smaller or lighter than primary |
+| Tertiary | Body content, field labels, card titles | Readable, not competing |
+| Quaternary | Metadata, timestamps, captions | Muted, clearly subordinate |
+
+**Minimum 1.5x difference between adjacent levels** to create a clear distinction. A 1.2x difference reads as an accident, not a decision.
+
+**WHEN IT BREAKS:** Typography pairs can carry hierarchy at identical size using weight + tracking — a 400/700 weight pair at 14px is a clear two-level system. In that case the size ratio rule yields to the type system. See `typography.md`.
+
+### Hierarchy Tools (use in this order)
+
+1. **Space** — generous whitespace isolates the primary element before you touch anything else
+2. **Size** — scale differences above 1.5x register immediately
+3. **Weight** — font-weight, border-weight, shadow depth
+4. **Color** — last resort; adds semantic load and accessibility risk
+
+Using all four at once creates noise. Mature interfaces use one or two.
+
+---
+
+### Serial Position Effect
+
+First and last items in a sequence are remembered best (primacy + recency). Put the critical item first or last in nav lists, onboarding steps, and feature rows — never buried mid-sequence. Mid-list is where options go to be forgotten.
+
+## Composition Strategies
+
+### Symmetry vs. Asymmetry
+
+Symmetry signals stability, formality, and confidence. Use it for hero sections, authentication flows, landing page headers.
+
+Asymmetry signals energy, modernity, and movement. Use it for editorial layouts, feature showcases, dashboards with a dominant primary panel.
+
+Avoid the default of centered-everything — it reads as unsophisticated because it makes no compositional decision. Left-aligned layouts with deliberate asymmetric weight distribution feel more considered.
+
+### Focal Point
+
+Every layout needs exactly one focal point — the element the eye arrives at first. If you have two competing elements at the same visual weight, one of them is wrong. Remove hierarchy from one or subordinate it spatially.
+
+### Optical Center vs. Geometric Center
+
+The geometric center of a rectangle is at 50% vertical. The optical center is 5–8% above that. Content positioned at the optical center feels balanced; content at true geometric center reads as slightly low.
+
+This matters most for:
+- Modal dialogs — vertically centered modals in a viewport look sunken; use `align-items: center` with a slight upward offset or top-biased margins
+- Icon placement within a bounding box — a 24×24 icon with a visually tall glyph needs a −1px vertical nudge
+- Above-the-fold hero sections — weight the primary element in the upper optical zone
+
+### Rule of Thirds (use only with hero imagery)
+
+The rule of thirds creates dynamic tension by placing subjects at grid intersections rather than center. In interfaces without strong photographic content it adds complexity without benefit. Reserve it for editorial layouts and landing pages with full-bleed images.
+
+---
+
+## Alignment Discipline
+
+- **Max 1-2 alignment types per section.** Every additional alignment axis is another anchor the eye must re-find; mixed left/center/right in one view reads as unplanned.
+- **Mixed text sizes on one line align to the shared baseline**, not to vertical centers — center-aligning a 24px number next to a 13px label makes the label float.
+- **Truncate the middle, not the end**, when items share long prefixes ("Quarterly report — … — Q3 2026"): the differentiating ends are what users scan for.
+
+---
+
+## Choosing Layout Tools
+
+**Flexbox — 1D.** Rows of items, nav bars, button groups, component internals. Default choice for the majority of components.
+
+**Grid — 2D.** Page structure, dashboards, anything requiring row AND column coordination. Reach for it when flex with `flex-wrap` forces workarounds.
+
+```css
+/* Responsive without breakpoints — flex */
+.group { display: flex; flex-wrap: wrap; gap: var(--space-md); }
+
+/* Responsive without breakpoints — grid */
+.grid  { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: var(--space-lg); }
+```
+
+Don't default to Grid when Flex would be simpler. Don't reach for JS measurement when CSS layout solves it.
+
+---
+
+## Breaking Monotony
+
+- Don't default to card grids for everything — spacing creates grouping naturally
+- Cards only when content is truly distinct and actionable — never nest cards inside cards
+- Vary card sizes, span columns, or mix cards with non-card content
+- Asymmetric compositions break the centered-content default when the content supports it
+- Never template the "big metric + small label + stat row + gradient" pattern — it's a design cliché
+
+---
+
+## Depth & Elevation
+
+### Z-Index Scale (Semantic)
+```css
+--z-dropdown:       10;
+--z-sticky:         20;
+--z-modal-backdrop: 30;
+--z-modal:          40;
+--z-toast:          50;
+--z-tooltip:        60;
+```
+
+Never use arbitrary values (999, 9999). Use elevation to reinforce hierarchy, not as decoration.
+
+### Shadow Scale
+```css
+--shadow-sm:  0 1px 2px rgba(0,0,0,0.05);
+--shadow-md:  0 4px 6px rgba(0,0,0,0.07), 0 1px 3px rgba(0,0,0,0.06);
+--shadow-lg:  0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05);
+--shadow-xl:  0 20px 25px rgba(0,0,0,0.1), 0 8px 10px rgba(0,0,0,0.04);
+```
+
+Always layered (ambient + direct light). Higher elevation = larger spread + lower opacity, not just a bigger number.
+
+**Dark mode breaks layered shadows.** A dark shadow cast on a dark surface has nowhere to show up — the layered ambient+direct recipe above effectively disappears. Don't stack darker shadows to compensate; collapse elevation to a single subtle light ring instead — a 1px, low-alpha white inset or outset border (`0 0 0 1px rgba(255,255,255,0.08)`-ish) reads as "raised" against a dark surface the way a shadow does against a light one.
+
+---
+
+## Optical Adjustments
+
+- **±1px nudges** when geometric centering looks visually off-center — common with icons inside buttons, badges, avatars
+- **Nested radii:** child ≤ parent. Use `calc(var(--radius-parent) - var(--padding))` to keep concentric curves
+- **Icon/text lockups:** adjust weight, size, spacing, or color — one lever at a time until they feel unified
+
+### Concentric Radius Arithmetic
+
+The relationship that keeps nested corners visually parallel: **outer radius = inner radius + the gap between the two edges.** Worked example on the token scale — an inner surface using `--radius-xl` (14px) sitting inside 6px of padding needs an outer radius of `14 + 6 = 20px`, which lands exactly on `--radius-2xl`. Skip the arithmetic and the outer curve either pinches tighter than the inner one (looks accidental) or bows out looser (looks sloppy) — concentric only reads as intentional when the two curves share a center point.
+
+**Exception:** past roughly 24px of padding, the two surfaces read far enough apart that concentric math stops mattering — at that distance, treat inner and outer as separate surfaces with independently chosen radii rather than chasing an arithmetic relationship the eye can no longer perceive.
+
+### Optical Alignment Recipes
+
+- **Icon-leading buttons need asymmetric padding** — trim roughly 2px off the icon side of the button's padding. An icon's own whitespace (the space inside its bounding box between the glyph and its edge) reads as extra padding the eye already counts, so equal padding on both sides looks lopsided toward the icon.
+- **Triangular and asymmetric glyphs need a nudge toward their visual mass.** Play icons, carets, and similar shapes have most of their ink weight off-center within their bounding box — a 1-2px nudge in the direction the shape "leans" corrects the optical imbalance a perfectly centered bounding box leaves behind.
+- **When an SVG is persistently off-balance across every context it's used in**, fix the path's `viewBox` centering at the source rather than compensating with margin on every instance. Per-instance margin hacks drift out of sync the next time the icon is resized or reused elsewhere; a corrected `viewBox` fixes it everywhere at once.
+
+---
+
+## Style-to-CSS Reference
+
+| Property | Minimal Clean | Soft Modern | Sharp Geometric | Rich Editorial | Dark Premium | Playful Bold |
+|----------|---------------|-------------|-----------------|----------------|--------------|--------------|
+| `border-radius` | 2-4px | 8-16px | 0px | 2-4px | 4-8px | 12-20px |
+| Shadows | None or barely-there | Layered (ambient + direct) | None — use borders | Subtle, warm | Subtle glow, inset | Bold, offset |
+| Borders | `rgba(0,0,0,0.06)` 1px | Soft, same hue as shadow | 1px crisp, high-contrast | Thin, warm-tinted | `rgba(255,255,255,0.08)` | Thick, colored |
+| Spacing | Generous whitespace | Comfortable, padded | Tight, precise | Generous, editorial | Moderate | Loose, breathing |
+| Weight range | 400-600 | 400-600 | 400-800 | 300-700 | 400-700 | 500-800 |
+
+---
+
+## Never
+
+- Arbitrary spacing outside your defined scale
+- All spacing equal across a section — variety creates hierarchy
+- Wrap everything in cards — not everything needs a container
+- Nest cards inside cards
+- Center everything — left-aligned asymmetry reads as more intentional
+- Default to Grid when Flex would be simpler
+- Arbitrary z-index values (999, 9999)
+- Two adjacent hierarchy levels at the same visual weight — decide which leads