designing-tasteful-frontends

name

designing-tasteful-frontends

description

Upgrades AI-built frontends (landing pages, portfolios, marketing sites) to premium, Awwwards-level quality. Forces the agent to read the brief, infer a visual direction, set layout/motion/density dials, map requests to official design systems, and run a strict 50+ item pre-flight checklist. Lazy-loads specialized aesthetic profiles (Soft Tactile, Minimalist Editorial, Industrial Brutalist) and the Image-to-Code visual workflow. Bans common AI tells like purple glows, Inter font defaults, em-dashes, and repetitive three-card grids. Use when building highly aesthetic web frontends. Don't use for data-heavy dashboards, backend APIs, or strict brand compliance tasks like accessibility checks or layout standardizing—use `applying-marketing-web-standards` for those.

Designing Tasteful Frontends: Anti-Slop Web Architecture

This skill governs the generation of highly aesthetic, premium, and custom web frontends. It actively suppresses the standard "AI slop" clichés generated by LLM coding agents, replacing them with professional layout asymmetry, calibrated typography, motivated motion, and clean, intentional spacing.

[!IMPORTANT] This skill is for landing pages, portfolios, and marketing sites — not dashboards, data tables, or multi-step product UIs. Every rule is context-aware: read the room first.

---

1. Brief Inference & Aesthetic Calibration

Before writing any code or tweaking dials, you must infer the target visual direction. Most AI design is poor because models jump to a generic default instead of reading the room.

1.A The "Design Read" One-Liner

Before outputting any code, you MUST output a single line: "Reading this as: <page kind> for <audience>, with a <vibe> language, leaning toward <design system or aesthetic family>."

• Example: "Reading this as: B2B SaaS landing for technical buyers, with a Linear-style minimalist language, leaning toward Tailwind utilities + Geist + restrained motion."

1.B Lazy-Loading Aesthetic & Workflow Profiles

Once you declare the "Design Read" above, you must immediately open and read the corresponding reference file if the aesthetic or workflow matches:

• If the vibe is premium consumer, health, luxury, or interactive portfolio $\rightarrow$ Load aesthetic-soft-tactile.md (enforces Double-Bezel nested cards, button-in-button CTAs, and spring motion curves).
• If the vibe is Notion/Linear-style, clean workspace, documentation, or editorial $\rightarrow$ Load aesthetic-minimalist-editorial.md (enforces warm bone off-white canvas, spot pastels, ultra-flat 1px borders, and physical keyboard Micro-UIs).
• If the vibe is cybernetic, mechanical, aerospace blueprint, raw industrial, or high-density data $\rightarrow$ Load aesthetic-industrial-brutalist.md (enforces Swiss print, CRT telemetry, absolute-zero corner radius, and ASCII symbols).
• If the task is highly visual and image generation tools are available in the environment $\rightarrow$ Load workflow-image-to-code.md (enforces the image $\rightarrow$ analyze $\rightarrow$ code pipeline).

1.C The Three Dials

Calibrate three dials (scale 1-10) based on your inferred design profile to drive all layout, motion, and density decisions:

• DESIGN_VARIANCE (1 = Perfect Symmetry, 10 = Asymmetric Artsy Chaos)
• MOTION_INTENSITY (1 = Static, 10 = Cinematic Scroll & Physics)
• VISUAL_DENSITY (1 = Airy Art Gallery, 10 = Packed Telemetry Cockpit)

Use-Case Dial Presets

Use Case	VARIANCE	MOTION	DENSITY
Landing (SaaS Mainstream)	7	6	4
Landing (Agency / Creative)	9	8	3
Portfolio (Designer / Creative)	8	7	3
Portfolio (Developer)	6	5	4
Editorial / Blog	6	4	3
Trust-Critical / Public Sector	3	2	5

---

2. Core Architecture & Conventions

Unless the brief maps to an official enterprise design system (see design-systems.md), use these default conventions:

2.A The Premium Tech Stack

• Framework: React or Next.js (Default to Server Components (RSC) for static shells, and isolate motion/interactivity into "use client" leaf components).
• Styling: Tailwind CSS v4.
• Animation: Motion (formerly Framer Motion), imported from motion/react (import { motion } from "motion/react").
• Icons: phosphor-icons (@phosphor-icons/react), hugeicons (hugeicons-react), or Radix icons. Banned: lucide-react (unless explicitly requested). Std stroke width: 1.5 or 2.0.
• Fonts: Always use next/font (Next.js) or self-hosted @font-face with font-display: swap.

2.B State Management & Viewports

• Continuous Values: NEVER use React useState to track continuous inputs (mouse position, scroll progress, pointer physics). Use Motion's useMotionValue, useTransform, or useScroll.
• Viewport Stability: NEVER use h-screen for full-height hero sections. Use min-h-[100dvh] to prevent iOS Safari viewport jumping.
• Grid over Flex-Math: NEVER use complex flexbox percentage math (e.g., w-[calc(33%-1rem)]). Use CSS Grid (grid grid-cols-1 md:grid-cols-3 gap-6).

---

3. Design Engineering Directives

You must proactively override the standard AI defaults. Apply the following strict aesthetic guidelines:

3.A Typography & Pairings

• Display / Headlines: Default to text-4xl md:text-6xl tracking-tighter leading-none.
• Body: Default to text-base text-gray-600 leading-relaxed max-w-[65ch].
• Sans Font Choice: Discourage Inter as a default. Prefer Geist, Satoshi, Outfit, or Cabinet Grotesk.
• Serif Discipline: Serif is strongly discouraged as a default "creative" font. Use it only when the brand specifically demands it, and rotate from a premium pool (e.g., PP Editorial New, GT Sectra, Recoleta, Cormorant Garamond). Banned: Fraunces and Instrument_Serif as defaults.
• Italic Descender Clearance: When using italics in display type, descenders (y g j p q) will clip under tight line heights. Use leading-[1.1] minimum and add pb-1 or mb-1 padding.

3.B Color Calibration & Theme Lock

• Accents: Max 1 accent color, saturation under 80%. Lock this accent color across the entire page (no changing accent colors mid-page).
• Banned Palettes: Banned as a premium-consumer default background: warm beige/cream (#f5f1ea) paired with brass/clay (#b08947) and espresso text (#1a1714). Rotate to cold luxury, forest, terracotta, or pure monochrome.
• Theme Lock: The page has ONE theme (light, dark, or auto). Do not flip backgrounds from dark to light mid-scroll.

3.C Layout & Whitespace

• Anti-Center Bias: Centered Hero/H1 sections are avoided when DESIGN_VARIANCE > 4. Use asymmetric splits or left-aligned layouts.
• Hero Stack Discipline: Max 4 text elements in the hero:
  1. Eyebrow OR Brand Strip (pick zero or one)
  2. Headline (max 2 lines on desktop, $\le$ 6 words)
  3. Subtext (max 20 words, max 3-4 lines)
  4. CTAs (1 primary + max 1 secondary)
• Section Repetition Ban: A landing page with 8 sections must use at least 4 different layout families. Max 2 consecutive "left-image/right-text" zig-zag layouts.
• Eyebrow Restraint: An uppercase tracking eyebrow is allowed on at most 1 per 3 sections (including the hero). Count them across all sections: $\text{count} \le \lceil \text{sections} / 3 \rceil$.

3.D Systematic Spacing & Interaction Physics

• The 8pt Grid Discipline: All paddings, margins, gaps, and structural heights/widths must conform strictly to multiples of 8px (or 4px for fine micro-spacing, e.g., 1 unit = 4px in Tailwind). Avoid arbitrary values or odd spacing increments.
• The 5-State Control Matrix: All clickable or interactive elements (buttons, inputs, links) must support and style five distinct states:
  1. Default: Normal appearance with clear visual signifiers (color, border, or diffused shadow) indicating clickability.
  2. Hover: Subtle change in background opacity/hue (hover:bg-zinc-100), small scale lift (hover:scale-[1.01]), or directional translation.
  3. Active/Pressed: Real haptic click response via scale compression (active:scale-[0.98]).
  4. Focused: Clear, highly-visible keyboard focus rings (focus-visible:ring-2 focus-visible:ring-offset-2). Default browser outlines are banned.
  5. Disabled: Grayed-out design (opacity-50), removal of hover transforms, and explicit cursor-not-allowed pointer-events-none.
• 60-30-10 Color Allocation: Maintain a strict visual hierarchy using balanced colors:
  • 60% (Dominant Neutral): Main canvas backgrounds and structural shells (e.g., bg-zinc-50 / bg-zinc-950).
  • 30% (Secondary): Card/surface backgrounds, borders, dividers, secondary text (e.g., bg-white, border-zinc-200, text-zinc-500).
  • 10% (Accent): Highly targeted interactive actions, primary CTAs, active states, and focal highlights.
• Dark Mode Elevation-Lightening: When rendering in dark themes, mimic real-world lighting by progressively lightening elevated surfaces:
  • Level 0 (Background Canvas): Deepest dark tone (bg-zinc-950).
  • Level 1 (Card Panels/Surfaces): Slightly lighter surface tone (bg-zinc-900) with micro-borders.
  • Level 2 (Overlays/Modals/Dropdowns): Lightest surface tone (bg-zinc-800 or bg-zinc-850) combined with a soft ambient shadow and inner top highlights.

---

4. Choreographed Motion & Interaction

All motion must feel weighty, motivated, and simulate physical mass.

• Motivation: Every scroll trigger, marquee, or pinned panel must communicate hierarchy, storytelling, or feedback. If you cannot justify it in one sentence, keep it static.
• Reduced Motion: Any motion above MOTION_INTENSITY > 3 MUST honor prefers-reduced-motion using the useReducedMotion() hook or CSS media queries.
• Marquee Constraint: Horizontal scrolling text marquees are allowed at most once per page.
• Animations: Animate ONLY transform (scale, translate) and opacity. Never animate top, left, width, or height.

4.A Sticky-Stack Card Scroll (Canonical GSAP Skeleton)

Use this clean structure to stack cards dynamically on scroll:

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

---

5. References & Deep Context

For detailed specifications, visual vocabularies, and implementation guides, consult the following references:

• ai-tells.md: Complete catalog of banned AI visual, layout, and copywriting patterns (including the Em-Dash Ban).
• visual-vocabulary.md: Architectural patterns for Hero sections, Bento grids, and components.
• design-systems.md: Setup guide for official enterprise systems (Material Web, Fluent UI, Carbon, Primer, etc.).
• aesthetic-soft-tactile.md: Luxury/spring motion/nested cards double-bezel aesthetic.
• aesthetic-minimalist-editorial.md: Notion/Linear-style warm bone monochrome + spot pastel aesthetic.
• aesthetic-industrial-brutalist.md: Swiss print / CRT telemetry zero-radius brutalist aesthetic.
• workflow-image-to-code.md: Complete image-first visual design-to-code pipeline.
• agent-ready-ui.md: Architectural rules for building highly semantic, accessible, and AI-navigable/agent-ready structures.

---

6. Final Pre-Flight Check

Run this mechanical check before outputting any code. If any box fails, the output is not done.

• Design Read declared in one line?
• Dial values explicit and reasoned from the brief?
• ZERO em-dashes (—) or en-dashes (–) anywhere in the visible output?
• Page Theme Lock: Background remains in a single theme (light, dark, auto) without mid-page inversion?
• Color & Shape Consistency: Single accent color and uniform corner-radius system locked across all sections?
• Hero Viewport Fit: Headline $\le$ 2 lines, subtext $\le$ 20 words, CTA visible above fold, top padding cap $\le$ pt-24?
• Hero Stack Discipline: Max 4 text elements in the hero? No taglines under CTAs, no trust micro-strip inside the hero?
• Eyebrow Count (Mechanical): Total section eyebrows $\le \lceil \text{sections} / 3 \rceil$?
• Zigzag Alternation Cap: Max 2 consecutive sections using the same split image+text layout?
• Section-Layout-Repetition: No two sections share the exact same layout family ($\ge$ 4 families per 8 sections)?
• No Duplicate CTA Intent: No two CTAs on the page carry the same action intent (e.g., "Get in touch" + "Let's talk")?
• Bento Rhythm: Grids have exactly as many cells as there is content (no empty placeholder cells)?
• Real Images & SVG Logos: Real photos or PicSum seeds used (no div-based fake screenshots). Logo walls use SVG marks or Simple Icons, never plain text wordmarks?
• Quotes $\le$ 3 lines: Quote bodies compressed, attribution clean, no em-dashes?
• Hardware Acceleration: Only transform and opacity are animated?
• Reduced Motion: All animations wrapped under a prefers-reduced-motion check?
• GPU Protection: Grain/noise textures placed only on fixed, pointer-events-none overlays, never on scrolling containers?
• 8pt Spacing Discipline: All gaps, padding, and margins conform strictly to multiples of 4px/8px (e.g., p-2, gap-4, py-24)?
• Interactive 5-State Matrix: All buttons, links, and inputs support and explicitly style five distinct states (Default signifier, Hover color/transform, Active scale compression active:scale-[0.98], Focus-visible styled ring, and Disabled styles)?
• 60-30-10 Color Balance: Brand color ratio maintains 60% dominant neutral (canvas ground), 30% secondary (borders, surfaces, support text), and 10% accent maximum?
• Dark Mode Surface Elevation: In dark mode, elevated surfaces (modals, dropdowns, nested cards) are progressively lighter than the base canvas (bg-zinc-950 -> bg-zinc-900 -> bg-zinc-800) to simulate depth and light behavior?
• Agent-Ready Semantics: Page structure uses correct landmarks (, , ), sequential headings, and native buttons or interactive links (never
  click triggers)?
• Deterministic Data Anchors: Interactive targets and main interactive modules feature stable data-agent="..." attributes for robust LLM/agent automation?
• Accessible Label Completeness: Every image has contextual alt text, and icon-only components feature visually-hidden text labels or clear aria-label definitions?
• Strategic Product Alignment: The "Design Read" is accompanied by a brief storytelling rationale justifying the layout patterns based on high-agency product conversions and user flows?