• Chrome (Mar 27, 2026)

  • Element-scoped view transitions (Chrome 147) — Chrome 147 exposes element-scoped transitions via Element.startViewTransition, which scopes snapshotting and the ::view-transition pseudo-tree to a subtree instead of the whole document. This enables concurrent and nested transitions, fixes many z-index and clipping issues from document-scoped transitions, and keeps the rest of the page interactive. See the Chrome guide and blog announcement: https://developer.chrome.com/docs/css-ui/view-transitions/element-scoped-view-transitions and https://developer.chrome.com/blog/element-scoped-view-transitions (Mar 27, 2026).

  • Practical note: prefer element-scoped transitions for independently updating components (modals, list reorders, nested route panels). When nesting, follow the docs for view-transition-name, containment, and clipping to avoid visual leakage.

  • Feature detection pattern (copy-pasteable, robust):

    // Support both Element.startViewTransition and document.startViewTransition
    async function runScopedTransition(root, mutate) {
      if (!root) return mutate();
    
      const start = root.startViewTransition;
      if (typeof start === 'function') {
        try {
          return root.startViewTransition(mutate);
        } catch (e) {
          // fall through to document-level or JS choreography
        }
      }
    
      if (typeof document.startViewTransition === 'function') {
        return document.startViewTransition(mutate);
      }
    
      // fallback: JS animation choreography (Motion, GSAP, or CSS transitions)
      return mutate();
    }
    

• Tailwind (v4.x)

  • Tailwind v4.1 adds utilities useful for art direction: text-shadow utilities, mask utilities, colored drop-shadows, pointer-aware device variants (pointer/any-pointer), items-baseline-last, safe alignment, and more. See the announcement on the Tailwind blog (v4.1).
  • Tailwind v4.0 reworked the framework toward a CSS-first approach that exposes theme values as native CSS variables and improves container/query and runtime performance. Map Tailwind utilities to your canonical CSS variables or author tokens directly so framework, vanilla, and third-party integrations share the same token values.

• Tailwind Plus (vanilla-JS Elements)

  • Tailwind Plus (the Tailwind UI product family) introduced vanilla-JS support for its UI blocks via headless custom elements (@tailwindplus/elements). Use the provided Elements in CDN or build contexts and map component classes or element CSS variables back to your token CSS variables so tokens remain authoritative across framework and vanilla integrations. See the Tailwind Plus blog and Elements docs for examples.

• Design tooling

  • Figma variables and token tooling: use variables to test font scaling and token variations in design so accessibility regressions surface in design review rather than code review.

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 browser-level view transition APIs (use element-scoped view transitions for nested or concurrent transitions). Use JS-driven narrative choreography only when you need fine-grained control that the native API does not 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.

Tailwind v4's CSS-first approach exposes theme values as native CSS variables. Prefer mapping Tailwind utilities to these variables (or author tokens directly in CSS using @theme) so tokens remain the single source of truth across components and third‑party bundles.

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 encourages defining tokens as native CSS variables so they can be consumed by vanilla JS bundles, web components, and third‑party widgets.
• Map new utilities (text-shadow, masks, colored drop-shadows, pointer-aware variants) to tokens instead of sprinkling class utilities directly across components.
• If migrating, follow the Tailwind upgrade guide and release notes. Install the latest packages and run your visual regression suite against a modern-browser matrix.

Example token block (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>

Tailwind Plus — mapping Elements to tokens (copy-pasteable)

If you use Tailwind Plus Elements (@tailwindplus/elements) in a vanilla context, ensure the elements pick up your token variables rather than hard-coded colors or sizes. The Elements library provides headless custom elements (<el-dropdown>, <el-menu>, etc.) which you style via classes or CSS. Example pattern:

1. Include Elements (CDN):

<script src="https://cdn.jsdelivr.net/npm/@tailwindplus/elements@1" type="module"></script>

2. Define your tokens in CSS (tokens.css):

:root {
  --color-accent: oklch(0.65 0.25 29);
  --color-surface: oklch(0.98 0.005 260);
  --space-md: 1rem;
  --radius-md: 0.75rem;
}

3. Map utilities or component variables to tokens so both Tailwind utilities and Elements styles use the same values. Example using a small CSS shim that Elements will inherit:

.el-theme { /* shim class applied to a root container */
  --tp-accent: var(--color-accent);
  --tp-surface: var(--color-surface);
  --tp-gap: var(--space-md);
  --tp-radius: var(--radius-md);
}

/* Optional: provide utility aliases for tokens if your build expects Tailwind variables */
.el-theme .btn-primary {
  background-color: var(--tp-accent);
  border-radius: var(--tp-radius);
}

4. Use Elements markup in your HTML and apply the shim class on a wrapper so the elements pick up the token values:

<div class="el-theme">
  <el-dropdown class="relative inline-block text-left">
    <button class="btn-primary">Options</button>
    <el-menu anchor="bottom end" popover class="w-56">...</el-menu>
  </el-dropdown>
</div>

This keeps tokens authoritative and prevents design drift when mixing Tailwind utilities, framework components, and vanilla Elements.

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 safelist/lint rules or a custom 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

• Chrome (Mar 27, 2026): element-scoped view transitions are shipping in Chrome 147 and enable concurrent and nested transitions for subtrees; prefer element-scoped transitions for isolated layout changes. (Chrome Developer Docs: https://developer.chrome.com/docs/css-ui/view-transitions/element-scoped-view-transitions — published Mar 27, 2026; blog: https://developer.chrome.com/blog/element-scoped-view-transitions)
• Tailwind v4.1: v4.1 adds text-shadow, mask utilities, colored drop-shadows, pointer-aware device variants, items-baseline-last, and safe alignment. (Tailwind Blog: https://tailwindcss.com/blog/tailwindcss-v4-1).
• Tailwind Plus (Tailwind UI → Tailwind Plus): Tailwind Plus provides UI blocks and vanilla-JS Elements (@tailwindplus/elements) — map element variables to your tokens when using these elements to keep tokens authoritative across frameworks. (Tailwind Plus docs: https://tailwindcss.com/plus/ui-blocks/documentation/elements).

Next edits

• Add one new tactic based on Tailwind Plus vanilla-JS integration (component mapping example) — done.
• Rewrite the platform notes with explicit links and dates (completed).
• Add a short agent prompt for upgrading a repo to Tailwind v4 (keep running checklist).

Quick upgrade prompt (agent-ready)

Upgrade this repo to Tailwind v4. Checklist:

1. Review Tailwind's official upgrade guide and release notes:
   • https://tailwindcss.com/docs/upgrade-guide
   • Release tag notes (example): https://github.com/tailwindlabs/tailwindcss/releases/tag/v4.1.0
2. Pin and install the target packages in a feature branch:

# choose the exact versions used in your project matrix
npm install tailwindcss@4.1.0 @tailwindcss/cli@latest

3. Update config and plugin changes per the upgrade guide; run unit tests.
4. Run visual regression tests across a modern-browser matrix (include Chrome 147+ to validate view transitions where used).
5. If you use Tailwind Plus Elements, include @tailwindplus/elements and map element variables to your tokens as shown in the Tailwind Plus docs.