• Chrome (Mar 2026)

  • Element-scoped view transitions (Chrome 147) — Chrome 147 ships element-scoped view transitions that let you call Element.startViewTransition() on a DOM subtree so multiple independent transitions can run concurrently and nested transitions are possible. Use 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 explanatory blog post: https://developer.chrome.com/blog/element-scoped-view-transitions. Reference (MDN View Transition API): https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API
  • When using nesting, pay attention to view-transition-name containment and clipping — the browser's guide and examples show patterns for shuffling lists and nested content.
  • Scroll-triggered animation primitives are shipping in modern Chrome builds. Prefer native scroll-triggered APIs for large, performance-sensitive scroll choreography and provide GSAP or polyfill fallbacks for cross‑browser consistency.
  • Scoped custom element registries are available — use them to encapsulate web components and avoid tag collisions across packages.
  • Sanitizer API is available for safer sanitization of third‑party or user-provided HTML; prefer it over ad-hoc string manipulation where supported (fall back to a tested sanitizer on other browsers).

• Tailwind (v4.x)

  • Tailwind v4 is a CSS-first rework of the configuration and runtime. v4's ongoing point releases (v4.0, v4.1, etc.) add utilities that matter for art direction: text-shadow utilities, mask-* utilities, colored drop-shadow, pointer-* / any-pointer-* device targeting, items-baseline-last, safe alignment behaviors, more variants, and improved graceful degradation for older browsers. See the v4.1 announcement for details: https://tailwindcss.com/blog/tailwindcss-v4-1
  • Migration basics (copy-pasteable):
    1. Ensure Node.js 20+ is installed.
    2. Create a new branch and run the interactive upgrade tool: npx @tailwindcss/upgrade.
    3. Replace PostCSS plugin entry with @tailwindcss/postcss or migrate to the Vite plugin @tailwindcss/vite for Vite projects.
    4. Update CLI invocations to npx @tailwindcss/cli.
    5. Run visual regression tests on a modern‑browser matrix (Safari 16.4+, Chrome 111+, Firefox 128+ or newer) and fix regressions.
  • Tailwind v4 exposes theme values as native CSS variables (CSS-first). 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 (formerly Tailwind UI)

  • Tailwind Plus now provides vanilla-JS integration and a set of interactive primitives shipped as @tailwindplus/elements (custom elements). This lets you drop in accessible, framework-agnostic UI blocks (dialogs, dropdowns, command palettes, drawers) via a single script: <script src="https://cdn.jsdelivr.net/npm/@tailwindplus/elements@1" type="module"></script> and style them with Tailwind utilities or your token variables. See: https://tailwindcss.com/blog/vanilla-js-support-for-tailwind-plus
  • When using Tailwind Plus bundles in non-framework contexts, map component classes or attributes back to your token CSS variables so tokens remain authoritative across framework and vanilla integrations.

• 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-scoped view transition
  element.startViewTransition(() => {
    // mutate the subtree under `element` synchronously
  })
} else if (typeof document.startViewTransition === 'function') {
  // page-level view transition
  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's CSS-first model encourages defining tokens in CSS. Use @theme or a central tokens.css file that becomes the single source of truth. Because v4 outputs native CSS variables, these tokens can be consumed by vanilla-JS Tailwind Plus bundles, web components, and third‑party widgets.
• Map the new utilities (text-shadow, masks, 3D transforms, container queries) to tokens instead of sprinkling class utilities across components.
• If migrating from v3: run npx @tailwindcss/upgrade in a branch, update PostCSS/Vite plugin entries, and run your visual regression suite against modern browsers.

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>

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

• Chrome (Mar 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 Blog, MDN)
• Tailwind v4 / v4.1: CSS-first config and new utilities (text-shadow, mask utilities, colored drop-shadows, pointer-aware variants, items-baseline-last, safe alignment, and more) — map these utilities to tokens instead of scattering ad-hoc utilities. (Tailwind Blog v4.1)
• Tailwind Plus: vanilla-JS support via @tailwindplus/elements (custom elements) enables framework-agnostic interactive UI blocks; when using these, map classes/attributes back to your token variables so tokens remain authoritative. (Tailwind Plus blog)

Next edits

• Add one new tactic based on Tailwind Plus vanilla-JS integration (component mapping example).
• Rewrite the platform notes with explicit migration commands and version numbers (done for Tailwind and Chrome; add browser matrix tests as a follow-up).
• Add a short agent prompt for upgrading a repo to Tailwind v4 (done).

Quick upgrade prompt (agent-ready)

Upgrade this repo to Tailwind v4. Checklist:

1. Ensure Node 20+ is installed.
2. Run npx @tailwindcss/upgrade in a new branch and review the diffs.
3. Replace PostCSS entry with @tailwindcss/postcss or migrate to @tailwindcss/vite for Vite projects.
4. Update build scripts to use npx @tailwindcss/cli.
5. Run visual regression tests on modern browsers (Safari 16.4+, Chrome 111+, Firefox 128+).