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.

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.

• "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."

• 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

8 / 6 / 4

• 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.

• 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.

• 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

  ).

• 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

  ).

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

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

<span>Acme Co</span>

• 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.

• 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>

• 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

• 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.

• 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 ( " ).

• 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.

• 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.

• 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.

• Animate ONLY

  transform

  and

  opacity

  . Never animate

  top

  ,

  left

  ,

  width

  ,

  height

  .
• Use

  will-change: transform

  sparingly - only on elements that will actually animate.

• 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.

• 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.

• 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.

• 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.

• 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

  .

• 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: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1), opacity 0.3s cubic-bezier(0.16, 1, 0.3, 1)

  (name the properties; never

  transition: all

  , which also animates layout properties off the GPU, see 6.A).

  animation-delay

  cascades for load-ins.
• 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.

• 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.

• 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)

  .

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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".

• 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.

• 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.

• 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 / 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.