Project Documentation

tasteskill: Anti-Slop Frontend Skill

由项目内 Markdown 源文件转换生成的 HTML 版本，用于浏览器阅读和团队共享。

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.

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

3.B State

3.C Icons

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

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

4.2 Color Calibration

4.3 Layout Diversification

4.4 Materiality, Shadows, Cards

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

4.7 Layout Discipline (Hard Rules. Failing any of these is shipping broken work)

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.

4.10 Quotes & Testimonials

4.11 Page Theme Lock (Light / Dark Mode Consistency)

The page has ONE theme. Sections do not invert.

5. CONTEXT-AWARE PROACTIVITY

These are tools, not defaults. Use them when the design read calls for them. None of these fire automatically.

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

6. PERFORMANCE & ACCESSIBILITY GUARDRAILS

6.A Hardware Acceleration

6.B Reduced Motion (mandatory)

6.C Dark Mode (mandatory for any consumer-facing page)

6.D Core Web Vitals Targets

6.E DOM Cost

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)

MOTION_INTENSITY (Level 1-10)

VISUAL_DENSITY (Level 1-10)

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)

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

9.B Typography

9.C Layout & Spacing

9.D Content & Data (“Jane Doe” Effect)

9.E External Resources & Components

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.

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

Layout & Grids

Cards & Containers

Scroll Animations

Galleries & Media

Typography & Text

Micro-Interactions & Effects

Animation Library Choice

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)

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

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

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

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

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.

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.

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

# 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

Fluent UI

Carbon

Shopify Polaris

Atlassian

Primer

GOV.UK

USWDS

Bootstrap

Tailwind

Radix

shadcn/ui

Native CSS / W3C standards

Apple Liquid Glass (Apple platforms only)

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

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