• View transitions now support concurrent and nested flows with element-scoped view transitions. Use element-scoped APIs to isolate route/section transitions and avoid global cross-fades when multiple transitions run in parallel. Prefer view transitions for route and layout changes and reserve JS choreography for complex narrative sequences.
• Scroll-triggered animations are available in newer Chrome builds. When possible prefer native scroll-triggered APIs for large, performance-sensitive scroll choreography and provide polyfills/fallbacks for broader support.
• Scoped custom element registries allow encapsulated web components in design systems — use scoped registries to prevent cross-package tag collisions and to safely mount multiple component libraries on the same page.
• Sanitizer API landed for safer HTML sanitization. Use it for sanitizing user or third-party content instead of ad-hoc regexes or string manipulation.

Core concepts

Art direction modes

Every project starts by picking one primary visual thesis. Do not mix modes without intent.

Motion layers

Motion is a three-layer system:

1. Ambient — slow loops, shader drift, environmental life that exists without user input
2. Interaction — hover, press, open, focus — immediate feedback tied to user actions
3. Narrative — scroll-driven and route-change choreography that guides the user through a story

One strong hero move beats many small distractions. If a page has a heavy 3D or shader hero, quiet the rest of the UI motion.

When route or layout transitions are involved, prefer the browser-level view transition APIs (use element-scoped view transitions for nested transitions). Use JS-driven narrative choreography only when you need fine-grained control that the native API can't provide.

Token system

Before building any component, define tokens for: color, spacing, radii, shadows, border weights, type scale, z-index, blur, motion duration/easing, and (new) text-shadow and mask tokens where your design needs them.

Workflow

1. Choose your art direction mode

Evaluate the product, audience, and competitive landscape. Pick one primary mode from the table above. Write it down in your project brief or design doc.

2. Set up the token system with Tailwind v4 @theme

• Tailwind v4 provides extra utilities (text-shadow, masks). Map these utilities to tokens instead of sprinkling utilities across components.
• If you use Tailwind Plus components, review the Tailwind Plus integration path (vanilla JS support may simplify non-framework usage).

Example token block (keep this canonical and copy-pasteable):

@theme {
  --color-surface: oklch(0.98 0.005 260);
  --color-surface-elevated: oklch(1 0 0);
  --color-accent: oklch(0.65 0.25 29);
  --color-accent-subtle: oklch(0.65 0.15 29 / 0.15);
  --color-text-primary: oklch(0.15 0.01 260);
  --color-text-secondary: oklch(0.45 0.01 260);

  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  --space-xl: 2.5rem;
  --space-2xl: 4rem;
  --space-3xl: 6rem;

  --radius-sm: 0.375rem;
  --radius-md: 0.75rem;
  --radius-card: 1rem;
  --radius-pill: 9999px;

  --shadow-subtle: 0 1px 2px oklch(0 0 0 / 0.05);
  --shadow-elevated: 0 4px 12px oklch(0 0 0 / 0.08), 0 1px 3px oklch(0 0 0 / 0.04);

  /* text-shadow tokens (use Tailwind v4 utilities via token mapping) */
  --text-shadow-soft: 0 1px 2px rgba(0,0,0,0.06);
  --text-shadow-strong: 0 6px 18px rgba(0,0,0,0.12);

  --font-display: "Instrument Serif", serif;
  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  --duration-fast: 120ms;
  --duration-normal: 250ms;
  --duration-slow: 500ms;
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
}

3. Wire up the Motion component layer

import { motion } from "motion/react";

function HeroHeadline({ children }: { children: React.ReactNode }) {
  return (
    <motion.h1
      initial={{ opacity: 0, y: 24, filter: "blur(8px)" }}
      animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
      transition={{ duration: 0.6, ease: [0.16, 1, 0.3, 1] }}
      className="font-display text-5xl text-text-primary"
    >
      {children}
    </motion.h1>
  );
}

When using route changes, prefer view transitions for layout swaps and reserve motion libraries for layered or sequenced narrative effects that need replay or complex timing.

4. Layer in GSAP for scroll choreography (when needed)

import { useRef, useEffect } from "react";
import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";

gsap.registerPlugin(ScrollTrigger);

function ScrollSection() {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const ctx = gsap.context(() => {
      gsap.from(".reveal-item", {
        y: 60,
        opacity: 0,
        stagger: 0.12,
        scrollTrigger: {
          trigger: ref.current,
          start: "top 80%",
        },
      });
    }, ref);
    return () => ctx.revert();
  }, []);

  return <div ref={ref}>{/* children */}</div>;
}

Prefer native scroll-triggered APIs when available; use GSAP or a polyfill only when you need cross-browser consistency or richer sequencing.

5. Review against craft benchmarks

Compare your output against manual-grade references: userinterface.wiki, Rauno's site, Devouring Details, Interface Craft, UI Playbook. Ask: does this feel authored, or generated?

Examples

Example 1 — Premium AI SaaS hero section

Token-driven, restrained depth, subtle ambient motion:

<section className="relative overflow-hidden bg-surface px-space-xl py-space-3xl">
  <motion.div
    initial={{ opacity: 0, y: 32 }}
    animate={{ opacity: 1, y: 0 }}
    transition={{ duration: 0.7, ease: [0.16, 1, 0.3, 1] }}
    className="mx-auto max-w-3xl text-center"
  >
    <h1 className="font-display text-6xl text-text-primary text-balance">
      Intelligence you can trust
    </h1>
    <p className="mt-space-md text-lg text-text-secondary">
      Enterprise AI infrastructure that scales with your ambition.
    </p>
  </motion.div>
</section>

Example 2 — Neo-brutalist card

High contrast, raw borders, no soft shadows:

<div className="border-2 border-text-primary bg-surface p-space-lg">
  <h3 className="font-mono text-sm uppercase tracking-widest text-accent">
    Module 04
  </h3>
  <p className="mt-space-sm font-sans text-xl font-bold text-text-primary">
    Break every assumption about what a card should look like.
  </p>
</div>

Decision tree

• Need a distinctive landing page? → Start here with art direction mode selection
• Need component animation? → Use Motion (Framer Motion skill)
• Need scroll choreography? → Use GSAP + ScrollTrigger skill (or prefer native scroll-triggered APIs)
• Need 3D hero scene? → Use React Three Fiber skill
• Need token system only? → Use Tailwind Design System skill
• Need performance audit? → Use Web Performance skill
• Multiple concerns? → Start here, then delegate to specific skills

Edge cases and gotchas

1. Heavy animation + readability conflict — Above-the-fold copy and CTA must remain readable while motion runs. Test by pausing the animation: if the page makes no sense frozen, the hierarchy is wrong.
2. prefers-reduced-motion — Every ambient and narrative animation must degrade to static under prefers-reduced-motion: reduce. Interaction motion can simplify but should not vanish entirely (users still need feedback).
3. Mobile performance — Canvas, heavy blur, backdrop-filter, and large shadow animations are expensive on mobile. Profile on a real mid-range device, not just DevTools throttling.
4. Token drift — When tokens are not enforced, arbitrary values creep in within weeks. Use Tailwind's strict mode or a lint rule to flag raw values in design-critical properties.
5. Art direction scope creep — Mixing two modes (e.g., editorial + cinematic) almost always produces mud. Pick one, commit, and only borrow from another mode for a specific justified element.
6. Font loading flash — Display fonts cause layout shift if not preloaded. Use font-display: swap with a closely-matched system fallback and preload the font file.
7. Web components collisions — If your design system exposes custom elements, register them with a scoped registry to avoid cross-library tag collisions when multiple component sets coexist on a page.
8. Sanitizing HTML — Use the browser Sanitizer API for user or third-party HTML where available; keep a safe fallback sanitizer for other browsers.

Evaluation criteria

• A single art direction mode is chosen and documented
• Token system covers color, spacing, radii, shadow, type, motion, text-shadow/mask where used
• Tokens are defined in @theme before any component styling
• Motion follows the three-layer model (ambient, interaction, narrative)
• Hero focal point is singular and does not compete with other animations
• prefers-reduced-motion fallbacks are implemented
• Mobile performance is profiled on a real device
• No raw hex values, arbitrary spacing, or accidental radius drift
• Above-the-fold copy is readable while motion runs
• Output is compared against at least one craft reference

Research-backed changes

The biggest delta is Vanilla JavaScript support for Tailwind Plus. Fold the concrete changes into the operating notes, then discard the fluff.

Fresh signals

• Vanilla JavaScript support for Tailwind Plus · Tailwind CSS Blog
• Compass: A starter kit for online courses · Tailwind CSS Blog
• Tailwind CSS v4.1: Text shadows, masks, and tons more · Tailwind CSS Blog
• Tailwind UI is now Tailwind Plus · Tailwind CSS Blog

Next edits

• Add one new tactic based on Vanilla JavaScript support for Tailwind Plus.
• Rewrite one stale section with today's source language.
• Turn the top signal into a reusable agent prompt.

Fresh signals

• Blog · Tailwind CSS Blog
• Vanilla JavaScript support for Tailwind Plus · Tailwind CSS Blog
• Compass: A starter kit for online courses · Tailwind CSS Blog
• Tailwind CSS v4.1: Text shadows, masks, and tons more · Tailwind CSS Blog

Next edits

• Add one new tactic based on Blog.
• Rewrite one stale section with today's source language.
• Turn the top signal into a reusable agent prompt.

Fresh signals

• Blog · Tailwind CSS Blog
• Vanilla JavaScript support for Tailwind Plus · Tailwind CSS Blog
• Compass: A starter kit for online courses · Tailwind CSS Blog
• Tailwind CSS v4.1: Text shadows, masks, and tons more · Tailwind CSS Blog

Next edits

• Add one new tactic based on Blog.
• Rewrite one stale section with today's source language.
• Turn the top signal into a reusable agent prompt.