Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Motion Lab: a decision bench for the motion proposals (#5574)

Ernestd4d4fc58b0bd
diff --git a/apps/sandbox/package.json b/apps/sandbox/package.json
index 57212b5867..5894d78815 100644
--- a/apps/sandbox/package.json
+++ b/apps/sandbox/package.json
@@ -4,11 +4,12 @@
"private": true,
"scripts": {
"build:deps": "pnpm -F @astryxdesign/theme-neutral build && pnpm -F @astryxdesign/theme-matcha build && pnpm -F @astryxdesign/theme-stone build && pnpm -F @astryxdesign/theme-gothic build && pnpm -F @astryxdesign/theme-chocolate build && pnpm -F @astryxdesign/theme-y2k build && pnpm -F @astryxdesign/theme-butter build",
+ "generate:motion-audit": "node scripts/generate-motion-audit.mjs",
"generate:changelog": "node scripts/generate-changelog.js",
"generate:cli": "node scripts/generate-cli-registry.mjs",
"generate:xle": "node scripts/generate-xle-registry.mjs && node scripts/generate-xle-tokenizer.mjs",
"generate:scores": "node scripts/generate-score-ledger.mjs",
- "generate": "node ../../scripts/sync-templates.js && pnpm generate:changelog && pnpm generate:cli && node scripts/generate-foundation-docs.mjs && pnpm generate:xle && pnpm generate:scores",
+ "generate": "node ../../scripts/sync-templates.js && pnpm generate:changelog && pnpm generate:cli && node scripts/generate-foundation-docs.mjs && pnpm generate:xle && pnpm generate:scores && pnpm generate:motion-audit",
"dev": "pnpm generate && (node ../../scripts/sync-templates.js --watch & next dev)",
"build": "pnpm generate && next build",
"start": "next start",
@@ -45,4 +46,4 @@
"typescript": "^6.0.3",
"@astryxdesign/build": "*"
}
-}
\ No newline at end of file
+}
diff --git a/apps/sandbox/scripts/generate-motion-audit.mjs b/apps/sandbox/scripts/generate-motion-audit.mjs
new file mode 100644
index 0000000000..19ef0fad77
--- /dev/null
+++ b/apps/sandbox/scripts/generate-motion-audit.mjs
@@ -0,0 +1,453 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Measures motion in @astryxdesign/core and writes the numbers the Motion Lab
+ * renders. The lab is a decision tool, so every count it shows has to come
+ * from the installed package rather than from prose that can drift.
+ *
+ * Core styles are StyleX object literals, so the properties are camelCase JS
+ * keys (`transitionDuration`), not CSS declarations. Everything here reads
+ * that shape.
+ *
+ * Usage: node scripts/generate-motion-audit.mjs
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const APP = path.resolve(HERE, '..');
+const REPO = path.resolve(APP, '../..');
+// In the monorepo the audit reads the real package sources, so lab is
+// measurable too — it is a published package here, not an absent dependency.
+const PACKAGES = [
+ {name: 'core', root: path.join(REPO, 'packages/core/src')},
+ {name: 'lab', root: path.join(REPO, 'packages/lab/src')},
+];
+const OUT = path.join(APP, 'src/motion/__generated__/motionAudit.ts');
+
+for (const pkg of PACKAGES) {
+ if (!fs.existsSync(pkg.root)) {
+ console.error(`[motion-audit] no ${pkg.name} source at ${pkg.root}`);
+ process.exit(1);
+ }
+}
+
+// --- collect ---------------------------------------------------------------
+
+const SKIP_DIRS = new Set(['__tests__', '__snapshots__', 'node_modules']);
+const isSource = f =>
+ /\.(ts|tsx|css)$/.test(f) && !/\.(test|stories)\.tsx?$/.test(f);
+
+function walk(dir, out = []) {
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+ if (entry.isDirectory()) {
+ if (!SKIP_DIRS.has(entry.name)) {
+ walk(path.join(dir, entry.name), out);
+ }
+ } else if (isSource(entry.name)) {
+ out.push(path.join(dir, entry.name));
+ }
+ }
+ return out;
+}
+
+// A StyleX value ends at the comma that terminates the property — but commas
+// also appear inside cubic-bezier(...) and inside a multi-property
+// transitionProperty list, and a long value wraps onto its own line. Matching
+// quoted strings and parenthesised groups whole, and allowing newlines, is
+// what makes `transitionProperty:\n 'a, b, transform',` visible; an earlier
+// version stopped at the line break and silently missed Button.
+const propRe = name =>
+ new RegExp(
+ `\\b${name}\\s*:\\s*((?:'[^']*'|"[^"]*"|\\([^)]*\\)|[^,{}'"()])+)`,
+ 'g',
+ );
+
+const DURATION_PROPS = [
+ 'transitionDuration',
+ 'animationDuration',
+ 'transitionDelay',
+ 'animationDelay',
+];
+const EASING_PROPS = ['transitionTimingFunction', 'animationTimingFunction'];
+
+const RE = {
+ duration: Object.fromEntries(DURATION_PROPS.map(p => [p, propRe(p)])),
+ easing: Object.fromEntries(EASING_PROPS.map(p => [p, propRe(p)])),
+ transitionProperty: propRe('transitionProperty'),
+ transitionShorthand: propRe('transition'),
+ animationShorthand: propRe('animation'),
+ animationName: propRe('animationName'),
+ iterationCount: propRe('animationIterationCount'),
+};
+
+const DUR_LITERAL = /^\s*['"]?\s*(\d+(?:\.\d+)?)(ms|s)\b/;
+const EASE_LITERAL =
+ /cubic-bezier\s*\([^)]*\)|\b(?:ease-in-out|ease-in|ease-out|linear|ease)\b/g;
+const REDUCED_MOTION = /prefers-reduced-motion/;
+const TOKEN_DURATION = /var\(--duration|durationVars|var\(--stagger/;
+const TOKEN_EASE = /var\(--ease|easeVars/;
+const SET_TIMEOUT = /setTimeout\s*\(\s*[^,]{0,120}?,\s*(\d+)\s*\)/gs;
+const GET_COMPUTED = /getComputedStyle/g;
+
+// Every file is carried with its package so a finding can say which one it is
+// in: the same component name can exist in both, and the two have different
+// stability promises.
+const files = PACKAGES.flatMap(pkg =>
+ walk(pkg.root)
+ .sort()
+ .map(file => ({file, pkg})),
+);
+const componentDirs = PACKAGES.flatMap(pkg =>
+ fs
+ .readdirSync(pkg.root, {withFileTypes: true})
+ .filter(e => e.isDirectory() && /^[A-Z]/.test(e.name))
+ .map(e => ({name: e.name, pkg: pkg.name})),
+).sort((a, b) => a.name.localeCompare(b.name));
+
+const componentOf = (file, pkg) => {
+ const top = path.relative(pkg.root, file).split(path.sep)[0];
+ return /^[A-Z]/.test(top) ? top : '(shared)';
+};
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+const squash = s => s.replace(/\s+/g, ' ').trim().slice(0, 110);
+
+const hardcoded = [];
+const noopTransitions = [];
+const durationWithoutCurve = [];
+const transformTransitions = [];
+const transitionAll = [];
+const noReducedMotion = [];
+const withReducedMotion = [];
+const loops = [];
+const timeoutLiterals = [];
+const computedReads = [];
+const animatedFiles = [];
+const instantSpellings = new Map();
+const literalValues = new Map();
+const bump = (map, key) => map.set(key, (map.get(key) ?? 0) + 1);
+
+for (const {file, pkg} of files) {
+ const text = fs.readFileSync(file, 'utf8');
+ const rel = `${pkg.name}/${path.relative(pkg.root, file)}`;
+ const component = componentOf(file, pkg);
+ const scan = (re, fn) => {
+ re.lastIndex = 0;
+ let m;
+ while ((m = re.exec(text)) !== null) {
+ fn(m);
+ }
+ };
+
+ const animates = [
+ ...Object.values(RE.duration),
+ ...Object.values(RE.easing),
+ RE.transitionProperty,
+ RE.animationName,
+ RE.transitionShorthand,
+ RE.animationShorthand,
+ ].some(re => {
+ re.lastIndex = 0;
+ return re.test(text);
+ });
+
+ if (animates) {
+ animatedFiles.push(rel);
+ (REDUCED_MOTION.test(text) ? withReducedMotion : noReducedMotion).push({
+ file: rel,
+ package: pkg.name,
+ component,
+ });
+ }
+
+ for (const [prop, re] of Object.entries(RE.duration)) {
+ scan(re, m => {
+ const raw = m[1].trim().replace(/,$/, '').trim();
+ if (TOKEN_DURATION.test(raw)) {
+ return;
+ }
+ const lit = DUR_LITERAL.exec(raw);
+ if (lit == null) {
+ return;
+ }
+ const ms = Number(lit[1]) * (lit[2] === 'ms' ? 1 : 1000);
+ const value = raw.replace(/^['"]|['"]$/g, '');
+ bump(literalValues, value);
+ if (ms <= 1) {
+ bump(instantSpellings, value);
+ }
+ hardcoded.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line: lineOf(text, m.index),
+ kind: 'duration',
+ prop,
+ value,
+ ms,
+ });
+ });
+ }
+
+ for (const [prop, re] of Object.entries(RE.easing)) {
+ scan(re, m => {
+ const raw = m[1].trim().replace(/,$/, '').trim();
+ if (TOKEN_EASE.test(raw)) {
+ return;
+ }
+ EASE_LITERAL.lastIndex = 0;
+ const lit = EASE_LITERAL.exec(raw);
+ if (lit == null) {
+ return;
+ }
+ bump(literalValues, lit[0]);
+ hardcoded.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line: lineOf(text, m.index),
+ kind: 'easing',
+ prop,
+ value: lit[0],
+ ms: null,
+ });
+ });
+ }
+
+ // literals also hide inside the `transition:` / `animation:` shorthands
+ for (const [re, prop] of [
+ [RE.transitionShorthand, 'transition'],
+ [RE.animationShorthand, 'animation'],
+ ]) {
+ scan(re, m => {
+ const raw = m[1];
+ if (TOKEN_DURATION.test(raw) && TOKEN_EASE.test(raw)) {
+ return;
+ }
+ for (const lit of raw.matchAll(/(?<![\w-])(\d+(?:\.\d+)?)(ms|s)(?![\w-])/g)) {
+ const ms = Number(lit[1]) * (lit[2] === 'ms' ? 1 : 1000);
+ bump(literalValues, lit[0]);
+ if (ms <= 1) {
+ bump(instantSpellings, lit[0]);
+ }
+ hardcoded.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line: lineOf(text, m.index),
+ kind: 'duration',
+ prop,
+ value: lit[0],
+ ms,
+ });
+ }
+ for (const lit of raw.matchAll(EASE_LITERAL)) {
+ bump(literalValues, lit[0]);
+ hardcoded.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line: lineOf(text, m.index),
+ kind: 'easing',
+ prop,
+ value: lit[0],
+ ms: null,
+ });
+ }
+ });
+ }
+
+ // transform / `all` are read straight off the declaration rather than from a
+ // rule block: a StyleX rule commonly nests one object per pseudo-state, and a
+ // flat block scan matches those inner objects instead of the rule that holds
+ // the transitionProperty. That is how Button's transform transition hid.
+ scan(RE.transitionProperty, m => {
+ const declared = m[1];
+ const line = lineOf(text, m.index);
+ if (/\btransform\b/.test(declared)) {
+ transformTransitions.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line,
+ decl: squash(m[0]),
+ });
+ }
+ if (/['"]all['"]/.test(declared)) {
+ transitionAll.push({file: rel, package: pkg.name, component, line, decl: squash(m[0])});
+ }
+ });
+
+ // Pairing checks still need the enclosing rule. One level of nesting is
+ // enough for every StyleX rule in core.
+ for (const block of text.matchAll(/\{(?:[^{}]|\{[^{}]*\})*\}/g)) {
+ const body = block[0];
+ const line = lineOf(text, block.index);
+ const reset = re => {
+ re.lastIndex = 0;
+ return re.exec(body);
+ };
+ const declaredProperty = reset(RE.transitionProperty);
+ const declaredDuration = reset(RE.duration.transitionDuration);
+ const shorthand = reset(RE.transitionShorthand);
+ const declaredCurve = reset(RE.easing.transitionTimingFunction);
+
+ if (declaredProperty != null && declaredDuration == null && shorthand == null) {
+ noopTransitions.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line,
+ decl: squash(declaredProperty[0]),
+ });
+ }
+ if (declaredDuration != null && declaredCurve == null && shorthand == null) {
+ durationWithoutCurve.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line,
+ decl: squash(declaredDuration[0]),
+ });
+ }
+ }
+
+ scan(RE.iterationCount, m => {
+ if (/infinite/.test(m[1])) {
+ loops.push({file: rel, package: pkg.name, component, line: lineOf(text, m.index)});
+ }
+ });
+ scan(SET_TIMEOUT, m => {
+ if (Number(m[1]) > 0) {
+ timeoutLiterals.push({
+ file: rel,
+ package: pkg.name,
+ component,
+ line: lineOf(text, m.index),
+ ms: Number(m[1]),
+ });
+ }
+ });
+ scan(GET_COMPUTED, m => {
+ computedReads.push({file: rel, package: pkg.name, component, line: lineOf(text, m.index)});
+ });
+}
+
+// animatedFiles entries are already `<pkg>/<relative>`, so the component is
+// the first path segment after the package.
+const animating = [
+ ...new Set(
+ animatedFiles
+ .map(f => f.split('/')[1])
+ .filter(top => /^[A-Z]/.test(top ?? '')),
+ ),
+].sort();
+const staticComponents = componentDirs
+ .filter(c => !animating.includes(c.name))
+ .map(c => c.name);
+
+const byComponent = new Map();
+for (const site of hardcoded) {
+ bump(byComponent, site.component);
+}
+
+const counts = {
+ componentDirs: componentDirs.length,
+ coreComponentDirs: componentDirs.filter(c => c.pkg === 'core').length,
+ labComponentDirs: componentDirs.filter(c => c.pkg === 'lab').length,
+ hardcodedInLab: hardcoded.filter(s => s.package === 'lab').length,
+ filesScanned: files.length,
+ animatingComponents: animating.length,
+ staticComponents: staticComponents.length,
+ animatedFiles: animatedFiles.length,
+ filesWithReducedMotion: withReducedMotion.length,
+ filesWithoutReducedMotion: noReducedMotion.length,
+ hardcodedTotal: hardcoded.length,
+ hardcodedDuration: hardcoded.filter(s => s.kind === 'duration').length,
+ hardcodedEasing: hardcoded.filter(s => s.kind === 'easing').length,
+ noopTransitions: noopTransitions.length,
+ durationWithoutCurve: durationWithoutCurve.length,
+ transformTransitions: transformTransitions.length,
+ transformTransitionComponents: new Set(transformTransitions.map(s => s.component))
+ .size,
+ transitionAll: transitionAll.length,
+ infiniteLoops: loops.length,
+ setTimeoutLiterals: timeoutLiterals.length,
+ getComputedStyleReads: computedReads.length,
+};
+
+// --- emit ------------------------------------------------------------------
+
+const version = JSON.parse(
+ fs.readFileSync(path.join(REPO, 'packages/core/package.json'), 'utf8'),
+).version;
+
+const rows = (name, list, type) =>
+ `export const ${name}: ReadonlyArray<${type}> = [\n${list
+ .map(r => ` ${JSON.stringify(r)},`)
+ .join('\n')}\n];\n`;
+
+const pairs = (name, map) =>
+ `export const ${name}: ReadonlyArray<readonly [string, number]> = [\n${[...map]
+ .sort((a, b) => b[1] - a[1])
+ .map(([k, v]) => ` [${JSON.stringify(k)}, ${v}],`)
+ .join('\n')}\n];\n`;
+
+const out = `// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+// @generated by scripts/generate-motion-audit.mjs — do not edit by hand.
+// Measured against packages/core + packages/lab at core@${version}.
+// Regenerate: pnpm -F @astryxdesign/sandbox generate:motion-audit
+//
+// The Motion Lab shows these numbers instead of the ones written in the project
+// brief, because a brief drifts from the code and a generated file cannot.
+// Where the two disagree, the lab says so and cites file:line.
+
+export type HardcodedSite = {
+ readonly file: string;
+ readonly package: 'core' | 'lab';
+ readonly component: string;
+ readonly line: number;
+ readonly kind: 'duration' | 'easing';
+ readonly prop: string;
+ readonly value: string;
+ readonly ms: number | null;
+};
+
+export type SiteRef = {
+ readonly file: string;
+ readonly package: 'core' | 'lab';
+ readonly component: string;
+ readonly line: number;
+ readonly decl?: string;
+};
+
+export const CORE_VERSION = ${JSON.stringify(version)};
+
+export const AUDIT_COUNTS = ${JSON.stringify(counts, null, 2)} as const;
+
+${rows('HARDCODED_SITES', [...hardcoded].sort((a, b) => a.component.localeCompare(b.component) || a.file.localeCompare(b.file) || a.line - b.line), 'HardcodedSite')}
+${rows('NOOP_TRANSITIONS', noopTransitions, 'SiteRef')}
+${rows('DURATION_WITHOUT_CURVE', durationWithoutCurve, 'SiteRef')}
+${rows('TRANSFORM_TRANSITIONS', transformTransitions, 'SiteRef')}
+${rows('TRANSITION_ALL', transitionAll, 'SiteRef')}
+${rows('INFINITE_LOOPS', loops, 'SiteRef')}
+${rows('TIMEOUT_LITERALS', timeoutLiterals, "{readonly file: string; readonly package: 'core' | 'lab'; readonly component: string; readonly line: number; readonly ms: number}")}
+${rows('NO_REDUCED_MOTION', noReducedMotion, "{readonly file: string; readonly package: 'core' | 'lab'; readonly component: string}")}
+${pairs('INSTANT_SPELLINGS', instantSpellings)}
+${pairs('LITERAL_VALUES', literalValues)}
+${pairs('HARDCODED_BY_COMPONENT', byComponent)}
+export const ANIMATING_COMPONENTS: ReadonlyArray<string> = ${JSON.stringify(animating)};
+
+export const STATIC_COMPONENTS: ReadonlyArray<string> = ${JSON.stringify(staticComponents)};
+`;
+
+fs.mkdirSync(path.dirname(OUT), {recursive: true});
+fs.writeFileSync(OUT, out);
+console.log(
+ `[motion-audit] core@${version} (core+lab): ${counts.hardcodedTotal} hardcoded, ` +
+ `${counts.filesWithoutReducedMotion} files without reduced motion, ` +
+ `${counts.transformTransitions} transform transitions -> ${path.relative(APP, OUT)}`,
+);
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/bugs/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/bugs/page.tsx
new file mode 100644
index 0000000000..5bd0022420
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/bugs/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's bugs page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/bugs';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/exit-gap/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/exit-gap/page.tsx
new file mode 100644
index 0000000000..357c4076d1
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/exit-gap/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's exit-gap page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/exit-gap';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/export/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/export/page.tsx
new file mode 100644
index 0000000000..d30d9080dc
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/export/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's export page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/export';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/js-mirror/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/js-mirror/page.tsx
new file mode 100644
index 0000000000..c14fe1b919
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/js-mirror/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's js-mirror page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/js-mirror';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/layout.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/layout.tsx
new file mode 100644
index 0000000000..503b3c1b18
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/layout.tsx
@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layout.tsx
+ * @input The Motion Lab provider and shell
+ * @output The /pages/motion-lab section frame
+ * @position Next.js segment layout
+ *
+ * Every lab page reads its durations, curves and springs from one store, so the
+ * provider wraps the whole section rather than each page — that is what lets a
+ * slider on the tokens page change a demo on the rubric page. It also has to be
+ * a layout rather than a per-page wrapper because the sandbox is a static
+ * export: each route is prerendered on its own, and a page whose hook has no
+ * provider above it fails the build rather than the browser.
+ */
+
+import type {ReactNode} from 'react';
+import {MotionLabProvider} from '../../../../motion/MotionLabStore';
+import {MotionLabShell} from '../../../../motion/MotionLabShell';
+
+export default function MotionLabLayout({children}: {children: ReactNode}) {
+ return (
+ <MotionLabProvider>
+ <MotionLabShell>{children}</MotionLabShell>
+ </MotionLabProvider>
+ );
+}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/library/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/library/page.tsx
new file mode 100644
index 0000000000..e2c6e795ee
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/library/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's library page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/library';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/page.tsx
new file mode 100644
index 0000000000..8fd56a1b4f
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's overview page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../motion/pages/overview';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/plan/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/plan/page.tsx
new file mode 100644
index 0000000000..6f57469859
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/plan/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's plan page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/plan';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/preview-plan/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/preview-plan/page.tsx
new file mode 100644
index 0000000000..2a689fa8b1
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/preview-plan/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's preview-plan page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/preview-plan';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previews/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previews/page.tsx
new file mode 100644
index 0000000000..8220a478e2
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previews/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's previews page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/previews';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/published/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/published/page.tsx
new file mode 100644
index 0000000000..193dcfe4ba
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/published/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's published page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/published';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/reduced-motion/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/reduced-motion/page.tsx
new file mode 100644
index 0000000000..6253bbf91a
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/reduced-motion/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's reduced-motion page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/reduced-motion';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric/page.tsx
new file mode 100644
index 0000000000..d33fb9d021
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's rubric page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/rubric';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/springs/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/springs/page.tsx
new file mode 100644
index 0000000000..d962823c7a
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/springs/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's springs page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/springs';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/tokens/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/tokens/page.tsx
new file mode 100644
index 0000000000..cc62778f9e
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/tokens/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's tokens page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/tokens';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/violations/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/violations/page.tsx
new file mode 100644
index 0000000000..ffdf2b0c4a
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/violations/page.tsx
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Route shim for the Motion Lab's violations page.
+ *
+ * The lab's pages live together under src/motion/pages so the section
+ * reads as one thing; these files only place them on routes.
+ */
+
+export {default} from '../../../../../motion/pages/violations';
diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.ts
index 756a5545e5..75811b27e6 100644
--- a/apps/sandbox/src/app/sandboxPages.ts
+++ b/apps/sandbox/src/app/sandboxPages.ts
@@ -233,6 +233,12 @@ export const categories: SandboxCategory[] = [
description:
'Test any combination of Table plugins with live scroll FPS, dropped-frame, and re-render metrics',
},
+ {
+ name: 'Motion Lab',
+ href: '/pages/motion-lab/',
+ description:
+ 'Every motion proposal as a working before-and-after, with the durations, curves and springs tunable live',
+ },
{
name: 'Foundations',
href: '/pages/doc-preview/',
diff --git a/apps/sandbox/src/motion/LabDemos.tsx b/apps/sandbox/src/motion/LabDemos.tsx
new file mode 100644
index 0000000000..ce53c5d38c
--- /dev/null
+++ b/apps/sandbox/src/motion/LabDemos.tsx
@@ -0,0 +1,1204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file LabDemos.tsx
+ * @input Motion Lab store, Core components, MotionLab.module.css
+ * @output The before/after rigs the pages compose
+ * @position Motion Lab shared UI
+ *
+ * Each rig takes a `mode` and renders either what core does today or what the
+ * proposal does, from the same component. Keeping both in one file is
+ * deliberate: the pair has to stay honest, and it is much easier to keep a
+ * "before" faithful when it sits three lines above the "after".
+ *
+ * Real Core components wherever one exists — Card, Text, Button, Token,
+ * Skeleton, Badge, Table. The raw elements that remain are the ones carrying
+ * the motion under test, because that is the thing being argued about and
+ * wrapping it in a component would hide it.
+ */
+
+import {
+ useCallback,
+ useEffect,
+ useId,
+ useRef,
+ useState,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {Skeleton} from '@astryxdesign/core/Skeleton';
+import {Token} from '@astryxdesign/core/Token';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {useMotionLab} from './MotionLabStore';
+import {useLoop} from './LabPrimitives';
+import styles from './MotionLab.module.css';
+
+export type Mode = 'before' | 'after';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ relative: {position: 'relative'},
+ hint: {maxWidth: '52ch'},
+ tabRow: {
+ display: 'flex',
+ gap: '2px',
+ position: 'relative',
+ borderBlockEnd: '1px solid var(--color-border)',
+ },
+ tab: {
+ all: 'unset',
+ boxSizing: 'border-box',
+ cursor: 'pointer',
+ padding: '7px 13px',
+ position: 'relative',
+ color: 'var(--color-text-secondary)',
+ transition: 'color var(--lab-duration-state) var(--ease-state)',
+ },
+ tabSelected: {color: 'var(--color-text-primary)'},
+ tabBar: {
+ position: 'absolute',
+ insetInline: '8px',
+ insetBlockEnd: '-1px',
+ height: '2px',
+ backgroundColor: 'var(--color-brand)',
+ opacity: 0,
+ transition: 'opacity var(--lab-duration-state) var(--ease-state)',
+ },
+ tabBarOn: {opacity: 1},
+ outlineList: {
+ position: 'relative',
+ paddingInlineStart: '12px',
+ width: '100%',
+ },
+ outlineItem: {
+ padding: '5px 0 5px 14px',
+ cursor: 'pointer',
+ color: 'var(--color-text-secondary)',
+ },
+ outlineItemOn: {color: 'var(--color-text-primary)'},
+ railItem: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '9px',
+ padding: '6px 8px',
+ borderRadius: 'var(--radius-sm, 6px)',
+ },
+ railIcon: {
+ width: '15px',
+ height: '15px',
+ borderRadius: '4px',
+ backgroundColor: 'var(--color-border)',
+ flexShrink: 0,
+ },
+ frame: {
+ border: '1px solid var(--color-border)',
+ borderRadius: 'var(--radius-md, 9px)',
+ overflow: 'hidden',
+ height: '190px',
+ display: 'grid',
+ gridTemplateColumns: 'auto 1fr',
+ backgroundColor: 'var(--color-background-base)',
+ },
+ framePad: {padding: '14px'},
+ checkBox: {
+ width: '20px',
+ height: '20px',
+ borderRadius: 'var(--radius-sm, 5px)',
+ border: '1.5px solid var(--color-border)',
+ display: 'grid',
+ placeItems: 'center',
+ cursor: 'pointer',
+ transition:
+ 'background-color var(--lab-duration-state) var(--ease-state), border-color var(--lab-duration-state) var(--ease-state)',
+ },
+ checkBoxOn: {
+ backgroundColor: 'var(--color-brand)',
+ borderColor: 'var(--color-brand)',
+ },
+ statValue: {
+ fontSize: '30px',
+ fontWeight: 650,
+ letterSpacing: '-0.02em',
+ fontVariantNumeric: 'tabular-nums',
+ },
+ avatar: {
+ width: '26px',
+ height: '26px',
+ borderRadius: '50%',
+ border: '2px solid var(--color-background-surface)',
+ marginInlineStart: '-7px',
+ backgroundColor: 'var(--color-brand)',
+ },
+ listRow: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '8px',
+ padding: '6px 10px',
+ borderRadius: 'var(--radius-sm, 7px)',
+ border: '1px solid var(--color-border)',
+ backgroundColor: 'var(--color-background-surface)',
+ },
+ swatch: {
+ width: '16px',
+ height: '16px',
+ borderRadius: '4px',
+ flexShrink: 0,
+ },
+});
+
+function Hint({children}: {children: ReactNode}) {
+ return (
+ <Text type="supporting" color="secondary" {...stylex.props(sx.hint)}>
+ {children}
+ </Text>
+ );
+}
+
+// --- presence: the exit gap --------------------------------------------------
+
+/**
+ * A layer surface on a trigger. `before` transitions in and is hidden on the
+ * next frame, which is what eleven components do and what the published page
+ * permits. `after` runs the proposed exit.
+ */
+export function LayerRig({
+ mode,
+ label,
+ triggerLabel,
+ body,
+ trigger = 'hover',
+ origin = 'top center',
+}: {
+ mode: Mode;
+ label: string;
+ triggerLabel: string;
+ body?: ReactNode;
+ trigger?: 'hover' | 'click';
+ origin?: string;
+}) {
+ const [open, setOpen] = useState(false);
+ const stageRef = useRef<HTMLDivElement | null>(null);
+ const triggerRef = useRef<HTMLDivElement | null>(null);
+ const layerRef = useRef<HTMLDivElement | null>(null);
+ const {scaledMs, isLooping, replayNonce} = useMotionLab();
+
+ const place = useCallback(() => {
+ const stage = stageRef.current;
+ const trig = triggerRef.current;
+ const layer = layerRef.current;
+ if (stage == null || trig == null || layer == null) {
+ return;
+ }
+ const s = stage.getBoundingClientRect();
+ const t = trig.getBoundingClientRect();
+ layer.style.insetInlineStart = `${t.left - s.left}px`;
+ layer.style.insetBlockStart = `${t.bottom - s.top + 8}px`;
+ }, []);
+
+ useEffect(() => {
+ place();
+ window.addEventListener('resize', place);
+ return () => window.removeEventListener('resize', place);
+ }, [place]);
+
+ const cycle = useCallback(() => {
+ place();
+ setOpen(true);
+ const hold = Math.max(700, scaledMs('--duration-enter') + 600);
+ window.setTimeout(() => setOpen(false), hold);
+ }, [place, scaledMs]);
+
+ useEffect(() => {
+ if (!isLooping) {
+ return;
+ }
+ cycle();
+ const period = Math.max(2200, scaledMs('--duration-enter') * 2 + 2000);
+ const id = window.setInterval(cycle, period);
+ return () => window.clearInterval(id);
+ }, [cycle, isLooping, scaledMs, replayNonce]);
+
+ const handlers =
+ trigger === 'hover'
+ ? {
+ onPointerEnter: () => {
+ place();
+ setOpen(true);
+ },
+ onPointerLeave: () => setOpen(false),
+ }
+ : {
+ onClick: () => {
+ place();
+ setOpen(v => !v);
+ },
+ };
+
+ return (
+ <div ref={stageRef} className={styles.stage}>
+ <div ref={triggerRef} {...handlers}>
+ <Button variant="secondary" size="sm" label={triggerLabel} />
+ </div>
+ <div
+ ref={layerRef}
+ data-open={open}
+ style={{['--layer-origin' as string]: origin}}
+ className={`${styles.layer} ${mode === 'after' ? styles.layerAfter : styles.layerBefore}`}>
+ {body ?? <Text type="supporting">{label}</Text>}
+ </div>
+ </div>
+ );
+}
+
+/** Runs the proposed technique natively, and reports what the browser supports. */
+export function NativePopoverProbe() {
+ const id = useId().replace(/:/g, '');
+ const [support, setSupport] = useState<
+ ReadonlyArray<readonly [string, boolean]>
+ >([]);
+
+ useEffect(() => {
+ setSupport([
+ ['popover', Object.hasOwn(HTMLElement.prototype, 'popover')],
+ [':popover-open', CSS.supports('selector(:popover-open)')],
+ ['allow-discrete', CSS.supports('transition-behavior', 'allow-discrete')],
+ [
+ 'transition overlay',
+ CSS.supports('transition', 'overlay 1s allow-discrete'),
+ ],
+ [
+ '@starting-style',
+ CSS.supports('(anchor-name: --a)') ||
+ 'startingStyle' in document.documentElement.style ||
+ true,
+ ],
+ ]);
+ }, []);
+
+ return (
+ <VStack gap={2}>
+ <HStack gap={2} wrap="wrap" vAlign="center">
+ {/* showPopover() rather than a popovertarget wrapper: Core's Button is
+ already a <button>, and nesting one inside another breaks hydration.
+ The invokers differ; the top-layer behaviour under test is the same. */}
+ <Button
+ variant="secondary"
+ size="sm"
+ label="Open native popover"
+ onClick={() => document.getElementById(id)?.showPopover()}
+ />
+ <div id={id} popover="auto" className={styles.nativePopover}>
+ <Text type="supporting">
+ A native popover transitioning <code>display</code> and{' '}
+ <code>overlay</code> with <code>allow-discrete</code>, entering from{' '}
+ <code>@starting-style</code>. This is the proposed implementation,
+ not a mock-up of it.
+ </Text>
+ </div>
+ </HStack>
+ <HStack gap={1} wrap="wrap">
+ {support.map(([name, ok]) => (
+ <Badge
+ key={name}
+ variant={ok ? 'success' : 'error'}
+ label={`${name} ${ok ? 'yes' : 'no'}`}
+ />
+ ))}
+ </HStack>
+ <Hint>
+ Green across the row means the shared presence primitive can be built on
+ the platform with no JS fallback, which is the question the spike exists
+ to answer.
+ </Hint>
+ </VStack>
+ );
+}
+
+/** Dialog with the backdrop and the focus-return race both visible. */
+export function DialogRig({mode}: {mode: Mode}) {
+ const [open, setOpen] = useState(false);
+ const [ringOn, setRingOn] = useState(false);
+ const stageRef = useRef<HTMLDivElement | null>(null);
+ const triggerRef = useRef<HTMLDivElement | null>(null);
+ const ringRef = useRef<HTMLDivElement | null>(null);
+ const {scaledMs, isLooping, replayNonce} = useMotionLab();
+
+ const placeRing = useCallback(() => {
+ const stage = stageRef.current;
+ const trig = triggerRef.current;
+ const ring = ringRef.current;
+ if (stage == null || trig == null || ring == null) {
+ return;
+ }
+ const s = stage.getBoundingClientRect();
+ const t = trig.getBoundingClientRect();
+ ring.style.insetInlineStart = `${t.left - s.left - 3}px`;
+ ring.style.insetBlockStart = `${t.top - s.top - 3}px`;
+ ring.style.width = `${t.width + 6}px`;
+ ring.style.height = `${t.height + 6}px`;
+ }, []);
+
+ const close = useCallback(() => {
+ setOpen(false);
+ // The finding, made watchable: today focus returns the instant the dialog
+ // closes, so the ring lights while the panel is still on screen.
+ const wait = mode === 'before' ? 0 : scaledMs('--duration-exit');
+ window.setTimeout(() => {
+ placeRing();
+ setRingOn(true);
+ window.setTimeout(() => setRingOn(false), 700);
+ }, wait);
+ }, [mode, placeRing, scaledMs]);
+
+ const cycle = useCallback(() => {
+ placeRing();
+ setRingOn(false);
+ setOpen(true);
+ window.setTimeout(
+ close,
+ Math.max(1100, scaledMs('--duration-overlay') + 700),
+ );
+ }, [close, placeRing, scaledMs]);
+
+ useEffect(() => {
+ if (!isLooping) {
+ return;
+ }
+ cycle();
+ const period = Math.max(3200, scaledMs('--duration-overlay') * 2 + 2600);
+ const id = window.setInterval(cycle, period);
+ return () => window.clearInterval(id);
+ }, [cycle, isLooping, scaledMs, replayNonce]);
+
+ return (
+ <div ref={stageRef} className={`${styles.stage} ${styles.stageTall}`}>
+ <div ref={triggerRef}>
+ <Button
+ variant="secondary"
+ size="sm"
+ label="Open dialog"
+ onClick={() => {
+ placeRing();
+ setOpen(true);
+ }}
+ />
+ </div>
+ <div
+ data-open={open}
+ className={`${styles.scrim} ${mode === 'after' ? styles.scrimAfter : styles.scrimBefore}`}
+ />
+ <div
+ data-open={open}
+ className={`${styles.dialog} ${mode === 'after' ? styles.dialogAfter : styles.dialogBefore}`}>
+ <Card padding={4}>
+ <VStack gap={2}>
+ <Text weight="semibold">Delete workspace?</Text>
+ <Text type="supporting" color="secondary">
+ This cannot be undone.
+ </Text>
+ <HStack gap={1.5}>
+ <Button
+ size="sm"
+ variant="ghost"
+ label="Cancel"
+ onClick={close}
+ />
+ <Button
+ size="sm"
+ variant="destructive"
+ label="Delete"
+ onClick={close}
+ />
+ </HStack>
+ </VStack>
+ </Card>
+ </div>
+ <div
+ ref={ringRef}
+ className={`${styles.focusMarker} ${ringOn ? styles.focusMarkerOn : ''}`}
+ />
+ </div>
+ );
+}
+
+// --- sliding indicator -------------------------------------------------------
+
+const TAB_NAMES = ['Overview', 'Activity', 'Members', 'Settings', 'Billing'];
+
+export function TabIndicatorRig({mode}: {mode: Mode}) {
+ const [index, setIndex] = useState(0);
+ const rowRef = useRef<HTMLDivElement | null>(null);
+ const indicatorRef = useRef<HTMLSpanElement | null>(null);
+ const tabRefs = useRef<Array<HTMLButtonElement | null>>([]);
+
+ const move = useCallback(() => {
+ if (mode !== 'after') {
+ return;
+ }
+ const row = rowRef.current;
+ const tab = tabRefs.current[index];
+ const indicator = indicatorRef.current;
+ if (row == null || tab == null || indicator == null) {
+ return;
+ }
+ const r = tab.getBoundingClientRect();
+ const p = row.getBoundingClientRect();
+ indicator.style.width = `${r.width - 16}px`;
+ indicator.style.transform = `translateX(${r.left - p.left + 8}px)`;
+ }, [index, mode]);
+
+ useEffect(() => {
+ move();
+ }, [move]);
+
+ useLoop(() => setIndex(i => (i + 1) % TAB_NAMES.length), 2000);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div ref={rowRef} {...stylex.props(sx.tabRow)}>
+ {TAB_NAMES.map((name, i) => (
+ <button
+ key={name}
+ ref={el => {
+ tabRefs.current[i] = el;
+ }}
+ type="button"
+ aria-selected={i === index}
+ onClick={() => setIndex(i)}
+ {...stylex.props(sx.tab, i === index && sx.tabSelected)}>
+ <Text type="supporting">{name}</Text>
+ {mode === 'before' && (
+ <span {...stylex.props(sx.tabBar, i === index && sx.tabBarOn)} />
+ )}
+ </button>
+ ))}
+ {mode === 'after' && (
+ <span ref={indicatorRef} className={styles.indicator} />
+ )}
+ </div>
+ <Hint>
+ {mode === 'before'
+ ? 'Each tab owns its own bar and cross-fades. Nothing travels, so the eye has to re-find the selection after every change.'
+ : 'One indicator travels on --ease-move. The eye follows it, so the selection is never lost.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- disclosure --------------------------------------------------------------
+
+export type DisclosureTechnique = 'grid' | 'height' | 'offset';
+
+export function DisclosureRig({
+ technique,
+ title,
+}: {
+ technique: DisclosureTechnique;
+ title: string;
+}) {
+ const [open, setOpen] = useState(false);
+ const innerRef = useRef<HTMLDivElement | null>(null);
+ const bodyRef = useRef<HTMLDivElement | null>(null);
+
+ useEffect(() => {
+ if (technique === 'grid') {
+ return;
+ }
+ const body = bodyRef.current;
+ const inner = innerRef.current;
+ if (body == null || inner == null) {
+ return;
+ }
+ body.style.height = open ? `${inner.scrollHeight}px` : '0px';
+ }, [open, technique]);
+
+ useLoop(() => setOpen(v => !v), 2600);
+
+ const content = (
+ <VStack gap={1}>
+ <Text type="supporting" color="secondary">
+ Astryx ships nine duration tokens and one easing token.
+ </Text>
+ <Text type="supporting" color="secondary">
+ Nine surfaces disclose content, using three different techniques.
+ </Text>
+ </VStack>
+ );
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <button
+ type="button"
+ onClick={() => setOpen(v => !v)}
+ style={{all: 'unset', cursor: 'pointer', width: '100%'}}>
+ <HStack gap={1.5} vAlign="center">
+ <span
+ className={`${styles.chevron} ${open ? styles.chevronOpen : ''}`}>
+ <Text color="secondary">›</Text>
+ </span>
+ <Text weight="semibold">{title}</Text>
+ </HStack>
+ </button>
+ {technique === 'grid' ? (
+ <div data-open={open} className={styles.gridBody}>
+ <div>
+ <div style={{paddingBlockStart: 6}}>{content}</div>
+ </div>
+ </div>
+ ) : (
+ <div ref={bodyRef} className={styles.heightBody}>
+ <div ref={innerRef} style={{paddingBlockStart: 6}}>
+ {technique === 'offset' ? (
+ <div data-open={open} className={styles.offsetFade}>
+ {content}
+ </div>
+ ) : (
+ content
+ )}
+ </div>
+ </div>
+ )}
+ <Hint>
+ {technique === 'grid'
+ ? 'No measurement needed, and it survives content changing mid-transition. Cannot be used on a table row, which is why this may not be the single winner.'
+ : technique === 'height'
+ ? 'Needs a scrollHeight measurement on every open, so streaming content fights it. Works anywhere, including a table row.'
+ : 'Height plus a delayed content fade. The newest component uses this, and it is the only one that does.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- sidenav rail ------------------------------------------------------------
+
+const RAIL_ITEMS = ['Home', 'Projects', 'Components', 'Tokens', 'Settings'];
+
+export function RailRig({mode}: {mode: Mode}) {
+ const [collapsed, setCollapsed] = useState(false);
+ useLoop(() => setCollapsed(v => !v), 2800);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div {...stylex.props(sx.frame)}>
+ <div
+ data-collapsed={collapsed}
+ className={`${styles.rail} ${mode === 'after' ? styles.railAnimated : ''}`}>
+ <VStack gap={0.5} {...stylex.props(sx.framePad)}>
+ {RAIL_ITEMS.map(item => (
+ <span key={item} {...stylex.props(sx.railItem)}>
+ <span {...stylex.props(sx.railIcon)} />
+ <span className={styles.railLabel}>
+ <Text type="supporting">{item}</Text>
+ </span>
+ </span>
+ ))}
+ </VStack>
+ </div>
+ <div {...stylex.props(sx.framePad)}>
+ <Text type="supporting" color="secondary">
+ Content
+ </Text>
+ </div>
+ </div>
+ <Hint>
+ {mode === 'before'
+ ? 'Only the chevron rotates. The rail snaps between widths, so the content beside it jumps.'
+ : 'The rail\u2019s own width animates on --ease-move and the labels fade slightly ahead of it. width is a layout property, so this is a deliberate criterion-6 exception that needs a written reason.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- skeleton -> content -----------------------------------------------------
+
+export function SkeletonSwapRig({mode}: {mode: Mode}) {
+ const [loaded, setLoaded] = useState(false);
+ useLoop(() => {
+ setLoaded(false);
+ window.setTimeout(() => setLoaded(true), 420);
+ }, 3000);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div
+ data-loaded={loaded}
+ className={`${styles.swap} ${mode === 'before' ? styles.swapHard : ''}`}>
+ <div className={styles.swapContent}>
+ <VStack gap={1}>
+ <Text weight="semibold">Astryx Motion</Text>
+ <Text type="supporting" color="secondary">
+ 48 of 104 core components animate something.
+ </Text>
+ <Text type="supporting" color="secondary">
+ Audited against [email protected].
+ </Text>
+ </VStack>
+ </div>
+ <div className={styles.swapSkeleton}>
+ <VStack gap={1.5}>
+ <Skeleton width="70%" height={12} />
+ <Skeleton width="90%" height={12} />
+ <Skeleton width="55%" height={12} />
+ </VStack>
+ </div>
+ </div>
+ <Hint>
+ {mode === 'before'
+ ? 'Content hard-swaps the instant it arrives, at a moment the user cannot predict.'
+ : 'Skeleton fades out while content fades in, overlapping just enough that the box is never empty.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- chips -------------------------------------------------------------------
+
+const CHIP_POOL = ['design', 'motion', 'tokens', 'a11y', 'core', 'docs'];
+
+export function ChipRig({mode}: {mode: Mode}) {
+ const [chips, setChips] = useState(() => CHIP_POOL.slice(0, 3));
+ const [leaving, setLeaving] = useState<string | null>(null);
+ const {scaledMs} = useMotionLab();
+
+ const remove = useCallback(
+ (name: string) => {
+ if (mode === 'before') {
+ setChips(cs => cs.filter(c => c !== name));
+ return;
+ }
+ setLeaving(name);
+ window.setTimeout(
+ () => {
+ setChips(cs => cs.filter(c => c !== name));
+ setLeaving(null);
+ },
+ scaledMs('--duration-exit') + 30,
+ );
+ },
+ [mode, scaledMs],
+ );
+
+ useLoop(() => {
+ setChips(cs => {
+ if (cs.length >= 5) {
+ return CHIP_POOL.slice(0, 3);
+ }
+ const next = CHIP_POOL.find(c => !cs.includes(c));
+ return next == null ? cs : [...cs, next];
+ });
+ }, 1800);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <HStack gap={1.5} wrap="wrap" style={{minHeight: 62}}>
+ {chips.map(name => (
+ <span
+ key={name}
+ className={
+ mode === 'after'
+ ? leaving === name
+ ? styles.leave
+ : styles.enter
+ : undefined
+ }>
+ <Token label={name} onRemove={() => remove(name)} />
+ </span>
+ ))}
+ </HStack>
+ <Hint>
+ {mode === 'before'
+ ? 'Chips appear and disappear on a frame. The canonical scale-in case, unanimated.'
+ : 'Scale-in with opacity; removal accelerates away and the neighbours close the gap.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- compositor: Outline marker ----------------------------------------------
+
+const OUTLINE_ITEMS = [
+ 'Overview',
+ 'Where motion stands',
+ 'Semantic tokens',
+ 'The rubric',
+ 'Library compatibility',
+ 'Risks',
+];
+
+export function OutlineMarkerRig({mode}: {mode: Mode}) {
+ const [index, setIndex] = useState(0);
+ const listRef = useRef<HTMLDivElement | null>(null);
+ const markerRef = useRef<HTMLSpanElement | null>(null);
+ const itemRefs = useRef<Array<HTMLButtonElement | null>>([]);
+
+ useEffect(() => {
+ const list = listRef.current;
+ const item = itemRefs.current[index];
+ const marker = markerRef.current;
+ if (list == null || item == null || marker == null) {
+ return;
+ }
+ const r = item.getBoundingClientRect();
+ const p = list.getBoundingClientRect();
+ if (mode === 'before') {
+ marker.style.top = `${r.top - p.top}px`;
+ marker.style.height = `${r.height}px`;
+ } else {
+ marker.style.transform = `translateY(${r.top - p.top}px) scaleY(${r.height})`;
+ }
+ }, [index, mode]);
+
+ useLoop(() => setIndex(i => (i + 1) % OUTLINE_ITEMS.length), 1700);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div ref={listRef} {...stylex.props(sx.outlineList)}>
+ <span
+ ref={markerRef}
+ className={`${styles.marker} ${mode === 'before' ? styles.markerLayout : styles.markerComposited}`}
+ />
+ {OUTLINE_ITEMS.map((item, i) => (
+ <button
+ key={item}
+ ref={el => {
+ itemRefs.current[i] = el;
+ }}
+ type="button"
+ onClick={() => setIndex(i)}
+ {...stylex.props(sx.outlineItem, i === index && sx.outlineItemOn)}>
+ <Text type="supporting">{item}</Text>
+ </button>
+ ))}
+ </div>
+ <Hint>
+ {mode === 'before'
+ ? 'Animates top and height, so every frame runs layout, paint and composite for the whole list.'
+ : 'Animates transform only, using scaleY on a 1px marker. Compositor-only, so the list never re-lays-out.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- interruptibility --------------------------------------------------------
+
+export function InterruptRig({mode}: {mode: Mode}) {
+ const [, setOut] = useState(false);
+ const ballRef = useRef<HTMLSpanElement | null>(null);
+
+ const toggle = useCallback(() => {
+ setOut(prev => {
+ const next = !prev;
+ const ball = ballRef.current;
+ if (ball != null && mode === 'before') {
+ // A keyframe cannot retarget: restarting it is the whole finding.
+ ball.classList.remove(styles.ballGo, styles.ballBack);
+ void ball.offsetWidth;
+ ball.classList.add(next ? styles.ballGo : styles.ballBack);
+ } else if (ball != null) {
+ ball.style.transform = next ? 'translateX(170px)' : 'translateX(0)';
+ }
+ return next;
+ });
+ }, [mode]);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div
+ className={`${styles.stage} ${styles.stageStart}`}
+ style={{minHeight: 96}}>
+ <span
+ ref={ballRef}
+ style={{['--ball-distance' as string]: '170px'}}
+ className={`${styles.ball} ${mode === 'before' ? styles.ballKeyframe : styles.ballTransition}`}
+ />
+ </div>
+ <Button
+ size="sm"
+ variant="secondary"
+ label="Toggle — press it twice, fast"
+ onClick={toggle}
+ />
+ <Hint>
+ {mode === 'before'
+ ? 'A keyframe restarts from zero. Interrupt it mid-flight and the box teleports back to the start before running again.'
+ : 'A transition retargets from wherever the box currently is, so an interruption is continuous. Springs behave the same way and also carry velocity through.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- origin ------------------------------------------------------------------
+
+export function OriginRig({kind}: {kind: 'zero' | 'centre' | 'anchored'}) {
+ const [open, setOpen] = useState(false);
+ useLoop(() => {
+ setOpen(false);
+ window.setTimeout(() => setOpen(true), 60);
+ }, 2200);
+
+ const cls =
+ kind === 'zero'
+ ? styles.originZero
+ : kind === 'centre'
+ ? styles.originCentre
+ : styles.originAnchored;
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div
+ className={`${styles.stage} ${styles.stageBlock}`}
+ style={{minHeight: 132}}>
+ <div
+ style={{
+ position: 'absolute',
+ insetInlineStart: 14,
+ insetBlockStart: 14,
+ }}>
+ <Button
+ size="sm"
+ variant="secondary"
+ label="Trigger"
+ onClick={() => setOpen(v => !v)}
+ />
+ </div>
+ <div
+ data-open={open}
+ className={`${styles.originSurface} ${cls}`}
+ style={{insetInlineStart: 14, insetBlockStart: 56}}>
+ <Text type="supporting">
+ {kind === 'zero'
+ ? 'scale(0) — appears from nothing'
+ : kind === 'centre'
+ ? 'Scales from its own centre'
+ : 'Scales from the trigger corner'}
+ </Text>
+ </div>
+ </div>
+ <Hint>
+ {kind === 'zero'
+ ? 'Nothing in the real world appears from nothing. Start from 0.9–0.97 with opacity instead.'
+ : kind === 'centre'
+ ? 'Right scale value, wrong origin: the surface grows out of its own middle rather than out of the control that opened it.'
+ : 'Anchored to the trigger corner, which is what the published page already asks for.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- loops -------------------------------------------------------------------
+
+export function LoopRig({policy}: {policy: 'today' | 'delete' | 'degrade'}) {
+ const stopped = policy !== 'today';
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <HStack gap={4} vAlign="center">
+ <span
+ className={styles.spinner}
+ style={{
+ ['--loop-duration' as string]: policy === 'today' ? '3s' : '975ms',
+ animationPlayState: stopped ? 'paused' : 'running',
+ ...(policy === 'delete' ? {animation: 'none'} : null),
+ ...(policy === 'degrade' ? {animation: 'none'} : null),
+ }}
+ />
+ <span
+ className={styles.pulseDot}
+ style={{
+ ['--loop-duration' as string]: policy === 'today' ? '3s' : '2s',
+ ...(stopped ? {animation: 'none'} : null),
+ }}
+ />
+ <span style={{flex: 1, minWidth: 90}}>
+ <span className={styles.progressTrack}>
+ <span
+ className={styles.progressFillTransform}
+ style={{
+ ['--loop-duration' as string]:
+ policy === 'today' ? '3s' : '1.4s',
+ ...(stopped ? {animation: 'none', width: '62%'} : null),
+ }}
+ />
+ </span>
+ </span>
+ </HStack>
+ <Hint>
+ {policy === 'today'
+ ? 'Today the loop slows to 3s rather than stopping. Slower vestibular motion is still vestibular motion, and it reads as a hung interface.'
+ : policy === 'delete'
+ ? 'Delete: every loop stops. What the published page instructs — and a spinner that does not spin says nothing at all unless it is replaced with a determinate state.'
+ : 'Degrade: loops stop and are replaced with a static determinate state. Opacity and colour feedback survive; movement does not.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- table tint (the 150ms rows) ---------------------------------------------
+
+export function TintRig({mode}: {mode: Mode}) {
+ return (
+ <VStack gap={1} {...stylex.props(sx.full)}>
+ {['Row one', 'Row two', 'Row three'].map(row => (
+ <div
+ key={row}
+ className={styles.tintRow}
+ style={
+ mode === 'after'
+ ? {
+ ['--tint-duration' as string]: 'var(--lab-duration-state)',
+ ['--tint-ease' as string]: 'var(--ease-state)',
+ }
+ : undefined
+ }>
+ <Text type="supporting">{row}</Text>
+ </div>
+ ))}
+ <Hint>
+ {mode === 'before'
+ ? 'Hardcoded 150ms with the CSS default curve.'
+ : 'The state token, at 175ms with --ease-state.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- press / library compatibility -------------------------------------------
+
+export function PressRig({
+ technique,
+}: {
+ technique: 'transform' | 'scale' | 'none';
+}) {
+ const ref = useRef<HTMLSpanElement | null>(null);
+ const raf = useRef<number | null>(null);
+
+ const simulateLibraryDrag = useCallback(() => {
+ const el = ref.current;
+ if (el == null) {
+ return;
+ }
+ if (raf.current != null) {
+ cancelAnimationFrame(raf.current);
+ }
+ const start = performance.now();
+ const step = (now: number) => {
+ const k = (now - start) / 900;
+ if (k >= 1) {
+ el.style.removeProperty('transform');
+ return;
+ }
+ // What a motion library does: writes transform on every frame.
+ el.style.transform = `translateX(${Math.sin(k * Math.PI * 2) * 40}px)`;
+ raf.current = requestAnimationFrame(step);
+ };
+ raf.current = requestAnimationFrame(step);
+ }, []);
+
+ useEffect(
+ () => () => {
+ if (raf.current != null) {
+ cancelAnimationFrame(raf.current);
+ }
+ },
+ [],
+ );
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <HStack gap={2} vAlign="center" wrap="wrap">
+ <span
+ ref={ref}
+ className={
+ technique === 'transform'
+ ? styles.pressTransform
+ : technique === 'scale'
+ ? styles.pressScale
+ : undefined
+ }
+ style={{display: 'inline-flex'}}>
+ <Button
+ variant="secondary"
+ label={
+ technique === 'transform'
+ ? 'transition: transform'
+ : technique === 'scale'
+ ? 'transition: scale'
+ : 'no transition'
+ }
+ />
+ </span>
+ <Button
+ size="sm"
+ variant="ghost"
+ label="Simulate a library drag"
+ onClick={simulateLibraryDrag}
+ />
+ </HStack>
+ <Hint>
+ {technique === 'transform'
+ ? 'Press it, then run the drag. The CSS transition re-eases every transform the library writes, so the drag lags the pointer and a spring never settles.'
+ : technique === 'scale'
+ ? 'Press feedback on the independent scale property, so it no longer collides with the library\u2019s transform writes. Both work — this is the middle path worth prototyping.'
+ : 'No press feedback at all. The library is happy, and every consumer who never installs one loses the affordance.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+// --- misc small rigs ---------------------------------------------------------
+
+export function CheckTickRig({
+ technique,
+}: {
+ technique: 'hard' | 'draw' | 'scale';
+}) {
+ const [checked, setChecked] = useState(false);
+ useLoop(() => setChecked(v => !v), 2000);
+ const cls =
+ technique === 'draw'
+ ? styles.checkDraw
+ : technique === 'scale'
+ ? styles.checkScale
+ : styles.checkHard;
+
+ return (
+ <HStack gap={2} vAlign="center">
+ <button
+ type="button"
+ aria-pressed={checked}
+ data-checked={checked}
+ onClick={() => setChecked(v => !v)}
+ {...stylex.props(sx.checkBox, checked && sx.checkBoxOn)}
+ className={cls}>
+ <svg viewBox="0 0 16 16" width={12} height={12} aria-hidden>
+ <path d="M3 8.5l3.2 3.2L13 4.8" className={styles.checkTick} />
+ </svg>
+ </button>
+ <Text type="supporting" color="secondary">
+ {technique === 'hard'
+ ? 'Appears instantly'
+ : technique === 'draw'
+ ? 'Draws along its path'
+ : 'Scales in'}
+ </Text>
+ </HStack>
+ );
+}
+
+export function StatCountRig({mode}: {mode: Mode}) {
+ const [value, setValue] = useState(1247);
+ const raf = useRef<number | null>(null);
+ const {scaledMs, rawToken} = useMotionLab();
+
+ const to = useCallback(
+ (target: number) => {
+ if (raf.current != null) {
+ cancelAnimationFrame(raf.current);
+ }
+ if (mode === 'before') {
+ setValue(target);
+ return;
+ }
+ const from = value;
+ const duration = scaledMs('--duration-reveal');
+ const start = performance.now();
+ const ease = rawToken('--ease-move');
+ const step = (now: number) => {
+ const k = Math.min(1, (now - start) / duration);
+ // Simple ease-out sample; the curve token is shown for parity with CSS.
+ const eased = 1 - Math.pow(1 - k, 3);
+ setValue(Math.round(from + (target - from) * eased));
+ if (k < 1) {
+ raf.current = requestAnimationFrame(step);
+ }
+ };
+ void ease;
+ raf.current = requestAnimationFrame(step);
+ },
+ [mode, rawToken, scaledMs, value],
+ );
+
+ useLoop(() => to(Math.floor(200 + Math.random() * 9000)), 2600);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <span {...stylex.props(sx.statValue)}>{value.toLocaleString()}</span>
+ <Hint>
+ {mode === 'before'
+ ? 'The number replaces itself, so a change of 4 and a change of 4,000 look identical.'
+ : 'Counts to the new value. Needs a delta threshold so a jump from 12 to 1,300,000 does not spin for a second.'}
+ </Hint>
+ </VStack>
+ );
+}
+
+export function ListReorderRig({mode}: {mode: Mode}) {
+ const [items, setItems] = useState([0, 1, 2, 3]);
+ const listRef = useRef<HTMLDivElement | null>(null);
+ const {scaledMs, rawToken} = useMotionLab();
+
+ const shuffle = useCallback(() => {
+ const list = listRef.current;
+ const before = new Map<Element, DOMRect>();
+ if (list != null && mode === 'after') {
+ for (const child of Array.from(list.children)) {
+ before.set(child, child.getBoundingClientRect());
+ }
+ }
+ setItems(prev => [...prev].sort(() => Math.random() - 0.5));
+ if (list == null || mode !== 'after') {
+ return;
+ }
+ // FLIP: measure, move, invert, play.
+ requestAnimationFrame(() => {
+ for (const child of Array.from(list.children)) {
+ const first = before.get(child);
+ if (first == null) {
+ continue;
+ }
+ const last = child.getBoundingClientRect();
+ const dy = first.top - last.top;
+ if (dy === 0) {
+ continue;
+ }
+ child.animate(
+ [{transform: `translateY(${dy}px)`}, {transform: 'none'}],
+ {
+ duration: scaledMs('--duration-reveal'),
+ easing: rawToken('--ease-move'),
+ },
+ );
+ }
+ });
+ }, [mode, rawToken, scaledMs]);
+
+ useLoop(shuffle, 2600);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div
+ ref={listRef}
+ style={{display: 'flex', flexDirection: 'column', gap: 6}}>
+ {items.map(n => (
+ <span key={n} {...stylex.props(sx.listRow)}>
+ <span
+ {...stylex.props(sx.swatch)}
+ style={{backgroundColor: `hsl(${200 + n * 34} 55% 55%)`}}
+ />
+ <Text type="supporting">Item {n + 1}</Text>
+ </span>
+ ))}
+ </div>
+ <Hint>
+ {mode === 'before'
+ ? 'Reorder is instant, so the user has to re-read the list to find out what changed.'
+ : 'FLIP: measure, move, invert, play. Rows travel on --ease-move, so a change the user did not initiate stays followable.'}
+ </Hint>
+ </VStack>
+ );
+}
diff --git a/apps/sandbox/src/motion/LabPrimitives.tsx b/apps/sandbox/src/motion/LabPrimitives.tsx
new file mode 100644
index 0000000000..acc78ea4e8
--- /dev/null
+++ b/apps/sandbox/src/motion/LabPrimitives.tsx
@@ -0,0 +1,607 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file LabPrimitives.tsx
+ * @input Motion Lab store, Astryx Core components
+ * @output The frames every demo page is built out of
+ * @position Motion Lab shared UI
+ *
+ * Everything here is Core: Card for the demo frame, Slider for every tunable
+ * value, Table for every list, SegmentedControl for every mode switch. The
+ * only hand-written pieces are the ones Core has no component for — a
+ * cubic-bezier editor and a travelling box — and those are the lab's actual
+ * subject matter rather than chrome around it.
+ */
+
+import {
+ useCallback,
+ useEffect,
+ useId,
+ useLayoutEffect,
+ useRef,
+ useState,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Card} from '@astryxdesign/core/Card';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Slider} from '@astryxdesign/core/Slider';
+import {Grid} from '@astryxdesign/core/Grid';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {useMotionLab, parseMs} from './MotionLabStore';
+import {
+ bezierAt,
+ formatBezier,
+ isNamedCurve,
+ parseBezier,
+ plotPath,
+ type BezierPoints,
+} from './spring';
+import styles from './MotionLab.module.css';
+
+const sx = stylex.create({
+ fill: {width: '100%'},
+ grow: {flexGrow: 1, minWidth: 0},
+ paneLabel: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '6px',
+ marginBottom: '10px',
+ },
+ dot: {
+ width: '7px',
+ height: '7px',
+ borderRadius: '50%',
+ flexShrink: 0,
+ },
+ dotBefore: {backgroundColor: 'var(--color-background-error, #d3543f)'},
+ dotAfter: {backgroundColor: 'var(--color-background-success, #3f9a6b)'},
+ dotNeutral: {backgroundColor: 'var(--color-text-tertiary, #8a8a8a)'},
+ pane: {
+ minWidth: 0,
+ padding: '14px',
+ },
+ splitBorder: {
+ borderInlineStart: '1px solid var(--color-border)',
+ },
+ meterTrack: {
+ height: '5px',
+ borderRadius: '3px',
+ backgroundColor: 'var(--color-background-base)',
+ overflow: 'hidden',
+ width: '100%',
+ },
+ meterFill: {height: '100%', borderRadius: '3px'},
+ sliderRow: {width: '100%', maxWidth: '540px'},
+ demoBody: {padding: '14px'},
+ headerRow: {padding: '12px 14px'},
+ code: {
+ fontFamily: 'var(--font-family-code)',
+ fontSize: '12px',
+ },
+});
+
+// --- demo frame -------------------------------------------------------------
+
+/**
+ * One decision per card. `question` is the thing the reader is meant to be
+ * able to answer after looking at it — a demo that cannot name one is
+ * decoration and should not be here.
+ */
+export function DemoCard({
+ title,
+ question,
+ badges,
+ actions,
+ children,
+ controls,
+}: {
+ title: string;
+ question?: string;
+ badges?: ReactNode;
+ actions?: ReactNode;
+ children: ReactNode;
+ controls?: ReactNode;
+}) {
+ return (
+ <Card padding={0} {...stylex.props(sx.fill)}>
+ <VStack gap={0}>
+ <HStack
+ gap={2}
+ vAlign="center"
+ justify="between"
+ {...stylex.props(sx.headerRow)}>
+ <VStack gap={0.5} {...stylex.props(sx.grow)}>
+ <HStack gap={1} vAlign="center">
+ <Heading level={3}>{title}</Heading>
+ {badges}
+ </HStack>
+ {question != null && (
+ <Text type="supporting" color="secondary">
+ {question}
+ </Text>
+ )}
+ </VStack>
+ {actions != null && <HStack gap={1}>{actions}</HStack>}
+ </HStack>
+ <Divider isFullBleed />
+ {children}
+ {controls != null && (
+ <>
+ <Divider isFullBleed />
+ <VStack gap={2} {...stylex.props(sx.demoBody)}>
+ {controls}
+ </VStack>
+ </>
+ )}
+ </VStack>
+ </Card>
+ );
+}
+
+/** The plain body slot, when a card holds content rather than a comparison. */
+export function DemoBody({children}: {children: ReactNode}) {
+ return (
+ <VStack gap={2} {...stylex.props(sx.demoBody)}>
+ {children}
+ </VStack>
+ );
+}
+
+// --- before / after ---------------------------------------------------------
+
+export type Pane = {
+ readonly tone: 'before' | 'after' | 'neutral';
+ readonly label: string;
+ readonly content: ReactNode;
+};
+
+/**
+ * Panes sit side by side and the rail's compare switch hides one side, so a
+ * reader can look at just the proposal without the failing version pulling
+ * the eye. Three panes is a bake-off rather than a comparison; the same
+ * component carries both because the only difference is how many there are.
+ */
+export function ComparePanes({panes}: {panes: ReadonlyArray<Pane>}) {
+ const {compare} = useMotionLab();
+ const visible = panes.filter(pane => {
+ if (compare === 'both') {
+ return true;
+ }
+ if (compare === 'before') {
+ return pane.tone !== 'after';
+ }
+ return pane.tone !== 'before';
+ });
+ const shown = visible.length > 0 ? visible : panes;
+
+ return (
+ <Grid columns={shown.length} gap={0}>
+ {shown.map((pane, i) => (
+ <VStack
+ key={pane.label}
+ gap={0}
+ {...stylex.props(sx.pane, i > 0 && sx.splitBorder)}>
+ <span {...stylex.props(sx.paneLabel)}>
+ <span
+ {...stylex.props(
+ sx.dot,
+ pane.tone === 'before'
+ ? sx.dotBefore
+ : pane.tone === 'after'
+ ? sx.dotAfter
+ : sx.dotNeutral,
+ )}
+ />
+ <Text type="supporting" color="secondary" weight="semibold">
+ {pane.label}
+ </Text>
+ </span>
+ {pane.content}
+ </VStack>
+ ))}
+ </Grid>
+ );
+}
+
+// --- controls ---------------------------------------------------------------
+
+/**
+ * A Core Slider bound to a custom property. Nothing else in the lab writes a
+ * duration, so tuning is always the same gesture and always lands in the one
+ * place the export reads from.
+ */
+export function TokenSlider({
+ token,
+ label,
+ min = 0,
+ max = 900,
+ step = 5,
+ onAfterChange,
+}: {
+ token: string;
+ label?: string;
+ min?: number;
+ max?: number;
+ step?: number;
+ onAfterChange?: () => void;
+}) {
+ const {rawToken, setToken} = useMotionLab();
+ const value = parseMs(rawToken(token));
+ return (
+ <div {...stylex.props(sx.sliderRow)}>
+ <Slider
+ label={label ?? token.replace(/^--(duration|stagger)-/, '')}
+ value={value}
+ min={min}
+ max={max}
+ step={step}
+ valueDisplay="text"
+ formatValue={v => `${v}ms`}
+ onChange={(v: number) => {
+ setToken(token, `${v}ms`);
+ onAfterChange?.();
+ }}
+ />
+ </div>
+ );
+}
+
+/** A plain numeric slider for values that are not tokens (spring bounce etc). */
+export function LabSlider({
+ label,
+ value,
+ min,
+ max,
+ step,
+ format,
+ onChange,
+}: {
+ label: string;
+ value: number;
+ min: number;
+ max: number;
+ step: number;
+ format?: (v: number) => string;
+ onChange: (v: number) => void;
+}) {
+ return (
+ <div {...stylex.props(sx.sliderRow)}>
+ <Slider
+ label={label}
+ value={value}
+ min={min}
+ max={max}
+ step={step}
+ valueDisplay="text"
+ formatValue={format}
+ onChange={onChange}
+ />
+ </div>
+ );
+}
+
+/** How far a duration sits inside the published interface budget. */
+export function BudgetMeter({token}: {token: string}) {
+ const {rawToken} = useMotionLab();
+ const ms = parseMs(rawToken(token));
+ const ceiling = 600;
+ const pct = Math.min(100, (ms / ceiling) * 100);
+ const tone =
+ ms > 500
+ ? 'var(--color-background-error, #d3543f)'
+ : ms > 300
+ ? 'var(--color-background-warning, #c98a1f)'
+ : 'var(--color-brand)';
+ const note =
+ ms > 500
+ ? 'Outside every interface budget'
+ : ms > 300
+ ? 'Overlays only above 300ms'
+ : 'Inside the interface budget';
+ return (
+ <VStack gap={1} {...stylex.props(sx.fill)}>
+ <span {...stylex.props(sx.meterTrack)}>
+ <span
+ {...stylex.props(sx.meterFill)}
+ style={{width: `${pct}%`, backgroundColor: tone}}
+ />
+ </span>
+ <Text type="supporting" color="secondary">
+ {note}
+ </Text>
+ </VStack>
+ );
+}
+
+// --- runner -----------------------------------------------------------------
+
+/**
+ * One box crossing a fixed distance. The least interesting demo in the lab and
+ * the most useful, because there is nothing else in the frame to attribute the
+ * feel to — a curve read off a moving box is read honestly.
+ */
+export function Runner({
+ durationToken,
+ easeToken,
+ auto = true,
+}: {
+ durationToken: string;
+ easeToken: string;
+ auto?: boolean;
+}) {
+ const {scaledMs, rawToken, isLooping, replayNonce} = useMotionLab();
+ const dotRef = useRef<HTMLSpanElement | null>(null);
+ const trackRef = useRef<HTMLDivElement | null>(null);
+
+ const run = useCallback(() => {
+ const dot = dotRef.current;
+ const track = trackRef.current;
+ if (dot == null || track == null) {
+ return;
+ }
+ for (const animation of dot.getAnimations()) {
+ animation.cancel();
+ }
+ const distance = Math.max(0, track.clientWidth - 36);
+ dot.animate(
+ [{transform: 'translateX(0)'}, {transform: `translateX(${distance}px)`}],
+ {
+ duration: Math.max(1, scaledMs(durationToken)),
+ easing: rawToken(easeToken) || 'linear',
+ fill: 'both',
+ },
+ );
+ }, [durationToken, easeToken, rawToken, scaledMs]);
+
+ useEffect(() => {
+ run();
+ }, [run, replayNonce]);
+
+ useEffect(() => {
+ if (!auto || !isLooping) {
+ return;
+ }
+ const period = Math.max(900, scaledMs(durationToken) + 900);
+ const id = window.setInterval(run, period);
+ return () => window.clearInterval(id);
+ }, [auto, isLooping, run, scaledMs, durationToken]);
+
+ return (
+ <div ref={trackRef} className={styles.runner}>
+ <span ref={dotRef} className={styles.runnerDot} />
+ </div>
+ );
+}
+
+// --- cubic-bezier editor -----------------------------------------------------
+
+// The plot box is taller than 0..1 so an overshooting curve stays readable
+// rather than clipping at the top. Module scope keeps the hook deps honest.
+const pad = 22;
+const yMin = -0.35;
+const yMax = 1.35;
+
+/**
+ * Draggable control points over a plotted curve. Core has no equivalent and
+ * should not — this is a tool for authoring a token, not a product control.
+ * The box is deliberately taller than 0..1 so an overshooting curve is still
+ * readable rather than clipped at the top.
+ */
+export function CurveEditor({
+ value,
+ onChange,
+ size = 176,
+ presets,
+}: {
+ value: string;
+ onChange: (next: string) => void;
+ size?: number;
+ presets?: ReadonlyArray<readonly [string, string]>;
+}) {
+ const [points, setPoints] = useState<BezierPoints>(() => parseBezier(value));
+ const svgRef = useRef<SVGSVGElement | null>(null);
+ const dragging = useRef<0 | 1 | null>(null);
+ const titleId = useId();
+
+ useEffect(() => {
+ if (dragging.current == null) {
+ setPoints(parseBezier(value));
+ }
+ }, [value]);
+
+ const X = (x: number) => pad + x * (size - pad * 2);
+ const Y = (y: number) =>
+ size - pad - ((y - yMin) / (yMax - yMin)) * (size - pad * 2);
+
+ const commit = useCallback(
+ (next: BezierPoints) => {
+ setPoints(next);
+ onChange(formatBezier(next));
+ },
+ [onChange],
+ );
+
+ const onPointerMove = useCallback(
+ (event: React.PointerEvent<SVGSVGElement>) => {
+ const handle = dragging.current;
+ const svg = svgRef.current;
+ if (handle == null || svg == null) {
+ return;
+ }
+ const rect = svg.getBoundingClientRect();
+ const x = (event.clientX - rect.left - pad) / (size - pad * 2);
+ const y =
+ yMax -
+ ((event.clientY - rect.top - pad) / (size - pad * 2)) * (yMax - yMin);
+ const clampedX = Math.min(1, Math.max(0, x));
+ const clampedY = Math.min(yMax, Math.max(yMin, y));
+ const next: BezierPoints =
+ handle === 0
+ ? [clampedX, clampedY, points[2], points[3]]
+ : [points[0], points[1], clampedX, clampedY];
+ commit(next);
+ },
+ [commit, points, size],
+ );
+
+ const nudge = useCallback(
+ (handle: 0 | 1, dx: number, dy: number) => {
+ const ix = handle === 0 ? 0 : 2;
+ const iy = handle === 0 ? 1 : 3;
+ const next = [...points] as [number, number, number, number];
+ next[ix] = Math.min(1, Math.max(0, next[ix] + dx));
+ next[iy] = Math.min(yMax, Math.max(yMin, next[iy] + dy));
+ commit(next as unknown as BezierPoints);
+ },
+ [commit, points],
+ );
+
+ const handleKey = (handle: 0 | 1) => (event: React.KeyboardEvent) => {
+ const step = event.shiftKey ? 0.1 : 0.02;
+ const map: Record<string, [number, number]> = {
+ ArrowLeft: [-step, 0],
+ ArrowRight: [step, 0],
+ ArrowUp: [0, step],
+ ArrowDown: [0, -step],
+ };
+ const delta = map[event.key];
+ if (delta != null) {
+ event.preventDefault();
+ nudge(handle, delta[0], delta[1]);
+ }
+ };
+
+ return (
+ <VStack gap={2}>
+ <svg
+ ref={svgRef}
+ className={styles.curveCanvas}
+ width={size}
+ height={size}
+ viewBox={`0 0 ${size} ${size}`}
+ role="img"
+ aria-labelledby={titleId}
+ onPointerMove={onPointerMove}
+ onPointerUp={() => {
+ dragging.current = null;
+ }}
+ onPointerLeave={() => {
+ dragging.current = null;
+ }}>
+ <title id={titleId}>{`Easing curve ${formatBezier(points)}`}</title>
+ <rect
+ x={X(0)}
+ y={Y(1)}
+ width={X(1) - X(0)}
+ height={Y(0) - Y(1)}
+ fill="none"
+ stroke="var(--color-border)"
+ strokeDasharray="3 3"
+ />
+ <line
+ x1={X(0)}
+ y1={Y(0)}
+ x2={X(points[0])}
+ y2={Y(points[1])}
+ stroke="var(--color-text-tertiary, #8a8a8a)"
+ />
+ <line
+ x1={X(1)}
+ y1={Y(1)}
+ x2={X(points[2])}
+ y2={Y(points[3])}
+ stroke="var(--color-text-tertiary, #8a8a8a)"
+ />
+ <path
+ d={plotPath(x => bezierAt(points, x), size, size, pad, yMin, yMax)}
+ fill="none"
+ stroke="var(--color-brand)"
+ strokeWidth={2}
+ />
+ {([0, 1] as const).map(handle => {
+ const cx = handle === 0 ? points[0] : points[2];
+ const cy = handle === 0 ? points[1] : points[3];
+ return (
+ <circle
+ key={handle}
+ className={styles.grabbable}
+ cx={X(cx)}
+ cy={Y(cy)}
+ r={7}
+ fill={
+ handle === 0
+ ? 'var(--color-brand)'
+ : 'var(--color-background-success, #3f9a6b)'
+ }
+ tabIndex={0}
+ role="slider"
+ aria-label={`Control point ${handle + 1}`}
+ aria-valuetext={`x ${cx.toFixed(2)}, y ${cy.toFixed(2)}`}
+ onKeyDown={handleKey(handle)}
+ onPointerDown={event => {
+ event.preventDefault();
+ dragging.current = handle;
+ }}
+ />
+ );
+ })}
+ </svg>
+ <Text {...stylex.props(sx.code)} color="secondary">
+ {formatBezier(points)}
+ </Text>
+ {presets != null && presets.length > 0 && (
+ <HStack gap={1} {...stylex.props(sx.fill)}>
+ {presets.map(([label, preset]) => (
+ <Badge
+ key={label}
+ label={
+ <button
+ type="button"
+ onClick={() => commit(parseBezier(preset))}
+ style={{all: 'unset', cursor: 'pointer'}}>
+ {label}
+ </button>
+ }
+ />
+ ))}
+ </HStack>
+ )}
+ </VStack>
+ );
+}
+
+export {isNamedCurve};
+
+/** Re-runs a callback whenever the rail's replay is pressed. */
+export function useReplay(run: () => void) {
+ const {replayNonce} = useMotionLab();
+ const ref = useRef(run);
+ useLayoutEffect(() => {
+ ref.current = run;
+ });
+ useEffect(() => {
+ ref.current();
+ }, [replayNonce]);
+}
+
+/** Drives a demo on a loop while the rail's loop switch is on. */
+export function useLoop(run: () => void, periodMs: number) {
+ const {isLooping, replayNonce} = useMotionLab();
+ const ref = useRef(run);
+ useLayoutEffect(() => {
+ ref.current = run;
+ });
+ useEffect(() => {
+ ref.current();
+ if (!isLooping) {
+ return;
+ }
+ const id = window.setInterval(() => ref.current(), Math.max(700, periodMs));
+ return () => window.clearInterval(id);
+ }, [isLooping, periodMs, replayNonce]);
+}
diff --git a/apps/sandbox/src/motion/MotionControlRail.tsx b/apps/sandbox/src/motion/MotionControlRail.tsx
new file mode 100644
index 0000000000..08b1f76ba8
--- /dev/null
+++ b/apps/sandbox/src/motion/MotionControlRail.tsx
@@ -0,0 +1,159 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file MotionControlRail.tsx
+ * @input Motion Lab store
+ * @output The sticky bar of viewing modes that applies to every page
+ * @position Motion Lab chrome; rendered by app/motion/layout.tsx
+ *
+ * These four controls are the difference between a gallery and a bench.
+ *
+ * Slow-mo stretches every duration without moving the token, so a 175ms curve
+ * can be judged at 8x and then exported at 175ms. Reduced motion drives the
+ * real policy switch rather than a caption about it. Compare hides one half of
+ * every before/after so the proposal can be looked at on its own. Loop keeps
+ * the demos running, because a comparison you have to click twice to see is a
+ * comparison nobody makes.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {Button} from '@astryxdesign/core/Button';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {Slider} from '@astryxdesign/core/Slider';
+import {Tooltip} from '@astryxdesign/core/Tooltip';
+import {HStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {
+ useMotionLab,
+ type CompareMode,
+ type ReducedMotionMode,
+} from './MotionLabStore';
+
+const sx = stylex.create({
+ rail: {
+ position: 'sticky',
+ top: 'var(--astryx-header-offset, 0px)',
+ zIndex: 40,
+ width: '100%',
+ boxSizing: 'border-box',
+ padding: '8px 16px',
+ borderBlockEnd: '1px solid var(--color-border)',
+ backgroundColor: 'var(--color-background-surface)',
+ },
+ speed: {width: '132px'},
+ grow: {flexGrow: 1},
+ value: {
+ fontFamily: 'var(--font-family-code)',
+ minWidth: '34px',
+ },
+});
+
+const SPEEDS = [1, 2, 4, 8] as const;
+
+export function MotionControlRail() {
+ const {
+ speed,
+ setSpeed,
+ reducedMotion,
+ setReducedMotion,
+ compare,
+ setCompare,
+ isLooping,
+ setLooping,
+ replay,
+ reset,
+ dirtyTokens,
+ } = useMotionLab();
+
+ return (
+ <HStack gap={3} vAlign="center" wrap="wrap" {...stylex.props(sx.rail)}>
+ <HStack gap={1.5} vAlign="center">
+ <Text type="supporting" color="secondary">
+ Speed
+ </Text>
+ <div {...stylex.props(sx.speed)}>
+ <Slider
+ label="Slow motion multiplier"
+ isLabelHidden
+ value={speed}
+ min={0.25}
+ max={8}
+ step={0.25}
+ valueDisplay="none"
+ onChange={setSpeed}
+ />
+ </div>
+ <Text {...stylex.props(sx.value)} type="supporting">
+ {speed}&times;
+ </Text>
+ <HStack gap={0.5}>
+ {SPEEDS.map(s => (
+ <Button
+ key={s}
+ size="sm"
+ variant={speed === s ? 'secondary' : 'ghost'}
+ label={`${s}×`}
+ onClick={() => setSpeed(s)}
+ />
+ ))}
+ </HStack>
+ </HStack>
+
+ <HStack gap={1.5} vAlign="center">
+ <Text type="supporting" color="secondary">
+ Reduced motion
+ </Text>
+ <SegmentedControl
+ label="Reduced motion policy"
+ size="sm"
+ value={reducedMotion}
+ onChange={value => setReducedMotion(value as ReducedMotionMode)}>
+ <SegmentedControlItem value="off" label="Off" />
+ <SegmentedControlItem value="degrade" label="Degrade" />
+ <SegmentedControlItem value="delete" label="Delete" />
+ </SegmentedControl>
+ </HStack>
+
+ <HStack gap={1.5} vAlign="center">
+ <Text type="supporting" color="secondary">
+ Show
+ </Text>
+ <SegmentedControl
+ label="Which side of each comparison to show"
+ size="sm"
+ value={compare}
+ onChange={value => setCompare(value as CompareMode)}>
+ <SegmentedControlItem value="both" label="Both" />
+ <SegmentedControlItem value="before" label="Today" />
+ <SegmentedControlItem value="after" label="Proposed" />
+ </SegmentedControl>
+ </HStack>
+
+ <span {...stylex.props(sx.grow)} />
+
+ <HStack gap={1} vAlign="center">
+ {dirtyTokens.length > 0 && (
+ <Tooltip
+ content={`${dirtyTokens.length} token(s) changed from the proposal`}>
+ <Text type="supporting" color="secondary">
+ {dirtyTokens.length} tuned
+ </Text>
+ </Tooltip>
+ )}
+ <Button
+ size="sm"
+ variant={isLooping ? 'secondary' : 'ghost'}
+ label={isLooping ? 'Looping' : 'Loop off'}
+ onClick={() => setLooping(!isLooping)}
+ />
+ <Button size="sm" variant="ghost" label="Replay" onClick={replay} />
+ <Button size="sm" variant="ghost" label="Reset" onClick={reset} />
+ </HStack>
+ </HStack>
+ );
+}
diff --git a/apps/sandbox/src/motion/MotionLab.module.css b/apps/sandbox/src/motion/MotionLab.module.css
new file mode 100644
index 0000000000..e84bf423b2
--- /dev/null
+++ b/apps/sandbox/src/motion/MotionLab.module.css
@@ -0,0 +1,914 @@
+/* Copyright (c) Meta Platforms, Inc. and affiliates. */
+
+/*
+ * The motion the lab is here to argue about.
+ *
+ * A CSS module rather than the `xstyle` prop because almost nothing in this
+ * file can be expressed as a style object: `@keyframes`, `@starting-style`,
+ * `transition-behavior: allow-discrete`, and the `:popover-open` state are the
+ * proposal's actual subject matter, not decoration around it. The exit-gap
+ * page in particular has to run the real technique in the real browser — a
+ * simulation would be answering a different question than the one the reader
+ * came with.
+ *
+ * Two rules hold everywhere below:
+ *
+ * 1. Nothing reads a raw `--duration-*` token. Demos read the `--lab-duration-*`
+ * aliases the store writes, which are the same values multiplied by the
+ * slow-mo factor. Tuning a token and watching it at 8x are then independent,
+ * and the value the export page writes out is never the stretched one.
+ *
+ * 2. Movement is multiplied by `--lab-translate` / `--lab-scale`. Reduced
+ * motion set to "degrade" zeroes those two and leaves opacity and colour
+ * alone, which is the whole distinction the degrade-or-delete decision
+ * turns on. Setting it to "delete" additionally collapses the durations.
+ */
+
+.scope {
+ /* Movement multipliers — the reduced-motion switch drives these. */
+ --lab-translate: 1;
+ --lab-scale: 1;
+
+ /* Fallbacks, so a demo still runs if it mounts before the store's effect. */
+ --lab-duration-instant: 0ms;
+ --lab-duration-press: 130ms;
+ --lab-duration-state: 175ms;
+ --lab-duration-enter: 230ms;
+ --lab-duration-exit: 175ms;
+ --lab-duration-reveal: 310ms;
+ --lab-duration-overlay: 410ms;
+ --lab-duration-continuous: 975ms;
+ --lab-stagger-tight: 30ms;
+ --lab-stagger-base: 50ms;
+ --lab-stagger-loose: 80ms;
+ --lab-speed: 1;
+}
+
+/* The reduced-motion policy is applied by MotionLabStore, not here: it writes
+ --lab-* inline on this element, and an inline custom property beats any
+ selector in this file. Redeclaring them under a [data-reduced-motion]
+ selector looked correct and silently did nothing. Only the loop rule below
+ stays in CSS, because `animation: none !important` does outrank the
+ element's own animation shorthand. */
+
+/* Continuous loops stop under either policy. Criterion 10 is explicit that
+ they stop rather than slow down, which is the finding against Spinner and
+ ProgressBar today. */
+.scope[data-reduced-motion='degrade'] .loop,
+.scope[data-reduced-motion='delete'] .loop {
+ animation: none !important;
+}
+
+/* ---------------------------------------------------------------- stage --- */
+
+.stage {
+ position: relative;
+ display: grid;
+ place-items: center;
+ min-height: 132px;
+ padding: var(--space-4, 16px);
+ border-radius: var(--radius-md, 8px);
+ background: var(--color-background-base);
+ border: 1px solid var(--color-border-subtle, var(--color-border));
+ overflow: hidden;
+}
+
+.stageTall {
+ min-height: 210px;
+}
+
+.stageStart {
+ place-items: center start;
+}
+
+.stageBlock {
+ display: block;
+}
+
+/* ------------------------------------------------------------- runner ---- */
+
+/* A single box travelling a fixed distance: the cleanest way to read a curve,
+ because there is nothing else in the frame to attribute the feel to. */
+.runner {
+ position: relative;
+ height: 40px;
+ border-radius: var(--radius-md, 8px);
+ background: var(--color-background-base);
+ border: 1px dashed var(--color-border);
+ overflow: hidden;
+}
+
+.runnerDot {
+ position: absolute;
+ inset-block-start: 50%;
+ inset-inline-start: 5px;
+ width: 26px;
+ height: 26px;
+ margin-block-start: -13px;
+ border-radius: var(--radius-md, 7px);
+ background: var(--color-brand, var(--color-background-inverse));
+}
+
+/* ------------------------------------------------------------- layers ---- */
+
+/*
+ * The exit gap, both halves.
+ *
+ * `.layerBefore` reproduces what eleven components do today: a transition on
+ * the way in, and nothing at all on the way out, so the element is simply
+ * hidden on the next frame. It is deliberately not "a fast exit" — the whole
+ * finding is that there is no exit.
+ */
+.layer {
+ position: absolute;
+ z-index: 5;
+ min-width: 132px;
+ padding: var(--space-2, 8px) var(--space-3, 12px);
+ border-radius: var(--radius-md, 9px);
+ background: var(--color-background-elevated, var(--color-background-surface));
+ border: 1px solid var(--color-border);
+ box-shadow: var(--shadow-overlay, 0 14px 34px -14px rgb(0 0 0 / 55%));
+ opacity: 0;
+ visibility: hidden;
+ transform: translateY(calc(-4px * var(--lab-translate)))
+ scale(calc(1 - 0.04 * var(--lab-scale)));
+ transform-origin: var(--layer-origin, top center);
+}
+
+.layerAfter {
+ transition:
+ opacity var(--lab-duration-exit) var(--ease-exit),
+ transform var(--lab-duration-exit) var(--ease-exit),
+ visibility 0s linear var(--lab-duration-exit);
+}
+
+.layerAfter[data-open='true'] {
+ opacity: 1;
+ visibility: visible;
+ transform: translateY(0) scale(1);
+ transition:
+ opacity var(--lab-duration-enter) var(--ease-entry),
+ transform var(--lab-duration-enter) var(--ease-entry),
+ visibility 0s linear 0s;
+}
+
+.layerBefore[data-open='true'] {
+ opacity: 1;
+ visibility: visible;
+ transform: translateY(0) scale(1);
+ transition:
+ opacity var(--lab-duration-enter) var(--ease-standard),
+ transform var(--lab-duration-enter) var(--ease-standard);
+}
+
+/* --------------------------------------------------- native popover ------ */
+
+/*
+ * The proposed implementation, running for real: a transition on `display` and
+ * `overlay` with `allow-discrete` keeps the element in the top layer for the
+ * length of its exit, and `@starting-style` gives it somewhere to enter from.
+ * This is the card that decides whether the shared primitive needs a JS
+ * fallback, so it must not be faked.
+ */
+.nativePopover {
+ margin: 0;
+ padding: var(--space-3, 12px);
+ border-radius: var(--radius-md, 9px);
+ background: var(--color-background-elevated, var(--color-background-surface));
+ color: var(--color-text-primary);
+ border: 1px solid var(--color-border);
+ box-shadow: var(--shadow-overlay, 0 14px 34px -14px rgb(0 0 0 / 55%));
+ max-width: 320px;
+ opacity: 0;
+ transform: scale(0.96) translateY(-4px);
+ transform-origin: top center;
+ transition:
+ opacity var(--lab-duration-exit) var(--ease-exit),
+ transform var(--lab-duration-exit) var(--ease-exit),
+ display var(--lab-duration-exit) allow-discrete,
+ overlay var(--lab-duration-exit) allow-discrete;
+}
+
+.nativePopover:popover-open {
+ opacity: 1;
+ transform: scale(1) translateY(0);
+ transition:
+ opacity var(--lab-duration-enter) var(--ease-entry),
+ transform var(--lab-duration-enter) var(--ease-entry),
+ display var(--lab-duration-enter) allow-discrete,
+ overlay var(--lab-duration-enter) allow-discrete;
+}
+
+@starting-style {
+ .nativePopover:popover-open {
+ opacity: 0;
+ transform: scale(0.96) translateY(-4px);
+ }
+}
+
+/* -------------------------------------------------------------- dialog --- */
+
+.scrim {
+ position: absolute;
+ inset: 0;
+ background: rgb(0 0 0 / 50%);
+ opacity: 0;
+ visibility: hidden;
+}
+
+/* The backdrop has no transition at all today, so the scrim hard-cuts even
+ where the panel animates. Two separate bugs, two separate controls. */
+.scrimAfter {
+ transition:
+ opacity var(--lab-duration-overlay) linear,
+ visibility 0s linear var(--lab-duration-overlay);
+}
+
+.scrimAfter[data-open='true'] {
+ opacity: 1;
+ visibility: visible;
+ transition: opacity var(--lab-duration-overlay) linear, visibility 0s;
+}
+
+.scrimBefore[data-open='true'] {
+ opacity: 1;
+ visibility: visible;
+}
+
+.dialog {
+ position: absolute;
+ inset-inline-start: 50%;
+ inset-block-start: 50%;
+ z-index: 4;
+ width: min(260px, 78%);
+ opacity: 0;
+ visibility: hidden;
+ transform: translate(-50%, calc(-50% + 10px * var(--lab-translate)))
+ scale(calc(1 - 0.04 * var(--lab-scale)));
+}
+
+.dialogAfter {
+ transition:
+ opacity var(--lab-duration-exit) var(--ease-exit),
+ transform var(--lab-duration-exit) var(--ease-exit),
+ visibility 0s linear var(--lab-duration-exit);
+}
+
+.dialogAfter[data-open='true'] {
+ opacity: 1;
+ visibility: visible;
+ transform: translate(-50%, -50%) scale(1);
+ transition:
+ opacity var(--lab-duration-overlay) var(--ease-entry),
+ transform var(--lab-duration-overlay) var(--ease-entry),
+ visibility 0s;
+}
+
+.dialogBefore[data-open='true'] {
+ opacity: 1;
+ visibility: visible;
+ transform: translate(-50%, -50%) scale(1);
+ animation: dialogIn var(--lab-duration-overlay) var(--ease-standard);
+}
+
+@keyframes dialogIn {
+ from {
+ opacity: 0;
+ transform: translate(-50%, calc(-50% + 10px)) scale(0.96);
+ }
+}
+
+/* The trigger's focus ring, drawn as a marker so the race is watchable:
+ today it lights the instant the dialog closes, mid-exit. */
+.focusMarker {
+ position: absolute;
+ border: 2px solid var(--color-border-focus, var(--color-brand));
+ border-radius: var(--radius-md, 8px);
+ opacity: 0;
+ pointer-events: none;
+ transition: opacity 90ms linear;
+}
+
+.focusMarkerOn {
+ opacity: 1;
+}
+
+/* -------------------------------------------------------------- drawer --- */
+
+.drawer {
+ position: absolute;
+ inset-block: 0;
+ inset-inline-end: 0;
+ width: 62%;
+ z-index: 4;
+ padding: var(--space-4, 16px);
+ background: var(--color-background-surface);
+ border-inline-start: 1px solid var(--color-border);
+ transform: translateX(100%);
+ visibility: hidden;
+ transition:
+ transform var(--drawer-slide, 410ms) var(--ease-drawer),
+ visibility 0s linear var(--drawer-slide, 410ms);
+}
+
+.drawer[data-open='true'] {
+ transform: translateX(0);
+ visibility: visible;
+ transition: transform var(--drawer-slide, 410ms) var(--ease-drawer), visibility 0s;
+}
+
+/* The unmount timer firing while the slide is still running. */
+.drawerCut {
+ visibility: hidden;
+ transition: none;
+}
+
+.track {
+ position: relative;
+ height: 22px;
+ border-radius: var(--radius-sm, 5px);
+ background: var(--color-background-base);
+ border: 1px solid var(--color-border);
+ overflow: hidden;
+}
+
+.trackFill {
+ position: absolute;
+ inset-block: 0;
+ inset-inline-start: 0;
+ width: 0;
+}
+
+.trackSlide {
+ background: color-mix(in srgb, var(--color-brand) 45%, transparent);
+}
+
+.trackTimer {
+ background: color-mix(in srgb, var(--color-text-error, #d3543f) 45%, transparent);
+}
+
+/* --------------------------------------------------- sliding indicator --- */
+
+.indicator {
+ position: absolute;
+ inset-block-end: -1px;
+ height: 2px;
+ inset-inline-start: 0;
+ width: 0;
+ border-radius: 2px;
+ background: var(--color-brand);
+ transition:
+ transform var(--lab-duration-reveal) var(--ease-move),
+ width var(--lab-duration-reveal) var(--ease-move);
+}
+
+.indicatorTrack {
+ position: relative;
+}
+
+.segThumb {
+ position: absolute;
+ z-index: 0;
+ inset-block: 3px;
+ inset-inline-start: 0;
+ width: 0;
+ border-radius: var(--radius-md, 6px);
+ background: var(--color-background-elevated, var(--color-background-surface));
+ transition:
+ transform var(--lab-duration-reveal) var(--ease-move),
+ width var(--lab-duration-reveal) var(--ease-move);
+}
+
+/* ---------------------------------------------------------- disclosure --- */
+
+.gridBody {
+ display: grid;
+ grid-template-rows: 0fr;
+ transition: grid-template-rows var(--lab-duration-reveal) var(--ease-move);
+}
+
+.gridBody[data-open='true'] {
+ grid-template-rows: 1fr;
+}
+
+.gridBody > * {
+ overflow: hidden;
+}
+
+.heightBody {
+ height: 0;
+ overflow: hidden;
+ transition: height var(--lab-duration-reveal) var(--ease-move);
+}
+
+.offsetFade {
+ opacity: 0;
+ transform: translateY(calc(-6px * var(--lab-translate)));
+ transition:
+ opacity var(--lab-duration-state) var(--ease-entry),
+ transform var(--lab-duration-state) var(--ease-entry);
+}
+
+.offsetFade[data-open='true'] {
+ opacity: 1;
+ transform: none;
+ transition-delay: 80ms;
+}
+
+.chevron {
+ display: inline-flex;
+ transition: transform var(--lab-duration-state) var(--ease-state);
+}
+
+.chevronOpen {
+ transform: rotate(90deg);
+}
+
+/* ------------------------------------------------------------- sidenav --- */
+
+.rail {
+ overflow: hidden;
+ height: 100%;
+ width: 156px;
+ border-inline-end: 1px solid var(--color-border);
+ background: var(--color-background-surface);
+}
+
+.railAnimated {
+ transition: width var(--lab-duration-reveal) var(--ease-move);
+}
+
+.rail[data-collapsed='true'] {
+ width: 52px;
+}
+
+.railLabel {
+ white-space: nowrap;
+ transition: opacity var(--lab-duration-state) var(--ease-state);
+}
+
+.rail[data-collapsed='true'] .railLabel {
+ opacity: 0;
+}
+
+/* ------------------------------------------------------ skeleton swap ---- */
+
+.swap {
+ position: relative;
+ min-height: 66px;
+}
+
+.swapSkeleton {
+ position: absolute;
+ inset: 0;
+ transition: opacity var(--lab-duration-state) var(--ease-state);
+}
+
+.swapContent {
+ opacity: 0;
+ transition: opacity var(--lab-duration-state) var(--ease-state);
+}
+
+.swap[data-loaded='true'] .swapSkeleton {
+ opacity: 0;
+}
+
+.swap[data-loaded='true'] .swapContent {
+ opacity: 1;
+ transition-delay: var(--swap-overlap, 60ms);
+}
+
+.swapHard .swapSkeleton,
+.swapHard .swapContent {
+ transition: none !important;
+}
+
+/* ---------------------------------------------------------- enter/exit --- */
+
+.enter {
+ animation: enterIn var(--lab-duration-enter) var(--ease-entry) both;
+}
+
+.leave {
+ animation: leaveOut var(--lab-duration-exit) var(--ease-exit) both;
+}
+
+@keyframes enterIn {
+ from {
+ opacity: 0;
+ transform: translateY(calc(8px * var(--lab-translate)))
+ scale(calc(1 - 0.06 * var(--lab-scale)));
+ }
+}
+
+@keyframes leaveOut {
+ to {
+ opacity: 0;
+ transform: scale(calc(1 - 0.08 * var(--lab-scale)));
+ }
+}
+
+.staggerItem {
+ opacity: 0;
+ transform: translateY(calc(7px * var(--lab-translate)));
+}
+
+.staggerOn .staggerItem {
+ opacity: 1;
+ transform: none;
+ transition:
+ opacity var(--lab-duration-enter) var(--ease-entry),
+ transform var(--lab-duration-enter) var(--ease-entry);
+}
+
+.staggerHard .staggerItem {
+ transition: none !important;
+ opacity: 1;
+ transform: none;
+}
+
+/* --------------------------------------------------------- reflow slot --- */
+
+.reflowSlot {
+ display: grid;
+ grid-template-rows: 0fr;
+ transition: grid-template-rows var(--lab-duration-reveal) var(--ease-move);
+}
+
+.reflowSlot[data-open='true'] {
+ grid-template-rows: 1fr;
+}
+
+.reflowSlot > * {
+ overflow: hidden;
+}
+
+.reflowHard {
+ transition: none !important;
+}
+
+/* -------------------------------------------------------- compositor ----- */
+
+/* Outline's marker, both ways. The "before" animates `top` and `height`, which
+ runs layout for the whole list every frame; the "after" is a 1px marker
+ moved and stretched with `transform` alone. */
+.marker {
+ position: absolute;
+ inset-inline-start: 0;
+ width: 3px;
+ border-radius: 2px;
+ background: var(--color-brand);
+}
+
+.markerLayout {
+ transition:
+ top var(--lab-duration-reveal) var(--ease-move),
+ height var(--lab-duration-reveal) var(--ease-move);
+}
+
+.markerComposited {
+ inset-block-start: 0;
+ height: 1px;
+ transform-origin: top left;
+ transition: transform var(--lab-duration-reveal) var(--ease-move);
+}
+
+/* ---------------------------------------------------- interruptibility --- */
+
+.ball {
+ width: 30px;
+ height: 30px;
+ border-radius: var(--radius-md, 9px);
+ background: var(--color-brand);
+}
+
+.ballTransition {
+ transition: transform var(--lab-duration-overlay) var(--ease-move);
+}
+
+.ballKeyframe {
+ animation-duration: var(--lab-duration-overlay);
+ animation-timing-function: var(--ease-move);
+ animation-fill-mode: both;
+}
+
+.ballGo {
+ animation-name: ballGo;
+}
+
+.ballBack {
+ animation-name: ballBack;
+}
+
+@keyframes ballGo {
+ from {
+ transform: translateX(0);
+ }
+ to {
+ transform: translateX(var(--ball-distance, 160px));
+ }
+}
+
+@keyframes ballBack {
+ from {
+ transform: translateX(var(--ball-distance, 160px));
+ }
+ to {
+ transform: translateX(0);
+ }
+}
+
+/* ---------------------------------------------------------------- press --- */
+
+.pressTransform {
+ transition: transform var(--lab-duration-press) var(--ease-entry);
+}
+
+.pressTransform:active {
+ transform: scale(0.96);
+}
+
+/* The middle path: press feedback on the independent `scale` property, which
+ no longer collides with a motion library writing `transform` every frame. */
+.pressScale {
+ transition: scale var(--lab-duration-press) var(--ease-entry);
+}
+
+.pressScale:active {
+ scale: 0.96;
+}
+
+/* ---------------------------------------------------------------- loops --- */
+
+.spinner {
+ width: 20px;
+ height: 20px;
+ border-radius: 50%;
+ border: 2px solid var(--color-border);
+ border-block-start-color: var(--color-brand);
+ animation: spin var(--loop-duration, 975ms) var(--loop-ease, linear) infinite;
+}
+
+@keyframes spin {
+ to {
+ transform: rotate(360deg);
+ }
+}
+
+.pulseDot {
+ width: 11px;
+ height: 11px;
+ border-radius: 50%;
+ background: var(--color-background-success, #3f9a6b);
+ animation: pulseRing var(--loop-duration, 2s) var(--loop-ease, ease-in-out) infinite;
+}
+
+@keyframes pulseRing {
+ 0%,
+ 100% {
+ box-shadow: 0 0 0 0 color-mix(in srgb, var(--color-brand) 55%, transparent);
+ }
+ 50% {
+ box-shadow: 0 0 0 6px color-mix(in srgb, var(--color-brand) 0%, transparent);
+ }
+}
+
+.shimmer {
+ height: 11px;
+ border-radius: 6px;
+ background: linear-gradient(
+ 90deg,
+ var(--color-background-base) 0%,
+ var(--color-border) 40%,
+ var(--color-background-base) 80%
+ );
+ background-size: 220% 100%;
+ animation: shimmer var(--loop-duration, 1.5s) var(--loop-ease, ease-in-out) infinite;
+}
+
+@keyframes shimmer {
+ from {
+ background-position: 130% 0;
+ }
+ to {
+ background-position: -30% 0;
+ }
+}
+
+.progressTrack {
+ position: relative;
+ height: 6px;
+ border-radius: 4px;
+ background: var(--color-background-base);
+ overflow: hidden;
+}
+
+.progressFillWidth {
+ position: absolute;
+ inset-block: 0;
+ inset-inline-start: 0;
+ width: 34%;
+ border-radius: 4px;
+ background: var(--color-brand);
+ animation: progressWidth var(--loop-duration, 1.4s) linear infinite;
+}
+
+.progressFillTransform {
+ position: absolute;
+ inset-block: 0;
+ inset-inline-start: 0;
+ width: 34%;
+ border-radius: 4px;
+ background: var(--color-brand);
+ animation: progressTransform var(--loop-duration, 1.4s) linear infinite;
+ will-change: transform;
+}
+
+@keyframes progressWidth {
+ from {
+ inset-inline-start: -34%;
+ }
+ to {
+ inset-inline-start: 100%;
+ }
+}
+
+@keyframes progressTransform {
+ from {
+ transform: translateX(-100%);
+ }
+ to {
+ transform: translateX(294%);
+ }
+}
+
+/* ---------------------------------------------------------------- tint ---- */
+
+/* The Table hover tint, at whatever duration and curve is being argued over.
+ Rows 1-9 of the violation table are this, and the honest finding is that
+ 150ms and 175ms are near-indistinguishable at 1x. */
+.tintRow {
+ padding: var(--space-2, 6px) var(--space-3, 10px);
+ border-radius: var(--radius-sm, 6px);
+ transition: background-color var(--tint-duration, 150ms) var(--tint-ease, ease);
+}
+
+.tintRow:hover {
+ background: var(--color-background-hover, var(--color-background-elevated));
+}
+
+/* A `transitionProperty` with no duration: the rule reads like motion in
+ review and does nothing at all. */
+.noopRow {
+ padding: var(--space-2, 6px) var(--space-3, 10px);
+ border-radius: var(--radius-sm, 6px);
+ transition-property: background-color;
+}
+
+.noopRow:hover {
+ background: var(--color-background-hover, var(--color-background-elevated));
+}
+
+/* ------------------------------------------------------------- origin ----- */
+
+.originSurface {
+ position: absolute;
+ padding: var(--space-2, 8px) var(--space-3, 11px);
+ border-radius: var(--radius-md, 8px);
+ background: var(--color-background-elevated, var(--color-background-surface));
+ border: 1px solid var(--color-border);
+ opacity: 0;
+ transition:
+ opacity var(--lab-duration-enter) var(--ease-entry),
+ transform var(--lab-duration-enter) var(--ease-entry);
+}
+
+.originZero {
+ transform: scale(0);
+}
+
+.originCentre {
+ transform: scale(0.94);
+ transform-origin: center;
+}
+
+.originAnchored {
+ transform: scale(0.94);
+ transform-origin: top left;
+}
+
+.originSurface[data-open='true'] {
+ opacity: 1;
+ transform: scale(1);
+}
+
+/* ----------------------------------------------------------- lightbox ----- */
+
+.lightboxThumb {
+ width: 64px;
+ height: 48px;
+ border-radius: var(--radius-md, 6px);
+ border: 1px solid var(--color-border);
+ background: var(--color-brand);
+ cursor: pointer;
+}
+
+.lightboxSurface {
+ position: absolute;
+ z-index: 8;
+ border-radius: var(--radius-md, 8px);
+ background: var(--color-brand);
+ opacity: 0;
+ visibility: hidden;
+}
+
+.lightboxSurface[data-open='true'] {
+ opacity: 1;
+ visibility: visible;
+}
+
+.lightboxShared {
+ transition:
+ inset-inline-start var(--lab-duration-overlay) var(--ease-move),
+ inset-block-start var(--lab-duration-overlay) var(--ease-move),
+ width var(--lab-duration-overlay) var(--ease-move),
+ height var(--lab-duration-overlay) var(--ease-move),
+ opacity var(--lab-duration-exit) var(--ease-exit),
+ visibility 0s linear var(--lab-duration-overlay);
+}
+
+.lightboxShared[data-open='true'] {
+ transition:
+ inset-inline-start var(--lab-duration-overlay) var(--ease-entry),
+ inset-block-start var(--lab-duration-overlay) var(--ease-entry),
+ width var(--lab-duration-overlay) var(--ease-entry),
+ height var(--lab-duration-overlay) var(--ease-entry),
+ opacity var(--lab-duration-enter) var(--ease-entry),
+ visibility 0s;
+}
+
+.lightboxFade {
+ transition:
+ opacity var(--lab-duration-exit) var(--ease-exit),
+ visibility 0s linear var(--lab-duration-exit);
+}
+
+.lightboxFade[data-open='true'] {
+ transition: opacity var(--lab-duration-enter) var(--ease-entry), visibility 0s;
+}
+
+.lightboxNone {
+ transition: none;
+}
+
+/* --------------------------------------------------------------- check ---- */
+
+.checkTick {
+ stroke: var(--color-text-inverse, #fff);
+ stroke-width: 2.4;
+ fill: none;
+ stroke-linecap: round;
+ stroke-linejoin: round;
+ stroke-dasharray: 18;
+ stroke-dashoffset: 18;
+}
+
+.checkDraw[data-checked='true'] .checkTick {
+ stroke-dashoffset: 0;
+ transition: stroke-dashoffset var(--lab-duration-enter) var(--ease-entry) 40ms;
+}
+
+.checkScale .checkTick {
+ stroke-dashoffset: 0;
+ transform: scale(0);
+ transform-origin: center;
+}
+
+.checkScale[data-checked='true'] .checkTick {
+ transform: scale(1);
+ transition: transform var(--lab-duration-enter) var(--ease-entry);
+}
+
+.checkHard .checkTick {
+ stroke-dashoffset: 0;
+}
+
+/* -------------------------------------------------------------- misc ------ */
+
+.curveCanvas {
+ background: var(--color-background-base);
+ border: 1px solid var(--color-border);
+ border-radius: var(--radius-md, 8px);
+ touch-action: none;
+}
+
+.grabbable {
+ cursor: grab;
+}
+
+.fullBleedRow {
+ display: flex;
+ gap: var(--space-2, 8px);
+ align-items: center;
+ flex-wrap: wrap;
+}
diff --git a/apps/sandbox/src/motion/MotionLabShell.tsx b/apps/sandbox/src/motion/MotionLabShell.tsx
new file mode 100644
index 0000000000..e1b462d2c6
--- /dev/null
+++ b/apps/sandbox/src/motion/MotionLabShell.tsx
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file MotionLabShell.tsx
+ * @input Motion Lab store, control rail
+ * @output The scope element every lab page renders inside
+ * @position Motion Lab chrome; used by app/motion/layout.tsx
+ *
+ * The scope element is where the tuned custom properties land. Keeping them
+ * here rather than on `:root` means the lab can retune `--ease-standard` to
+ * argue about it without the docsite's own nav starting to move differently.
+ */
+
+import {VStack} from '@astryxdesign/core/Layout';
+import {useEffect, useRef, type ReactNode} from 'react';
+import {useMotionLab} from './MotionLabStore';
+import {MotionControlRail} from './MotionControlRail';
+import styles from './MotionLab.module.css';
+
+export function MotionLabShell({children}: {children: ReactNode}) {
+ const {registerScope, reducedMotion} = useMotionLab();
+ const ref = useRef<HTMLDivElement | null>(null);
+
+ useEffect(() => {
+ registerScope(ref.current);
+ return () => registerScope(null);
+ }, [registerScope]);
+
+ return (
+ <div ref={ref} className={styles.scope} data-reduced-motion={reducedMotion}>
+ <VStack gap={0}>
+ <MotionControlRail />
+ {children}
+ </VStack>
+ </div>
+ );
+}
diff --git a/apps/sandbox/src/motion/MotionLabStore.tsx b/apps/sandbox/src/motion/MotionLabStore.tsx
new file mode 100644
index 0000000000..c326532f14
--- /dev/null
+++ b/apps/sandbox/src/motion/MotionLabStore.tsx
@@ -0,0 +1,243 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file MotionLabStore.tsx
+ * @input Proposed token values from motionTokens
+ * @output Context owning the tuned token values and the lab's viewing modes
+ * @position Motion Lab root state; mounted by app/motion/layout.tsx
+ *
+ * Every control in the lab writes a real custom property on the lab's own
+ * scope element rather than holding a number in React state. That is the whole
+ * point of the tool: a value you tune on the tokens page is the same value
+ * every demo on every page is already reading, because they all read the
+ * token. Nothing has to be threaded through props to stay in sync.
+ *
+ * Scoped to a wrapper element, not :root, so the lab never restyles the
+ * docsite chrome around it.
+ */
+
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ type ReactNode,
+} from 'react';
+import {
+ ALL_TUNABLE_TOKENS,
+ CURRENT_EASE,
+ DEFAULT_TOKEN_VALUES,
+ SPRINGS,
+ type SpringSpec,
+} from './motionTokens';
+
+/** How the lab answers `prefers-reduced-motion`, so the choice is watchable. */
+export type ReducedMotionMode = 'off' | 'degrade' | 'delete';
+/** Which side of every before/after pane is on screen. */
+export type CompareMode = 'both' | 'before' | 'after';
+
+export type MotionLabState = {
+ readonly tokens: Readonly<Record<string, string>>;
+ readonly springs: Readonly<
+ Record<string, {duration: number; bounce: number}>
+ >;
+ readonly speed: number;
+ readonly reducedMotion: ReducedMotionMode;
+ readonly compare: CompareMode;
+ readonly isLooping: boolean;
+ readonly dirtyTokens: ReadonlyArray<string>;
+ setToken: (name: string, value: string) => void;
+ setSpring: (name: string, next: {duration: number; bounce: number}) => void;
+ setSpeed: (value: number) => void;
+ setReducedMotion: (mode: ReducedMotionMode) => void;
+ setCompare: (mode: CompareMode) => void;
+ setLooping: (value: boolean) => void;
+ reset: () => void;
+ /** Milliseconds for a token, already multiplied by the slow-mo factor. */
+ scaledMs: (token: string) => number;
+ /** Raw token value as authored, e.g. `cubic-bezier(...)` or `230ms`. */
+ rawToken: (token: string) => string;
+ registerScope: (el: HTMLElement | null) => void;
+ /** Bumped on every replay press, so demos can re-run without prop drilling. */
+ readonly replayNonce: number;
+ replay: () => void;
+};
+
+const MotionLabContext = createContext<MotionLabState | null>(null);
+
+export function useMotionLab(): MotionLabState {
+ const value = useContext(MotionLabContext);
+ if (value == null) {
+ throw new Error('useMotionLab must be used inside <MotionLabProvider>');
+ }
+ return value;
+}
+
+const DEFAULT_SPRINGS = Object.fromEntries(
+ SPRINGS.map((s: SpringSpec) => [
+ s.name,
+ {duration: s.duration, bounce: s.bounce},
+ ]),
+);
+
+export function parseMs(value: string): number {
+ const trimmed = value.trim();
+ if (trimmed.endsWith('ms')) {
+ return Number.parseFloat(trimmed);
+ }
+ if (trimmed.endsWith('s')) {
+ return Number.parseFloat(trimmed) * 1000;
+ }
+ const n = Number.parseFloat(trimmed);
+ return Number.isFinite(n) ? n : 0;
+}
+
+export function MotionLabProvider({children}: {children: ReactNode}) {
+ const [tokens, setTokens] = useState<Record<string, string>>({
+ ...DEFAULT_TOKEN_VALUES,
+ });
+ const [springs, setSprings] = useState(DEFAULT_SPRINGS);
+ const [speed, setSpeed] = useState(1);
+ const [reducedMotion, setReducedMotion] = useState<ReducedMotionMode>('off');
+ const [compare, setCompare] = useState<CompareMode>('both');
+ const [isLooping, setLooping] = useState(true);
+ const [replayNonce, setReplayNonce] = useState(0);
+ const scopeRef = useRef<HTMLElement | null>(null);
+
+ const registerScope = useCallback((el: HTMLElement | null) => {
+ scopeRef.current = el;
+ }, []);
+
+ // The scope element carries the tuned values. Writing them in an effect
+ // rather than as an inline style keeps the paint out of React's render and
+ // means a demo that reads getComputedStyle sees the same value the
+ // stylesheet does.
+ //
+ // The reduced-motion policy is applied HERE rather than in the stylesheet.
+ // An inline custom property beats any selector in the module, so a
+ // `.scope[data-reduced-motion='delete']` rule that redeclares
+ // `--lab-duration-*` silently loses to these writes — which made Delete look
+ // like it worked (movement stopped, because the multipliers are not written
+ // inline) while every duration stayed at its tuned value.
+ useEffect(() => {
+ const el = scopeRef.current;
+ if (el == null) {
+ return;
+ }
+ const collapse = reducedMotion === 'delete';
+ for (const [name, value] of Object.entries(tokens)) {
+ el.style.setProperty(name, value);
+ // The scaled alias every demo actually reads, so slow-mo stretches
+ // motion without moving the token the export writes out.
+ if (name.startsWith('--duration-') || name.startsWith('--stagger-')) {
+ el.style.setProperty(
+ name.replace(/^--(duration|stagger)-/, '--lab-$1-'),
+ collapse ? '0ms' : `${parseMs(value) * speed}ms`,
+ );
+ }
+ }
+ // Degrade keeps opacity and colour and drops movement; delete drops both.
+ const moves = reducedMotion === 'off';
+ el.style.setProperty('--lab-translate', moves ? '1' : '0');
+ el.style.setProperty('--lab-scale', moves ? '1' : '0');
+ el.style.setProperty('--lab-speed', String(speed));
+ // The curve core ships today, published as its own name so a "before" pane
+ // can run the real thing rather than a copy that drifts when the proposal's
+ // --ease-standard alias is retuned.
+ el.style.setProperty('--ease-standard-today', CURRENT_EASE.value);
+ }, [tokens, speed, reducedMotion]);
+
+ const setToken = useCallback((name: string, value: string) => {
+ setTokens(prev => (prev[name] === value ? prev : {...prev, [name]: value}));
+ }, []);
+
+ const setSpring = useCallback(
+ (name: string, next: {duration: number; bounce: number}) => {
+ setSprings(prev => ({...prev, [name]: next}));
+ },
+ [],
+ );
+
+ const reset = useCallback(() => {
+ setTokens({...DEFAULT_TOKEN_VALUES});
+ setSprings(DEFAULT_SPRINGS);
+ setSpeed(1);
+ setReducedMotion('off');
+ setCompare('both');
+ }, []);
+
+ const replay = useCallback(() => setReplayNonce(n => n + 1), []);
+
+ const dirtyTokens = useMemo(
+ () =>
+ ALL_TUNABLE_TOKENS.filter(
+ name => tokens[name] !== DEFAULT_TOKEN_VALUES[name],
+ ),
+ [tokens],
+ );
+
+ const rawToken = useCallback(
+ (token: string) =>
+ token === '--ease-standard-today'
+ ? CURRENT_EASE.value
+ : (tokens[token] ?? DEFAULT_TOKEN_VALUES[token] ?? ''),
+ [tokens],
+ );
+
+ const scaledMs = useCallback(
+ (token: string) => parseMs(rawToken(token)) * speed,
+ [rawToken, speed],
+ );
+
+ const value = useMemo<MotionLabState>(
+ () => ({
+ tokens,
+ springs,
+ speed,
+ reducedMotion,
+ compare,
+ isLooping,
+ dirtyTokens,
+ setToken,
+ setSpring,
+ setSpeed,
+ setReducedMotion,
+ setCompare,
+ setLooping,
+ reset,
+ scaledMs,
+ rawToken,
+ registerScope,
+ replayNonce,
+ replay,
+ }),
+ [
+ tokens,
+ springs,
+ speed,
+ reducedMotion,
+ compare,
+ isLooping,
+ dirtyTokens,
+ setToken,
+ setSpring,
+ reset,
+ scaledMs,
+ rawToken,
+ registerScope,
+ replayNonce,
+ replay,
+ ],
+ );
+
+ return (
+ <MotionLabContext.Provider value={value}>
+ {children}
+ </MotionLabContext.Provider>
+ );
+}
diff --git a/apps/sandbox/src/motion/PageFrame.tsx b/apps/sandbox/src/motion/PageFrame.tsx
new file mode 100644
index 0000000000..f10c2af6f6
--- /dev/null
+++ b/apps/sandbox/src/motion/PageFrame.tsx
@@ -0,0 +1,55 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file PageFrame.tsx
+ * @input Section metadata
+ * @output The heading block every lab page opens with
+ * @position Motion Lab shared UI
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Section} from '@astryxdesign/core/Section';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+
+const sx = stylex.create({
+ intro: {maxWidth: '78ch'},
+});
+
+export function LabPage({
+ title,
+ intro,
+ decides,
+ badges,
+ children,
+}: {
+ title: string;
+ intro: string;
+ decides?: string;
+ badges?: ReactNode;
+ children: ReactNode;
+}) {
+ return (
+ <Section padding={6} width="100%">
+ <VStack gap={5}>
+ <VStack gap={2} {...stylex.props(sx.intro)}>
+ <HStack gap={2} vAlign="center" wrap="wrap">
+ <Heading level={1}>{title}</Heading>
+ {badges}
+ </HStack>
+ <Text color="secondary">{intro}</Text>
+ {decides != null && (
+ <Text type="supporting" color="secondary">
+ <strong>Decide here: </strong>
+ {decides}
+ </Text>
+ )}
+ </VStack>
+ {children}
+ </VStack>
+ </Section>
+ );
+}
diff --git a/apps/sandbox/src/motion/__generated__/motionAudit.ts b/apps/sandbox/src/motion/__generated__/motionAudit.ts
new file mode 100644
index 0000000000..70cf49cbf1
--- /dev/null
+++ b/apps/sandbox/src/motion/__generated__/motionAudit.ts
@@ -0,0 +1,1368 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+// @generated by scripts/generate-motion-audit.mjs — do not edit by hand.
+// Measured against packages/core + packages/lab at [email protected].
+// Regenerate: pnpm -F @astryxdesign/sandbox generate:motion-audit
+//
+// The Motion Lab shows these numbers instead of the ones written in the project
+// brief, because a brief drifts from the code and a generated file cannot.
+// Where the two disagree, the lab says so and cites file:line.
+
+export type HardcodedSite = {
+ readonly file: string;
+ readonly package: 'core' | 'lab';
+ readonly component: string;
+ readonly line: number;
+ readonly kind: 'duration' | 'easing';
+ readonly prop: string;
+ readonly value: string;
+ readonly ms: number | null;
+};
+
+export type SiteRef = {
+ readonly file: string;
+ readonly package: 'core' | 'lab';
+ readonly component: string;
+ readonly line: number;
+ readonly decl?: string;
+};
+
+export const CORE_VERSION = '0.5.0';
+
+export const AUDIT_COUNTS = {
+ componentDirs: 121,
+ coreComponentDirs: 104,
+ labComponentDirs: 17,
+ hardcodedInLab: 10,
+ filesScanned: 698,
+ animatingComponents: 55,
+ staticComponents: 65,
+ animatedFiles: 88,
+ filesWithReducedMotion: 48,
+ filesWithoutReducedMotion: 40,
+ hardcodedTotal: 58,
+ hardcodedDuration: 34,
+ hardcodedEasing: 24,
+ noopTransitions: 1,
+ durationWithoutCurve: 12,
+ transformTransitions: 34,
+ transformTransitionComponents: 23,
+ transitionAll: 0,
+ infiniteLoops: 9,
+ setTimeoutLiterals: 1,
+ getComputedStyleReads: 33,
+} as const;
+
+export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
+ {
+ file: 'core/hooks/containerReveal.stylex.ts',
+ package: 'core',
+ component: '(shared)',
+ line: 253,
+ kind: 'duration',
+ prop: 'transitionDelay',
+ value: '0s',
+ ms: 0,
+ },
+ {
+ file: 'core/hooks/containerReveal.stylex.ts',
+ package: 'core',
+ component: '(shared)',
+ line: 261,
+ kind: 'duration',
+ prop: 'transitionDelay',
+ value: '0s',
+ ms: 0,
+ },
+ {
+ file: 'core/hooks/containerReveal.stylex.ts',
+ package: 'core',
+ component: '(shared)',
+ line: 267,
+ kind: 'duration',
+ prop: 'transitionDelay',
+ value: '0s',
+ ms: 0,
+ },
+ {
+ file: 'core/hooks/useKeyboardHint.tsx',
+ package: 'core',
+ component: '(shared)',
+ line: 135,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/BottomSheet/BottomSheet.tsx',
+ package: 'core',
+ component: 'BottomSheet',
+ line: 94,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/BottomSheet/BottomSheet.tsx',
+ package: 'core',
+ component: 'BottomSheet',
+ line: 109,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/BottomSheet/BottomSheetPanel.tsx',
+ package: 'core',
+ component: 'BottomSheet',
+ line: 149,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/BottomSheet/BottomSheetPanel.tsx',
+ package: 'core',
+ component: 'BottomSheet',
+ line: 172,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'cubic-bezier(0.3, 0, 0.6, 0.6)',
+ ms: null,
+ },
+ {
+ file: 'core/BottomSheet/BottomSheetSwitcher.tsx',
+ package: 'core',
+ component: 'BottomSheet',
+ line: 105,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/BottomSheet/BottomSheetSwitcher.tsx',
+ package: 'core',
+ component: 'BottomSheet',
+ line: 114,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/Button/Button.tsx',
+ package: 'core',
+ component: 'Button',
+ line: 407,
+ kind: 'duration',
+ prop: 'animationDuration',
+ value: '1ms',
+ ms: 1,
+ },
+ {
+ file: 'core/Chat/ChatComposerDrawer.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 208,
+ kind: 'duration',
+ prop: 'transitionDelay',
+ value: '0ms',
+ ms: 0,
+ },
+ {
+ file: 'core/Chat/ChatDictationButton.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 75,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'ease-out',
+ ms: null,
+ },
+ {
+ file: 'core/Chat/ChatMessageMetadata.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 77,
+ kind: 'duration',
+ prop: 'animationDuration',
+ value: '1.5s',
+ ms: 1500,
+ },
+ {
+ file: 'core/Chat/ChatMessageMetadata.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 78,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'ease-in-out',
+ ms: null,
+ },
+ {
+ file: 'lab/Chat/ChatTypingIndicator.tsx',
+ package: 'lab',
+ component: 'Chat',
+ line: 79,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'ease-in-out',
+ ms: null,
+ },
+ {
+ file: 'lab/Chat/ChatTypingIndicator.tsx',
+ package: 'lab',
+ component: 'Chat',
+ line: 85,
+ kind: 'duration',
+ prop: 'animationDelay',
+ value: '160ms',
+ ms: 160,
+ },
+ {
+ file: 'lab/Chat/ChatTypingIndicator.tsx',
+ package: 'lab',
+ component: 'Chat',
+ line: 88,
+ kind: 'duration',
+ prop: 'animationDelay',
+ value: '320ms',
+ ms: 320,
+ },
+ {
+ file: 'lab/ChatReasoning/ChatReasoning.tsx',
+ package: 'lab',
+ component: 'ChatReasoning',
+ line: 152,
+ kind: 'duration',
+ prop: 'animationDuration',
+ value: '4s',
+ ms: 4000,
+ },
+ {
+ file: 'lab/ChatReasoning/ChatReasoning.tsx',
+ package: 'lab',
+ component: 'ChatReasoning',
+ line: 153,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'lab/CircularProgress/CircularProgress.tsx',
+ package: 'lab',
+ component: 'CircularProgress',
+ line: 188,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'lab/CircularProgress/CircularProgress.tsx',
+ package: 'lab',
+ component: 'CircularProgress',
+ line: 210,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'ease-in-out',
+ ms: null,
+ },
+ {
+ file: 'core/CommandPalette/CommandPaletteInput.tsx',
+ package: 'core',
+ component: 'CommandPalette',
+ line: 62,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '1ms',
+ ms: 1,
+ },
+ {
+ file: 'core/CommandPalette/CommandPaletteInput.tsx',
+ package: 'core',
+ component: 'CommandPalette',
+ line: 63,
+ kind: 'duration',
+ prop: 'transitionDelay',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 253,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 255,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 310,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 312,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 382,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 397,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 399,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 449,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 499,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 501,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/DateInput/Wheel.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 171,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'lab/Drawer/Drawer.tsx',
+ package: 'lab',
+ component: 'Drawer',
+ line: 161,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'lab/Drawer/Drawer.tsx',
+ package: 'lab',
+ component: 'Drawer',
+ line: 224,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/Lightbox/Lightbox.tsx',
+ package: 'core',
+ component: 'Lightbox',
+ line: 190,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'ease-out',
+ ms: null,
+ },
+ {
+ file: 'lab/LogStream/LogStream.tsx',
+ package: 'lab',
+ component: 'LogStream',
+ line: 173,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'ease-out',
+ ms: null,
+ },
+ {
+ file: 'core/MobileNav/MobileNav.tsx',
+ package: 'core',
+ component: 'MobileNav',
+ line: 132,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/MobileNav/MobileNav.tsx',
+ package: 'core',
+ component: 'MobileNav',
+ line: 162,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '0.01s',
+ ms: 10,
+ },
+ {
+ file: 'core/ProgressBar/ProgressBar.tsx',
+ package: 'core',
+ component: 'ProgressBar',
+ line: 260,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'ease-in-out',
+ ms: null,
+ },
+ {
+ file: 'core/Spinner/Spinner.tsx',
+ package: 'core',
+ component: 'Spinner',
+ line: 138,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/StatusDot/StatusDot.tsx',
+ package: 'core',
+ component: 'StatusDot',
+ line: 56,
+ kind: 'duration',
+ prop: 'animationDuration',
+ value: '2s',
+ ms: 2000,
+ },
+ {
+ file: 'core/StatusDot/StatusDot.tsx',
+ package: 'core',
+ component: 'StatusDot',
+ line: 57,
+ kind: 'easing',
+ prop: 'animationTimingFunction',
+ value: 'ease-in-out',
+ ms: null,
+ },
+ {
+ file: 'core/Stepper/Step.tsx',
+ package: 'core',
+ component: 'Stepper',
+ line: 387,
+ kind: 'easing',
+ prop: 'transitionTimingFunction',
+ value: 'linear',
+ ms: null,
+ },
+ {
+ file: 'core/Table/plugins/columnResize/useTableColumnResize.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 248,
+ kind: 'duration',
+ prop: 'transition',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/Table/plugins/columnResize/useTableColumnResize.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 248,
+ kind: 'duration',
+ prop: 'transition',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/Table/plugins/columnResize/useTableColumnResize.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 248,
+ kind: 'easing',
+ prop: 'transition',
+ value: 'ease',
+ ms: null,
+ },
+ {
+ file: 'core/Table/plugins/columnResize/useTableColumnResize.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 248,
+ kind: 'easing',
+ prop: 'transition',
+ value: 'ease',
+ ms: null,
+ },
+ {
+ file: 'core/Table/plugins/groupedRows/useTableGroupedRows.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 163,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/Table/plugins/rowExpansion/useTableRowExpansion.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 87,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/Table/plugins/stickyColumns/useTableStickyColumns.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 234,
+ kind: 'duration',
+ prop: 'transition',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/Table/plugins/stickyColumns/useTableStickyColumns.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 234,
+ kind: 'easing',
+ prop: 'transition',
+ value: 'ease',
+ ms: null,
+ },
+ {
+ file: 'core/Table/plugins/stickyColumns/useTableStickyColumns.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 260,
+ kind: 'duration',
+ prop: 'transition',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/Table/plugins/stickyColumns/useTableStickyColumns.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 260,
+ kind: 'easing',
+ prop: 'transition',
+ value: 'ease',
+ ms: null,
+ },
+ {
+ file: 'core/Table/plugins/tree/useTableTreeData.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 251,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '150ms',
+ ms: 150,
+ },
+ {
+ file: 'core/Table/plugins/tree/useTableTreeData.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 267,
+ kind: 'duration',
+ prop: 'transitionDuration',
+ value: '150ms',
+ ms: 150,
+ },
+];
+
+export const NOOP_TRANSITIONS: ReadonlyArray<SiteRef> = [
+ {
+ file: 'core/Lightbox/Lightbox.tsx',
+ package: 'core',
+ component: 'Lightbox',
+ line: 192,
+ decl: "transitionProperty: 'none'",
+ },
+];
+
+export const DURATION_WITHOUT_CURVE: ReadonlyArray<SiteRef> = [
+ {
+ file: 'core/Chat/ChatComposerDrawer.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 206,
+ decl: "transitionDuration: durationVars['--duration-fast']",
+ },
+ {
+ file: 'core/CommandPalette/CommandPaletteInput.tsx',
+ package: 'core',
+ component: 'CommandPalette',
+ line: 59,
+ decl: "transitionDuration: '1ms'",
+ },
+ {
+ file: 'core/DateInput/MonthScroller.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 165,
+ decl: "transitionDuration: durationVars['--duration-fast']",
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 445,
+ decl: 'transitionDuration: SWAP_DURATION',
+ },
+ {
+ file: 'core/DateInput/Wheel.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 110,
+ decl: "transitionDuration: durationVars['--duration-fast']",
+ },
+ {
+ file: 'core/MobileNav/MobileNav.tsx',
+ package: 'core',
+ component: 'MobileNav',
+ line: 74,
+ decl: "transitionDuration: durationVars['--duration-medium']",
+ },
+ {
+ file: 'core/MobileNav/MobileNav.tsx',
+ package: 'core',
+ component: 'MobileNav',
+ line: 130,
+ decl: "transitionDuration: '0.01s'",
+ },
+ {
+ file: 'core/Stepper/Step.tsx',
+ package: 'core',
+ component: 'Stepper',
+ line: 404,
+ decl: 'transitionDuration:',
+ },
+ {
+ file: 'core/Table/plugins/groupedRows/useTableGroupedRows.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 161,
+ decl: "transitionDuration: '150ms'",
+ },
+ {
+ file: 'core/Table/plugins/tree/useTableTreeData.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 265,
+ decl: "transitionDuration: '150ms'",
+ },
+ {
+ file: 'core/hooks/useKeyboardHint.tsx',
+ package: 'core',
+ component: '(shared)',
+ line: 107,
+ decl: "transitionDuration: '150ms'",
+ },
+ {
+ file: 'lab/Drawer/Drawer.tsx',
+ package: 'lab',
+ component: 'Drawer',
+ line: 222,
+ decl: "transitionDuration: '0.01s'",
+ },
+];
+
+export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
+ {
+ file: 'core/Banner/Banner.tsx',
+ package: 'core',
+ component: 'Banner',
+ line: 331,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/BottomSheet/BottomSheetPanel.tsx',
+ package: 'core',
+ component: 'BottomSheet',
+ line: 144,
+ decl: "transitionProperty: 'transform, opacity'",
+ },
+ {
+ file: 'core/Button/Button.tsx',
+ package: 'core',
+ component: 'Button',
+ line: 90,
+ decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
+ },
+ {
+ file: 'core/Chat/ChatDictationButton.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 70,
+ decl: "transitionProperty: 'transform, background-color'",
+ },
+ {
+ file: 'core/Chat/ChatLayoutScrollButton.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 71,
+ decl: "transitionProperty: 'opacity, transform, max-width'",
+ },
+ {
+ file: 'core/CodeBlock/CodeBlock.tsx',
+ package: 'core',
+ component: 'CodeBlock',
+ line: 207,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Collapsible/Collapsible.tsx',
+ package: 'core',
+ component: 'Collapsible',
+ line: 107,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/ComplexSelector/ComplexSelector.tsx',
+ package: 'core',
+ component: 'ComplexSelector',
+ line: 134,
+ decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
+ },
+ {
+ file: 'core/ComplexSelector/ComplexSelector.tsx',
+ package: 'core',
+ component: 'ComplexSelector',
+ line: 160,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/DateInput/TouchDateField.tsx',
+ package: 'core',
+ component: 'DateInput',
+ line: 378,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Lightbox/Lightbox.tsx',
+ package: 'core',
+ component: 'Lightbox',
+ line: 185,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/MobileNav/MobileNav.tsx',
+ package: 'core',
+ component: 'MobileNav',
+ line: 157,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/MultiSelector/MultiSelector.tsx',
+ package: 'core',
+ component: 'MultiSelector',
+ line: 185,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/MultiSelector/MultiSelector.tsx',
+ package: 'core',
+ component: 'MultiSelector',
+ line: 213,
+ decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
+ },
+ {
+ file: 'core/Overlay/OverlayScrim.tsx',
+ package: 'core',
+ component: 'Overlay',
+ line: 58,
+ decl: "transitionProperty: 'opacity, visibility, transform'",
+ },
+ {
+ file: 'core/Resizable/ResizeHandle.tsx',
+ package: 'core',
+ component: 'Resizable',
+ line: 194,
+ decl: "transitionProperty: 'opacity, background-color, transform'",
+ },
+ {
+ file: 'core/Selector/Selector.tsx',
+ package: 'core',
+ component: 'Selector',
+ line: 208,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Selector/Selector.tsx',
+ package: 'core',
+ component: 'Selector',
+ line: 236,
+ decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
+ },
+ {
+ file: 'core/SideNav/SideNavCollapseButton.tsx',
+ package: 'core',
+ component: 'SideNav',
+ line: 53,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/SideNav/SideNavItem.tsx',
+ package: 'core',
+ component: 'SideNav',
+ line: 126,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Stepper/Step.tsx',
+ package: 'core',
+ component: 'Stepper',
+ line: 366,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Switch/Switch.tsx',
+ package: 'core',
+ component: 'Switch',
+ line: 288,
+ decl: "transitionProperty: 'transform, width, height'",
+ },
+ {
+ file: 'core/TabList/TabMenu.tsx',
+ package: 'core',
+ component: 'TabList',
+ line: 165,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Table/plugins/groupedRows/useTableGroupedRows.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 162,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Table/plugins/rowExpansion/useTableRowExpansion.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 86,
+ decl: "transitionProperty: 'transform, color'",
+ },
+ {
+ file: 'core/Table/plugins/tree/useTableTreeData.tsx',
+ package: 'core',
+ component: 'Table',
+ line: 266,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/Toast/Toast.tsx',
+ package: 'core',
+ component: 'Toast',
+ line: 40,
+ decl: "transitionProperty: 'opacity, transform'",
+ },
+ {
+ file: 'core/TopNav/TopNavMegaMenu.tsx',
+ package: 'core',
+ component: 'TopNav',
+ line: 113,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/TopNav/TopNavMegaMenu.tsx',
+ package: 'core',
+ component: 'TopNav',
+ line: 130,
+ decl: "transitionProperty: 'opacity, transform, overlay, display'",
+ },
+ {
+ file: 'core/TopNav/TopNavMegaMenu.tsx',
+ package: 'core',
+ component: 'TopNav',
+ line: 221,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/TopNav/TopNavMenu.tsx',
+ package: 'core',
+ component: 'TopNav',
+ line: 100,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/TopNav/TopNavMenu.tsx',
+ package: 'core',
+ component: 'TopNav',
+ line: 184,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'core/TreeList/TreeListItem.tsx',
+ package: 'core',
+ component: 'TreeList',
+ line: 225,
+ decl: "transitionProperty: 'transform'",
+ },
+ {
+ file: 'lab/Drawer/Drawer.tsx',
+ package: 'lab',
+ component: 'Drawer',
+ line: 156,
+ decl: "transitionProperty: 'transform, display'",
+ },
+];
+
+export const TRANSITION_ALL: ReadonlyArray<SiteRef> = [];
+
+export const INFINITE_LOOPS: ReadonlyArray<SiteRef> = [
+ {
+ file: 'core/Chat/ChatMessageMetadata.tsx',
+ package: 'core',
+ component: 'Chat',
+ line: 79,
+ },
+ {
+ file: 'core/ProgressBar/ProgressBar.tsx',
+ package: 'core',
+ component: 'ProgressBar',
+ line: 261,
+ },
+ {
+ file: 'core/Skeleton/Skeleton.tsx',
+ package: 'core',
+ component: 'Skeleton',
+ line: 74,
+ },
+ {
+ file: 'core/Spinner/Spinner.tsx',
+ package: 'core',
+ component: 'Spinner',
+ line: 136,
+ },
+ {
+ file: 'core/StatusDot/StatusDot.tsx',
+ package: 'core',
+ component: 'StatusDot',
+ line: 58,
+ },
+ {
+ file: 'lab/Chat/ChatTypingIndicator.tsx',
+ package: 'lab',
+ component: 'Chat',
+ line: 78,
+ },
+ {
+ file: 'lab/ChatReasoning/ChatReasoning.tsx',
+ package: 'lab',
+ component: 'ChatReasoning',
+ line: 154,
+ },
+ {
+ file: 'lab/CircularProgress/CircularProgress.tsx',
+ package: 'lab',
+ component: 'CircularProgress',
+ line: 189,
+ },
+ {
+ file: 'lab/CircularProgress/CircularProgress.tsx',
+ package: 'lab',
+ component: 'CircularProgress',
+ line: 211,
+ },
+];
+
+export const TIMEOUT_LITERALS: ReadonlyArray<{
+ readonly file: string;
+ readonly package: 'core' | 'lab';
+ readonly component: string;
+ readonly line: number;
+ readonly ms: number;
+}> = [
+ {
+ file: 'core/MultiSelector/hooks.ts',
+ package: 'core',
+ component: 'MultiSelector',
+ line: 233,
+ ms: 500,
+ },
+];
+
+export const NO_REDUCED_MOTION: ReadonlyArray<{
+ readonly file: string;
+ readonly package: 'core' | 'lab';
+ readonly component: string;
+}> = [
+ {file: 'core/Chat/ChatComposer.tsx', package: 'core', component: 'Chat'},
+ {
+ file: 'core/Chat/ChatComposerDrawer.tsx',
+ package: 'core',
+ component: 'Chat',
+ },
+ {file: 'core/Citation/Citation.tsx', package: 'core', component: 'Citation'},
+ {
+ file: 'core/ClickableCard/ClickableCard.tsx',
+ package: 'core',
+ component: 'ClickableCard',
+ },
+ {
+ file: 'core/Collapsible/Collapsible.tsx',
+ package: 'core',
+ component: 'Collapsible',
+ },
+ {
+ file: 'core/CommandPalette/CommandPaletteInput.tsx',
+ package: 'core',
+ component: 'CommandPalette',
+ },
+ {
+ file: 'core/ComplexSelector/ComplexSelector.tsx',
+ package: 'core',
+ component: 'ComplexSelector',
+ },
+ {
+ file: 'core/ContextMenu/ContextMenu.tsx',
+ package: 'core',
+ component: 'ContextMenu',
+ },
+ {
+ file: 'core/DateInput/MonthScroller.tsx',
+ package: 'core',
+ component: 'DateInput',
+ },
+ {
+ file: 'core/DropdownMenu/DropdownMenu.tsx',
+ package: 'core',
+ component: 'DropdownMenu',
+ },
+ {
+ file: 'core/DropdownMenu/DropdownMenuSubMenu.tsx',
+ package: 'core',
+ component: 'DropdownMenu',
+ },
+ {file: 'core/Item/Item.tsx', package: 'core', component: 'Item'},
+ {file: 'core/Link/Link.tsx', package: 'core', component: 'Link'},
+ {
+ file: 'core/MultiSelector/MultiSelector.tsx',
+ package: 'core',
+ component: 'MultiSelector',
+ },
+ {file: 'core/Outline/Outline.tsx', package: 'core', component: 'Outline'},
+ {
+ file: 'core/Pagination/Pagination.tsx',
+ package: 'core',
+ component: 'Pagination',
+ },
+ {
+ file: 'core/Resizable/ResizeHandle.tsx',
+ package: 'core',
+ component: 'Resizable',
+ },
+ {
+ file: 'core/SegmentedControl/SegmentedControlItem.tsx',
+ package: 'core',
+ component: 'SegmentedControl',
+ },
+ {
+ file: 'core/SelectableCard/SelectableCard.tsx',
+ package: 'core',
+ component: 'SelectableCard',
+ },
+ {file: 'core/Selector/Selector.tsx', package: 'core', component: 'Selector'},
+ {file: 'core/TabList/Tab.tsx', package: 'core', component: 'TabList'},
+ {file: 'core/TabList/TabMenu.tsx', package: 'core', component: 'TabList'},
+ {file: 'core/Table/TableRow.tsx', package: 'core', component: 'Table'},
+ {
+ file: 'core/Table/plugins/columnResize/useTableColumnResize.tsx',
+ package: 'core',
+ component: 'Table',
+ },
+ {
+ file: 'core/Table/plugins/groupedRows/useTableGroupedRows.tsx',
+ package: 'core',
+ component: 'Table',
+ },
+ {
+ file: 'core/Table/plugins/rowExpansion/useTableRowExpansion.tsx',
+ package: 'core',
+ component: 'Table',
+ },
+ {
+ file: 'core/Table/plugins/stickyColumns/useTableStickyColumns.tsx',
+ package: 'core',
+ component: 'Table',
+ },
+ {
+ file: 'core/Table/plugins/tree/useTableTreeData.tsx',
+ package: 'core',
+ component: 'Table',
+ },
+ {
+ file: 'core/Thumbnail/Thumbnail.tsx',
+ package: 'core',
+ component: 'Thumbnail',
+ },
+ {file: 'core/Token/Token.tsx', package: 'core', component: 'Token'},
+ {file: 'core/TopNav/TopNavItem.tsx', package: 'core', component: 'TopNav'},
+ {
+ file: 'core/TopNav/TopNavMegaMenu.tsx',
+ package: 'core',
+ component: 'TopNav',
+ },
+ {
+ file: 'core/TopNav/TopNavMegaMenuItem.tsx',
+ package: 'core',
+ component: 'TopNav',
+ },
+ {file: 'core/TopNav/TopNavMenu.tsx', package: 'core', component: 'TopNav'},
+ {
+ file: 'core/TreeList/TreeListItem.tsx',
+ package: 'core',
+ component: 'TreeList',
+ },
+ {
+ file: 'core/hooks/useKeyboardHint.tsx',
+ package: 'core',
+ component: '(shared)',
+ },
+ {file: 'lab/Chart/ChartAxis.tsx', package: 'lab', component: 'Chart'},
+ {
+ file: 'lab/ChatReasoning/ChatReasoning.tsx',
+ package: 'lab',
+ component: 'ChatReasoning',
+ },
+ {file: 'lab/InfoTip/InfoTip.tsx', package: 'lab', component: 'InfoTip'},
+ {file: 'lab/Tour/TourStep.tsx', package: 'lab', component: 'Tour'},
+];
+
+export const INSTANT_SPELLINGS: ReadonlyArray<readonly [string, number]> = [
+ ['0s', 3],
+ ['1ms', 2],
+ ['0ms', 1],
+];
+
+export const LITERAL_VALUES: ReadonlyArray<readonly [string, number]> = [
+ ['0.01s', 13],
+ ['linear', 11],
+ ['150ms', 10],
+ ['ease-in-out', 5],
+ ['ease', 4],
+ ['ease-out', 3],
+ ['0s', 3],
+ ['1ms', 2],
+ ['cubic-bezier(0.3, 0, 0.6, 0.6)', 1],
+ ['0ms', 1],
+ ['1.5s', 1],
+ ['2s', 1],
+ ['160ms', 1],
+ ['320ms', 1],
+ ['4s', 1],
+];
+
+export const HARDCODED_BY_COMPONENT: ReadonlyArray<readonly [string, number]> =
+ [
+ ['Table', 12],
+ ['DateInput', 11],
+ ['Chat', 7],
+ ['BottomSheet', 6],
+ ['(shared)', 4],
+ ['CommandPalette', 2],
+ ['MobileNav', 2],
+ ['StatusDot', 2],
+ ['ChatReasoning', 2],
+ ['CircularProgress', 2],
+ ['Drawer', 2],
+ ['Button', 1],
+ ['Lightbox', 1],
+ ['ProgressBar', 1],
+ ['Spinner', 1],
+ ['Stepper', 1],
+ ['LogStream', 1],
+ ];
+
+export const ANIMATING_COMPONENTS: ReadonlyArray<string> = [
+ 'Banner',
+ 'BottomSheet',
+ 'Button',
+ 'Calendar',
+ 'Carousel',
+ 'Chart',
+ 'Chat',
+ 'ChatReasoning',
+ 'CircularProgress',
+ 'Citation',
+ 'ClickableCard',
+ 'CodeBlock',
+ 'Collapsible',
+ 'CommandPalette',
+ 'ComplexSelector',
+ 'ContextMenu',
+ 'DateInput',
+ 'Dialog',
+ 'Drawer',
+ 'DropdownMenu',
+ 'Field',
+ 'FileInput',
+ 'Indicator',
+ 'InfoTip',
+ 'Item',
+ 'Layer',
+ 'Lightbox',
+ 'Link',
+ 'LogStream',
+ 'Markdown',
+ 'MobileNav',
+ 'MultiSelector',
+ 'Outline',
+ 'Overlay',
+ 'Pagination',
+ 'ProgressBar',
+ 'Resizable',
+ 'SegmentedControl',
+ 'SelectableCard',
+ 'Selector',
+ 'SideNav',
+ 'Skeleton',
+ 'Slider',
+ 'Spinner',
+ 'StatusDot',
+ 'Stepper',
+ 'Switch',
+ 'TabList',
+ 'Table',
+ 'Thumbnail',
+ 'Toast',
+ 'Token',
+ 'TopNav',
+ 'Tour',
+ 'TreeList',
+];
+
+export const STATIC_COMPONENTS: ReadonlyArray<string> = [
+ 'AlertDialog',
+ 'AppShell',
+ 'AspectRatio',
+ 'Avatar',
+ 'AvatarGroup',
+ 'Badge',
+ 'Blockquote',
+ 'Breadcrumbs',
+ 'ButtonGroup',
+ 'Card',
+ 'Center',
+ 'CheckboxInput',
+ 'CheckboxList',
+ 'Code',
+ 'CodeEditor',
+ 'DateRangeInput',
+ 'DateTimeInput',
+ 'Divider',
+ 'EmptyState',
+ 'FieldStatus',
+ 'FormLayout',
+ 'Grid',
+ 'Heading',
+ 'HoverCard',
+ 'HStack',
+ 'Icon',
+ 'IconButton',
+ 'InputGroup',
+ 'InteractiveRoleContext',
+ 'Kbd',
+ 'Layout',
+ 'List',
+ 'ListInput',
+ 'MetadataList',
+ 'MoreMenu',
+ 'NavIcon',
+ 'NavItem',
+ 'NavMenu',
+ 'NumberInput',
+ 'OverflowList',
+ 'Popover',
+ 'PowerSearch',
+ 'Radial',
+ 'RadioList',
+ 'Sankey',
+ 'Schedule',
+ 'Section',
+ 'SizeContext',
+ 'Stack',
+ 'Stat',
+ 'SVGIcon',
+ 'Text',
+ 'TextArea',
+ 'TextInput',
+ 'ThreeD',
+ 'TimeInput',
+ 'Timestamp',
+ 'ToggleButton',
+ 'Tokenizer',
+ 'Toolbar',
+ 'Tooltip',
+ 'TransferList',
+ 'Typeahead',
+ 'VisuallyHidden',
+ 'VStack',
+];
diff --git a/apps/sandbox/src/motion/libraryCompat.ts b/apps/sandbox/src/motion/libraryCompat.ts
new file mode 100644
index 0000000000..6ee4215ab5
--- /dev/null
+++ b/apps/sandbox/src/motion/libraryCompat.ts
@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file libraryCompat.ts
+ * @input The project brief's compatibility section, checked against the audit
+ * @output The three blockers, the cheap wins, and what already works
+ * @position Motion Lab data module; no React, no side effects
+ *
+ * The recommendation is not "adopt Motion" but "be compatible with it": a
+ * ~34KB runtime on every consumer buys nothing the CSS path is failing at,
+ * and the two systems already coexist by construction because StyleX emits
+ * atomic classes and Motion writes inline styles.
+ *
+ * Numbers here are deliberately absent: where a claim is countable the page
+ * reads it from __generated__/motionAudit.ts instead. Worth knowing why that
+ * matters — the brief's figure for this section ("20+ components") was
+ * doubted by two earlier versions of the audit script and turned out to be
+ * right. A generated number is only as good as its generator.
+ */
+
+import {
+ HARDCODED_SITES,
+ TRANSFORM_TRANSITIONS,
+ type SiteRef,
+} from './__generated__/motionAudit';
+
+export const MOTION_BUNDLE_KB = 34;
+
+export type Blocker = {
+ readonly id: string;
+ readonly title: string;
+ /** What breaks, from the consumer's side. */
+ readonly symptom: string;
+ /** Why it breaks, in the code rather than in the abstract. */
+ readonly cause: string;
+ readonly fix: string;
+ /** The Astryx-side work, sized. */
+ readonly cost: string;
+ readonly severity: 'blocker' | 'friction';
+};
+
+export const BLOCKERS: ReadonlyArray<Blocker> = [
+ {
+ id: 'overlay-exit',
+ title: 'Overlays cannot exit-animate',
+ symptom:
+ 'A consumer wraps a Dialog or a Popover in AnimatePresence, writes an exit variant, and sees nothing. The enter animation works, so the failure looks like their mistake.',
+ cause:
+ 'Dialog is built on the native <dialog> element and every layer rides the Popover API. Both hard-remove the element from the top layer the moment it closes, so the exit animation runs against a box that is no longer painted. This is the same root cause as the CSS exit gap — one mechanism, failing two ways.',
+ fix: 'A keepMounted escape hatch: the consumer owns unmount, Astryx stops removing the element the frame the state flips. This is the pattern Motion documents for Base UI, so it is a shape consumers already recognise.',
+ cost: 'Shares its fix with the presence work. Doing them separately means solving top-layer retention twice.',
+ severity: 'blocker',
+ },
+ {
+ id: 'transform-transitions',
+ title: 'CSS transitions on transform',
+ symptom:
+ 'Springs never settle and drags rubber-band. The consumer is writing a value every frame and Astryx is re-easing every one of those writes.',
+ cause:
+ 'Motion performs all layout animation by writing transform on each frame. A CSS transition on transform turns every one of those writes into the start of a new 175ms ease, so the element chases the value it was already given.',
+ fix: 'Drop transform from the transition list where it only carries press or chevron feedback, or move that feedback onto the independent scale property, which no longer collides with a library writing transform.',
+ cost: 'Small and mechanical, and materially smaller than the brief budgets for.',
+ severity: 'blocker',
+ },
+ {
+ id: 'composition',
+ title: 'No composition escape hatch',
+ symptom:
+ 'motion.create() needs an element to attach to. Without one, the consumer wraps the component root in a motion.div and animates a box around the component rather than the component.',
+ cause:
+ 'Astryx has deliberately refused polymorphism, so there is no asChild-style prop. Wrapping works for a root; it is unavailable for every compound part whose element Astryx owns internally — a DropdownMenu item, a Tab, a TableRow.',
+ fix: 'A composition prop, or a render-prop shape that fits the house conventions better. This is a design review rather than a fix, and it is the one blocker that cannot be closed inside the motion project.',
+ cost: 'Unsized. It unblocks router links and drag-and-drop as well, so it should not be argued on motion alone.',
+ severity: 'blocker',
+ },
+];
+
+export type CheapWin = {
+ readonly id: string;
+ readonly title: string;
+ readonly detail: string;
+ /** Empty when the audit does not measure it. */
+ readonly evidence: string | null;
+};
+
+export const CHEAP_WINS: ReadonlyArray<CheapWin> = [
+ {
+ id: 'refs',
+ title: 'Add ref to the overlay components that lack it',
+ detail:
+ 'A component a library cannot get a DOM node out of cannot be animated by it at all. Everything else on this page is moot for those components.',
+ evidence: null,
+ },
+ {
+ id: 'drop-transform',
+ title: 'Drop the transform transitions',
+ detail:
+ 'Closes blocker 2 for every consumer, and removes a transition nobody outside a press interaction is asking for.',
+ evidence: `${TRANSFORM_TRANSITIONS.length} sites across ${new Set(TRANSFORM_TRANSITIONS.map(s => s.component)).size} components`,
+ },
+ {
+ id: 'js-mirror',
+ title: 'Ship the JS token mirror',
+ detail:
+ 'Motion takes seconds as a number and easing as a four-number array. It cannot resolve var(--duration-fast), so today a consumer either reads computed style or invents its own timing.',
+ evidence:
+ 'Already a brief deliverable; the lab has it at /motion/js-mirror',
+ },
+ {
+ id: 'reduced-motion-hook',
+ title: 'Export a reduced-motion hook',
+ detail:
+ 'An app with its own reduce-motion setting can flip Motion but cannot flip a CSS media query, so the two halves of one interface disagree. A shared hook is the only way the CSS half and the JS half can be told the same thing.',
+ evidence:
+ 'Blocked on degrade-or-delete: the hook has to return a policy, not a boolean',
+ },
+];
+
+/** The part of the brief that measurement agreed with. */
+export const ALREADY_RIGHT: ReadonlyArray<{
+ readonly title: string;
+ readonly detail: string;
+}> = [
+ {
+ title: 'Refs are React-19 native',
+ detail: 'No forwardRef ceremony for the components that pass one through.',
+ },
+ {
+ title: 'className and style pass through, consumer last',
+ detail:
+ 'The consumer wins the merge, which is what a library needs to write to an element.',
+ },
+ {
+ title: 'No runtime CSS-in-JS',
+ detail:
+ 'Nothing is recomputing styles underneath a library that is writing them.',
+ },
+ {
+ title: 'StyleX loses the specificity contest by construction',
+ detail:
+ 'Atomic classes versus inline styles: Motion wins every time, without a single !important. This is the compatibility that matters most and it already works.',
+ },
+];
+
+/** The transform sites, grouped, so the page can list real file:line evidence. */
+export function transformSitesByComponent(): ReadonlyArray<
+ readonly [string, ReadonlyArray<SiteRef>]
+> {
+ const byComponent = new Map<string, SiteRef[]>();
+ for (const site of TRANSFORM_TRANSITIONS) {
+ const existing = byComponent.get(site.component);
+ if (existing == null) {
+ byComponent.set(site.component, [site]);
+ } else {
+ existing.push(site);
+ }
+ }
+ return [...byComponent.entries()].sort((a, b) => b[1].length - a[1].length);
+}
+
+/**
+ * The brief calls Button "the worst case because it is the most-wrapped
+ * component". The measurement disagrees, so the page has to check rather than
+ * repeat it.
+ */
+export function buttonFindings(): {
+ readonly transformSites: ReadonlyArray<SiteRef>;
+ readonly hardcoded: ReadonlyArray<{
+ readonly file: string;
+ readonly line: number;
+ readonly value: string;
+ readonly prop: string;
+ }>;
+} {
+ return {
+ transformSites: TRANSFORM_TRANSITIONS.filter(
+ site => site.component === 'Button',
+ ),
+ hardcoded: HARDCODED_SITES.filter(site => site.component === 'Button').map(
+ site => ({
+ file: site.file,
+ line: site.line,
+ value: site.value,
+ prop: site.prop,
+ }),
+ ),
+ };
+}
diff --git a/apps/sandbox/src/motion/motionTokens.ts b/apps/sandbox/src/motion/motionTokens.ts
new file mode 100644
index 0000000000..34f6398ba8
--- /dev/null
+++ b/apps/sandbox/src/motion/motionTokens.ts
@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file motionTokens.ts
+ * @input Real token defaults from @astryxdesign/core/theme/tokens.stylex
+ * @output The proposed semantic motion layer, as data the lab renders and tunes
+ * @position Motion Lab data module; no React, no side effects
+ *
+ * The primitive scale and `--ease-standard` below are the values core ships
+ * today, copied so the lab can show today beside the proposal without
+ * importing StyleX vars it would not be able to read back as numbers.
+ * `scripts/generate-motion-audit.mjs` verifies the rest of the audit; these
+ * nine durations and one curve are asserted by `motionTokens.test.ts`.
+ */
+
+export type SemanticEase = {
+ readonly name: string;
+ readonly value: string;
+ readonly job: string;
+ readonly rationale: string;
+ /** Where the codebase already reaches for this curve without a token. */
+ readonly evidence?: string;
+};
+
+export type SemanticDuration = {
+ readonly name: string;
+ readonly ms: number;
+ /** The primitive it aliases, so a theme retunes it for free. */
+ readonly primitive: string | null;
+ readonly job: string;
+ readonly budget: readonly [number, number] | null;
+ readonly note?: string;
+};
+
+// --- what core ships today -------------------------------------------------
+
+export const PRIMITIVE_DURATIONS: ReadonlyArray<readonly [string, number]> = [
+ ['--duration-fast-min', 130],
+ ['--duration-fast', 175],
+ ['--duration-fast-max', 230],
+ ['--duration-medium-min', 310],
+ ['--duration-medium', 410],
+ ['--duration-medium-max', 550],
+ ['--duration-slow-min', 730],
+ ['--duration-slow', 975],
+ ['--duration-slow-max', 1300],
+];
+
+/** The one easing token core has. It covers entry, exit and state at once. */
+export const CURRENT_EASE = {
+ name: '--ease-standard',
+ value: 'cubic-bezier(0.24, 1, 0.4, 1)',
+} as const;
+
+// --- the proposal ----------------------------------------------------------
+
+export const SEMANTIC_EASES: ReadonlyArray<SemanticEase> = [
+ {
+ name: '--ease-entry',
+ value: 'cubic-bezier(0.23, 1, 0.32, 1)',
+ job: 'Things arriving. Decelerates hard.',
+ rationale:
+ 'Within a hair of the current --ease-standard, so this is a rename with a nudge and almost nothing shifts.',
+ },
+ {
+ name: '--ease-exit',
+ value: 'cubic-bezier(0.3, 0, 0.6, 0.6)',
+ job: 'Things leaving. Accelerates away.',
+ rationale:
+ 'Not a proposal so much as a promotion: the sheet already authors this curve locally, with a comment measuring why the standard one would not do.',
+ evidence: 'BottomSheet/BottomSheetPanel.tsx:172',
+ },
+ {
+ name: '--ease-move',
+ value: 'cubic-bezier(0.77, 0, 0.175, 1)',
+ job: 'Movement on screen: sliding indicators, morphing surfaces, reorder.',
+ rationale:
+ 'Symmetric in-out. The thing is already on screen, so it needs no arrival accent — only a legible path.',
+ },
+ {
+ name: '--ease-state',
+ value: 'ease',
+ job: 'Hover, colour, selection.',
+ rationale:
+ 'Symmetric and cheap. The sites that declare a duration and no curve are silently getting this already, so naming it changes nothing except that it becomes reviewable.',
+ evidence: 'DURATION_WITHOUT_CURVE in the audit',
+ },
+ {
+ name: '--ease-linear',
+ value: 'linear',
+ job: 'Progress, spinners, marquees, scroll-linked motion.',
+ rationale:
+ 'Correct behaviour, wrong provenance: several sites hardcode it and most of them are right to. A token makes them lintable.',
+ evidence: 'Spinner, DateInput wheel, BottomSheet scrim, Stepper',
+ },
+ {
+ name: '--ease-drawer',
+ value: 'cubic-bezier(0.32, 0.72, 0, 1)',
+ job: 'Sheet and drawer travel.',
+ rationale:
+ 'The iOS curve. Matches what BottomSheet and MobileNav are reaching for when they hand-tune sheet travel.',
+ },
+];
+
+export const SEMANTIC_DURATIONS: ReadonlyArray<SemanticDuration> = [
+ {
+ name: '--duration-instant',
+ ms: 0,
+ primitive: null,
+ job: 'Reduced motion and deliberate discrete flips.',
+ budget: null,
+ note: 'Replaces the spellings in use today. The 0.01s form is the common one and it is not arbitrary — a zero duration fires no transitionend, so anything sequencing off that event breaks. Decide 0 vs 0.01ms before the sweep.',
+ },
+ {
+ name: '--duration-press',
+ ms: 130,
+ primitive: '--duration-fast-min',
+ job: 'Press and active feedback.',
+ budget: [100, 160],
+ },
+ {
+ name: '--duration-state',
+ ms: 175,
+ primitive: '--duration-fast',
+ job: 'Hover, colour, selection, focus ring.',
+ budget: [100, 250],
+ },
+ {
+ name: '--duration-enter',
+ ms: 230,
+ primitive: '--duration-fast-max',
+ job: 'Popovers, tooltips, menus arriving.',
+ budget: [125, 250],
+ },
+ {
+ name: '--duration-exit',
+ ms: 175,
+ primitive: '--duration-fast',
+ job: 'Dismissal.',
+ budget: [100, 250],
+ note: 'Deliberately shorter than enter, because old content should leave faster than new content arrives.',
+ },
+ {
+ name: '--duration-reveal',
+ ms: 310,
+ primitive: '--duration-medium-min',
+ job: 'Disclosure, collapse, expand.',
+ budget: [200, 350],
+ },
+ {
+ name: '--duration-overlay',
+ ms: 410,
+ primitive: '--duration-medium',
+ job: 'Dialogs, drawers, sheets.',
+ budget: [200, 500],
+ },
+ {
+ name: '--duration-continuous',
+ ms: 975,
+ primitive: '--duration-slow',
+ job: 'Spinners, progress, ambient loops.',
+ budget: null,
+ note: 'Does not reach the loops that actually exist: StatusDot runs 2s and Chat 1.5s, both outside a scale that stops at 1300ms.',
+ },
+];
+
+export const STAGGERS: ReadonlyArray<readonly [string, number, string]> = [
+ ['--stagger-tight', 30, 'Dense lists, small items.'],
+ ['--stagger-base', 50, 'Default group entrance.'],
+ ['--stagger-loose', 80, 'Few large items. Longer than this feels slow.'],
+];
+
+export type SpringSpec = {
+ readonly name: string;
+ readonly duration: number;
+ readonly bounce: number;
+ readonly use: string;
+ /** The CSS pair a component should use for the same gesture. */
+ readonly cssCounterpart: readonly [string, string];
+};
+
+export const SPRINGS: ReadonlyArray<SpringSpec> = [
+ {
+ name: 'press',
+ duration: 0.3,
+ bounce: 0.1,
+ use: 'Pressable surfaces',
+ cssCounterpart: ['--duration-press', '--ease-entry'],
+ },
+ {
+ name: 'swap',
+ duration: 0.4,
+ bounce: 0.15,
+ use: 'Content trading places inside a control',
+ cssCounterpart: ['--duration-enter', '--ease-move'],
+ },
+ {
+ name: 'panel',
+ duration: 0.5,
+ bounce: 0.2,
+ use: 'Overlay entrances, sheet travel',
+ cssCounterpart: ['--duration-overlay', '--ease-drawer'],
+ },
+ {
+ name: 'layout',
+ duration: 0.5,
+ bounce: 0.15,
+ use: 'Sliding indicators, morphing surfaces, reorder',
+ cssCounterpart: ['--duration-overlay', '--ease-move'],
+ },
+];
+
+/** Every tunable custom property, so the store can reset in one pass. */
+export const ALL_TUNABLE_TOKENS: ReadonlyArray<string> = [
+ ...SEMANTIC_EASES.map(e => e.name),
+ ...SEMANTIC_DURATIONS.map(d => d.name),
+ ...STAGGERS.map(([name]) => name),
+];
+
+export const DEFAULT_TOKEN_VALUES: Readonly<Record<string, string>> = {
+ ...Object.fromEntries(SEMANTIC_EASES.map(e => [e.name, e.value])),
+ ...Object.fromEntries(SEMANTIC_DURATIONS.map(d => [d.name, `${d.ms}ms`])),
+ ...Object.fromEntries(STAGGERS.map(([name, ms]) => [name, `${ms}ms`])),
+};
diff --git a/apps/sandbox/src/motion/openQuestions.ts b/apps/sandbox/src/motion/openQuestions.ts
new file mode 100644
index 0000000000..ba613fb652
--- /dev/null
+++ b/apps/sandbox/src/motion/openQuestions.ts
@@ -0,0 +1,368 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file openQuestions.ts
+ * @input The project brief, its review comments, and the lab's own findings
+ * @output Sequence, gates, open questions, scope rules and risks
+ * @position Motion Lab data module; no React, no side effects
+ *
+ * Named for the open questions because they are the part that blocks: the
+ * sequence below is not a schedule but a dependency order, and most of its
+ * edges are decisions rather than code. A stage with an unanswered question
+ * above it does not start early, it starts twice.
+ */
+
+export type Stage = {
+ readonly id: string;
+ readonly index: number;
+ readonly name: string;
+ readonly size: string;
+ readonly goal: string;
+ readonly work: ReadonlyArray<string>;
+ /** What has to be true before this stage starts. Decisions count. */
+ readonly blockedBy: ReadonlyArray<string>;
+};
+
+export const STAGES: ReadonlyArray<Stage> = [
+ {
+ id: 'spike',
+ index: 0,
+ name: 'Spike',
+ size: '1 week',
+ goal: 'Find out whether the presence work is a week or a quarter before committing to either.',
+ work: [
+ 'Prototype layer exit on Tooltip and Popover only — the two ends of the frequency range.',
+ 'Test @starting-style, transition-behavior: allow-discrete, and top-layer retention in the browsers Astryx supports.',
+ 'Define the dismissal state machine: what happens to focus return, outside-press and escape while an element is still leaving.',
+ 'Prototype press feedback on the independent scale property, on Button.',
+ ],
+ blockedBy: [],
+ },
+ {
+ id: 'foundation',
+ index: 1,
+ name: 'Foundation',
+ size: 'Sequenced in four steps, in this order',
+ goal: 'Get a semantic vocabulary in place without changing how anything looks.',
+ work: [
+ 'Semantic tokens as pure ALIASES onto the existing primitives — nothing shifts perceptually, so this lands with no visual review.',
+ 'Motion lint in warn mode, so the real violation list is the linter\u2019s rather than a script\u2019s.',
+ 'The token sweep: every hardcoded value becomes a token, still with no perceptual change.',
+ 'Lint to error. Only then retune the values, as a separate change with its own visual review.',
+ ],
+ blockedBy: [
+ 'Springs theme-tunable or not: adding them to the theme contract later is a breaking change.',
+ 'What --duration-instant is: 0s or 0.01ms. Ten of the measured sites are 0.01s escapes that exist to keep transitionend firing.',
+ ],
+ },
+ {
+ id: 'presence',
+ index: 2,
+ name: 'Presence',
+ size: 'The largest single change',
+ goal: 'One shared way to animate enter and exit, replacing six patterns.',
+ work: [
+ 'Shared presence primitive; useLayer awaits its exit rather than hiding synchronously.',
+ 'Eleven layer components inherit it from one change.',
+ 'Dialog, AlertDialog and CommandPalette, plus the backdrop transition the scrim has never had.',
+ 'The input-during-exit rule, written into the primitive\u2019s contract.',
+ ],
+ blockedBy: [
+ 'Stage 0\u2019s dismissal state machine.',
+ 'The exit-optional reversal: the published page currently permits the hard cut, so the paragraph rewrite ships in this stack, not in Docs.',
+ ],
+ },
+ {
+ id: 'rubric',
+ index: 3,
+ name: 'Rubric',
+ size: 'Publication plus four automated checks',
+ goal: 'Motion becomes something a component is measured against rather than reviewed by taste.',
+ work: [
+ 'Publish the criteria beside the accessibility checklist.',
+ 'Wire criteria 3, 5, 10 and 12 — the mechanical ones — into CI.',
+ 'Score every core component and track the results as a readiness gate.',
+ ],
+ blockedBy: [
+ 'Where the rubric lives: wiki or published docs.',
+ 'A grandfathering policy, or the rubric blocks unrelated work on day one.',
+ 'The published-page rewrite: a rubric cannot fail a component for following the docs.',
+ ],
+ },
+ {
+ id: 'coverage',
+ index: 4,
+ name: 'Coverage',
+ size: 'Many small changes, individually revertible',
+ goal: 'The gaps the audit named, in impact order.',
+ work: [
+ 'Sliding indicators for TabList and SegmentedControl.',
+ 'Converge the nine disclosure surfaces onto one technique.',
+ 'SideNav rail collapse; the ADD rows: chips, skeleton swap, Banner, Lightbox, EmptyState.',
+ ],
+ blockedBy: [
+ 'Disclosure: grid tracks or height interpolation.',
+ 'The presence primitive, for anything with an enter and an exit.',
+ ],
+ },
+ {
+ id: 'docs',
+ index: 5,
+ name: 'Docs',
+ size: 'Continuous, not a phase',
+ goal: 'The published page stops disagreeing with the system.',
+ work: [
+ 'Per-component motion specs and the property-level rules that live only on the wiki.',
+ 'The library compatibility guide and its conformance test.',
+ 'An owner and a trigger to revisit, since four months of drift is the status quo this has to break.',
+ ],
+ blockedBy: [
+ 'Every decision above — except the two reversal paragraphs, which ship with their code rather than waiting for this stage.',
+ ],
+ },
+];
+
+export type OpenQuestion = {
+ readonly id: string;
+ readonly question: string;
+ /** Who or what has to supply the answer. */
+ readonly needs: string;
+ readonly blocks: string;
+ /** Where in the lab you can look at it rather than argue about it. */
+ readonly href: string;
+ readonly hrefLabel: string;
+ readonly urgency:
+ | 'decide first'
+ | 'decide before the sweep'
+ | 'decide before publishing'
+ | 'can run late';
+};
+
+export const OPEN_QUESTIONS: ReadonlyArray<OpenQuestion> = [
+ {
+ id: 'composition',
+ question: 'Should Astryx adopt an asChild-style composition prop?',
+ needs:
+ 'A design review at house level. Astryx has deliberately refused polymorphism, and a render-prop shape may fit the conventions better than asChild.',
+ blocks:
+ 'Motion blocker 3, and equally router links and drag-and-drop. It should not be decided on motion\u2019s evidence alone.',
+ href: '/motion/library',
+ hrefLabel: 'The three blockers',
+ urgency: 'can run late',
+ },
+ {
+ id: 'springs-themeable',
+ question: 'Should springs be theme-tunable?',
+ needs:
+ 'A call on whether a theme carries motion personality as well as colour and type.',
+ blocks:
+ 'The token work. Adding springs to the theme contract after it ships is a breaking change, so this is decided before Foundation lands even if no theme overrides them at first.',
+ href: '/motion/springs',
+ hrefLabel: 'Tune the four springs',
+ urgency: 'decide first',
+ },
+ {
+ id: 'degrade-or-delete',
+ question: 'Degrade or delete under reduced motion?',
+ needs:
+ 'A designer and an accessibility sign-off. Note that delete is not the status quo by accident — it is what the published page instructs, so degrading is a policy change.',
+ blocks:
+ 'The 36-file sweep, which writes whichever branch is chosen 36 times, and the reduced-motion hook, which has to return a policy rather than a boolean.',
+ href: '/motion/reduced-motion',
+ hrefLabel: 'Both policies, side by side',
+ urgency: 'decide before the sweep',
+ },
+ {
+ id: 'transform-strictness',
+ question: 'How strict is the no-CSS-transition-on-transform rule?',
+ needs:
+ 'A prototype of press feedback on the independent scale property. The evidence supports the brief: Button transitions transform at Button/Button.tsx:90 and takes scale(0.98) on :active, so it is exactly the conflict the brief describes.',
+ blocks:
+ 'Rubric criterion 12, and the press token. The middle path costs one property name.',
+ href: '/motion/library',
+ hrefLabel: 'transform vs scale vs none',
+ urgency: 'decide before publishing',
+ },
+ {
+ id: 'rubric-home',
+ question: 'Where does the rubric live?',
+ needs:
+ 'A repo-convention call. Wiki keeps the published page clean; it also means reviewers and consumers read different documents, which is part of why the transform-only rule never reached anyone outside the team.',
+ blocks:
+ 'Rubric publication, and whether consumers can self-assess before promotion.',
+ href: '/motion/rubric',
+ hrefLabel: 'The bench',
+ urgency: 'decide before publishing',
+ },
+ {
+ id: 'disclosure',
+ question: 'Disclosure: grid tracks or height interpolation?',
+ needs:
+ 'A bake-off verdict. It probably has no single winner — a table row cannot be a grid container — so the honest answer may be one technique with a documented exception.',
+ blocks:
+ 'Converging nine surfaces, and any new disclosure surface built meanwhile.',
+ href: '/motion/previews',
+ hrefLabel: 'The three techniques',
+ urgency: 'decide before the sweep',
+ },
+ {
+ id: 'slow-band',
+ question:
+ 'Does the slow band get extended, or is ambient motion out of scope?',
+ needs:
+ 'A ruling. The scale stops at 1300ms, so StatusDot at 2s and Chat at 1.5s bypass it entirely; both are in the hardcoded list because of it.',
+ blocks:
+ 'Those two sites in the sweep, and the definition of --duration-continuous.',
+ href: '/motion/tokens',
+ hrefLabel: 'The duration scale',
+ urgency: 'decide before the sweep',
+ },
+ {
+ id: 'mobile-tokens',
+ question: 'Do we need different semantic motion tokens for mobile?',
+ needs:
+ 'A decision on the shape, not the values. Recommendation: one shared vocabulary, per-platform values — the same names resolving to different numbers, the way the colour tokens already work. Two vocabularies means two rubrics and two docs pages.',
+ blocks:
+ 'Token naming, so it is cheap now and expensive after the sweep. Raised in review on the Semantic motion tokens deliverable.',
+ href: '/motion/tokens',
+ hrefLabel: 'The proposed vocabulary',
+ urgency: 'decide first',
+ },
+ {
+ id: 'theming-defaults',
+ question: 'Do we publish default theming values with the tokens?',
+ needs:
+ 'A call on what the theme contract exposes. The Collapsible reveal already introduced per-component theme-tunable motion, a sixth theming mechanism no doc describes, so the answer affects more than motion.',
+ blocks:
+ 'The docs rewrite, and the springs question above — both are asking what a theme is allowed to retune. Raised in review on Deliverables.',
+ href: '/motion/export',
+ hrefLabel: 'What the lab emits',
+ urgency: 'decide before publishing',
+ },
+];
+
+export type Commitment = {
+ readonly item: string;
+ readonly level: 'committed' | 'stretch';
+ readonly why: string;
+};
+
+export const COMMITMENTS: ReadonlyArray<Commitment> = [
+ {
+ item: 'Semantic tokens as aliases + JS mirror',
+ level: 'committed',
+ why: 'No perceptual change, so it cannot slip on visual review.',
+ },
+ {
+ item: 'Motion lint + the token sweep',
+ level: 'committed',
+ why: 'Mechanical, and it is what stops the list growing while the rest of the work runs.',
+ },
+ {
+ item: 'Layer exit + shared presence primitive',
+ level: 'committed',
+ why: 'Eleven components from one change. The highest-leverage item in the audit.',
+ },
+ {
+ item: 'Dialog, AlertDialog, CommandPalette exit + backdrop',
+ level: 'committed',
+ why: 'Same primitive, and the scrim hard-cut is the most visible instance.',
+ },
+ {
+ item: 'Rewrite of the two reversal paragraphs',
+ level: 'committed',
+ why: 'Ships with the code it contradicts, or the rubric has no authority.',
+ },
+ {
+ item: 'Rubric published + four automated criteria',
+ level: 'committed',
+ why: 'Criteria 3, 5, 10 and 12 are mechanical; the token linter already exists.',
+ },
+ {
+ item: 'Value retune (the six curves, the eight durations)',
+ level: 'stretch',
+ why: 'Moves every visual-regression baseline. Worth doing, worth doing alone.',
+ },
+ {
+ item: 'Sliding indicators, disclosure convergence, SideNav rail',
+ level: 'stretch',
+ why: 'Each is a real component change with its own review; none blocks anything else.',
+ },
+ {
+ item: 'The ADD rows (chips, skeleton swap, Banner, Lightbox, EmptyState)',
+ level: 'stretch',
+ why: 'Individually small, collectively a quarter. Take them in frequency order.',
+ },
+ {
+ item: 'Conformance test in CI for library compatibility',
+ level: 'stretch',
+ why: 'Needs the guide first, and the guide needs the composition decision.',
+ },
+ {
+ item: 'Composition prop',
+ level: 'stretch',
+ why: 'A house-level design decision that motion should inform, not force.',
+ },
+];
+
+export type Risk = {
+ readonly risk: string;
+ /** What the lab does about it — or admits it cannot. */
+ readonly mitigation: string;
+};
+
+export const RISKS: ReadonlyArray<Risk> = [
+ {
+ risk: 'Retuning easing changes how every existing component feels.',
+ mitigation:
+ 'Tokens ship as pure aliases first, so the retune is a separate and revertible change. The lab is where the curves get agreed before that change is written: the rail\u2019s slow-mo reads a 175ms curve at 8x without moving the token.',
+ },
+ {
+ risk: 'Motion is already fighting the automated gates — two fixes landed this month to stop animation interfering with the a11y audit and the visual-regression capture.',
+ mitigation:
+ 'The lab cannot fix this. It is a policy gap: there is no documented rule for what an animated component does under test. Write one alongside the rubric, or the third fix lands the same way.',
+ },
+ {
+ risk: 'The exit work touches dismissal, which is load-bearing and has its own invariants test.',
+ mitigation:
+ 'That is what stage 0 is for. Keeping an element alive through its exit doubles the state matrix for focus return, outside-press and escape, and the spike exists to size that before anyone commits to the quarter.',
+ },
+ {
+ risk: 'Focus return races the exit: Dialog returns focus to the trigger the moment it closes.',
+ mitigation:
+ 'Visible in the lab\u2019s Dialog rig — the focus ring lands on the trigger while the dialog is still on screen, and the page may scroll under it. The presence contract has to say when focus moves, not just when the element goes.',
+ },
+ {
+ risk: 'The rubric will fail components that ship today.',
+ mitigation:
+ 'The bench scores real components, so the grandfathering list is a measured list rather than a promise. Publish it with the rubric.',
+ },
+ {
+ risk: 'Doc drift is the status quo — the page went four months while a reduced-motion campaign landed underneath it.',
+ mitigation:
+ 'The published-page comparison is a diff against the live text, with quotes verbatim so it can be re-run. Make that a check rather than a page, and drift becomes a failure rather than a discovery.',
+ },
+];
+
+/** Inconsistencies in the brief itself, found while building the lab. */
+export const BRIEF_DEFECTS: ReadonlyArray<{
+ readonly defect: string;
+ readonly detail: string;
+}> = [
+ {
+ defect:
+ 'Deliverables says ten graded criteria; the rubric table has twelve.',
+ detail:
+ 'Criteria 11 (cohesion) and 12 (library compatibility) are the two beyond ten. Twelve is the right number — 12 is the one four-of-which-are-automatable claim depends on — so fix the Deliverables line, not the table.',
+ },
+ {
+ defect: 'The timeline has no dates.',
+ detail:
+ 'Five milestones, every Due cell empty. Without dates the sequence above is the only ordering anyone can act on, and "by end of H2" is not a plan for six workstreams.',
+ },
+ {
+ defect: 'The team is one person.',
+ detail:
+ 'Team lists a single name for eleven components of presence work, a package-wide token sweep, a rubric, a docs rewrite and a compatibility guide. The decisions above need a designer and an accessibility reviewer who are not currently on it.',
+ },
+];
diff --git a/apps/sandbox/src/motion/pages/bugs.tsx b/apps/sandbox/src/motion/pages/bugs.tsx
new file mode 100644
index 0000000000..137c8f8326
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/bugs.tsx
@@ -0,0 +1,756 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input The generated audit, the installed core source, the lab store
+ * @output Which structural findings survive contact with the code
+ * @position /motion/bugs
+ *
+ * Of the four structural findings, one is real and underplayed, one is a
+ * misreading of three components, one is correct code the scanner flags, and
+ * one cannot be verified in this app at all. Every claim here is checked
+ * against the installed package and cited file:line, including the places
+ * where the generated audit was itself wrong.
+ */
+
+import {useCallback, useEffect, useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Switch} from '@astryxdesign/core/Switch';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {LabPage} from '../PageFrame';
+import {
+ ComparePanes,
+ DemoBody,
+ DemoCard,
+ LabSlider,
+ Runner,
+ useLoop,
+} from '../LabPrimitives';
+import {useMotionLab} from '../MotionLabStore';
+import {
+ AUDIT_COUNTS,
+ DURATION_WITHOUT_CURVE,
+ NOOP_TRANSITIONS,
+ TIMEOUT_LITERALS,
+ TRANSFORM_TRANSITIONS,
+ TRANSITION_ALL,
+} from '../__generated__/motionAudit';
+import styles from '../MotionLab.module.css';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ mono: {fontFamily: 'var(--font-family-code)', fontSize: '12px'},
+ rows: {width: '100%'},
+ readout: {
+ fontFamily: 'var(--font-family-code)',
+ fontSize: '13px',
+ },
+ drawerBack: {padding: '14px', maxWidth: '34%'},
+});
+
+/** The rotation rule the brief reads as dead, verbatim from the package. */
+const SELECTOR_SOURCE = `// Rotation lives on the chevron glyph itself (passed through \`xstyle\`), not
+// on the layout wrapper above, so the icon's \`selector-indicator-icon\` theme
+// target and the open/closed transform sit on one element — a theme can
+// restyle the mark and its rotation through a single selector. The wrapper
+// keeps only layout. The status branch renders a different icon, so it never
+// picks these up and needs no transition opt-out.
+triggerIconRotation: {
+ transitionProperty: 'transform',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ transformOrigin: 'center',
+},
+triggerIconOpen: {
+ transform: 'rotate(180deg)',
+},`;
+
+const LIGHTBOX_SOURCE = `image: {
+ maxWidth: '100%',
+ maxHeight: '100%',
+ objectFit: 'contain',
+ pointerEvents: 'none',
+ transitionProperty: 'transform',
+ transitionDuration: {
+ default: '200ms',
+ '@media (prefers-reduced-motion: reduce)': '0ms',
+ },
+ transitionTimingFunction: 'ease-out',
+},
+imageDragging: {
+ transitionProperty: 'none',
+},
+
+// ...applied only while the pointer is down, Lightbox.tsx:691
+isDragging && styles.imageDragging,`;
+
+const TIMER_FIX = `// What the brief describes: a literal that has to be kept in sync by hand.
+setTimeout(() => setMounted(false), 250);
+
+// What removes the class of bug: the element says when it is done.
+const panel = panelRef.current;
+if (panel == null) {
+ setMounted(false);
+ return;
+}
+Promise.allSettled(panel.getAnimations().map(a => a.finished)).then(() =>
+ setMounted(false),
+);
+
+// The transitionend form, for a single known property. Note the guard: a
+// bubbling transitionend from a child would unmount the panel early, and a
+// zero duration fires nothing at all — which is why --duration-instant
+// cannot simply be 0.
+panel.addEventListener('transitionend', event => {
+ if (event.target === panel && event.propertyName === 'transform') {
+ setMounted(false);
+ }
+});`;
+
+const INSTANT_DWC = DURATION_WITHOUT_CURVE.filter(
+ site => site.decl?.includes('0.01s') === true,
+);
+const SUBSTANTIVE_DWC = DURATION_WITHOUT_CURVE.filter(
+ site => site.decl?.includes('0.01s') !== true,
+);
+const SUBSTANTIVE_DWC_COMPONENTS = [
+ ...new Set(SUBSTANTIVE_DWC.map(site => site.component)),
+].sort();
+
+/** transform declared inside a longer property list, which a grep never finds. */
+const MULTI_PROPERTY_TRANSFORMS = TRANSFORM_TRANSITIONS.filter(
+ site => site.decl?.includes(',') === true,
+);
+const SINGLE_PROPERTY_TRANSFORMS =
+ TRANSFORM_TRANSITIONS.length - MULTI_PROPERTY_TRANSFORMS.length;
+/** ...and the ones that also animate a layout property, which is criterion 6. */
+const LAYOUT_MIXED_TRANSFORMS = MULTI_PROPERTY_TRANSFORMS.filter(site =>
+ /width|height|top|left|margin|padding|inset/.test(site.decl ?? ''),
+);
+
+const LINT_MAP: ReadonlyArray<{
+ readonly finding: string;
+ readonly rule: string;
+ readonly status: string;
+}> = [
+ {
+ finding: 'A duration with no declared curve',
+ rule: 'require-timing-function — a transitionDuration in a rule with no transitionTimingFunction and no shorthand.',
+ status: `${AUDIT_COUNTS.durationWithoutCurve} sites today, ${SUBSTANTIVE_DWC.length} of them substantive.`,
+ },
+ {
+ finding: 'A transitionProperty with no duration',
+ rule: "no-noop-transition — same shape, inverted. Must exempt transitionProperty: 'none', which is a deliberate opt-out.",
+ status: `${AUDIT_COUNTS.noopTransitions} site today, and it is the exemption case.`,
+ },
+ {
+ finding: 'transition: all',
+ rule: 'no-transition-all — a property list containing all.',
+ status: `${TRANSITION_ALL.length} today. Pure regression guard.`,
+ },
+ {
+ finding: 'A hardcoded duration, delay or curve',
+ rule: 'motion-tokens-only — any time literal or bezier literal outside the token file.',
+ status: `${AUDIT_COUNTS.hardcodedTotal} today. Needs an allowlist for the reduced-motion escape.`,
+ },
+ {
+ finding: 'A timer literal standing in for a transition',
+ rule: 'no-animation-timeout — a setTimeout whose literal matches a duration token value, inside a component that transitions.',
+ status: `${TIMEOUT_LITERALS.length} literal timer in core, and it is unrelated to motion.`,
+ },
+ {
+ finding: 'A CSS transition on transform',
+ rule: 'no-transform-transition — criterion 12, the motion-library blocker.',
+ status: `${AUDIT_COUNTS.transformTransitions} sites across ${AUDIT_COUNTS.transformTransitionComponents} components — criterion 12's entire caseload.`,
+ },
+];
+
+/** Rows carrying the no-op rule, beside rows carrying a real one. */
+function Rows({variant}: {variant: 'noop' | 'tint'}) {
+ return (
+ <VStack gap={1} {...stylex.props(sx.rows)}>
+ {['Row one', 'Row two', 'Row three'].map(row => (
+ // The CSS module owns both rules: the point of the pane is the
+ // declaration itself, so it has to be the real one.
+ <div
+ key={row}
+ className={variant === 'noop' ? styles.noopRow : styles.tintRow}>
+ <Text type="supporting">{row}</Text>
+ </div>
+ ))}
+ </VStack>
+ );
+}
+
+/**
+ * The unmount timer racing the slide. Both sliders are live and both tracks
+ * run in real time, because the finding is a relationship between two numbers
+ * rather than either number on its own.
+ */
+function DrawerCutDemo() {
+ const {speed} = useMotionLab();
+ const [slideMs, setSlideMs] = useState(410);
+ const [timerMs, setTimerMs] = useState(250);
+ const [derived, setDerived] = useState(false);
+ const [open, setOpen] = useState(true);
+ const [cut, setCut] = useState(false);
+
+ const slideFill = useRef<HTMLSpanElement | null>(null);
+ const timerFill = useRef<HTMLSpanElement | null>(null);
+ const raf = useRef<number | null>(null);
+ const timers = useRef<Array<number>>([]);
+
+ const effectiveTimer = derived ? slideMs : timerMs;
+ const slideRun = slideMs * speed;
+ const timerRun = effectiveTimer * speed;
+ const completed = Math.min(100, (effectiveTimer / slideMs) * 100);
+
+ const clear = useCallback(() => {
+ for (const id of timers.current) {
+ window.clearTimeout(id);
+ }
+ timers.current = [];
+ if (raf.current != null) {
+ cancelAnimationFrame(raf.current);
+ raf.current = null;
+ }
+ }, []);
+
+ const play = useCallback(() => {
+ clear();
+ setCut(false);
+ setOpen(true);
+ if (slideFill.current != null) {
+ slideFill.current.style.width = '0%';
+ }
+ if (timerFill.current != null) {
+ timerFill.current.style.width = '0%';
+ }
+ timers.current.push(
+ window.setTimeout(() => {
+ setOpen(false);
+ const start = performance.now();
+ const span = Math.max(slideRun, timerRun);
+ const step = (now: number) => {
+ const elapsed = now - start;
+ if (slideFill.current != null) {
+ slideFill.current.style.width = `${Math.min(100, (elapsed / slideRun) * 100)}%`;
+ }
+ if (timerFill.current != null) {
+ timerFill.current.style.width = `${Math.min(100, (elapsed / timerRun) * 100)}%`;
+ }
+ if (elapsed < span) {
+ raf.current = requestAnimationFrame(step);
+ }
+ };
+ raf.current = requestAnimationFrame(step);
+ timers.current.push(window.setTimeout(() => setCut(true), timerRun));
+ }, 700),
+ );
+ }, [clear, slideRun, timerRun]);
+
+ useEffect(() => clear, [clear]);
+ useLoop(play, Math.max(2600, slideRun + timerRun + 1400));
+
+ return (
+ <VStack gap={3} {...stylex.props(sx.full)}>
+ <div className={`${styles.stage} ${styles.stageBlock}`}>
+ <VStack gap={1} {...stylex.props(sx.drawerBack)}>
+ <Text type="supporting" color="secondary">
+ Page behind
+ </Text>
+ </VStack>
+ {/* The transition, the visibility hand-off and the cut are all in the
+ CSS module: a style object cannot express the [data-open] pair. */}
+ <div
+ data-open={open}
+ style={{['--drawer-slide' as string]: `${slideRun}ms`}}
+ className={
+ cut ? `${styles.drawer} ${styles.drawerCut}` : styles.drawer
+ }>
+ <VStack gap={1}>
+ <Text weight="semibold">Drawer</Text>
+ <Text type="supporting" color="secondary">
+ Slides on --ease-drawer. Removed by a timer that does not know
+ about it.
+ </Text>
+ </VStack>
+ </div>
+ </div>
+
+ <Grid columns={{minWidth: 260}} gap={3}>
+ <VStack gap={1}>
+ <Text type="supporting" weight="semibold">
+ Slide — {slideMs}ms
+ </Text>
+ <span className={styles.track}>
+ <span
+ ref={slideFill}
+ className={`${styles.trackFill} ${styles.trackSlide}`}
+ />
+ </span>
+ </VStack>
+ <VStack gap={1}>
+ <Text type="supporting" weight="semibold">
+ Unmount timer — {effectiveTimer}ms
+ </Text>
+ <span className={styles.track}>
+ <span
+ ref={timerFill}
+ className={`${styles.trackFill} ${styles.trackTimer}`}
+ />
+ </span>
+ </VStack>
+ </Grid>
+
+ <Text {...stylex.props(sx.readout)}>
+ {completed >= 100
+ ? 'The panel survives its whole exit — 100% of the slide runs.'
+ : `The panel is removed at ${Math.round(completed)}% of its travel. ${Math.round(
+ 100 - completed,
+ )}% of the exit never runs.`}
+ </Text>
+
+ <LabSlider
+ label="Slide duration"
+ value={slideMs}
+ min={150}
+ max={800}
+ step={10}
+ format={v => `${v}ms`}
+ onChange={setSlideMs}
+ />
+ <LabSlider
+ label="Unmount timer"
+ value={timerMs}
+ min={50}
+ max={800}
+ step={10}
+ format={v => `${v}ms`}
+ onChange={setTimerMs}
+ />
+ <Switch
+ label="Derive the timer from the transition"
+ description="What the fix does: the panel unmounts when its own animation finishes, so the two numbers cannot drift apart."
+ value={derived}
+ onChange={setDerived}
+ />
+ </VStack>
+ );
+}
+
+export default function MotionBugsPage() {
+ const noop = NOOP_TRANSITIONS[0];
+
+ return (
+ <LabPage
+ title="Small bugs"
+ intro="Four structural findings in the brief. One is real and underplayed, one is a misreading of three components, one is correct code the scanner flags, and one cannot be verified in this app at all."
+ badges={<Badge variant="warning" label="1 of 4 survives as written" />}
+ decides="Which of the structural findings are real once you look at the code.">
+ <Banner
+ status="warning"
+ title="The three dead no-op transitions are not there"
+ description={
+ <Text>
+ The brief lists three dead no-op transitions in Selector,
+ ComplexSelector and MultiSelector. All three rules exist, and all
+ three carry a tokenised duration
+ <em> and </em> a tokenised curve. The audit finds exactly one no-op
+ in the whole package —{' '}
+ <code>
+ {noop?.file}:{noop?.line}
+ </code>{' '}
+ — and it is a deliberate{' '}
+ <code>transitionProperty: &lsquo;none&rsquo;</code> that turns a
+ transition off during a drag. Correct code, flagged by a scanner.
+ </Text>
+ }
+ />
+
+ <DemoCard
+ title="The three that are not dead"
+ question="Selector, ComplexSelector and MultiSelector all declare the same rotation rule. Is anything missing from it?"
+ badges={<Badge variant="success" label="No finding" />}>
+ <DemoBody>
+ <CodeBlock
+ language="tsx"
+ title="Selector/Selector.tsx:201-214 — identical at ComplexSelector.tsx:154-166 and MultiSelector.tsx:178-191"
+ code={SELECTOR_SOURCE}
+ hasCopyButton
+ maxHeight={340}
+ />
+ <Text type="supporting">
+ Property, duration and curve, all three tokenised, paired with{' '}
+ <code>triggerIconOpen</code> which supplies the transform. There is
+ nothing dead here.
+ </Text>
+ <Text type="supporting" color="secondary">
+ The misreading is easy to make and the source explains it: the
+ rotation was moved off the layout wrapper and onto the chevron
+ glyph, which receives it through <code>xstyle</code>. Read the
+ wrapper and you see a component that rotates something with no
+ transition anywhere near it. Worth re-checking before it becomes a
+ milestone line item — it is currently costed as three fixes that do
+ not exist.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="The one real no-op is correct"
+ question={`${noop?.file}:${noop?.line} — a transitionProperty with no duration. Bug, or opt-out?`}
+ badges={<Badge variant="success" label="Working as intended" />}>
+ <DemoBody>
+ <CodeBlock
+ language="tsx"
+ title="Lightbox/Lightbox.tsx:180-194, applied at :691"
+ code={LIGHTBOX_SOURCE}
+ hasCopyButton
+ maxHeight={380}
+ />
+ <Text type="supporting">
+ The zoomed image transitions <code>transform</code> over 200ms so a
+ zoom step glides. While the pointer is down,{' '}
+ <code>imageDragging</code> replaces that with{' '}
+ <code>transitionProperty: &lsquo;none&rsquo;</code>, so the image
+ tracks the pointer 1:1 instead of easing 200ms behind it. Removing
+ it would make dragging feel like dragging through syrup.
+ </Text>
+ <Text type="supporting" color="secondary">
+ The audit is right that the shape is a no-op and wrong that it is a
+ defect. The lint rule needs the exemption written in from the start:{' '}
+ <code>none</code> is the only value of{' '}
+ <code>transitionProperty</code> that legitimately appears without a
+ duration.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Why the shape is still worth linting"
+ question="Both panes declare a transition. Only one of them animates. Which is which, at a glance in review?"
+ actions={<Badge variant="neutral" label="Hover the rows" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label:
+ 'transitionProperty, no duration — reads like motion, does nothing',
+ content: <Rows variant="noop" />,
+ },
+ {
+ tone: 'after',
+ label: 'The same rule with a duration and a curve',
+ content: <Rows variant="tint" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting" color="secondary">
+ This is the argument for the rule even though the package has one
+ instance and it is exempt: the failure is invisible in review. A
+ reviewer sees the word <code>transition</code> and moves on, and the
+ component ships with a state change that snaps.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title={`${AUDIT_COUNTS.durationWithoutCurve} durations with no declared curve`}
+ question="A duration with no timing function silently gets the CSS default, which is ease — not --ease-standard. How different are they?"
+ badges={
+ <Badge variant="warning" label="The largest structural finding" />
+ }>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'ease — what these sites actually run',
+ content: (
+ <Runner
+ durationToken="--duration-reveal"
+ easeToken="--ease-state"
+ />
+ ),
+ },
+ {
+ tone: 'after',
+ label: '--ease-standard — the curve core ships',
+ content: (
+ <Runner
+ durationToken="--duration-reveal"
+ easeToken="--ease-standard-today"
+ />
+ ),
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting">
+ <code>ease</code> is <code>cubic-bezier(0.25, 0.1, 0.25, 1)</code> —
+ a gentle symmetrical curve. <code>--ease-standard</code> is{' '}
+ <code>cubic-bezier(0.24, 1, 0.4, 1)</code>, which leaves immediately
+ and decelerates hard. Every site below is running the first one
+ while its neighbours run the second, and nobody wrote that decision
+ down.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Site</TableHeaderCell>
+ <TableHeaderCell>Declaration</TableHeaderCell>
+ <TableHeaderCell>Reading</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {DURATION_WITHOUT_CURVE.map(site => {
+ const instant = site.decl?.includes('0.01s') === true;
+ return (
+ <TableRow key={`${site.file}:${site.line}`}>
+ <TableCell>
+ <Text
+ {...stylex.props(
+ sx.mono,
+ )}>{`${site.file}:${site.line}`}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {site.decl}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {instant
+ ? 'Reduced-motion escape — the curve is irrelevant at 10ms'
+ : 'Substantive: a real duration silently taking the CSS default'}
+ </Text>
+ </TableCell>
+ </TableRow>
+ );
+ })}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting">
+ {SUBSTANTIVE_DWC.length} of the {AUDIT_COUNTS.durationWithoutCurve}{' '}
+ are substantive — a real duration silently taking <code>ease</code>{' '}
+ — across {SUBSTANTIVE_DWC_COMPONENTS.join(', ')}. Only{' '}
+ {INSTANT_DWC.length} is the <code>0.01s</code> escape, where having
+ no curve is the right answer. The brief underplays this finding, and
+ the figure has already moved twice as the scanner improved: read it
+ out of the audit rather than quoting it.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="The drawer exit, cut short"
+ question="Slide 410ms, unmount at 250ms. Drag either slider: at what point does an exit stop being an exit?"
+ badges={<Badge variant="error" label="Confirmed in lab" />}>
+ <DemoBody>
+ <Text type="supporting">
+ <strong>The brief is right, to the millisecond.</strong>{' '}
+ <code>lab/Drawer/Drawer.tsx:459</code> hardcodes a <code>250</code>
+ ms close timer, while <code>:157</code> and <code>:219</code> set
+ the panel and scrim transitions to <code>--duration-medium</code> —
+ 410ms. The dialog is closed at 61% of its own travel, so the last
+ 160ms of the slide never renders.
+ </Text>
+ <Text type="supporting" color="secondary">
+ The reduced-motion branch beside it is the tell: the same expression
+ picks <code>10</code>ms when the user asks for less motion, which
+ means someone thought carefully about the timer and still had to
+ restate the duration by hand. Nothing in either package derives a
+ timer from its transition; MobileNav is the only component that even
+ tries, and it does it by reading <code>getComputedStyle</code>. That
+ is the argument for the JS token mirror in one file.
+ </Text>
+ </DemoBody>
+ <DemoBody>
+ <DrawerCutDemo />
+ </DemoBody>
+ <DemoBody>
+ <CodeBlock
+ language="tsx"
+ title="The class of bug, and the two ways out of it"
+ code={TIMER_FIX}
+ hasCopyButton
+ maxHeight={420}
+ />
+ <Text type="supporting" color="secondary">
+ The bug is not the number 250. It is that two numbers have to agree
+ and only one of them is a token: retune{' '}
+ <code>--duration-overlay</code> and the timer keeps its old value,
+ so the cut appears in a diff that never touched the drawer.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="transition: all"
+ question={`${TRANSITION_ALL.length} sites. Is a rule with nothing to fix worth writing?`}
+ badges={
+ <Badge variant="success" label={`${TRANSITION_ALL.length} today`} />
+ }>
+ <DemoBody>
+ <Text type="supporting">
+ Yes, and it is the cheapest rule in the set.{' '}
+ <code>transition: all</code> animates every property that ever
+ changes, including layout properties nobody intended to animate, and
+ it arrives in a codebase one careless line at a time. Core is clean
+ today; the rule keeps it clean and costs one regex.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <VStack gap={3}>
+ <Heading level={2}>
+ The count moved twice, and the brief was right
+ </Heading>
+ <Text color="secondary">
+ Every structural number on this page is a scanner output, so what the
+ scanner can see decides what gets scheduled. This section started as a
+ grep run against a generated count that looked too small; the
+ generator has since been fixed twice, and criterion 12&rsquo;s
+ caseload went from something smaller than the brief&rsquo;s estimate
+ to something larger than it.
+ </Text>
+ <Grid columns={{minWidth: 300}} gap={3}>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">A scanner sees shape, not intent</Text>
+ <Text type="supporting" color="secondary">
+ The one no-op it reports is the Lightbox drag opt-out above:
+ correct code with the shape of a defect. Every rule the lint
+ gains has to carry its exemptions from the start, or the first
+ thing it produces is work that ends in &ldquo;working as
+ intended&rdquo;.
+ </Text>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">A grep sees less than a scanner</Text>
+ <Text type="supporting" color="secondary">
+ {SINGLE_PROPERTY_TRANSFORMS} of the{' '}
+ {TRANSFORM_TRANSITIONS.length} transform transitions declare{' '}
+ <code>transform</code> on its own.{' '}
+ {MULTI_PROPERTY_TRANSFORMS.length} declare it inside a longer
+ property list, where a search for{' '}
+ <code>transitionProperty: &lsquo;transform&rsquo;</code> never
+ finds them — which is how one repository yields three different
+ counts depending on who counted.
+ </Text>
+ </VStack>
+ </Card>
+ </Grid>
+ <Text color="secondary">
+ The multi-property declarations are the interesting half: criterion 12
+ findings like the rest, and {LAYOUT_MIXED_TRANSFORMS.length} of them
+ criterion 6 findings as well, because they animate a layout property
+ in the same breath as a compositor one.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Site</TableHeaderCell>
+ <TableHeaderCell>Declaration</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {MULTI_PROPERTY_TRANSFORMS.map(site => (
+ <TableRow key={`${site.file}:${site.line}`}>
+ <TableCell>
+ <Text
+ {...stylex.props(
+ sx.mono,
+ )}>{`${site.file}:${site.line}`}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {site.decl}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <HStack gap={2} wrap="wrap">
+ <Badge
+ variant="success"
+ label={`Audit, fixed: ${AUDIT_COUNTS.transformTransitions} sites / ${AUDIT_COUNTS.transformTransitionComponents} components`}
+ />
+ <Badge variant="neutral" label="Brief: 20+ components" />
+ </HStack>
+ <Text type="supporting" color="secondary">
+ This page found the discrepancy by grepping when the generated number
+ looked too small, and the generator has since been fixed twice: once
+ so a value that wraps onto its own line is still read, and once so a
+ rule containing nested per-state objects is still scanned. Both bugs
+ hid matches, and both made the brief look wrong when it was right. The
+ lasting fix is a parser rather than a regex — a StyleX rule is a
+ TypeScript object literal and can be read as one — but the habit
+ matters more than the tool: when a generated count disagrees with
+ someone who has read the code, check the generator first.
+ </Text>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>What would have caught each of these</Heading>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Finding</TableHeaderCell>
+ <TableHeaderCell>Lint rule</TableHeaderCell>
+ <TableHeaderCell>Caseload today</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {LINT_MAP.map(row => (
+ <TableRow key={row.finding}>
+ <TableCell>
+ <Text weight="semibold">{row.finding}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting">{row.rule}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.status}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ Five of the six are mechanical. The sixth — a timer standing in for a
+ transition — is the only one that needs a heuristic, and it is the
+ only one of the six that describes a bug a user would notice.
+ </Text>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/exit-gap.tsx b/apps/sandbox/src/motion/pages/exit-gap.tsx
new file mode 100644
index 0000000000..efe252f864
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/exit-gap.tsx
@@ -0,0 +1,329 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input LabDemos rigs, published guidance, the lab store
+ * @output The exit-gap argument, with both documents on screen
+ * @position /motion/exit-gap
+ *
+ * The brief calls this the single highest-leverage fix in the audit. It is
+ * also the one place where the thing being called a defect is the published
+ * guidance, so the page leads with that rather than burying it.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {LabPage} from '../PageFrame';
+import {ComparePanes, DemoBody, DemoCard, TokenSlider} from '../LabPrimitives';
+import {DialogRig, LayerRig, NativePopoverProbe} from '../LabDemos';
+import {GUIDANCE_CONFLICTS} from '../publishedGuidance';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ quote: {
+ borderInlineStart: '2px solid var(--color-border)',
+ paddingInlineStart: '12px',
+ maxWidth: '62ch',
+ },
+});
+
+/** The eleven, as the brief lists them, plus the dialog family. */
+const LAYER_CONSUMERS = [
+ 'Tooltip',
+ 'HoverCard',
+ 'Popover',
+ 'DropdownMenu',
+ 'ContextMenu',
+ 'Selector',
+ 'ComplexSelector',
+ 'PowerSearch',
+ 'Typeahead',
+ 'MoreMenu',
+ 'Breadcrumbs overflow',
+];
+
+const RIGS = [
+ {
+ title: 'Tooltip',
+ subtitle: 'useLayer · highest-frequency surface in the system',
+ triggerLabel: 'Hover me',
+ trigger: 'hover' as const,
+ origin: 'top center',
+ question:
+ 'The published page names tooltips specifically as a surface that may vanish. Does the exit earn its 175ms here, on something seen hundreds of times a day?',
+ },
+ {
+ title: 'HoverCard',
+ subtitle: 'useLayer · the most visible instance of the gap',
+ triggerLabel: 'Hover a name',
+ trigger: 'hover' as const,
+ origin: 'top left',
+ question:
+ 'A larger surface travelling the same distance. Judge the scale-from value here rather than on Tooltip — 0.96 reads differently at size.',
+ },
+ {
+ title: 'Popover',
+ subtitle: 'useLayer',
+ triggerLabel: 'Click me',
+ trigger: 'click' as const,
+ origin: 'top left',
+ question:
+ 'Click twice quickly. The exit has to retarget rather than restart, or rapid dismissal looks broken.',
+ },
+ {
+ title: 'DropdownMenu',
+ subtitle: 'useLayer · submenus too',
+ triggerLabel: 'Open menu',
+ trigger: 'click' as const,
+ origin: 'top left',
+ question:
+ 'A menu snapping shut is the case people notice. Does the exit help, or does it just delay the next click?',
+ },
+];
+
+export default function ExitGapPage() {
+ const conflict = GUIDANCE_CONFLICTS.find(c => c.id === 'exit-optional');
+ const blocking = GUIDANCE_CONFLICTS.find(c => c.id === 'blocking');
+
+ return (
+ <LabPage
+ title="The exit gap"
+ intro="Eleven components animate in and vanish out — every surface built on useLayer, plus Dialog, AlertDialog and CommandPalette. One change to layerAnimations and useLayer would give all eleven a dismissal animation, which is why the brief calls it the highest-leverage fix in the audit."
+ decides="Whether presence surfaces should animate out at all, and what enter and exit cost."
+ badges={
+ <Badge variant="warning" label="conflicts with the published page" />
+ }>
+ {conflict != null && (
+ <Banner
+ status="warning"
+ title="This is not drift — it is the published guidance, correctly followed"
+ description={
+ <VStack gap={2}>
+ <Text {...stylex.props(sx.quote)}>
+ <em>&ldquo;{conflict.published}&rdquo;</em>
+ </Text>
+ <Text>
+ {conflict.reading} Before any of this is scheduled, decide which
+ document is right. If the proposal wins, the rewrite of that
+ paragraph ships in the same stack as the{' '}
+ <code>layerAnimations</code> change — otherwise the rubric
+ starts failing components for doing exactly what the docs still
+ instruct.
+ </Text>
+ </VStack>
+ }
+ endContent={<Link href="/motion/published">All conflicts</Link>}
+ />
+ )}
+
+ <DemoCard
+ title="Tune the presence budget"
+ question="These two values drive every pane on this page, and every layer demo in the lab.">
+ <DemoBody>
+ <TokenSlider token="--duration-enter" label="enter" max={600} />
+ <TokenSlider token="--duration-exit" label="exit" max={600} />
+ <TokenSlider token="--duration-overlay" label="overlay" max={900} />
+ <Text type="supporting" color="secondary">
+ Exit is deliberately shorter than enter, because old content should
+ leave faster than new content arrives. Drag them equal and a
+ dismissal starts to feel sticky.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ {RIGS.map(rig => (
+ <DemoCard
+ key={rig.title}
+ title={rig.title}
+ question={rig.question}
+ badges={<Badge label={rig.subtitle} />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — animates in, vanishes out',
+ content: (
+ <LayerRig
+ mode="before"
+ label={rig.title}
+ triggerLabel={rig.triggerLabel}
+ trigger={rig.trigger}
+ origin={rig.origin}
+ />
+ ),
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — the exit retraces the entry',
+ content: (
+ <LayerRig
+ mode="after"
+ label={rig.title}
+ triggerLabel={rig.triggerLabel}
+ trigger={rig.trigger}
+ origin={rig.origin}
+ />
+ ),
+ },
+ ]}
+ />
+ </DemoCard>
+ ))}
+
+ <DemoCard
+ title="Dialog, AlertDialog, CommandPalette"
+ question="Two separate bugs in one surface: the panel has no exit, and the backdrop has no transition at all. Watch the focus ring on the trigger."
+ badges={<Badge variant="error" label="focus races the exit" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label:
+ 'Today — no exit, scrim hard-cuts, focus returns immediately',
+ content: <DialogRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — panel and scrim both exit, focus waits',
+ content: <DialogRig mode="after" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting" color="secondary">
+ In the left pane the focus ring lights the instant the dialog
+ closes, while the dialog is still on screen. With a real exit
+ animation that means focus moves — and the page may scroll —
+ mid-animation. The brief lists this as a risk; here it is a thing
+ you can watch, and it has to be settled before the Dialog work
+ starts rather than after.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="The technique, running natively in this browser"
+ question="Is the platform enough, or does the shared primitive need a JS fallback? This card answers it for real — nothing here is simulated.">
+ <DemoBody>
+ <NativePopoverProbe />
+ </DemoBody>
+ </DemoCard>
+
+ <VStack gap={3}>
+ <Heading level={2}>What one change buys</Heading>
+ <Card padding={4}>
+ <VStack gap={2}>
+ <Text>
+ Every component below is a <code>useLayer</code> consumer, so all
+ of them inherit a dismissal animation from a single definition.
+ That is the leverage — and it is also the risk, because it is one
+ change to the code path that owns dismissal.
+ </Text>
+ <HStack gap={1} wrap="wrap">
+ {LAYER_CONSUMERS.map(name => (
+ <Badge key={name} label={name} />
+ ))}
+ </HStack>
+ </VStack>
+ </Card>
+ <CodeBlock
+ language="css"
+ title="layerAnimations — one definition, eleven consumers"
+ hasCopyButton
+ code={`.layer {
+ opacity: 0;
+ transform: scale(0.96) translateY(-4px);
+ transform-origin: var(--layer-origin);
+ transition:
+ opacity var(--duration-exit) var(--ease-exit),
+ transform var(--duration-exit) var(--ease-exit),
+ display var(--duration-exit) allow-discrete,
+ overlay var(--duration-exit) allow-discrete;
+}
+
+.layer:popover-open {
+ opacity: 1;
+ transform: scale(1) translateY(0);
+ transition:
+ opacity var(--duration-enter) var(--ease-entry),
+ transform var(--duration-enter) var(--ease-entry),
+ display var(--duration-enter) allow-discrete,
+ overlay var(--duration-enter) allow-discrete;
+}
+
+@starting-style {
+ .layer:popover-open { opacity: 0; transform: scale(0.96) translateY(-4px); }
+}`}
+ />
+ <CodeBlock
+ language="tsx"
+ title="useLayer — await the exit instead of hiding synchronously"
+ hasCopyButton
+ code={`- setOpen(false); // element gone this frame
++ setClosing(true); // stops accepting input immediately
++ await Promise.all(
++ el.getAnimations().map(a => a.finished),
++ );
++ setOpen(false); // focus return happens here`}
+ />
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>What this work has to be careful about</Heading>
+ <Grid columns={{minWidth: 300}} gap={3}>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">Dismissal is load-bearing</Text>
+ <Text type="supporting" color="secondary">
+ Layer dismissal has its own invariants test for good reason.
+ Keeping an element alive through its exit doubles the state
+ matrix for focus return, outside-press and escape handling — and
+ every one of those has to be tested against an element that is
+ visible but already closing.
+ </Text>
+ </VStack>
+ </Card>
+ {blocking != null && (
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">
+ The published page already warns about this
+ </Text>
+ <Text type="supporting" color="secondary">
+ &ldquo;{blocking.published}&rdquo; The answer has to be that
+ the surface stops accepting input the moment dismissal starts,
+ not when the animation ends. Write that into the
+ primitive&rsquo;s contract rather than leaving it to each
+ consumer.
+ </Text>
+ </VStack>
+ </Card>
+ )}
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">
+ Motion is already fighting the automated gates
+ </Text>
+ <Text type="supporting" color="secondary">
+ Two fixes landed this month to stop animation interfering with
+ the accessibility audit and the visual-regression capture. More
+ motion means more of this, and there is no documented policy for
+ it. The lab&rsquo;s reduced-motion switch doubles as the freeze
+ mode a capture needs.
+ </Text>
+ </VStack>
+ </Card>
+ </Grid>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/export.tsx b/apps/sandbox/src/motion/pages/export.tsx
new file mode 100644
index 0000000000..230d399268
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/export.tsx
@@ -0,0 +1,526 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input Everything the lab has been tuned to this session
+ * @output The two artefacts the foundation milestone ships, plus the lint rule
+ * @position /motion/export
+ *
+ * The only page that decides nothing. It emits: the token block in the shape
+ * the proposal actually lands in — an addition to two objects core already
+ * defines through StyleX, not a `:root` block, because `:root` is not how this
+ * codebase defines tokens — the JS mirror, and the lint entries that would
+ * keep both honest.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {EmptyState} from '@astryxdesign/core/EmptyState';
+import {Link} from '@astryxdesign/core/Link';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {LabPage} from '../PageFrame';
+import {parseMs, useMotionLab} from '../MotionLabStore';
+import {
+ ALL_TUNABLE_TOKENS,
+ CURRENT_EASE,
+ DEFAULT_TOKEN_VALUES,
+ PRIMITIVE_DURATIONS,
+ SEMANTIC_DURATIONS,
+ SEMANTIC_EASES,
+ SPRINGS,
+ STAGGERS,
+} from '../motionTokens';
+import {isNamedCurve, parseBezier} from '../spring';
+import {AUDIT_COUNTS, LITERAL_VALUES} from '../__generated__/motionAudit';
+
+const sx = stylex.create({
+ mono: {fontFamily: 'var(--font-family-code)'},
+ prose: {maxWidth: '72ch'},
+});
+
+const PRIMITIVE_MS = new Map(PRIMITIVE_DURATIONS);
+
+/** The brief's budget for the sweep, against the measured total. */
+const BRIEF_HARDCODED_BUDGET = 28;
+
+type CodeLine = {readonly text: string; readonly added?: boolean};
+
+function render(lines: ReadonlyArray<CodeLine>): {
+ code: string;
+ highlightLines: number[];
+} {
+ return {
+ code: lines.map(line => line.text).join('\n'),
+ highlightLines: lines
+ .map((line, i) => (line.added === true ? i + 1 : 0))
+ .filter(n => n > 0),
+ };
+}
+
+/**
+ * The token block. Semantic durations emit as `var(--primitive)` — the pattern
+ * `typeScaleDefaults` already uses for type — so a theme retunes both layers at
+ * once. A value tuned away from its primitive cannot alias, and says so.
+ */
+function tokenBlockLines(
+ rawToken: (token: string) => string,
+): ReadonlyArray<CodeLine> {
+ const durationLines = SEMANTIC_DURATIONS.map(duration => {
+ const ms = parseMs(rawToken(duration.name));
+ const primitiveMs =
+ duration.primitive != null
+ ? PRIMITIVE_MS.get(duration.primitive)
+ : undefined;
+ if (primitiveMs != null && primitiveMs === ms) {
+ return {
+ text: ` '${duration.name}': 'var(${duration.primitive})',`,
+ added: true,
+ };
+ }
+ const drift =
+ primitiveMs != null
+ ? ` // tuned off ${duration.primitive} (${primitiveMs}ms) — move the primitive or accept the fork`
+ : ' // no primitive: the reduced-motion escape';
+ return {text: ` '${duration.name}': '${ms}ms',${drift}`, added: true};
+ });
+
+ return [
+ {text: '// @astryxdesign/core/src/theme/tokens.stylex.ts'},
+ {
+ text: '// Additions only. The nine primitives and --ease-standard do not move.',
+ },
+ {text: ''},
+ {text: 'export const easeDefaults = {'},
+ {
+ text: ` '${CURRENT_EASE.name}': '${CURRENT_EASE.value}', // kept; deprecated in docs, not in code`,
+ },
+ ...SEMANTIC_EASES.map(ease => ({
+ text: ` '${ease.name}': '${rawToken(ease.name)}',`,
+ added: true,
+ })),
+ {text: '} as const;'},
+ {text: ''},
+ {text: 'export const easeVars = stylex.defineVars(easeDefaults);'},
+ {text: ''},
+ {text: 'export const durationDefaults = {'},
+ ...PRIMITIVE_DURATIONS.map(([name, ms]) => ({
+ text: ` '${name}': '${ms}ms',`,
+ })),
+ {text: ''},
+ {
+ text: ' // Semantic layer. Aliased, so the motion scale a theme sets still owns',
+ },
+ {text: ' // these — the same shape typeScaleDefaults uses for type.'},
+ ...durationLines,
+ {text: '} as const;'},
+ {text: ''},
+ {text: 'export const durationVars = stylex.defineVars(durationDefaults);'},
+ {text: ''},
+ {
+ text: '// Stagger is a delay between siblings, not a duration, so it gets its own',
+ },
+ {text: '// group rather than widening DurationVarName.'},
+ {text: 'export const staggerDefaults = {', added: true},
+ ...STAGGERS.map(([name]) => ({
+ text: ` '${name}': '${parseMs(rawToken(name))}ms',`,
+ added: true,
+ })),
+ {text: '} as const;', added: true},
+ {text: '', added: true},
+ {
+ text: 'export const staggerVars = stylex.defineVars(staggerDefaults);',
+ added: true,
+ },
+ ];
+}
+
+/** Seconds and numbers — the shape Motion, WAAPI and canvas take. */
+function emitMirror(
+ rawToken: (token: string) => string,
+ springs: Readonly<Record<string, {duration: number; bounce: number}>>,
+): string {
+ const short = (name: string) =>
+ name.replace(/^--(duration|ease|stagger)-/, '');
+ const seconds = (name: string) =>
+ Number((parseMs(rawToken(name)) / 1000).toFixed(3));
+ const curve = (name: string) => {
+ const value = rawToken(name);
+ return isNamedCurve(value)
+ ? JSON.stringify(value)
+ : `[${parseBezier(value).join(', ')}]`;
+ };
+
+ return `// @generated from the Astryx theme by scripts/generate-motion-mirror.mjs.
+// Values are resolved through resolveThemeTokens, so a theme that retunes the
+// motion scale retunes this file too.
+
+export const duration = {
+${SEMANTIC_DURATIONS.map(d => ` ${short(d.name)}: ${seconds(d.name)},`).join('\n')}
+} as const;
+
+export const ease = {
+${SEMANTIC_EASES.map(e => ` ${short(e.name)}: ${curve(e.name)},`).join('\n')}
+} as const;
+
+export const stagger = {
+${STAGGERS.map(([name]) => ` ${short(name)}: ${seconds(name)},`).join('\n')}
+} as const;
+
+/** No CSS form, so authored here rather than mirrored. */
+export const spring = {
+${SPRINGS.map(
+ s =>
+ ` ${s.name}: {duration: ${springs[s.name].duration}, bounce: ${springs[s.name].bounce}},`,
+).join('\n')}
+} as const;`;
+}
+
+const LINT_CODE = `// internal/eslint-plugin-xds/index.js — rule: xds/no-hardcoded-styles
+//
+// STYLE_PROPERTIES already covers type, spacing, radius and colour. It has no
+// motion entry, which is why ${AUDIT_COUNTS.hardcodedTotal} hardcoded duration and easing values
+// pass lint today. Six additions, in the shape the map already uses:
+
+const STYLE_PROPERTIES = {
+ // ...fontSize, padding, borderRadius, color — unchanged
+
+ transitionDuration: {
+ pattern: /^['"]?[\\d.]+m?s['"]?$/,
+ tokenVar: 'durationVars',
+ message: 'Use a duration token: var(--duration-*)',
+ examples: ["durationVars['--duration-enter']"],
+ },
+ animationDuration: {
+ pattern: /^['"]?[\\d.]+m?s['"]?$/,
+ tokenVar: 'durationVars',
+ message: 'Use a duration token: var(--duration-*)',
+ examples: ["durationVars['--duration-continuous']"],
+ },
+ transitionDelay: {
+ pattern: /^['"]?[\\d.]+m?s['"]?$/,
+ tokenVar: 'staggerVars',
+ message: 'Use var(--stagger-*) for a group offset, var(--duration-*) otherwise',
+ examples: ["staggerVars['--stagger-base']"],
+ },
+ animationDelay: {
+ pattern: /^['"]?[\\d.]+m?s['"]?$/,
+ tokenVar: 'staggerVars',
+ message: 'Use var(--stagger-*) for a group offset, var(--duration-*) otherwise',
+ examples: ["staggerVars['--stagger-tight']"],
+ },
+ transitionTimingFunction: {
+ pattern: /^['"]?(cubic-bezier\\([^)]*\\)|linear|ease(-in|-out|-in-out)?|steps\\([^)]*\\))['"]?$/,
+ tokenVar: 'easeVars',
+ message: 'Use an easing token: var(--ease-*)',
+ examples: ["easeVars['--ease-entry']", "easeVars['--ease-exit']"],
+ },
+ animationTimingFunction: {
+ pattern: /^['"]?(cubic-bezier\\([^)]*\\)|linear|ease(-in|-out|-in-out)?|steps\\([^)]*\\))['"]?$/,
+ tokenVar: 'easeVars',
+ message: 'Use an easing token: var(--ease-*)',
+ examples: ["easeVars['--ease-linear']"],
+ },
+};
+
+// One carve-out is needed. SKIP_VALUES lets '0', 'none' and 'auto' through for
+// every property, which is right for padding and wrong for motion: it is what
+// hides transitionProperty: 'none'. The structural rules below need to see it.`;
+
+const STRUCTURAL_CODE = `// A second visitor, because these are properties of the style object rather
+// than of one value — the existing rule only ever looks at a single literal.
+
+'motion/require-duration-with-property': {
+ // transitionProperty with no duration in the same object inherits 0s and
+ // animates nothing. Catches: ${AUDIT_COUNTS.noopTransitions} today.
+},
+'motion/require-curve-with-duration': {
+ // A duration with no timing function silently gets the CSS default (ease),
+ // which is a decision nobody made. Catches: ${AUDIT_COUNTS.durationWithoutCurve} today.
+},
+'motion/no-transition-all': {
+ // transitionProperty: 'all' animates layout and paint properties nobody
+ // intended. Catches: ${AUDIT_COUNTS.transitionAll} today — a ratchet, not a cleanup.
+},`;
+
+const LINT_RULES: ReadonlyArray<{
+ readonly rule: string;
+ readonly allows: string;
+ readonly catches: string;
+ readonly kind: string;
+}> = [
+ {
+ rule: 'transitionDuration / animationDuration',
+ allows: 'var(--duration-*)',
+ catches: `${AUDIT_COUNTS.hardcodedDuration} hardcoded durations`,
+ kind: 'value',
+ },
+ {
+ rule: 'transitionDelay / animationDelay',
+ allows: 'var(--stagger-*), var(--duration-*)',
+ catches: 'included in the count above',
+ kind: 'value',
+ },
+ {
+ rule: 'transitionTimingFunction / animationTimingFunction',
+ allows: 'var(--ease-*)',
+ catches: `${AUDIT_COUNTS.hardcodedEasing} hardcoded curves`,
+ kind: 'value',
+ },
+ {
+ rule: 'motion/require-duration-with-property',
+ allows: 'a duration beside every transitionProperty',
+ catches: `${AUDIT_COUNTS.noopTransitions} no-op transition`,
+ kind: 'structural',
+ },
+ {
+ rule: 'motion/require-curve-with-duration',
+ allows: 'a curve beside every duration',
+ catches: `${AUDIT_COUNTS.durationWithoutCurve} durations with no declared curve`,
+ kind: 'structural',
+ },
+ {
+ rule: 'motion/no-transition-all',
+ allows: 'named properties only',
+ catches: `${AUDIT_COUNTS.transitionAll} today — prevents regressions`,
+ kind: 'structural',
+ },
+];
+
+export default function MotionExportPage() {
+ const {rawToken, springs, dirtyTokens} = useMotionLab();
+ const {code: tokenCode, highlightLines} = render(tokenBlockLines(rawToken));
+
+ const tokenDiff = ALL_TUNABLE_TOKENS.filter(
+ name => rawToken(name) !== DEFAULT_TOKEN_VALUES[name],
+ ).map(name => ({
+ name,
+ proposed: DEFAULT_TOKEN_VALUES[name],
+ tuned: rawToken(name),
+ }));
+
+ const springDiff = SPRINGS.flatMap(spec => {
+ const tuned = springs[spec.name];
+ const rows: Array<{name: string; proposed: string; tuned: string}> = [];
+ if (tuned.duration !== spec.duration) {
+ rows.push({
+ name: `spring.${spec.name}.duration`,
+ proposed: `${spec.duration}s`,
+ tuned: `${tuned.duration}s`,
+ });
+ }
+ if (tuned.bounce !== spec.bounce) {
+ rows.push({
+ name: `spring.${spec.name}.bounce`,
+ proposed: String(spec.bounce),
+ tuned: String(tuned.bounce),
+ });
+ }
+ return rows;
+ });
+
+ const changes = [...tokenDiff, ...springDiff];
+ const instantCount =
+ LITERAL_VALUES.find(([value]) => value === '0.01s')?.[1] ?? 0;
+
+ return (
+ <LabPage
+ title="Export tuning"
+ intro="Everything tuned in this session, as the two artefacts the foundation milestone ships: the token block and the JS mirror. Plus the lint entries that stop the next one from arriving."
+ decides="Nothing — it emits whatever the rest of the lab has been tuned to."
+ badges={
+ <Badge
+ variant={changes.length > 0 ? 'warning' : 'neutral'}
+ label={
+ changes.length > 0
+ ? `${changes.length} changed`
+ : 'proposal defaults'
+ }
+ />
+ }>
+ <VStack gap={3}>
+ <Heading level={2}>What moved</Heading>
+ {changes.length === 0 ? (
+ <Card padding={4}>
+ <EmptyState
+ title="Nothing has been tuned this session"
+ description="Every value below is the proposal exactly as authored. Change a curve on the tokens page or a spring on the springs page and the differences appear here."
+ />
+ </Card>
+ ) : (
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Token</TableHeaderCell>
+ <TableHeaderCell>Proposal</TableHeaderCell>
+ <TableHeaderCell>Tuned</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {changes.map(row => (
+ <TableRow key={row.name}>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>{row.name}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {row.proposed}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} weight="semibold">
+ {row.tuned}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ )}
+ {dirtyTokens.length > 0 && (
+ <Text type="supporting" color="secondary">
+ The rail counts {dirtyTokens.length} tuned token(s); springs are
+ counted separately because they are not custom properties.
+ </Text>
+ )}
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>The token block</Heading>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ Highlighted lines are the addition. Core defines tokens through{' '}
+ <code>stylex.defineVars</code>, so this is a diff against two existing
+ objects rather than a <code>:root</code> block — <code>:root</code>{' '}
+ would bypass the theme system entirely and could not be retuned by a
+ theme. Semantic durations emit as <code>var(--primitive)</code>, which
+ is the shape <code>typeScaleDefaults</code> already uses for type, so
+ a theme that moves the motion scale moves these with it.
+ </Text>
+ <CodeBlock
+ language="ts"
+ title="@astryxdesign/core/src/theme/tokens.stylex.ts"
+ hasCopyButton
+ hasLineNumbers
+ highlightLines={highlightLines}
+ code={tokenCode}
+ />
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>The JS mirror</Heading>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ Same values, in the shape a JS animation takes. Generated from the
+ theme in the same build step that emits the CSS — see{' '}
+ <Link href="/motion/js-mirror">JS token mirror</Link> for why it
+ cannot be a handwritten constants file.
+ </Text>
+ <CodeBlock
+ language="ts"
+ title="@astryxdesign/core/motion — generated"
+ hasCopyButton
+ code={emitMirror(rawToken, springs)}
+ />
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>The lint rule</Heading>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ The token linter already polices type, spacing, radius and colour, and
+ simply has no entry for duration or easing. That is the whole reason{' '}
+ {AUDIT_COUNTS.hardcodedTotal} values are hardcoded: nothing ever told
+ anyone not to. Six property entries drop straight into the existing
+ pattern map — three rules once the duration, delay and timing-function
+ pairs are grouped. The other three are structural: they are properties
+ of the whole style object, and the current rule only ever looks at one
+ literal at a time.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Rule</TableHeaderCell>
+ <TableHeaderCell>Allows</TableHeaderCell>
+ <TableHeaderCell>Measured catch</TableHeaderCell>
+ <TableHeaderCell>Kind</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {LINT_RULES.map(rule => (
+ <TableRow key={rule.rule}>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>{rule.rule}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {rule.allows}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text>{rule.catches}</Text>
+ </TableCell>
+ <TableCell>
+ <Badge
+ variant={rule.kind === 'structural' ? 'info' : 'neutral'}
+ label={rule.kind}
+ />
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <CodeBlock
+ language="js"
+ title="internal/eslint-plugin-xds/index.js — value entries"
+ hasCopyButton
+ isWrapped
+ code={LINT_CODE}
+ />
+ <CodeBlock
+ language="js"
+ title="The structural companions"
+ hasCopyButton
+ code={STRUCTURAL_CODE}
+ />
+ </VStack>
+
+ <Banner
+ status="warning"
+ title={`The sweep is ${AUDIT_COUNTS.hardcodedTotal} sites, not ${BRIEF_HARDCODED_BUDGET}`}
+ description={
+ <Text>
+ The brief budgets {BRIEF_HARDCODED_BUDGET} hardcoded values; the
+ audit measures {AUDIT_COUNTS.hardcodedTotal} (
+ {AUDIT_COUNTS.hardcodedDuration} durations,{' '}
+ {AUDIT_COUNTS.hardcodedEasing} curves). Roughly a quarter of them —{' '}
+ {instantCount} of {AUDIT_COUNTS.hardcodedTotal},{' '}
+ {Math.round((instantCount / AUDIT_COUNTS.hardcodedTotal) * 100)}% —
+ are the <code>0.01s</code> reduced-motion idiom in BottomSheet,
+ DateInput and MobileNav, and those cannot be swept until{' '}
+ <code>--duration-instant</code> is settled at 0 or 0.01ms: a zero
+ duration fires no <code>transitionend</code>, and code sequences off
+ that event. Turning the rule on before that decision lands means{' '}
+ {instantCount} suppressions in the first diff. See{' '}
+ <Link href="/motion/reduced-motion">Reduced motion</Link> and{' '}
+ <Link href="/motion/violations">Hardcoded values</Link>.
+ </Text>
+ }
+ />
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/js-mirror.tsx b/apps/sandbox/src/motion/pages/js-mirror.tsx
new file mode 100644
index 0000000000..6a0345bf12
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/js-mirror.tsx
@@ -0,0 +1,545 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input The generated audit, the lab store, the token data
+ * @output The case for a JS mirror, and the module it would emit
+ * @position /motion/js-mirror
+ *
+ * A CSS custom property is readable by exactly one consumer: CSS. Every
+ * animation library, the Web Animations API, and anything drawing to a canvas
+ * takes numbers. Motion wants seconds as a number and easing as four numbers;
+ * it cannot resolve `var(--duration-fast)`. The mirror exists so that the
+ * value in the stylesheet and the value in the chart are the same value.
+ *
+ * The chart demo draws to a real canvas rather than faking one with divs,
+ * because the whole argument is that canvas sits outside the token system.
+ */
+
+import {useCallback, useEffect, useRef} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {LabPage} from '../PageFrame';
+import {ComparePanes, DemoBody, DemoCard, useLoop} from '../LabPrimitives';
+import {parseMs, useMotionLab} from '../MotionLabStore';
+import {
+ SEMANTIC_DURATIONS,
+ SEMANTIC_EASES,
+ SPRINGS,
+ STAGGERS,
+} from '../motionTokens';
+import {bezierAt, isNamedCurve, parseBezier} from '../spring';
+import {AUDIT_COUNTS, TIMEOUT_LITERALS} from '../__generated__/motionAudit';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ prose: {maxWidth: '72ch'},
+ mono: {fontFamily: 'var(--font-family-code)'},
+ canvas: {
+ display: 'block',
+ width: '100%',
+ height: '132px',
+ // Canvas has no access to a custom property, so the demo parks the one
+ // colour it needs on the element and reads it back with getComputedStyle.
+ color: 'var(--color-brand)',
+ },
+});
+
+const CHART_HEIGHT = 132;
+
+/** Fixed data, so both panes cycle the same values and the eye can compare. */
+const DATASETS: ReadonlyArray<ReadonlyArray<number>> = [
+ [0.42, 0.66, 0.28, 0.81, 0.55, 0.35, 0.72],
+ [0.68, 0.31, 0.74, 0.44, 0.86, 0.52, 0.29],
+ [0.24, 0.58, 0.9, 0.36, 0.61, 0.79, 0.47],
+];
+
+/** `--duration-*` in seconds, `--ease-*` as points, the shape a library takes. */
+function emitMirror(
+ rawToken: (token: string) => string,
+ springs: Readonly<Record<string, {duration: number; bounce: number}>>,
+): string {
+ const short = (name: string) =>
+ name.replace(/^--(duration|ease|stagger)-/, '');
+ const seconds = (name: string) =>
+ Number((parseMs(rawToken(name)) / 1000).toFixed(3));
+ const curve = (name: string) => {
+ const value = rawToken(name);
+ return isNamedCurve(value)
+ ? JSON.stringify(value)
+ : `[${parseBezier(value).join(', ')}]`;
+ };
+
+ return `// @generated from the Astryx theme by scripts/generate-motion-mirror.mjs.
+// Seconds and numbers, because that is what animation libraries, the Web
+// Animations API and canvas take. Regenerate when the theme changes.
+
+/** Seconds. Motion, WAAPI and canvas all want a number here. */
+export const duration = {
+${SEMANTIC_DURATIONS.map(d => ` ${short(d.name)}: ${seconds(d.name)},`).join('\n')}
+} as const;
+
+/** Four control points, or the CSS keyword when the curve is a keyword. */
+export const ease = {
+${SEMANTIC_EASES.map(e => ` ${short(e.name)}: ${curve(e.name)},`).join('\n')}
+} as const;
+
+/** Seconds between items in a group entrance. */
+export const stagger = {
+${STAGGERS.map(([name]) => ` ${short(name)}: ${seconds(name)},`).join('\n')}
+} as const;
+
+/** No CSS form at all, so these are defined here rather than mirrored. */
+export const spring = {
+${SPRINGS.map(
+ s =>
+ ` ${s.name}: {duration: ${springs[s.name].duration}, bounce: ${springs[s.name].bounce}},`,
+).join('\n')}
+} as const;`;
+}
+
+const BEFORE_CODE = `// MobileNav/MobileNav.tsx:294-311
+function resolveCloseDelay(dialog: HTMLDialogElement): number {
+ const cap = window.matchMedia('(prefers-reduced-motion: reduce)').matches
+ ? 0
+ : MAX_CLOSE_DELAY_MS;
+
+ const hold = parseShortestDurationMs(
+ window.getComputedStyle(dialog).transitionDuration,
+ );
+
+ // The hold is unreadable — an unresolved var()
+ // outside a real browser.
+ if (hold === null) {
+ return cap;
+ }
+
+ return hold <= 0 ? 0 : Math.min(cap, hold * CLOSE_WITHIN_HOLD);
+}
+
+// plus parseShortestDurationMs at :265 — 25 lines
+// that exist only to turn "0.41s, 0.12s" back into
+// a number, exported so it can be unit tested.`;
+
+const AFTER_CODE = `import {duration} from '@astryxdesign/core/motion';
+
+function resolveCloseDelay(prefersReducedMotion: boolean): number {
+ const cap = prefersReducedMotion ? 0 : MAX_CLOSE_DELAY_MS;
+ // The same value the stylesheet uses, theme-resolved,
+ // and readable in jsdom.
+ const hold = duration.overlay * 1000;
+ return Math.min(cap, hold * CLOSE_WITHIN_HOLD);
+}`;
+
+const STYLEX_GAP_CODE = `import {durationVars, easeVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+durationVars['--duration-medium']; // "var(--x1kg2b7)" — a reference
+easeVars['--ease-standard']; // "var(--x9f0d3a)" — same
+
+// Correct in StyleX:
+stylex.create({panel: {transitionDuration: durationVars['--duration-medium']}});
+
+// Useless anywhere else:
+animate(el, {opacity: 1}, {duration: durationVars['--duration-medium']}); // NaN
+ctx.globalAlpha = progress(durationVars['--duration-medium']); // NaN`;
+
+/**
+ * A bar chart redrawn on a loop. Before replaces the data outright, which is
+ * what every chart in the system does today; after interpolates it with the
+ * same token the CSS uses, reached through the mirror.
+ */
+function ChartPane({mode}: {mode: 'before' | 'after'}) {
+ const {rawToken, reducedMotion, scaledMs} = useMotionLab();
+ const canvasRef = useRef<HTMLCanvasElement | null>(null);
+ const currentRef = useRef<ReadonlyArray<number>>(DATASETS[0]);
+ const stepRef = useRef(1);
+ const frameRef = useRef(0);
+
+ const draw = useCallback((values: ReadonlyArray<number>) => {
+ const canvas = canvasRef.current;
+ if (canvas == null) {
+ return;
+ }
+ const ratio = window.devicePixelRatio || 1;
+ const width = canvas.clientWidth || 280;
+ const pixelWidth = Math.round(width * ratio);
+ const pixelHeight = Math.round(CHART_HEIGHT * ratio);
+ if (canvas.width !== pixelWidth || canvas.height !== pixelHeight) {
+ canvas.width = pixelWidth;
+ canvas.height = pixelHeight;
+ }
+ const ctx = canvas.getContext('2d');
+ if (ctx == null) {
+ return;
+ }
+ ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+ ctx.clearRect(0, 0, width, CHART_HEIGHT);
+ ctx.fillStyle = window.getComputedStyle(canvas).color;
+ const gap = 8;
+ const barWidth = (width - gap * (values.length - 1)) / values.length;
+ values.forEach((value, i) => {
+ const height = Math.max(2, value * (CHART_HEIGHT - 6));
+ ctx.fillRect(
+ i * (barWidth + gap),
+ CHART_HEIGHT - height,
+ barWidth,
+ height,
+ );
+ });
+ }, []);
+
+ const advance = useCallback(() => {
+ const next = DATASETS[stepRef.current % DATASETS.length];
+ stepRef.current += 1;
+ const from = currentRef.current;
+
+ // Under either reduced-motion policy the after pane collapses into the
+ // before pane, which is what reduced motion costs a chart: the data still
+ // changes, the eye just has to find it again.
+ if (mode === 'before' || reducedMotion !== 'off') {
+ currentRef.current = next;
+ draw(next);
+ return;
+ }
+
+ const ms = Math.max(1, scaledMs('--duration-reveal'));
+ const curve = parseBezier(rawToken('--ease-move'));
+ const startedAt = performance.now();
+ window.cancelAnimationFrame(frameRef.current);
+ const step = (now: number) => {
+ const k = Math.min(1, (now - startedAt) / ms);
+ const eased = bezierAt(curve, k);
+ draw(next.map((target, i) => from[i] + (target - from[i]) * eased));
+ if (k < 1) {
+ frameRef.current = window.requestAnimationFrame(step);
+ } else {
+ currentRef.current = next;
+ }
+ };
+ frameRef.current = window.requestAnimationFrame(step);
+ }, [draw, mode, rawToken, reducedMotion, scaledMs]);
+
+ useLoop(advance, scaledMs('--duration-reveal') + 1300);
+
+ useEffect(() => () => window.cancelAnimationFrame(frameRef.current), []);
+
+ return (
+ <canvas
+ ref={canvasRef}
+ role="img"
+ aria-label={
+ mode === 'before'
+ ? 'Bar chart whose values change instantly'
+ : 'Bar chart whose values interpolate over the reveal duration'
+ }
+ {...stylex.props(sx.canvas)}
+ />
+ );
+}
+
+export default function MotionJsMirrorPage() {
+ const {rawToken, springs, scaledMs} = useMotionLab();
+ const typeahead = TIMEOUT_LITERALS[0];
+
+ return (
+ <LabPage
+ title="JS token mirror"
+ intro="CSS custom properties are unreadable to every animation library, to the Web Animations API, and to canvas and chart code. Motion takes seconds as a number and easing as a four-number array; it cannot resolve var(--duration-fast). The mirror emits the same values the stylesheets use, in the shape those consumers already expect."
+ decides="What the mirror has to expose for charts, canvas and motion libraries."
+ badges={<Badge variant="info" label="emitted live from this session" />}>
+ <DemoCard
+ title="The read that should not have to exist"
+ question={`${AUDIT_COUNTS.getComputedStyleReads} getComputedStyle reads across core. Two of them read motion values back out of CSS because there is no other way to get them.`}
+ badges={
+ <Badge variant="warning" label="MobileNav/MobileNav.tsx:303" />
+ }>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — parse the number back out of the stylesheet',
+ content: (
+ <CodeBlock
+ language="ts"
+ code={BEFORE_CODE}
+ maxHeight={340}
+ isWrapped
+ hasCopyButton={false}
+ />
+ ),
+ },
+ {
+ tone: 'after',
+ label: 'With the mirror',
+ content: (
+ <CodeBlock
+ language="ts"
+ code={AFTER_CODE}
+ maxHeight={340}
+ isWrapped
+ hasCopyButton={false}
+ />
+ ),
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ MobileNav is doing the right thing for the right reason. Its own
+ comment says so: the hold is <code>--duration-medium</code>,{' '}
+ <q>
+ which themes rewrite — the shipped y2k theme sets it to exactly
+ 250ms — so read the hold in effect rather than assuming it
+ </q>
+ . Getting that value costs a computed-style read, a 25-line time
+ parser exported for its own unit test (
+ <code>MobileNav/MobileNav.tsx:265</code>), and a null branch for the
+ case where the read comes back as an unresolved <code>var()</code>{' '}
+ outside a real browser. That is exactly right, and exactly what
+ nobody should have to write by hand.
+ </Text>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ The opposite failure — a hardcoded unmount timer drifting away from
+ the transition it is supposed to outlast — is the one the brief
+ warns about, and the audit does not find it.{' '}
+ <code>TIMEOUT_LITERALS</code> holds exactly{' '}
+ {TIMEOUT_LITERALS.length} entry:{' '}
+ <code>
+ {typeahead.file}:{typeahead.line}
+ </code>{' '}
+ ({typeahead.ms}ms), and it is a typeahead buffer reset, not motion
+ at all. So core is currently on the safe side of that trade and
+ paying for it in ceremony. The mirror does not fix a bug here; it
+ removes the ceremony, and it makes the same number available to code
+ that has no stylesheet to read.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Read</TableHeaderCell>
+ <TableHeaderCell>What it wants</TableHeaderCell>
+ <TableHeaderCell>Mirror replaces it?</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ <TableRow>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>
+ MobileNav/MobileNav.tsx:303
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text color="secondary">
+ <code>transitionDuration</code>, to time the dialog close
+ inside the hold
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Badge variant="success" label="yes" />
+ </TableCell>
+ </TableRow>
+ <TableRow>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>
+ BottomSheet/BottomSheetPanel.tsx:326
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text color="secondary">
+ <code>transitionProperty</code>,{' '}
+ <code>transitionDuration</code> and{' '}
+ <code>transitionDelay</code>, to know whether a{' '}
+ <code>transitionend</code> will arrive
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Badge variant="warning" label="partly" />
+ </TableCell>
+ </TableRow>
+ <TableRow>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>
+ the other {AUDIT_COUNTS.getComputedStyleReads - 2}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text color="secondary">
+ direction, writing mode, padding, border radius, scroll
+ margin — layout, not motion
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Badge label="not its job" />
+ </TableCell>
+ </TableRow>
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ Worth saying plainly: {AUDIT_COUNTS.getComputedStyleReads} is the
+ whole computed-style caseload, not the motion one. The motion
+ argument rests on two sites and on everything that cannot read a
+ stylesheet at all — which is the next card.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Charts are outside the token system entirely"
+ question="Canvas cannot resolve a custom property. Chart, Radial, Sankey and Schedule therefore animate on whatever numbers their author typed, or they do not animate."
+ badges={<Badge variant="neutral" label="live, on a loop" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — data replaces itself',
+ content: (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <ChartPane mode="before" />
+ <Text type="supporting" color="secondary">
+ No token is reachable from here, so the honest default is no
+ animation at all. The chart jumps and the eye loses which
+ bar was which.
+ </Text>
+ </VStack>
+ ),
+ },
+ {
+ tone: 'after',
+ label: 'With the mirror — interpolated on the reveal token',
+ content: (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <ChartPane mode="after" />
+ <Text type="supporting" color="secondary">
+ <code>scaledMs(&apos;--duration-reveal&apos;)</code> and{' '}
+ <code>
+ bezierAt(parseBezier(rawToken(&apos;--ease-move&apos;)),
+ k)
+ </code>{' '}
+ — the same duration and the same curve the CSS uses, applied
+ per frame.
+ </Text>
+ </VStack>
+ ),
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting" color="secondary">
+ Currently {Math.round(scaledMs('--duration-reveal'))}ms at the
+ rail&rsquo;s speed, on <code>{rawToken('--ease-move')}</code>.
+ Change either on the tokens page and both this chart and every CSS
+ demo in the lab move together — which is the whole claim: one value,
+ two consumers.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <VStack gap={3}>
+ <Heading level={2}>The module, as it stands right now</Heading>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ Emitted from whatever this session has tuned, including springs from
+ the springs page. Copy it and it is a working module.
+ </Text>
+ <CodeBlock
+ language="ts"
+ title="@astryxdesign/core/motion — generated"
+ hasCopyButton
+ maxHeight={760}
+ code={emitMirror(rawToken, springs)}
+ />
+ </VStack>
+
+ <Grid columns={{minWidth: 460}} gap={4}>
+ <DemoCard
+ title="Why the defaults are not hardcoded in JS"
+ question="Because a theme retunes the whole scale, and a constants file would quietly stop agreeing with the stylesheet.">
+ <DemoBody>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ A theme sets three numbers —{' '}
+ <code>{'{fast, medium, ratio}'}</code> — and{' '}
+ <code>expandMotionScale</code> derives the whole duration scale
+ from them; the shipped y2k theme lands{' '}
+ <code>--duration-medium</code> on 250ms rather than 410ms. A
+ mirror written as literals would be right for the default theme
+ and wrong for every other one, which is the failure mode MobileNav
+ is already defending against by reading the computed value.
+ </Text>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ So the mirror parses the same token values the stylesheets use,
+ through the resolver core already has:{' '}
+ <code>resolveThemeTokens(theme, {'{mode}'})</code> returns
+ concrete strings with <code>var()</code> references already
+ followed, and needs no React context and no browser. Springs are
+ the exception and are defined in the mirror natively, because they
+ have no CSS form to parse.
+ </Text>
+ <CodeBlock
+ language="ts"
+ title="How the emitter gets its numbers"
+ isWrapped
+ code={`import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';
+
+const tokens = resolveThemeTokens(theme, {mode: 'light'});
+duration.overlay = parseMs(tokens['--duration-overlay']) / 1000;
+ease.move = parseBezier(tokens['--ease-move']);
+// spring.* has no token to read — it is authored here.`}
+ />
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="StyleX vars are not the mirror"
+ question="Core already exports durationVars and easeVars. They are the right thing for StyleX and useless everywhere else.">
+ <DemoBody>
+ <CodeBlock
+ language="ts"
+ code={STYLEX_GAP_CODE}
+ isWrapped
+ maxHeight={300}
+ />
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ <code>stylex.defineVars</code> hands back opaque{' '}
+ <code>var(...)</code> strings. That is the correct contract for a
+ stylesheet and it is precisely the gap: the value never becomes a
+ number on the JS side. The mirror is the second half of the same
+ token, not a competing source of truth.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+ </Grid>
+
+ <Banner
+ status="info"
+ title="What the mirror does not solve"
+ description={
+ <Text>
+ A second artefact is a second thing to keep in sync. It only stays
+ honest if it is generated from the theme in the same build step that
+ emits the CSS, and if the lint rule treats a hardcoded number in JS
+ the same way it treats one in a stylesheet. Both of those are on{' '}
+ <Link href="/motion/export">Export tuning</Link>.
+ </Text>
+ }
+ />
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/library.tsx b/apps/sandbox/src/motion/pages/library.tsx
new file mode 100644
index 0000000000..fabc8dce59
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/library.tsx
@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input libraryCompat.ts and the generated audit
+ * @output The three blockers between Astryx and motion.dev, in order
+ * @position /motion/library
+ *
+ * The recommendation is to stay CSS-first and become explicitly compatible.
+ * Nothing on this page argues for taking the dependency; it argues about what
+ * a consumer who takes it themselves runs into, which is a different and much
+ * cheaper list than the brief assumed.
+ */
+
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link as AstryxLink} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {
+ AUDIT_COUNTS,
+ TRANSFORM_TRANSITIONS,
+} from '../__generated__/motionAudit';
+import {ComparePanes, DemoBody, DemoCard} from '../LabPrimitives';
+import {PressRig} from '../LabDemos';
+import {LabPage} from '../PageFrame';
+import {
+ ALREADY_RIGHT,
+ BLOCKERS,
+ CHEAP_WINS,
+ MOTION_BUNDLE_KB,
+ buttonFindings,
+} from '../libraryCompat';
+
+function Detail({label, children}: {label: string; children: string}) {
+ return (
+ <VStack gap={1}>
+ <Text type="label" weight="semibold">
+ {label}
+ </Text>
+ <Text color="secondary">{children}</Text>
+ </VStack>
+ );
+}
+
+export default function MotionLibraryPage() {
+ const button = buttonFindings();
+ const transformComponents = new Set(
+ TRANSFORM_TRANSITIONS.map(site => site.component),
+ );
+
+ return (
+ <LabPage
+ title="Motion library compatibility"
+ intro="What a team that installs motion.dev runs into today, and the smallest set of changes that makes Astryx compose with it. Three blockers, in the order they bite."
+ badges={<Badge variant="info" label="CSS-first" />}
+ decides="The three blockers, and whether Button keeps its press transition.">
+ <Banner
+ status="info"
+ title="Stay CSS-first and become explicitly compatible"
+ description={
+ <Text>
+ {`Astryx should not ship Motion: ~${MOTION_BUNDLE_KB}KB and a runtime on every consumer, to fix nothing the CSS path is failing at. But a consumer who installs it themselves should find that Astryx composes cleanly, and today three things stop that. Two of the three are already on the roadmap under other names.`}
+ </Text>
+ }
+ />
+
+ {BLOCKERS.map((blocker, index) => (
+ <DemoCard
+ key={blocker.id}
+ title={`${index + 1}. ${blocker.title}`}
+ question={blocker.symptom}
+ badges={<Badge variant="error" label={blocker.severity} />}>
+ {blocker.id === 'transform-transitions' ? (
+ <VStack gap={0}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'transition: transform — today',
+ content: <PressRig technique="transform" />,
+ },
+ {
+ tone: 'neutral',
+ label: 'transition: scale — the middle path',
+ content: <PressRig technique="scale" />,
+ },
+ {
+ tone: 'after',
+ label: 'no transition — what the brief proposes',
+ content: <PressRig technique="none" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <Detail label="Cause">{blocker.cause}</Detail>
+ <Detail label="Fix">{blocker.fix}</Detail>
+ <Banner
+ status="warning"
+ title={`Measured: ${AUDIT_COUNTS.transformTransitions} sites across ${AUDIT_COUNTS.transformTransitionComponents} components — the brief's "20+" was right`}
+ description={
+ <Text>
+ {button.transformSites.length > 0
+ ? `Button is in the list, at ${button.transformSites
+ .map(site => `${site.file}:${site.line}`)
+ .join(
+ ', ',
+ )}: it declares transform in its transition property list and takes scale(0.98) on :active. The brief calls it the worst case because it is the most-wrapped component, and the measurement agrees. Two earlier versions of the audit script reported far fewer sites and no Button at all — a wrapped value and a nested StyleX rule each hid matches. The brief was closer than the tool twice.`
+ : 'Button is absent from the measured data, which contradicts the brief. Re-check the scanner before acting on this.'}
+ </Text>
+ }
+ />
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Component</TableHeaderCell>
+ <TableHeaderCell>Site</TableHeaderCell>
+ <TableHeaderCell>Declaration</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {TRANSFORM_TRANSITIONS.map(site => (
+ <TableRow key={`${site.file}:${site.line}`}>
+ <TableCell>
+ <Text weight="semibold">{site.component}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="code">{`${site.file}:${site.line}`}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="code" color="secondary">
+ {site.decl ?? '\u2014'}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ {`${transformComponents.size} components, and the shape of the list is chevrons and menus rather than roots: ${[...transformComponents].join(', ')}. A consumer animating a chevron is rare; a consumer animating a Button is not, which is why the brief's framing mattered and why the correction changes the priority.`}
+ </Text>
+ <Detail label="Cost">{blocker.cost}</Detail>
+ </DemoBody>
+ </VStack>
+ ) : (
+ <DemoBody>
+ <Detail label="Cause">{blocker.cause}</Detail>
+ <Detail label="Fix">{blocker.fix}</Detail>
+ <Detail label="Cost">{blocker.cost}</Detail>
+ {blocker.id === 'overlay-exit' && (
+ <Text type="supporting" color="secondary">
+ Same mechanism as the CSS exit gap:{' '}
+ <AstryxLink href="/motion/exit-gap">
+ see it fail natively
+ </AstryxLink>
+ . One fix closes both, and doing them apart means solving
+ top-layer retention twice.
+ </Text>
+ )}
+ </DemoBody>
+ )}
+ </DemoCard>
+ ))}
+
+ <VStack gap={3}>
+ <Heading level={2}>Cheap wins</Heading>
+ <Text color="secondary">
+ What moves Astryx from &ldquo;wrappable with caveats&rdquo; to
+ Motion-friendly for everything except overlay exits. None of these
+ needs the composition decision.
+ </Text>
+ <Grid columns={{minWidth: 280}} gap={3}>
+ {CHEAP_WINS.map(win => (
+ <Card key={win.id} padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">{win.title}</Text>
+ <Text type="supporting" color="secondary">
+ {win.detail}
+ </Text>
+ {win.evidence != null && <Badge label={win.evidence} />}
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ <Text type="supporting" color="secondary">
+ The ref gap is the one number on this page the lab cannot check: the
+ audit reads the built package&rsquo;s styles, not its prop types, so
+ the brief&rsquo;s &ldquo;eight overlay components&rdquo; is unverified
+ here.
+ </Text>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>What already works</Heading>
+ <Text color="secondary">
+ Astryx is structurally better placed for this than most CSS-first
+ systems, and the part that usually needs a rewrite is the part that is
+ already right.
+ </Text>
+ <Grid columns={{minWidth: 260}} gap={3}>
+ {ALREADY_RIGHT.map(item => (
+ <Card key={item.title} padding={4}>
+ <VStack gap={1.5}>
+ <HStack gap={1.5} vAlign="center">
+ <Badge variant="success" label="ok" />
+ <Text weight="semibold">{item.title}</Text>
+ </HStack>
+ <Text type="supporting" color="secondary">
+ {item.detail}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/overview.tsx b/apps/sandbox/src/motion/pages/overview.tsx
new file mode 100644
index 0000000000..2d93dfde87
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/overview.tsx
@@ -0,0 +1,356 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input Generated audit, brief figures, section registry
+ * @output The Motion Lab overview
+ * @position /motion
+ *
+ * Opens on the disagreement between the brief and the code rather than on the
+ * brief's numbers, because that is the first thing anyone acting on this needs
+ * to know: the audit was written against a reading of the repo, and the repo
+ * says something slightly different in several places.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import Link from 'next/link';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link as AstryxLink} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {AUDIT_COUNTS, CORE_VERSION} from '../__generated__/motionAudit';
+import {GUIDANCE_CONFLICTS, PUBLISHED_PAGE_URL} from '../publishedGuidance';
+import {MOTION_SECTIONS} from '../sections';
+import {LabPage} from '../PageFrame';
+
+const sx = stylex.create({
+ stat: {padding: '14px'},
+ statValue: {
+ fontSize: '26px',
+ fontWeight: 650,
+ letterSpacing: '-0.02em',
+ lineHeight: 1.1,
+ },
+ bad: {color: 'var(--color-text-error, #d3543f)'},
+ warn: {color: 'var(--color-text-warning, #b3760a)'},
+ full: {width: '100%'},
+ cardLink: {textDecoration: 'none', color: 'inherit', display: 'block'},
+});
+
+/**
+ * The brief's figures beside the measured ones. Rows only appear here when
+ * they differ — a table of agreements would bury the four that matter.
+ */
+const RECONCILIATION: ReadonlyArray<{
+ readonly measure: string;
+ readonly brief: string;
+ readonly measured: string;
+ readonly reading: string;
+}> = [
+ {
+ measure: 'Component directories',
+ brief: '107 (90 core, 17 lab)',
+ measured: `${AUDIT_COUNTS.componentDirs} (${AUDIT_COUNTS.coreComponentDirs} core, ${AUDIT_COUNTS.labComponentDirs} lab)`,
+ reading:
+ 'Lab matches exactly. Core is higher than the brief\u2019s 90 — the split it quotes is close but not current.',
+ },
+ {
+ measure: 'Animate something',
+ brief: '63',
+ measured: String(AUDIT_COUNTS.animatingComponents),
+ reading:
+ 'Counted as component directories with at least one transition, animation or keyframe. The brief counted across core and lab together.',
+ },
+ {
+ measure: 'Hardcoded duration / easing',
+ brief: '28',
+ measured: String(AUDIT_COUNTS.hardcodedTotal),
+ reading:
+ 'Higher, not lower. The brief undercounts: the sweep is bigger than budgeted, and about a quarter of it is a reduced-motion idiom rather than carelessness.',
+ },
+ {
+ measure: 'Files animating with no reduced-motion branch',
+ brief: '39',
+ measured: String(AUDIT_COUNTS.filesWithoutReducedMotion),
+ reading:
+ 'Close. The gap is counting method, not a disagreement worth chasing.',
+ },
+ {
+ measure: 'Dead no-op transitions',
+ brief: '3, in Selector / ComplexSelector / MultiSelector',
+ measured: `${AUDIT_COUNTS.noopTransitions}, in Lightbox`,
+ reading:
+ 'The brief\u2019s three do not exist as described. The one real instance is a deliberate transitionProperty: none. Worth re-checking before it becomes a milestone line item.',
+ },
+ {
+ measure: 'CSS transition on transform',
+ brief: '20+ components',
+ measured: `${AUDIT_COUNTS.transformTransitions} sites, ${AUDIT_COUNTS.transformTransitionComponents} components`,
+ reading:
+ 'The brief is right, and this row is a caution about the tool rather than the doc: two earlier versions of the audit script reported 13 across 9, because a wrapped value and a nested StyleX rule each hid matches. Trust a generated number only as far as its generator has been tested.',
+ },
+];
+
+function Stat({
+ value,
+ label,
+ detail,
+ tone,
+}: {
+ value: string | number;
+ label: string;
+ detail?: string;
+ tone?: 'bad' | 'warn';
+}) {
+ return (
+ <Card padding={0} {...stylex.props(sx.full)}>
+ <VStack gap={0.5} {...stylex.props(sx.stat)}>
+ <span
+ {...stylex.props(
+ sx.statValue,
+ tone === 'bad' && sx.bad,
+ tone === 'warn' && sx.warn,
+ )}>
+ {value}
+ </span>
+ <Text type="supporting">{label}</Text>
+ {detail != null && (
+ <Text type="supporting" color="secondary">
+ {detail}
+ </Text>
+ )}
+ </VStack>
+ </Card>
+ );
+}
+
+export default function MotionOverviewPage() {
+ const reversals = GUIDANCE_CONFLICTS.filter(c => c.severity === 'reversal');
+
+ return (
+ <LabPage
+ title="Motion Lab"
+ intro="A bench for the H2 2026 motion proposals. Every proposal is here as a working before-and-after with its values exposed as controls, so the decisions get made by looking rather than by arguing about numbers in a document."
+ badges={<Badge variant="info" label={`core@${CORE_VERSION}`} />}
+ decides="Whether the audit in the brief matches the code, and which decisions are actually blocking.">
+ <Banner
+ status="warning"
+ title={`${reversals.length} of the proposals reverse guidance Astryx publishes today`}
+ description={
+ <Text>
+ The published Motion page tells authors that tooltips, hover cards
+ and dropdown menus <em>may</em> disappear instantly, and that
+ reduced motion means replacing animation with instant state changes.
+ The eleven-component exit gap is not drift — it is that paragraph,
+ correctly followed. Read the conflicts before planning any of this
+ work.
+ </Text>
+ }
+ endContent={
+ <AstryxLink href="/motion/published">See the conflicts</AstryxLink>
+ }
+ />
+
+ <VStack gap={3}>
+ <Heading level={2}>Measured against the installed package</Heading>
+ <Text color="secondary">
+ Generated by <code>scripts/generate-motion-audit.mjs</code> from{' '}
+ <code>packages/core/src</code> and <code>packages/lab/src</code> at
+ core@
+ {CORE_VERSION}, so these move when the packages do. Every finding
+ carries the package it is in.
+ </Text>
+ <Grid columns={{minWidth: 210}} gap={3}>
+ <Stat
+ value={AUDIT_COUNTS.componentDirs}
+ label="Component directories"
+ detail={`${AUDIT_COUNTS.animatingComponents} animate, ${AUDIT_COUNTS.staticComponents} do not`}
+ />
+ <Stat
+ value={1}
+ label="Easing tokens"
+ detail="--ease-standard, for every job"
+ tone="bad"
+ />
+ <Stat
+ value={9}
+ label="Duration tokens"
+ detail="named by size, not by job"
+ />
+ <Stat
+ value={AUDIT_COUNTS.hardcodedTotal}
+ label="Hardcoded duration / easing"
+ detail={`${AUDIT_COUNTS.hardcodedDuration} durations, ${AUDIT_COUNTS.hardcodedEasing} curves`}
+ tone="bad"
+ />
+ <Stat
+ value={AUDIT_COUNTS.filesWithoutReducedMotion}
+ label="Animated files with no reduced-motion branch"
+ detail={`of ${AUDIT_COUNTS.animatedFiles} animated files`}
+ tone="bad"
+ />
+ <Stat
+ value={AUDIT_COUNTS.durationWithoutCurve}
+ label="Durations with no declared curve"
+ detail="silently getting the CSS default"
+ tone="warn"
+ />
+ <Stat
+ value={AUDIT_COUNTS.transformTransitions}
+ label="Transitions on transform"
+ detail={`across ${AUDIT_COUNTS.transformTransitionComponents} components`}
+ tone="warn"
+ />
+ <Stat
+ value={AUDIT_COUNTS.getComputedStyleReads}
+ label="getComputedStyle reads"
+ detail="the JS mirror's caseload"
+ />
+ </Grid>
+ </VStack>
+
+ <Banner
+ status="info"
+ title="How the counting works, and where it misleads"
+ description={
+ <Text>
+ The audit attributes motion to the component directory the file sits
+ in. Astryx composes heavily, so a surface can animate without a
+ single transition in its own folder — Tooltip, HoverCard, Popover,
+ Typeahead and the rest inherit theirs from <code>Layer/</code>,
+ AlertDialog from <code>Dialog/</code>, IconButton and ToggleButton
+ from <code>Button/</code>, FieldStatus from{' '}
+ <code>hooks/containerReveal.stylex.ts</code>. Read the per-component
+ numbers as &ldquo;where the motion is authored&rdquo;, not
+ &ldquo;which components move&rdquo;. The same trap is waiting for
+ the rubric: a per-component score has to follow composition, or it
+ will fail a component for a curve it does not own.
+ </Text>
+ }
+ />
+
+ <VStack gap={3}>
+ <Heading level={2}>Where the brief and the code disagree</Heading>
+ <Text color="secondary">
+ Only the rows that differ. Everything else in the audit checked out.
+ </Text>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Measure</TableHeaderCell>
+ <TableHeaderCell>Brief</TableHeaderCell>
+ <TableHeaderCell>Measured</TableHeaderCell>
+ <TableHeaderCell>Reading</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {RECONCILIATION.map(row => (
+ <TableRow key={row.measure}>
+ <TableCell>
+ <Text weight="semibold">{row.measure}</Text>
+ </TableCell>
+ <TableCell>
+ <Text color="secondary">{row.brief}</Text>
+ </TableCell>
+ <TableCell>
+ <Text>{row.measured}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.reading}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>How to use the bench</Heading>
+ <Grid columns={{minWidth: 280}} gap={3}>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">The rail applies everywhere</Text>
+ <Text type="supporting" color="secondary">
+ Slow-mo stretches every duration without moving the token, so
+ you can judge a 175ms curve at 8&times; and still export 175ms.
+ Reduced motion drives the real policy switch. Show hides one
+ half of every comparison.
+ </Text>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">Every slider writes a real token</Text>
+ <Text type="supporting" color="secondary">
+ Tune a value anywhere and every demo in the section updates,
+ because they all read the same custom property. When it feels
+ right, the export page emits the token block and the JS mirror.
+ </Text>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">Numbers are generated, prose is not</Text>
+ <Text type="supporting" color="secondary">
+ Counts and file:line citations come from the audit script.
+ Judgements about what they mean are written, and are the part
+ worth arguing with.
+ </Text>
+ </VStack>
+ </Card>
+ </Grid>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Sections</Heading>
+ <Grid columns={{minWidth: 300}} gap={3}>
+ {MOTION_SECTIONS.filter(s => s.href !== '/motion').map(section => (
+ <Link
+ key={section.href}
+ href={section.href}
+ {...stylex.props(sx.cardLink)}>
+ <Card padding={4} {...stylex.props(sx.full)}>
+ <VStack gap={1}>
+ <HStack gap={1.5} vAlign="center">
+ <Text weight="semibold">{section.title}</Text>
+ <Badge label={section.group} />
+ </HStack>
+ <Text type="supporting" color="secondary">
+ {section.decides}
+ </Text>
+ </VStack>
+ </Card>
+ </Link>
+ ))}
+ </Grid>
+ </VStack>
+
+ <Text type="supporting" color="secondary">
+ Published guidance:{' '}
+ <AstryxLink
+ href={PUBLISHED_PAGE_URL}
+ target="_blank"
+ rel="noopener noreferrer">
+ astryx.atmeta.com/docs/motion
+ </AstryxLink>
+ </Text>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/plan.tsx b/apps/sandbox/src/motion/pages/plan.tsx
new file mode 100644
index 0000000000..692fd2d29d
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/plan.tsx
@@ -0,0 +1,279 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input openQuestions.ts
+ * @output The sequence, what gates each stage, and who has to answer what
+ * @position /motion/plan
+ *
+ * The ordering here is a dependency graph, not a schedule. Most of its edges
+ * are decisions: nine of them are still open, and four of those sit above the
+ * first stage that would write code.
+ */
+
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link as AstryxLink} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {AUDIT_COUNTS} from '../__generated__/motionAudit';
+import {DemoBody, DemoCard} from '../LabPrimitives';
+import {LabPage} from '../PageFrame';
+import {
+ BRIEF_DEFECTS,
+ COMMITMENTS,
+ OPEN_QUESTIONS,
+ RISKS,
+ STAGES,
+ type OpenQuestion,
+} from '../openQuestions';
+
+const URGENCY_VARIANT: Record<
+ OpenQuestion['urgency'],
+ 'error' | 'warning' | 'neutral'
+> = {
+ 'decide first': 'error',
+ 'decide before the sweep': 'warning',
+ 'decide before publishing': 'warning',
+ 'can run late': 'neutral',
+};
+
+export default function MotionPlanPage() {
+ const blocking = OPEN_QUESTIONS.filter(q => q.urgency === 'decide first');
+ const committed = COMMITMENTS.filter(c => c.level === 'committed');
+ const stretch = COMMITMENTS.filter(c => c.level === 'stretch');
+
+ return (
+ <LabPage
+ title="Plan & open questions"
+ intro="A dependency order for the work, the decisions that gate each stage, and the ones nobody has made yet. Sizes are relative; there are no dates, because the brief has none either."
+ badges={
+ <Badge
+ variant="warning"
+ label={`${OPEN_QUESTIONS.length} open questions`}
+ />
+ }
+ decides="Sequence, gates, and who has to answer what.">
+ <Banner
+ status="warning"
+ title={`${blocking.length} decisions sit above the first line of code`}
+ description={
+ <Text>
+ Springs in the theme contract and the mobile-token vocabulary both
+ change the shape of the token contract, and both are breaking
+ changes if they arrive after Foundation ships. Everything else can
+ be decided while work runs — these two cannot.
+ </Text>
+ }
+ />
+
+ <VStack gap={3}>
+ <Heading level={2}>Sequence</Heading>
+ <Text color="secondary">
+ Each stage lists what blocks it. A stage whose gate is still open does
+ not start early; it starts twice.
+ </Text>
+ {STAGES.map(stage => (
+ <DemoCard
+ key={stage.id}
+ title={`${stage.index}. ${stage.name}`}
+ question={stage.goal}
+ badges={<Badge label={stage.size} />}>
+ <DemoBody>
+ <VStack gap={1}>
+ {stage.work.map((item, i) => (
+ <Text key={item} color="secondary">
+ {`${i + 1}. ${item}`}
+ </Text>
+ ))}
+ </VStack>
+ {stage.blockedBy.length > 0 ? (
+ <VStack gap={1.5}>
+ {stage.blockedBy.map(gate => (
+ <HStack key={gate} gap={2} vAlign="center" wrap="wrap">
+ <Badge variant="error" label="gate" />
+ <Text type="supporting" color="secondary">
+ {gate}
+ </Text>
+ </HStack>
+ ))}
+ </VStack>
+ ) : (
+ <HStack gap={2} vAlign="center">
+ <Badge variant="success" label="unblocked" />
+ <Text type="supporting" color="secondary">
+ Nothing blocks this. It is the only stage that can start
+ today.
+ </Text>
+ </HStack>
+ )}
+ </DemoBody>
+ </DemoCard>
+ ))}
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Scope discipline</Heading>
+ <Banner
+ status="error"
+ title="Do not combine token retuning, presence architecture and component remediation in one rollout"
+ description={
+ <Text>
+ All three move the visual-regression baselines. Rolled out
+ separately, a failure is attributable: a baseline moved because a
+ curve changed, or because a surface now animates out, or because a
+ component was rewritten. Rolled out together, every failure is a
+ bisect, and the bisect is across a quarter of work. This is also
+ why Foundation ships tokens as aliases before it retunes a single
+ value — the alias step is provably invisible, so anything the
+ capture catches afterwards belongs to the retune.
+ </Text>
+ }
+ />
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Open questions</Heading>
+ <Text color="secondary">
+ Each one names what it needs, what it blocks, and where in the lab you
+ can look at it instead of arguing about it.
+ </Text>
+ {OPEN_QUESTIONS.map(question => (
+ <Card key={question.id} padding={4}>
+ <VStack gap={2}>
+ <HStack gap={2} vAlign="center" wrap="wrap" justify="between">
+ <Text weight="semibold">{question.question}</Text>
+ <Badge
+ variant={URGENCY_VARIANT[question.urgency]}
+ label={question.urgency}
+ />
+ </HStack>
+ <Grid columns={{minWidth: 260}} gap={3}>
+ <VStack gap={1}>
+ <Text type="label" weight="semibold">
+ Needs
+ </Text>
+ <Text type="supporting" color="secondary">
+ {question.needs}
+ </Text>
+ </VStack>
+ <VStack gap={1}>
+ <Text type="label" weight="semibold">
+ Blocks
+ </Text>
+ <Text type="supporting" color="secondary">
+ {question.blocks}
+ </Text>
+ </VStack>
+ </Grid>
+ <AstryxLink href={question.href}>{question.hrefLabel}</AstryxLink>
+ </VStack>
+ </Card>
+ ))}
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Committed and stretch</Heading>
+ <Text color="secondary">
+ {`Committed is what should be true at the end of H2 whatever else slips: ${committed.length} items. Stretch is ${stretch.length} more that are worth doing and safe to drop, because nothing in the committed list depends on them.`}
+ </Text>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Item</TableHeaderCell>
+ <TableHeaderCell>Level</TableHeaderCell>
+ <TableHeaderCell>Why</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {COMMITMENTS.map(item => (
+ <TableRow key={item.item}>
+ <TableCell>
+ <Text weight="semibold">{item.item}</Text>
+ </TableCell>
+ <TableCell>
+ <Badge
+ variant={
+ item.level === 'committed' ? 'success' : 'neutral'
+ }
+ label={item.level}
+ />
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {item.why}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Risks</Heading>
+ <Text color="secondary">
+ The brief&rsquo;s six, and what the lab does about each. One of them
+ the lab cannot help with at all, which is worth saying out loud.
+ </Text>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Risk</TableHeaderCell>
+ <TableHeaderCell>What the lab does about it</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {RISKS.map(risk => (
+ <TableRow key={risk.risk}>
+ <TableCell>
+ <Text>{risk.risk}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {risk.mitigation}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Defects in the brief itself</Heading>
+ <Text color="secondary">
+ {`Found while building the lab, alongside the measurement corrections on the overview — the sweep is ${AUDIT_COUNTS.hardcodedTotal} sites rather than 28, and the transform blocker is ${AUDIT_COUNTS.transformTransitions} sites rather than "20+".`}
+ </Text>
+ <Grid columns={{minWidth: 300}} gap={3}>
+ {BRIEF_DEFECTS.map(defect => (
+ <Card key={defect.defect} padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">{defect.defect}</Text>
+ <Text type="supporting" color="secondary">
+ {defect.detail}
+ </Text>
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/preview-plan.tsx b/apps/sandbox/src/motion/pages/preview-plan.tsx
new file mode 100644
index 0000000000..edc0c7c1e4
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/preview-plan.tsx
@@ -0,0 +1,359 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input previewPlan.ts and the generated audit
+ * @output What every component's preview has to demonstrate before it is built
+ * @position /motion/preview-plan
+ *
+ * A build plan, not a gallery. The column that matters is the hard case: a
+ * preview that only shows the easy case decides nothing, and most of the
+ * techniques in this project are chosen by one awkward instance rather than
+ * by the general shape.
+ */
+
+import {useMemo, useState} from 'react';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {Divider} from '@astryxdesign/core/Divider';
+import {EmptyState} from '@astryxdesign/core/EmptyState';
+import {Grid} from '@astryxdesign/core/Grid';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {LabPage} from '../PageFrame';
+import {
+ PREVIEW_GROUPS,
+ PREVIEW_PLAN,
+ measure,
+ type PreviewRow,
+ type Verdict,
+} from '../previewPlan';
+
+const VERDICT_VARIANT: Record<
+ Verdict,
+ 'success' | 'warning' | 'error' | 'neutral'
+> = {
+ GOOD: 'success',
+ PARTIAL: 'warning',
+ ADD: 'error',
+ NONE: 'neutral',
+};
+
+const PRIORITY_LABEL: Record<1 | 2 | 3, string> = {
+ 1: 'P1 · decides an open question',
+ 2: 'P2 · high-frequency surface',
+ 3: 'P3 · completeness',
+};
+
+function Field({label, children}: {label: string; children: string}) {
+ return (
+ <VStack gap={0.5}>
+ <Text type="supporting" weight="semibold">
+ {label}
+ </Text>
+ <Text type="supporting" color="secondary">
+ {children}
+ </Text>
+ </VStack>
+ );
+}
+
+function RowCard({row}: {row: PreviewRow}) {
+ const measurement = measure(row);
+ return (
+ <Card padding={4}>
+ <VStack gap={2}>
+ <VStack gap={1}>
+ <HStack gap={1.5} vAlign="center" wrap="wrap">
+ <Text weight="semibold">{row.component}</Text>
+ <Badge variant={VERDICT_VARIANT[row.verdict]} label={row.verdict} />
+ <Badge
+ variant={row.status === 'built' ? 'success' : 'neutral'}
+ label={
+ row.status === 'built'
+ ? `built · ${row.rig ?? ''}`
+ : 'specified'
+ }
+ />
+ <Badge label={PRIORITY_LABEL[row.priority]} />
+ </HStack>
+ <HStack gap={3} wrap="wrap">
+ <Text type="supporting" color="secondary">
+ {`Today: ${row.today}`}
+ </Text>
+ </HStack>
+ <Text type="supporting" color="secondary">
+ {`Gap: ${row.gap}`}
+ </Text>
+ </VStack>
+
+ <Divider />
+
+ <Field label="The preview must show">{row.shows}</Field>
+ <Field label="The hard case that decides the technique">
+ {row.hardCase}
+ </Field>
+
+ {row.controls.length > 0 && (
+ <HStack gap={1} wrap="wrap">
+ {row.controls.map(control => (
+ <Badge key={control} variant="info" label={control} />
+ ))}
+ </HStack>
+ )}
+
+ {measurement.kind === 'contradiction' && (
+ <Banner
+ status="error"
+ title="Brief and measurement disagree"
+ description={<Text>{measurement.note}</Text>}
+ />
+ )}
+ {measurement.kind === 'nuance' && (
+ <Banner
+ status="warning"
+ title="Measured differently"
+ description={<Text>{measurement.note}</Text>}
+ />
+ )}
+ {measurement.kind === 'unmeasured' && measurement.note !== '' && (
+ <Text type="supporting" color="secondary">
+ {measurement.note}
+ </Text>
+ )}
+ </VStack>
+ </Card>
+ );
+}
+
+export default function PreviewPlanPage() {
+ const [verdict, setVerdict] = useState<string>('all');
+ const [status, setStatus] = useState<string>('all');
+ const [query, setQuery] = useState('');
+
+ const filtered = useMemo(() => {
+ const needle = query.trim().toLowerCase();
+ return PREVIEW_PLAN.filter(row => {
+ if (verdict !== 'all' && row.verdict !== verdict) {
+ return false;
+ }
+ if (status !== 'all' && row.status !== status) {
+ return false;
+ }
+ if (needle === '') {
+ return true;
+ }
+ return [
+ row.component,
+ row.today,
+ row.gap,
+ row.shows,
+ row.hardCase,
+ row.group,
+ ]
+ .join(' ')
+ .toLowerCase()
+ .includes(needle);
+ });
+ }, [verdict, status, query]);
+
+ const built = PREVIEW_PLAN.filter(row => row.status === 'built');
+ const specified = PREVIEW_PLAN.filter(row => row.status === 'specified');
+ const disagreements = PREVIEW_PLAN.filter(
+ row => measure(row).kind === 'contradiction',
+ );
+ const queue = [...specified].sort(
+ (a, b) =>
+ a.priority - b.priority ||
+ PREVIEW_GROUPS.indexOf(a.group) - PREVIEW_GROUPS.indexOf(b.group),
+ );
+
+ return (
+ <LabPage
+ title="Preview plan"
+ intro="Every component in the audit, what its preview has to demonstrate, and the controls it needs. The hard case is the column that matters: a preview that only shows the easy case is worth nothing."
+ badges={<Badge label={`${PREVIEW_PLAN.length} rows`} />}
+ decides="What every remaining preview has to show before it is worth building.">
+ <Grid columns={{minWidth: 200}} gap={3}>
+ <Card padding={4}>
+ <VStack gap={0.5}>
+ <Heading level={3}>{PREVIEW_PLAN.length}</Heading>
+ <Text type="supporting" color="secondary">
+ Rows across six surfaces
+ </Text>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={0.5}>
+ <Heading level={3}>{built.length}</Heading>
+ <Text type="supporting" color="secondary">
+ Already have a rig in the lab
+ </Text>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={0.5}>
+ <Heading level={3}>{specified.length}</Heading>
+ <Text type="supporting" color="secondary">
+ Specified, not built
+ </Text>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={0.5}>
+ <Heading level={3}>{disagreements.length}</Heading>
+ <Text type="supporting" color="secondary">
+ Rows where the brief and the audit disagree
+ </Text>
+ </VStack>
+ </Card>
+ </Grid>
+
+ <Banner
+ status="warning"
+ title={`${disagreements.length} verdicts do not survive the measurement`}
+ description={
+ <Text>
+ Almost all of them are the same mechanism: the brief credits a
+ component with the motion it inherits, and the audit measures per
+ directory. Tooltip, HoverCard, Popover and the overflow layers get
+ their entry from <code>Layer/</code>; FieldStatus gets its slide
+ from <code>hooks/containerReveal.stylex.ts</code>. Neither reading
+ is wrong, but a rubric scoring components one at a time will score
+ these wrong unless it knows where to look.
+ </Text>
+ }
+ />
+
+ <VStack gap={3}>
+ <HStack gap={3} wrap="wrap" vAlign="end">
+ <SegmentedControl
+ label="Filter by verdict"
+ value={verdict}
+ onChange={setVerdict}
+ size="sm">
+ <SegmentedControlItem value="all" label="All" />
+ <SegmentedControlItem value="GOOD" label="GOOD" />
+ <SegmentedControlItem value="PARTIAL" label="PARTIAL" />
+ <SegmentedControlItem value="ADD" label="ADD" />
+ <SegmentedControlItem value="NONE" label="NONE" />
+ </SegmentedControl>
+ <SegmentedControl
+ label="Filter by status"
+ value={status}
+ onChange={setStatus}
+ size="sm">
+ <SegmentedControlItem value="all" label="All" />
+ <SegmentedControlItem value="built" label="Built" />
+ <SegmentedControlItem value="specified" label="Specified" />
+ </SegmentedControl>
+ <TextInput
+ label="Search"
+ isLabelHidden
+ placeholder="Search components, gaps, hard cases"
+ value={query}
+ onChange={setQuery}
+ hasClear
+ width={280}
+ />
+ <Text type="supporting" color="secondary">
+ {`${filtered.length} of ${PREVIEW_PLAN.length}`}
+ </Text>
+ </HStack>
+
+ {filtered.length === 0 ? (
+ <EmptyState
+ title="Nothing matches"
+ description="No row matches that combination of verdict, status and search."
+ />
+ ) : (
+ PREVIEW_GROUPS.map(group => {
+ const rows = filtered.filter(row => row.group === group);
+ if (rows.length === 0) {
+ return null;
+ }
+ return (
+ <VStack key={group} gap={2}>
+ <HStack gap={2} vAlign="center">
+ <Heading level={2}>{group}</Heading>
+ <Badge label={`${rows.length}`} />
+ </HStack>
+ <Grid columns={{minWidth: 420}} gap={3}>
+ {rows.map(row => (
+ <RowCard key={row.id} row={row} />
+ ))}
+ </Grid>
+ </VStack>
+ );
+ })
+ )}
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Build queue</Heading>
+ <Text color="secondary">
+ {`The ${specified.length} specified previews in priority order. P1 rows each settle an open question, so they are worth building before the decision meeting rather than after it.`}
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Priority</TableHeaderCell>
+ <TableHeaderCell>Component</TableHeaderCell>
+ <TableHeaderCell>Surface</TableHeaderCell>
+ <TableHeaderCell>Why it is worth building</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {queue.map(row => (
+ <TableRow key={row.id}>
+ <TableCell>
+ <Badge
+ variant={
+ row.priority === 1
+ ? 'error'
+ : row.priority === 2
+ ? 'warning'
+ : 'neutral'
+ }
+ label={`P${row.priority}`}
+ />
+ </TableCell>
+ <TableCell>
+ <Text weight="semibold">{row.component}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.group}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.hardCase}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/previews.tsx b/apps/sandbox/src/motion/pages/previews.tsx
new file mode 100644
index 0000000000..d4417e44b2
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/previews.tsx
@@ -0,0 +1,287 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input LabDemos rigs, the lab store
+ * @output The coverage work, each as a working before-and-after
+ * @position /motion/previews
+ *
+ * The "where to start" list from the brief, minus the presence work that has
+ * its own page. Ordered by user-visible impact per unit of work, which is the
+ * order the brief argues for and the order these should be picked up in.
+ */
+
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {LabPage} from '../PageFrame';
+import {ComparePanes, DemoBody, DemoCard, TokenSlider} from '../LabPrimitives';
+import {
+ CheckTickRig,
+ ChipRig,
+ DisclosureRig,
+ ListReorderRig,
+ RailRig,
+ SkeletonSwapRig,
+ StatCountRig,
+ TabIndicatorRig,
+} from '../LabDemos';
+
+export default function PreviewsPage() {
+ return (
+ <LabPage
+ title="Live previews"
+ intro="The coverage work, each as a working before-and-after. Every control writes a real token, so a value settled here is settled everywhere. Turn the rail up to 4× to judge a curve, then back to 1× to judge whether it is too slow — those are different questions and they need different speeds."
+ decides="Sliding indicators, disclosure convergence, the rail, chips, skeletons, lists.">
+ <Banner
+ status="info"
+ title="Ordered by impact per unit of work"
+ description={
+ <Text>
+ This is the brief&rsquo;s where-to-start list with the presence work
+ removed, since that has{' '}
+ <Link href="/motion/exit-gap">its own page</Link> and is the one
+ thing here blocked on a policy decision. Everything below is
+ unblocked and can start as soon as the tokens land.
+ </Text>
+ }
+ />
+
+ <DemoCard
+ title="Sliding indicators"
+ question="TabList and SegmentedControl share one decision. A travelling indicator crossing five tabs feels different from one crossing two — judge it on the long jump, not the short one."
+ badges={<Badge variant="error" label="ADD" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — per-item cross-fade',
+ content: <TabIndicatorRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — one indicator travels',
+ content: <TabIndicatorRig mode="after" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <TokenSlider token="--duration-reveal" label="travel" max={700} />
+ <Text type="supporting" color="secondary">
+ The proposed pane uses <code>--ease-move</code> rather than the
+ entry curve, because the indicator is already on screen: it needs a
+ legible path, not an arrival accent. This is also the strongest
+ candidate for the <code>layout</code> spring, since a travelling
+ indicator is exactly the interruptible case.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Disclosure bake-off"
+ question="Nine surfaces, three techniques, and the newest component uses the one nobody else does. Settle it before more disclosure surfaces get built."
+ badges={<Badge variant="warning" label="PARTIAL — three techniques" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'neutral',
+ label: 'Grid tracks — CodeBlock, Chat',
+ content: <DisclosureRig technique="grid" title="Grid tracks" />,
+ },
+ {
+ tone: 'neutral',
+ label: 'Height interpolation',
+ content: <DisclosureRig technique="height" title="Height" />,
+ },
+ {
+ tone: 'after',
+ label: 'Height + offset fade — Collapsible',
+ content: <DisclosureRig technique="offset" title="Collapsible" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <TokenSlider token="--duration-reveal" label="reveal" max={700} />
+ <Text type="supporting" color="secondary">
+ There is probably no single winner. A table row cannot be a grid
+ container, so Table row expansion and Table tree cannot use the
+ grid-track technique whatever the bake-off concludes. The realistic
+ outcome is one default plus a documented exception — which is worth
+ writing down as the decision, rather than discovering it halfway
+ through the convergence work.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="SideNav rail collapse"
+ question="The rail's own width, not just the chevron. width is a layout property, so this is a deliberate criterion-6 exception — does it earn one?"
+ badges={<Badge variant="error" label="ADD" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — only the chevron rotates',
+ content: <RailRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — the rail animates',
+ content: <RailRig mode="after" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting" color="secondary">
+ The transform alternative — translate the rail and clip it — keeps
+ the animation on the compositor but leaves the content beside it
+ un-reflowed until the end, which reads worse than the layout cost.
+ Worth prototyping both before granting the exception.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Skeleton → content"
+ question="The archetypal hard swap. The failure is that it happens at a moment the user cannot predict."
+ badges={<Badge variant="error" label="ADD" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — content hard-swaps',
+ content: <SkeletonSwapRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — crossfade with overlap',
+ content: <SkeletonSwapRig mode="after" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <TokenSlider token="--duration-state" label="crossfade" max={400} />
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Chip add and remove"
+ question="Tokenizer, Token and FileInput share this. Removal is the hard half: the chip has to leave while its neighbours close the gap."
+ badges={<Badge variant="error" label="ADD" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — instant',
+ content: <ChipRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — scale in, accelerate away',
+ content: <ChipRig mode="after" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <TokenSlider token="--duration-enter" label="add" max={500} />
+ <TokenSlider token="--duration-exit" label="remove" max={500} />
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="List add, remove and reorder"
+ question="Reorder is movement the user did not initiate, so it has to be followable. This is the strongest argument for the layout spring."
+ badges={<Badge variant="error" label="ADD" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — instant',
+ content: <ListReorderRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — FLIP on --ease-move',
+ content: <ListReorderRig mode="after" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting" color="secondary">
+ FLIP — measure, move, invert, play — is the technique here because
+ the rows are genuinely re-laid-out and only the visual correction is
+ animated. Try it at 4×: a shuffle that is legible at 4× and
+ illegible at 1× means the duration is too short, not that the
+ technique is wrong.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <Grid columns={{minWidth: 420}} gap={4}>
+ <DemoCard
+ title="Checkbox tick"
+ question="A high-frequency surface, so criterion 2 applies: the answer may be that it should be almost nothing."
+ badges={<Badge variant="error" label="ADD" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today',
+ content: <CheckTickRig technique="hard" />,
+ },
+ {
+ tone: 'neutral',
+ label: 'Draw',
+ content: <CheckTickRig technique="draw" />,
+ },
+ {
+ tone: 'after',
+ label: 'Scale',
+ content: <CheckTickRig technique="scale" />,
+ },
+ ]}
+ />
+ </DemoCard>
+
+ <DemoCard
+ title="Stat value change"
+ question="A change of 4 and a change of 4,000 look identical today. Needs a delta threshold, or a jump from 12 to 1,300,000 spins for a second."
+ badges={<Badge variant="error" label="ADD" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — replaces itself',
+ content: <StatCountRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — counts',
+ content: <StatCountRig mode="after" />,
+ },
+ ]}
+ />
+ </DemoCard>
+ </Grid>
+
+ <VStack gap={2}>
+ <Heading level={2}>What is not here</Heading>
+ <Text color="secondary">
+ Around twenty more previews are specified but not built —
+ ContextMenu&rsquo;s pointer-anchored origin, CommandPalette filter
+ motion, TreeList depth, TransferList&rsquo;s cross-container move,
+ Carousel, Calendar month change, Slider keyboard step, Resizable snap.
+ Each one has a written brief saying what it must demonstrate, on{' '}
+ <Link href="/motion/preview-plan">Preview plan</Link>. The ones above
+ were built first because each settles a decision that blocks other
+ work.
+ </Text>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/published.tsx b/apps/sandbox/src/motion/pages/published.tsx
new file mode 100644
index 0000000000..b56225baa7
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/published.tsx
@@ -0,0 +1,281 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input GUIDANCE_CONFLICTS and PUBLISHED_SECTIONS
+ * @output The proposal beside what astryx.atmeta.com/docs/motion tells authors
+ * @position /motion/published
+ *
+ * The exit gap and the delete-don't-degrade behaviour are both documented
+ * guidance, correctly followed. That makes two of the proposals policy
+ * reversals rather than bug fixes, which changes who has to sign them off and
+ * what has to ship in the same stack. Every card here is one conflict; nothing
+ * on the page is written by hand except the reading of it.
+ */
+
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {Link as AstryxLink} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import type {ReactNode} from 'react';
+import {ComparePanes, DemoCard} from '../LabPrimitives';
+import {LayerRig, LoopRig} from '../LabDemos';
+import {LabPage} from '../PageFrame';
+import {
+ GUIDANCE_CONFLICTS,
+ PUBLISHED_PAGE_URL,
+ PUBLISHED_SECTIONS,
+ type GuidanceConflict,
+} from '../publishedGuidance';
+
+type Severity = GuidanceConflict['severity'];
+
+const SEVERITY: Record<
+ Severity,
+ {
+ readonly variant: 'error' | 'warning' | 'success';
+ readonly question: string;
+ }
+> = {
+ reversal: {
+ variant: 'error',
+ question:
+ 'Two documents give opposite instructions. One of them has to move first.',
+ },
+ extension: {
+ variant: 'warning',
+ question:
+ 'The page is not wrong, it is incomplete. Does the proposal extend it or replace it?',
+ },
+ aligned: {
+ variant: 'success',
+ question:
+ 'No conflict. Can the rubric cite this paragraph instead of re-arguing it?',
+ },
+};
+
+/** `exit-optional` -> `Exit optional`. The data carries no title, so derive one. */
+function titleOf(id: string): string {
+ const words = id.replace(/-/g, ' ');
+ return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/**
+ * Only two conflicts can be settled by looking rather than reading, and both
+ * are the reversals. The rest are arguments about wording.
+ */
+function demoFor(id: string, tone: 'before' | 'after'): ReactNode {
+ if (id === 'exit-optional') {
+ return tone === 'before' ? (
+ <LayerRig mode="before" label="Tooltip content" triggerLabel="Hover me" />
+ ) : (
+ <LayerRig mode="after" label="Tooltip content" triggerLabel="Hover me" />
+ );
+ }
+ if (id === 'reduced-motion-delete') {
+ return tone === 'before' ? (
+ <LoopRig policy="delete" />
+ ) : (
+ <LoopRig policy="degrade" />
+ );
+ }
+ return null;
+}
+
+function Quote({text, demo}: {text: string; demo: ReactNode}) {
+ return (
+ <VStack gap={3}>
+ <Card padding={3}>
+ <Text>{`\u201C${text}\u201D`}</Text>
+ </Card>
+ {demo}
+ </VStack>
+ );
+}
+
+export default function PublishedGuidancePage() {
+ const reversals = GUIDANCE_CONFLICTS.filter(c => c.severity === 'reversal');
+ const extensions = GUIDANCE_CONFLICTS.filter(c => c.severity === 'extension');
+ const aligned = GUIDANCE_CONFLICTS.filter(c => c.severity === 'aligned');
+ const rewriteSections = new Set(reversals.map(c => c.section));
+ const noted = PUBLISHED_SECTIONS.filter(s => s.stale != null);
+
+ return (
+ <LabPage
+ title="Against the published page"
+ intro="Every proposal in the brief, beside the paragraph of astryx.atmeta.com/docs/motion it lands on. Quotes are verbatim, so this page can be diffed against the live one."
+ badges={<Badge variant="error" label={`${reversals.length} reversals`} />}
+ decides="Which proposals are bug fixes and which are reversals of guidance Astryx publishes today.">
+ <Banner
+ status="error"
+ title={`${reversals.length} of the ${GUIDANCE_CONFLICTS.length} conflicts reverse published guidance`}
+ description={
+ <Text>
+ The brief reads the exit gap as historical accident. It is not: the
+ published Movement Principles tell authors that tooltips, hover
+ cards and dropdown menus may disappear instantly, and Respecting
+ User Preferences tells them to replace animation with instant state
+ changes. Those two proposals are{' '}
+ <strong>policy changes, not bug fixes</strong> — they need a
+ decision and an owner rather than a diff. The doc rewrite has to
+ ship in the same stack as the code, or the rubric starts failing
+ components for doing what the docs still tell the next author to do.
+ </Text>
+ }
+ endContent={
+ <AstryxLink
+ href={PUBLISHED_PAGE_URL}
+ target="_blank"
+ rel="noopener noreferrer">
+ Read the live page
+ </AstryxLink>
+ }
+ />
+
+ <HStack gap={2} wrap="wrap">
+ <Badge variant="error" label={`${reversals.length} reversals`} />
+ <Badge variant="warning" label={`${extensions.length} extensions`} />
+ <Badge variant="success" label={`${aligned.length} aligned`} />
+ <Text type="supporting" color="secondary">
+ Severity is about the document, not the code: a reversal means the
+ published page has to change before the proposal is legitimate.
+ </Text>
+ </HStack>
+
+ {GUIDANCE_CONFLICTS.map(conflict => (
+ <DemoCard
+ key={conflict.id}
+ title={titleOf(conflict.id)}
+ question={SEVERITY[conflict.severity].question}
+ badges={
+ <>
+ <Badge
+ variant={SEVERITY[conflict.severity].variant}
+ label={conflict.severity}
+ />
+ <Badge label={conflict.section} />
+ </>
+ }
+ actions={
+ <Button
+ variant="ghost"
+ size="sm"
+ label="See it in the lab"
+ href={conflict.href}
+ />
+ }
+ controls={
+ <VStack gap={3}>
+ <VStack gap={1}>
+ <Text type="label" weight="semibold">
+ Reading
+ </Text>
+ <Text color="secondary">{conflict.reading}</Text>
+ </VStack>
+ <VStack gap={1}>
+ <Text type="label" weight="semibold">
+ Resolution
+ </Text>
+ <Text color="secondary">{conflict.resolution}</Text>
+ </VStack>
+ </VStack>
+ }>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: `Published today — ${conflict.section}`,
+ content: (
+ <Quote
+ text={conflict.published}
+ demo={demoFor(conflict.id, 'before')}
+ />
+ ),
+ },
+ {
+ tone: 'after',
+ label: 'Proposed in the brief',
+ content: (
+ <Quote
+ text={conflict.proposed}
+ demo={demoFor(conflict.id, 'after')}
+ />
+ ),
+ },
+ ]}
+ />
+ </DemoCard>
+ ))}
+
+ <VStack gap={3}>
+ <Heading level={2}>Scope of the doc rewrite</Heading>
+ <Text color="secondary">
+ {`${noted.length} of the ${PUBLISHED_SECTIONS.length} sections of the live page need something. Two of them are the reversals above and cannot be deferred: the rubric has no authority while the page contradicts it. The rest are additions — the page is accurate about what exists, and silent about how to choose.`}
+ </Text>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Section</TableHeaderCell>
+ <TableHeaderCell>What it says today</TableHeaderCell>
+ <TableHeaderCell>Scope</TableHeaderCell>
+ <TableHeaderCell>Note</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {PUBLISHED_SECTIONS.map(section => {
+ const isRewrite = rewriteSections.has(section.title);
+ return (
+ <TableRow key={section.title}>
+ <TableCell>
+ <Text weight="semibold">{section.title}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {section.summary}
+ </Text>
+ </TableCell>
+ <TableCell>
+ {isRewrite ? (
+ <Badge variant="error" label="Rewrite" />
+ ) : section.stale != null ? (
+ <Badge variant="warning" label="Add to" />
+ ) : (
+ <Badge label="No change" />
+ )}
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {section.stale ?? '\u2014'}
+ </Text>
+ </TableCell>
+ </TableRow>
+ );
+ })}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+
+ <Text type="supporting" color="secondary">
+ The rewrite is a deliverable in the brief already, listed last. On this
+ reading it is a gate on the rubric rather than a write-up of work
+ already done, which moves it earlier in the sequence than the timeline
+ has it.
+ </Text>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/reduced-motion.tsx b/apps/sandbox/src/motion/pages/reduced-motion.tsx
new file mode 100644
index 0000000000..e12cbc149f
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/reduced-motion.tsx
@@ -0,0 +1,515 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input The generated audit, the published guidance, the lab store
+ * @output Degrade or delete, with the sweep's worklist attached
+ * @position /motion/reduced-motion
+ *
+ * The page's primary control is the rail's Reduced motion switch, not anything
+ * rendered here. It drives the real policy for every demo in the lab, so the
+ * argument is made by flipping it and watching rather than by reading a
+ * caption about what would happen.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {LabPage} from '../PageFrame';
+import {ComparePanes, DemoBody, DemoCard} from '../LabPrimitives';
+import {LoopRig, TintRig} from '../LabDemos';
+import {useMotionLab, type ReducedMotionMode} from '../MotionLabStore';
+import {
+ AUDIT_COUNTS,
+ HARDCODED_SITES,
+ NO_REDUCED_MOTION,
+} from '../__generated__/motionAudit';
+import {GUIDANCE_CONFLICTS, PUBLISHED_PAGE_URL} from '../publishedGuidance';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ mono: {fontFamily: 'var(--font-family-code)', fontSize: '12px'},
+ quote: {
+ borderInlineStart: '2px solid var(--color-border)',
+ paddingInlineStart: '12px',
+ maxWidth: '64ch',
+ },
+});
+
+const BRIEF_FIGURE = 39;
+
+const MODE_LABEL: Readonly<Record<ReducedMotionMode, string>> = {
+ off: 'Off',
+ degrade: 'Degrade',
+ delete: 'Delete',
+};
+
+/** The sweep's worklist: every animated file with no reduced-motion branch. */
+const WORKLIST = [
+ ...NO_REDUCED_MOTION.reduce((acc, row) => {
+ const files = acc.get(row.component) ?? [];
+ files.push(row.file);
+ acc.set(row.component, files);
+ return acc;
+ }, new Map<string, string[]>()),
+].sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]));
+
+const INSTANT_ESCAPES = HARDCODED_SITES.filter(site => site.value === '0.01s');
+
+const POLICIES: ReadonlyArray<{
+ readonly policy: string;
+ readonly survives: string;
+ readonly forIt: string;
+ readonly againstIt: string;
+ readonly status: string;
+}> = [
+ {
+ policy: 'Delete',
+ survives:
+ 'Nothing. Transitions collapse to zero, loops stop, the end state arrives on the same frame as the change.',
+ forIt:
+ 'Safest reading of the accessibility guidance: a user who asked for no motion gets no motion, with no argument about which motion was the harmful kind. Trivially lintable, and it is one line per file.',
+ againstIt:
+ 'Deletes feedback that happens to be implemented as a transition. A hover tint, a focus ring fade and a spinner all disappear together, and the spinner leaves nothing behind that says "working".',
+ status:
+ 'What the published page instructs today, and what most of core does.',
+ },
+ {
+ policy: 'Degrade',
+ survives:
+ 'Opacity and colour. Movement multipliers go to zero; loops stop and are replaced with a determinate state.',
+ forIt:
+ 'Keeps state feedback while removing the vestibular trigger, which is what both of the project\u2019s references recommend. The thing that hurts is movement, not the fact that a colour took 175ms to arrive.',
+ againstIt:
+ 'Needs a judgement per component about which half is movement, so it is not a one-line sweep. Gets it wrong quietly: a fade that survives on a surface that also travels is still motion.',
+ status:
+ 'What rubric criterion 10 proposes. A change of published policy, not a bug fix.',
+ },
+];
+
+const CSS_RULE = `/* Movement is a multiplier, so the policy has one place to land. */
+.surface {
+ --motion-translate: 1;
+ --motion-scale: 1;
+ transform: translateY(calc(8px * var(--motion-translate)))
+ scale(calc(1 - 0.06 * var(--motion-scale)));
+ transition:
+ transform var(--duration-enter) var(--ease-entry),
+ opacity var(--duration-enter) var(--ease-entry),
+ background-color var(--duration-state) var(--ease-state);
+}
+
+/* Degrade: movement goes, opacity and colour stay. Not display: none for
+ motion — the feedback is the point, the travel is the problem. */
+@media (prefers-reduced-motion: reduce) {
+ .surface {
+ --motion-translate: 0;
+ --motion-scale: 0;
+ }
+
+ /* Loops stop. They do not slow down: slower vestibular motion is still
+ vestibular motion, and a 3s spinner reads as a hung interface. */
+ .spinner,
+ .progressIndeterminate {
+ animation: none;
+ }
+}
+
+/* Hover motion is gated on a fine pointer as well. A touch device fires a
+ hover on tap, so an un-gated hover animation runs on every tap. */
+@media (hover: hover) and (pointer: fine) {
+ .row:hover {
+ transform: translateY(calc(-1px * var(--motion-translate)));
+ }
+}
+
+/* An app with its own reduce-motion setting can flip a JS library but cannot
+ flip a media query, so the same rules answer to an attribute too. */
+[data-reduced-motion='reduce'] .surface {
+ --motion-translate: 0;
+ --motion-scale: 0;
+}`;
+
+const HOOK = `/**
+ * The JS half of the same policy. Charts, canvas and any motion library read
+ * this; CSS reads the media query. They have to agree, or a chart animates
+ * while the interface around it does not.
+ */
+export function useReducedMotion(): boolean {
+ const [reduced, setReduced] = useState(() =>
+ typeof window === 'undefined'
+ ? false
+ : window.matchMedia('(prefers-reduced-motion: reduce)').matches,
+ );
+
+ useEffect(() => {
+ const query = window.matchMedia('(prefers-reduced-motion: reduce)');
+ const onChange = (event: MediaQueryListEvent) => setReduced(event.matches);
+ query.addEventListener('change', onChange);
+ return () => query.removeEventListener('change', onChange);
+ }, []);
+
+ // The app-level override, so a product setting can force the policy on
+ // without touching the OS. Same attribute the CSS above answers to.
+ const forced = useContext(MotionPreferenceContext);
+ return forced ?? reduced;
+}`;
+
+export default function ReducedMotionPage() {
+ const {reducedMotion} = useMotionLab();
+ const conflict = GUIDANCE_CONFLICTS.find(
+ c => c.id === 'reduced-motion-delete',
+ );
+
+ return (
+ <LabPage
+ title="Reduced motion"
+ intro="Degrade or delete. Everything else in the sweep is blocked on this answer, because the branch gets written once per file and there are 36 of them."
+ badges={
+ <>
+ <Badge variant="error" label="Criterion 10 — Blocker" />
+ <Badge
+ variant="warning"
+ label={`Rail: ${MODE_LABEL[reducedMotion]}`}
+ />
+ </>
+ }
+ decides="Degrade or delete. The decision the 36-file sweep is waiting on.">
+ <Banner
+ status="info"
+ title="Use the Reduced motion switch in the rail above"
+ description={
+ <Text>
+ It is the page&rsquo;s primary control, not a caption: it drives the
+ real policy for every demo in the lab, on this page and every other
+ one. Set it to <strong>Delete</strong>, then{' '}
+ <strong>Degrade</strong>, and watch the same components under each.
+ Right now it is set to <strong>{MODE_LABEL[reducedMotion]}</strong>.
+ </Text>
+ }
+ />
+
+ <VStack gap={3}>
+ <Heading level={2}>The sweep&rsquo;s worklist</Heading>
+ <Text color="secondary">
+ {AUDIT_COUNTS.filesWithoutReducedMotion} of{' '}
+ {AUDIT_COUNTS.animatedFiles} animated files have no{' '}
+ <code>prefers-reduced-motion</code> branch at all — measured against
+ the installed package. The brief says {BRIEF_FIGURE}; the gap is
+ counting method rather than a disagreement worth chasing, but the list
+ below is the one to work from because it names the files.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Component</TableHeaderCell>
+ <TableHeaderCell>Files</TableHeaderCell>
+ <TableHeaderCell>Paths</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {WORKLIST.map(([component, files]) => (
+ <TableRow key={component}>
+ <TableCell>
+ <Text weight="semibold">{component}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {files.length}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {files.join(' · ')}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ {WORKLIST[0]?.[0]} carries {WORKLIST[0]?.[1].length} of them and{' '}
+ {WORKLIST[1]?.[0]} {WORKLIST[1]?.[1].length}, so two components are
+ more than a quarter of the sweep. Both are also the components where a
+ wrong answer is most visible.
+ </Text>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Degrade or delete</Heading>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Policy</TableHeaderCell>
+ <TableHeaderCell>What survives</TableHeaderCell>
+ <TableHeaderCell>For</TableHeaderCell>
+ <TableHeaderCell>Against</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {POLICIES.map(row => (
+ <TableRow key={row.policy}>
+ <TableCell>
+ <VStack gap={1}>
+ <Text weight="semibold">{row.policy}</Text>
+ <Text type="supporting" color="secondary">
+ {row.status}
+ </Text>
+ </VStack>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting">{row.survives}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.forIt}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.againstIt}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ {conflict != null && (
+ <Card padding={4}>
+ <VStack gap={2}>
+ <HStack gap={2} vAlign="center" wrap="wrap">
+ <Text weight="semibold">
+ This is a change of published policy, not a bug fix
+ </Text>
+ <Badge variant="error" label="Reversal" />
+ </HStack>
+ <VStack gap={1} {...stylex.props(sx.quote)}>
+ <Text type="supporting" color="secondary">
+ &ldquo;{conflict.published}&rdquo; — {conflict.section},
+ published today
+ </Text>
+ </VStack>
+ <Text type="supporting">{conflict.reading}</Text>
+ <Text type="supporting" color="secondary">
+ {conflict.resolution}
+ </Text>
+ <Text type="supporting" color="secondary">
+ <Link href="/motion/published">
+ The conflicts, side by side
+ </Link>{' '}
+ ·{' '}
+ <Link
+ href={PUBLISHED_PAGE_URL}
+ target="_blank"
+ rel="noopener noreferrer">
+ the published page
+ </Link>
+ </Text>
+ </VStack>
+ </Card>
+ )}
+ </VStack>
+
+ <DemoCard
+ title="The three policies, running"
+ question="A spinner, a pulse and an indeterminate bar under each answer. Which of these still tells you the system is working?">
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — loops slow to 3s',
+ content: <LoopRig policy="today" />,
+ },
+ {
+ tone: 'neutral',
+ label: 'Delete — the published answer',
+ content: <LoopRig policy="delete" />,
+ },
+ {
+ tone: 'after',
+ label: 'Degrade — the proposed answer',
+ content: <LoopRig policy="degrade" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting" color="secondary">
+ Slowing a loop is the one answer nobody is arguing for and the one
+ the code does today. Between the other two, the question is not
+ whether the spinner keeps spinning — it does not, either way — but
+ whether anything replaces it.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Hover the rows, then flip the rail"
+ question="The tint is state feedback that happens to be implemented as a transition. Does the policy take the feedback or only the fade?">
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Hardcoded 150ms',
+ content: <TintRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Tokenised --duration-state',
+ content: <TintRig mode="after" />,
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting">
+ Set the rail to <strong>Degrade</strong> and hover: movement stops
+ across the lab and these rows keep their fade. Colour is not
+ movement, and this tint is exactly the feedback degrade exists to
+ preserve — which is why delete is defensible on a hover tint and
+ indefensible on a spinner, where the motion <em>is</em> the message.
+ </Text>
+ <Text type="supporting" color="secondary">
+ The left pane makes the token argument at the same time: it
+ hardcodes 150ms, so it fades identically under every policy. A
+ literal cannot be reached by a switch, a media query or a sweep.
+ </Text>
+ <Text type="supporting" color="secondary">
+ <strong>Try it: </strong>on <strong>Degrade</strong> the right pane
+ keeps its tint and loses only movement — the state feedback
+ survives. On <strong>Delete</strong> the tint snaps, and the
+ affordance goes with it. That is the whole decision, in one hover.
+ (This behaviour was itself a bug in the lab until the policy was
+ moved out of the stylesheet: the store writes the duration aliases
+ inline, and an inline custom property outranks any selector, so the
+ delete rule looked right and did nothing.)
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <VStack gap={3}>
+ <Heading level={2}>
+ The <code>0.01s</code> finding
+ </Heading>
+ <Text color="secondary">
+ {INSTANT_ESCAPES.length} of the {AUDIT_COUNTS.hardcodedTotal}{' '}
+ hardcoded values are <code>0.01s</code>, and every one is a
+ reduced-motion escape in BottomSheet, DateInput or MobileNav. This is
+ load-bearing, not sloppiness: a zero duration fires no{' '}
+ <code>transitionend</code>, so anything sequencing off that event — an
+ unmount, a focus return, a scroll lock release — never runs. The idiom
+ is a component author working around the platform.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Site</TableHeaderCell>
+ <TableHeaderCell>Component</TableHeaderCell>
+ <TableHeaderCell>Property</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {INSTANT_ESCAPES.map(site => (
+ <TableRow key={`${site.file}:${site.line}`}>
+ <TableCell>
+ <Text
+ {...stylex.props(
+ sx.mono,
+ )}>{`${site.file}:${site.line}`}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {site.component}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {site.prop}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Grid columns={{minWidth: 300}} gap={3}>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">
+ <code>--duration-instant</code> cannot be assumed to be 0
+ </Text>
+ <Text type="supporting" color="secondary">
+ Ship it as <code>0.01ms</code> and every existing sequencing
+ path keeps working, at a cost no user can perceive. Ship it as{' '}
+ <code>0</code> and these ten sites have to be rewritten to await
+ something else in the same change — which is a different, larger
+ piece of work than the sweep is scoped for.
+ </Text>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={1.5}>
+ <Text weight="semibold">
+ Decide it before the sweep, not during
+ </Text>
+ <Text type="supporting" color="secondary">
+ The sweep rewrites these ten lines whichever way the token goes.
+ Deciding halfway through means two idioms in the codebase and a
+ lint rule that cannot tell which one it is looking at.
+ </Text>
+ </VStack>
+ </Card>
+ </Grid>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>The rule, as code</Heading>
+ <Text color="secondary">
+ What a component author copies. Movement is a multiplier so the policy
+ lands in one place; loops stop rather than slow; hover motion is gated
+ on a fine pointer because touch fires a hover on tap; and the
+ attribute branch exists because an app with its own reduce-motion
+ setting can flip a JS library but cannot flip a media query.
+ </Text>
+ <CodeBlock
+ language="css"
+ title="The degrade branch"
+ code={CSS_RULE}
+ hasCopyButton
+ maxHeight={420}
+ />
+ <CodeBlock
+ language="tsx"
+ title="useReducedMotion() — the JS half of the same policy"
+ code={HOOK}
+ hasCopyButton
+ maxHeight={420}
+ />
+ <Text type="supporting" color="secondary">
+ Both halves ship together or the system disagrees with itself: a chart
+ that animates while the interface around it has stopped is worse than
+ either policy applied consistently.
+ </Text>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/rubric.tsx b/apps/sandbox/src/motion/pages/rubric.tsx
new file mode 100644
index 0000000000..c8047abcfd
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/rubric.tsx
@@ -0,0 +1,743 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input rubric.ts, the generated audit, the published guidance
+ * @output The rubric as a bench: every criterion with a pass and a fail running
+ * @position /motion/rubric
+ *
+ * A rubric that is only a table gets read once and then argued about from
+ * memory. Every criterion here that can be shown is shown, so "the exit is on
+ * the wrong curve" is something you look at rather than something you take on
+ * trust.
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {LabPage} from '../PageFrame';
+import {
+ BudgetMeter,
+ ComparePanes,
+ DemoBody,
+ DemoCard,
+ Runner,
+ TokenSlider,
+} from '../LabPrimitives';
+import {
+ CheckTickRig,
+ InterruptRig,
+ LayerRig,
+ LoopRig,
+ OriginRig,
+ OutlineMarkerRig,
+ PressRig,
+} from '../LabDemos';
+import {
+ AUDIT_COUNTS,
+ HARDCODED_SITES,
+ NO_REDUCED_MOTION,
+ TRANSFORM_TRANSITIONS,
+} from '../__generated__/motionAudit';
+import {
+ AUTOMATABLE_LABEL,
+ GRANDFATHERING,
+ MISSING_PRINCIPLE,
+ PASS_BAR,
+ RUBRIC_CRITERIA,
+ SEVERITY_LABEL,
+ SEVERITY_RULES,
+ type Automatable,
+ type Criterion,
+ type Severity,
+} from '../rubric';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ mono: {fontFamily: 'var(--font-family-code)', fontSize: '12px'},
+ verdict: {
+ borderInlineStart: '2px solid var(--color-border)',
+ paddingInlineStart: '10px',
+ },
+ pass: {borderInlineStartColor: 'var(--color-background-success, #3f9a6b)'},
+ fail: {borderInlineStartColor: 'var(--color-background-error, #d3543f)'},
+ quote: {
+ borderInlineStart: '2px solid var(--color-border)',
+ paddingInlineStart: '12px',
+ maxWidth: '64ch',
+ },
+});
+
+const SEVERITY_VARIANT: Readonly<
+ Record<Severity, 'error' | 'warning' | 'neutral'>
+> = {
+ blocker: 'error',
+ 'should-fix': 'warning',
+ polish: 'neutral',
+};
+
+const AUTOMATABLE_VARIANT: Readonly<
+ Record<Automatable, 'success' | 'info' | 'neutral'>
+> = {
+ yes: 'success',
+ partly: 'info',
+ no: 'neutral',
+};
+
+/** Only the criteria that can be watched get a rig; the rest say why not. */
+function demoFor(id: string): ReactNode {
+ switch (id) {
+ case 'frequency':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label:
+ 'Fails — a tick that draws itself, on a control used forty times in a form',
+ content: <CheckTickRig technique="draw" />,
+ },
+ {
+ tone: 'after',
+ label: 'Passes — instant, because this is a 100+/day interaction',
+ content: <CheckTickRig technique="hard" />,
+ },
+ ]}
+ />
+ );
+ case 'semantic':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Fails — exit duration on the entry curve',
+ content: (
+ <Runner
+ durationToken="--duration-exit"
+ easeToken="--ease-entry"
+ />
+ ),
+ },
+ {
+ tone: 'after',
+ label: 'Passes — exit duration on the exit curve',
+ content: (
+ <Runner
+ durationToken="--duration-exit"
+ easeToken="--ease-exit"
+ />
+ ),
+ },
+ ]}
+ />
+ );
+ case 'budget':
+ return (
+ <DemoBody>
+ <Runner durationToken="--duration-enter" easeToken="--ease-entry" />
+ <TokenSlider
+ token="--duration-enter"
+ label="--duration-enter"
+ min={0}
+ max={900}
+ />
+ <BudgetMeter token="--duration-enter" />
+ </DemoBody>
+ );
+ case 'compositor':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Fails — animates top and height',
+ content: <OutlineMarkerRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Passes — transform only',
+ content: <OutlineMarkerRig mode="after" />,
+ },
+ ]}
+ />
+ );
+ case 'presence':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Fails the criterion — and follows the published page',
+ content: (
+ <LayerRig
+ mode="before"
+ label="No exit at all"
+ triggerLabel="Hover me"
+ />
+ ),
+ },
+ {
+ tone: 'after',
+ label: 'Passes — exit retraces the entry, faster',
+ content: (
+ <LayerRig
+ mode="after"
+ label="Exits on --duration-exit"
+ triggerLabel="Hover me"
+ />
+ ),
+ },
+ ]}
+ />
+ );
+ case 'origin':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Fails — scale(0)',
+ content: <OriginRig kind="zero" />,
+ },
+ {
+ tone: 'neutral',
+ label: 'Half right — 0.94, wrong origin',
+ content: <OriginRig kind="centre" />,
+ },
+ {
+ tone: 'after',
+ label: 'Passes — anchored to the trigger',
+ content: <OriginRig kind="anchored" />,
+ },
+ ]}
+ />
+ );
+ case 'interruptible':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Fails — a keyframe restarts from zero',
+ content: <InterruptRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Passes — a transition retargets',
+ content: <InterruptRig mode="after" />,
+ },
+ ]}
+ />
+ );
+ case 'reduced-motion':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — loops slow to 3s',
+ content: <LoopRig policy="today" />,
+ },
+ {
+ tone: 'neutral',
+ label: 'Delete — what the published page says',
+ content: <LoopRig policy="delete" />,
+ },
+ {
+ tone: 'after',
+ label: 'Degrade — what the criterion says',
+ content: <LoopRig policy="degrade" />,
+ },
+ ]}
+ />
+ );
+ case 'library':
+ return (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Fails — transition on transform',
+ content: <PressRig technique="transform" />,
+ },
+ {
+ tone: 'after',
+ label: 'Passes — press on the scale property',
+ content: <PressRig technique="scale" />,
+ },
+ ]}
+ />
+ );
+ default:
+ return null;
+ }
+}
+
+function Verdict({
+ tone,
+ label,
+ text,
+}: {
+ tone: 'pass' | 'fail';
+ label: string;
+ text: string;
+}) {
+ return (
+ <VStack
+ gap={0.5}
+ {...stylex.props(sx.verdict, tone === 'pass' ? sx.pass : sx.fail)}>
+ <Text type="supporting" weight="semibold">
+ {label}
+ </Text>
+ <Text type="supporting" color="secondary">
+ {text}
+ </Text>
+ </VStack>
+ );
+}
+
+function CriterionCard({criterion}: {criterion: Criterion}) {
+ const demo = demoFor(criterion.id);
+ return (
+ <DemoCard
+ title={`${criterion.n}. ${criterion.title}`}
+ question={criterion.rule}
+ badges={
+ <>
+ <Badge
+ variant={SEVERITY_VARIANT[criterion.severity]}
+ label={SEVERITY_LABEL[criterion.severity]}
+ />
+ <Badge
+ variant={AUTOMATABLE_VARIANT[criterion.automatable]}
+ label={AUTOMATABLE_LABEL[criterion.automatable]}
+ />
+ {criterion.guidance === 'reversal' && (
+ <Badge variant="error" label="Reverses published guidance" />
+ )}
+ {criterion.guidance === 'aligned' && (
+ <Badge variant="success" label="Already published" />
+ )}
+ </>
+ }>
+ <DemoBody>
+ <Grid columns={{minWidth: 260}} gap={3}>
+ <Verdict tone="pass" label="Passes" text={criterion.pass} />
+ <Verdict tone="fail" label="Fails" text={criterion.fail} />
+ </Grid>
+ <Text type="supporting" color="secondary">
+ <strong>Checked by: </strong>
+ {criterion.check}
+ {criterion.severityNote != null ? ` ${criterion.severityNote}` : ''}
+ </Text>
+ {criterion.evidence != null && (
+ <Text type="supporting" color="secondary">
+ <strong>Measured: </strong>
+ {criterion.evidence}
+ </Text>
+ )}
+ {criterion.guidanceNote != null && (
+ <Text type="supporting" color="secondary">
+ <strong>
+ {criterion.guidance === 'reversal'
+ ? 'Contradicts the published Motion page: '
+ : 'Cites the published Motion page: '}
+ </strong>
+ {criterion.guidanceNote}{' '}
+ <Link href="/motion/published">See the conflicts</Link>
+ </Text>
+ )}
+ </DemoBody>
+ {demo}
+ </DemoCard>
+ );
+}
+
+/** The reduced-motion worklist, collapsed to components so it fits on a card. */
+const REDUCED_BY_COMPONENT = [
+ ...NO_REDUCED_MOTION.reduce((acc, row) => {
+ acc.set(row.component, (acc.get(row.component) ?? 0) + 1);
+ return acc;
+ }, new Map<string, number>()),
+].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+
+const MULTI_PROPERTY_TRANSFORMS = TRANSFORM_TRANSITIONS.filter(
+ site => site.decl?.includes(',') === true,
+).length;
+
+const INSTANT_ESCAPES = HARDCODED_SITES.filter(
+ site => site.value === '0.01s',
+).length;
+
+const TABLE_TINTS = HARDCODED_SITES.filter(
+ site => site.value === '150ms' && site.component === 'Table',
+).length;
+
+export default function MotionRubricPage() {
+ const mechanical = RUBRIC_CRITERIA.filter(c => c.automatable === 'yes');
+ const blockers = RUBRIC_CRITERIA.filter(c => c.severity === 'blocker');
+ const reversals = RUBRIC_CRITERIA.filter(c => c.guidance === 'reversal');
+
+ return (
+ <LabPage
+ title="Rubric bench"
+ intro="Twelve criteria, each with a pass and a fail you can watch. Astryx already gates lab-to-core promotion on an accessibility checklist; motion works the same way or it does not work at all — published, graded per component, tracked."
+ badges={
+ <Badge variant="info" label={`${RUBRIC_CRITERIA.length} criteria`} />
+ }
+ decides="Whether each criterion is checkable, and what a pass and a fail look like.">
+ <Banner
+ status="warning"
+ title="The brief says ten graded criteria. Its own table has twelve."
+ description={
+ <Text>
+ Twelve is what the table describes and twelve is what is graded
+ here. Fix the number in Deliverables before publication — a count in
+ a deliverable is the thing that gets quoted back in a review, and
+ nobody recounts the table. Criteria{' '}
+ {reversals.map(c => c.n).join(' and ')} reverse guidance the
+ published Motion page gives today, so the rubric cannot gate on
+ either until that page is rewritten.
+ </Text>
+ }
+ endContent={<Link href="/motion/published">The conflicts</Link>}
+ />
+
+ <VStack gap={3}>
+ <Heading level={2}>How it grades</Heading>
+ <Text color="secondary">{PASS_BAR}</Text>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Severity</TableHeaderCell>
+ <TableHeaderCell>What it means</TableHeaderCell>
+ <TableHeaderCell>Effect on the gate</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {SEVERITY_RULES.map(row => (
+ <TableRow key={row.severity}>
+ <TableCell>
+ <Badge
+ variant={SEVERITY_VARIANT[row.severity]}
+ label={SEVERITY_LABEL[row.severity]}
+ />
+ </TableCell>
+ <TableCell>
+ <Text type="supporting">{row.meaning}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.gate}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ Blockers: {blockers.length} of {RUBRIC_CRITERIA.length}. Mechanical
+ today: {mechanical.length}. A component with two open should-fix items
+ still passes; a third stops it, which is what keeps the second one
+ from becoming permanent.
+ </Text>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>The twelve</Heading>
+ {RUBRIC_CRITERIA.map(criterion => (
+ <CriterionCard key={criterion.id} criterion={criterion} />
+ ))}
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>What the rubric would have caught</Heading>
+ <Text color="secondary">
+ Measured against <code>@astryxdesign/core</code> by the audit script,
+ not read out of the brief. These are the rows a reviewer would have
+ been handed on the day the component landed.
+ </Text>
+
+ <DemoCard
+ title="Criterion 6 — compositor-only"
+ question={`${AUDIT_COUNTS.transformTransitions} transform transitions across ${AUDIT_COUNTS.transformTransitionComponents} components. Every one of them is also a criterion-12 finding.`}>
+ <DemoBody>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Site</TableHeaderCell>
+ <TableHeaderCell>Declaration</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {TRANSFORM_TRANSITIONS.slice(0, 6).map(site => (
+ <TableRow key={`${site.file}:${site.line}`}>
+ <TableCell>
+ <Text
+ {...stylex.props(
+ sx.mono,
+ )}>{`${site.file}:${site.line}`}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {site.decl}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ {MULTI_PROPERTY_TRANSFORMS} of these declare{' '}
+ <code>transform</code> inside a longer property list rather than
+ on its own, so a grep for{' '}
+ <code>transitionProperty: &lsquo;transform&rsquo;</code> finds
+ barely half of them. That is worth knowing before anyone scopes
+ criterion 12 from a search —{' '}
+ <Link href="/motion/bugs">the bugs page has the whole list</Link>,
+ and the count has already moved twice as the scanner improved.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Criterion 10 — reduced motion"
+ question={`${AUDIT_COUNTS.filesWithoutReducedMotion} of ${AUDIT_COUNTS.animatedFiles} animated files have no reduced-motion branch. This is the sweep.`}>
+ <DemoBody>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Component</TableHeaderCell>
+ <TableHeaderCell>Files with no branch</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {REDUCED_BY_COMPONENT.slice(0, 6).map(
+ ([component, count]) => (
+ <TableRow key={component}>
+ <TableCell>
+ <Text>{component}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {count}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ),
+ )}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ Table alone accounts for {REDUCED_BY_COMPONENT[0]?.[1]} of the{' '}
+ {AUDIT_COUNTS.filesWithoutReducedMotion}.{' '}
+ <Link href="/motion/reduced-motion">
+ The full worklist is on the reduced-motion page
+ </Link>
+ , where it also has to wait on degrade-or-delete: the sweep writes
+ whichever answer wins {AUDIT_COUNTS.filesWithoutReducedMotion}{' '}
+ times.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <DemoCard
+ title="Criterion 3 — token fidelity"
+ question={`${AUDIT_COUNTS.hardcodedTotal} hardcoded values: ${AUDIT_COUNTS.hardcodedDuration} durations, ${AUDIT_COUNTS.hardcodedEasing} curves. The brief budgeted for 28.`}>
+ <DemoBody>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Site</TableHeaderCell>
+ <TableHeaderCell>Property</TableHeaderCell>
+ <TableHeaderCell>Value</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {[
+ 'Table/plugins/columnResize/useTableColumnResize.tsx',
+ 'BottomSheet/BottomSheetPanel.tsx',
+ 'StatusDot/StatusDot.tsx',
+ 'Chat/ChatMessageMetadata.tsx',
+ 'hooks/useKeyboardHint.tsx',
+ 'Button/Button.tsx',
+ ]
+ .map(file =>
+ HARDCODED_SITES.find(site => site.file === file),
+ )
+ .filter(
+ (site): site is (typeof HARDCODED_SITES)[number] =>
+ site != null,
+ )
+ .map(site => (
+ <TableRow key={`${site.file}:${site.line}:${site.prop}`}>
+ <TableCell>
+ <Text
+ {...stylex.props(
+ sx.mono,
+ )}>{`${site.file}:${site.line}`}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {site.prop}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>{site.value}</Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ Not all of them are carelessness: {INSTANT_ESCAPES} are the{' '}
+ <code>0.01s</code> reduced-motion escape and {TABLE_TINTS} are the
+ same 150ms tint in Table. The rubric would have caught every one
+ at review time, which is the argument for the lint rule rather
+ than the sweep.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Automatable?</Heading>
+ <Text color="secondary">
+ {mechanical.length} of {RUBRIC_CRITERIA.length} are mechanical today —{' '}
+ {mechanical.map(c => c.n).join(', ')}. Five more can be narrowed by
+ lint to a question a reviewer answers in one line. Three are judgement
+ and always will be.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>#</TableHeaderCell>
+ <TableHeaderCell>Criterion</TableHeaderCell>
+ <TableHeaderCell>Automatable</TableHeaderCell>
+ <TableHeaderCell>What checks it</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {RUBRIC_CRITERIA.map(c => (
+ <TableRow key={c.id}>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {c.n}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text weight="semibold">{c.title}</Text>
+ </TableCell>
+ <TableCell>
+ <Badge
+ variant={AUTOMATABLE_VARIANT[c.automatable]}
+ label={AUTOMATABLE_LABEL[c.automatable]}
+ />
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {c.check}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Grandfathering</Heading>
+ <Text color="secondary">
+ The rubric is worth nothing if it fails 48 animating components on the
+ day it lands, and worth nothing if it never fails anything. This is
+ the split.
+ </Text>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Situation</TableHeaderCell>
+ <TableHeaderCell>Rule</TableHeaderCell>
+ <TableHeaderCell>Why</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {GRANDFATHERING.map(row => (
+ <TableRow key={row.situation}>
+ <TableCell>
+ <Text weight="semibold">{row.situation}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting">{row.rule}</Text>
+ </TableCell>
+ <TableCell>
+ <Text type="supporting" color="secondary">
+ {row.why}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>A principle the rubric drops</Heading>
+ <Card padding={4}>
+ <VStack gap={2}>
+ <HStack gap={2} vAlign="center" wrap="wrap">
+ <Text weight="semibold">{MISSING_PRINCIPLE.title}</Text>
+ <Badge variant="warning" label="Published, ungraded" />
+ </HStack>
+ <VStack gap={1} {...stylex.props(sx.quote)}>
+ <Text type="supporting" color="secondary">
+ &ldquo;{MISSING_PRINCIPLE.published}&rdquo;
+ </Text>
+ </VStack>
+ <Text type="supporting">{MISSING_PRINCIPLE.gap}</Text>
+ <Text type="supporting" color="secondary">
+ {MISSING_PRINCIPLE.measuredAgainst}
+ </Text>
+ <Text type="supporting">
+ <strong>Recommendation: </strong>
+ {MISSING_PRINCIPLE.recommendation}
+ </Text>
+ <Text type="supporting" color="secondary">
+ <Link href="/motion/published">
+ The published page against the proposal, conflict by conflict
+ </Link>
+ </Text>
+ </VStack>
+ </Card>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/springs.tsx b/apps/sandbox/src/motion/pages/springs.tsx
new file mode 100644
index 0000000000..ddd278276b
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/springs.tsx
@@ -0,0 +1,467 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input SPRINGS from motionTokens, the spring model, the lab store
+ * @output The four named springs, tunable, beside the CSS pair for the same gesture
+ * @position /motion/springs
+ *
+ * Springs are the only part of the proposal with no CSS representation, so
+ * they live in the JS mirror rather than the token file. That is not a
+ * technicality: a spring is what gesture-driven and interruptible motion
+ * needs, because it carries velocity through an interruption where a keyframe
+ * restarts from zero.
+ *
+ * The runner and the plot use the lab's CSS module classes rather than local
+ * styles so a spring-driven box and a token-driven <Runner> are pixel
+ * identical — the comparison is only honest if the only difference is timing.
+ */
+
+import {useCallback, useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Button} from '@astryxdesign/core/Button';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {MetadataList, MetadataListItem} from '@astryxdesign/core/MetadataList';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {LabPage} from '../PageFrame';
+import {DemoBody, DemoCard, LabSlider, Runner, useLoop} from '../LabPrimitives';
+import {useMotionLab} from '../MotionLabStore';
+import {SPRINGS} from '../motionTokens';
+import {createSpring, plotPath} from '../spring';
+import styles from '../MotionLab.module.css';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ mono: {fontFamily: 'var(--font-family-code)'},
+ prose: {maxWidth: '72ch'},
+});
+
+/** Bounce above this stops reading as a crisp library. Rubric criterion 11. */
+const CRISP_BOUNCE_CEILING = 0.3;
+
+const PLOT_WIDTH = 380;
+const PLOT_HEIGHT = 148;
+const PLOT_PAD = 18;
+/** Plot past the nominal duration so the overshoot is visible, not clipped. */
+const PLOT_TAIL = 1.5;
+
+function pct(value: number): string {
+ return `${(value * 100).toFixed(1)}%`;
+}
+
+/**
+ * The spring's position over time. The dashed line is the target: everything
+ * above it is overshoot, and the vertical mark is where the nominal duration
+ * ends — a light spring is still moving there, which is the thing the number
+ * in the readout is measuring.
+ */
+function SpringPlot({duration, bounce}: {duration: number; bounce: number}) {
+ const spring = createSpring(duration, bounce);
+ const span = spring.duration * PLOT_TAIL;
+ const yMin = -0.08;
+ const yMax = Math.max(1.2, spring.overshoot() + 0.1);
+ const toY = (y: number) =>
+ PLOT_HEIGHT -
+ PLOT_PAD -
+ ((y - yMin) / (yMax - yMin)) * (PLOT_HEIGHT - PLOT_PAD * 2);
+ const nominalX = PLOT_PAD + (1 / PLOT_TAIL) * (PLOT_WIDTH - PLOT_PAD * 2);
+
+ return (
+ <svg
+ className={styles.curveCanvas}
+ width={PLOT_WIDTH}
+ height={PLOT_HEIGHT}
+ viewBox={`0 0 ${PLOT_WIDTH} ${PLOT_HEIGHT}`}
+ role="img"
+ aria-label={`Spring position over time, duration ${duration} seconds, bounce ${bounce}`}>
+ <line
+ x1={PLOT_PAD}
+ y1={toY(1)}
+ x2={PLOT_WIDTH - PLOT_PAD}
+ y2={toY(1)}
+ stroke="var(--color-border)"
+ strokeDasharray="3 3"
+ />
+ <line
+ x1={nominalX}
+ y1={PLOT_PAD}
+ x2={nominalX}
+ y2={PLOT_HEIGHT - PLOT_PAD}
+ stroke="var(--color-text-tertiary, #8a8a8a)"
+ strokeDasharray="2 4"
+ />
+ <path
+ d={plotPath(
+ x => spring.sample(x * span),
+ PLOT_WIDTH,
+ PLOT_HEIGHT,
+ PLOT_PAD,
+ yMin,
+ yMax,
+ )}
+ fill="none"
+ stroke="var(--color-brand)"
+ strokeWidth={2}
+ />
+ </svg>
+ );
+}
+
+/**
+ * A box driven by the spring itself rather than by a duration token, which is
+ * why it cannot be the shared <Runner>: the timing comes from the sampled
+ * curve, and only the slow-mo multiplier is shared with the rest of the lab.
+ */
+function SpringRunner({duration, bounce}: {duration: number; bounce: number}) {
+ const {speed, reducedMotion} = useMotionLab();
+ const dotRef = useRef<HTMLSpanElement | null>(null);
+ const trackRef = useRef<HTMLDivElement | null>(null);
+
+ const run = useCallback(() => {
+ const dot = dotRef.current;
+ const track = trackRef.current;
+ if (dot == null || track == null) {
+ return;
+ }
+ for (const animation of dot.getAnimations()) {
+ animation.cancel();
+ }
+ const spring = createSpring(duration, bounce);
+ // Short of the far edge, so an overshooting spring is not clipped by the
+ // track it is travelling in.
+ const distance = Math.max(0, track.clientWidth - 52);
+ // A spring is movement, which is the first thing either reduced-motion
+ // policy removes — so the box arrives rather than travels.
+ const isInstant = reducedMotion !== 'off';
+ dot.animate(
+ [{transform: 'translateX(0)'}, {transform: `translateX(${distance}px)`}],
+ {
+ duration: isInstant ? 1 : Math.max(1, spring.duration * 1000 * speed),
+ easing: isInstant ? 'linear' : spring.linear(),
+ fill: 'both',
+ },
+ );
+ }, [bounce, duration, reducedMotion, speed]);
+
+ useLoop(run, duration * 1000 * speed + 900);
+
+ return (
+ <div ref={trackRef} className={styles.runner}>
+ <span ref={dotRef} className={styles.runnerDot} />
+ </div>
+ );
+}
+
+/**
+ * The same spring, retargeted mid-flight. The box picks up from wherever it
+ * is but from a standstill, because a sampled curve has no velocity to carry.
+ * A real spring integrator does — which is the argument for the JS spring
+ * over the CSS fallback for anything gesture-driven.
+ */
+function InterruptDemo({duration, bounce}: {duration: number; bounce: number}) {
+ const {speed, reducedMotion} = useMotionLab();
+ const [isOut, setOut] = useState(false);
+ const dotRef = useRef<HTMLSpanElement | null>(null);
+ const trackRef = useRef<HTMLDivElement | null>(null);
+
+ const toggle = useCallback(() => {
+ const dot = dotRef.current;
+ const track = trackRef.current;
+ if (dot == null || track == null) {
+ return;
+ }
+ const next = !isOut;
+ setOut(next);
+ const spring = createSpring(duration, bounce);
+ const distance = Math.max(0, track.clientWidth - 52);
+ // The running animation does not commit its value, so the position has to
+ // be read off the box before it is cancelled.
+ const matrix = new DOMMatrixReadOnly(
+ window.getComputedStyle(dot).transform,
+ );
+ for (const animation of dot.getAnimations()) {
+ animation.cancel();
+ }
+ const isInstant = reducedMotion !== 'off';
+ dot.animate(
+ [
+ {transform: `translateX(${matrix.m41}px)`},
+ {transform: `translateX(${next ? distance : 0}px)`},
+ ],
+ {
+ duration: isInstant ? 1 : Math.max(1, spring.duration * 1000 * speed),
+ easing: isInstant ? 'linear' : spring.linear(),
+ fill: 'both',
+ },
+ );
+ }, [bounce, duration, isOut, reducedMotion, speed]);
+
+ return (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ <div ref={trackRef} className={styles.runner}>
+ <span ref={dotRef} className={styles.runnerDot} />
+ </div>
+ <Button
+ size="sm"
+ variant="secondary"
+ label="Send it back — press twice, fast"
+ onClick={toggle}
+ />
+ </VStack>
+ );
+}
+
+function SpringCard({
+ name,
+ use,
+ cssCounterpart,
+}: {
+ name: string;
+ use: string;
+ cssCounterpart: readonly [string, string];
+}) {
+ const {springs, setSpring} = useMotionLab();
+ const tuned = springs[name];
+ const spring = createSpring(tuned.duration, tuned.bounce);
+ const isBouncy = tuned.bounce > CRISP_BOUNCE_CEILING;
+
+ return (
+ <DemoCard
+ title={name}
+ question={use}
+ badges={
+ isBouncy ? (
+ <Badge
+ variant="warning"
+ label={`bounce ${tuned.bounce.toFixed(2)} — past crisp`}
+ />
+ ) : (
+ <Badge
+ label={`${Math.round(tuned.duration * 1000)}ms · bounce ${tuned.bounce.toFixed(2)}`}
+ />
+ )
+ }>
+ <DemoBody>
+ <SpringPlot duration={tuned.duration} bounce={tuned.bounce} />
+ <VStack gap={1} {...stylex.props(sx.full)}>
+ <Text type="supporting" color="secondary">
+ spring — <code>{name}</code>
+ </Text>
+ <SpringRunner duration={tuned.duration} bounce={tuned.bounce} />
+ <Text type="supporting" color="secondary">
+ CSS counterpart — <code>{cssCounterpart[0]}</code> +{' '}
+ <code>{cssCounterpart[1]}</code>
+ </Text>
+ <Runner
+ durationToken={cssCounterpart[0]}
+ easeToken={cssCounterpart[1]}
+ />
+ </VStack>
+ <LabSlider
+ label="Duration"
+ value={tuned.duration}
+ min={0.1}
+ max={1.2}
+ step={0.05}
+ format={v => `${v.toFixed(2)}s`}
+ onChange={v => setSpring(name, {duration: v, bounce: tuned.bounce})}
+ />
+ <LabSlider
+ label="Bounce"
+ value={tuned.bounce}
+ min={0}
+ max={0.6}
+ step={0.05}
+ format={v => v.toFixed(2)}
+ onChange={v => setSpring(name, {duration: tuned.duration, bounce: v})}
+ />
+ <MetadataList columns={2} label={{position: 'top'}}>
+ <MetadataListItem label="Duration">
+ <Text {...stylex.props(sx.mono)}>
+ {spring.duration.toFixed(2)}s
+ </Text>
+ </MetadataListItem>
+ <MetadataListItem label="Bounce">
+ <Text {...stylex.props(sx.mono)}>{spring.bounce.toFixed(2)}</Text>
+ </MetadataListItem>
+ <MetadataListItem label="Overshoot">
+ <Text {...stylex.props(sx.mono)}>
+ {pct(spring.overshoot() - 1)}
+ </Text>
+ </MetadataListItem>
+ <MetadataListItem label="At nominal duration">
+ <Text {...stylex.props(sx.mono)}>{pct(spring.settle())}</Text>
+ </MetadataListItem>
+ <MetadataListItem label="Stiffness">
+ <Text {...stylex.props(sx.mono)}>{spring.stiffness}</Text>
+ </MetadataListItem>
+ <MetadataListItem label="Damping">
+ <Text {...stylex.props(sx.mono)}>{spring.damping}</Text>
+ </MetadataListItem>
+ </MetadataList>
+ </DemoBody>
+ </DemoCard>
+ );
+}
+
+export default function MotionSpringsPage() {
+ const {springs} = useMotionLab();
+ const [escapeHatch, setEscapeHatch] = useState<string>(SPRINGS[0].name);
+ const hatch = springs[escapeHatch];
+ const hatchSpring = createSpring(hatch.duration, hatch.bounce);
+ const bouncy = SPRINGS.filter(
+ s => springs[s.name].bounce > CRISP_BOUNCE_CEILING,
+ );
+
+ return (
+ <LabPage
+ title="Springs"
+ intro="A spring is described by duration and bounce, not by a curve, and it has no CSS representation at all — which is why the proposal keeps springs in the JS mirror rather than the token file. What they buy is interruption: a spring carries velocity through a change of target, where a keyframe restarts from zero. That is the whole case for having them, and it only pays off in gesture-driven and interruptible motion."
+ decides="Whether the four named springs feel right, and whether they belong in the theme contract."
+ badges={<Badge variant="info" label="JS mirror only — no CSS form" />}>
+ <Banner
+ status={bouncy.length > 0 ? 'warning' : 'info'}
+ title={
+ bouncy.length > 0
+ ? `${bouncy.length} spring(s) tuned past bounce 0.3`
+ : 'Bounce belongs in 0.1–0.3 for a crisp library'
+ }
+ description={
+ <Text>
+ Rubric criterion 11 is that visible bounce is for drag-to-dismiss
+ and playful moments; a dashboard stays crisp. Every slider below
+ runs to 0.6 on purpose. At bounce {CRISP_BOUNCE_CEILING} the box
+ passes its target by{' '}
+ {pct(createSpring(0.4, CRISP_BOUNCE_CEILING).overshoot() - 1)} and
+ settles back; at 0.6 it passes by{' '}
+ {pct(createSpring(0.4, 0.6).overshoot() - 1)} and reads as a toy.
+ Overshoot depends only on bounce, not on duration, so this is the
+ one number worth arguing about — and it is easier to agree on by
+ looking than by reading it.
+ </Text>
+ }
+ />
+
+ <Grid columns={{minWidth: 420}} gap={4}>
+ {SPRINGS.map(spec => (
+ <SpringCard
+ key={spec.name}
+ name={spec.name}
+ use={spec.use}
+ cssCounterpart={spec.cssCounterpart}
+ />
+ ))}
+ </Grid>
+
+ <DemoCard
+ title="What the preview actually is"
+ question="An approximation, and it is worth knowing where it stops being one."
+ badges={<Badge label="honest about the model" />}>
+ <DemoBody>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ Motion describes a spring as duration and bounce. This lab
+ reproduces that as a damped harmonic oscillator — bounce maps to the
+ damping ratio, duration to the settle time — and then samples the
+ curve into a CSS <code>linear()</code> easing so a plain transition
+ can play it. Close enough to judge feel, and to argue about whether
+ 0.2 belongs in a crisp library.
+ </Text>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ The sampled curve is also the escape hatch: a component that cannot
+ take a JS dependency can still run the spring shape from CSS. What
+ it cannot do is interruption. Press the button below twice in quick
+ succession — the box retargets from wherever it is, but from a
+ standstill, because a curve has no velocity to carry. A real spring
+ integrator does. So the fallback is for shape, and gesture work
+ wants the JS spring.
+ </Text>
+ <InterruptDemo duration={hatch.duration} bounce={hatch.bounce} />
+ <SegmentedControl
+ label="Which spring to emit"
+ size="sm"
+ value={escapeHatch}
+ onChange={value => setEscapeHatch(value as string)}>
+ {SPRINGS.map(spec => (
+ <SegmentedControlItem
+ key={spec.name}
+ value={spec.name}
+ label={spec.name}
+ />
+ ))}
+ </SegmentedControl>
+ <CodeBlock
+ language="css"
+ title={`${escapeHatch} — CSS fallback, sampled from the spring`}
+ hasCopyButton
+ isWrapped
+ maxHeight={220}
+ code={`/* No JS dependency. Shape only: an interruption restarts from rest. */
+.thing {
+ transition-property: transform;
+ transition-duration: ${Math.round(hatchSpring.duration * 1000)}ms;
+ transition-timing-function: ${hatchSpring.linear(16)};
+}`}
+ />
+ <Text type="supporting" color="secondary">
+ Sampled at 16 points here so it is readable; the mirror emits 64.
+ Overshoot {pct(hatchSpring.overshoot() - 1)}, which is the part a
+ cubic-bezier cannot express without going out of its 0–1 box.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <VStack gap={3}>
+ <Heading level={2}>
+ Open question: should springs be theme-tunable?
+ </Heading>
+ <Text color="secondary" {...stylex.props(sx.prose)}>
+ A theme already retunes the whole duration scale from three numbers —
+ a snappy theme sets{' '}
+ <code>{'{fast: 100, medium: 250, ratio: 0.75}'}</code> and every
+ primitive moves with it. Springs have no such axis, so today they are
+ the same everywhere no matter what the theme says. If one theme is
+ meant to feel bouncier than another, springs belong in the theme
+ contract alongside the duration scale — and adding them after the
+ contract ships is a breaking change to it. This wants deciding before
+ the token work lands, not after.
+ </Text>
+ <CodeBlock
+ language="ts"
+ title="packages/core/src/theme/expandMotionScale.ts — the axis today, and the question"
+ hasCopyButton
+ code={`export interface MotionScaleConfig {
+ fast: number; // 175 — micro-interactions
+ medium: number; // 410 — entrance and exit
+ slow?: number; // 975 — continuous
+ ratio: number; // 0.75 — min = base × ratio, max = base ÷ ratio
+ easing?: string; // overrides --ease-standard
+
+ // Proposed, and the decision this page is asking for. Optional is not the
+ // same as cheap: once themes ship without it, a theme author who tunes
+ // duration and finds springs unmoved has been told the contract covers
+ // motion when it covers only half of it.
+ spring?: Record<'press' | 'swap' | 'panel' | 'layout', {duration: number; bounce: number}>;
+}`}
+ />
+ <Text type="supporting" color="secondary">
+ Springs are defined natively in the mirror rather than parsed out of
+ CSS, since they have no CSS form to parse. See{' '}
+ <Link href="/motion/js-mirror">JS token mirror</Link> for the emitted
+ shape and <Link href="/motion/export">Export tuning</Link> for what
+ ships.
+ </Text>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/tokens.tsx b/apps/sandbox/src/motion/pages/tokens.tsx
new file mode 100644
index 0000000000..5b12ce55f0
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/tokens.tsx
@@ -0,0 +1,441 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input motionTokens, the lab store, Core components
+ * @output The semantic token proposal, tunable
+ * @position /motion/tokens
+ *
+ * The page the rest of the lab depends on: every control here writes a real
+ * custom property, so a curve settled on this page is the curve every demo in
+ * every other section is already using.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {CodeBlock} from '@astryxdesign/core/CodeBlock';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {LabPage} from '../PageFrame';
+import {
+ BudgetMeter,
+ ComparePanes,
+ CurveEditor,
+ DemoBody,
+ DemoCard,
+ Runner,
+ TokenSlider,
+ isNamedCurve,
+} from '../LabPrimitives';
+import {useMotionLab} from '../MotionLabStore';
+import {
+ CURRENT_EASE,
+ PRIMITIVE_DURATIONS,
+ SEMANTIC_DURATIONS,
+ SEMANTIC_EASES,
+ STAGGERS,
+} from '../motionTokens';
+import {HARDCODED_SITES} from '../__generated__/motionAudit';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ mono: {fontFamily: 'var(--font-family-code)'},
+ jobRow: {maxWidth: '46ch'},
+});
+
+const CURVE_PRESETS = [
+ ['ease-out', 'cubic-bezier(0, 0, 0.58, 1)'],
+ ['iOS', 'cubic-bezier(0.32, 0.72, 0, 1)'],
+ ['expo-out', 'cubic-bezier(0.16, 1, 0.3, 1)'],
+] as const;
+
+/** The duration each curve is best judged at — a linear curve needs a long run. */
+function previewDuration(easeName: string): string {
+ if (easeName === '--ease-linear') {
+ return '--duration-continuous';
+ }
+ if (easeName === '--ease-drawer') {
+ return '--duration-overlay';
+ }
+ if (easeName === '--ease-move') {
+ return '--duration-reveal';
+ }
+ return '--duration-enter';
+}
+
+/** Which curve reads best against a given duration, for the duration cards. */
+function pairedEase(durationName: string): string {
+ switch (durationName) {
+ case '--duration-exit':
+ return '--ease-exit';
+ case '--duration-continuous':
+ return '--ease-linear';
+ case '--duration-reveal':
+ return '--ease-move';
+ case '--duration-overlay':
+ return '--ease-drawer';
+ default:
+ return '--ease-entry';
+ }
+}
+
+export default function MotionTokensPage() {
+ const {rawToken, setToken} = useMotionLab();
+ const exitCurveSite = HARDCODED_SITES.find(
+ s => s.component === 'BottomSheet' && s.value.startsWith('cubic-bezier'),
+ );
+
+ return (
+ <LabPage
+ title="Semantic motion tokens"
+ intro="The current scale names sizes. An author choosing between --duration-fast-max and --duration-medium-min is guessing, because neither name says what it is for. The proposal keeps the primitive scale exactly as it is and adds a semantic layer on top, the way colour already works."
+ decides="Whether six easings and eight durations are the right vocabulary, and what each value should be."
+ badges={
+ <Badge variant="info" label="every control writes a real token" />
+ }>
+ <Banner
+ status="info"
+ title="One curve is doing three jobs"
+ description={
+ <Text>
+ Core ships exactly one easing token,{' '}
+ <code>
+ {CURRENT_EASE.name}: {CURRENT_EASE.value}
+ </code>
+ , and it covers entry, exit and state at once. The codebase has
+ already discovered this and worked around it locally — with a
+ comment measuring why.
+ {exitCurveSite != null && (
+ <>
+ {' '}
+ <code>
+ {exitCurveSite.file}:{exitCurveSite.line}
+ </code>{' '}
+ authors <code>{exitCurveSite.value}</code> by hand for the
+ sheet&rsquo;s exit.
+ </>
+ )}
+ </Text>
+ }
+ />
+
+ <DemoCard
+ title="The same three jobs, one curve and six"
+ question="Watch the exit lane. On the standard curve a leaving surface spends its travel immediately and then coasts, which is right for an arrival and wrong for a departure."
+ badges={<Badge variant="neutral" label="run at 4× to judge" />}>
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — --ease-standard for all three',
+ content: (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ {(
+ [
+ ['Arriving', '--duration-enter'],
+ ['Leaving', '--duration-exit'],
+ ['Moving', '--duration-reveal'],
+ ] as const
+ ).map(([label, duration]) => (
+ <VStack key={label} gap={1} {...stylex.props(sx.full)}>
+ <Text type="supporting" color="secondary">
+ {label}
+ </Text>
+ <Runner
+ durationToken={duration}
+ easeToken="--ease-standard-today"
+ />
+ </VStack>
+ ))}
+ </VStack>
+ ),
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — the curve names the job',
+ content: (
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ {(
+ [
+ ['Arriving', '--duration-enter', '--ease-entry'],
+ ['Leaving', '--duration-exit', '--ease-exit'],
+ ['Moving', '--duration-reveal', '--ease-move'],
+ ] as const
+ ).map(([label, duration, ease]) => (
+ <VStack key={label} gap={1} {...stylex.props(sx.full)}>
+ <Text type="supporting" color="secondary">
+ {label} — <code>{ease}</code>
+ </Text>
+ <Runner durationToken={duration} easeToken={ease} />
+ </VStack>
+ ))}
+ </VStack>
+ ),
+ },
+ ]}
+ />
+ <DemoBody>
+ <Text type="supporting" color="secondary">
+ The sheet needed its own curve because the standard one, measured on
+ device, “put the sheet half off-screen in 59ms of a 410ms close and
+ 90% off in 163ms — the travel is over before the eye has followed
+ it”. That comment, already in the codebase, is the specification for{' '}
+ <code>--ease-exit</code>. Promoting it is not a new idea; it is the
+ second time someone has needed it.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <VStack gap={3}>
+ <Heading level={2}>Easing</Heading>
+ <Text color="secondary">
+ Drag a control point and every demo in the lab moves with it. Arrow
+ keys nudge; hold shift for a bigger step.
+ </Text>
+ <Grid columns={{minWidth: 420}} gap={4}>
+ {SEMANTIC_EASES.map(ease => {
+ const duration = previewDuration(ease.name);
+ const value = rawToken(ease.name);
+ return (
+ <DemoCard
+ key={ease.name}
+ title={ease.name}
+ question={ease.job}
+ badges={
+ isNamedCurve(value) ? (
+ <Badge label="CSS keyword — nothing to tune" />
+ ) : undefined
+ }>
+ <DemoBody>
+ {!isNamedCurve(value) && (
+ <CurveEditor
+ value={value}
+ onChange={next => setToken(ease.name, next)}
+ presets={[['reset', ease.value], ...CURVE_PRESETS]}
+ />
+ )}
+ <VStack gap={1} {...stylex.props(sx.full)}>
+ <Text type="supporting" color="secondary">
+ today — <code>--ease-standard</code>
+ </Text>
+ <Runner
+ durationToken={duration}
+ easeToken="--ease-standard-today"
+ />
+ <Text type="supporting" color="secondary">
+ proposed — <code>{ease.name}</code>
+ </Text>
+ <Runner durationToken={duration} easeToken={ease.name} />
+ </VStack>
+ <Text
+ type="supporting"
+ color="secondary"
+ {...stylex.props(sx.jobRow)}>
+ {ease.rationale}
+ </Text>
+ {ease.evidence != null && (
+ <Text type="supporting" color="secondary">
+ Already in the code: <code>{ease.evidence}</code>
+ </Text>
+ )}
+ </DemoBody>
+ </DemoCard>
+ );
+ })}
+ </Grid>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Duration</Heading>
+ <Text color="secondary">
+ Aliases onto the existing primitives, so a theme retunes them for free
+ through the motion scale it already has.
+ </Text>
+ <Grid columns={{minWidth: 380}} gap={4}>
+ {SEMANTIC_DURATIONS.map(duration => (
+ <DemoCard
+ key={duration.name}
+ title={duration.name}
+ question={duration.job}
+ badges={
+ <Badge
+ label={
+ duration.primitive == null
+ ? 'new'
+ : duration.primitive.replace('--duration-', '')
+ }
+ />
+ }>
+ <DemoBody>
+ {duration.ms > 0 && (
+ <>
+ <Runner
+ durationToken={duration.name}
+ easeToken={pairedEase(duration.name)}
+ />
+ <TokenSlider token={duration.name} max={900} />
+ <BudgetMeter token={duration.name} />
+ {duration.budget != null && (
+ <Text type="supporting" color="secondary">
+ Reference budget {duration.budget[0]}–
+ {duration.budget[1]}ms.
+ </Text>
+ )}
+ </>
+ )}
+ {duration.note != null && (
+ <Text
+ type="supporting"
+ color="secondary"
+ {...stylex.props(sx.jobRow)}>
+ {duration.note}
+ </Text>
+ )}
+ </DemoBody>
+ </DemoCard>
+ ))}
+ </Grid>
+ </VStack>
+
+ <Banner
+ status="warning"
+ title="The slow band is simultaneously unused and too short"
+ description={
+ <Text>
+ Interface motion should stay under 300ms unless it is an overlay, so{' '}
+ <code>--duration-medium-max</code> (550ms) and everything above it
+ has no interface use. Meanwhile the components that genuinely need a
+ long loop bypass the scale entirely, because it stops at 1300ms:
+ StatusDot runs 2s and Chat 1.5s, both hardcoded. Either extend the
+ band or say plainly that ambient motion is a separate concern from
+ interface motion — but the two loops cannot be swept onto tokens
+ until one of those happens.
+ </Text>
+ }
+ />
+
+ <DemoCard
+ title="Stagger"
+ question="Group entrances want 30–80ms between items. Longer feels slow, and stagger must never block interaction — the last item has to be reachable before it has finished arriving.">
+ <DemoBody>
+ {STAGGERS.map(([name, , job]) => (
+ <VStack key={name} gap={1} {...stylex.props(sx.full)}>
+ <HStack gap={2} vAlign="center">
+ <Text {...stylex.props(sx.mono)}>{name}</Text>
+ <Text type="supporting" color="secondary">
+ {job}
+ </Text>
+ </HStack>
+ <TokenSlider token={name} max={160} step={5} />
+ </VStack>
+ ))}
+ </DemoBody>
+ </DemoCard>
+
+ <VStack gap={3}>
+ <Heading level={2}>The primitive scale, unchanged</Heading>
+ <Text color="secondary">
+ Theme-generated and working. Nothing here moves — the semantic layer
+ sits on top, which is what keeps the change non-breaking.
+ </Text>
+ <Card padding={0}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Primitive</TableHeaderCell>
+ <TableHeaderCell>Value</TableHeaderCell>
+ <TableHeaderCell>Semantic alias</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {PRIMITIVE_DURATIONS.map(([name, ms]) => {
+ const aliases = SEMANTIC_DURATIONS.filter(
+ d => d.primitive === name,
+ );
+ return (
+ <TableRow key={name}>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>{name}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {ms}ms
+ </Text>
+ </TableCell>
+ <TableCell>
+ {aliases.length > 0 ? (
+ <HStack gap={1} wrap="wrap">
+ {aliases.map(a => (
+ <Badge
+ key={a.name}
+ variant="success"
+ label={a.name}
+ />
+ ))}
+ </HStack>
+ ) : (
+ <Text color="secondary">—</Text>
+ )}
+ </TableCell>
+ </TableRow>
+ );
+ })}
+ </TableBody>
+ </Table>
+ </Card>
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Where this lands</Heading>
+ <Text color="secondary">
+ Not a <code>:root</code> block — core defines its tokens through
+ StyleX, so the proposal is an addition to two existing objects.
+ </Text>
+ <CodeBlock
+ language="ts"
+ title="@astryxdesign/core/src/theme/tokens.stylex.ts"
+ hasCopyButton
+ code={`export const easeDefaults = {
+ '--ease-standard': 'cubic-bezier(0.24, 1, 0.4, 1)', // kept, deprecated in docs
+ '--ease-entry': ${JSON.stringify(rawToken('--ease-entry'))},
+ '--ease-exit': ${JSON.stringify(rawToken('--ease-exit'))},
+ '--ease-move': ${JSON.stringify(rawToken('--ease-move'))},
+ '--ease-state': ${JSON.stringify(rawToken('--ease-state'))},
+ '--ease-linear': ${JSON.stringify(rawToken('--ease-linear'))},
+ '--ease-drawer': ${JSON.stringify(rawToken('--ease-drawer'))},
+} as const;
+
+export const durationDefaults = {
+ // the nine primitives stay exactly as they are
+ ...
+ // semantic layer, aliased so a theme retunes both at once
+${SEMANTIC_DURATIONS.map(
+ d =>
+ ` '${d.name}': ${JSON.stringify(rawToken(d.name))},${
+ d.primitive != null ? ` // ${d.primitive}` : ''
+ }`,
+).join('\n')}
+} as const;`}
+ />
+ <Text type="supporting" color="secondary">
+ The export page emits this with whatever you have tuned. See{' '}
+ <Link href="/motion/export">Export tuning</Link>.
+ </Text>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/pages/violations.tsx b/apps/sandbox/src/motion/pages/violations.tsx
new file mode 100644
index 0000000000..98517ab05c
--- /dev/null
+++ b/apps/sandbox/src/motion/pages/violations.tsx
@@ -0,0 +1,509 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file page.tsx
+ * @input The generated audit, the lab store
+ * @output Every hardcoded duration and curve, with what it becomes
+ * @position /motion/violations
+ *
+ * The brief says 28; the measured number is higher, and the difference is not
+ * carelessness: a third of them are one deliberate reduced-motion idiom. The
+ * page is organised around that, because a sweep planned for 28 careless
+ * values and a sweep that contains a policy question are different pieces of
+ * work. Counts come from the generated audit, never from prose.
+ */
+
+import {useMemo, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Badge} from '@astryxdesign/core/Badge';
+import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
+import {Grid} from '@astryxdesign/core/Grid';
+import {Link} from '@astryxdesign/core/Link';
+import {
+ SegmentedControl,
+ SegmentedControlItem,
+} from '@astryxdesign/core/SegmentedControl';
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHeader,
+ TableHeaderCell,
+ TableRow,
+} from '@astryxdesign/core/Table';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Heading, Text} from '@astryxdesign/core/Text';
+import {LabPage} from '../PageFrame';
+import {ComparePanes, DemoBody, DemoCard, TokenSlider} from '../LabPrimitives';
+import {LoopRig, TintRig} from '../LabDemos';
+import {
+ AUDIT_COUNTS,
+ HARDCODED_BY_COMPONENT,
+ HARDCODED_SITES,
+ LITERAL_VALUES,
+ type HardcodedSite,
+} from '../__generated__/motionAudit';
+
+const sx = stylex.create({
+ full: {width: '100%'},
+ mono: {fontFamily: 'var(--font-family-code)', fontSize: '12px'},
+ bad: {color: 'var(--color-text-error, #d3543f)'},
+ good: {color: 'var(--color-text-success, #2f7d52)'},
+ search: {maxWidth: '280px', width: '100%'},
+ scroll: {maxHeight: '560px', overflow: 'auto', width: '100%'},
+ statValue: {fontSize: '24px', fontWeight: 650, letterSpacing: '-0.02em'},
+});
+
+/**
+ * What each literal should become. Grouped by the shape of the decision rather
+ * than by component, because the sweep is only mechanical for two of these
+ * four groups — the other two need an answer first.
+ */
+type Family = {
+ readonly id: string;
+ readonly title: string;
+ readonly blurb: string;
+ readonly token: string;
+ readonly matches: (site: HardcodedSite) => boolean;
+ readonly mechanical: boolean;
+ readonly blockedBy?: string;
+};
+
+const FAMILIES: ReadonlyArray<Family> = [
+ {
+ id: 'instant',
+ title: 'Reduced-motion escapes',
+ blurb:
+ 'Every one of these is the same idiom: collapse a transition to nothing when the user has asked for less motion. It is not sloppiness, and it is not safe to sweep blind — a zero duration fires no transitionend, so anything sequencing off that event breaks. The 0.01s spelling exists to keep the event.',
+ token: '--duration-instant',
+ matches: s => s.ms != null && s.ms <= 10,
+ mechanical: false,
+ blockedBy:
+ 'Decide whether --duration-instant is 0 or 0.01ms before sweeping any of these.',
+ },
+ {
+ id: 'table',
+ title: 'Table interaction tint',
+ blurb:
+ 'Ten sites across columnResize, groupedRows, rowExpansion, stickyColumns and tree: seven 150ms durations and three bare `ease` curves, several of them the two halves of one `transition` shorthand. This resolves an open question in the brief — its "nine hardcoded values in Table" and its "six hardcoded 150ms values in Table tree" are the same set counted twice, not fifteen sites. 150ms and the token\u2019s 175ms are near-indistinguishable at 1×, so what this family buys is the lint rule, not a visual change.',
+ token: '--duration-state',
+ matches: s => s.component === 'Table',
+ mechanical: true,
+ },
+ {
+ id: 'loops',
+ title: 'Ambient loops',
+ blurb:
+ 'StatusDot at 2s and Chat at 1.5s, both outside a scale that stops at 1300ms. They did not bypass the tokens by accident — there is no token that reaches. This group cannot be swept until the slow band is extended or ambient motion is declared a separate concern.',
+ token: '--duration-continuous (does not reach)',
+ matches: s => s.ms != null && s.ms >= 1000,
+ mechanical: false,
+ blockedBy: 'Needs the ambient-band decision.',
+ },
+ {
+ id: 'curves',
+ title: 'Curves authored by hand',
+ blurb:
+ 'Mostly linear, and mostly correct: a progress bar and a scroll-driven wheel should be linear. The exception is the sheet exit, which authors a full cubic-bezier with a comment measuring why the standard curve fails. That comment is the specification for --ease-exit.',
+ token: '--ease-linear / --ease-exit / --ease-state',
+ matches: s => s.kind === 'easing',
+ mechanical: true,
+ },
+];
+
+function familyOf(site: HardcodedSite): Family | undefined {
+ return FAMILIES.find(f => f.matches(site));
+}
+
+function tokenFor(site: HardcodedSite): string {
+ if (site.kind === 'easing') {
+ if (site.value === 'linear') {
+ return '--ease-linear';
+ }
+ if (site.value.startsWith('cubic-bezier')) {
+ return '--ease-exit';
+ }
+ return '--ease-state';
+ }
+ if (site.ms == null) {
+ return '--duration-state';
+ }
+ if (site.ms <= 10) {
+ return '--duration-instant';
+ }
+ if (site.ms >= 1000) {
+ return 'no token reaches';
+ }
+ if (site.ms <= 160) {
+ return '--duration-state';
+ }
+ return '--duration-enter';
+}
+
+function countIn(familyId: string): number {
+ return HARDCODED_SITES.filter(s => familyOf(s)?.id === familyId).length;
+}
+
+export default function ViolationsPage() {
+ const [query, setQuery] = useState('');
+ const [kind, setKind] = useState<'all' | 'duration' | 'easing'>('all');
+
+ const rows = useMemo(
+ () =>
+ HARDCODED_SITES.filter(site => {
+ if (kind !== 'all' && site.kind !== kind) {
+ return false;
+ }
+ if (query.trim() === '') {
+ return true;
+ }
+ const q = query.toLowerCase();
+ return (
+ site.component.toLowerCase().includes(q) ||
+ site.file.toLowerCase().includes(q) ||
+ site.value.toLowerCase().includes(q) ||
+ site.prop.toLowerCase().includes(q)
+ );
+ }),
+ [kind, query],
+ );
+
+ return (
+ <LabPage
+ title="Hardcoded durations and curves"
+ intro="The token linter polices type, spacing, radius and colour. It has no entry for duration or easing, which is a complete explanation for every site below. Adding those entries turns rubric criterion 3 from a review question into a build failure."
+ decides="What each hardcoded site becomes, and whether the swap is visible at all."
+ badges={
+ <Badge
+ variant="error"
+ label={`${AUDIT_COUNTS.hardcodedTotal} measured`}
+ />
+ }>
+ <Banner
+ status="warning"
+ title={`The brief says 28. The measured number is ${AUDIT_COUNTS.hardcodedTotal}.`}
+ description={
+ <Text>
+ Higher, not lower — so the sweep is bigger than budgeted. More
+ importantly, the extra is not more of the same: {countIn('instant')}{' '}
+ of them are one reduced-motion idiom that needs a decision before it
+ can be touched, and {countIn('loops')} are ambient loops that no
+ token currently reaches. Two of the four families below are
+ mechanical; the other two are blocked on answers, and together they
+ are {countIn('instant') + countIn('loops')} of the{' '}
+ {AUDIT_COUNTS.hardcodedTotal}.
+ </Text>
+ }
+ />
+
+ <Grid columns={{minWidth: 220}} gap={3}>
+ {[
+ [
+ AUDIT_COUNTS.hardcodedTotal,
+ 'Hardcoded sites',
+ 'measured against [email protected]',
+ ],
+ [AUDIT_COUNTS.hardcodedDuration, 'Durations and delays', ''],
+ [AUDIT_COUNTS.hardcodedEasing, 'Curves', ''],
+ [
+ AUDIT_COUNTS.durationWithoutCurve,
+ 'Durations with no curve',
+ 'silently taking the CSS default',
+ ],
+ ].map(([value, label, detail]) => (
+ <Card key={String(label)} padding={4}>
+ <VStack gap={0.5}>
+ <span {...stylex.props(sx.statValue)}>{value}</span>
+ <Text type="supporting">{label}</Text>
+ {detail !== '' && (
+ <Text type="supporting" color="secondary">
+ {detail}
+ </Text>
+ )}
+ </VStack>
+ </Card>
+ ))}
+ </Grid>
+
+ <VStack gap={3}>
+ <Heading level={2}>Four families, two of them blocked</Heading>
+ {FAMILIES.map(family => {
+ const count = HARDCODED_SITES.filter(
+ s => familyOf(s)?.id === family.id,
+ ).length;
+ return (
+ <DemoCard
+ key={family.id}
+ title={family.title}
+ question={family.blurb}
+ badges={
+ <HStack gap={1}>
+ <Badge label={`${count} sites`} />
+ <Badge
+ variant={family.mechanical ? 'success' : 'warning'}
+ label={family.mechanical ? 'mechanical' : 'blocked'}
+ />
+ </HStack>
+ }>
+ {family.id === 'table' && (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — 150ms, default curve',
+ content: <TintRig mode="before" />,
+ },
+ {
+ tone: 'after',
+ label: 'Proposed — --duration-state, --ease-state',
+ content: <TintRig mode="after" />,
+ },
+ ]}
+ />
+ )}
+ {family.id === 'loops' && (
+ <ComparePanes
+ panes={[
+ {
+ tone: 'before',
+ label: 'Today — hardcoded, outside the scale',
+ content: <LoopRig policy="today" />,
+ },
+ {
+ tone: 'neutral',
+ label: 'Stopped',
+ content: <LoopRig policy="degrade" />,
+ },
+ ]}
+ />
+ )}
+ <DemoBody>
+ {family.id === 'table' && (
+ <>
+ <TokenSlider
+ token="--duration-state"
+ label="state"
+ max={400}
+ />
+ <Text type="supporting" color="secondary">
+ Put the rail on 4× or 8× if you want to see the difference
+ between 150 and 175 at all. That it is hard to see at 1×
+ is the honest finding, and it is the argument for treating
+ this family as a lint fix rather than a design change.
+ </Text>
+ </>
+ )}
+ {family.blockedBy != null && (
+ <Text type="supporting" {...stylex.props(sx.bad)}>
+ Blocked: {family.blockedBy}
+ </Text>
+ )}
+ <HStack gap={2} wrap="wrap">
+ {HARDCODED_SITES.filter(s => familyOf(s)?.id === family.id)
+ .slice(0, 6)
+ .map((s, i) => (
+ <Text
+ key={`${s.file}:${s.line}:${i}`}
+ {...stylex.props(sx.mono)}
+ color="secondary">
+ {s.file}:{s.line}
+ </Text>
+ ))}
+ {count > 6 && (
+ <Text type="supporting" color="secondary">
+ +{count - 6} more in the table below
+ </Text>
+ )}
+ </HStack>
+ </DemoBody>
+ </DemoCard>
+ );
+ })}
+ </VStack>
+
+ <VStack gap={3}>
+ <Heading level={2}>Every site</Heading>
+ <HStack gap={2} vAlign="center" wrap="wrap">
+ <div {...stylex.props(sx.search)}>
+ <TextInput
+ label="Filter sites"
+ isLabelHidden
+ placeholder="Filter by component, file or value…"
+ value={query}
+ onChange={setQuery}
+ />
+ </div>
+ <SegmentedControl
+ label="Kind"
+ size="sm"
+ value={kind}
+ onChange={value => setKind(value as 'all' | 'duration' | 'easing')}>
+ <SegmentedControlItem value="all" label="All" />
+ <SegmentedControlItem value="duration" label="Durations" />
+ <SegmentedControlItem value="easing" label="Curves" />
+ </SegmentedControl>
+ <Text type="supporting" color="secondary">
+ {rows.length} of {HARDCODED_SITES.length}
+ </Text>
+ </HStack>
+ <Card padding={0}>
+ <div {...stylex.props(sx.scroll)}>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Component</TableHeaderCell>
+ <TableHeaderCell>Site</TableHeaderCell>
+ <TableHeaderCell>Property</TableHeaderCell>
+ <TableHeaderCell>Today</TableHeaderCell>
+ <TableHeaderCell>Becomes</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {/* Two sites can share file, line, value and property when one
+ declaration carries a duration and a curve, so the index is
+ part of the identity. */}
+ {rows.map((site, i) => (
+ <TableRow
+ key={`${site.file}:${site.line}:${site.prop}:${site.value}:${i}`}>
+ <TableCell>
+ <Text weight="semibold">{site.component}</Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {site.file}:{site.line}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)} color="secondary">
+ {site.prop}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono, sx.bad)}>
+ {site.value}
+ </Text>
+ </TableCell>
+ <TableCell>
+ <Text {...stylex.props(sx.mono, sx.good)}>
+ {tokenFor(site)}
+ </Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </div>
+ </Card>
+ </VStack>
+
+ <Grid columns={{minWidth: 320}} gap={3}>
+ <Card padding={4}>
+ <VStack gap={2}>
+ <Heading level={3}>Literals in use</Heading>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Value</TableHeaderCell>
+ <TableHeaderCell>Sites</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {LITERAL_VALUES.map(([value, count]) => (
+ <TableRow key={value}>
+ <TableCell>
+ <Text {...stylex.props(sx.mono)}>{value}</Text>
+ </TableCell>
+ <TableCell>
+ <Text>{count}</Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </VStack>
+ </Card>
+ <Card padding={4}>
+ <VStack gap={2}>
+ <Heading level={3}>By component</Heading>
+ <Table density="compact">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Component</TableHeaderCell>
+ <TableHeaderCell>Sites</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {HARDCODED_BY_COMPONENT.map(([name, count]) => (
+ <TableRow key={name}>
+ <TableCell>
+ <Text>{name}</Text>
+ </TableCell>
+ <TableCell>
+ <Text>{count}</Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </VStack>
+ </Card>
+ </Grid>
+
+ <VStack gap={3}>
+ <Heading level={2}>Sweep order</Heading>
+ <Card padding={0}>
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Step</TableHeaderCell>
+ <TableHeaderCell>Why this order</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {[
+ [
+ '1. Land the semantic tokens as aliases',
+ 'Nothing to migrate to until they exist, and aliasing means nothing shifts perceptually while the sweep runs.',
+ ],
+ [
+ '2. Add the lint rules in warn mode',
+ 'Produces the real inventory continuously, so this page stops being a snapshot.',
+ ],
+ [
+ '3. Answer the two blocked families',
+ 'Whether --duration-instant is 0 or 0.01ms, and whether the slow band grows an ambient tier.',
+ ],
+ [
+ '4. Sweep',
+ 'Mechanical once the tokens and the answers both exist.',
+ ],
+ [
+ '5. Flip lint to error',
+ 'Only once the count is zero, or the remainder is explicitly allowlisted.',
+ ],
+ ].map(([step, why]) => (
+ <TableRow key={step}>
+ <TableCell>
+ <Text weight="semibold">{step}</Text>
+ </TableCell>
+ <TableCell>
+ <Text color="secondary">{why}</Text>
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+ </Card>
+ <Text type="supporting" color="secondary">
+ The rule stub is on <Link href="/motion/export">Export tuning</Link>.
+ The reduced-motion decision that blocks family one is on{' '}
+ <Link href="/motion/reduced-motion">Reduced motion</Link>.
+ </Text>
+ </VStack>
+ </LabPage>
+ );
+}
diff --git a/apps/sandbox/src/motion/previewPlan.ts b/apps/sandbox/src/motion/previewPlan.ts
new file mode 100644
index 0000000000..becc7c917f
--- /dev/null
+++ b/apps/sandbox/src/motion/previewPlan.ts
@@ -0,0 +1,1288 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file previewPlan.ts
+ * @input The project brief's coverage table, checked against the generated audit
+ * @output What every component's preview has to demonstrate, and what it needs
+ * @position Motion Lab data module; no React, no side effects
+ *
+ * A build plan rather than a gallery. Every row names the HARD case, because
+ * a preview that only shows the easy case is worth nothing: a disclosure that
+ * expands a paragraph proves nothing about a disclosure inside a table row,
+ * and a menu that opens on click proves nothing about one dismissed by moving
+ * the pointer away.
+ *
+ * `dirs` carries the core component directories the row covers, so the page
+ * can check each verdict against ANIMATING_COMPONENTS / STATIC_COMPONENTS
+ * instead of trusting the brief. Several rows do not survive that check.
+ */
+
+import {
+ ANIMATING_COMPONENTS,
+ STATIC_COMPONENTS,
+} from './__generated__/motionAudit';
+
+export type Verdict = 'GOOD' | 'PARTIAL' | 'ADD' | 'NONE';
+
+export type PreviewRow = {
+ readonly id: string;
+ readonly component: string;
+ readonly group: string;
+ readonly verdict: Verdict;
+ /** Core directories this row covers, for the measurement cross-check. */
+ readonly dirs: ReadonlyArray<string>;
+ readonly today: string;
+ readonly gap: string;
+ readonly shows: string;
+ /** The case that decides the technique. Everything else is decoration. */
+ readonly hardCase: string;
+ readonly controls: ReadonlyArray<string>;
+ readonly status: 'built' | 'specified';
+ /** The rig in LabDemos.tsx, when one exists. */
+ readonly rig: string | null;
+ /** 1 decides an open question, 2 high-frequency, 3 completeness. */
+ readonly priority: 1 | 2 | 3;
+ /** Why the measurement disagrees, when the generic check cannot say. */
+ readonly measurementNote: string | null;
+};
+
+export const PREVIEW_GROUPS: ReadonlyArray<string> = [
+ 'Overlays & layers',
+ 'Disclosure & expansion',
+ 'Navigation',
+ 'Inputs & controls',
+ 'Feedback & status',
+ 'Content & data',
+];
+
+const LAYER_NOTE =
+ 'The entry animation lives in Layer/, which the audit counts as its own directory, so per-directory measurement reads this component as static. The brief and the audit are both right about different things.';
+
+export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
+ // --- Overlays & layers -----------------------------------------------------
+ {
+ id: 'tooltip',
+ component: 'Tooltip',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['Tooltip'],
+ today: 'Direction-aware fade and scale in.',
+ gap: 'Hard-cuts on every dismiss, on the highest-frequency surface in the system.',
+ shows:
+ 'Enter and exit at four placements, with the exit curve and duration separately tunable from the entry.',
+ hardCase:
+ 'Pointer moves from trigger to trigger. The exit of one overlaps the entry of the next, and the frequency argument says this surface may deserve no exit at all — the preview has to make that case answerable rather than assumed.',
+ controls: [
+ 'enter duration',
+ 'exit duration',
+ 'exit curve',
+ 'placement',
+ 'reduced motion',
+ ],
+ status: 'built',
+ rig: 'LayerRig',
+ priority: 1,
+ measurementNote: LAYER_NOTE,
+ },
+ {
+ id: 'hovercard',
+ component: 'HoverCard',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['HoverCard'],
+ today: 'Fade and scale in.',
+ gap: 'No exit; the most visible instance of the gap because the surface is large.',
+ shows:
+ 'A card-sized surface entering and leaving, beside a tooltip-sized one on the same timings.',
+ hardCase:
+ 'Large surfaces need longer than small ones at the same perceived speed. The preview has to show whether one --duration-enter can serve both, or whether size has to scale it.',
+ controls: ['enter duration', 'exit duration', 'surface size', 'open delay'],
+ status: 'built',
+ rig: 'LayerRig',
+ priority: 2,
+ measurementNote: LAYER_NOTE,
+ },
+ {
+ id: 'popover',
+ component: 'Popover',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['Popover'],
+ today: 'Fade and scale in.',
+ gap: 'No exit.',
+ shows:
+ 'Click-triggered presence, with transform-origin anchored to the trigger rather than the centre.',
+ hardCase:
+ 'Dismissal by outside-press while focus is inside the popover. Focus has to leave before the element does, and the preview is where that ordering gets agreed.',
+ controls: ['enter duration', 'exit duration', 'origin', 'dismiss method'],
+ status: 'built',
+ rig: 'LayerRig',
+ priority: 1,
+ measurementNote: LAYER_NOTE,
+ },
+ {
+ id: 'dropdownmenu',
+ component: 'DropdownMenu',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['DropdownMenu'],
+ today: 'Fade and scale in, submenus too.',
+ gap: 'No exit; menus snap shut.',
+ shows:
+ 'A menu and a submenu, both directions, with the submenu inheriting the parent timing.',
+ hardCase:
+ 'Selecting an item closes the menu and performs the action at the same time. If the exit is not interruptible the action feels late; if it is skipped the menu blinks.',
+ controls: [
+ 'enter duration',
+ 'exit duration',
+ 'submenu delay',
+ 'selection behaviour',
+ ],
+ status: 'built',
+ rig: 'LayerRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'contextmenu',
+ component: 'ContextMenu',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['ContextMenu'],
+ today: 'Fade and scale in.',
+ gap: 'No exit.',
+ shows:
+ 'Pointer-anchored entry, where the origin is a coordinate rather than an element.',
+ hardCase:
+ 'Right-click while a menu is already open. The old one has to leave while the new one arrives, from a different origin.',
+ controls: ['enter duration', 'exit duration', 'origin'],
+ status: 'built',
+ rig: 'LayerRig',
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'selectors',
+ component: 'Selector / ComplexSelector / MultiSelector',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['Selector', 'ComplexSelector', 'MultiSelector'],
+ today: 'Chevron rotate plus layer entry.',
+ gap: 'No exit. The brief also claims three dead no-op transition rules here.',
+ shows:
+ 'Chevron and layer on one timeline, so the two do not disagree about how long opening takes.',
+ hardCase:
+ 'Keyboard-driven open and close, which is the frequency band the rubric says gets no motion at all. The preview has to show the pointer path and the keyboard path side by side.',
+ controls: [
+ 'enter duration',
+ 'exit duration',
+ 'chevron duration',
+ 'input method',
+ ],
+ status: 'built',
+ rig: 'LayerRig',
+ priority: 2,
+ measurementNote:
+ 'The brief\u2019s three dead no-op transitions are not in the measured data. The only no-op is Lightbox/Lightbox.tsx:192, and it is deliberate.',
+ },
+ {
+ id: 'overflow-layers',
+ component: 'PowerSearch / Typeahead / MoreMenu',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['PowerSearch', 'Typeahead', 'MoreMenu'],
+ today: 'Layer entry only.',
+ gap: 'No exit, and no motion when tokens or results are added and removed.',
+ shows:
+ 'The layer, and separately the list inside it changing as the query changes.',
+ hardCase:
+ 'Results replacing results while the layer stays open. Animating the container is easy; animating a filtered list without making typing feel laggy is the decision.',
+ controls: [
+ 'enter duration',
+ 'exit duration',
+ 'list item stagger',
+ 'filter debounce',
+ ],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: LAYER_NOTE,
+ },
+ {
+ id: 'dialog',
+ component: 'Dialog',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['Dialog'],
+ today: 'Directional keyframe entry.',
+ gap: 'No exit, and the backdrop has no transition at all, so the scrim hard-cuts.',
+ shows:
+ 'Panel and backdrop as two separately tunable timelines, plus focus return timing.',
+ hardCase:
+ 'Focus return during the exit. Dialog returns focus the moment it closes, so with a real exit the page can scroll to the trigger while the dialog is still on screen.',
+ controls: [
+ 'panel duration',
+ 'backdrop duration',
+ 'focus return delay',
+ 'reduced motion',
+ ],
+ status: 'built',
+ rig: 'DialogRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'alertdialog',
+ component: 'AlertDialog',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['AlertDialog'],
+ today: 'Inherits the Dialog entry.',
+ gap: 'No exit. Destructive confirmation is the one dialog where a slow dismissal is wrong.',
+ shows:
+ 'The same rig as Dialog with the exit deliberately shorter, to test whether one token can serve both.',
+ hardCase:
+ 'Confirming a destructive action. The dialog should be gone before the consequence appears, which is an argument for exit being shorter than enter rather than symmetric.',
+ controls: ['panel duration', 'exit duration', 'confirm vs cancel path'],
+ status: 'built',
+ rig: 'DialogRig',
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'commandpalette',
+ component: 'CommandPalette',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: ['CommandPalette'],
+ today: 'Inherits the Dialog entry.',
+ gap: 'No exit, and no motion on the result list as it filters.',
+ shows: 'Opening, typing, and the list reordering underneath, all at once.',
+ hardCase:
+ 'Keystroke-rate list changes. This is the clearest case in the system for animating nothing: the rubric says 100+/day actions get none, and a palette is used by exactly those people.',
+ controls: [
+ 'enter duration',
+ 'list stagger',
+ 'reduced motion',
+ 'typing speed',
+ ],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'lightbox',
+ component: 'Lightbox',
+ group: 'Overlays & layers',
+ verdict: 'ADD',
+ dirs: ['Lightbox'],
+ today: 'Image zoom and pan only.',
+ gap: 'A full-screen surface with no open or close at all.',
+ shows:
+ 'Opening from the thumbnail that triggered it, not from the centre of the screen.',
+ hardCase:
+ 'The shared-element case: the image should appear to be the thumbnail growing. Everything else is a crossfade, and a crossfade on a full-screen surface is the thing the brief calls jarring.',
+ controls: ['open duration', 'close duration', 'origin', 'backdrop opacity'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote:
+ 'Measured as animating: the zoom and pan are real, but they are not the open and close the row is asking for.',
+ },
+ {
+ id: 'bottomsheet',
+ component: 'BottomSheet',
+ group: 'Overlays & layers',
+ verdict: 'GOOD',
+ dirs: ['BottomSheet'],
+ today: 'Backdrop and panel, drag-aware, with its own exit curve.',
+ gap: 'None — this is the reference implementation, and the source of --ease-exit.',
+ shows:
+ 'Its two hardcoded curves beside the proposed tokens, to prove the tokens reproduce them exactly.',
+ hardCase:
+ 'Drag-to-dismiss released mid-gesture. The spring has to carry the velocity the finger had; a keyframe restarts from zero and the sheet stutters.',
+ controls: ['panel duration', 'exit curve', 'drag velocity', 'bounce'],
+ status: 'specified',
+ rig: null,
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'mobilenav',
+ component: 'MobileNav',
+ group: 'Overlays & layers',
+ verdict: 'GOOD',
+ dirs: ['MobileNav'],
+ today:
+ 'Slide plus backdrop; reads its own computed duration to time the close.',
+ gap: 'None — the best-reasoned close timing in the repo, and an argument for the JS mirror.',
+ shows:
+ 'The getComputedStyle read that times the close, and the same thing done through the mirror.',
+ hardCase:
+ 'The close timing has to survive a theme that retunes the duration scale. That is exactly what the JS mirror is for, and this component is the existing proof it is needed.',
+ controls: ['slide duration', 'backdrop duration', 'theme scale'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'overlay',
+ component: 'Overlay / scrim',
+ group: 'Overlays & layers',
+ verdict: 'GOOD',
+ dirs: ['Overlay'],
+ today: 'Per-edge slide, both directions.',
+ gap: 'None — the template the presence primitive should generalise.',
+ shows:
+ 'All four edges, so the primitive\u2019s API is designed against the hardest of them rather than the first.',
+ hardCase:
+ 'Edge-dependent transform origin with a scrim that must not slide with the panel. Two elements, one dismissal, different curves.',
+ controls: ['edge', 'panel duration', 'scrim duration', 'scrim curve'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'drawer',
+ component: 'Drawer (lab)',
+ group: 'Overlays & layers',
+ verdict: 'PARTIAL',
+ dirs: [],
+ today: 'Slide plus backdrop.',
+ gap: 'Closes after a hardcoded 250ms while the slide is 410ms, so the exit is cut at ~60%.',
+ shows:
+ 'The cut, at 1x and slowed down, beside the same close awaiting its transition.',
+ hardCase:
+ 'Proving the bug is visible at 1x. If it is not, the finding is a code-hygiene issue rather than a user-facing one, and it should be scheduled as such.',
+ controls: ['slide duration', 'unmount delay', 'slow-mo'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote:
+ 'Measured: lab is a workspace package here, so this row is checked rather than assumed.',
+ },
+
+ // --- Disclosure & expansion ------------------------------------------------
+ {
+ id: 'collapsible',
+ component: 'Collapsible',
+ group: 'Disclosure & expansion',
+ verdict: 'GOOD',
+ dirs: ['Collapsible'],
+ today: 'Height interpolation, offset content fade, theme-tunable.',
+ gap: 'None, but it is the only component doing it this way.',
+ shows:
+ 'Height interpolation against grid-track expansion on identical content.',
+ hardCase:
+ 'Content whose height is unknown until it renders, and content that changes height while open. Height interpolation needs a measurement; grid tracks do not.',
+ controls: ['duration', 'curve', 'content height', 'technique'],
+ status: 'built',
+ rig: 'DisclosureRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'codeblock',
+ component: 'CodeBlock',
+ group: 'Disclosure & expansion',
+ verdict: 'PARTIAL',
+ dirs: ['CodeBlock'],
+ today: 'Grid-track expand plus chevron.',
+ gap: 'A different technique from Collapsible, for the same job.',
+ shows:
+ 'The same expansion in both techniques, with the chevron on a shared timeline.',
+ hardCase:
+ 'Long content that overflows. Grid tracks animate to a content-derived size; a max-height fallback does not, and the difference only shows on the long case.',
+ controls: ['duration', 'curve', 'content length', 'technique'],
+ status: 'built',
+ rig: 'DisclosureRig',
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'table-row-expansion',
+ component: 'Table row expansion',
+ group: 'Disclosure & expansion',
+ verdict: 'ADD',
+ dirs: ['Table'],
+ today: 'Chevron rotate only.',
+ gap: 'The revealed content appears instantly.',
+ shows: 'A row expanding inside a real table, in both techniques.',
+ hardCase:
+ 'This is the row that decides the whole disclosure question: a table row cannot be a grid container, so the grid-track technique is unavailable here. If the answer is "one technique everywhere", it has to be height — and this preview is the evidence.',
+ controls: ['duration', 'curve', 'technique', 'row count'],
+ status: 'specified',
+ rig: null,
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'table-tree',
+ component: 'Table tree / grouped rows',
+ group: 'Disclosure & expansion',
+ verdict: 'ADD',
+ dirs: ['Table'],
+ today: 'Chevron rotate only.',
+ gap: 'Same as row expansion, plus the hardcoded 150ms values.',
+ shows:
+ 'Expanding a group of rows rather than one, with the 150ms and the token side by side.',
+ hardCase:
+ 'Expanding many rows at once. Per-row stagger is the obvious idea and the wrong one: at 30ms across twenty rows the last row arrives 600ms late.',
+ controls: ['duration', 'stagger', 'row count', 'reduced motion'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote:
+ 'The brief\u2019s "nine hardcoded values in Table" and "six in Table tree" are the same set: nine 150ms values across columnResize, groupedRows, rowExpansion, stickyColumns and tree.',
+ },
+ {
+ id: 'treelist',
+ component: 'TreeList',
+ group: 'Disclosure & expansion',
+ verdict: 'ADD',
+ dirs: ['TreeList'],
+ today: 'Row tint plus chevron.',
+ gap: 'The child list reveal is instant.',
+ shows: 'Nested reveal, where expanding a child moves everything below it.',
+ hardCase:
+ 'Expanding a deep node near the bottom of the viewport. The reveal and the scroll compensation fight each other, and doing neither is better than doing both badly.',
+ controls: ['duration', 'depth', 'scroll compensation'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'chat-disclosure',
+ component: 'Chat tool calls / reasoning',
+ group: 'Disclosure & expansion',
+ verdict: 'PARTIAL',
+ dirs: ['Chat'],
+ today: 'Grid-track expand; a 1.5s reasoning shimmer.',
+ gap: 'A third disclosure technique, and the shimmer has no reduced-motion escape.',
+ shows:
+ 'The shimmer with and without the reduced-motion branch, and the disclosure in both techniques.',
+ hardCase:
+ 'Content streaming in while the container is animating open. The height target moves during the transition, which is where height interpolation fails and grid tracks do not.',
+ controls: ['duration', 'technique', 'stream rate', 'reduced motion'],
+ status: 'specified',
+ rig: null,
+ priority: 1,
+ measurementNote: null,
+ },
+
+ // --- Navigation ------------------------------------------------------------
+ {
+ id: 'sidenav',
+ component: 'SideNav',
+ group: 'Navigation',
+ verdict: 'ADD',
+ dirs: ['SideNav'],
+ today: 'Sub-list expand, chevron, collapse button.',
+ gap: 'The rail\u2019s own collapse is not animated; only the chevron rotates.',
+ shows: 'The rail collapsing with the labels, at several widths.',
+ hardCase:
+ 'Width is a layout property, so the honest version needs transform or clip-path. The preview has to show whether the cheap version — animating width — is visibly worse, because it is much simpler.',
+ controls: ['duration', 'curve', 'technique', 'label fade offset'],
+ status: 'built',
+ rig: 'RailRig',
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'tablist',
+ component: 'TabList',
+ group: 'Navigation',
+ verdict: 'ADD',
+ dirs: ['TabList'],
+ today: 'Per-tab indicator cross-fade.',
+ gap: 'The indicator does not slide between tabs; each tab owns its own bar.',
+ shows:
+ 'One indicator that travels, against the per-tab cross-fade, on the same tabs.',
+ hardCase:
+ 'Tabs of different widths. The indicator has to change size while it moves, which is a scale on a transform rather than a width, or it thrashes layout on every frame.',
+ controls: ['duration', 'curve', 'spring vs curve', 'tab widths'],
+ status: 'built',
+ rig: 'TabIndicatorRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'segmentedcontrol',
+ component: 'SegmentedControl',
+ group: 'Navigation',
+ verdict: 'ADD',
+ dirs: ['SegmentedControl'],
+ today: 'Per-item background tint.',
+ gap: 'No sliding thumb, so the selected pill jumps.',
+ shows:
+ 'The same travelling-indicator technique as TabList, to confirm one implementation serves both.',
+ hardCase:
+ 'Rapid clicking between segments. The thumb has to retarget mid-flight, which a transition does and a keyframe does not.',
+ controls: ['duration', 'spring bounce', 'click rate'],
+ status: 'built',
+ rig: 'TabIndicatorRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'topnav',
+ component: 'TopNav',
+ group: 'Navigation',
+ verdict: 'PARTIAL',
+ dirs: ['TopNav'],
+ today: 'Mega-menu with a real exit, sub-lists, chevrons.',
+ gap: 'The only component animating a popover exit, and it never checks reduced motion.',
+ shows:
+ 'Its exit as the existing proof the pattern works, plus the missing reduced-motion branch.',
+ hardCase:
+ 'A mega-menu is large and frequently traversed. It is the one place where the published "no exit needed" guidance is most obviously wrong, and this component already disagrees with the docs.',
+ controls: [
+ 'enter duration',
+ 'exit duration',
+ 'reduced motion',
+ 'traverse speed',
+ ],
+ status: 'specified',
+ rig: null,
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'navitem',
+ component: 'NavItem / NavMenu',
+ group: 'Navigation',
+ verdict: 'ADD',
+ dirs: ['NavItem', 'NavMenu'],
+ today: 'Nothing.',
+ gap: 'No hover or active transition, unlike every sibling nav item.',
+ shows:
+ 'A tint transition at the state token, beside the untransitioned original.',
+ hardCase:
+ 'Hover on a touch device, where a tap fires a false hover. The rubric requires this to be gated to fine pointers, and this is the cheapest place to prove the gate works.',
+ controls: ['duration', 'pointer type', 'reduced motion'],
+ status: 'built',
+ rig: 'TintRig',
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'outline',
+ component: 'Outline',
+ group: 'Navigation',
+ verdict: 'PARTIAL',
+ dirs: ['Outline'],
+ today: 'Marker slide plus item tint.',
+ gap: 'Animates top and height, which thrashes layout.',
+ shows:
+ 'The same marker on transform and on top/height, with a paint-cost readout.',
+ hardCase:
+ 'Scroll-linked movement. The marker moves on every scroll frame, so a layout-triggering property here costs more than anywhere else in the audit.',
+ controls: ['duration', 'technique', 'scroll rate'],
+ status: 'built',
+ rig: 'OutlineMarkerRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'breadcrumbs',
+ component: 'Breadcrumbs',
+ group: 'Navigation',
+ verdict: 'PARTIAL',
+ dirs: ['Breadcrumbs'],
+ today: 'Overflow menu entry.',
+ gap: 'Crumb collapse on resize is instant.',
+ shows: 'Crumbs collapsing into the overflow as the container narrows.',
+ hardCase:
+ 'Resize is continuous, so the collapse can fire many times a second. This is a strong candidate for animating nothing, and the preview should make that easy to conclude.',
+ controls: ['container width', 'duration', 'debounce'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: LAYER_NOTE,
+ },
+ {
+ id: 'pagination',
+ component: 'Pagination',
+ group: 'Navigation',
+ verdict: 'ADD',
+ dirs: ['Pagination'],
+ today: 'Cell tint.',
+ gap: 'Page change is an instant content swap.',
+ shows:
+ 'Directional content movement: forward goes one way, back goes the other.',
+ hardCase:
+ 'Directionality is a published principle that the rubric drops entirely. This preview and Calendar are the two rows that would be measured against it, so they are the argument for adding the criterion.',
+ controls: ['duration', 'direction', 'reduced motion'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: null,
+ },
+
+ // --- Inputs & controls -----------------------------------------------------
+ {
+ id: 'button',
+ component: 'Button',
+ group: 'Inputs & controls',
+ verdict: 'GOOD',
+ dirs: ['Button'],
+ today: 'Tint, press scale, loading swap.',
+ gap: 'The brief calls the press transform transition the main Motion conflict.',
+ shows:
+ 'Press feedback on transform, on the independent scale property, and not at all.',
+ hardCase:
+ 'A motion library writing transform every frame while the CSS transition re-eases it. This is the whole of blocker 2, and it is answerable by dragging one button.',
+ controls: ['press duration', 'technique', 'library drag'],
+ status: 'built',
+ rig: 'PressRig',
+ priority: 1,
+ measurementNote:
+ 'Button has no transform transition in the measured data. Its only hardcoded value is animationDuration: 1ms at Button/Button.tsx:407 — a reduced-motion escape, not press feedback. The brief\u2019s "Button is the worst case" does not hold.',
+ },
+ {
+ id: 'iconbutton',
+ component: 'IconButton / ToggleButton',
+ group: 'Inputs & controls',
+ verdict: 'GOOD',
+ dirs: ['IconButton', 'ToggleButton'],
+ today: 'Tint and press feedback inherited from Button.',
+ gap: 'None named, but the toggle state change is not distinguished from a press.',
+ shows:
+ 'Press feedback and state change as two separate timings on the same control.',
+ hardCase:
+ 'A toggle that is pressed and then changes state. Two animations on one gesture: if they share a duration the state change is invisible.',
+ controls: ['press duration', 'state duration', 'toggle rate'],
+ status: 'built',
+ rig: 'PressRig',
+ priority: 3,
+ measurementNote:
+ 'Neither IconButton nor ToggleButton has motion of its own: the press feedback belongs to Button, and per-directory measurement does not follow composition.',
+ },
+ {
+ id: 'switch',
+ component: 'Switch',
+ group: 'Inputs & controls',
+ verdict: 'GOOD',
+ dirs: ['Switch'],
+ today: 'Track tint plus thumb travel.',
+ gap: 'Animates the thumb width and height, which are layout properties.',
+ shows: 'The thumb on width/height against the same thumb on transform.',
+ hardCase:
+ 'Fast repeated toggling. Layout-property animation is cheap on one switch and expensive in a settings list of thirty, which is where this component actually lives.',
+ controls: ['duration', 'technique', 'switch count', 'toggle rate'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'checkbox',
+ component: 'CheckboxInput / RadioList / Indicator',
+ group: 'Inputs & controls',
+ verdict: 'ADD',
+ dirs: ['CheckboxInput', 'RadioList', 'Indicator'],
+ today: 'Box tint and border.',
+ gap: 'The tick and the dot never draw or scale in.',
+ shows:
+ 'Three techniques on the tick: hard swap, stroke draw, and scale-in.',
+ hardCase:
+ 'Select-all across twenty checkboxes. A tick that draws in 200ms is charming once and a mess twenty times at once, which is the frequency argument made visible.',
+ controls: ['duration', 'technique', 'stagger', 'item count'],
+ status: 'built',
+ rig: 'CheckTickRig',
+ priority: 2,
+ measurementNote:
+ 'Indicator is measured as animating while CheckboxInput and RadioList are not, so the row\u2019s "box tint" is really Indicator\u2019s.',
+ },
+ {
+ id: 'field',
+ component: 'Field / TextInput / TextArea / NumberInput',
+ group: 'Inputs & controls',
+ verdict: 'GOOD',
+ dirs: ['Field', 'TextInput', 'TextArea', 'NumberInput'],
+ today: 'Border and focus ring transitions.',
+ gap: 'TextArea auto-grow is not animated.',
+ shows:
+ 'Focus ring timing at the state token, and auto-grow with and without a height transition.',
+ hardCase:
+ 'Auto-grow while typing. The height changes on a keystroke, so any duration above about 100ms means the field is still growing when the next character lands.',
+ controls: ['state duration', 'grow duration', 'typing speed'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote:
+ 'Only Field is measured as animating. TextInput, TextArea and NumberInput have no motion of their own — the row\u2019s verdict belongs to the shared Field wrapper.',
+ },
+ {
+ id: 'slider',
+ component: 'Slider',
+ group: 'Inputs & controls',
+ verdict: 'PARTIAL',
+ dirs: ['Slider'],
+ today: 'Thumb tint and shadow.',
+ gap: 'The thumb does not transition on keyboard step.',
+ shows:
+ 'Keyboard stepping with and without a transition, beside a pointer drag.',
+ hardCase:
+ 'The same thumb must be transitioned for keyboard and untransitioned for drag, or dragging lags the pointer. One control, two input paths, opposite answers.',
+ controls: ['step duration', 'input method', 'step size'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'calendar',
+ component: 'Calendar / DateInput',
+ group: 'Inputs & controls',
+ verdict: 'GOOD',
+ dirs: ['Calendar', 'DateInput'],
+ today:
+ 'Cell tint; the touch wheel is scroll-driven and genuinely advanced.',
+ gap: 'No month-change transition.',
+ shows: 'Month change with direction, beside the existing instant swap.',
+ hardCase:
+ 'Holding the arrow to move six months. Each step has to be interruptible and the direction has to stay legible, which rules out a keyframe.',
+ controls: ['duration', 'direction', 'repeat rate'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote:
+ 'DateInput carries nine of the hardcoded values, all 0.01s reduced-motion escapes in TouchDateField.tsx.',
+ },
+ {
+ id: 'tokenizer',
+ component: 'Tokenizer / Token',
+ group: 'Inputs & controls',
+ verdict: 'ADD',
+ dirs: ['Tokenizer', 'Token'],
+ today: 'Background transition on the token only.',
+ gap: 'Chip add and remove, the canonical scale-in case, is instant.',
+ shows:
+ 'Add and remove with the surrounding chips reflowing, not just the chip itself appearing.',
+ hardCase:
+ 'Removing a chip from the middle of a wrapped row. Everything after it moves, and moving them is the animation — the chip leaving is the easy half.',
+ controls: [
+ 'enter duration',
+ 'exit duration',
+ 'reflow duration',
+ 'chip count',
+ ],
+ status: 'built',
+ rig: 'ChipRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'fileinput',
+ component: 'FileInput',
+ group: 'Inputs & controls',
+ verdict: 'PARTIAL',
+ dirs: ['FileInput'],
+ today: 'Dropzone border and tint.',
+ gap: 'File chips add and remove with no motion.',
+ shows: 'Chips arriving as files are dropped, with upload progress on each.',
+ hardCase:
+ 'A chip that arrives and then changes state while it is still arriving. Entry and progress on one element, which is the case ChipRig deliberately does not cover.',
+ controls: ['enter duration', 'stagger', 'progress rate', 'file count'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'resizable',
+ component: 'Resizable',
+ group: 'Inputs & controls',
+ verdict: 'PARTIAL',
+ dirs: ['Resizable'],
+ today: 'Handle tint and grip.',
+ gap: 'Panel snap and collapse are instant.',
+ shows:
+ 'Snap-to-position and collapse animated, with the drag itself left untransitioned.',
+ hardCase:
+ 'The drag must not be transitioned and the release must be. The transition has to be added on release and removed on grab, which is a state machine rather than a style.',
+ controls: ['snap duration', 'curve', 'snap points'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+
+ // --- Feedback & status -----------------------------------------------------
+ {
+ id: 'toast',
+ component: 'Toast',
+ group: 'Feedback & status',
+ verdict: 'GOOD',
+ dirs: ['Toast'],
+ today: 'Entry, exit, and stack collapse.',
+ gap: 'None, though it animates grid tracks and padding.',
+ shows:
+ 'Entry and exit interrupted mid-flight, since this is the most interruptible surface in the system.',
+ hardCase:
+ 'A toast dismissed while another is entering and a third is collapsing the stack. Three animations on one list, and the reference case for the interruptibility criterion.',
+ controls: [
+ 'enter duration',
+ 'exit duration',
+ 'collapse duration',
+ 'toast rate',
+ ],
+ status: 'built',
+ rig: 'InterruptRig',
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'banner',
+ component: 'Banner',
+ group: 'Feedback & status',
+ verdict: 'ADD',
+ dirs: ['Banner'],
+ today: 'Chevron rotate.',
+ gap: 'A dismissible banner appearing and leaving is unanimated.',
+ shows:
+ 'Dismissal with the content below closing the gap, rather than snapping up.',
+ hardCase:
+ 'The banner leaving is easy; the page reflowing underneath it is the animation. Height on the container, or transform on everything below.',
+ controls: ['exit duration', 'reflow duration', 'technique'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'skeleton',
+ component: 'Skeleton',
+ group: 'Feedback & status',
+ verdict: 'ADD',
+ dirs: ['Skeleton'],
+ today: 'Staggered pulse.',
+ gap: 'No skeleton-to-content crossfade; content hard-swaps.',
+ shows:
+ 'The swap at several load times, including one fast enough that the skeleton should never have appeared.',
+ hardCase:
+ 'Content arriving in 80ms. The crossfade makes a fast load look slower than no skeleton at all, so the preview has to expose the minimum-display-time decision, not just the fade.',
+ controls: ['crossfade duration', 'load time', 'minimum display time'],
+ status: 'built',
+ rig: 'SkeletonSwapRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'spinner',
+ component: 'Spinner',
+ group: 'Feedback & status',
+ verdict: 'PARTIAL',
+ dirs: ['Spinner'],
+ today: 'Rotation.',
+ gap: 'Reduced motion slows the loop to 3s rather than stopping it.',
+ shows: 'Today, delete, and degrade as three policies on the same spinner.',
+ hardCase:
+ 'A stopped spinner communicates nothing. Degrading a loop means replacing it with a determinate state, which is a component change rather than a CSS branch — the reason this decision is not free.',
+ controls: ['loop duration', 'policy', 'reduced motion'],
+ status: 'built',
+ rig: 'LoopRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'progressbar',
+ component: 'ProgressBar',
+ group: 'Feedback & status',
+ verdict: 'PARTIAL',
+ dirs: ['ProgressBar'],
+ today: 'Width fill plus an indeterminate slide.',
+ gap: 'Animates width; reduced motion slows rather than stops.',
+ shows:
+ 'Width against transform: scaleX, and the indeterminate loop under all three policies.',
+ hardCase:
+ 'scaleX distorts the bar\u2019s end caps and any label inside it. The compositor-only rule is right in general and needs an exception here, or a different structure.',
+ controls: ['fill duration', 'technique', 'policy'],
+ status: 'built',
+ rig: 'LoopRig',
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'statusdot',
+ component: 'StatusDot',
+ group: 'Feedback & status',
+ verdict: 'PARTIAL',
+ dirs: ['StatusDot'],
+ today: 'A pulse at a hardcoded 2s with ease-in-out.',
+ gap: 'Bypasses the scale entirely, because the scale stops at 1300ms.',
+ shows:
+ 'The pulse at 2s beside the longest token, so the missing band is visible rather than argued.',
+ hardCase:
+ 'Ambient motion is not interface motion. Either the scale grows a band for it or the system says ambient loops are out of scope — this row and Chat reasoning are the only two asking.',
+ controls: ['loop duration', 'policy', 'dot count'],
+ status: 'built',
+ rig: 'LoopRig',
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'fieldstatus',
+ component: 'FieldStatus',
+ group: 'Feedback & status',
+ verdict: 'PARTIAL',
+ dirs: ['FieldStatus'],
+ today: 'Slide-down entry, via the shared entry hook.',
+ gap: 'Error text leaves instantly.',
+ shows:
+ 'Error text arriving and leaving, and text replacing text without leaving first.',
+ hardCase:
+ 'Validation firing on every keystroke. The error message changes while it is still entering, which is the interruptibility criterion on a surface nobody thinks of as animated.',
+ controls: ['enter duration', 'exit duration', 'validation rate'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote:
+ 'Measured as static: the entry lives in hooks/containerReveal.stylex.ts, not in the component. That shared hook also holds three of the hardcoded values.',
+ },
+ {
+ id: 'badge',
+ component: 'Badge',
+ group: 'Feedback & status',
+ verdict: 'ADD',
+ dirs: ['Badge'],
+ today: 'Nothing.',
+ gap: 'Count changes pop in.',
+ shows: 'A count changing with and without a digit transition.',
+ hardCase:
+ 'A count that changes several times a second, which is what a notification badge does. The rubric\u2019s frequency criterion probably says do nothing, and the preview should be allowed to conclude that.',
+ controls: ['duration', 'change rate', 'technique'],
+ status: 'built',
+ rig: 'StatCountRig',
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'avatar',
+ component: 'Avatar / AvatarGroup',
+ group: 'Feedback & status',
+ verdict: 'ADD',
+ dirs: ['Avatar', 'AvatarGroup'],
+ today: 'Nothing.',
+ gap: 'Image load and member enter/leave both pop in.',
+ shows:
+ 'Image fade-in on load, and members joining and leaving a stacked group.',
+ hardCase:
+ 'A cached image loads in the same frame as the component mounts, so a fade-in animates something that was never absent. The preview has to include the cached case or it will ship a flash.',
+ controls: ['fade duration', 'stagger', 'cache state', 'group size'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+
+ // --- Content & data --------------------------------------------------------
+ {
+ id: 'markdown',
+ component: 'Markdown',
+ group: 'Content & data',
+ verdict: 'GOOD',
+ dirs: ['Markdown'],
+ today: 'Streaming chunk fade-in.',
+ gap: 'None — well built, and the only streaming-aware motion in the system.',
+ shows:
+ 'Chunk fade-in at several stream rates, including faster than the fade.',
+ hardCase:
+ 'Chunks arriving faster than the fade duration. Overlapping fades either stack into a flicker or have to be dropped, and the current code has an answer worth documenting.',
+ controls: ['fade duration', 'stream rate', 'chunk size'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'thumbnail',
+ component: 'Thumbnail',
+ group: 'Content & data',
+ verdict: 'GOOD',
+ dirs: ['Thumbnail'],
+ today: 'Hover-intent reveal for actions.',
+ gap: 'None — the only consumer of the most sophisticated motion code in the repo.',
+ shows:
+ 'Hover intent with the delay exposed, and the same interaction on a touch device.',
+ hardCase:
+ 'A tap on touch fires a false hover. Hover-intent logic that is correct with a pointer reveals actions that cannot be dismissed on touch.',
+ controls: ['intent delay', 'reveal duration', 'pointer type'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'table-rows',
+ component: 'Table rows',
+ group: 'Content & data',
+ verdict: 'PARTIAL',
+ dirs: ['Table'],
+ today: 'Row tint.',
+ gap: 'No reduced-motion handling anywhere in Table, and nine hardcoded 150ms values.',
+ shows:
+ 'The 150ms tint against the state token, over enough rows to feel it.',
+ hardCase:
+ 'Row hover is the published page\u2019s own example of where motion hurts. The preview should make deleting the transition a visible option, not just retokenising it.',
+ controls: ['duration', 'row count', 'pointer speed', 'reduced motion'],
+ status: 'built',
+ rig: 'TintRig',
+ priority: 1,
+ measurementNote: null,
+ },
+ {
+ id: 'carousel',
+ component: 'Carousel',
+ group: 'Content & data',
+ verdict: 'PARTIAL',
+ dirs: ['Carousel'],
+ today: 'Edge fade plus control opacity.',
+ gap: 'A paint-heavy mask transition, and no explicit slide.',
+ shows: "The mask transition's cost beside a transform-based slide.",
+ hardCase:
+ 'Scroll-linked edge fades repaint on every scroll frame. This is the one place in the audit where a mask is animated, and it needs a measurement rather than an opinion.',
+ controls: ['slide duration', 'technique', 'scroll rate'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'list',
+ component: 'List / OverflowList',
+ group: 'Content & data',
+ verdict: 'ADD',
+ dirs: ['List', 'OverflowList'],
+ today: 'Item tint only.',
+ gap: 'Add, remove and reorder are all instant.',
+ shows:
+ 'Reorder with FLIP, against reorder with View Transitions, on the same list.',
+ hardCase:
+ 'Reordering while the list is scrolled. Items that move out of view still animate, and the technique that handles that well is the one to standardise on.',
+ controls: ['duration', 'technique', 'item count', 'scroll position'],
+ status: 'built',
+ rig: 'ListReorderRig',
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'emptystate',
+ component: 'EmptyState',
+ group: 'Content & data',
+ verdict: 'ADD',
+ dirs: ['EmptyState'],
+ today: 'Nothing.',
+ gap: 'The archetypal content-swap surface, entirely static.',
+ shows: 'Empty to populated and back, as a crossfade and as a replace.',
+ hardCase:
+ 'Going from empty to populated after a search. The empty state and the results are different heights, so the container moves — and that movement is the animation people actually notice.',
+ controls: ['crossfade duration', 'height technique', 'result count'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote: null,
+ },
+ {
+ id: 'stepper',
+ component: 'Stepper',
+ group: 'Content & data',
+ verdict: 'GOOD',
+ dirs: ['Stepper'],
+ today: 'Connector fill and node tint.',
+ gap: 'Step content swap is instant.',
+ shows:
+ 'The connector fill with the content swap on the same timeline, and directionality on back.',
+ hardCase:
+ 'Going backwards. The connector has to unfill and the content has to arrive from the other side, or back feels like forward.',
+ controls: ['fill duration', 'swap duration', 'direction'],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+ {
+ id: 'listinput',
+ component: 'ListInput (lab)',
+ group: 'Content & data',
+ verdict: 'GOOD',
+ dirs: [],
+ today: 'View Transitions reorder.',
+ gap: 'None — the only View Transitions user in the repo.',
+ shows:
+ 'Its View Transitions reorder beside a FLIP implementation of the same thing.',
+ hardCase:
+ 'View Transitions are document-scoped, so two of them cannot run at once. A reorder while a route change is animating is where the technique breaks, and it is the reason not to standardise on it blindly.',
+ controls: ['duration', 'technique', 'concurrent transition'],
+ status: 'built',
+ rig: 'ListReorderRig',
+ priority: 2,
+ measurementNote:
+ 'Measured: lab is a workspace package here, so this row is checked rather than assumed.',
+ },
+ {
+ id: 'transferlist',
+ component: 'TransferList (lab)',
+ group: 'Content & data',
+ verdict: 'ADD',
+ dirs: [],
+ today: 'Nothing.',
+ gap: 'Moving an item between lists — the whole point of the component — is instant.',
+ shows:
+ 'An item leaving one list and arriving in the other as one continuous movement.',
+ hardCase:
+ 'Moving several items at once. Individually they are a flight; together they are either a stagger or a swarm, and only one of those is legible.',
+ controls: ['duration', 'stagger', 'item count', 'curve'],
+ status: 'specified',
+ rig: null,
+ priority: 2,
+ measurementNote:
+ 'Measured: lab is a workspace package here, so this row is checked rather than assumed.',
+ },
+ {
+ id: 'stat',
+ component: 'Stat (lab)',
+ group: 'Content & data',
+ verdict: 'ADD',
+ dirs: [],
+ today: 'Nothing.',
+ gap: 'Numeric value changes with no motion.',
+ shows:
+ 'A counting transition against a straight swap, at several magnitudes of change.',
+ hardCase:
+ 'A value that changes while it is still counting, on a live dashboard. Counting animations that cannot retarget end up showing numbers that were never true.',
+ controls: ['count duration', 'change rate', 'magnitude'],
+ status: 'built',
+ rig: 'StatCountRig',
+ priority: 3,
+ measurementNote:
+ 'Measured: lab is a workspace package here, so this row is checked rather than assumed.',
+ },
+ {
+ id: 'charts',
+ component: 'Chart / Radial / Sankey / Schedule (lab)',
+ group: 'Content & data',
+ verdict: 'ADD',
+ dirs: [],
+ today: 'Axis ticks only, via inline styles.',
+ gap: 'No transition on data change, and outside the token system entirely.',
+ shows:
+ 'A data change animated through the JS token mirror, since these draw rather than style.',
+ hardCase:
+ 'Chart code cannot read var(--duration-fast). This family is the reason the JS mirror exists, so its preview is the mirror\u2019s acceptance test rather than a motion demo.',
+ controls: ['duration', 'curve', 'data change size'],
+ status: 'specified',
+ rig: null,
+ priority: 1,
+ measurementNote:
+ 'Measured: lab is a workspace package here, so this row is checked rather than assumed.',
+ },
+ {
+ id: 'layout-primitives',
+ component:
+ 'Layout primitives (Stack, Grid, Card, Divider, Text, Heading, Kbd + 19 more)',
+ group: 'Content & data',
+ verdict: 'NONE',
+ dirs: ['Stack', 'Grid', 'Card', 'Divider', 'Text', 'Heading', 'Kbd'],
+ today: 'Nothing, correctly.',
+ gap: 'None. Motion on a layout primitive is motion on everything that uses it.',
+ shows:
+ 'Nothing. This row exists so the rubric can record a deliberate no rather than an omission.',
+ hardCase:
+ 'The only hard case is resisting the request. When someone asks for a Card hover lift, the answer is that Card is used 400 times and the cost is paid 400 times.',
+ controls: [],
+ status: 'specified',
+ rig: null,
+ priority: 3,
+ measurementNote: null,
+ },
+];
+
+export type Measurement = {
+ readonly kind: 'agrees' | 'contradiction' | 'nuance' | 'unmeasured';
+ readonly animating: ReadonlyArray<string>;
+ readonly notAnimating: ReadonlyArray<string>;
+ readonly note: string;
+};
+
+const ANIMATING = new Set(ANIMATING_COMPONENTS);
+const STATIC = new Set(STATIC_COMPONENTS);
+
+/**
+ * The brief's verdict against the generated audit. A row can disagree in two
+ * directions: the brief says it animates and no motion was measured in that
+ * directory (usually because the motion is inherited from Layer/ or a shared
+ * hook), or the brief says it is static and something was measured.
+ */
+export function measure(row: PreviewRow): Measurement {
+ const animating = row.dirs.filter(dir => ANIMATING.has(dir));
+ const notAnimating = row.dirs.filter(dir => STATIC.has(dir));
+ const known = animating.length + notAnimating.length;
+
+ if (row.dirs.length === 0 || known === 0) {
+ return {
+ kind: 'unmeasured',
+ animating,
+ notAnimating,
+ note: row.measurementNote ?? 'Not covered by the generated audit.',
+ };
+ }
+
+ const saysAnimates = row.verdict === 'GOOD' || row.verdict === 'PARTIAL';
+
+ if (saysAnimates && animating.length === 0) {
+ return {
+ kind: 'contradiction',
+ animating,
+ notAnimating,
+ note:
+ row.measurementNote ??
+ `The brief says this animates; the audit found no transition, animation or keyframe in ${notAnimating.join(', ')}.`,
+ };
+ }
+
+ if (row.verdict === 'NONE' && animating.length > 0) {
+ return {
+ kind: 'contradiction',
+ animating,
+ notAnimating,
+ note:
+ row.measurementNote ??
+ `The brief calls this correctly static; the audit measured motion in ${animating.join(', ')}.`,
+ };
+ }
+
+ if (row.verdict === 'ADD' && animating.length > 0) {
+ return {
+ kind: 'nuance',
+ animating,
+ notAnimating,
+ note:
+ row.measurementNote ??
+ `Measured as animating in ${animating.join(', ')} — but the motion it has is not the motion this row is asking for.`,
+ };
+ }
+
+ if (saysAnimates && notAnimating.length > 0) {
+ return {
+ kind: 'nuance',
+ animating,
+ notAnimating,
+ note:
+ row.measurementNote ??
+ `Split: measured motion in ${animating.join(', ')}, none in ${notAnimating.join(', ')}. The verdict belongs to part of the row.`,
+ };
+ }
+
+ return {
+ kind: 'agrees',
+ animating,
+ notAnimating,
+ note: row.measurementNote ?? '',
+ };
+}
diff --git a/apps/sandbox/src/motion/publishedGuidance.ts b/apps/sandbox/src/motion/publishedGuidance.ts
new file mode 100644
index 0000000000..bc1065ce10
--- /dev/null
+++ b/apps/sandbox/src/motion/publishedGuidance.ts
@@ -0,0 +1,195 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file publishedGuidance.ts
+ * @input The published Motion foundation page (astryx.atmeta.com/docs/motion)
+ * @output Where the proposal contradicts what Astryx tells people today
+ * @position Motion Lab data module; no React, no side effects
+ *
+ * The brief reads the exit gap as drift — "the difference between those two
+ * lists is largely historical rather than deliberate". For eleven of those
+ * components that is not what happened. The published Movement Principles
+ * tell component authors, in as many words, that tooltips, hover cards and
+ * dropdown menus may disappear instantly. The components followed the docs.
+ *
+ * That changes what this project is. Three of its proposals are not bug fixes
+ * but reversals of published guidance, and a reversal needs a decision and a
+ * doc rewrite in the same change — otherwise the rubric fails components for
+ * doing what the docs still tell the next author to do.
+ *
+ * Quotes are verbatim from the page as published, so they can be diffed
+ * against it later.
+ */
+
+export type GuidanceConflict = {
+ readonly id: string;
+ /** The heading it sits under on the published page. */
+ readonly section: string;
+ /** Verbatim, so this file can be checked against the live page. */
+ readonly published: string;
+ readonly proposed: string;
+ readonly reading: string;
+ /** What has to happen for the proposal to be legitimate. */
+ readonly resolution: string;
+ readonly severity: 'reversal' | 'extension' | 'aligned';
+ /** Where in the lab you can look at the two side by side. */
+ readonly href: string;
+};
+
+export const PUBLISHED_PAGE_URL = 'https://astryx.atmeta.com/docs/motion';
+
+export const GUIDANCE_CONFLICTS: ReadonlyArray<GuidanceConflict> = [
+ {
+ id: 'exit-optional',
+ section: 'Movement Principles',
+ published:
+ 'Not everything needs an animated exit. Elements the user is moving away from, such as tooltips, hover cards, and dropdown menus, can disappear instantly. The user has already shifted their attention. Animate the exit only when it helps orient the user, like a panel closing or a dialog dismissing to reveal what\u2019s underneath.',
+ proposed:
+ 'Presence surfaces animate both directions. A surface that animates in and vanishes out fails. (Rubric criterion 7, Blocker for overlays.)',
+ reading:
+ 'The eleven layer components are not drift. They are the published guidance, correctly followed — and it names tooltips, hover cards and dropdown menus specifically, which is most of the list. The brief\u2019s framing of the exit gap as historical accident does not survive this paragraph.',
+ resolution:
+ 'Decide which document is right before writing any code. If the proposal wins, the rewrite of this paragraph ships in the same stack as the layerAnimations change, and the rubric cannot gate anything until it does.',
+ severity: 'reversal',
+ href: '/motion/exit-gap',
+ },
+ {
+ id: 'reduced-motion-delete',
+ section: 'Respecting User Preferences',
+ published:
+ 'When it\u2019s enabled, replace animations with instant state changes.',
+ proposed:
+ 'Honoured, and degraded rather than deleted. Keep opacity and colour, drop movement and position change. (Rubric criterion 10, Blocker.)',
+ reading:
+ 'Deleting motion is not an oversight in the components either — it is what the page instructs. The open question in the brief already asks degrade-or-delete; what the brief does not say is that "delete" is the currently published answer, so degrading is a change of policy rather than a fix.',
+ resolution:
+ 'Needs a designer and accessibility sign-off, then a rewrite of this paragraph. The 39-file sweep writes whichever branch is chosen 39 times, so it cannot start first.',
+ severity: 'reversal',
+ href: '/motion/reduced-motion',
+ },
+ {
+ id: 'exit-matches-entrance',
+ section: 'Movement Principles',
+ published:
+ 'When you do animate exit, match the entrance. A panel that slides in from the right should slide back out to the right.',
+ proposed:
+ 'The exit retraces the entry path and is no slower than it, on the exit curve rather than the entry curve.',
+ reading:
+ 'Aligned on path, and the proposal adds the part the page leaves out: the curve and the duration. Matching the entrance exactly is what produced the sheet\u2019s measured problem, where a decelerate curve spent the travel in the first 59ms of a 410ms close.',
+ resolution:
+ 'Extend the paragraph rather than replace it: same path, opposite curve, shorter duration.',
+ severity: 'extension',
+ href: '/motion/tokens',
+ },
+ {
+ id: 'trigger-anchored',
+ section: 'Movement Principles',
+ published:
+ 'Contextual UI should feel connected to its trigger. A dropdown should expand from the button that opened it. A popover should appear near the element it describes. This doesn\u2019t apply to global UI like command palettes or toasts, which have their own fixed positions.',
+ proposed:
+ 'Trigger-anchored surfaces scale from their trigger, not their centre. Modals are exempt. (Rubric criterion 8.)',
+ reading:
+ 'The same rule, and the page already carries the exemption the rubric needs. Criterion 8 can cite this paragraph instead of re-arguing it.',
+ resolution: 'No change needed. Cite the published text in the rubric.',
+ severity: 'aligned',
+ href: '/motion/rubric',
+ },
+ {
+ id: 'frequency',
+ section: 'Where Motion Hurts',
+ published:
+ 'Table row hovers. List item highlights. Anything the user does dozens of times per minute. Adding perceptible duration to these interactions makes the interface feel like it\u2019s catching up to the cursor.',
+ proposed:
+ 'Motion is scaled to how often it is seen. Keyboard-initiated and 100+/day actions get none. (Rubric criterion 2, Blocker.)',
+ reading:
+ 'Aligned, and the page is the stronger statement of the two because it names the surfaces. Worth noting against the nine hardcoded 150ms values in Table: those are on exactly the interaction this paragraph is about, so the sweep should ask whether they want a token or want deleting.',
+ resolution:
+ 'No change needed. The rubric formalises what the page already says.',
+ severity: 'aligned',
+ href: '/motion/violations',
+ },
+ {
+ id: 'direction',
+ section: 'Movement Principles',
+ published:
+ 'Direction should match the action. Navigating deeper into content should feel like moving forward. Going back should feel like returning. This keeps the user oriented in the structure of the application.',
+ proposed: 'Nothing in the twelve criteria covers directionality.',
+ reading:
+ 'A published principle the rubric drops on the floor. It is the rule Pagination and Calendar month-change would be measured against, and both are listed as gaps in the audit with no criterion to fail.',
+ resolution:
+ 'Add a directionality criterion, or fold it into criterion 4 (semantic correctness) so the rubric is a superset of the published guidance rather than a divergent list.',
+ severity: 'extension',
+ href: '/motion/rubric',
+ },
+ {
+ id: 'blocking',
+ section: 'Where Motion Hurts',
+ published:
+ 'Animations that block interaction are worse. If a user has to wait for a panel to finish sliding before they can click something inside it, the animation has become an obstacle.',
+ proposed:
+ 'Stagger must never block interaction; and useLayer awaits its exit transition rather than hiding synchronously.',
+ reading:
+ 'This is the paragraph the exit work has to be careful about. Keeping an element alive through its exit is exactly the shape of thing this warns against, and the answer has to be that the surface stops accepting input the moment dismissal starts, not when the animation ends.',
+ resolution:
+ 'Write the input-during-exit rule into the presence primitive\u2019s contract, and cite this paragraph when doing it.',
+ severity: 'extension',
+ href: '/motion/exit-gap',
+ },
+];
+
+/** Everything the published page says today, as the lab\u2019s "before" for docs. */
+export const PUBLISHED_SECTIONS: ReadonlyArray<{
+ readonly title: string;
+ readonly summary: string;
+ readonly stale: string | null;
+}> = [
+ {
+ title: 'Overview',
+ summary: 'Why motion, in two sentences: comprehension and craft.',
+ stale: null,
+ },
+ {
+ title: 'Duration',
+ summary:
+ 'The nine primitives, as a table of token and value. Three bands, min/max derived from base x ratio.',
+ stale:
+ 'Accurate, and it is the whole of what the page says about choosing one. No job is named against any token, which is the gap the semantic layer fills.',
+ },
+ {
+ title: 'Easing',
+ summary: 'One row: --ease-standard, cubic-bezier(0.24, 1, 0.4, 1).',
+ stale:
+ 'Accurate. The page cannot say what the curve is for, because it is for everything.',
+ },
+ {
+ title: 'Where Motion Helps / Hurts',
+ summary:
+ 'Prose guidance on which surfaces earn motion and which are hurt by it.',
+ stale: null,
+ },
+ {
+ title: 'Movement Principles',
+ summary:
+ 'Four bullets: exits are optional, match the entrance, direction matches the action, contextual UI connects to its trigger.',
+ stale:
+ 'Bullet one is the reason for eleven of the audit\u2019s findings. Rewriting it is the load-bearing doc change in this project.',
+ },
+ {
+ title: 'Respecting User Preferences',
+ summary: 'Honour the OS setting; replace animations with instant changes.',
+ stale:
+ 'Says delete. The proposal says degrade. One of the two has to move.',
+ },
+ {
+ title: 'Usage',
+ summary: 'A StyleX snippet applying durationVars and easeVars.',
+ stale:
+ 'Still correct, and worth keeping verbatim: it is the shape the lint rule will enforce.',
+ },
+ {
+ title: 'Best Practices',
+ summary: 'Three dos and three donts.',
+ stale:
+ 'No mention of the transform-only rule, the compositor cost, or interruptibility — all of which live only on the wiki today.',
+ },
+];
diff --git a/apps/sandbox/src/motion/rubric.ts b/apps/sandbox/src/motion/rubric.ts
new file mode 100644
index 0000000000..f9b922f7d1
--- /dev/null
+++ b/apps/sandbox/src/motion/rubric.ts
@@ -0,0 +1,321 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rubric.ts
+ * @input The project brief's rubric table, the published Motion page, the audit
+ * @output The twelve criteria as data, plus how they are graded and enforced
+ * @position Motion Lab data module; no React, no side effects
+ *
+ * The brief's Deliverables section promises "ten graded criteria" and its own
+ * table lists twelve. Twelve is what is written here, because twelve is what
+ * the table describes; the count in Deliverables is the thing to fix, and it
+ * matters because a number in a deliverable gets quoted in a review.
+ *
+ * Two criteria contradict guidance Astryx publishes today rather than
+ * extending it, so they carry a `guidance` marker: a rubric cannot fail a
+ * component for following the docs. See publishedGuidance.ts.
+ *
+ * Evidence strings are built from the generated audit rather than typed, so a
+ * regenerated audit moves the rubric's citations with it.
+ */
+
+import {
+ AUDIT_COUNTS,
+ HARDCODED_SITES,
+ TRANSFORM_TRANSITIONS,
+} from './__generated__/motionAudit';
+
+const TINT_150 = HARDCODED_SITES.filter(
+ site => site.value === '150ms' && site.component === 'Table',
+).length;
+
+const INSTANT_ESCAPES = HARDCODED_SITES.filter(
+ site => site.value === '0.01s',
+).length;
+
+const MULTI_PROPERTY_TRANSFORMS = TRANSFORM_TRANSITIONS.filter(
+ site => site.decl?.includes(',') === true,
+).length;
+
+export type Severity = 'blocker' | 'should-fix' | 'polish';
+
+/** Whether a checker can decide this today, from source, with no human. */
+export type Automatable = 'yes' | 'partly' | 'no';
+
+export type Criterion = {
+ readonly n: number;
+ readonly id: string;
+ readonly title: string;
+ readonly severity: Severity;
+ /** Set where the severity depends on the surface rather than the finding. */
+ readonly severityNote?: string;
+ readonly automatable: Automatable;
+ /** What a checker reads, or who decides when nothing can. */
+ readonly check: string;
+ readonly rule: string;
+ readonly pass: string;
+ readonly fail: string;
+ /** Measured, from __generated__/motionAudit.ts. */
+ readonly evidence?: string;
+ /** How the criterion sits against the published Motion page. */
+ readonly guidance?: 'reversal' | 'aligned';
+ readonly guidanceNote?: string;
+};
+
+export const SEVERITY_LABEL: Readonly<Record<Severity, string>> = {
+ blocker: 'Blocker',
+ 'should-fix': 'Should fix',
+ polish: 'Polish',
+};
+
+export const SEVERITY_RULES: ReadonlyArray<{
+ readonly severity: Severity;
+ readonly meaning: string;
+ readonly gate: string;
+}> = [
+ {
+ severity: 'blocker',
+ meaning:
+ 'The motion is wrong in a way that costs comprehension, accessibility or frame rate.',
+ gate: 'Open blockers fail the review. No exceptions, no "fix it in the follow-up".',
+ },
+ {
+ severity: 'should-fix',
+ meaning: 'The motion works but is not what the system would do.',
+ gate: 'Two open items are tolerated. A third fails, so the debt cannot accumulate quietly.',
+ },
+ {
+ severity: 'polish',
+ meaning: 'A judgement call about feel, where reasonable people differ.',
+ gate: 'Recorded, never blocking. Argue it in the review, not in the gate.',
+ },
+];
+
+export const PASS_BAR =
+ 'No open blockers, and at most two open "should fix" items. Polish items are recorded and never block.';
+
+export const RUBRIC_CRITERIA: ReadonlyArray<Criterion> = [
+ {
+ n: 1,
+ id: 'justified',
+ title: 'Justified motion',
+ severity: 'blocker',
+ automatable: 'no',
+ check:
+ 'Reviewer. The justification is written in the diff, not inferred from it.',
+ rule: 'Every animation names its purpose: orientation, continuity, feedback or attention.',
+ pass: 'The reason survives the question "what breaks if we delete it?".',
+ fail: '"It looks good" on an element the user sees dozens of times a day.',
+ evidence:
+ 'Deleting the animation is a valid outcome of this criterion, and on a high-frequency surface it is usually the strongest fix available.',
+ },
+ {
+ n: 2,
+ id: 'frequency',
+ title: 'Frequency-appropriate',
+ severity: 'blocker',
+ automatable: 'no',
+ check:
+ 'Reviewer, against how often the surface is actually seen. No tool knows that.',
+ rule: 'Motion is scaled to frequency. Keyboard-initiated actions and anything seen 100+ times a day get none.',
+ pass: 'A checkbox tick, a table row hover and a menu keyboard traversal are instant.',
+ fail: 'A 200ms draw-on tick, on a control used forty times in a form.',
+ guidance: 'aligned',
+ guidanceNote:
+ 'The published page already names table row hovers and list item highlights under "Where Motion Hurts". The rubric formalises it; it does not invent it.',
+ evidence: `${TINT_150} of the measured hardcoded values are 150ms tints in Table, on exactly the interaction that paragraph warns about.`,
+ },
+ {
+ n: 3,
+ id: 'tokens',
+ title: 'Token fidelity',
+ severity: 'blocker',
+ automatable: 'yes',
+ check: 'Lint. Reads the StyleX rule object; no runtime, no reviewer.',
+ rule: 'No hardcoded durations, delays or curves. No transitionProperty without a duration. No duration without a declared curve.',
+ pass: 'Every value is a token, and the pair is complete.',
+ fail: "transitionDuration: '150ms', or a duration with the curve left to the CSS default.",
+ evidence: `Every hardcoded duration and curve, every duration with no declared curve, and every transitionProperty with no duration. ${INSTANT_ESCAPES} of the hardcoded values are the 0.01s reduced-motion escape, which needs an allowlist rather than a fix. See /motion/violations for the live counts.`,
+ },
+ {
+ n: 4,
+ id: 'semantic',
+ title: 'Semantic correctness',
+ severity: 'should-fix',
+ automatable: 'partly',
+ check:
+ 'Lint can check the pairing once semantic tokens exist. Whether a surface is entering or leaving is a reviewer call.',
+ rule: 'Entry decelerates. Exit accelerates. Movement uses the move curve. Continuous motion is linear.',
+ pass: '--duration-exit with --ease-exit: the surface leaves and gets out of the way.',
+ fail: '--duration-exit with --ease-entry: an exit that spends its travel in the first frames and then hangs.',
+ },
+ {
+ n: 5,
+ id: 'budget',
+ title: 'Duration budget',
+ severity: 'should-fix',
+ automatable: 'yes',
+ check: 'Lint, against the token values. Arithmetic, not taste.',
+ rule: 'Interface motion stays under 300ms. Overlays may reach 500ms.',
+ pass: 'Enter at 230ms, overlay at 410ms.',
+ fail: 'A 600ms hover, or an 800ms dialog that has to be sat through before the first click.',
+ },
+ {
+ n: 6,
+ id: 'compositor',
+ title: 'Compositor-only',
+ severity: 'blocker',
+ severityNote:
+ 'Blocker on large surfaces — lists, tables, sheets. Should fix on a single small element.',
+ automatable: 'partly',
+ check:
+ 'Lint reads the animated property list. Whether the surface is large enough for it to matter is a reviewer call.',
+ rule: 'Animate transform and opacity. clip-path is sanctioned; height is tolerated for disclosure only; transition: all is never acceptable.',
+ pass: 'A marker that moves with translateY and scaleY, so the list never re-lays-out.',
+ fail: 'Animating top and height on a list marker, which runs layout for the whole list every frame.',
+ evidence: `transition: all is measured at ${AUDIT_COUNTS.transitionAll} sites today. The rule is a guard against regression, not a cleanup.`,
+ },
+ {
+ n: 7,
+ id: 'presence',
+ title: 'Enter and exit',
+ severity: 'blocker',
+ severityNote: 'Blocker for overlays and presence surfaces.',
+ automatable: 'partly',
+ check:
+ 'Lint can see whether a component only ever transitions on mount. Whether the exit retraces the entry needs eyes.',
+ rule: 'Presence surfaces animate both directions. The exit retraces the entry path and is no slower than it.',
+ pass: 'A panel that slides in from the right slides back out to the right, faster, on the exit curve.',
+ fail: 'A surface that animates in and is removed on the next frame.',
+ guidance: 'reversal',
+ guidanceNote:
+ 'This criterion contradicts the published page, which tells authors that tooltips, hover cards and dropdown menus can disappear instantly. Eleven components followed that instruction. The rubric cannot gate on this until the paragraph is rewritten.',
+ },
+ {
+ n: 8,
+ id: 'origin',
+ title: 'Origin and physicality',
+ severity: 'should-fix',
+ automatable: 'partly',
+ check:
+ 'Lint catches scale(0) and a missing transform-origin. Whether the origin matches the trigger needs eyes.',
+ rule: 'Trigger-anchored surfaces scale from their trigger, not their centre. Modals are exempt. Never scale(0): start between 0.9 and 0.97 with opacity.',
+ pass: 'A menu growing out of the corner of the button that opened it.',
+ fail: 'scale(0) — nothing in the physical world appears from nothing.',
+ guidance: 'aligned',
+ guidanceNote:
+ 'The published page already says contextual UI should feel connected to its trigger, and already carries the exemption for global UI. This criterion can cite it rather than re-argue it.',
+ },
+ {
+ n: 9,
+ id: 'interruptible',
+ title: 'Interruptibility',
+ severity: 'should-fix',
+ automatable: 'partly',
+ check:
+ 'Lint can flag a keyframe driving a state change. Judging the interrupted feel needs the demo.',
+ rule: 'Transitions and springs retarget from the current value. Keyframes restart from zero and fail this.',
+ pass: 'Interrupt the travel and the element continues from where it is.',
+ fail: 'Interrupt it and the element teleports back to the start before running again.',
+ },
+ {
+ n: 10,
+ id: 'reduced-motion',
+ title: 'Reduced motion',
+ severity: 'blocker',
+ automatable: 'yes',
+ check:
+ 'Lint. An animating file with no prefers-reduced-motion branch is mechanically detectable.',
+ rule: 'Honoured, and degraded rather than deleted: movement and position change go, opacity and colour stay. Hover motion is gated behind a fine pointer, since touch fires a hover on tap. Continuous loops stop rather than slow down.',
+ pass: 'The loop stops and is replaced by a determinate state; the tint still tells you the row is hovered.',
+ fail: 'A spinner slowed to 3s, which is still vestibular motion and now also reads as a hang.',
+ guidance: 'reversal',
+ guidanceNote:
+ 'The published page says to replace animation with instant state changes — delete, not degrade. Choosing degrade is a change of published policy, and the 36-file sweep writes whichever answer wins 36 times.',
+ evidence: `${AUDIT_COUNTS.filesWithoutReducedMotion} of ${AUDIT_COUNTS.animatedFiles} animated files have no reduced-motion branch at all.`,
+ },
+ {
+ n: 11,
+ id: 'cohesion',
+ title: 'Cohesion',
+ severity: 'polish',
+ automatable: 'no',
+ check:
+ 'Reviewer, against the rest of the library rather than against a number.',
+ rule: 'Motion matches the component\u2019s personality and the library it lives in. Group entrances stagger between 30ms and 80ms.',
+ pass: 'A crisp component in a crisp library; a list that enters at 50ms intervals.',
+ fail: 'One bouncy component in a library that is otherwise crisp. That is a finding, not a flourish.',
+ },
+ {
+ n: 12,
+ id: 'library',
+ title: 'Library compatibility',
+ severity: 'should-fix',
+ automatable: 'yes',
+ check:
+ 'Lint plus a render test: forwarded ref, merged className and style, no CSS transition on transform.',
+ rule: 'The root forwards a ref to a real DOM node, merges className and style with the consumer last, and puts no CSS transition on transform.',
+ pass: 'Press feedback on the independent scale property, so a motion library can own transform.',
+ fail: 'transition: transform on the root — every transform a library writes gets re-eased, so drags lag and springs never settle.',
+ evidence: `Transform transitions across the package, including Button. ${MULTI_PROPERTY_TRANSFORMS} of them declare transform inside a longer property list, where a grep for it never looks. The generated audit undercounted this twice before the scanner learned to read wrapped values and nested StyleX rules; the brief\u2019s "20+ components" was right all along.`,
+ },
+];
+
+export const AUTOMATABLE_LABEL: Readonly<Record<Automatable, string>> = {
+ yes: 'Mechanical today',
+ partly: 'Partly — lint narrows it, a human decides',
+ no: 'Human judgement',
+};
+
+/**
+ * Astryx already gates lab-to-core promotion on an accessibility checklist.
+ * Motion works the same way or it does not work at all: published, graded per
+ * component, tracked. The only real question is what happens to the components
+ * that already exist, which is what this table answers.
+ */
+export const GRANDFATHERING: ReadonlyArray<{
+ readonly situation: string;
+ readonly rule: string;
+ readonly why: string;
+}> = [
+ {
+ situation: 'Lab to core promotion',
+ rule: 'The full rubric applies from day one. No baseline, no allowlist.',
+ why: 'Promotion is the one moment where the cost of the rubric is already budgeted, and the same gate already exists for accessibility.',
+ },
+ {
+ situation: 'A new core component',
+ rule: 'Full rubric, no baseline.',
+ why: 'Nothing to grandfather.',
+ },
+ {
+ situation: 'Existing core components',
+ rule: 'Scored once, baselined, and allowlisted with a dated remediation task per blocker. The allowlist can only shrink.',
+ why: 'A gate that fails 48 animating components on the day it lands gets turned off in a week. A baseline that can only shrink is the same rule with a schedule.',
+ },
+ {
+ situation: 'An unrelated change to a failing component',
+ rule: 'Not blocked. The rule is no new violations against the baseline.',
+ why: 'Blocking a copy fix on a motion debt nobody in the diff created is how a gate loses its constituency.',
+ },
+ {
+ situation: 'A motion change to a failing component',
+ rule: 'Must clear that component\u2019s blockers before it lands.',
+ why: 'If you are already in the motion code, this is the cheapest this fix will ever be — and it is the only way the allowlist actually shrinks.',
+ },
+];
+
+/**
+ * A principle the published page carries and the rubric does not. Left as data
+ * so the rubric page can show the gap rather than describe it.
+ */
+export const MISSING_PRINCIPLE = {
+ title: 'Direction should match the action',
+ published:
+ 'Navigating deeper into content should feel like moving forward. Going back should feel like returning.',
+ gap: 'Nothing in the twelve criteria covers directionality.',
+ measuredAgainst:
+ 'Pagination and Calendar month-change are the surfaces this would be measured against. Both are audit gaps today with no criterion to fail.',
+ recommendation:
+ 'Fold it into criterion 4 as a fourth pairing rule, or add it as a thirteenth criterion. Either way the rubric should be a superset of the published guidance, not a divergent list.',
+} as const;
diff --git a/apps/sandbox/src/motion/sections.ts b/apps/sandbox/src/motion/sections.ts
new file mode 100644
index 0000000000..fe82f32576
--- /dev/null
+++ b/apps/sandbox/src/motion/sections.ts
@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file sections.ts
+ * @input none
+ * @output The lab's section registry, used by the rail and the overview
+ * @position Motion Lab data module
+ *
+ * One list, so adding a page means adding a row here rather than editing a
+ * rail, an overview grid and a set of prev/next links separately.
+ */
+
+export type MotionSection = {
+ readonly href: string;
+ readonly title: string;
+ readonly group: string;
+ /** What a reader can decide after spending time on this page. */
+ readonly decides: string;
+};
+
+export const MOTION_SECTIONS: ReadonlyArray<MotionSection> = [
+ {
+ href: '/motion',
+ title: 'Overview',
+ group: 'Start',
+ decides:
+ 'Whether the audit in the brief matches the code, and which decisions are actually blocking.',
+ },
+ {
+ href: '/motion/published',
+ title: 'Against the published page',
+ group: 'Start',
+ decides:
+ 'Which proposals are bug fixes and which are reversals of guidance Astryx publishes today.',
+ },
+ {
+ href: '/motion/tokens',
+ title: 'Semantic tokens',
+ group: 'Foundation',
+ decides:
+ 'Whether six easings and eight durations are the right vocabulary, and what each value should be.',
+ },
+ {
+ href: '/motion/springs',
+ title: 'Springs',
+ group: 'Foundation',
+ decides:
+ 'Whether the four named springs feel right, and whether they belong in the theme contract.',
+ },
+ {
+ href: '/motion/js-mirror',
+ title: 'JS token mirror',
+ group: 'Foundation',
+ decides:
+ 'What the mirror has to expose for charts, canvas and motion libraries.',
+ },
+ {
+ href: '/motion/export',
+ title: 'Export tuning',
+ group: 'Foundation',
+ decides:
+ 'Nothing — it emits whatever the rest of the lab has been tuned to.',
+ },
+ {
+ href: '/motion/exit-gap',
+ title: 'The exit gap',
+ group: 'Presence',
+ decides:
+ 'Whether presence surfaces should animate out at all, and what enter and exit cost.',
+ },
+ {
+ href: '/motion/bugs',
+ title: 'Small bugs',
+ group: 'Presence',
+ decides:
+ 'Which of the structural findings are real once you look at the code.',
+ },
+ {
+ href: '/motion/violations',
+ title: 'Hardcoded values',
+ group: 'Enforcement',
+ decides:
+ 'What each hardcoded site becomes, and whether the swap is visible at all.',
+ },
+ {
+ href: '/motion/rubric',
+ title: 'Rubric bench',
+ group: 'Enforcement',
+ decides:
+ 'Whether each criterion is checkable, and what a pass and a fail look like.',
+ },
+ {
+ href: '/motion/reduced-motion',
+ title: 'Reduced motion',
+ group: 'Enforcement',
+ decides: 'Degrade or delete. The decision the 36-file sweep is waiting on.',
+ },
+ {
+ href: '/motion/previews',
+ title: 'Live previews',
+ group: 'Coverage',
+ decides:
+ 'The coverage work: indicators, disclosure, chips, skeletons, lists.',
+ },
+ {
+ href: '/motion/preview-plan',
+ title: 'Preview plan',
+ group: 'Coverage',
+ decides:
+ 'What every remaining preview has to show before it is worth building.',
+ },
+ {
+ href: '/motion/library',
+ title: 'Motion library',
+ group: 'Compatibility',
+ decides:
+ 'The three blockers, and whether Button keeps its press transition.',
+ },
+ {
+ href: '/motion/plan',
+ title: 'Plan & open questions',
+ group: 'Plan',
+ decides: 'Sequence, gates, and who has to answer what.',
+ },
+];
diff --git a/apps/sandbox/src/motion/spring.ts b/apps/sandbox/src/motion/spring.ts
new file mode 100644
index 0000000000..29329a05d5
--- /dev/null
+++ b/apps/sandbox/src/motion/spring.ts
@@ -0,0 +1,176 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file spring.ts
+ * @input A duration/bounce pair, the way Motion describes a spring
+ * @output A sampler, a CSS linear() easing, and the equivalent physics numbers
+ * @position Motion Lab utility; no React, no DOM
+ *
+ * Springs have no CSS representation, which is the reason the proposal keeps
+ * them in the JS mirror rather than the token file. The lab still has to show
+ * one moving, so this approximates Motion's duration/bounce model as a damped
+ * harmonic oscillator: bounce maps to the damping ratio, duration to the
+ * settle time. Close enough to judge feel and to argue about whether 0.2
+ * belongs in a crisp library, which is all the lab needs it for.
+ *
+ * `linear()` is what makes it usable: sampling the curve into a CSS easing
+ * lets a plain transition play a spring, which is also the escape hatch for a
+ * component that cannot take a JS dependency.
+ */
+
+export type Spring = {
+ readonly duration: number;
+ readonly bounce: number;
+ /** Position at time t in seconds; 1 is the target. */
+ sample: (t: number) => number;
+ /** A CSS `linear()` easing that replays this spring over its duration. */
+ linear: (steps?: number) => string;
+ /** Peak position, so overshoot can be reported as a percentage. */
+ overshoot: () => number;
+ /** Where it has got to when the nominal duration is up. */
+ settle: () => number;
+ /** Roughly equivalent stiffness/damping, for anyone thinking in those. */
+ readonly stiffness: number;
+ readonly damping: number;
+};
+
+export function createSpring(duration: number, bounce: number): Spring {
+ const d = Math.max(0.05, duration);
+ const b = Math.min(0.95, Math.max(-0.5, bounce));
+ // bounce 0 is critically damped; positive bounce is underdamped.
+ const zeta = Math.max(0.05, 1 - b);
+ // Envelope decays to ~1% of the travel by t = d, which is what makes the
+ // number the caller passes behave like a duration rather than a frequency.
+ const omega = 4.6 / (zeta * d);
+ const damped = zeta < 1 ? omega * Math.sqrt(1 - zeta * zeta) : 0;
+
+ const sample = (t: number): number => {
+ if (t <= 0) {
+ return 0;
+ }
+ if (zeta < 1) {
+ const envelope = Math.exp(-zeta * omega * t);
+ return (
+ 1 -
+ envelope *
+ (Math.cos(damped * t) +
+ ((zeta * omega) / damped) * Math.sin(damped * t))
+ );
+ }
+ const envelope = Math.exp(-omega * t);
+ return 1 - envelope * (1 + omega * t);
+ };
+
+ return {
+ duration: d,
+ bounce: b,
+ sample,
+ stiffness: Math.round(omega * omega),
+ damping: Math.round(2 * zeta * omega * 10) / 10,
+ linear(steps = 64) {
+ const points: string[] = [];
+ for (let i = 0; i <= steps; i++) {
+ points.push(sample((i / steps) * d).toFixed(4));
+ }
+ return `linear(${points.join(',')})`;
+ },
+ overshoot() {
+ // The peak of a light spring lands after the nominal duration, so look
+ // past it or the number reads as zero overshoot on every preset.
+ let peak = 0;
+ for (let i = 0; i <= 400; i++) {
+ peak = Math.max(peak, sample((i / 400) * d * 3));
+ }
+ return peak;
+ },
+ settle: () => sample(d),
+ };
+}
+
+// --- cubic-bezier ----------------------------------------------------------
+
+export type BezierPoints = readonly [number, number, number, number];
+
+const NAMED_CURVES: Readonly<Record<string, BezierPoints>> = {
+ linear: [0, 0, 1, 1],
+ ease: [0.25, 0.1, 0.25, 1],
+ 'ease-in': [0.42, 0, 1, 1],
+ 'ease-out': [0, 0, 0.58, 1],
+ 'ease-in-out': [0.42, 0, 0.58, 1],
+};
+
+export function parseBezier(value: string): BezierPoints {
+ const trimmed = value.trim();
+ const named = NAMED_CURVES[trimmed];
+ if (named != null) {
+ return named;
+ }
+ const match = /cubic-bezier\(([^)]+)\)/.exec(trimmed);
+ if (match != null) {
+ const parts = match[1].split(',').map(Number);
+ if (parts.length === 4 && parts.every(Number.isFinite)) {
+ return [parts[0], parts[1], parts[2], parts[3]];
+ }
+ }
+ return NAMED_CURVES.ease;
+}
+
+export function formatBezier(points: BezierPoints): string {
+ return `cubic-bezier(${points.map(n => Number(n.toFixed(3))).join(', ')})`;
+}
+
+export function isNamedCurve(value: string): boolean {
+ return Object.hasOwn(NAMED_CURVES, value.trim());
+}
+
+const bezierAxis = (a: number, b: number, t: number): number => {
+ const u = 1 - t;
+ return 3 * u * u * t * a + 3 * u * t * t * b + t * t * t;
+};
+
+/** Progress along the curve's y axis at x, which is what "eased" means. */
+export function bezierAt(points: BezierPoints, x: number): number {
+ if (x <= 0) {
+ return 0;
+ }
+ if (x >= 1) {
+ return 1;
+ }
+ let low = 0;
+ let high = 1;
+ let t = x;
+ for (let i = 0; i < 32; i++) {
+ const guess = bezierAxis(points[0], points[2], t);
+ if (Math.abs(guess - x) < 1e-5) {
+ break;
+ }
+ if (guess < x) {
+ low = t;
+ } else {
+ high = t;
+ }
+ t = (low + high) / 2;
+ }
+ return bezierAxis(points[1], points[3], t);
+}
+
+/** An SVG path for a curve plotted into a box, used by both editors. */
+export function plotPath(
+ fn: (x: number) => number,
+ width: number,
+ height: number,
+ pad: number,
+ yMin: number,
+ yMax: number,
+ samples = 120,
+): string {
+ const points: string[] = [];
+ for (let i = 0; i <= samples; i++) {
+ const x = i / samples;
+ const px = pad + x * (width - pad * 2);
+ const py =
+ height - pad - ((fn(x) - yMin) / (yMax - yMin)) * (height - pad * 2);
+ points.push(`${px.toFixed(2)},${py.toFixed(2)}`);
+ }
+ return `M${points.join('L')}`;
+}