agemon 0.1.0 → 6.3.0

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

@@ -0,0 +1,319 @@
+# Heuristics — Severity-Ranked Review Methodology
+
+Any skill can list anti-patterns. A heuristic review is a defensible artifact a PM can action: every finding names a heuristic or law, the element it applies to, the viewport it was seen at, and an impact tag. This file is the source of truth for the heuristic mode of `/agemon-design review` — the checklist, the laws, the output shape. It produces findings, not numbers: a figure computed from model judgment reads as a measurement it is not.
+
+---
+
+## How to Use
+
+Run the full pass: Nielsen's 10 as a checklist → the 6 Design Laws as checks → rank findings by impact tag. Output is a findings table PMs can paste into any issue tracker.
+
+Usability is not a knob. `CRAFT_LEVEL` does not relax these findings — a blocking problem is blocking at every craft level.
+
+---
+
+## Finding Format
+
+Every finding is one row: `| Heuristic or law | Element | Viewport | Finding | Impact |`.
+
+- **Element** names the specific thing: "Save button in the settings form", not "the form".
+- **Viewport** is where you saw it (desktop 1280, tablet 768, mobile 375, or "code only" if you did not render it).
+- **Finding** is concrete: quote the text, count the elements, name the broken flow. Vague findings are rejected.
+- A heuristic with nothing to report gets no row. Do not pad the table with praise.
+
+---
+
+## Nielsen's 10 Usability Heuristics
+
+Source: Nielsen, J. (1994). "10 Usability Heuristics for User Interface Design." Nielsen Norman Group.
+
+### 1. Visibility of System Status
+
+The system should always keep users informed about what is going on, through appropriate feedback within reasonable time.
+
+**What to look for:**
+- [ ] Every async action has a loading state (spinner, progress, skeleton)
+- [ ] Submit buttons disable + show progress while in flight
+- [ ] Optimistic UI reconciles on server response (no silent failure)
+- [ ] Navigation state is visible (active tab, breadcrumb, selected row)
+- [ ] Long operations (>5s) escalate to progress percentage or estimate
+
+**Common failures in AI-generated UIs:**
+- Form submit has no loading state — user clicks 3-4x thinking nothing happened
+- Toast appears then disappears before the user can read it
+- No indication that a save succeeded ("did it work?")
+
+### 2. Match Between System and the Real World
+
+Speak the user's language — words, phrases, concepts they know. Follow real-world conventions.
+
+**What to look for:**
+- [ ] No system jargon in user-facing copy ("exception thrown", "null ref")
+- [ ] Icons match cultural convention (trash = delete, not a cog)
+- [ ] Dates are formatted for the user's locale, not ISO
+- [ ] Error messages speak human, not stack trace
+- [ ] Metaphors are consistent (folder, file, workspace)
+
+**Common failures in AI-generated UIs:**
+- "Submit payload" instead of "Save changes"
+- "Entity not found" instead of "We couldn't find that project"
+- Time displayed as `1713369600` (Unix) instead of `2 hours ago`
+
+### 3. User Control and Freedom
+
+Users often perform actions by mistake. They need a clearly marked emergency exit.
+
+**What to look for:**
+- [ ] Every destructive action has Undo (preferred) or a confirm dialog
+- [ ] Modals close on Esc and on backdrop click
+- [ ] Multi-step flows have Back without losing state
+- [ ] Autosave preserves in-progress work on nav away
+- [ ] URL reflects state so the back button works
+
+**Common failures in AI-generated UIs:**
+- Delete is instant and irreversible — no undo toast
+- Modal traps the user; no way out without completing the form
+- Browser back loses all form input
+
+### 4. Consistency and Standards
+
+Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform conventions.
+
+**What to look for:**
+- [ ] Primary action placement consistent across views (right side, solid fill)
+- [ ] Same verb for same operation throughout ("Delete" always, not "Delete"/"Remove"/"Trash")
+- [ ] Icon meanings stable across screens
+- [ ] Form patterns match platform (e.g., Cmd+Enter submits on macOS)
+
+**Common failures in AI-generated UIs:**
+- Buttons swap position between modals (Cancel left here, right there)
+- Three different words for "delete" in the same product
+- Non-standard scroll hijacking on a standard content page
+
+### 5. Error Prevention
+
+Better than good error messages is a design that prevents the problem from occurring in the first place.
+
+**What to look for:**
+- [ ] Destructive actions require confirmation typed with the resource name
+- [ ] Disabled states prevent invalid submissions (with explanation on hover)
+- [ ] Input constraints enforced client-side (date pickers, typed inputs)
+- [ ] Autosave + version history on content-creation surfaces
+- [ ] Warn before leaving unsaved changes
+
+**Common failures in AI-generated UIs:**
+- Freeform "Are you sure?" confirms that users mindlessly click
+- No validation until submit; user fills 12 fields then sees 4 errors
+- Paste blocked on fields (password confirm, order IDs)
+
+### 6. Recognition Rather Than Recall
+
+Minimize the user's memory load by making objects, actions, and options visible.
+
+**What to look for:**
+- [ ] Recently used / favorited items surfaced
+- [ ] Autocomplete on any field with a known set of answers
+- [ ] Keyboard shortcuts listed in tooltips (not hidden in a help menu)
+- [ ] Current selection persists visibly
+- [ ] Empty states suggest next actions
+
+**Common failures in AI-generated UIs:**
+- Power-user shortcuts (Cmd+K) exist but are undiscoverable
+- User must remember which tab they were on after a refresh
+- Dropdown with 200 options and no search
+
+### 7. Flexibility and Efficiency of Use
+
+Accelerators — unseen by novice — may speed up the interaction for the expert.
+
+**What to look for:**
+- [ ] Keyboard shortcuts for frequent actions (Cmd+K, j/k nav)
+- [ ] Bulk actions on lists (multi-select + batch operate)
+- [ ] Saved views / filters / segments
+- [ ] Customization for heavy users (column config, hotkeys)
+- [ ] Paste-to-action patterns (URL paste auto-parses)
+
+**Common failures in AI-generated UIs:**
+- Forces the same flow for novice and expert
+- No way to multi-select in lists of 100+
+- Command palette missing on tools users will spend hours in
+
+### 8. Aesthetic and Minimalist Design
+
+Dialogues should not contain information that is irrelevant or rarely needed.
+
+**What to look for:**
+- [ ] Every section answers one question; no filler
+- [ ] Visual weight proportional to importance
+- [ ] One accent, 3-5 placements per viewport (see core-rules.md, Anti-Slop Test)
+- [ ] White space is used, not avoided
+- [ ] No decorative graphics competing with content
+
+**Common failures in AI-generated UIs:**
+- Hero has 4 CTAs of equal weight
+- Every card has a colored top border
+- Gradient backgrounds on every section
+
+### 9. Help Users Recognize, Diagnose, and Recover From Errors
+
+Error messages in plain language, precisely indicate the problem, and constructively suggest a solution.
+
+**What to look for:**
+- [ ] Errors appear inline, at the field, not as a global banner
+- [ ] Messages specify what went wrong AND how to fix it
+- [ ] Server errors include a copy-to-clipboard ID for support
+- [ ] Recovery is one click (retry, undo, contact support)
+- [ ] Network errors differ from validation errors
+
+**Common failures in AI-generated UIs:**
+- "Something went wrong" with no detail, no retry, no support path
+- Red toast that disappears before the user reads it
+- Error blames the user ("Invalid input") instead of explaining
+
+### 10. Help and Documentation
+
+Even though it is better if the system can be used without documentation, help may be necessary.
+
+**What to look for:**
+- [ ] Help is contextual, not a separate site the user must leave to
+- [ ] Empty states double as onboarding ("Create your first project")
+- [ ] Tooltips on non-obvious icons
+- [ ] Inline help links in complex forms
+- [ ] Searchable docs for deep features
+
+**Common failures in AI-generated UIs:**
+- No tooltips on icon-only buttons
+- Help buried behind a "?" in the corner with a 404 behind it
+- Onboarding is a 10-slide lightbox the user skips
+
+---
+
+## The 6 Design Laws
+
+Each is checked against a specific element. These are physics + psychology, not preferences — breaking them has measurable UX impact.
+
+### Fitts's Law
+
+Source: Fitts, P. M. (1954). "The information capacity of the human motor system in controlling the amplitude of movement."
+
+**Statement:** Time to acquire a target is a function of its size and distance.
+
+**When load-bearing:** Every tappable / clickable surface. Critical on mobile.
+
+**What to look for:**
+- **Holds when** touch targets ≥ 44px on mobile, ≥ 24px on desktop; primary CTA in the natural eye/thumb path; related actions grouped
+- **Breaks when** touch targets under 44px mobile; destructive actions adjacent to primary actions; CTA placed far from where the user just looked
+
+### Hick's Law
+
+Source: Hick, W. E. (1952). "On the rate of gain of information."
+
+**Statement:** Decision time grows logarithmically with the number of choices.
+
+**When load-bearing:** Menus, navigation, plan selectors, form fields, dashboards.
+
+**What to look for:**
+- **Holds when** nav ≤ 7 items at any level; no field offers 20+ unfiltered options without search
+- **Breaks when** 12+ top-nav items; a single select with 200 entries and no type-ahead; dashboard with 18 metrics at equal weight
+
+### Doherty Threshold
+
+Source: Doherty, W. J. & Thadani, A. J. (1982). "The Economic Value of Rapid Response Time." IBM.
+
+**Statement:** Productivity soars when response time is under 400ms.
+
+**When load-bearing:** Every user-initiated action. Critical on data-heavy views and transitions.
+
+**What to look for:**
+- **Holds when** perceived response < 400ms; optimistic UI for saves, likes, toggles; skeletons within 200ms
+- **Breaks when** form submit shows a spinner for 2s with no optimistic state; nav click waits on full server round-trip before painting anything
+
+### Cleveland-McGill Hierarchy
+
+Source: Cleveland, W. S. & McGill, R. (1984). "Graphical Perception: Theory, Experimentation, and Application to the Development of Graphical Methods." JASA.
+
+**Statement:** Humans decode visual encodings with different accuracy — position > length > angle > area > color-hue.
+
+**When load-bearing:** Every chart, metric card, comparative dataviz.
+
+**What to look for:**
+- **Holds when** quantitative comparisons use position or length (bar, line, dot); color reserved for category; no pie or 3D
+- **Breaks when** pie chart used for comparison; donut with ≥ 5 slices; color-gradient used to encode magnitude where length would work
+
+### Miller's Law
+
+Source: Miller, G. A. (1956). "The Magical Number Seven, Plus or Minus Two."
+
+**Statement:** Humans hold ~7 (±2) items in working memory. Chunking extends this.
+
+**When load-bearing:** Nav depth, form section counts, onboarding flows, step counts.
+
+**What to look for:**
+- **Holds when** navigation ≤ 7 items per level; forms chunked into ≤ 5 sections; multi-step flows ≤ 5 steps or with clear progress. (Wizard ceiling is 5, not 7: each step holds multiple fields, and each field consumes working-memory slots of its own.)
+- **Breaks when** 14-item top nav; a single-page form with 23 ungrouped fields; a checkout with 9 steps and no progress indicator
+
+### Tesler's Law
+
+Also called the Law of Conservation of Complexity. Attributed to Larry Tesler.
+
+**Statement:** Every application has an irreducible amount of complexity. The only question is who deals with it — the user, the UI, or the backend.
+
+**When load-bearing:** Feature-rich tools. Configuration-heavy flows. Anywhere you're tempted to "expose a toggle."
+
+**What to look for:**
+- **Holds when** complexity absorbed by sensible defaults, automation, or backend inference; advanced controls behind progressive disclosure
+- **Breaks when** UI exposes every backend knob; user must configure 8 things before they can accomplish the primary task; no default state, only empty forms
+
+---
+
+## Impact Tags
+
+Every finding carries exactly one impact tag. This is how a PM prioritizes:
+
+| Tag | Meaning | Example |
+|-----|---------|---------|
+| `blocks-conversion` | User cannot complete the core journey | Signup form submit silently fails on network error |
+| `adds-friction` | User completes but abandonment rate rises | Submit button has no loading state; users click 3-4x |
+| `reduces-trust` | Quality signal — affects retention | Typos in error messages; inconsistent button styles |
+| `minor-polish` | Craft layer only; no measurable user impact | Missing `tabular-nums` on a metric |
+
+Rank findings in the final output by impact tag, not by heuristic order: `blocks-conversion > adds-friction > reduces-trust > minor-polish`.
+
+---
+
+## Output Format
+
+The heuristic review outputs **exactly** this structure. Do not invent new sections. Do not merge tables. Do not drop the ranking at the end. Do not add a score, grade or pass/fail verdict.
+
+```markdown
+## Heuristic Findings
+
+| Heuristic | Element | Viewport | Finding | Impact |
+|-----------|---------|----------|---------|--------|
+| Visibility of system status | Submit button, signup form | mobile 375 | No loading state; users click 3-4x thinking nothing happened | adds-friction |
+| User control and freedom | Delete confirm dialog, project list | desktop 1280 | Confirm exists but there is no undo after it lands | reduces-trust |
+| Consistency and standards | Cancel button, billing modal | desktop 1280 | Cancel on the right here, on the left in every other modal | minor-polish |
+| Flexibility and efficiency | Invoice list, 200+ rows | desktop 1280 | No bulk select | adds-friction |
+| Error recovery | Error banner, checkout | mobile 375 | "Something went wrong" with no ID, no retry | blocks-conversion |
+
+## Design Law Findings
+
+| Law | Element | Viewport | Detail | Impact |
+|-----|---------|----------|--------|--------|
+| Fitts's Law | Primary CTA, pricing card | mobile 375 | 32px tall; expected ≥ 44px | adds-friction |
+| Doherty Threshold | Save button, settings | desktop 1280 | Spinner for ~1.8s with no optimistic state | adds-friction |
+| Tesler's Law | First-run form | desktop 1280 | 8 required config fields before the first action | reduces-trust |
+
+## Top findings (ranked by impact)
+
+1. Error recovery (blocks-conversion) — "Something went wrong" banner strands users in checkout on mobile; no ID, no retry, no support path
+2. Fitts's Law (adds-friction) — primary CTA on the pricing card is 32px on mobile; raise to ≥ 44px
+3. Doherty Threshold (adds-friction) — save feels broken on desktop; add optimistic UI
+4. Flexibility and efficiency (adds-friction) — bulk select missing on the 200+ row invoice list
+5. Visibility of system status (adds-friction) — signup submit has no loading state on mobile
+```
+
+**Notes on output:**
+- Use the short name for each heuristic (not the verbose Nielsen title). The heuristic is unambiguous from context.
+- The `Top findings` list is a rank, not a re-listing. Include only findings at `reduces-trust` or worse. Cap at 5.
+- Laws and heuristics that hold up get no row. If you want to say what is working, say it in one line after the ranking, not in the tables.

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, labelled in the subject's own vocabulary (its real parts, stages or sections), not a generic figure label. 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**: a common generated look (see [tells-2026-11.md](tells-2026-11.md)); use only when the content calls for emphasis, never as a habit
+- **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
+- **Section labels**: small, tracked-out uppercase labels are a common generated look ([tells-2026-11.md](tells-2026-11.md)); use one only when it names a real section the way the subject would, otherwise sentence case
+
+### 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: a face chosen for the brief's subject
+Body:             a readable sans or serif chosen for the same brief
+Code/technical:   a monospace, only if the content has code
+```