• Chrome (Mar 27, 2026)

  • Element-scoped view transitions (Chrome 147) — Chrome 147 (docs published Mar 27, 2026) exposes element-scoped transitions via element.startViewTransition(), which lets you start a view transition on a subtree rather than the whole document. This enables concurrent and nested transitions and avoids many layering and clipping issues caused by document-scoped transitions. Prefer element-scoped transitions for isolated subtree changes and nested route updates. See the Chrome guide: https://developer.chrome.com/docs/css-ui/view-transitions/element-scoped-view-transitions and the Chrome blog announcement: https://developer.chrome.com/blog/element-scoped-view-transitions.

  • Practical note: use element-scoped transitions for components/regions that update independently (e.g., modals, list reorders, nested route panels). When nesting, follow view-transition-name containment and clipping guidance in the docs to avoid visual leakage.

  • Feature detection pattern (copy-pasteable):

    // prefer element-scoped transitions when available
    const root = document.querySelector('#region');
    if (root && typeof root.startViewTransition === 'function') {
      root.startViewTransition(() => { /* mutate subtree */ });
    } else if (typeof document.startViewTransition === 'function') {
      document.startViewTransition(() => { /* mutate document */ });
    } else {
      // fallback: JS animation choreography (Motion, GSAP, or CSS transitions)
    }
    

• Tailwind (v4.x)

  • Tailwind v4.0 (released Jan 22, 2025) is a CSS-first rework that exposes theme values as native CSS variables and introduces a high-performance engine, container-query support, and a CSS-first configuration experience: https://tailwindcss.com/blog/tailwindcss-v4.

  • Tailwind v4.1 (Apr 3, 2025) adds utilities directly 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 v4.1 announcement for specifics: https://tailwindcss.com/blog/tailwindcss-v4-1.

  • Migration basics (copy-pasteable): consult Tailwind's official upgrade guide and release notes for exact checks and breaking changes. A minimal install step (replace @latest with a concrete version in CI if you pin):

    npm install tailwindcss@latest @tailwindcss/cli@latest
    # run your project's Tailwind upgrade checks and visual regressions
    

  • Theme and tokens: Tailwind v4's CSS-first approach exposes theme values as native CSS variables. Prefer mapping Tailwind utilities to your canonical CSS variables or author tokens directly in CSS so third-party bundles and vanilla integrations consume the same token values.

• Tailwind Plus (vanilla-JS Elements)

  • Tailwind Plus announced vanilla-JS support for its UI blocks (Elements) on July 25, 2025. @tailwindplus/elements provides headless custom elements you can include via a CDN and style with utilities or CSS: https://tailwindcss.com/blog/vanilla-js-support-for-tailwind-plus.
  • When using Tailwind Plus Elements in non-framework contexts, map component classes or element variables back to your token CSS variables so tokens remain authoritative across framework and vanilla integrations. The mapping pattern below is copy-pasteable.

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

Feature-detection pattern (element-scoped view transitions fallback):

if (element && typeof element.startViewTransition === 'function') {
  element.startViewTransition(() => {
    // mutate the subtree under `element` synchronously
  });
} else if (typeof document.startViewTransition === 'function') {
  document.startViewTransition(() => {
    // mutate document
  });
} else {
  // fallback: JS animation choreography (Motion, GSAP, or CSS transitions)
}

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 (see Platform notes) 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; blog: https://developer.chrome.com/blog/element-scoped-view-transitions)
• Tailwind v4 / v4.1 (Jan–Apr 2025): Tailwind v4.0 (Jan 22, 2025) reworked the framework to be CSS-first and exposes theme values as native CSS variables; v4.1 (Apr 3, 2025) added text-shadow, mask utilities, colored drop-shadows, pointer-aware device variants, items-baseline-last, and more. (Tailwind Blog: https://tailwindcss.com/blog/tailwindcss-v4; https://tailwindcss.com/blog/tailwindcss-v4-1)
• Tailwind Plus (Jul 25, 2025): Tailwind Plus Elements (@tailwindplus/elements) provides headless custom elements for framework-agnostic interactive UI blocks — when using these, map classes/attributes back to your token variables so tokens remain authoritative across framework and vanilla integrations. (Tailwind Plus blog: https://tailwindcss.com/blog/vanilla-js-support-for-tailwind-plus)

Next edits

• Add one new tactic based on Tailwind Plus vanilla-JS integration (component mapping example) — done.
• Rewrite the platform notes with explicit migration commands and version numbers (Tailwind and Chrome notes updated).
• 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
2. Install the latest runtime and CLI in a feature branch:

npm install tailwindcss@latest @tailwindcss/cli@latest

3. Follow the upgrade guide's config + plugin changes and run your test suite.
4. Run visual regression tests on a modern-browser matrix and fix regressions (include Chrome 147+ to verify view transitions where used).
5. Optionally, run the Tailwind upgrade helper (e.g., npx @tailwindcss/upgrade) if a migration helper is published for your target version — verify changes locally before committing.