agemon 0.1.0 → 6.3.0

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

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

@@ -0,0 +1,155 @@
+# Loop Engine
+
+Run→evaluate→fix one→re-evaluate→stop. A loop is not a review pass — it iterates until its stop condition holds or the budget runs out. A stop condition is an objective check (items present, values found by search) or a count of severity-ranked findings; a general impression never passes it. A loop NEVER hard-depends on a renderer, NEVER auto-installs anything, and ALWAYS degrades with an explicit notice when visual evaluation is unavailable. The budget is non-negotiable: when it is exhausted the engine stops and reports, even if the stop condition has not been met.
+
+---
+
+## Engine Contract
+
+Every preset declares all five fields. None is optional.
+
+| Field | Allowed values | Description |
+|-------|---------------|-------------|
+| `target` | `new-build` \| `existing-surface` \| `user-screenshot` | The artifact being evaluated |
+| `lens` | one or more reference file paths / sections | Reference content that drives evaluation |
+| `gate` | `checklist-all-green` \| `zero-critical` \| `zero-off-system` | Stop condition: an objective check or a severity-finding count, never an overall impression |
+| `renderer` | `required` \| `none` | Renderer dependency level — `required` degrades to code-only if unavailable; `none` means static analysis only (always available) |
+| `budget` | integer 1–5 (default 3, hard cap 5) | Maximum iterations allowed |
+
+---
+
+## The Loop
+
+The agent executes this numbered procedure for every iteration:
+
+1. **Read** the target AND the brief's §6 (learned constraints = override registry). Brief §6 overrides preset gates; the a11y/correctness floor is never overridden.
+2. **Detect renderer** (see Renderer Detection Ladder below) and emit the pre-flight cost notice — preset name, budget, "will run up to N iterations; each iteration runs one full evaluate → fix → re-evaluate cycle." MUST emit before any iteration begins.
+3. **Evaluate** the target through the preset's lens → produce a severity-ranked findings list.
+4. **Select ONE highest-impact fix.** Ranking: Critical before Major; tiebreaker within the same tier = earlier-numbered finish-bar pass / earlier-listed state in the state-design lattice / earlier-cited finding in the brief; for token-consistency: within the same tier, apply layer order — primitive token violations before semantic, semantic before component. MUST NOT apply more than one fix per iteration.
+5. **Apply** the selected fix.
+6. **Re-evaluate** — re-run the stop-condition check on the updated state.
+7. **Stop** when the gate passes OR the iteration count reaches the budget, whichever comes first. On budget exhaustion: STOP, print final gate state, and list all open findings as "Unresolved within budget:". MUST NOT silently extend the budget.
+
+**Anti-thrash rule:** a fix that introduces a new violation is caught in the NEXT iteration — no inline re-validation. It counts against the budget.
+
+---
+
+## Renderer Detection Ladder
+
+Probe in this order; stop at the first match:
+
+1. `playwright` / `@playwright/test` / `puppeteer` in `package.json` devDependencies → use it.
+2. Existing e2e / visual harness file (`playwright.config.*`, `cypress.config.*`, `cypress/`, `.storybook/test-runner*`) → use it.
+3. Agent-browser tool present in the current agent session → **announce before launch** ("I will invoke agent-browser for visual evaluation — proceeding unless you say stop") then use it.
+4. `npx playwright screenshot` — **OPT-IN ONLY.** Present as a choice; NEVER auto-run. If the user declines → rung 5.
+5. **NONE** → degrade to code-only reasoning. Emit verbatim:
+
+> "renderer: none — evaluating code only; visual rendering unverified. Findings cover structure, tokens, and code-level anti-slop signals. Confidence: partial."
+
+---
+
+## Honesty / Confidence Contract
+
+Every loop report MUST state:
+
+- **Renderer tier** used (rung number from the detection ladder above).
+- **Whether visual evaluation occurred.**
+- **Confidence level** — `full` (renderer present), `partial` (code-only or renderer degraded).
+- **Iteration count vs budget** — e.g., "2 of 3 iterations used."
+- **Unresolved findings** — any finding still open when the loop stops.
+
+**`target = user-screenshot` → EVALUATE-ONLY mode:**
+- Produce a severity-ranked findings report.
+- MUST NOT apply any fixes.
+- MUST NOT run fix iterations.
+- MUST NOT claim the gate passed or failed.
+- MUST state: "Target is a screenshot — findings reported; no fix iterations run."
+
+**`visual-anti-slop` with renderer=none** is the SAME preset degraded — not a separate preset. Report the gate as "partial — visual rendering unverified."
+
+---
+
+## Anti-thrash + Budget Rules
+
+- **One fix per iteration.** The ranking above is mandatory — it prevents oscillation.
+- The iteration counter is tracked in the report ("iteration 2 of 3").
+- Budget exhausted → STOP, print final gate state + "Unresolved within budget:" list. The user must explicitly raise the budget; the engine MUST NOT auto-extend.
+- Brief §6 constraints override preset gates. The a11y/correctness floor is never overridden by brief constraints.
+
+---
+
+## Preset Catalog
+
+| Preset | target | lens | gate | renderer | maps to |
+|--------|--------|------|------|----------|---------|
+| `visual-anti-slop` | new-build \| existing-surface | core-rules.md Anti-Slop Test + finish-bar.md Pass 1 + Pass 9 | zero-critical (Major: absent or explicitly user-confirmed — no self-accept, silence ≠ accepted) | required — degrades to code-only | pre-ship pass |
+| `state-coverage` | new-build \| existing-surface | state-design.md lattice, knob-gated to CRAFT_LEVEL | checklist-all-green (all required states present) | none | `/agemon-design harden` |
+| `token-consistency` | new-build \| existing-surface | tokens.md 3-layer contract + core-rules.md Anti-Slop Minor items | zero-off-system | none (static scan) | `/agemon-design tokens` audit |
+
+---
+
+## visual-anti-slop — eliminate AI-template signals until the gate passes
+
+**Lens:** core-rules.md Anti-Slop Test (Critical + Major items) + `finish-bar.md` Pass 1 (hierarchy) + Pass 9 (pixel honesty).
+**Gate:** all Critical Anti-Slop items absent AND all Major items absent or explicitly user-confirmed. A Major is "accepted" ONLY when the user explicitly confirms it (during pre-flight or mid-loop); absent explicit confirmation it stays OPEN and counts against the gate. No self-accept, no "not found on re-eval = accepted".
+**Renderer:** required — degrades to code-only (partial confidence) if unavailable. The gate is reported as "partial — visual rendering unverified" when renderer=none. MUST NOT claim full pass on visual criteria without a renderer.
+**Highest-impact ranking:** Critical Anti-Slop findings first; within Major, earlier-numbered finish-bar pass wins.
+**Example run:**
+
+- Pre-flight: "visual-anti-slop, budget 3, will run up to 3 iterations; each iteration runs one full evaluate → fix → re-evaluate cycle."
+- Iter 1: Critical — identical card grid detected → refactor to asymmetric layout. Re-evaluate.
+- Iter 2: Major — uniform border-radius on all elements → vary by element role. Re-evaluate.
+- Gate passes (0 Critical, 0 unaccepted Major). Stop at 2/3 iterations.
+
+---
+
+## state-coverage — iterate until all required states are present
+
+**Lens:** `state-design.md` state lattice, knob-gated to CRAFT_LEVEL (per state-design.md lattice — see the CRAFT_LEVEL table there for the full threshold definition).
+**Gate:** all required states (per the CRAFT_LEVEL knob, as defined in state-design.md) present as explicit designs or stubs.
+**Renderer:** none — code analysis only; always available.
+**Highest-impact ranking:** missing required states ordered by position in the state-design lattice (idle → loading → empty → error → partial → success → conflict → offline).
+**Example run:**
+
+- Pre-flight: "state-coverage, budget 3, will run up to 3 iterations; each iteration runs one full evaluate → fix → re-evaluate cycle."
+- Iter 1: CRAFT_LEVEL 6 → required: idle/loading/empty/error/success. Missing: empty, error. Highest-impact = empty (lattice position). Stub empty state with copy + CTA. Re-evaluate.
+- Iter 2: Missing: error. Stub error state with cause + retry. Re-evaluate.
+- Gate passes (all required states present). Stop at 2/3 iterations.
+
+---
+
+## token-consistency — iterate until zero off-system values remain
+
+**Lens:** `tokens.md` 3-layer contract (per tokens.md 3-layer contract — see that file for canonical layer definitions) + core-rules.md Anti-Slop Minor items for hardcoded values.
+**Gate:** zero off-system values — any color, radius, or spacing value not drawn from the project's token system.
+**Renderer:** none — static code scan; always available.
+**Highest-impact ranking:** Critical token violations (raw hex colors) before Major (arbitrary radii, magic spacing); tiebreaker = order of appearance in the file.
+**Example run:**
+
+- Pre-flight: "token-consistency, budget 3, will run up to 3 iterations; each iteration runs one full evaluate → fix → re-evaluate cycle."
+- Iter 1: Off-system values found: `#3B82F6` (hex color), `border-radius: 6px` (magic value). Highest-impact = hex color → replace with `var(--accent)`. Re-evaluate.
+- Iter 2: Remaining: `border-radius: 6px` → replace with `var(--radius-sm)`. Re-evaluate.
+- Gate passes (zero off-system values). Stop at 2/3 iterations.
+
+---
+
+## Choosing / Adding a Preset
+
+| Use case | Preset |
+|----------|--------|
+| Surface looks AI-generated; fix visual slop | `visual-anti-slop` |
+| Edge-case states are missing (loading, error, empty) | `state-coverage` |
+| Hardcoded colors, radii, or spacing bypass the token system | `token-consistency` |
+
+**Preset block template** (drop-in for future presets — mirror this file's style):
+
+```
+## <preset-name> — <one-line intent>
+**Lens:** <reference file(s) + exact section(s)>
+**Gate:** <binary pass condition>
+**Renderer:** <none | required | gated — degrades to code-only at lower confidence>
+**Highest-impact ranking:** <tier order + tiebreaker>
+**Example run:** <3-5 line trace: iter 1 finding→fix, iter 2 …, stop reason>
+```
+
+Add the new preset row to the Preset Catalog table above. All five template fields are required.

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

@@ -0,0 +1,98 @@
+# Metadata
+
+Page metadata quality — correctness of what's already being emitted, not SEO strategy. For keyword strategy, content structure, or ranking tactics, defer to an SEO skill; this file is about the mechanical contract between what a page claims about itself and what actually ships.
+
+---
+
+## When to Read This
+
+Read when a task touches `<title>`, `<meta>` tags, canonical URLs, Open Graph / Twitter Card tags, structured data (JSON-LD), or favicons — building a new page template, auditing an existing site, or wiring up a metadata API in a framework (Next.js `generateMetadata`, Remix `meta`, etc.).
+
+---
+
+## Social Sharing Tags
+
+Any page that could get pasted into Slack, X, LinkedIn, or iMessage needs `og:title`, `og:image`, and `twitter:card` present at minimum. Drop one and the platform improvises — usually a generic card, sometimes a broken one.
+
+```html
+<meta property="og:title" content="Page title" />
+<meta property="og:description" content="One or two sentences." />
+<meta property="og:image" content="https://example.com/og/page-slug.png" />
+<meta property="og:url" content="https://example.com/page-slug" />
+<meta name="twitter:card" content="summary_large_image" />
+```
+
+Tags existing in the page source proves nothing about how a card actually renders. Crawlers for these platforms can't resolve `localhost`, so the only real test is pasting a live deployed link into the destination (or its dedicated preview debugger) and reading what comes back.
+
+---
+
+## Deterministic Metadata
+
+Nothing feeding a title, description, or JSON-LD block should trace back to an unstable input — no `Math.random()`, no `Date.now()`, no client-only state read before first paint.
+
+Two distinct failures follow from ignoring this:
+- **Hydration mismatch** — the server-rendered value and the client's first pass disagree, and the framework flags it.
+- **A stuck preview cache** — social platforms fetch a URL's metadata once and cache the result. If that single fetch happened to capture a randomized or time-sensitive value, every future share of that link shows the same wrong preview, with no external way to force a refresh.
+
+Pull metadata only from route params, fetched content, or build-time constants.
+
+---
+
+## Identity Consistency
+
+Title, description, canonical URL, and `og:url` all describe one page — a contradiction between any two of them (a title selling one thing, a description written for another) is a bug, not a stylistic quirk.
+
+Settle on the page's single canonical form up front — trailing slash or not, `www` or not, query params stripped or kept — and reuse that exact string in the canonical tag, the sitemap, internal links, and the Open Graph URL. Letting any of these drift from the others leaves crawlers guessing which version is authoritative, which can split ranking signal across what should be one page.
+
+---
+
+## Non-Production Indexing
+
+Preview deployments, staging environments, and branch builds ship with search indexing turned off:
+
+```html
+<meta name="robots" content="noindex, nofollow" />
+```
+
+Wire this to the environment itself — a build-time flag, not a checkbox a person remembers to tick — because the one deploy someone forgets is exactly the one that matters. An indexed staging URL then competes with the real page in search results and can surface content before it's meant to be public.
+
+---
+
+## Structured Data (JSON-LD)
+
+Structured data should restate facts that already exist elsewhere on the page, not add new ones for the crawler's benefit.
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Actual product name",
+  "offers": {
+    "@type": "Offer",
+    "price": "49.00",
+    "priceCurrency": "USD"
+  }
+}
+```
+
+Don't fabricate organization details that aren't published anywhere, a price the product doesn't actually charge, a review count nobody left, or a `ratingValue` backed by zero reviews. Search engines diff structured data against the visible page and penalize the mismatch — and beyond the penalty, a made-up rating is a false claim presented to users as fact. No reviews yet means the `AggregateRating` block gets omitted, not filled with placeholder numbers.
+
+---
+
+## Favicons & Touch Icons
+
+A single `favicon.ico` doesn't cover the surfaces that request icons — browsers, home-screen bookmarks, and OS task switchers each ask for a different size, and any size that isn't supplied falls back to an unstyled default glyph.
+
+```html
+<link rel="icon" href="/favicon.ico" sizes="32x32" />
+<link rel="icon" href="/icon.svg" type="image/svg+xml" />
+<link rel="apple-touch-icon" href="/apple-touch-icon.png" sizes="180x180" />
+<link rel="manifest" href="/site.webmanifest" />
+```
+
+---
+
+## Cross-References
+
+- `accessibility.md` — semantic structure that structured data and screen readers both depend on.
+- `responsive.md` — `og:image` dimensions and safe-area concerns for share-preview screenshots.