Design Taste Frontend

In this repo: Tailwind 4 (CSS-first config in apps/sim/app/_styles/globals.css); animation via import { motion } from 'framer-motion' (not motion/react — rewrite every motion/react import in the samples below); icons from @sim/emcn/icons; colors through the CSS-variable tokens in .claude/rules/sim-styling.md (no hardcoded text-gray-*/hex/zinc utilities, no paired dark: utilities). This note overrides any conflicting guidance or code sample anywhere in this file.

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)

1.B Use-Case Presets

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)

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.

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). Outside this repo import from motion/react; in this repo import from framer-motion (see the note at the top).
• 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

• Icons: in this repo, @sim/emcn/icons only — one family per tree, strokeWidth standardized. Outside this repo, pick one maintained library and standardize on it.

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: Default to a sans display face (Geist Display, ABC Diatype, Söhne Breit, Cabinet Grotesk Display, Migra Sans, GT Walsheim, Inter Display, PP Neue Montreal). Use a serif only when the brand names one or the aesthetic is genuinely editorial/luxury/heritage and you can say in one line why this serif fits this brand; Fraunces and Instrument Serif are the generic picks, so prefer another (PP Editorial New, GT Sectra Display, Reckless Neue, Tiempos Headline, Cormorant Garamond, EB Garamond, Domaine Display, Canela). Emphasize a word with italic or bold of the same family, not a second family.

• Italic descender clearance: 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: 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 palettes: For premium-consumer briefs (cookware, wellness, artisan, DTC home goods), the warm cream + brass/clay/oxblood + espresso palette is the generic default; choose the palette from the brand's own assets and state the reason in one line. Alternatives that read as premium without the cliché: cold silver/chrome, deep green + bone + amber, off-black + tan, cobalt + one neutral, terracotta + slate, olive + brick, monochrome + one saturated accent.

4.3 Layout Diversification

• Anti-center bias: Centered Hero / H1 sections are avoided when DESIGN_VARIANCE > 4. Prefer "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: no generic card containers. Data metrics breathe in plain layout.
• Shape consistency lock: 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 (a11y): Before shipping any button, verify the button text is readable against the button background: no white button + white text, no bg-white CTA with text-white label, no transparent button against the page background without a border. 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: Button text fits 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: 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 (a11y): Form inputs, placeholder text, focus rings, helper text, and error text all pass WCAG AA contrast against the section background: no light placeholders on a near-white form, no white form on a white section, no labels below 4.5:1. 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

• Hero fits 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: 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)
  • Not 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, not 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 renders 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 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: 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. 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. 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. 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 not a 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. 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 read as unfinished.

Priority order for visual assets:

1. Image-generation tool first. When an image-gen tool is available, use it for section-specific assets (hero photography, product shots, textures) at the section's aspect ratio.
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: 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

No div-based fake screenshots. 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. A long product specification table with border-b on every row is the generic default for cookware / hardware / apparel / artisan-goods briefs. 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 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 in quote text (Section 9.G).
• 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 with Motion's useMotionValue / useTransform outside the React render cycle, not 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 is motivated. 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: at most one per page. 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

"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

"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:

"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>
      ))}
    

…(truncated)