Self-evolving second brain with 35 AI skills, 10 agents, and people CRM. Closed-loop harness: a V-model verification lifecycle where the worker never grades its own homework. Plus paired anti-slop design skills for marketing and product UI. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex.
Python agent-loopagent-pluginsagent-skillsagenticai-agentsclaude-codeclosed-loopcursorgarry-tangbraingstackknowledge-managementloop-engineeringobsidianpeople-crmproductivitysecond-brainself-evolvingverification-harnessworker-agents
feat: paired anti-slop design skills (v3.8.1)
Huy Tieu935e6c464ecc
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 3cee4be..64704dc 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "cog-second-brain",- "version": "3.8.0",- "description": "Self-evolving second brain with 31 AI agent skills, 10 agents, and people CRM. Closed-loop harness release: a V-model verification lifecycle (spec to evidence, criterion-traced checkpoints), read-only verifier agents that observe artifacts instead of trusting worker summaries, risk lanes, multi-session ultragoals with a north-star acceptance gate, plus craft skills for writing and visual work. Inspired by Garry Tan's gstack specialist sessions, gbrain knowledge patterns, and dwarves-kit closed-loop execution. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex, and any markdown-reading agent.",+ "version": "3.8.1",+ "description": "Self-evolving second brain with 33 AI agent skills, 10 agents, and people CRM. Closed-loop harness release: a V-model verification lifecycle (spec to evidence, criterion-traced checkpoints), read-only verifier agents that observe artifacts instead of trusting worker summaries, risk lanes, multi-session ultragoals with a north-star acceptance gate, plus craft skills for writing, visual work, and a paired anti-slop design system for marketing and product UI. Inspired by Garry Tan's gstack specialist sessions, gbrain knowledge patterns, and dwarves-kit closed-loop execution. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex, and any markdown-reading agent.","author": {"name": "Huy Tieu","url": "https://github.com/huytieu"@@ -52,7 +52,11 @@"verifier-agents","retrospective","no-ai-slop",- "data-viz"+ "data-viz",+ "design-systems",+ "ui-ux",+ "anti-slop",+ "product-design"],"category": "productivity","tags": [@@ -225,6 +229,16 @@"name": "daily-journal","path": ".claude/skills/daily-journal/SKILL.md","description": "A passive daily work journal the agent keeps for you - appends entries after meaningful work, runs a guided reflection on request"+ },+ {+ "name": "taste-skill",+ "path": ".claude/skills/taste-skill/SKILL.md",+ "description": "Anti-slop frontend skill for landing pages, portfolios, and redesigns - reads the brief, states a design read, and ships interfaces that do not look templated"+ },+ {+ "name": "product-ui-taste",+ "path": ".claude/skills/product-ui-taste/SKILL.md",+ "description": "Anti-slop skill for dense product surfaces (dashboards, tables, forms, wizards, admin consoles) - frame-first, correct at every edge case real data produces"}],"metadata": {@@ -248,12 +262,13 @@"Read-only verifier agents (task-verifier, integration-verifier) that observe artifacts, not worker summaries","Risk lanes: ceremony scales with blast radius instead of applying uniformly","Ultragoals: multi-session goals with per-phase verification and a final north-star acceptance gate",- "Cross-model flagship gate - a different model family catches a different error class"+ "Cross-model flagship gate - a different model family catches a different error class",+ "Paired anti-slop design skills: taste-skill owns marketing surfaces, product-ui-taste owns dense product UI"],"requirements": {"obsidian": "Recommended for markdown file management","git": "Optional but recommended for version control and safe updates",- "claudeCode": "Recommended for the full 31-skill native experience",+ "claudeCode": "Recommended for the full 33-skill native experience","kiro": "Optional - ships 7 native core powers","geminiCli": "Optional - ships 7 native core commands","agentsMd": "Universal fallback surface for Codex and other markdown-reading agents"@@ -265,7 +280,7 @@"validation": "Run ./scripts/validate-agent-surface.sh before publishing or after framework updates"},"directoryStructure": {- ".claude/skills": "31 Claude Code skills (full surface)",+ ".claude/skills": "33 Claude Code skills (full surface)",".claude/agents": "10 agent definitions - 6 workers plus 4 read-only verifiers",".claude/roles": "7 role packs for personalized skill and integration recommendations",".kiro/powers": "7 Kiro powers (core workflows)",@@ -283,16 +298,16 @@},"skillArchitecture": {"type": "agent-skills",- "skills": 31,+ "skills": 33,"workerAgents": 10,"rolePacks": 7,"invocation": "model-invoked","progressiveDisclosure": true,"nativeSurfaces": {- "claudeCode": 31,+ "claudeCode": 33,"kiro": 7,"geminiCli": 7,- "agentsMd": 31+ "agentsMd": 33},"description": "Self-contained skills with worker delegation and a read-only verification layer, full Claude Code surface, core native Kiro/Gemini surfaces, and AGENTS.md as the universal fallback"}diff --git a/.claude/skills/product-ui-taste/SKILL.md b/.claude/skills/product-ui-taste/SKILL.mdnew file mode 100644index 0000000..c5b5926--- /dev/null+++ b/.claude/skills/product-ui-taste/SKILL.md@@ -0,0 +1,653 @@+---+name: product-ui-taste+description: Anti-slop skill for PRODUCT UI - dashboards, data tables, forms, multi-step flows, settings, list/detail, app shells. The agent reads the surface, budgets the frame first, and ships dense interfaces that are correct at every edge case (overflow, long labels, empty/error/loading states, i18n expansion, keyboard/a11y). House-system-first; maps to Carbon/Polaris/Atlaskit/Fluent/Primer/Material3/Radix-shadcn/Ant. The counterpart to taste-skill, which owns landing/portfolio/marketing.+---++# product-ui-taste: Anti-Slop Skill for Dense Product Surfaces++> Dashboards, data tables, forms, wizards, settings, list/detail, admin consoles, app shells. NOT landing pages, portfolios, or marketing (that is `taste-skill`). NOT charts (that is `dataviz`). NOT native mobile.+> Every rule is **contextual and mechanical**. It fires from the surface you are building, not automatically. Read the surface, budget the frame, then pull only what fits.+> **Companion contract:** `taste-skill` explicitly hands off "dashboards / dense product UI / data tables / multi-step forms" to "the right tool." This skill is that tool. If a brief is half marketing and half product (a landing page with an embedded live dashboard), use `taste-skill` for the hero/marketing sections and this skill for the product surface. Never run both on the same component.++---++## 0. PRODUCT READ (Read the Surface Before Anything Else)++Marketing UI lives on first impression. Product UI lives on the **hundredth** use, under real data, by someone doing a job. The slop failure mode is different: not "templated aesthetic," but **prototype that dies on contact with real data** - a table that scrolls the whole page sideways, a button that truncates its own label, a single grey "no data" box reused for three different situations, a form that clears itself when the user fat-fingers one field.++### 0.A Read these signals first+1. **Surface type** - the single most important read. One of: **index/table** (list of records to scan, filter, select), **detail/record** (one entity, its fields and related data), **dashboard/overview** (KPIs + widgets + a table or two), **form/settings** (input and configuration), **multi-step flow/wizard** (a sequential task), **console/observability** (logs, metrics, deploys), **feed/messaging** (stream of items). Most real screens are a composition of two or three (index + detail drawer; dashboard + drill-in table).+2. **Data shape and volume** - how many rows at p95, how wide is a row, are cells uniform or ragged, is the data live/streaming or static, can a field be empty/null/very-long.+3. **Density need** - a trader's cockpit and a consumer settings page are both "product UI" and want opposite densities. Read: expert-daily-driver (compact, keyboard-first) vs. occasional-consumer (comfortable, forgiving).+4. **Consequence level** - is the primary action informational (view), reversible (rename, move), or destructive/irreversible (delete, deploy, charge a card). This drives confirmation, focus defaults, and autosave eligibility.+5. **Who is the user and what are they permitted to do** - roles, read-only viewers, plan/license tiers. Product UI has states marketing UI never has: permission-denied, read-only, plan-locked (Section 6.G). Read this now, not after building the happy path.+6. **Existing system** - is there already a Carbon/Fluent/Polaris/Atlaskit app, or a house token set? Product UI is almost never greenfield. Match the host system before importing taste.++### 0.B Output a one-line "Product Read" before generating+Before any code, state: **"Reading this as: a \<surface type> for \<user> at \<density>, \<data volume>, consequence \<level>, built on \<design system | house tokens | none>."**++Examples:+- *"Reading this as: an index+detail-drawer for internal ops at compact density, ~2k rows (virtualize), consequence reversible, built on the house system (Table + side-panel inspector)."*+- *"Reading this as: a settings/form surface for end customers at comfortable density, low volume, consequence mixed (billing = destructive), built on the house system's form layout."*++### 0.C The anti-default that matters most: rows, not cards+The single fastest way to make a product screen look like an AI prototype is to **wrap every record in a Card with a Badge**. Dense data that the user scans, filters, sorts, or selects belongs in **rows** (Table for columnar, List/Item for single-line), edge-to-edge, with dividers and 32-40px row height. Card is a **widget container** (KPI tile, chart panel, settings group, gallery entry), never a list-item wrapper. [Material3 lists; Carbon] If your first instinct on a list of records is a Card grid, stop and re-read this line.++### 0.D If the brief is ambiguous, ask ONE question, then proceed+The one question worth asking is almost always about **data volume or consequence** (they change the architecture): "roughly how many rows at the high end?" or "is this action reversible?" Everything else, infer from the Product Read and state your assumption. Do not interview.++### 0.E Anti-default discipline+The model's defaults for product UI are: Card-soup, fixed-width `<table>` that overflows the page, `disabled` submit button as the only validation, one generic empty state, `z-index: 9999`, and a full-page spinner on every load. Each has a specific correct replacement below. When you catch yourself reaching for one, that is the signal to open the matching section.++---++## 1. THE THREE DIALS (Core Configuration)++After the Product Read, set three dials. Unlike taste-skill (VARIANCE / MOTION / DENSITY tuned for expressive marketing), product dials are tuned for **information work**. Motion is deliberately near-absent in product UI; it is feedback, not decoration.++* **`DENSITY: 2`** - 1 = comfortable/consumer, 2 = standard, 3 = compact/cockpit. Drives row height, padding scale, font size, and whether you offer a density switcher.+* **`DATA_COMPLEXITY: 2`** - 1 = simple list (plain Table/List), 2 = sortable+filterable+selectable table, 3 = enterprise grid (frozen columns, virtualization, column management, live data).+* **`CONSEQUENCE: 2`** - 1 = informational/read, 2 = reversible mutations, 3 = destructive/irreversible/financial. Drives confirmation defaults, autosave eligibility, error tone, and how loud "unsaved changes" gets.++**Baseline: `2 / 2 / 2`** (a standard SaaS product table with a detail view). Override from the Product Read.++### 1.A Dial inference+| Signal | DENSITY | DATA_COMPLEXITY | CONSEQUENCE |+|---|---|---|---|+| "internal admin / ops tool / expert daily driver" | 3 | 2-3 | 2 |+| "enterprise data console / grid / analytics" | 3 | 3 | 2 |+| "consumer settings / account / onboarding" | 1 | 1 | 1-2 |+| "SaaS product dashboard (default)" | 2 | 2 | 2 |+| "billing / delete / deploy / permissions surface" | match | match | 3 |+| "observability / logs / live metrics" | 3 | 3 | 1 |++### 1.B Use-case presets+| Preset | DENSITY | DATA_COMPLEXITY | CONSEQUENCE | Frame |+|---|---|---|---|---|+| Internal admin tool | 3 | 2 | 2 | AppShell + SideNav, inspector on select |+| SaaS product dashboard | 2 | 2 | 2 | AppShell + SideNav or TopNav + TabList |+| Enterprise data console | 3 | 3 | 2 | AppShell + SideNav, full-height grid |+| Consumer settings/account | 1 | 1 | 1-2 | AppShell + settings template (nav + form panels) |+| Multi-step wizard | 1 | 1 | 2-3 | Centered column, stepper, no distracting chrome |++### 1.C How the dials drive output+Use these exact names as global variables in reasoning. `DENSITY` gates row height and the density-switcher decision (Section 10.A). `DATA_COMPLEXITY` gates how far down the table deep-dive (Section 7) you go. `CONSEQUENCE` gates Sections 6.G, 8.E, 8.F, 9.A. Do not invent aliases.++---++## 2. PRODUCT ARCHETYPE → DESIGN SYSTEM MAP++Product UI is almost never hand-rolled CSS. Pick the foundation from the host app first, the archetype second. **One system per app.** Do not mix Carbon with Fluent, or drop shadcn into a Polaris tree.++### 2.A House system first (discover, do not guess)+If the app already has a design system, that system wins, and your first job is to **find out what it actually ships** rather than assuming. Most mature systems already solve the dense-surface problems this skill is about, so you rarely drop to raw CSS. Guessing at component names and props is the single most common way an agent produces code that looks right and does not compile.++Before writing UI, resolve each of these against the host system's real API (its CLI, its docs site, or its `.d.ts` files):++| Need | What to look for | How to resolve it |+|---|---|---|+| Full-page shell | An app-shell primitive plus its nav slots | System docs "layout" or "app shell" page |+| Multi-pane tool / inspector | A layout + side-panel pair, not two floated divs | Docs "layout" page; check whether the panel is resizable |+| Columnar data | The system's Table and its sort/select/pagination plugins | Component reference, not a blog example |+| Sticky / frozen columns | A dedicated hook or plugin (most systems ship one) | Search the docs for "sticky" or "frozen" before hand-rolling |+| Resizable columns | A column-resize hook | Same |+| Pagination footer | Table pagination + page-size control | Component reference |+| Search + filter toolbar | A toolbar/filter component distinct from plain search | Component reference |+| Single-line records | A List / Item pair | Component reference |+| Empty region | An EmptyState component | Component reference |+| Status / metadata | A status indicator distinct from Badge | Token/status docs |++**Workflow, always:** find the closest page or block template the system already ships, study its layout skeleton, then read the real props for every component you use. **Never invent props.** Prefer the system's own layout components over raw `<div>`s so spacing stays on the system's scale. Use design tokens for every value (`var(--color-*)`, spacing tokens), never raw hex or px. Reserve Badge for counts and enumerated states; status belongs on a status indicator.++**The house-system bridge (resolve the tension):** the CSS mechanics in Sections 5-10 (scroll ownership, `position:sticky` headers, frozen-column offsets, z-index tiers, `min-width:0`) are the **contract a mature system's hooks already satisfy** under the hood. Inside such a system, reach for the hook or plugin first, because a real sticky-column hook gives you the offset, the solid background, and the shadow divider correctly. Drop to the raw CSS contract only (a) to verify the system did it right when something bleeds through, or (b) when you are outside a design system entirely. Never hand-roll a sticky column with inline styles inside a system Table when the hook exists.++### 2.B External systems (match the host, or pick by archetype)+| Archetype / brief | Reach for | Why |+|---|---|---|+| IBM-style enterprise analytics, dense grids | `@carbon/react` + `@carbon/styles` | Most mature data-density + 2x-grid + empty/loading patterns [carbon] |+| Microsoft / enterprise SaaS, DataGrid | `@fluentui/react-components` (v9) | Official Fluent 2, Overflow primitives, tokens [fluent] |+| Atlassian / Jira-style product | `@atlaskit/*` + `@atlaskit/tokens` | Semantic spacing tokens chosen by meaning [atlaskit] |+| Merchant/admin, resource lists | Polaris (`@shopify/polaris` or web components) | IndexTable, four-states philosophy, error content [polaris] |+| GitHub-style devtool chrome | `@primer/react` / `@primer/css` | PageLayout landmarks, Blankslate, Truncate [primer] |+| Adaptive/canonical layouts, consumer-ish | `@material/web` + Material 3 tokens | Window-size classes, list-detail/supporting-pane [material3] |+| Own-the-code lean internal tool | Radix Primitives + shadcn/ui + TanStack Table | Headless a11y primitives, you own styling [radix, tanstack] |+| Enterprise React data-dense fast | Ant Design or Mantine + Mantine React Table | Batteries-included Table/Form [ant, mantine] |+| Lean keyboard-first (Linear/Vercel vibe) | Radix/shadcn + custom tokens | Density + command palette + restraint [linear, vercel] |++**Honesty rule:** if the app is one of these, use the official package and its Table/Form/Dialog. Do not recreate Carbon's data table in raw CSS. Do not import a system's tokens then override 90% of them.++---++## 3. FRAME-FIRST APP-SHELL ARCHITECTURE++**Budget the frame in pixels before writing one line of content.** Real applications are built top-down: pick the shell, name its regions, give each an explicit px budget, decide its container policy and responsive behavior, then fill. Content-first layout (write sections, wrap each in a Card) produces a padded scroll column that reads as a prototype. [most systems' layout docs]++### 3.A Pick the shell+- **AppShell** (header and/or side nav) - the default full-page product frame.+- **Layout + LayoutContent + LayoutPanel** - multi-pane tools: explorers, consoles, master-detail with an inspector.+- **Plain content column** - a single form, a settings section, a wizard.++### 3.B Region px budgets (memorize these)+| Region | Budget |+|---|---|+| Side nav | 240-280px |+| Icon rail (collapsed nav) | 64-72px |+| Detail / inspector panel | 340-420px (resizable 320-480) |+| Filter / facet rail | 220-260px |+| Row height | 32px compact / 40px standard / 48px comfortable [dense systems budget 32-40; Carbon ships 5 relative tiers, no fixed px] |+| Header / top nav | 48-64px (common app-bar convention) |++### 3.C Landmark regions (do not conflate them)+Name every region with a real landmark and know the difference [primer PageLayout]:+- **Header** - full width, top, app chrome.+- **Content** - the primary region, flexes to fill.+- **Pane** - a secondary region **beside** Content, content-height only. Use for an inspector or supporting info.+- **Sidebar** - **full-height** navigation, distinct from Pane. Never build a "sidebar" that is really a content-height pane, or a "pane" that is really full-height nav.+- **Footer** - full width, bottom (status bar, pagination context).++### 3.D Canonical layouts (recognize and scaffold) [material3]+- **List-detail** - list on the left, selected record on the right. Below ~1024px, detail overlays or becomes a separate route.+- **Supporting-pane** - primary content ~2/3, supporting pane ~1/3.+- **Feed** - a single scrolling stream (rows/bubbles, no cards in the stream).+- **Master-detail with inspector** (the tool backbone) - selecting a row opens a **fixed-width LayoutPanel inspector**, it does not navigate away. Add `resizable`. Overlay it below ~1024px instead of compressing Content.++### 3.E App-shell chrome that marketing UI never has+- **Workspace / org switcher** - almost every SaaS shell needs one, anchored top of the side nav or header-left, showing the current tenant's name/avatar. On click, a dropdown (not a modal) lists workspaces with a search field once there are 8+, a "recent workspaces" group, and a "create/join" action at the bottom. It switches context (data scope), it is not a nav destination. Keep it one element; never scatter tenant choice into the nav list. Persist the last-active workspace per user.+- **Global command palette** (Cmd/Ctrl-K) - for DATA_COMPLEXITY >= 2 keyboard-first tools, this is the fastest navigation. Recognize it as a first-class shell affordance, not a nice-to-have.+- **Background-job / async status tray** - when the app kicks off concurrent long-running operations (imports, exports, deploys), a persistent notification tray (a header icon with a count badge opening a dropdown of jobs) beats a modal per job. Each job row shows a determinate progress bar, a cancel affordance, and terminal success/error with a result link. Carbon's rule: for waits over a few minutes, let the user leave and notify on completion. Never block the whole UI on one background job. [carbon loading]++### 3.F Container policy per region (Cards vs Rows, decided per archetype)+| Archetype | Container policy |+|---|---|+| Tracker / work tool (issues, tickets, CRM) | Rows only. Grouped edge-to-edge lists, zero cards. |+| Console / observability | Card grid for dashboard widgets; Table for everything else. |+| Messaging / feed | Rows and bubbles. No cards in the stream. |+| Media / gallery | Card grid (ClickableCard) + dense metadata rows in detail. |+| Settings / forms | FormLayout sections; Card only to group dangerous/billing actions. |++Banned: a Card per list item (card soup), stacked full-width Cards as page structure, nested Cards, Badge as decoration.++---++## 4. LAYOUT HARD RULES (Failing any of these ships broken work)++* **SCROLL OWNERSHIP (the #1 product-UI layout bug).** Exactly **one** wrapper owns each scroll axis (`overflow:auto`). The page `<body>` must **never** scroll horizontally. A wide table scrolls inside its own container, not by pushing the whole app sideways. Sticky headers use `position:sticky` scoped to that scroll wrapper, **never** `position:fixed` to the viewport. [carbon, ant table-scroll, tanstack] If two nested elements both scroll the same axis, you have a bug.+* **Every sticky element needs a bounded-height ancestor.** `position:sticky` silently does nothing if no ancestor establishes a scroll boundary. A sticky table header requires the table's scroll container to have a real max-height. [css mechanics]+* **min-width:0 on flex children that hold text.** A flex/grid child defaults to `min-width:auto`, which refuses to shrink below content size, so `text-overflow:ellipsis` silently no-ops and the child pushes the layout wider instead. Any truncating text inside a flex row needs `min-width:0` on the text-holding child. This is the most common reason "my ellipsis isn't working." [overflow-truncation]+* **Responsive contract declared up front, per region.** Before filling, write which regions collapse, overlay, or drop at which breakpoints. No "Tailwind will handle it" assumptions. Nav collapses to an icon rail or off-canvas MobileNav; the inspector overlays below ~1024px; a wide table keeps horizontal scroll rather than reflowing columns.+* **Breakpoints: use size classes, not device names.** Compact / medium / expanded (Material 3) or Carbon's exact 2x-grid breakpoints (320 / 672 / 1056 / 1312 / 1584, 8px mini-unit, 16px padding, 32px gutter) as a fallback grid. [material3, carbon 2x-grid]+* **Container queries for reusable components.** A card or panel that appears in a wide Content region and a narrow Pane must respond to **its own** width, not the viewport. Use `container-type` + `@container`, not viewport media queries, for anything that renders in more than one region width. [joshwcomeau, responsive-layout]+* **Sidebar collapse = off-canvas or icon-rail, not in-place shrink.** Collapsing a 260px nav to 180px just cramps it. Collapse to a 64-72px icon rail (with tooltips) or slide it off-canvas with a persistent reopen strip. Persist which panes were shown across a resize/fold so the user does not lose context.+* **Density is a layout MODE, not a CSS zoom.** Offer at least the density presets the DENSITY dial calls for as a real switch (row height + padding token swap), not a browser-zoom hack. [i18n-a11y-density, carbon 5 row heights]+* **Never hardcode a fixed width on a text container.** Badges, buttons, table headers, chips, tags must be auto-layout (flex/grid, hug-contents) so text can reflow or expand. A fixed-width text container clips under real data and under translation (Section 10.B).+* **Tabular numbers for compared numbers.** Any column or list of numbers the user compares vertically uses `font-variant-numeric: tabular-nums` so digits align. Proportional digits in a metrics column is a Tell.++---++## 5. OVERFLOW & TRUNCATION CATALOG (Deep-Dive)++Product UI is where real strings arrive: a 90-character file path, a German button label, a customer name that is one word or forty. Truncation is a scalpel, not a default.++### 5.A The never-truncate list (mandatory)+**Never truncate primary/identifying content**: titles, entity names, unique IDs, error and validation messages, page headers, button labels. Truncation is for **secondary/supplementary** content only (descriptions, secondary metadata, breadcrumb middles). [carbon overflow, primer truncate] If an identifying string is too long, wrap it, give it more space, or use middle-truncation that preserves both ends (for paths/IDs) - never a trailing ellipsis that hides the part that distinguishes two records.++### 5.B Every truncated string needs a real full-text fallback+A hover-only `title` tooltip is **not** an accessible fallback: it fails keyboard-only users, touch users, and speech-recognition users. Provide the full text on focus as well as hover, or expandable inline, or in the detail view. [carbon, primer]++### 5.C Long button labels (mandatory, a signature product-UI Tell)+**Never truncate a button label.** Size the button to its content ("hug contents") with a `min-width` floor for tap-target accessibility. If the label is long (or translated), wrap to at most 2 lines before you ever truncate, and re-evaluate the label copy. A button reading "Save chang..." is broken work. Icon-only buttons need an `aria-label` and a tooltip. [overflow-truncation, i18n]++### 5.D Single-line ellipsis recipe+`overflow:hidden; text-overflow:ellipsis; white-space:nowrap;` **plus** `min-width:0` on every flex ancestor between the text and the scroll/row container (Section 4). Without the `min-width:0` chain, the CSS is inert.++### 5.E Multi-line clamp recipe (`-webkit-line-clamp`)+All four properties together or none work: `display:-webkit-box; -webkit-line-clamp:N; -webkit-box-orient:vertical; overflow:hidden;`. **Never put padding on the clamped element itself** - the clamp math ignores padding and text bleeds. If you need padding, wrap the clamp in a padded parent, or use a fixed-height fallback (`line-height * N`). [css-tricks line-clampin]++### 5.F Content edge cases: counts, big numbers, missing data (mandatory)+Real data is 0, 1, or 1,000,000 - design all three, not just the demo's "3."+- **Zero / one / many (pluralization):** every count string handles 0, 1, and N with correct grammar - "0 items," "1 item," "24 items," never "1 items" or "24 item." Use an ICU/plural-aware formatter, never string concatenation; some languages have up to 6 plural forms. The zero case usually routes to an empty state (Section 6.C), not "0 items" sitting in a full layout.+- **Very large / very precise numbers:** abbreviate for scannability in dense contexts (1.2k, 3.4M, 1.1B) but keep the exact value reachable on hover/focus and in the detail view; **never abbreviate a number the user must act on precisely** (an invoice total, an account balance). Locale-aware grouping (1,234.56 vs 1.234,56), tabular-nums for compared columns (Section 4), and a consistent threshold before switching to abbreviation.+- **Missing / null / not-applicable (general rule, not just table cells):** a null field renders a consistent, quiet placeholder ("Not set," "-," "Unknown") that is visually distinct from an empty string and from zero. Decide per field whether null means "not set yet" (invite input), "not applicable" (explain briefly), or "hidden by permission" (Section 6.G) - three different placeholders, never one blank that reads as a render bug.+- **Long unbroken tokens** (URLs, hashes, file paths, IDs with no spaces): use middle-truncation that keeps both ends, or `overflow-wrap:anywhere`, never a trailing ellipsis that hides the distinguishing tail, and never let the token blow out its column width.++### 5.G Column-header and chrome overflow+- **Column headers**: wrap to 2 lines, then truncate with a tooltip carrying the full header. [carbon]+- **Breadcrumbs**: collapse the middle to an ellipsis/overflow-menu, keep first and last. [carbon overflow]+- **Toolbars / action bars / tabs**: use priority-plus overflow (Fluent Overflow): declare a visible-priority order and a `minimumVisible` floor, move the rest into a "More" menu, render in reverse DOM order so the first item wins. [fluent]+- **Long free content blocks**: "Show more / Show less" for expandable prose, "Load more" for lists (Section 7.D).++---++## 6. STATE MATRIX (Deep-Dive)++Every data surface has more than a happy path. Design the full matrix at **three granularities**: page, component/region, and field. The slop failure is reusing one grey box for every non-happy state.++### 6.A The four base states, always designed together+For any region that loads data, design **ideal / loading / empty / error** before you ship the ideal. [polaris four-states, nngroup]++### 6.B Loading timing thresholds (mandatory)+- **< 1s**: show nothing. A flash-and-vanish skeleton is worse than a beat of stillness.+- **1-10s, full-page/region load**: a **skeleton that mirrors the real layout shape** (the actual rows/fields it will become), never a frame-only grey box, never a spinner for structured content. [nngroup skeleton, carbon loading]+- **> 10s, or unknown-length work** (uploads, downloads, conversions, deploys): a **determinate progress bar**, never an indeterminate spinner or skeleton. For multi-minute work, let the user leave and notify on done. [carbon]+- **Background refresh of already-shown data**: keep the old content visible with a subtle inline indicator. **Never re-blank** cached content to a spinner/skeleton on refresh.++### 6.C Empty states are three distinct states (mandatory)+Never reuse one empty component/message across these:+1. **Never-used-yet (first run)** - onboarding tone: what this is + a primary CTA to create the first record. [primer empty-states, pencilandpaper]+2. **Filtered/searched to nothing** - "no results for X," with a clear-filters action. The data exists; the filter is the cause.+3. **Zero-as-a-win** - "inbox zero," "no alerts." Positive tone, no guilt CTA.+[carbon empty-states, atlaskit empty-state] For tiny tiles/side-panels, a centered text-only empty state is the exception to "mirror the layout."++### 6.D Error states are never empty states+A load failure is **always** an ErrorState, never an EmptyState. Error copy is specific, plain-language, actionable (what to do next), and carries an error code/id for support. Route all of them through one shared ErrorState component so tone and layout stay consistent; never ship a bare "An error occurred." [polaris error-messages, nngroup]++### 6.E Field and inline states+Fields have their own micro-states: pending async validation (Section 8.D), inline error, success confirmation, saving/saved (autosave, Section 8.E). Do not let a field-level failure silently no-op.++### 6.F Partial, stale, and offline states (mandatory to consider)+Between "loaded" and "failed" live the states real networks produce:+- **Partial load / partial failure:** when a composite view loads and one widget fails, fail **that widget in place** (its own inline ErrorState + retry), never blank the whole page for one failed panel. A dashboard where one broken tile kills every tile is a bug.+- **Stale / cached / refreshing:** show last-known-good data with a subtle "updating" indicator and a "last updated <time>" stamp; never re-blank to a skeleton on a background refresh (Section 6.B). On refresh failure, keep the stale data and surface a non-blocking "couldn't refresh, showing data from <time>" notice.+- **Offline / disconnected:** detect connection loss, show a persistent non-modal banner, disable or **queue** mutations, and reconcile on reconnect. Never let a user type into a form that silently cannot save.+- **Optimistic update contract:** if you render a mutation before the server confirms, you MUST have a rollback path - restore the prior value and show a clear error if the write fails. An optimistic update with no rollback is a data-integrity Tell.++### 6.G Permission and plan states (product-UI-only, mandatory to consider)+Marketing UI has no concept of these; product UI lives on them:+- **Permission-denied / role-gated**: decide **disabled vs. hidden** deliberately. Hide an action the user can never have; disable (with a reason on hover/focus) an action they could have with a role change. Never show a dead control with no explanation.+- **Read-only mode**: present the same layout with inputs rendered as static values and a clear "read-only" affordance, not greyed-out inputs that look broken.+- **Plan/license-locked**: a locked-feature affordance ("Upgrade to unlock") is a distinct state with its own component - visible, explained, with an upgrade path - not a disabled button. [Keep it consistent with whatever precedent the host app already sets.]++---++## 7. DATA TABLE DEEP-DIVE (The Hardest Product Surface)++Gate depth by DATA_COMPLEXITY. A simple list needs 7.A-7.B; an enterprise grid needs all of it. **Inside a design system, use its `Table` plus the system's plugins/hooks; the mechanics below are the contract those hooks satisfy, and your guide when you are outside one.**++### 7.A Scroll ownership and sticky header (mandatory)+One wrapper owns both axes (`overflow:auto`) with a bounded height; the page never scrolls sideways (Section 4). Sticky header via `position:sticky; top:0` **scoped to that wrapper**. [carbon, ant table-scroll]++### 7.B Frozen / pinned columns (mandatory recipe)+`position:sticky` + explicit `left:0` (or `right:0`) offset + `z-index >= 10` (above the scrolling body) + a **solid, non-transparent background that also covers hover and selected-row states** + an **inset `box-shadow` divider, never a CSS `border`** (borders disappear or double-render under sticky scroll). Miss the solid background and the scrolling content bleeds through the frozen column. [ant, mantine-react-table column-pinning, tanstack]++### 7.C Virtualization (DATA_COMPLEXITY 3)+Virtualize past ~100-200 rows. Required DOM shape: **two wrappers** - outer = viewport-height scrollable, inner = full virtual-content height (a spacer). **Never size the `<table>` element itself to the full virtual height** - it distorts row heights and collapses the sticky header (which cannot escape a too-short parent). [tanstack virtual #640] Do not attach per-row style objects or per-row menu instances during virtual render (perf death); use `columnResizeMode:"onEnd"` unless memoized. [ant, mantine]++### 7.D Pagination vs. infinite scroll vs. load-more (decision tree)+- **Paginate** once an index exceeds ~50 items (concrete Polaris cutoff), and always for "find a specific item / compare distant items / inspect the top few" tasks. [polaris, smashingmagazine]+- **Infinite scroll**: only for exploratory, homogeneous, endless feeds - **never** for search results or comparison tasks. If used, ship `history.pushState()` so the back button restores scroll position (>90% of implementations get this wrong). On mobile, load one larger flat batch (15-30 items), never chunk-lazy-load mid-scroll (fetches during active scroll are unreliable). [nngroup infinite-scrolling, baymard]+- **Load-more button**: the safe middle for finite-but-long lists; user controls the fetch.++### 7.E Selection, bulk actions, and selection persistence+- Row selection supports Shift-click range and select-all. Distinguish "select all N (across pages)" from "select all on this page" in copy. [polaris]+- **Selection persistence (a classic enterprise correctness bug):** preserve selected-row **IDs** across pagination, sort, and filter changes; do not silently drop the selection when the page changes. Show a running "N selected" count that survives navigation.+- During an active bulk operation, disable per-row actions to prevent conflicting mutations.+- **Toolbar action cap: 5 visible primary actions**, then overflow to a menu. [polaris]++### 7.F Filtering, faceting, and search (distinct from each other)+- **Search** (free text) and **filter** (structured predicates) are different controls; do not merge them into one box silently. Match each filter control to its data type (date range, enum multi-select, numeric range). [data-table-mechanics; most systems ship a toolbar-filter component]+- **Applied-filter chips**: show active filters as a removable chip row above the table with a "Clear all," plus (for many facets) a faceted sidebar. This is the now-standard Jira/Linear/Notion pattern; without the chip row the user cannot see or undo what is filtering their data.++### 7.G Cell content+Cells hold ragged real data. Truncate secondary cells per Section 5 (with focus-reachable full text), never identifying cells. Right-align numeric columns and use tabular-nums (Section 4). Empty cell = a consistent "not set" placeholder (an em-dash is banned; use "-" or "Not set"), never a blank that looks like a render bug.++---++## 8. FORMS, VALIDATION & MULTI-STEP FLOWS (Deep-Dive)++### 8.A Label placement+Top-aligned labels by default (fastest to scan, best for localization and mobile). Right-aligned labels only for dense enterprise forms where vertical space is scarce. Left-aligned only to deliberately slow the user down on a careful task. Never right-align labels on a localized product (expansion breaks the column). [lukew web-form, nngroup web-form-design]++### 8.B Validation timing+Validate on **blur** and on **submit**, not on every keystroke of an incomplete value (do not scream "invalid email" at the first character). The exception is a live positive helper like password-strength. Show inline errors next to the field **and** an aggregate error summary at the top on submit, never only one of the two. [nngroup errors-forms, polaris inline-error]++### 8.C Never disable Submit as the only signal (mandatory)+For forms with 5+ fields, **never** make a disabled Submit the only feedback - the user cannot tell what is missing. Let them submit, then show the aggregate error count and focus the first error. A disabled Submit is acceptable only on trivial (<3 field) forms. **Always preserve user input after a failed submit** - never clear the form. [forms-flows, nngroup]++### 8.D Async / remote field validation+Debounce it, **and** cancel superseded requests with `AbortSignal` - an uncancelled slow response can overwrite a newer, correct result (username-availability race). [forms-flows]++### 8.E Autosave (gate by CONSEQUENCE)+- Autosave **per logical field-group**, never whole-form-on-every-keystroke.+- **Never autosave** password, visibility/permission, confidentiality, or financial-impact fields - those require explicit manual confirm (CONSEQUENCE 3).+- Trigger on blur + ~3s after the last keystroke. Show "Saving..." then "Saved <relative time>."+- A failed autosave gets a **persistent** (non-auto-dismissing) toast with retry, never a silent failure.++### 8.F Multi-step flows / wizards+- The step indicator must map to the **real** steps; completed steps are clickable to go back. No fake "Stage 1 / Stage 2" labels - name the actual step. [taste-skill tell parity]+- Fix wizard abandonment by cutting **field count**, not by adding steps. Do not inject mid-flow upsells. [baymard checkout-linear]+- Keep the flow linear; a branching wizard needs a visible map.++### 8.G Destructive / irreversible confirmation (CONSEQUENCE 3, mandatory)+Confirmation dialogs for delete/deploy/charge **default keyboard focus to the safe action (Cancel)**, not the destructive one. Use `role="alertdialog"`, `aria-modal="true"`, and `aria-describedby` pointing at the warning text. For high-consequence deletes, require typing the resource name to enable the destructive button. On close, return focus to the element that opened the dialog (or the next logical element). [w3 alertdialog, radix dialog]++---++## 9. NAVIGATION, OVERLAYS & LAYERING (Deep-Dive)++### 9.A Dialogs / modals+Focus-trap while open, return focus on close, close on Escape, close on overlay click only when non-destructive. `Dialog.Title` and `Dialog.Description` are **never omitted** even if visually hidden (screen readers announce them). [radix dialog, w3 dialog-modal]++### 9.B Toasts / notifications+Default ~5000ms, **pause on hover and focus**, swipe-dismiss threshold ~50px, dismissible manually. Distinguish foreground announcements (user's own action succeeded) from background ones (something changed) for screen-reader priority. Never put a destructive-confirm inside a toast. [radix toast]++### 9.C Menus, dropdowns, tabs, comboboxes+Full keyboard contract: arrow-key navigation, Home/End, type-ahead, roving tabindex (Section 10.D). Tab moves **between** a composite widget and the next content; arrows move **within** it. Menu/tab items that should stay keyboard-reachable use `aria-disabled`, not native `disabled` (which removes them from the tab order). [radix, w3 grid]++### 9.D The z-index / stacking-context system (mandatory, replaces ad-hoc z-index)+- **Assign wide numeric gaps per tier**, defined once as tokens, e.g. base 0, sticky 100, dropdown 1000, sticky-header 1050, overlay/drawer 1100, modal 1200, popover 1300, toast 1400, tooltip 1500. Never hand-tune a single z-index in isolation; change it against the whole scale. Ad-hoc `9999`/`99999` is a Tell.+- **Enumerate every stacking-context trigger** before debugging a layering bug: `position:fixed/sticky` with a z-index, `opacity < 1`, `transform` / `filter` / `will-change` naming a context property, `contain`, `container-type`, `isolation:isolate`, top-layer elements. [mdn stacking-context]+- **Nested stacking contexts are atomic**: a huge z-index on a deeply nested element **cannot** out-rank a shallow ancestor's sibling. If a menu clips behind a header, the fix is the ancestor context, not a bigger number.+- **Overlays layer by open-order**, not static per-type constants: the last-opened overlay wins. Use a layering manager / the platform top-layer (`<dialog>`, popover API) where available.++---++## 10. DENSITY, I18N & ACCESSIBILITY (Deep-Dive)++### 10.A Density as a first-class mode+Offer >= 3 density presets (comfortable / standard / compact) as a real switch that swaps row-height and padding tokens, not a scaled-down zoom. [i18n-a11y-density] Carbon ships 5 row heights; pick the set your DENSITY dial needs.++### 10.B Internationalization text-expansion budget (mandatory)+Design containers with headroom for translation, because English is one of the shortest UI languages:+- German: **+30-40%** typical, up to ~70% worst case.+- French / Russian / Spanish: +20-25%.+- Finnish: up to +100% (doubling).+- CJK: contracts, not expands.+Never hardcode fixed-width text containers (Section 4). Use flex/grid so text reflows instead of clipping. Pseudo-localization (wrap strings in accented padding) is a fast smoke test that catches ~80% of expansion bugs. [crowdin, i18n-a11y-density]++### 10.C RTL+Mirror **directional** icons only (back/forward arrows, chevrons, progress direction). **Never** mirror universal icons (clock, play, checkmark, logos). Numerals keep LTR shaping even inside RTL text. The primary action button moves to the left (the natural end of an RTL reading scan). Progress bars fill right-to-left. [crowdin]++### 10.D The ARIA grid keyboard contract (mandatory for any custom grid/table with focusable cells)+- **Roving tabindex**: exactly one cell has `tabindex="0"`, all others `-1`; the grid container itself is never a tab stop.+- Arrow keys move between cells, **boundary-clamped** (no wrap at row/column edges).+- **Home/End** move within the current row; **Ctrl+Home / Ctrl+End** jump to the grid's first/last cell.+- **Page Up/Down** only in scrollable grids (move ~5 rows).+[w3 grid data-grids] If you use a real design-system Table (Carbon, Fluent, Polaris, Ant), this is handled - do not reinvent it. Reach for the contract only when hand-building a grid.++### 10.E Cross-cutting a11y floors+- Touch targets >= 44-48px (touch), >= 24px (dense desktop). [material3 accessibility]+- `:focus-visible`, never a bare `:focus` that flashes on mouse click; never remove focus outlines without replacing them.+- Every icon-only control has an `aria-label`.+- Locale-aware number/date/currency formatting; never ship ambiguous `01/02/2025`.++---++## 11. ONBOARDING & PROGRESSIVE DISCLOSURE++Dense products overwhelm on first run. Reveal power progressively; earn complexity.++**Progressive disclosure (the default mechanic):**+- Keep advanced controls (bulk edit, column management, saved views, API/webhook config) one interaction away (a "More," an expander, a settings popover), not all on screen at once. Linear's principle: simple to start, grows more powerful. [linear]+- **Rule of thumb: >7 controls in a region is the disclosure trigger.** Group the primary 3-5 actions inline and overflow the rest; surface advanced settings behind a labeled expander, never a mystery-meat gear with no tooltip.+- Disclosure is per-surface, not global: do not hide a control the user just used two clicks ago.++**First-run (mandatory):**+- First run is the **"never-used" empty state** (Section 6.C.1), not a blank grid or a spinner. It states what this surface is in one line and points at the single first action ("Create your first project"), not a menu of ten.+- Seed with sample/demo data only if it is clearly labeled and one-click removable; never leave fake "Acme Inc" rows the user cannot tell from real data.++**Coach marks, tours, checklists (banned unless dismissible):**+- Any coach mark, product tour, or onboarding checklist MUST be skippable on step 1 and dismissible permanently; dismissal persists per user across sessions (never re-fire a dismissed tour). A tour that cannot be skipped, or a checklist with no close affordance, is a **Tell**.+- Max one active tour at a time; never stack a coach mark on top of a modal.+- Tours point at real controls in the real UI; never a fake highlighted screenshot. Return the user to a usable state on exit, not a dead end.+- Segment: returning/experienced users and invited teammates skip the first-run flow; do not re-onboard someone joining an existing populated workspace.++**Empty-to-productive path:** every empty state's CTA leads somewhere that actually creates value in <=3 steps. An onboarding checklist that just links to docs is decoration.++---++## 12. CONTEXT-AWARE PROACTIVITY (Canonical Skeletons to Recognize)++When the Product Read matches one of these, scaffold the whole skeleton, not a fragment:+- **Index/table page**: heading + toolbar (search, filters, primary action, density) + applied-filter chips + Table (sticky header, selection) + pagination footer + the three empty states + error state.+- **List-detail / master-detail**: list region + inspector LayoutPanel that overlays below ~1024px + "nothing selected" empty state.+- **Settings page**: section nav + FormLayout panels + autosave-or-save-bar + a Card only around the danger zone.+- **Multi-step wizard**: real stepper + linear steps + per-step validation + a review step + a non-destructive exit.+- **Dashboard/overview**: KPI tile row (Cards) + widget grid + one or two drill-in Tables (rows).+- **Admin console with bulk actions**: table + selection persistence + bulk action bar (capped at 5 + overflow) + confirmation dialogs.++### 12.A Block Library (reference implementations)+Full component implementations live in the host system, not duplicated here: reach them via your host system's template/skeleton command or its docs (Appendix B). Three high-value skeletons are worked below because they encode the contracts most often gotten wrong; treat them as the canonical shape, adapt to the host system.++**Block 1 - Index + detail-drawer (frame-first):**+```tsx+// Budget the frame first: nav 256 | table flex | inspector 380+<AppShell sideNav={<SideNav>{/* nav */}</SideNav>} contentPadding={0}>+ <Layout>+ <LayoutContent>+ <ToolbarTableFilter /* search + status/priority filters + overflow (cap 5) */ />+ {/* applied-filter chips row + Clear all (Section 7.F) */}+ <Table+ plugins={[useTableStickyColumns, useTableColumnResize /*, pagination */]}+ /* selection persists by row id across page/sort/filter (Section 7.E) */+ />+ {/* pagination footer; three empty states + ErrorState wired per Section 6 */}+ </LayoutContent>+ <LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider isScrollable>+ {selected ? <DetailFields item={selected} /> : <EmptyState title="Nothing selected" />}+ </LayoutPanel>+ </Layout>+</AppShell>+// Below ~1024px: LayoutPanel overlays Content; SideNav becomes MobileNav.+```++**Block 2 - Table scroll + sticky header + frozen column (the CSS contract a system's hooks satisfy):**+```css+/* ONE wrapper owns both scroll axes; page body never scrolls sideways (Section 4). */+.table-scroll { overflow: auto; max-block-size: 70vh; } /* bounded height => sticky works */+.table-scroll thead th { position: sticky; inset-block-start: 0; z-index: 20; }+/* Frozen first column: sticky + offset + z + SOLID THEME-TOKEN bg + shadow divider, never border */+.col-frozen {+ position: sticky; inset-inline-start: 0; z-index: 10;+ background: var(--color-surface); /* must also cover hover/selected rows */+ box-shadow: inset -1px 0 0 var(--color-border); /* not border-right (double-renders on scroll) */+}+```++**Block 3 - Truncation contract (single-line + multi-line):**+```css+.cell { min-inline-size: 0; } /* required on EVERY flex ancestor or ellipsis no-ops */+.cell .text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }+.clamp { /* all four props; NO padding on this node */+ display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden;+}+```++---++## 13. PERFORMANCE & ACCESSIBILITY GUARDRAILS+- Table load/filter response should feel instant; past ~1s show optimistic/loading feedback, past the thresholds in 6.B escalate.+- Enterprise-grid perf: no per-row style/menu object allocation on render; scoped auto-sizing; `columnResizeMode:"onEnd"` unless memoized; virtualize past ~100-200 rows.+- Motion in product UI is **feedback only**: state transitions, focus movement, a row entering/leaving. No decorative scroll animation, no marquees, no parallax. Respect `prefers-reduced-motion` for everything.+- Core Web Vitals still apply: CLS < 0.1 (skeletons must reserve the real dimensions so content does not jump), INP < 200ms on interactions.++---++## 14. DARK MODE+Token-driven, one theme locked per app (same discipline as taste-skill Section 8/11: no region flips to inverted mid-app). Use the host system's semantic layer tokens (`var(--color-*)`, Carbon `$layer`/`$border-subtle`, etc.), never hardcoded greys. Test tables, frozen columns (the solid background must be a **theme token**, or it bleeds in dark mode), overlays, and focus rings in both modes. Set the theme once at the shell root, never per-section.++---++## 15. PRODUCT-UI AI TELLS (Forbidden Patterns)++Distinct from taste-skill's landing-page tells. These are the signatures of a model faking a product screen. Hard bans unless the brief genuinely demands one.++- **Card soup**: every record wrapped in a Card + Badge. Use rows. (Section 0.C)+- **Fixed-width `<table>` that scrolls the page sideways**: no scroll-owning wrapper. (Section 4)+- **Truncated button label** ("Save chang..."). Size to content. (Section 5.C)+- **Truncated identifying content** (names/IDs/errors) with a hover-only `title`. (Section 5.A-B)+- **`disabled` Submit as the only validation** on a 5+-field form. (Section 8.C)+- **One generic empty state** reused for first-run AND filtered-empty AND load-failure. (Section 6.C-D)+- **"An error occurred"** with no cause, action, or code. (Section 6.D)+- **Skeleton that never resolves**, or a frame-only grey box that does not mirror the real layout. (Section 6.B)+- **Full-page spinner on a cached background refresh** (re-blanking data the user was reading). (Section 6.B)+- **Sticky/frozen column with a transparent background** (content bleeds through on scroll). (Section 7.B)+- **Ad-hoc z-index** (`9999`, `99999`) instead of a tiered token scale. (Section 9.D)+- **Fixed-width badges/labels/tabs** that clip under German/Finnish expansion. (Sections 4, 10.B)+- **Native `disabled` on menu/tab items** that should stay keyboard-reachable (use `aria-disabled`). (Section 9.C)+- **Badge as decoration** and **status dots spammed on every row** (status only, sparingly).+- **Motion for show** in a work tool (decorative scroll/hover animation). (Section 13)+- **Fake step labels** ("Stage 1 / Stage 2"), fake precise numbers, "Jane Doe"/"Acme" placeholder data in a shipped screen.+- **Em-dash (`—`) anywhere visible.** Banned in headers, cells, labels, empty/error copy, tooltips, and as the "not set" cell placeholder. Use a hyphen (`-`). This is the single most-violated Tell; zero tolerance. (taste-skill Section 9.G, house rule)++---++## 16. REFERENCE VOCABULARY (Names the Agent Should Know)+App shell / PageLayout (Header / Content / Pane / Sidebar / Footer) · canonical layouts (list-detail / supporting-pane / feed) · master-detail + inspector · IndexTable / Resource List / DataGrid / Table · frozen (pinned) columns · virtualization · roving tabindex · stacking context · container query · skeleton screen (shape-mirroring) · Blankslate / EmptyState / ErrorState · Overflow / priority-plus · applied-filter chips / faceted search · alertdialog · optimistic vs. pessimistic update · density mode · pseudo-localization · command palette · workspace switcher · job/status tray.++---++## 17. REDESIGN PROTOCOL (Auditing an Existing Dense Screen)+Before touching visual style, audit for the correctness bugs that matter more than aesthetics:+1. **Scroll ownership** violations (page scrolls sideways; nested double-scroll).+2. **Truncation on primary content**; hover-only fallbacks.+3. **Missing state differentiation** (one empty box for three states; no error state; skeleton missing).+4. **Frozen-column bleed-through**; transparent sticky backgrounds.+5. **z-index ad-hockery**; layering bugs from nested stacking contexts.+6. **No i18n buffer**; fixed-width text containers.+7. **Keyboard/a11y gaps**: no roving tabindex, bare `:focus`, icon buttons without labels, disabled submit as only signal.+Fix these first. Only then apply the density/token/visual polish. Preserve the host design system; do not swap Carbon for shadcn as a "redesign."++---++## 18. RELATIONSHIP TO taste-skill + OUT OF SCOPE+- **Hand off to `taste-skill`**: marketing hero sections, landing pages, portfolios, editorial, illustration-heavy brand surfaces. If a screen is half product, half marketing, split it: taste-skill for the marketing sections, this skill for the product surface. Never run both on one component.+- **Hand off to `dataviz`**: chart/graph authoring (color, encoding, axes). This skill covers the table and the dashboard frame around the charts, not the chart internals.+- **Out of scope**: native mobile (iOS/Android) app chrome beyond responsive web (tab bars, native nav) - a different skill's job; flag it, do not silently approximate. Realtime collab primitives (presence, cursors, OT) - different problem class.++---++## 19. FINAL PRE-FLIGHT CHECK++**Run every box. If any fails, the surface is not done.**++- [ ] **Product Read** stated (Section 0.B one-liner)?+- [ ] **Dials** (DENSITY / DATA_COMPLEXITY / CONSEQUENCE) set from the read, not silently baseline?+- [ ] **Frame budgeted in px** before content; shell + landmark regions named (Header/Content/Pane/Sidebar not conflated)?+- [ ] **Rows not cards** for dense data; Card only for widgets; no card soup, no nested cards?+- [ ] **Scroll ownership**: exactly one wrapper per axis, page never scrolls horizontally, sticky scoped to the wrapper?+- [ ] **min-width:0** on every truncating flex text child?+- [ ] **No truncated primary content** (names/IDs/errors/headers) and **no truncated button labels**; every truncation has a focus-reachable full-text fallback?+- [ ] **Line-clamp recipe** complete (all 4 props, no padding on the clamped node)?+- [ ] **Four states designed** (ideal/loading/empty/error) for every data region?+- [ ] **Loading thresholds**: <1s nothing, skeleton mirrors layout, >10s determinate progress, cached refresh never re-blanks?+- [ ] **Three distinct empty states** (first-run / filtered-empty / zero-as-a-win); load failure is an ErrorState with cause + action + code?+- [ ] **Partial/stale/offline states** handled (one failed widget fails in place; cached refresh never re-blanks; offline queues or blocks with notice; optimistic updates have a rollback path)?+- [ ] **Content edge cases**: counts pluralized (0/1/N, no "1 items"); big numbers abbreviated with exact value reachable and never abbreviated where precision matters; missing data has a consistent placeholder distinct from zero/empty?+- [ ] **Permission/plan states** considered (disabled-vs-hidden, read-only, plan-locked) where roles/tiers exist?+- [ ] **Table**: scroll-owning wrapper + bounded height; sticky header; frozen columns have solid theme-token background + inset-shadow divider + z-index; virtualization uses the two-wrapper DOM?+- [ ] **Pagination vs infinite** chosen correctly (paginate >50 / for search; infinite only for feeds with pushState + mobile flat batch)?+- [ ] **Selection persists** across page/sort/filter; bulk toolbar capped at 5 + overflow?+- [ ] **Applied-filter chips** row present when filters exist; search and filter are distinct controls?+- [ ] **Forms**: top labels default; validate on blur+submit; inline + summary errors; input preserved on failed submit; no disabled-submit-as-only-signal on 5+ fields?+- [ ] **Async validation** debounced + AbortSignal-cancelled?+- [ ] **Autosave** per group, not for password/permission/financial fields, with Saving/Saved states + persistent retry on failure?+- [ ] **Destructive confirm** focuses the safe action, `role=alertdialog`, returns focus on close?+- [ ] **Dialogs** trap+return focus, Escape-close, Title/Description present; **toasts** pause on hover, dismissible?+- [ ] **z-index** from a tiered token scale (no 9999); layering bugs traced to stacking contexts, not bigger numbers?+- [ ] **i18n buffer** on every text container (+30-40% DE); no hardcoded fixed-width text; tabular-nums on compared numbers?+- [ ] **RTL** mirrors directional icons only (if RTL in scope)?+- [ ] **Keyboard/a11y**: roving tabindex on custom grids, `:focus-visible`, icon buttons labelled, `aria-disabled` not `disabled` on keyboard-reachable menu items, 44px/24px targets?+- [ ] **Density switch** offered where DENSITY calls for it (mode swap, not zoom)?+- [ ] **Dark mode** one theme locked, frozen-column background is a theme token, tested in both modes?+- [ ] **House system**: props discovered from real docs (nothing invented), no `<div>` for layout, tokens only, Badge for counts only, status via a status indicator?+- [ ] **No product-UI Tells** from Section 15; **zero em-dashes** anywhere visible?+- [ ] **One design system** per app (no Carbon + Fluent mixed)?++If a single box cannot be honestly ticked, fix it before delivering.++---++# APPENDICES - Source-Backed Reference Material++## Appendix A - Install / CLI per system++```bash+# House design system - resolve the real API before writing UI.+# Most systems ship a CLI or a docs site; use whichever exists.+# 1. find the closest shipped page/block template+# 2. study its layout skeleton+# 3. read real props for every component (never invent props)++# IBM Carbon+npm install @carbon/react @carbon/styles+# Microsoft Fluent UI React v9+npm install @fluentui/react-components+# Atlassian Atlaskit (per-component + tokens)+npm install @atlaskit/tokens @atlaskit/dynamic-table+# Shopify Polaris+npm install @shopify/polaris+# GitHub Primer React+npm install @primer/react styled-components+# Radix Primitives + shadcn/ui + TanStack Table+npm install @radix-ui/react-dialog @radix-ui/react-toast @tanstack/react-table+npx shadcn@latest add table dialog+# Material Web (Material 3)+npm install @material/web+# Ant Design / Mantine + Mantine React Table+npm install antd+npm install @mantine/core @mantine/form mantine-react-table+```++## Appendix B - Canonical sources (real URLs, gsearch-verified)++Consolidated primary sources:++**Frame / layout**+- Carbon 2x grid: https://carbondesignsystem.com/elements/2x-grid/usage/+- Primer PageLayout: https://primer.style/product/components/page-layout+- Material 3 canonical layouts: https://m3.material.io/foundations/adaptive-design/canonical-layouts+- Material 3 list-detail: https://m3.material.io/foundations/layout/canonical-examples/list-detail+- Material 3 supporting-pane: https://m3.material.io/foundations/layout/canonical-examples/supporting-pane+- Container queries: https://www.joshwcomeau.com/css/container-queries-unleashed/++**Overflow / truncation**+- Carbon overflow content: https://carbondesignsystem.com/patterns/overflow-content/+- Primer Truncate: https://primer.style/product/components/truncate/+- CSS line-clamp: https://css-tricks.com/line-clampin/++**State matrix**+- Polaris EmptyState: https://polaris-react.shopify.com/components/layout-and-structure/empty-state+- Carbon empty states: https://carbondesignsystem.com/patterns/empty-states-pattern/+- Carbon loading: https://carbondesignsystem.com/patterns/loading-pattern/+- Primer empty states: https://primer.style/product/ui-patterns/empty-states/+- NN/g skeleton screens: https://www.nngroup.com/articles/skeleton-screens/+- NN/g empty-state design: https://www.nngroup.com/articles/empty-state-interface-design/+- Pencil&Paper empty states: https://www.pencilandpaper.io/articles/empty-states+- Polaris error messages: https://polaris-react.shopify.com/content/error-messages++**Data table**+- Carbon data table: https://carbondesignsystem.com/components/data-table/usage/+- Polaris IndexTable: https://polaris-react.shopify.com/components/tables/index-table+- Ant table scroll: https://ant.design/docs/blog/table-scroll-ghost/+- Ant virtual table: https://ant.design/docs/blog/virtual-table/+- TanStack column sizing: https://tanstack.com/table/latest/docs/guide/column-sizing+- Mantine React Table column pinning: https://www.mantine-react-table.com/docs/guides/column-pinning+- NN/g infinite scroll: https://www.nngroup.com/articles/infinite-scrolling-tips/+- Baymard checkout linear / pagination context: https://baymard.com/blog/checkout-process-should-be-linear+- Pagination vs infinite vs load-more: https://www.smashingmagazine.com/2016/03/pagination-infinite-scrolling-load-more-buttons/++**Forms / flows**+- LukeW web form design: https://www.lukew.com/ff/entry.asp?504+- NN/g web form design: https://www.nngroup.com/articles/web-form-design/+- NN/g form errors: https://www.nngroup.com/articles/errors-forms-design-guidelines/+- Polaris inline error: https://polaris-react.shopify.com/components/selection-and-input/inline-error+- Ant / 2x form pattern: https://2x.ant.design/docs/pattern/form+- Mantine form validation: https://mantine.dev/form/validation/++**Overlays / layering / a11y**+- Radix Dialog: https://www.radix-ui.com/primitives/docs/components/dialog+- Radix Toast: https://www.radix-ui.com/primitives/docs/components/toast+- W3C ARIA alertdialog: https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/+- W3C ARIA dialog-modal: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/+- W3C ARIA grid data-grids: https://www.w3.org/WAI/ARIA/apg/patterns/grid/examples/data-grids/+- MDN stacking context: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Positioned_layout/Stacking_context++**Tokens / density / i18n**+- Atlaskit design tokens: https://atlassian.design/foundations/design-tokens+- Atlaskit spacing: https://atlassian.design/foundations/spacing+- Crowdin UI localization: https://crowdin.com/blog/best-practices-for-ui-localization+- Material 3 accessibility (targets): https://m3.material.io/components/buttons/accessibility++**Modern minimal**+- Linear method: https://linear.app/method/introduction+- Vercel design guidelines: https://vercel.com/design/guidelinesdiff --git a/.claude/skills/taste-skill/SKILL.md b/.claude/skills/taste-skill/SKILL.mdnew file mode 100644index 0000000..9b80a8e--- /dev/null+++ b/.claude/skills/taste-skill/SKILL.md@@ -0,0 +1,1208 @@+---+name: taste-skill+description: Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.+---++# tasteskill: Anti-Slop Frontend Skill++> Landing pages, portfolios, and redesigns. Not dashboards, not data tables, not multi-step product UI.+> Every rule below is **contextual**. None of it fires automatically. First read the brief, then pull only what fits.++---++## 0. BRIEF INFERENCE (Read the Room Before Anything Else)++Before touching code or tweaking dials, **infer what the user actually wants**. Most LLM design output is bad because the model jumps to a default aesthetic instead of reading the room.++### 0.A Read these signals first+1. **Page kind** - landing (SaaS / consumer / agency / event), portfolio (dev / designer / creative studio), redesign (preserve vs overhaul), editorial / blog.+2. **Vibe words** the user used - "minimalist", "calm", "Linear-style", "Awwwards", "brutalist", "premium consumer", "Apple-y", "playful", "serious B2B", "editorial", "agency-y", "glassy", "dark tech".+3. **Reference signals** - URLs they linked, screenshots they pasted, products they named, brands they're competing with.+4. **Audience** - B2B procurement panel vs. design-conscious consumer vs. recruiter scanning a portfolio. The audience picks the aesthetic, not your taste.+5. **Brand assets that already exist** - logo, color, type, photography. For redesigns, these are starting material, not optional input (see Section 11).+6. **Quiet constraints** - accessibility-first audiences, public-sector, regulated industries, trust-first commerce, kids' products. These constraints OVERRIDE aesthetic preference.++### 0.B Output a one-line "Design Read" before generating+Before any code, state in one line: **"Reading this as: \<page kind> for \<audience>, with a \<vibe> language, leaning toward \<design system or aesthetic family>."**++Example reads:+- *"Reading this as: B2B SaaS landing for technical buyers, with a Linear-style minimalist language, leaning toward Tailwind utilities + Geist + restrained motion."*+- *"Reading this as: solo designer portfolio for hiring managers, with an editorial / kinetic-type language, leaning toward native CSS + scroll-driven animation + custom typography."*+- *"Reading this as: redesign of a public-sector service site, with a trust-first language, leaning toward GOV.UK Frontend or USWDS."*++### 0.C If the brief is ambiguous, ask one question, do not guess+Ask exactly **one** clarifying question - never a multi-question dump - and only when the design read genuinely diverges. Example: *"Should this feel closer to Linear-clean or Awwwards-experimental?"*++If you can confidently infer from context, **do not ask**. Just declare the design read and proceed.++### 0.D Anti-Default Discipline+Do not default to: AI-purple gradients, centered hero over dark mesh, three equal feature cards, generic glassmorphism on everything, infinite-loop micro-animations everywhere, Inter + slate-900. These are the LLM defaults. Reach past them deliberately based on the design read.++---++## 1. THE THREE DIALS (Core Configuration)++After the design read, set three dials. Every layout, motion, and density decision below is gated by these.++* **`DESIGN_VARIANCE: 8`** - 1 = Perfect Symmetry, 10 = Artsy Chaos+* **`MOTION_INTENSITY: 6`** - 1 = Static, 10 = Cinematic / Physics+* **`VISUAL_DENSITY: 4`** - 1 = Art Gallery / Airy, 10 = Cockpit / Packed Data++**Baseline:** `8 / 6 / 4`. Use these unless the design read overrides them. Do not ask the user to edit this file - overrides happen conversationally.++### 1.A Dial Inference (design read → dial values)+| Signal | VARIANCE | MOTION | DENSITY |+|---|---|---|---|+| "minimalist / clean / calm / editorial / Linear-style" | 5-6 | 3-4 | 2-3 |+| "premium consumer / Apple-y / luxury / brand" | 7-8 | 5-7 | 3-4 |+| "playful / wild / Dribbble / Awwwards / experimental / agency" | 9-10 | 8-10 | 3-4 |+| "landing page / portfolio / marketing site (default)" | 7-9 | 6-8 | 3-5 |+| "trust-first / public-sector / regulated / accessibility-critical" | 3-4 | 2-3 | 4-5 |+| "redesign - preserve" | match existing | +1 | match existing |+| "redesign - overhaul" | +2 | +2 | match existing |++### 1.B Use-Case Presets+| Use case | VARIANCE | MOTION | DENSITY |+|---|---|---|---|+| Landing (SaaS, mainstream) | 7 | 6 | 4 |+| Landing (Agency / creative) | 9 | 8 | 3 |+| Landing (Premium consumer) | 7 | 6 | 3 |+| Portfolio (Designer / studio) | 8 | 7 | 3 |+| Portfolio (Developer) | 6 | 5 | 4 |+| Editorial / Blog | 6 | 4 | 3 |+| Public-sector service | 3 | 2 | 5 |+| Redesign - preserve | match | match+1 | match |+| Redesign - overhaul | +2 | +2 | match |++### 1.C How the Dials Drive Output+Use these (or user-overridden values) as global variables. Cross-references throughout this document refer to these exact variable names - never invent aliases like `LAYOUT_VARIANCE` or `ANIM_LEVEL`.++---++## 2. BRIEF → DESIGN SYSTEM MAP++Once you have the design read (Section 0) and dials (Section 1), pick the right foundation. Do not invent CSS for things that have an official package. Do not pretend an aesthetic trend is an official system.++### 2.A When to reach for a real design system (use official packages)+| Brief reads as… | Reach for | Why |+|---|---|---|+| Microsoft / enterprise SaaS / dashboards | `@fluentui/react-components` or `@fluentui/web-components` | Official Fluent UI, Microsoft tokens, accessibility done |+| Google-ish UI, Material-flavored product | `@material/web` + Material 3 tokens | Official, theme-able via Material Theming |+| IBM-style B2B / enterprise analytics | `@carbon/react` + `@carbon/styles` | Official Carbon, mature data-density patterns |+| Shopify app surfaces | `polaris.js` web components / Polaris React | Required for Shopify admin UI |+| Atlassian / Jira-style product | `@atlaskit/*` + `@atlaskit/tokens` | Official Atlassian DS |+| GitHub-style devtool / community page | `@primer/css` or `@primer/react-brand` | Official Primer; Brand variant for marketing |+| Public-sector UK service | `govuk-frontend` | Legally / regulatorily expected |+| US public-sector / trust-first | `uswds` | Same |+| Fast local-business / agency MVP | Bootstrap 5.3 | Boring, fast, works |+| Modern accessible React foundation | `@radix-ui/themes` | Primitives + polished theme |+| Modern SaaS where you own the components | shadcn/ui (`npx shadcn@latest add ...`) | You own the code, easy to customise; never ship default state |+| Tailwind-based modern SaaS / AI marketing | Tailwind v4 utilities + `dark:` variant | Default for indie + small team builds |++**Honesty rule:** if the brief reads as one of the systems above, install and use the **official** package. Do not recreate its CSS by hand. Do not import a system's tokens but then override 90% of them.++**One system per project.** Do not mix Fluent React with Carbon in the same tree. Do not import shadcn/ui components into a Material 3 app.++### 2.B When the brief is an aesthetic, not a system+For these directions, there is **no single official package**. Build with native CSS + Tailwind + a maintained component library. Be honest in code comments about what is borrowed inspiration vs. official material.++| Aesthetic | Honest implementation |+|---|---|+| Glassmorphism / "frosted glass" | `backdrop-filter`, layered borders, highlight overlays. Provide solid-fill fallback for `prefers-reduced-transparency`. |+| Bento (Apple-style tile grids) | CSS Grid with mixed cell sizes. No single library owns this. |+| Brutalism | Native CSS, monospace, raw borders. No library. |+| Editorial / magazine | Serif type, asymmetric grid, generous whitespace. No library. |+| Dark tech / hacker | Mono + accent neon, terminal motifs. No library. |+| Aurora / mesh gradients | SVG or layered radial gradients. No library. |+| Kinetic typography | Native CSS animations, scroll-driven animations, GSAP for hijacks. No library. |+| **Apple Liquid Glass** | Apple documents this for Apple platforms only. **There is no official `liquid-glass.css`.** Web implementations are approximations using `backdrop-filter` + layered borders + highlights. Label clearly as approximation. |++---++## 3. DEFAULT ARCHITECTURE & CONVENTIONS++Unless the design read picks a real design system (Section 2.A), these are the defaults:++### 3.A Stack+* **Framework:** React or Next.js. Default to Server Components (RSC).+ * **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component.+ * **INTERACTIVITY ISOLATION:** Any component using Motion, scroll listeners, or pointer physics MUST be an isolated leaf with `'use client'` at the top. Server Components render static layouts only.+* **Styling:** **Tailwind v4** (default). Tailwind v3 only if the existing project demands it.+ * For v4: do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin.+* **Animation:** **Motion** (the library formerly known as Framer Motion). Import from `motion/react` (`import { motion } from "motion/react"`). The `framer-motion` package still works as a legacy alias - prefer `motion/react` in new code.+* **Fonts:** Always use `next/font` (Next.js) or self-host with `@font-face` + `font-display: swap`. Never link Google Fonts via `<link>` in production.++### 3.B State+* Local `useState` / `useReducer` for isolated UI.+* Global state ONLY for deep prop-drilling avoidance - Zustand, Jotai, or React context.+* **NEVER** use `useState` to track continuous values driven by user input (mouse position, scroll progress, pointer physics, magnetic hover). Use Motion's `useMotionValue` / `useTransform` / `useScroll`. `useState` re-renders the React tree on every change and collapses on mobile.++### 3.C Icons+* **Allowed libraries (priority order):** `@phosphor-icons/react`, `hugeicons-react`, `@radix-ui/react-icons`, `@tabler/icons-react`.+* **Discouraged:** `lucide-react`. Acceptable only when the user explicitly asks for it or the project already depends on it.+* **NEVER hand-roll SVG icons.** If a glyph is missing, install a second library or compose from primitives - do not draw icon paths from scratch.+* **One family per project.** Do not mix Phosphor with Lucide in the same component tree.+* **Standardize `strokeWidth` globally** (e.g. `1.5` or `2.0`).++### 3.D Emoji Policy+Discouraged by default in code, markup, and visible text. Replace symbols with icon-library glyphs. **Override:** allow emojis only when the user explicitly asks for a playful / chat-style / social-native vibe - and even then use them sparingly with intent.++### 3.E Responsiveness & Layout Mechanics+* Standardize breakpoints (`sm 640`, `md 768`, `lg 1024`, `xl 1280`, `2xl 1536`).+* Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`.+* **Viewport Stability:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent layout jumping on mobile (iOS Safari address bar).+* **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`).++### 3.F Dependency Verification (mandatory)+Before importing ANY 3rd-party library, check `package.json`. If the package is missing, output the install command first. **Never** assume a library exists.++---++## 4. DESIGN ENGINEERING DIRECTIVES (Bias Correction)++LLMs default to clichés. Override these defaults proactively. Each rule has a context-aware override path.++### 4.1 Typography+* **Display / Headlines:** Default `text-4xl md:text-6xl tracking-tighter leading-none`.+* **Body / Paragraphs:** Default `text-base text-gray-600 leading-relaxed max-w-[65ch]`.+* **Sans font choice:**+ * **Discouraged as default:** `Inter`. Pick `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`, or a brand-appropriate serif first.+ * **Override:** Inter is acceptable when the user explicitly asks for a neutral / standard / Linear-style feel, or when the brief is a public-sector / accessibility-first site.+* **Pairings to know:** `Geist` + `Geist Mono`, `Satoshi` + `JetBrains Mono`, `Cabinet Grotesk` + `Inter Tight`, `GT America` + `IBM Plex Mono`.++* **SERIF DISCIPLINE (VERY DISCOURAGED AS DEFAULT):**+ * Serif is **very discouraged as the default font for any project.** "It feels creative / premium / editorial" is NOT a reason to reach for serif. The agent's default mental model that "creative brief = serif" is the single most-tested AI tell in production rounds.+ * **Serif is only acceptable when ONE of these is explicitly true:**+ - The brand brief literally names a serif font, OR+ - The aesthetic family is genuinely editorial / luxury / publication / manuscript / heritage / vintage AND you can articulate why this specific serif fits this specific brand+ * For everything else (creative agency, design studio, modern brand, premium consumer, portfolio, lifestyle), **default sans-serif display** (Geist Display, ABC Diatype, Söhne Breit, Cabinet Grotesk Display, Migra Sans, GT Walsheim, Inter Display, PP Neue Montreal). Sans display fonts are not "boring" — they are the default for the same reason black is the default in fashion.+ * **EMPHASIS RULE (related):** When you want to emphasize a word within a headline (the kinetic "and `spatial` design" type move), use **italic or bold of the SAME font**. Do NOT inject a random serif word into a sans headline (or vice versa) just to add visual interest. Mixed-family emphasis is amateur. Italic/bold emphasis in the same family is the right move.+ * **Specifically BANNED as defaults:** `Fraunces` and `Instrument_Serif` (the two LLM-favorite display serifs).+ * **If a serif is justified** (rare, per the above), rotate from this pool, do NOT reuse the same serif across consecutive projects: PP Editorial New, GT Sectra Display, Cardinal Grotesque, Reckless Neue, Tiempos Headline, Recoleta, Cormorant Garamond, Playfair Display, EB Garamond, IvyPresto, Migra, Editorial Old, Saol Display, Söhne Breit Kursiv, Domaine Display, Canela, Schnyder, Tobias, NB Architekt, ITC Galliard.++* **ITALIC DESCENDER CLEARANCE (mandatory):** When italic is used in display type and the word contains a descender letter (`y g j p q`), `leading-[1]` or `leading-none` will clip the descender. Use `leading-[1.1]` minimum and add `pb-1` or `mb-1` reserve on the wrapping element. Audit every italic word in display headlines before shipping.++### 4.2 Color Calibration+* Max 1 accent color. Saturation < 80% by default.+* **THE LILA RULE:** The "AI Purple / Blue glow" aesthetic is discouraged as a default. No automatic purple button glows, no random neon gradients. Use neutral bases (Zinc / Slate / Stone) with high-contrast singular accents (Emerald, Electric Blue, Deep Rose, Burnt Orange, etc.).+* **Override:** if the brand or brief explicitly asks for purple / violet / lila, embrace it. But execute with intent: consistent palette, harmonised neutrals, restrained gradients. Not generic AI gradient slop.+* **One palette per project.** Do not fluctuate between warm and cool grays within the same project.+* **COLOR CONSISTENCY LOCK (mandatory):** Once an accent color is chosen for a page, it is used on the WHOLE page. A warm-grey site does not suddenly get a blue CTA in section 7. A rose-accented site does not get a teal status badge in the footer. Pick one accent, lock it, audit every component before shipping.++* **PREMIUM-CONSUMER PALETTE BAN (mandatory, second-most-recurring AI-tell):**+ * For premium-consumer briefs (cookware, wellness, artisan, luxury, heritage craft, DTC home goods, etc.) the LLM default is **warm beige/cream + brass/clay/oxblood/ochre + espresso/ink dark text**. Concretely banned hex families as default backgrounds and accents:+ - Backgrounds: `#f5f1ea`, `#f7f5f1`, `#fbf8f1`, `#efeae0`, `#ece6db`, `#faf7f1`, `#e8dfcb` (all "warm paper / cream / chalk / bone")+ - Accents: `#b08947`, `#b6553a`, `#9a2436`, `#9c6e2a`, `#bc7c3a`, `#7d5621` (all "brass / clay / oxblood / ochre")+ - Text: `#1a1714`, `#1a1814`, `#1b1814` (all "espresso / warm near-black")+ * This palette is BANNED as the default reach for premium-consumer briefs. Every premium-consumer site you have ever shipped uses this exact palette. The brand becomes invisible.+ * **Default alternatives (rotate, do not reuse):**+ - **Cold Luxury:** silver-grey + chrome + smoke (think Tesla, Apple Watch Hermes-without-the-leather)+ - **Forest:** deep green + bone + amber accent (think Filson, Patagonia premium)+ - **Black and Tan:** true off-black + warm tan, sharp contrast, no beige+ - **Cobalt + Cream:** saturated blue against a single neutral, no brass+ - **Terracotta + Slate:** warm rust against cool grey, no brass+ - **Olive + Brick + Paper:** muted olive plus brick-red accent+ - **Pure monochrome + single saturated pop:** off-white + off-black + one bright accent (electric blue, emerald, hot pink, etc.)+ * **Palette-rotation rule:** if the previous premium-consumer project you generated used the beige+brass family, this one MUST use a different family. Do not ship the same warm-craft palette twice in a row.+ * **Override:** the beige+brass+espresso palette is acceptable ONLY when the brand brief explicitly names those colors, or when the brand identity is genuinely vintage / artisan / warm-craft AND you can articulate why this specific palette fits this specific brand. Default-reaching for it because "this is a cookware brief" is banned.++### 4.3 Layout Diversification+* **ANTI-CENTER BIAS:** Centered Hero / H1 sections are avoided when `DESIGN_VARIANCE > 4`. Force "Split Screen" (50/50), "Left-aligned content / right-aligned asset", "Asymmetric white-space", or scroll-pinned structures.+* **Override:** centered hero is OK for editorial / manifesto / launch-announcement briefs where the message itself is the design.++### 4.4 Materiality, Shadows, Cards+* Use cards ONLY when elevation communicates real hierarchy. Otherwise group with `border-t`, `divide-y`, or negative space.+* When a shadow is used, tint it to the background hue. No pure-black drop shadows on light backgrounds.+* For `VISUAL_DENSITY > 7`: generic card containers are banned. Data metrics breathe in plain layout.+* **SHAPE CONSISTENCY LOCK (mandatory):** Pick ONE corner-radius scale for the page and stick to it. Options: all-sharp (radius 0), all-soft (radius 12-16px), all-pill (full radius for interactive). Mixed systems are allowed only when there is a documented rule (e.g. "buttons are full-pill, cards are 16px, inputs are 8px") and that rule is followed everywhere. Round buttons in a square layout, or square cards on a pill-button page, is broken design.++### 4.5 Interactive UI States+LLMs default to "static successful state only." Always implement full cycles:+* **Loading:** Skeletal loaders matching the final layout's shape. Avoid generic circular spinners.+* **Empty States:** Beautifully composed; indicate how to populate.+* **Error States:** Clear, inline (forms), or contextual (toasts only for transient).+* **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push.+* **BUTTON CONTRAST CHECK (mandatory, a11y):** Before shipping any button, verify the button text is readable against the button background. White button + white text, `bg-white` CTA with `text-white` label, transparent button against the page background with no border → all banned. Audit every CTA: contrast ratio WCAG AA min (4.5:1 for body, 3:1 for large text 18px+). Same rule applies to ghost buttons over photographic backgrounds (use a backdrop, scrim, or stroke).+* **CTA BUTTON WRAP BAN (mandatory):** Button text MUST fit on one line at desktop. If a label like "VIEW SELECTED WORK" wraps to 2 or 3 lines, the button is broken. Fix by EITHER shortening the label (3 words max for primary CTAs, ideally 1-2) OR widening the button (do not artificially constrain `max-width` on CTAs). Wrapped CTAs at desktop are a Pre-Flight Fail.+* **NO DUPLICATE CTA INTENT (mandatory):** Two CTAs with the same intent on one page is a Pre-Flight Fail. Examples of same intent: "Get in touch" + "Contact us" + "Let's talk" + "Start a project" + "Start something" + "Reach out" = all "contact" intent → pick ONE label and use it everywhere on the page (nav, hero, footer). Same for "Try free" + "Get started" + "Sign up free" (all "signup" intent) and "View work" + "See selected work" + "Browse projects" (all "portfolio" intent). One label per intent.+* **FORM CONTRAST CHECK (mandatory, a11y):** Form inputs, placeholder text, focus rings, helper text, and error text all pass WCAG AA contrast against the section background. Light placeholders on a near-white form, white form on white page section, form labels grayer than 4.5:1 contrast → all banned. Audit every form before shipping.++### 4.6 Data & Form Patterns+* Label ABOVE input. Helper text optional but present in markup. Error text BELOW input. Standard `gap-2` for input blocks.+* No placeholder-as-label. Ever.++### 4.7 Layout Discipline (Hard Rules. Failing any of these is shipping broken work)++* **Hero MUST fit in the initial viewport.** Headline max 2 lines on desktop, subtext max **20 words** AND max 3-4 lines, CTAs visible without scroll. If the copy is too long: reduce font scale OR cut copy. If you cannot describe the value-prop in 20 words of subtext, the value-prop is unclear, not the rule too tight. Never let the hero overflow and force scroll to find the CTA.+* **Hero font-scale discipline.** Plan font size and image size *together*. If the hero asset is large and the headline is more than 6 words, do not start at `text-7xl/text-8xl`. Default sensible range: `text-4xl md:text-5xl lg:text-6xl` for most heroes; `text-6xl md:text-7xl` only when the headline is 3-5 words. A 4-line hero headline is always a font-size error, never a copy-length error.+* **HERO TOP PADDING CAP (mandatory):** Hero top padding max `pt-24` (≈6rem) at desktop. More than that means the hero content floats halfway down the viewport and reads as a layout bug, not as intentional space. If your hero needs more breathing room, increase font scale or asset size, not top padding.+* **HERO STACK DISCIPLINE (max 4 text elements).** The hero is a single moment, not a feature list. Allowed text elements, max 4 in total:+ 1. Eyebrow (small uppercase label) OR brand strip OR neither - pick zero or one+ 2. Headline (max 2 lines, see above)+ 3. Subtext (max 20 words, max 4 lines)+ 4. CTAs (1 primary + max 1 secondary)+ - **BANNED in the hero:** tiny tagline below CTAs ("Works with GitHub, GitLab, and self-hosted Git"), trust micro-strip ("Used by engineering teams at..."), pricing teaser ("Free for solo, $10/user for teams"), feature bullet list, social-proof avatar row. All of those move to dedicated sections directly below the hero.+ - If you have an eyebrow AND a tagline below CTAs in the same hero, drop the tagline. If you have a brand strip AND a tagline, drop the tagline. One small text element per hero, max.+* **"Used by" / "Trusted by" logo wall belongs UNDER the hero, never inside it.** The hero is for the value prop and primary CTA. The logo wall is a separate section directly below. Do not stuff trust logos into the same flex row as the hero copy.+* **Navigation MUST render on a single line on desktop.** If items don't fit at `lg` (1024px), condense labels, drop secondary items, or move to a hamburger. A two-line nav at desktop is broken design.+* **Navigation height cap: 80px max desktop, default 64-72px.** No huge "agency" nav bars that eat 15% of the viewport.+* **Bento grids MUST have rhythm, not one-sided repetition.** Do not stack 6 left-image / right-text rows. Vary the composition: alternate full-width feature rows, asymmetric tile sizes, vertical breaks.+* **BENTO CELL COUNT RULE (mandatory):** A bento grid has EXACTLY as many cells as you have content for. 3 items → 3 cells (1+2 split, or 2+1, or asymmetric trio). 5 items → 5 cells (2+3, 3+2, hero+4, etc.). If your grid has an empty cell in the middle or at the end, you planned wrong. Re-shape the grid; do not paste a blank tile.+* **Section-Layout-Repetition Ban.** Once you use a layout family for a section (e.g., 3-column-image-cards, full-width-quote, split-text-image), that family can appear at most ONCE on the page. "Selected commissions" must not look like "What we do." A landing page with 8 sections must use at least 4 different layout families.+* **ZIGZAG ALTERNATION CAP (mandatory).** Alternating "left-image + right-text" then "left-text + right-image" zigzag layout = banal. Max 2 sections in a row with this image+text-split pattern. The 3rd consecutive image+text split is a Pre-Flight Fail. Break the pattern with a full-width section, a vertical-stack section, a bento grid, a marquee, or a different layout family.+* **EYEBROW RESTRAINT (mandatory, the #1 violated rule in production tests).** An "eyebrow" is the small uppercase wide-tracking label sitting above a section headline (e.g. `FOUR COLORWAYS`, `SELECTED WORK`, `THE HARDWARE`, `Git-native task management`). Typical CSS signature: `text-[11px] uppercase tracking-[0.18em]`, `font-mono text-[10.5px] uppercase tracking-[0.22em]`. Every AI-built site puts an eyebrow above EVERY section header, producing the same templated rhythm. Hard rule:+ - **Maximum 1 eyebrow per 3 sections.** Hero counts as 1. So a page with 9 sections may use at most 3 eyebrows total.+ - If section A has an eyebrow, the next 2 sections cannot have one.+ - **Pre-Flight Check is mechanical:** count instances of `uppercase tracking` (or similar small-caps mono labels above headlines) across all section components. If count > ceil(sectionCount / 3), the output fails.+ - **What to do instead of an eyebrow:** drop it entirely. The headline alone is enough. If you need to categorize a section, the section's location on the page already categorizes it; no label needed.+* **SPLIT-HEADER BAN (mandatory).** The pattern "left big headline + right small explainer paragraph" as a section header (left col-span-7/8, right col-span-4/5 with a small body paragraph floating in the right column) is **banned as default**. Sections should have ONE focused message. If you genuinely need both a headline and an explainer paragraph, stack them vertically (headline on top, body below, max-width 65ch). Reach for the split-header pattern only when there is a real compositional reason (e.g., the right column carries a visual or interactive element, not just filler text).+* **Bento Background Diversity (mandatory).** Bento and feature-grid sections cannot be 6 white-on-white cards with text inside. At least 2-3 cells in any multi-cell grid need real visual variation: a real image, a brand-appropriate gradient (not AI-purple), a pattern, a tinted background. A cream-on-cream bento with only typography inside reads as boring AI default, even when the rest of the page is good.+* **Mobile collapse must be explicit per section.** For every multi-column layout, declare the `< 768px` fallback in the same component. No "it'll work, Tailwind handles it" assumptions.++### 4.8 Image & Visual Asset Strategy++Landing pages and portfolios are **visual products**. Text-only pages with fake-screenshot divs are slop.++**Priority order for visual assets:**+1. **Image-generation tool first.** If ANY image-gen tool is available in the environment (`generate_image`, MCP image tool, IDE-integrated gen, OpenAI image tools, etc.) you MUST use it to create section-specific assets: hero photography, product shots, texture backgrounds, mood images. Generate at the right aspect ratio for the section. Do not skip this step because hand-rolled CSS feels faster.+2. **Real web images second.** When no gen tool is available, use real photography sources. Acceptable defaults:+ * `https://picsum.photos/seed/{descriptive-seed}/{w}/{h}` for placeholder photography (seed should describe the section, e.g. `marrow-cookware-kitchen`)+ * Actual stock or brand URLs when the brief provides them+ * Open-license sources (Unsplash via direct URL, Pexels) if explicitly allowed+3. **Last resort: tell the user.** If neither is possible, do NOT fill the page with hand-rolled SVG illustrations or div-based "fake screenshots." Instead, leave clearly-labeled placeholder slots (`<!-- TODO: hero product photo, 1600x1200 -->`) and at the end of the response say: *"This page needs real images at: \[list of placements\]. Please generate or provide them."*++**Even minimalist sites need real images.** A pure-text page is not minimalism. It is incomplete work. Even an editorial Linear-style site needs at least 2-3 real images (hero, one product/lifestyle shot, one supporting image). Generate B&W minimalist photography if the brief is restrained; do not skip images entirely because the dial is low.++**Real company logos for social proof.** When the brief calls for a "Trusted by / Used by / Customers" logo wall, do NOT default to plain text wordmarks (`<span>Acme Co</span>` styled in a row). Use real SVG logos:+* **Source: Simple Icons** (`https://cdn.simpleicons.org/{slug}/ffffff` for any color, or `simple-icons` npm package). Covers most known brands.+* **Alternative: devicon** for tech-stack logos (`@svgr/cli` or CDN).+* **Make-up the brand name? Then make-up an SVG mark too.** Generate a simple monogram (one letter in a circle, two-letter ligature, abstract glyph) rendered as an inline `<svg>` matching the page style. Plain text wordmarks for invented brand names look generic.+* **Always** ensure logos render in both light and dark mode (white-on-dark, black-on-light, or single-color theme variable).+* **LOGO-ONLY rule (mandatory):** logo wall = logos and nothing else. Do NOT print industry / category labels below each logo (no `Vercel` + `hosting` underneath, no `Stripe` + `payments`, no `Cloudflare` + `infra`). The logo is the credibility, the label adds nothing the user does not already know. Optional: brand name as alt-text for screen readers, optional link to the brand's site. That is it.++**Hand-rolled illustrations:**+* SVG icons from libraries: fine (see Section 3.C).+* Hand-rolled decorative SVGs (custom illustrations, logos, marks): **strongly discouraged**, never as default. Acceptable only when:+ - The brief explicitly calls for it ("draw me an SVG logo")+ - It's a single, simple geometric mark (a square, a circle, a wordmark in display type)+ - You're confident in the output quality++**Div-based fake screenshots are banned.** A "hand-built product preview" rendered with `<div>` rectangles, fake task lists, fake dashboards, fake terminal windows is a Tell. If you need to show a product:+* Use a real screenshot URL if one exists+* Generate one via image tool+* Use a real component preview (an actual mini-version of the UI inside the page)+* Or skip the preview entirely and use editorial photography++**Hero needs a real visual.** Text + gradient blob is not a hero - it's a placeholder.++### 4.9 Content Density++Landing pages live on the **first impression**, not the full read. Cut ruthlessly.++* **Default content shape per section:** short headline (≤ 8 words) + short sub-paragraph (≤ 25 words) + one visual asset OR one CTA. Anything more must be justified by the section's job.+* **No data-dump sections.** A 20-row publication table, a 30-row award list, a giant pricing matrix on a marketing page = wrong layout. Use:+ - Top 3-5 highlights + "View full list" link+ - Marquee / carousel for breadth+ - Different page entirely if the data is the product+* **Long lists need a different UI component, not a longer list.** Default `<ul>` with bullets / `divide-y` rows is the lazy choice. If you have > 5 items, reach for one of these instead:+ - 2-column split with grouped items+ - Card grid with image + label per item+ - Tabs / accordion if items are categorisable+ - Horizontal scroll-snap pills+ - Carousel for breadth-heavy lists (testimonials, logos, capabilities)+ - Marquee for "lots-of-things-that-don't-need-individual-attention"+ A spec sheet with 10 rows + a hairline under every row is the WORST default. Either group rows into 2-3 chunks with sparse dividers, or move to a card-per-spec layout.+* **Spec sheets specifically (the Marrow-cookware pattern).** A long product specification table with `border-b` on every row is the AI default for cookware / hardware / apparel / artisan-goods briefs. Banned. Concrete alternatives:+ - **2-col card grid:** each spec gets its own card with the spec name, the value (large display number), and a one-line "why it matters" body. Cards arranged 2-col on desktop, 1-col mobile.+ - **Scroll-snap horizontal pills:** each spec is a pill, user can flick through.+ - **Grouped chunks:** group 10 specs into 3 logical clusters (e.g. "Materials", "Cooking", "Warranty"), each cluster gets ONE soft divider and a cluster heading.+ - **Featured-vs-rest:** 3-4 hero specs visualised as large display tiles, the rest collapsed under a "View full specifications" disclosure.++* **COPY SELF-AUDIT (mandatory before ship):** Before declaring any task done, re-read every visible string on the page (headlines, subheads, eyebrows, button labels, body copy, captions, alt text, footer text, error messages). Flag any string that is:+ - **Grammatically broken** ("free on its past", "two plans but one is honest", "to put it on the table" out of context)+ - **Has unclear referents** ("we plan to stay that way" without prior context)+ - **Sounds like AI hallucination** (cute-but-wrong wordplay, forced metaphors that don't track, "elegant nothing" phrases)+ - **Reads like an LLM trying to sound thoughtful** (passive-aggressive humility, fake-craftsman labels, mock-poetic micro-meta)+ Rewrite every flagged string. If unsure whether a string makes sense, replace it with a plain functional sentence. AI-generated cute copy is worse than boring copy.+* **Fake-precise numbers are flagged.** Numbers like `92%`, `4.1×`, `48k`, `5.8 mm`, `13.4 lb` either:+ - Come from real data (brief, brand guidelines, public metrics) - fine+ - Are explicitly labeled as mock (`<!-- mock -->`, "example", "sample data") - fine+ - Are AI-invented spec aesthetics - banned. Don't fake engineering precision the brand doesn't claim.+* **One copy register per page.** Don't mix technical mono ("47 tasks · 0.6 ctx-switches/day"), editorial prose, and marketing punch in the same composition unless the brand voice explicitly calls for it.++### 4.10 Quotes & Testimonials++* **Max 3 lines** of quote body. Never 6. If the original quote is longer → cut it. A landing-page quote is a snippet, not the full review.+* For very small font sizes (e.g. footer-style testimonials), the line cap can stretch slightly. Spirit: "fits in a glance."+* **No em-dashes inside the quote text** as design flourish (long pauses, kinetic em-dashes, em-dash-bullets). See Section 9.G - em-dash is completely banned.+* Attribution: name + role + (optionally) company. Never name only ("- Sarah").+* Quote marks: use real typographic quotes ( " " ) or none at all. Not straight ASCII ( " ).++### 4.11 Page Theme Lock (Light / Dark Mode Consistency)++The page has ONE theme. Sections do not invert.++* If the page is dark mode, ALL sections are dark mode. No light-mode-warm-paper section sandwiched between dark sections (or vice versa). The user must not feel they walked into a different website mid-scroll.+* The exception: if the brief explicitly calls for a "Color Block Story" or "Theme Switch on Scroll" device AND that is a deliberate composition (one full theme switch with a strong transition, not random alternation), it is allowed once per page.+* Default behaviour: pick light, dark, or auto (`prefers-color-scheme`) at the page level and lock it. Section-level background tints within the same theme family are fine (`bg-zinc-950` next to `bg-zinc-900`); flipping to `bg-amber-50` in the middle of a `bg-zinc-950` page is broken.+* When using a design system with built-in theming (Radix Themes, shadcn/ui with `<Theme>`), set the theme ONCE in `layout.tsx` or the page root. Do not let individual sections override.++---++## 5. CONTEXT-AWARE PROACTIVITY++These are tools, not defaults. Use them when the design read calls for them. **None of these fire automatically.**++* **Liquid Glass / Glassmorphism:** Appropriate for premium consumer, Apple-adjacent, luxury brand, or media-overlay vibes. Inappropriate for dashboards, public-sector, or "boring B2B." When used, go beyond `backdrop-blur`: add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) for physical edge refraction. Provide a solid-fill fallback under `prefers-reduced-transparency`.+* **Magnetic Micro-physics:** Use when `MOTION_INTENSITY > 5` AND the brief reads premium / playful / agency. Implement EXCLUSIVELY with Motion's `useMotionValue` / `useTransform` outside the React render cycle. Never `useState`. See Section 3.B.+* **Perpetual Micro-Interactions** (Pulse, Typewriter, Float, Shimmer, Carousel): Use when `MOTION_INTENSITY > 5` AND the section actively benefits from motion (status indicators, live feeds, AI-feel). **Not every card needs an infinite loop.** If a section is informational, leave it still. Apply Spring Physics (`type: "spring", stiffness: 100, damping: 20`) - no linear easing.+* **"Motion claimed, motion shown."** If `MOTION_INTENSITY > 4`, the page must actually move: entry transitions on hero, scroll-reveal on key sections, hover physics on CTAs, at minimum. A static page that claims `MOTION_INTENSITY: 7` is broken. Conversely, if you cannot ship working motion in the available scope, drop the dial to 3 and ship a clean static page. Never half-build motion that breaks (cut-off ScrollTriggers, jumpy enters, missing cleanups).+* **MOTION MUST BE MOTIVATED (mandatory).** Before adding any animation, ask: "what does this animation communicate?" Valid answers: hierarchy (drawing attention to the right thing), storytelling (revealing content in sequence that matches a narrative), feedback (acknowledging a user action), state transition (showing something changed). Invalid answer: "it looked cool". GSAP everywhere because GSAP is available is amateur. Each ScrollTrigger, each marquee, each pinned section needs a reason. If you cannot articulate the reason in one sentence, drop the animation.+* **MARQUEE MAX-ONE-PER-PAGE (mandatory).** Horizontal scrolling text marquees ("logos endlessly scrolling", "manifesto scrolling sideways", "kinetic word strip") are appropriate at most ONCE per page. Two or more marquees on the same page reads as lazy filler. Pick the one section where the marquee actually serves the content; the others get a different layout.+* **GSAP Sticky-Stack Pattern (when scroll-stack is used).** A "card stack on scroll" must be a REAL sticky-stack, not a sequential reveal list. See Section 5.A below for the canonical code skeleton. Common failure: trigger fires halfway through scroll instead of pinning at viewport top. Fix: `start: "top top"` not `start: "top center"` or `"top 80%"`.+* **GSAP Horizontal-Pan Pattern (when horizontal scroll-hijack is used).** See Section 5.B below for the canonical skeleton. Common failure: animation starts before the section is pinned, so the user sees half a slide. Same fix: `start: "top top"`, pin the wrapper, scrub the inner track.++### 5.A Sticky-Stack - Canonical Skeleton++```tsx+"use client";+import { useRef, useEffect } from "react";+import { gsap } from "gsap";+import { ScrollTrigger } from "gsap/ScrollTrigger";+import { useReducedMotion } from "motion/react";++gsap.registerPlugin(ScrollTrigger);++export function StickyStack({ cards }: { cards: React.ReactNode[] }) {+ const ref = useRef<HTMLDivElement>(null);+ const reduce = useReducedMotion();++ useEffect(() => {+ if (reduce || !ref.current) return;+ const ctx = gsap.context(() => {+ const cardEls = gsap.utils.toArray<HTMLElement>(".stack-card");+ cardEls.forEach((card, i) => {+ if (i === cardEls.length - 1) return;+ ScrollTrigger.create({+ trigger: card,+ start: "top top", // pin at viewport top+ endTrigger: cardEls[cardEls.length - 1],+ end: "top top",+ pin: true,+ pinSpacing: false,+ });+ gsap.to(card, {+ scale: 0.92,+ opacity: 0.55,+ ease: "none",+ scrollTrigger: {+ trigger: cardEls[i + 1],+ start: "top bottom",+ end: "top top",+ scrub: true,+ },+ });+ });+ }, ref);+ return () => ctx.revert();+ }, [reduce]);++ return (+ <div ref={ref} className="relative">+ {cards.map((card, i) => (+ <div+ key={i}+ className="stack-card sticky top-0 min-h-[100dvh] flex items-center justify-center"+ >+ {card}+ </div>+ ))}+ </div>+ );+}+```++Critical points: `start: "top top"`, `pin: true`, every card except the last is pinned, the scale/opacity transform is driven by the NEXT card's scroll trigger (so previous card shrinks as next one arrives).++### 5.B Horizontal-Pan - Canonical Skeleton++```tsx+"use client";+import { useRef, useEffect } from "react";+import { gsap } from "gsap";+import { ScrollTrigger } from "gsap/ScrollTrigger";+import { useReducedMotion } from "motion/react";++gsap.registerPlugin(ScrollTrigger);++export function HorizontalPan({ children }: { children: React.ReactNode }) {+ const wrap = useRef<HTMLDivElement>(null);+ const track = useRef<HTMLDivElement>(null);+ const reduce = useReducedMotion();++ useEffect(() => {+ if (reduce || !wrap.current || !track.current) return;+ const ctx = gsap.context(() => {+ const distance = track.current!.scrollWidth - window.innerWidth;+ gsap.to(track.current, {+ x: -distance,+ ease: "none",+ scrollTrigger: {+ trigger: wrap.current,+ start: "top top", // pin starts when section top hits viewport top+ end: () => `+=${distance}`, // scroll distance = track width minus viewport+ pin: true,+ scrub: 1,+ invalidateOnRefresh: true,+ },+ });+ }, wrap);+ return () => ctx.revert();+ }, [reduce]);++ return (+ <section ref={wrap} className="relative overflow-hidden">+ <div ref={track} className="flex h-[100dvh] items-center">+ {children}+ </div>+ </section>+ );+}+```++Critical points: `start: "top top"`, `pin: true`, `end: "+=${distance}"` (scroll length = horizontal travel needed), `scrub: 1`. The wrapper is pinned, the inner track slides horizontally as the user scrolls vertically.++### 5.C Scroll-Reveal Stagger - Canonical Skeleton (lighter alternative)++For simple "items appear as they enter viewport" (no pinning), prefer Motion's `whileInView` over GSAP - lighter, no ScrollTrigger needed:++```tsx+"use client";+import { motion, useReducedMotion } from "motion/react";++export function RevealStagger({ items }: { items: string[] }) {+ const reduce = useReducedMotion();+ return (+ <ul className="grid gap-6">+ {items.map((item, i) => (+ <motion.li+ key={item}+ initial={reduce ? false : { opacity: 0, y: 24 }}+ whileInView={{ opacity: 1, y: 0 }}+ viewport={{ once: true, amount: 0.3 }}+ transition={{+ duration: 0.6,+ delay: i * 0.06,+ ease: [0.16, 1, 0.3, 1],+ }}+ >+ {item}+ </motion.li>+ ))}+ </ul>+ );+}+```++Use this for: feature lists, testimonial grids, logo walls, anything that just needs "enter on scroll." Save GSAP for actual pin/scrub work.++### 5.D Forbidden Animation Patterns++* **`window.addEventListener("scroll", ...)`** is banned. It runs on every scroll frame, jank-prone, no batching. Use Motion's `useScroll()`, GSAP's `ScrollTrigger`, IntersectionObserver, or CSS `scroll-driven animations` (`animation-timeline: view()`).+* **Custom scroll progress calculations using `window.scrollY`** in React state. Same reason. Re-renders on every frame.+* **`requestAnimationFrame` loops that touch React state.** Use motion values (`useMotionValue` + `useTransform`) instead.+* **Layout Transitions:** Use Motion's `layout` and `layoutId` props for visible state changes (re-ordering lists, expanding modals, shared elements between routes). Do not wrap static content in `layout` props "for safety" - it costs measurement work.+* **Staggered Orchestration:** Use `staggerChildren` (Motion) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) for reveal moments where sequence matters. For `staggerChildren`, parent (`variants`) and children MUST share the same Client Component tree.++---++## 6. PERFORMANCE & ACCESSIBILITY GUARDRAILS++### 6.A Hardware Acceleration+* Animate ONLY `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`.+* Use `will-change: transform` sparingly - only on elements that will actually animate.++### 6.B Reduced Motion (mandatory)+* **Any motion above `MOTION_INTENSITY > 3` MUST honor `prefers-reduced-motion`.** This is non-negotiable.+* In Motion: wrap with `useReducedMotion()` and degrade to static.+* In CSS: gate animations behind `@media (prefers-reduced-motion: no-preference)` or provide an override block under `@media (prefers-reduced-motion: reduce)` that disables.+* Infinite loops, parallax, scroll-hijack, and magnetic physics MUST collapse to static / instant under reduced motion.++### 6.C Dark Mode (mandatory for any consumer-facing page)+* Design for **both modes from the start**. Never ship light-only or dark-only without explicit user instruction.+* Use Tailwind `dark:` variant OR CSS variables for tokens. Pick one strategy per project.+* **Do not prescribe specific dark-mode colors here.** The brief decides. Maintain visual hierarchy, brand identity, and WCAG AA contrast (AAA for body) across both modes.+* Respect `prefers-color-scheme: dark`. Default to system preference unless the brand insists on one mode.++### 6.D Core Web Vitals Targets+* **LCP** < 2.5s. Hero image must be `next/image priority` or preloaded.+* **INP** < 200ms. Heavy work off main thread.+* **CLS** < 0.1. Reserve space for images, fonts, embeds.+* Run Lighthouse before declaring a page done.++### 6.E DOM Cost+* Apply grain / noise filters EXCLUSIVELY to fixed, `pointer-events-none` pseudo-elements (e.g., `fixed inset-0 z-[60] pointer-events-none`). NEVER on scrolling containers - continuous GPU repaints destroy mobile FPS.+* Be aware of bundle size. Motion is not tiny. Three.js is large. Lazy-load anything that's not above-the-fold.++### 6.F Z-Index Restraint+NEVER spam arbitrary `z-50` or `z-10`. Use z-index strictly for systemic layer contexts (sticky navbars, modals, overlays, grain). Document the z-index scale in a project constants file.++---++## 7. DIAL DEFINITIONS (Technical Reference)++### DESIGN_VARIANCE (Level 1-10)+* **1-3 (Predictable):** Symmetrical CSS Grid (12-col, equal fr-units), equal paddings, centered alignment.+* **4-7 (Offset):** `margin-top: -2rem` overlaps, varied image aspect ratios (4:3 next to 16:9), left-aligned headers over center-aligned data.+* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (`grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`).+* **MOBILE OVERRIDE:** For levels 4-10, asymmetric layouts above `md:` MUST collapse to strict single-column (`w-full`, `px-4`, `py-8`) on viewports `< 768px`.++### MOTION_INTENSITY (Level 1-10)+* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only. `prefers-reduced-motion` is the default mode anyway.+* **4-7 (Fluid CSS):** `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. `animation-delay` cascades for load-ins. Focus on `transform` and `opacity`.+* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals, parallax, scroll-driven animation (CSS `animation-timeline` or GSAP ScrollTrigger). Use Motion hooks. **NEVER use `window.addEventListener('scroll')`** - it is a hard ban, not a "prefer-not." See Section 5.D for the allowed alternatives.++### VISUAL_DENSITY (Level 1-10)+* **1-3 (Art Gallery):** Lots of white space. Huge section gaps (`py-32` to `py-48`). Expensive, clean.+* **4-7 (Daily App):** Standard web app spacing (`py-16` to `py-24`).+* **8-10 (Cockpit):** Tight paddings. No card boxes; 1px lines separate data. Mandatory: `font-mono` for all numbers.++---++## 8. DARK MODE PROTOCOL++Dual-mode by default. Never assume light-only unless the brief is print-emulating editorial.++### 8.A Token Strategy (pick one, stick to it)+* **Tailwind `dark:` variant** (default for utility-first projects): every color utility paired with its dark variant (`bg-white dark:bg-zinc-950`, `text-gray-900 dark:text-gray-100`).+* **CSS variables** (for shadcn/ui, Radix Themes, or component libraries with theming): define semantic tokens (`--surface`, `--surface-elevated`, `--text-primary`, `--accent`) and swap values under `[data-theme="dark"]` or `@media (prefers-color-scheme: dark)`.++### 8.B Do Not Prescribe Specific Colors Here+The brief and brand decide. This skill enforces only:+* **Contrast** - WCAG AA minimum for body text, AAA target for hero copy.+* **Hierarchy parity** - visual hierarchy that works in light must work in dark. If a CTA pops in light, it pops in dark.+* **Brand fidelity** - primary brand color stays recognisable. Don't desaturate the brand into a dark mode.+* **No pure `#000000` and no pure `#ffffff`** - use off-black (zinc-950, near-black warm gray) and off-white. Pure values kill depth.++### 8.C Default Mode+Respect `prefers-color-scheme` unless the brand insists. Add a manual toggle if either mode would lose key brand expression.++### 8.D Test in Both Modes Before Finishing+Open the page in both modes during development. Do not ship a page you've only seen in one mode.++---++## 9. AI TELLS (Forbidden Patterns)++Avoid these signatures unless the brief explicitly asks for them.++### 9.A Visual & CSS+* **NO neon / outer glows** by default. Use inner borders or subtle tinted shadows.+* **NO pure black (`#000000`).** Off-black, zinc-950, or charcoal.+* **NO oversaturated accents.** Desaturate to blend with neutrals.+* **NO excessive gradient text** for large headers.+* **NO custom mouse cursors.** Outdated, accessibility-hostile, perf-hostile.++### 9.B Typography+* **AVOID Inter as default.** See Section 4.1. Override path exists.+* **NO oversized H1s** that just scream. Control hierarchy with weight + color, not raw scale.+* **Serif constraints:** Serif for editorial / luxury / publication. Not for dashboards.++### 9.C Layout & Spacing+* **Mathematically perfect** padding and margins. No floating elements with awkward gaps.+* **NO 3-column equal feature cards.** The generic "three identical cards horizontally" feature row is banned. Use 2-column zig-zag, asymmetric grid, scroll-pinned, or horizontal-scroll alternative.++### 9.D Content & Data ("Jane Doe" Effect)+* **NO generic names.** "John Doe", "Sarah Chan", "Jack Su" → use creative, realistic, locale-appropriate names.+* **NO generic avatars.** No SVG "egg" or Lucide user icons → use believable photo placeholders or specific styling.+* **NO fake-perfect numbers.** Avoid `99.99%`, `50%`, `1234567`. Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).+* **NO startup-slop brand names.** "Acme", "Nexus", "SmartFlow", "Cloudly" → invent contextual, premium names that sound real.+* **NO filler verbs.** "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize" → concrete verbs only.++### 9.E External Resources & Components+* **NO hand-rolled SVG icons.** Use Phosphor / HugeIcons / Radix / Tabler. Lucide on explicit request only.+* **Hand-rolled decorative SVGs strongly discouraged** as default (see Section 4.8).+* **NO div-based fake screenshots.** Never build a fake product UI out of `<div>` rectangles to simulate a screenshot. Use real images, generated images, or skip the preview.+* **NO broken Unsplash links.** Use `https://picsum.photos/seed/{descriptive-string}/{w}/{h}`, or generated photo placeholders, or actual assets.+* **shadcn/ui customization:** Allowed, but NEVER in default state. Customize radii, colors, shadows, typography to the project aesthetic.+* **Production-Ready Cleanliness:** Code visually clean, memorable, meticulously refined.++### 9.F Production-Test Tells (banned outright)++These patterns came out of real LLM-generated landing-page tests. They are the signatures the model defaults to when it tries to "look designed." Treat them as hard bans unless the brief explicitly calls for one.++**Hero & top-of-page**+* **NO version labels in the hero.** `V0.6`, `v2.0`, `BETA`, `INVITE-ONLY PREVIEW`, `EARLY ACCESS`, `ALPHA` - banned as default eyebrows. Only acceptable when the brief is explicitly about a product launch / preview status.+* **NO "Brand · No. 01"-style sub-eyebrows.** "Marrow · No. 01 · The 6-quart" type micro-meta lines. Skip them.++**Section numbering & micro-labels**+* **NO section-number eyebrows.** `00 / INDEX`, `001 · Capabilities`, `002 · Featured commission`, `06 · how it works`, `05 · The honest table` - banned. Eyebrows should name the topic in plain language, not enumerate.+* **NO `01 / 4`-style pagination on images or bento tiles.** If the user can count, they don't need the label.+* **NO `Scroll · 001 Capabilities`-style scroll cues.** A simple arrow or "Scroll" is enough; no section-number prefix.+* **NO "Index of Work, 2018 - 2026"-style range labels** as eyebrows. Just say what the section is.++**Separators & dots**+* **The middle-dot (`·`) is rationed.** Maximum 1 per line in metadata strips. Do NOT use it as the default separator for everything ("foo · bar · baz · qux · quux"). If you need a separator family, prefer line breaks, hairlines, or columns.+* **NO decorative colored status dots on every list/nav/badge.** A colored dot before "ONE Q4 SLOT OPEN" or before every nav link, or every task row - banned by default. Acceptable only when the dot conveys actual semantic state (a server status, an availability flag) and is used sparingly.++**Em-dashes & typography flourishes**+* **NO em-dash (`—`) as a design element OR anywhere else.** See Section 9.G below for the complete, non-negotiable ban. The em-dash character is forbidden in headlines, eyebrows, pills, body copy, quotes, attribution, captions, button text, and alt text. Use the regular hyphen (`-`).+* **NO `<br>`-broken-and-italicized headlines** as a default "design move." "for thirty\<br\>*years.*" type splits. Headlines should read naturally first, get clever only when the brief demands it.+* **NO vertical rotated text** ("INDEX OF WORK, 2018 - 2026" rotated 90°). Agency-portfolio cliché. Use it only when the brief is explicitly agency / Awwwards / experimental AND it serves a real composition purpose.+* **NO crosshair / hairline grid lines as decoration.** Vertical and horizontal lines drawn just to make the page "feel designed" - banned. Use them only when they organize real content.++**Fake product previews**+* **NO div-based fake product UI in the hero** (fake task list, fake terminal, fake dashboard built from styled divs). It is the #1 LLM-design Tell. Use a real screenshot, a generated image, a real component preview, or none at all.+* **NO fake version footers** ("v0.6.2-rc.1", "last sync 4s ago · main") inside fake screenshots. Adds nothing, screams AI.++**Marketing-copy Tells**+* **NO "Quietly in use at" / "Quietly trusted by"** social-proof headers. Use natural language: "Trusted by", "Used at", "Customers include", or skip the heading entirely if the logos speak.+* **NO "From the field" / "Field notes" / "Currently on the bench" / "On our desks" / "Loose plates" style poetic labels** on quote, blog, or sidebar sections. Reads as performative-craftsman. Use plain functional labels ("Testimonials", "Latest writing", "Now working on") or skip the label.+* **NO "We respect the French ones"-style** mock-humble industry-references in body copy. Cute and AI-y.+* **NO weather / locale strips** ("LIS 14:23 · 18°C") in headers/footers unless the brief is explicitly about a place / time-zone-distributed studio.+* **NO micro-meta-sentences under eyebrows.** Sentences like *"Each of these is a feature we ship today, not a roadmap promise. The list will stay short on purpose."* sitting under a section heading are clutter. Eyebrow + Headline + Body is enough.+* **NO generic step labels.** "Stage 1 / Stage 2 / Stage 3", "Step 1 / Step 2 / Step 3", "Phase 01 / Phase 02 / Phase 03", "Pass One / Pass Two / Pass Three". Banned. The actual step content is the label. If you must show progression, use the verb-noun directly ("Install", "Configure", "Ship") not "Stage 1: Install".++**Pills, labels and version stamps**+* **NO pills/labels/tags overlaid on images.** No `<span>` overlays on photos with tags like `Brand · 02`, `PLATE · BRAND`, `Field notes - journal`. Either let the image speak alone, or add a caption directly below (outside the image).+* **NO photo-credit captions as decoration.** Strings like `Field study no. 12 · Ines Caetano`, `Plate 03 · House archive`, `Frame XII · 35mm` under stock/picsum images are pretentious. Photo credit is allowed ONLY when there is a real photographer being credited for a real photo (with permission). Otherwise: skip the caption or use a one-line functional caption ("The 6-quart, in Sage.").+* **NO version footers on marketing pages.** Footer strings like `v1.4.2`, `Build 0048`, `last sync 4s ago · main` are CLI / devtool fixtures, not landing-page content. Banned on marketing/landing/portfolio pages.+* **NO "Reservation 412 of 800"-style live-stock counters** as decoration. Only if the brief is explicitly a limited-run waitlist with real data.++**Decoration text strips**+* **NO decoration text strip at hero bottom.** Patterns like `BRAND. MOTION. SPATIAL.`, `TYPE / FORM / MOTION`, `DESIGN · BUILD · SHIP`, `ESTD. 2018 · LISBON · BRAND. MOTION. SPATIAL.` as a small mono-caps strip across the bottom of the hero are an agency-portfolio cliché. Banned by default. Only acceptable when the strip carries real, navigable links (sticky bottom nav) or real status info (cookie banner, build info on a docs site).+* **NO floating top-right sub-text in section headings.** Pattern: section has a giant left-aligned headline; in the top-right corner of the same section header there is a small explainer paragraph floating with no clear alignment to anything else. That floater is the Tell. Either put the sub-text directly under the headline, or build a clean 2-column header (left: headline, right: aligned body), but not a tiny corner paragraph.++**Lists, dividers and scoring**+* **NO `border-t` + `border-b` on every row of a long list / spec table.** Pick one (bottom-border between rows OR top-border above the group) and use it sparsely. A 10-row spec table with hairlines under each row is the laziest layout - see Section 4.9 for alternative UI components.+* **NO scoring/progress bars with filled background tracks** as comparison visuals. If you need to show "X out of Y" comparisons, prefer a number + small icon, or a tiny inline bar WITHOUT a background track. Big filled `bg-zinc-200` tracks with a partial fill on top are dashboard-UI clutter on a landing page.++**Locale, time, scroll cues**+* **Locale / city-name / time / weather strips are banned for 99% of briefs.** "Lisbon, working with founders" in the hero, "1200-690 Lisbon, Portugal" in the footer, "Lisbon 14:23 · 18°C" in the nav. These are agency-portfolio decoration tells. Allowed ONLY when: the brief explicitly describes a globally-distributed studio with timezone-relevant work, OR a travel-focused brand, OR a real-world physical venue. A single contact-address mention in the footer is fine; an atmospheric locale strip is not.+* **Scroll cues are banned.** `Scroll`, `↓ scroll`, `Scroll to explore`, `Scroll to walk through it`, animated mouse-wheel icons. If the user has not scrolled yet, they are looking at the hero. They know what scroll is. The bottom of the viewport does not need a label.+* **ZERO decorative status dots by default.** A coloured dot before nav items, before list rows, before badges, before status labels is a Tell. Only acceptable when conveying real semantic state (a live indicator on actual server status, a live availability flag) and limited to one per page section.++### 9.G EM-DASH BAN (the single most-violated Tell)++**Em-dash (`—`) is COMPLETELY banned.** It is the LLM's signature stylistic crutch and it is the #1 visual Tell in production tests. There is no "limited use" allowance, no "natural language frequency" allowance, no "in body copy is fine" allowance. None.++* **Banned in headlines.** Use a period or a comma.+* **Banned in eyebrows / labels / pills / button text / image captions / nav items.** Replace with line breaks, columns, or hairlines.+* **Banned in body copy.** Restructure the sentence: two sentences with a period, OR a comma, OR parentheses, OR a colon.+* **Banned in quote attribution.** Use a normal hyphen with spaces (` - `) or a line break + smaller-weight name.+* **Banned in en-dash form too (`–`) when used as a separator.** Date ranges (`2018-2026`) use a hyphen. Number ranges (`€40-80k`) use a hyphen.++The ONLY permitted dash characters on the page are:+* Regular hyphen `-` (for compound words, ranges, line dividers in markup)+* Minus sign in math (`-5°C`)++If your output contains a single `—` or `–` anywhere visible to the user, the output fails the Pre-Flight Check and must be rewritten.++This rule is non-negotiable. The agent has historically ignored em-dash limits when phrased as "use sparingly." The phrasing here is binary: zero em-dashes.++---++## 10. REFERENCE VOCABULARY (Pattern Names the Agent Should Know)++This is a vocabulary, not a library. The agent should KNOW these pattern names to communicate about them, design with them in mind, and reach for them when the design read calls for them. **Implementations and code sketches live in the Block Library (Section 12), which is populated iteratively.**++### Hero Paradigms+* **Asymmetric Split Hero** - Text on one side, asset on the other, generous white space.+* **Editorial Manifesto Hero** - Large type, no asset, almost-poster.+* **Video / Media Mask Hero** - Type cut out as mask over video background.+* **Kinetic-Type Hero** - Animated typography as the primary visual.+* **Curtain-Reveal Hero** - Hero parts on scroll like a curtain.+* **Scroll-Pinned Hero** - Hero stays pinned while content scrolls behind.++### Navigation & Menus+* **Mac OS Dock Magnification** - Edge nav, icons scale fluidly on hover.+* **Magnetic Button** - Pulls toward cursor.+* **Gooey Menu** - Sub-items detach like viscous liquid.+* **Dynamic Island** - Morphing pill for status / alerts.+* **Contextual Radial Menu** - Circular menu expanding at click point.+* **Floating Speed Dial** - FAB springing into curved secondary actions.+* **Mega Menu Reveal** - Full-screen dropdown, stagger-fade content.++### Layout & Grids+* **Bento Grid** - Asymmetric tile grouping (Apple Control Center).+* **Masonry Layout** - Staggered grid, no fixed row height.+* **Chroma Grid** - Borders / tiles with subtle animating gradients.+* **Split-Screen Scroll** - Two halves sliding in opposite directions.+* **Sticky-Stack Sections** - Sections that pin and stack on scroll.++### Cards & Containers+* **Parallax Tilt Card** - 3D tilt tracking mouse coordinates.+* **Spotlight Border Card** - Borders illuminate under cursor.+* **Glassmorphism Panel** - Frosted glass with inner refraction.+* **Holographic Foil Card** - Iridescent rainbow shift on hover.+* **Tinder Swipe Stack** - Physical card stack, swipe-away.+* **Morphing Modal** - Button expands into its own dialog.++### Scroll Animations+* **Sticky Scroll Stack** - Cards stick and physically stack.+* **Horizontal Scroll Hijack** - Vertical scroll → horizontal pan.+* **Locomotive / Sequence Scroll** - Video / 3D sequence tied to scrollbar.+* **Zoom Parallax** - Central background image zooming on scroll.+* **Scroll Progress Path** - SVG line drawing along scroll.+* **Liquid Swipe Transition** - Page transition like viscous liquid.++### Galleries & Media+* **Dome Gallery** - 3D panoramic gallery.+* **Coverflow Carousel** - 3D carousel with angled edges.+* **Drag-to-Pan Grid** - Boundless draggable canvas.+* **Accordion Image Slider** - Narrow strips expanding on hover.+* **Hover Image Trail** - Mouse leaves popping image trail.+* **Glitch Effect Image** - RGB-channel shift on hover.++### Typography & Text+* **Kinetic Marquee** - Endless text bands reversing on scroll.+* **Text Mask Reveal** - Massive type as transparent window to video.+* **Text Scramble Effect** - Matrix-style decoding on load / hover.+* **Circular Text Path** - Text curving along spinning circle.+* **Gradient Stroke Animation** - Outlined text with running gradient.+* **Kinetic Typography Grid** - Letters dodging the cursor.++### Micro-Interactions & Effects+* **Particle Explosion Button** - CTA shatters into particles on success.+* **Liquid Pull-to-Refresh** - Reload indicator like detaching droplets.+* **Skeleton Shimmer** - Shifting light reflection across placeholders.+* **Directional Hover-Aware Button** - Fill enters from cursor's exact side.+* **Ripple Click Effect** - Wave from click coordinates.+* **Animated SVG Line Drawing** - Vectors drawing themselves in real time.+* **Mesh Gradient Background** - Organic lava-lamp blobs.+* **Lens Blur Depth** - Background UI blurred to focus foreground action.++### Animation Library Choice+* **Motion (`motion/react`)** - default for UI / Bento / state-change motion.+* **GSAP + ScrollTrigger** - for full-page scrolltelling and scroll hijacks. Isolate in dedicated leaf components with `useEffect` cleanup.+* **Three.js / WebGL** - for canvas backgrounds and 3D scenes. Same isolation rule.+* **NEVER mix GSAP / Three.js with Motion in the same component tree.** They fight over the same frames.++---++## 11. REDESIGN PROTOCOL++This skill handles **greenfield builds AND redesigns**. Misclassifying the mode is the single biggest source of bad redesign output.++### 11.A Detect the Mode (first action)+* **Greenfield** - no existing site, or full overhaul approved. Dial baseline from Section 1.+* **Redesign - Preserve** - modernise without breaking the brand. Audit first, extract brand tokens, evolve gradually.+* **Redesign - Overhaul** - new visual language on top of existing content. Treat as greenfield for visuals; preserve content and IA.++If ambiguous, ask **once**: *"Should this redesign preserve the existing brand, or are we starting visually from scratch?"*++### 11.B Audit Before Touching+Document the current state before proposing changes:+* **Brand tokens** - primary / accent colors, type stack, logo treatment, radii.+* **Information architecture** - page tree, primary nav, key conversion paths.+* **Content blocks** - what exists, what's doing work, what's filler.+* **Patterns to preserve** - signature interactions, recognisable hero, copy voice.+* **Patterns to retire** - AI-slop tells, broken layouts, dead links, generic stock imagery, perf traps.+* **Dial reading of the existing site** - infer current `DESIGN_VARIANCE` / `MOTION_INTENSITY` / `VISUAL_DENSITY`. That's your starting point, not the baseline.+* **SEO baseline** - current ranking pages, meta titles, structured data, OG cards. **SEO migration is the #1 redesign risk.**++### 11.C Preservation Rules+* **Do not change information architecture** unless asked. Keep page slugs, anchor IDs, primary nav labels stable for SEO and muscle memory.+* **Extract brand colors before applying Section 4.2.** A brand that is already purple stays purple - apply the LILA RULE's override.+* **Preserve copy voice** unless asked for a rewrite. Visual modernisation ≠ content rewrite.+* **Honor existing accessibility wins.** Do not regress focus states, alt text, keyboard nav, contrast.+* **Respect existing analytics events.** Do not rename buttons, form fields, section IDs that downstream tracking depends on.++### 11.D Modernisation Levers (priority order)+Apply in order - stop when the brief is satisfied:+1. **Typography refresh** - biggest visual lift per unit of risk.+2. **Spacing & rhythm** - increase section padding, fix vertical rhythm.+3. **Color recalibration** - desaturate, unify neutrals, keep brand accent.+4. **Motion layer** - add `MOTION_INTENSITY`-appropriate micro-interactions to existing components.+5. **Hero & key-section recomposition** - restructure top-of-funnel using Section 10 vocabulary.+6. **Full block replacement** - only when the existing block is unsalvageable.++### 11.E Decision Tree: Targeted Evolution vs Full Redesign+* IA, content, and SEO sound → **targeted evolution** (Levers 1-4). ~70% of value at ~40% of risk.+* Visual debt is structural (broken IA, no design system, broken mobile) → **full redesign** with strict content preservation.+* Brand itself is changing → **greenfield**.++### 11.F What Never Changes Silently+Never modify without explicit user approval:+* URL structure / route slugs.+* Primary nav labels.+* Form field names or order (breaks analytics + autofill).+* Brand logo or wordmark.+* Existing legal / consent / cookie copy.++---++## 12. THE BLOCK LIBRARY (Contract - Implementations Land Here Iteratively)++The Reference Vocabulary (Section 10) names patterns. The Block Library implements them with real props, real motion specs, and real code sketches.++**Status:** schema defined here. Blocks will be added iteratively. Do not freelance new blocks without following this schema.++### 12.A File Location+```+skills/taste-skill/blocks/+ hero/+ asymmetric-split.md+ editorial-manifesto.md+ kinetic-type.md+ ...+ feature/+ bento-grid.md+ sticky-scroll-stack.md+ zig-zag.md+ ...+ social-proof/+ pricing/+ cta/+ footer/+ navigation/+ portfolio/+ transition/+```++### 12.B Required Frontmatter+```yaml+---+name: asymmetric-split-hero+category: hero+dial_compatibility:+ variance: [6, 10]+ motion: [3, 10]+ density: [2, 5]+when_to_use: "Landing pages with one strong asset and one strong message. Default hero for SaaS, agency, premium consumer."+not_for: "Editorial / manifesto launches where the message IS the design."+stack: ["react", "next", "tailwind", "motion"]+---+```++### 12.C Required Body Sections+1. **Visual sketch** - short ASCII or description of the layout.+2. **Props API** - the component's interface.+3. **Code sketch** - minimal working implementation (Server Component default, Client island for motion).+4. **Mobile fallback** - explicit collapse rules for `< 768px`.+5. **Motion variants** - one variant per `MOTION_INTENSITY` band (1-3, 4-7, 8-10). Reduced-motion fallback explicit.+6. **Dark-mode notes** - token strategy specific to this block.+7. **Anti-patterns** - common ways this block goes wrong.+8. **References** - links to real examples in production.++### 12.D Block-Library Discipline+* One block per file. No multi-block files.+* Every block must work standalone (drop it into a page, it renders).+* Every block must pass the Pre-Flight Check (Section 14).+* Blocks that depend on a design system from Section 2.A live under `blocks/<category>/<name>--<system>.md` (e.g. `feature/bento-grid--material.md`).++---++## 13. OUT OF SCOPE++This skill is NOT for:+* Dashboards / dense product UI / admin panels (use Fluent, Carbon, Atlassian, or Polaris from Section 2.A).+* Data tables (use TanStack Table or AG Grid).+* Multi-step forms / wizards (use Form-specific patterns; this skill won't make them better).+* Code editors (use Monaco / CodeMirror with their official skinning).+* Native mobile (use Apple HIG / Material directly).+* Realtime collab UIs (presence, cursors, OT-aware - different problem class).++If the brief is one of the above, **say so explicitly**, point to the right tool, and only apply this skill's marketing-page / about-page / landing-page parts to the surfaces where they apply.++**For dense product UI specifically** (dashboards, data tables, forms, multi-step flows, settings, app shells), the dedicated counterpart to this skill is **`product-ui-taste`** - use it instead of (or alongside, on a split marketing+product screen) this one. It carries the frame-first / rows-not-cards / overflow / state-matrix / data-table / a11y rigor that this skill deliberately leaves out of scope.++---++## 14. FINAL PRE-FLIGHT CHECK++Run this matrix before outputting code. This is the last filter.++**THIS IS NOT OPTIONAL. Run every box. If any box fails, the output is not done.**++- [ ] **Brief inference** declared (Section 0.B one-liner)?+- [ ] **Dial values** explicit and reasoned from the brief, not silently using baseline?+- [ ] **Design system** chosen from Section 2 if applicable, or aesthetic labeled honestly?+- [ ] **Redesign mode** detected and audit performed (if applicable, Section 11)?+- [ ] **ZERO em-dashes (`—`) anywhere on the page.** Headlines, eyebrows, pills, body, quotes, attribution, captions, buttons, alt text. Zero. (Section 9.G - non-negotiable.)+- [ ] **Page Theme Lock**: ONE theme (light, dark, or auto) for the whole page. No section flips to inverted mode mid-page (Section 4.11)?+- [ ] **Color Consistency Lock**: one accent color used identically across all sections (Section 4.2)?+- [ ] **Shape Consistency Lock**: one corner-radius system applied consistently (Section 4.4)?+- [ ] **Button Contrast Check**: every CTA text is readable against its background (no white-on-white, WCAG AA 4.5:1)?+- [ ] **CTA Button Wrap**: no CTA label wraps to 2+ lines at desktop?+- [ ] **Form Contrast Check**: form inputs, placeholders, focus rings, labels all pass WCAG AA against the section background?+- [ ] **Serif discipline**: if a serif is used, it is NOT Fraunces or Instrument_Serif (or it is, with explicit brand justification)? Different serif from your previous project?+- [ ] **Premium-consumer palette check**: if the brief is premium-consumer (cookware / wellness / artisan / luxury), the palette is NOT the AI-default beige+brass+oxblood+espresso family? Different family from your previous premium-consumer project?+- [ ] **Italic descender clearance**: every italic word with `y g j p q` has `leading-[1.1]` min + `pb-1` reserve?+- [ ] **Hero fits the viewport**: headline ≤ 2 lines, subtext ≤ 20 words AND ≤ 4 lines, CTA visible without scroll, font scale planned around image?+- [ ] **Hero top padding**: max `pt-24` at desktop, hero content does not float halfway down the viewport?+- [ ] **Hero stack discipline**: max 4 text elements in hero (eyebrow OR brand strip, headline, subtext, CTAs)? No tiny tagline below CTAs, no trust micro-strip in hero?+- [ ] **EYEBROW COUNT (mechanical)**: count instances of `uppercase tracking` micro-labels above section headlines across all components. Count ≤ ceil(sectionCount / 3)? Hero counts as 1.+- [ ] **Split-Header Ban**: no "left big headline + right small explainer paragraph" pattern as a section header (vertical stack instead)?+- [ ] **Zigzag Alternation Cap**: no 3+ consecutive sections with the same image+text-split layout?+- [ ] **No Duplicate CTA Intent**: no two CTAs with the same intent ("Get in touch" + "Let's talk" both on page = Fail)?+- [ ] **Logo wall = logo only**: no industry / category labels printed below logos?+- [ ] **Bento Background Diversity**: at least 2-3 bento cells have real visual variation (image, gradient, pattern), not all white-on-white text cards?+- [ ] **"Used by / Trusted by" logo wall** lives UNDER the hero, not inside it, uses REAL SVG logos (Simple Icons / devicon) or generated SVG marks, NOT plain text wordmarks?+- [ ] **Copy Self-Audit**: every visible string re-read, no grammatically-broken or AI-hallucinated phrases ("free on its past" type) shipped?+- [ ] **Motion motivated**: every animation can be justified in one sentence (hierarchy / storytelling / feedback / state transition), no GSAP-for-show?+- [ ] **Marquee max-one-per-page**: no two horizontal marquees on the same page?+- [ ] **Navigation on ONE line** at desktop, height ≤ 80px?+- [ ] **Section-Layout-Repetition** check: no two sections share the same layout family (at least 4 different families across 8 sections)?+- [ ] **Bento has rhythm AND exact cell count** (N items → N cells, no empty cells in middle or at end)?+- [ ] **Long lists use the right UI component** (not default `<ul>` with `divide-y` for > 5 items - see Section 4.9 alternatives)?+- [ ] **Real images used** (gen-tool first, then Picsum-seed, then explicit placeholder slots) - NO div-based fake screenshots, NO hand-rolled decorative SVGs, NO pure-text minimalism?+- [ ] **No pills/labels overlaid on images** (no `Plate · Brand`, no `Field notes - journal`)?+- [ ] **No photo-credit captions as decoration** (`Field study no. 12 · Ines Caetano`)?+- [ ] **No version footers** (`v1.4.2`, `Build 0048`) on marketing pages?+- [ ] **No micro-meta-sentences** under eyebrows ("Each of these is a feature we ship today...")?+- [ ] **No decoration text strip at hero bottom** (`BRAND. MOTION. SPATIAL.`)?+- [ ] **No floating top-right sub-text** in section headings?+- [ ] **No scoring/progress bars with filled background tracks** as comparison visuals?+- [ ] **No locale / city-name / time / weather strips** unless brief is genuinely globally-distributed or place-focused?+- [ ] **No scroll cues** (`Scroll`, `↓ scroll`, `Scroll to explore`)?+- [ ] **No version labels in hero** (V0.6, BETA, INVITE-ONLY) unless the brief is a launch?+- [ ] **No section-numbering eyebrows** (`00 / INDEX`, `001 · Capabilities`, `06 · how it works`)?+- [ ] **No decorative dots** (zero by default, only for real semantic state)?+- [ ] **No `border-t` + `border-b` on every row** of long lists / spec tables?+- [ ] **Content density** sane: no 20-row data tables, no fake-precise specs without justification, ≤ 25-word sub-paragraphs by default?+- [ ] **Quotes ≤ 3 lines** of body, attribution clean (no em-dash)?+- [ ] **Motion claimed = motion shown**: if `MOTION_INTENSITY > 4`, page actually animates, not just claimed?+- [ ] **GSAP sticky-stack / horizontal-pan** implemented per Section 5.A / 5.B canonical skeleton (`start: "top top"`, `pin: true`, correct scrub)?+- [ ] **No `window.addEventListener('scroll')`** - using Motion `useScroll()` / ScrollTrigger / IntersectionObserver / CSS scroll-driven animations only?+- [ ] **Reduced motion** wrapped for everything `MOTION_INTENSITY > 3`?+- [ ] **Dark mode** tokens defined and tested in both modes?+- [ ] **Mobile collapse** explicit (`w-full`, `px-4`, `max-w-7xl mx-auto`) for high-variance layouts?+- [ ] **Viewport stability**: `min-h-[100dvh]`, never `h-screen`?+- [ ] **`useEffect` animations** have strict cleanup functions?+- [ ] **Empty / loading / error** states provided?+- [ ] **Cards omitted** in favor of spacing where possible?+- [ ] **Icons** from an allowed library only (Phosphor / HugeIcons / Radix / Tabler), no hand-rolled SVG paths?+- [ ] **Motion** isolated in client-leaf components with `'use client'` at the top, memoized?+- [ ] **No AI Tells** from Section 9 (Inter as default, AI-purple, three-equal cards, Jane Doe, Acme, "Quietly in use at")?+- [ ] **Core Web Vitals** plausibly hit (LCP < 2.5s, INP < 200ms, CLS < 0.1)?+- [ ] **One design system** per project (no Material + shadcn mixed)?++If a single checkbox cannot be honestly ticked, the page is not done. Fix it before delivering.++---++# APPENDICES - Real Source-Backed Reference Material++The sections below are vendored reference content. They give the agent real install commands, real canonical doc links, and real working starter snippets for each design system named in Section 2. Use them to ground decisions in production reality, not training-data fiction.++## Appendix A - Install Commands per Design System++```bash+# Material Web (Material 3)+npm install @material/web++# Fluent UI React (v9)+npm install @fluentui/react-components++# Fluent UI Web Components (framework-free)+npm install @fluentui/web-components @fluentui/tokens++# IBM Carbon+npm install @carbon/react @carbon/styles++# Radix Themes+npm install @radix-ui/themes++# shadcn/ui (open code, owned components)+npx shadcn@latest init+npx shadcn@latest add button card badge separator input++# Primer CSS (GitHub product/devtool UI)+npm install --save @primer/css++# Primer Brand (GitHub marketing UI)+npm install @primer/react-brand++# GOV.UK Frontend+npm install govuk-frontend++# USWDS (US Web Design System)+npm install uswds++# Atlassian Design System (Atlaskit)+yarn add @atlaskit/css-reset @atlaskit/tokens @atlaskit/button @atlaskit/badge @atlaskit/section-message @atlaskit/card++# Bootstrap 5.3+npm install bootstrap++# Shopify Polaris Web Components (Shopify apps only)+# Add this to your app HTML head:+# <meta name="shopify-api-key" content="%SHOPIFY_API_KEY%" />+# <script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>+```++## Appendix B - Canonical Sources (read these before reinventing)++### Material Web+- https://github.com/material-components/material-web+- https://material-web.dev/theming/material-theming/+- https://m3.material.io/develop/web++### Fluent UI+- https://fluent2.microsoft.design/get-started/develop+- https://fluent2.microsoft.design/components/web/react/+- https://github.com/microsoft/fluentui+- https://learn.microsoft.com/en-us/fluent-ui/web-components/++### Carbon+- https://carbondesignsystem.com/+- https://github.com/carbon-design-system/carbon+- https://carbondesignsystem.com/developing/react-tutorial/overview/+- https://carbondesignsystem.com/developing/web-components-tutorial/overview/++### Shopify Polaris+- https://shopify.dev/docs/api/app-home/web-components+- https://github.com/Shopify/polaris-react+- https://polaris-react.shopify.com/components++### Atlassian+- https://atlassian.design/get-started/develop+- https://atlassian.design/components/button/examples+- https://atlaskit.atlassian.com/packages/design-system/button/example/disabled+- https://atlassian.design/tokens/design-tokens++### Primer+- https://primer.style/+- https://github.com/primer/css+- https://github.com/primer/brand++### GOV.UK+- https://design-system.service.gov.uk/components/button/+- https://design-system.service.gov.uk/styles/layout/+- https://github.com/alphagov/govuk-frontend++### USWDS+- https://designsystem.digital.gov/documentation/developers/+- https://designsystem.digital.gov/components/button/+- https://designsystem.digital.gov/components/card/+- https://github.com/uswds/uswds++### Bootstrap+- https://getbootstrap.com/docs/5.3/layout/grid/+- https://getbootstrap.com/docs/5.3/components/card/++### Tailwind+- https://tailwindcss.com/docs/dark-mode+- https://tailwindcss.com/blog/tailwindcss-v4++### Radix+- https://www.radix-ui.com/themes/docs/components/theme+- https://www.radix-ui.com/themes/docs/components/card+- https://github.com/radix-ui/themes++### shadcn/ui+- https://ui.shadcn.com/docs+- https://ui.shadcn.com/docs/components/card+- https://github.com/shadcn-ui/ui++### Native CSS / W3C standards+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/backdrop-filter+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme+- https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion+- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout+- https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Scroll-driven_animations+- https://drafts.csswg.org/scroll-animations-1/++### Apple Liquid Glass (Apple platforms only)+- https://developer.apple.com/design/human-interface-guidelines/materials+- https://developer.apple.com/documentation/TechnologyOverviews/liquid-glass+- https://developer.apple.com/documentation/TechnologyOverviews/adopting-liquid-glass+- https://developer.apple.com/documentation/SwiftUI/Material++---++## Appendix C - Apple Liquid Glass: Honest Web Approximation++Do **not** treat random CSS snippets as official Apple Liquid Glass.++### What is official+Apple documents Liquid Glass inside Apple's Human Interface Guidelines and Developer Documentation for **Apple platforms**. It is a dynamic material used across Apple platform UI. Apple's native implementation belongs to Apple platform APIs and system components, **not a public web CSS package**.++Relevant official docs:+- Apple Human Interface Guidelines → Materials+- Apple Developer Documentation → Liquid Glass+- Apple Developer Documentation → Adopting Liquid Glass+- SwiftUI → Material++### What is NOT official+There is no `liquid-glass.css` from Apple for normal websites.++A web approximation can use:+- `backdrop-filter`+- transparent backgrounds+- layered borders+- highlight overlays+- gradients+- motion+- strong contrast fallbacks++But that is **web glassmorphism / frosted-glass approximation**, not official Apple Liquid Glass. Label it as such in comments.++### Safer web approximation skeleton++```css+.liquid-glass-web-approx {+ position: relative;+ isolation: isolate;+ overflow: hidden;+ border-radius: 999px;+ border: 1px solid rgb(255 255 255 / .32);+ background:+ linear-gradient(135deg, rgb(255 255 255 / .30), rgb(255 255 255 / .08)),+ rgb(255 255 255 / .12);+ backdrop-filter: blur(24px) saturate(180%) contrast(1.05);+ -webkit-backdrop-filter: blur(24px) saturate(180%) contrast(1.05);+ box-shadow:+ inset 0 1px 0 rgb(255 255 255 / .48),+ inset 0 -1px 0 rgb(255 255 255 / .12),+ 0 18px 60px rgb(0 0 0 / .18);+}++.liquid-glass-web-approx::before {+ content: "";+ position: absolute;+ inset: 0;+ z-index: -1;+ border-radius: inherit;+ background:+ radial-gradient(circle at 20% 0%, rgb(255 255 255 / .55), transparent 34%),+ linear-gradient(90deg, rgb(255 255 255 / .18), transparent 42%, rgb(255 255 255 / .14));+ pointer-events: none;+}++.liquid-glass-web-approx::after {+ content: "";+ position: absolute;+ inset: 1px;+ border-radius: inherit;+ border: 1px solid rgb(255 255 255 / .14);+ pointer-events: none;+}++@media (prefers-color-scheme: dark) {+ .liquid-glass-web-approx {+ border-color: rgb(255 255 255 / .18);+ background:+ linear-gradient(135deg, rgb(255 255 255 / .16), rgb(255 255 255 / .04)),+ rgb(15 23 42 / .42);+ box-shadow:+ inset 0 1px 0 rgb(255 255 255 / .22),+ 0 18px 60px rgb(0 0 0 / .42);+ }+}++@media (prefers-reduced-transparency: reduce) {+ .liquid-glass-web-approx {+ background: rgb(255 255 255 / .96);+ backdrop-filter: none;+ -webkit-backdrop-filter: none;+ }+}+```++**Important:** `prefers-reduced-transparency` has uneven browser support; test it. Always provide enough contrast even without blur.++---++**End of appendices.** Install commands above are reality anchors. The Apple Liquid Glass skeleton is a labeled approximation, not an Apple-issued package. For canonical docs per design system, consult the system's official docs (links in Section 2 plus Appendix B).diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.jsonindex c8680bc..6e37f55 100644--- a/.cursor-plugin/plugin.json+++ b/.cursor-plugin/plugin.json@@ -1,8 +1,8 @@{"name": "cog-second-brain","displayName": "COG: Agentic Second Brain",- "version": "3.8.0",- "description": "Self-evolving second brain powered by AI agents, Obsidian markdown, and Git. 31 skills, 10 agents (6 workers + 4 read-only verifiers), people CRM with tiered enrichment. Closed-loop harness release: V-model verification lifecycle with criterion-traced evidence, risk lanes, multi-session ultragoals with a north-star acceptance gate, and craft skills for writing and visuals. Works with Claude Code, Cursor, Kiro, Gemini CLI, and Codex.",+ "version": "3.8.1",+ "description": "Self-evolving second brain powered by AI agents, Obsidian markdown, and Git. 33 skills, 10 agents (6 workers + 4 read-only verifiers), people CRM with tiered enrichment. Closed-loop harness release: V-model verification lifecycle with criterion-traced evidence, risk lanes, multi-session ultragoals with a north-star acceptance gate, craft skills for writing and visuals, and paired anti-slop design skills for marketing and product UI. Works with Claude Code, Cursor, Kiro, Gemini CLI, and Codex.","author": {"name": "Huy Tieu","email": "[email protected]",@@ -195,6 +195,16 @@"name": "daily-journal","path": ".claude/skills/daily-journal/SKILL.md","description": "A passive daily work journal the agent keeps for you - appends entries after meaningful work, runs a guided reflection on request"+ },+ {+ "name": "taste-skill",+ "path": ".claude/skills/taste-skill/SKILL.md",+ "description": "Anti-slop frontend skill for landing pages, portfolios, and redesigns - reads the brief, states a design read, and ships interfaces that do not look templated"+ },+ {+ "name": "product-ui-taste",+ "path": ".claude/skills/product-ui-taste/SKILL.md",+ "description": "Anti-slop skill for dense product surfaces (dashboards, tables, forms, wizards, admin consoles) - frame-first, correct at every edge case real data produces"}],"agents": [diff --git a/.github/MARKETPLACE.md b/.github/MARKETPLACE.mdindex 093dfff..0dacb3a 100644--- a/.github/MARKETPLACE.md+++ b/.github/MARKETPLACE.md@@ -18,13 +18,13 @@ COG ships marketplace metadata in multiple formats:| File | Platform | Purpose ||---|---|---|-| `.claude-plugin/plugin.json` | Claude Code marketplace | Canonical skill manifest (31 skills, 10 agents) |+| `.claude-plugin/plugin.json` | Claude Code marketplace | Canonical skill manifest (33 skills, 10 agents) || `.cursor-plugin/plugin.json` | cursor.directory | Cursor-compatible manifest || `.cursorrules` | Cursor | Editor rules for Cursor users || `marketplace-entry.json` | General marketplaces | Lightweight catalog entry || `AGENTS.md` | Universal | Command reference for any markdown-reading agent |-Current packaged version: **3.8.0**+Current packaged version: **3.8.1**## Surface Model@@ -32,9 +32,9 @@ COG is a **multi-agent package**, not a single-surface plugin:| Surface | Coverage ||---|---:|-| Claude Code (`.claude/skills/`) | 31 native skills + 10 agents (6 workers + 4 verifiers) |+| Claude Code (`.claude/skills/`) | 33 native skills + 10 agents (6 workers + 4 verifiers) || Cursor (`.cursor-plugin/`) | Plugin manifest + rules |-| Universal docs (`AGENTS.md`) | 31+ documented commands |+| Universal docs (`AGENTS.md`) | 33+ documented commands || Kiro (`.kiro/powers/`) | 7 core powers || Gemini CLI (`.gemini/commands/`) | 7 core commands |diff --git a/AGENTS.md b/AGENTS.mdindex 4aec0d9..d8ddbba 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -561,7 +561,52 @@ The following 5 skills implement the V-model closed loop described in `WORKFLOW.### Craft Skills-The following 5 skills raise output quality on writing and visual work. They encode taste as mechanical rules rather than vibes.+The following 7 skills raise output quality on writing and visual work. They encode taste as mechanical rules rather than vibes.++---++### /taste-skill++**Description:** Anti-slop frontend skill for **landing pages, portfolios, and redesigns**. Reads the brief, infers the right design direction, and ships interfaces that do not look templated.++**Triggers:**+- Building or redesigning a landing page, portfolio, marketing site, or editorial page+- "make this look less generic / less templated"+- A brief that names a vibe ("Linear-style", "brutalist", "editorial", "premium consumer") or links a reference++**Purpose:** Most LLM design output is bad because the model jumps to a default aesthetic instead of reading the room. This forces a **Design Read** first: page kind, audience, vibe signals, existing brand assets, and quiet constraints (accessibility-first, regulated, trust-first commerce) that override aesthetic preference.++**What it does:**+1. Infers the brief and states a one-line **Design Read** before writing any code+2. Sets explicit dials (variance, motion, density) rather than defaulting+3. Picks a real design system when one applies, instead of hand-rolling+4. Audit-first on redesigns: existing brand assets are starting material, not optional input+5. Runs a strict pre-flight check before shipping++**Boundary:** Landing, portfolio, marketing, editorial. It hands off dashboards, data tables, and multi-step product UI to `/product-ui-taste`. Never run both on the same component.++---++### /product-ui-taste++**Description:** Anti-slop skill for **dense product surfaces**: dashboards, data tables, forms, wizards, settings, list/detail, admin consoles, app shells. Budgets the frame first and ships interfaces that survive real data.++**Triggers:**+- Building a dashboard, index table, detail view, settings page, or multi-step flow+- "the table breaks with real data"+- Any admin console or internal tool++**Purpose:** Marketing UI lives on first impression. Product UI lives on the **hundredth** use, under real data, by someone doing a job. The slop failure mode is different: not "templated aesthetic" but **a prototype that dies on contact with real data**. A table that scrolls the page sideways, a button that truncates its own label, one grey "no data" box reused for three different situations.++**What it does:**+1. States a one-line **Product Read** (surface type, user, density, data volume, consequence level, host system)+2. Sets three dials: `DENSITY`, `DATA_COMPLEXITY`, `CONSEQUENCE`+3. Resolves the host design system's **real** API before writing UI, never inventing component props+4. Budgets the frame in pixels top-down before any content+5. Enforces the anti-defaults: rows not card-soup, real empty/error/loading/permission-denied states, correct scroll ownership, sticky headers, frozen columns, z-index tiers+6. Covers the states marketing UI never has: read-only, permission-denied, plan-locked++**Boundary:** The counterpart to `/taste-skill`. Maps to Carbon, Polaris, Atlaskit, Fluent, Primer, Material 3, Radix/shadcn, and Ant.---diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dfe6d8e..45fe3c0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,25 @@All notable changes to COG (Cognition + Obsidian + Git) will be documented in this file.+## [3.8.1] - 2026-07-27++### Added++#### Paired anti-slop design skills (2)+The two skills held back from v3.8.0 pending a provenance check, now confirmed original and shipped. They are a **pair with a hard boundary**, because the two surfaces fail in opposite ways and a single "make it look good" skill gets both wrong.++- **`taste-skill`**: landing pages, portfolios, marketing, editorial. Most model design output is bad because it jumps to a default aesthetic instead of reading the room, so this forces a one-line **Design Read** (page kind, audience, vibe signals, existing brand assets, quiet constraints) before any code. Explicit variance/motion/density dials, real design systems where they apply, audit-first on redesigns, strict pre-flight check.+- **`product-ui-taste`**: dashboards, data tables, forms, wizards, settings, list/detail, admin consoles, app shells. Marketing UI lives on first impression; product UI lives on the hundredth use, under real data, by someone doing a job. The failure mode is not a templated aesthetic, it is a prototype that dies on contact with real data. Forces a **Product Read** and three dials (`DENSITY`, `DATA_COMPLEXITY`, `CONSEQUENCE`), budgets the frame in pixels top-down before content, and enforces the anti-defaults: rows instead of card-soup, correct scroll ownership, sticky headers, frozen-column offsets, z-index tiers, plus the states marketing UI never has (read-only, permission-denied, plan-locked).++**The boundary is the point.** `taste-skill` hands dense product UI to `product-ui-taste`; never run both on the same component. On a mixed brief (a landing page with an embedded live dashboard), `taste-skill` takes the hero and `product-ui-taste` takes the product surface.++Both resolve the host design system's **real** API before writing UI rather than inventing component props, and map across Carbon, Polaris, Atlaskit, Fluent, Primer, Material 3, Radix/shadcn, and Ant.++### Changed+- **Skill count 31 → 33** across all manifests, `AGENTS.md`, `README.md`, `SETUP.md`, `.github/MARKETPLACE.md`, and `docs/AGENT-SUPPORT.md`.+- `.gitignore` now covers harness runtime artifacts (`.claude/logs/`, `04-projects/harness/runs/`), which `checkpoint.sh` and `/execute` write per-user and which should never land in a user's commits.+- `.github/MARKETPLACE.md` release checklist gained the three steps that were being done by hand: refresh the packaged-version line, cut a GitHub Release, re-index the directories.+## [3.8.0] - 2026-07-27### The Closed-Loop Harnessdiff --git a/CLAUDE.md b/CLAUDE.mdindex 2fcf8c7..9baf37e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -244,7 +244,7 @@ Role packs live in `.claude/roles/`. New roles can be added by dropping a file f- `COMPETITIVE-WATCHLIST.md` — Companies/people being tracked### Framework files (updated via `cog-update.sh` or `/update-cog`)-- `.claude/skills/`: Claude Code skills (31 skills)+- `.claude/skills/`: Claude Code skills (33 skills)- `.claude/agents/` — Worker agent definitions (6 agents)- `.claude/roles/` — Role packs for personalized recommendations- `.kiro/powers/` — Kiro powersdiff --git a/COG-VERSION b/COG-VERSIONindex 1981190..f280719 100644--- a/COG-VERSION+++ b/COG-VERSION@@ -1 +1 @@-3.8.0+3.8.1diff --git a/README.md b/README.mdindex c18d983..0ccb505 100644--- a/README.md+++ b/README.md@@ -11,7 +11,7 @@```mermaidgraph LRA[You] -- natural language --> B[AI Agent]- B -- runs --> C[31 Skills]+ B -- runs --> C[33 Skills]C -- delegates to --> W[6 Workers]C -- verified by --> V[4 Read-Only Verifiers]C -- reads & writes --> D[.md Files]@@ -56,11 +56,11 @@ COG ships a **full Claude Code surface** plus **core native surfaces** for Kiro| Surface | Current support | Notes ||---|---|---|-| Claude Code | 31 native skills + 10 agents (6 workers + 4 verifiers) | Full first-class surface |+| Claude Code | 33 native skills + 10 agents (6 workers + 4 verifiers) | Full first-class surface || Cursor | Plugin manifest + rules | `.cursor-plugin/plugin.json` + `.cursorrules` || Kiro | 7 native powers | Core workflows today || Gemini CLI | 7 native commands | Core workflows today |-| `AGENTS.md` | 31 documented commands | Universal fallback for Codex and other agents |+| `AGENTS.md` | 33 documented commands | Universal fallback for Codex and other agents |Before publishing or updating framework files, run `./scripts/validate-agent-surface.sh` to catch drift between manifests, docs, and shipped files. See [docs/AGENT-SUPPORT.md](docs/AGENT-SUPPORT.md) for the detailed support matrix and contributor rules.@@ -134,6 +134,15 @@ The enforcement layer that keeps every other skill honest. Work walks a **V**: d| **museum-art** | Real public-domain artwork from museum open-access APIs instead of AI-generated or stock imagery | "Find a hero image for this post" || **daily-journal** | A passive work journal the agent keeps for you, plus a guided reflection on request | "Reflect on today" |+### Design Skills (Anti-Slop UI)++A paired set. `taste-skill` owns first-impression surfaces, `product-ui-taste` owns surfaces people use every day. Never run both on the same component.++| Skill | Owns | Try saying... |+|---|---|---|+| **taste-skill** | Landing pages, portfolios, marketing, editorial. States a "Design Read" before writing code so it stops defaulting to one house aesthetic | "Build a landing page for this" |+| **product-ui-taste** | Dashboards, data tables, forms, wizards, settings, admin consoles. Budgets the frame in px first, then survives real data: overflow, long labels, empty/error/permission-denied states | "Build the admin table for this" |+### Agents (Specialist Sessions)COG uses a worker agent architecture inspired by [garrytan/gstack](https://github.com/garrytan/gstack) specialist sessions and [garrytan/gbrain](https://github.com/garrytan/gbrain) knowledge patterns. Workers handle data-heavy tasks cheaply (Sonnet) while the lead session does reasoning (Opus).@@ -219,7 +228,7 @@ graph TD```COG-second-brain/-├── .claude/skills/ # Claude Code skills (31)+├── .claude/skills/ # Claude Code skills (33)├── .claude/agents/ # Worker agent definitions (6)├── .claude/roles/ # Role packs (7) — personalized recommendations├── .kiro/powers/ # Kiro powersdiff --git a/SETUP.md b/SETUP.mdindex ed32ac3..aad6baa 100644--- a/SETUP.md+++ b/SETUP.md@@ -44,10 +44,10 @@ That's it! You now have a working second brain.**What just happened?**- The cloned `COG-second-brain` folder IS your second brain- COG now exposes a clear multi-agent support matrix:- - `.claude/skills/` - 31 Claude Code skills (full surface)+ - `.claude/skills/` - 33 Claude Code skills (full surface)- `.kiro/powers/` - 7 Kiro powers (core workflows)- `.gemini/commands/` + `.gemini/skills/` - 7 Gemini CLI commands (core workflows)- - `AGENTS.md` - 31 documented commands for Codex and other agents+ - `AGENTS.md` - 33 documented commands for Codex and other agents- Onboarding will create your personalized directory structure- You can validate the packaged agent surfaces anytime with `./scripts/validate-agent-surface.sh`@@ -131,7 +131,7 @@ COG-second-brain/ # This is your second brain folder├── .claude/│ ├── agents/ # 6 worker agent definitions│ ├── roles/ # 7 role packs for personalized recommendations-│ └── skills/ # 31 Claude Code skills+│ └── skills/ # 33 Claude Code skills│ ├── onboarding/│ ├── braindump/│ ├── daily-brief/diff --git a/cog-update.sh b/cog-update.shindex 11d7b26..5684649 100755--- a/cog-update.sh+++ b/cog-update.sh@@ -71,6 +71,8 @@ FRAMEWORK_FILES=(".claude/skills/data-forms/SKILL.md"".claude/skills/museum-art/SKILL.md"".claude/skills/daily-journal/SKILL.md"+ ".claude/skills/taste-skill/SKILL.md"+ ".claude/skills/product-ui-taste/SKILL.md"# Role packs".claude/roles/_template.md"diff --git a/docs/AGENT-SUPPORT.md b/docs/AGENT-SUPPORT.mdindex 4956a7d..130d3c6 100644--- a/docs/AGENT-SUPPORT.md+++ b/docs/AGENT-SUPPORT.md@@ -8,7 +8,7 @@ This document is the packaging contract: it tells contributors and maintainers w| Surface | Shipped format | Coverage | Status ||---|---|---:|---|-| Claude Code | `.claude/skills/*/SKILL.md` | 31 skills | Full native surface |+| Claude Code | `.claude/skills/*/SKILL.md` | 33 skills | Full native surface || Universal agent docs | `AGENTS.md` | 17 commands | Full documented fallback || Kiro | `.kiro/powers/*/POWER.md` | 7 powers | Core workflows only || Gemini CLI | `.gemini/commands/*.toml` + `.gemini/skills/*.md` | 7 commands | Core workflows only |diff --git a/marketplace-entry.json b/marketplace-entry.jsonindex 6725478..cea047c 100644--- a/marketplace-entry.json+++ b/marketplace-entry.json@@ -6,8 +6,8 @@"email": "[email protected]","url": "https://github.com/huytieu"},- "description": "Self-evolving second brain with 31 AI skills, 10 agents, and people CRM. Closed-loop harness release: V-model verification lifecycle with criterion-traced evidence, read-only verifier agents, risk lanes, multi-session ultragoals with a north-star acceptance gate, and craft skills for writing and visuals. Inspired by Garry Tan's gstack and gbrain, and dwarves-kit. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex.",- "version": "3.8.0",+ "description": "Self-evolving second brain with 33 AI skills, 10 agents, and people CRM. Closed-loop harness release: V-model verification lifecycle with criterion-traced evidence, read-only verifier agents, risk lanes, multi-session ultragoals with a north-star acceptance gate, craft skills for writing and visuals, and paired anti-slop design skills for marketing and product UI. Inspired by Garry Tan's gstack and gbrain, and dwarves-kit. Works with Claude Code, Cursor, Kiro, Gemini CLI, Codex.",+ "version": "3.8.1","keywords": ["second-brain","garry-tan",@@ -29,7 +29,10 @@"closed-loop","verification-harness","ultragoal",- "evidence-ledger"+ "evidence-ledger",+ "design-systems",+ "anti-slop",+ "ui-ux"],"category": "productivity","homepage": "https://github.com/huytieu/COG-second-brain"