Skip to content

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

TypeScript

Motion Lab: narrow the exit rule, mount real components, add an idle-cost criterion (#5613)

Ernest7cb5bac59e62
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/LabDemos.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/LabDemos.tsx
index ce53c5d38c..b678800252 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/LabDemos.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/LabDemos.tsx
@@ -31,6 +31,13 @@ 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 {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {Tab, TabList} from '@astryxdesign/core/TabList';
+// A swizzled copy of core's TabList carrying the proposed travelling indicator.
+import {
+ Tab as ProposedTab,
+ TabList as ProposedTabList,
+} from './proposed/TabList';
import {Skeleton} from '@astryxdesign/core/Skeleton';
import {Token} from '@astryxdesign/core/Token';
import {HStack, VStack} from '@astryxdesign/core/Layout';
@@ -432,60 +439,34 @@ export function DialogRig({mode}: {mode: Mode}) {
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]);
+ const [value, setValue] = useState(TAB_NAMES[0]);
+ useLoop(
+ () =>
+ setValue(v => TAB_NAMES[(TAB_NAMES.indexOf(v) + 1) % TAB_NAMES.length]),
+ 2000,
+ );
- useLoop(() => setIndex(i => (i + 1) % TAB_NAMES.length), 2000);
+ // Both panes are TabList. `before` is core's, where every tab owns an
+ // indicator and they cross-fade on opacity; `after` is a swizzled copy of
+ // that source with one indicator that travels on transform. Same component,
+ // and the difference is the diff — see proposed/TabList/.
+ const List = mode === 'after' ? ProposedTabList : TabList;
+ const Item = mode === 'after' ? ProposedTab : Tab;
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>
+ <List
+ value={value}
+ onChange={setValue}
+ {...(mode === 'after' ? {hasTravellingIndicator: true} : null)}>
+ {TAB_NAMES.map(name => (
+ <Item key={name} value={name} label={name} />
))}
- {mode === 'after' && (
- <span ref={indicatorRef} className={styles.indicator} />
- )}
- </div>
+ </List>
<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.'}
+ ? 'Core\u2019s TabList. Each tab draws its own indicator and they cross-fade on opacity, so nothing travels and the eye has to re-find the selection after every change.'
+ : 'One indicator for the strip, moved with transform on --ease-move. Compositor-only, and the eye can follow it. Jump between distant tabs to judge the duration — a bar crossing five tabs feels different from one crossing two.'}
</Hint>
</VStack>
);
@@ -583,6 +564,22 @@ export function RailRig({mode}: {mode: Mode}) {
const [collapsed, setCollapsed] = useState(false);
useLoop(() => setCollapsed(v => !v), 2800);
+ // Hand-built, unlike the TabList and CheckboxInput demos on this page.
+ //
+ // A real fork of core's SideNav needs `SideNavCollapseContext` on the public
+ // surface — SideNav is a provider, and core exports only the reader hook
+ // `useSideNavCollapse`. Importing the context by relative path compiles and
+ // is silently wrong: the app resolves `@astryxdesign/core/*` to dist, so a
+ // relative import of src yields a SECOND React context object, and core's
+ // SideNavItem/Heading/Section read the other one, see the default
+ // `{isCollapsed: false}`, and render labels inside a narrow rail with no
+ // error anywhere.
+ //
+ // So this pane approximates the rail rather than being it, and the demo is
+ // weaker for it. The one-line fix is `export {SideNavCollapseContext}` from
+ // packages/core/src/SideNav/index.ts, beside the hook — exactly how
+ // SideNavRenderContext is already exported three lines below. Deferred: it is
+ // a public API surface change and wants its own review.
return (
<VStack gap={2} {...stylex.props(sx.full)}>
<div {...stylex.props(sx.frame)}>
@@ -608,8 +605,8 @@ export function RailRig({mode}: {mode: Mode}) {
</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.'}
+ ? 'Only the chevron rotates. The rail snaps between widths, so the content beside it jumps. Approximated \u2014 see the note in LabDemos.tsx for why this one is not the real SideNav.'
+ : 'The rail\u2019s own width animates on --ease-move. width is a layout property, so this is a deliberate criterion-6 exception \u2014 the transform alternative leaves neighbouring content un-reflowed until the animation ends, which reads worse on a rail this narrow.'}
</Hint>
</VStack>
);
@@ -1059,12 +1056,29 @@ export function CheckTickRig({
}) {
const [checked, setChecked] = useState(false);
useLoop(() => setChecked(v => !v), 2000);
- const cls =
- technique === 'draw'
- ? styles.checkDraw
- : technique === 'scale'
- ? styles.checkScale
- : styles.checkHard;
+
+ // The "today" pane is the real component. Core's CheckboxInput tints its box
+ // and border on change and the tick simply appears; drawing that by hand
+ // would be asserting the finding rather than showing it. The other two are
+ // hand-built because they are the proposals — core has no drawn or scaled
+ // tick to demonstrate.
+ if (technique === 'hard') {
+ return (
+ <HStack gap={2} vAlign="center">
+ <CheckboxInput
+ label="Real CheckboxInput"
+ isLabelHidden
+ value={checked}
+ onChange={setChecked}
+ />
+ <Text type="supporting" color="secondary">
+ Real CheckboxInput — the tick appears instantly
+ </Text>
+ </HStack>
+ );
+ }
+
+ const cls = technique === 'draw' ? styles.checkDraw : styles.checkScale;
return (
<HStack gap={2} vAlign="center">
@@ -1080,11 +1094,7 @@ export function CheckTickRig({
</svg>
</button>
<Text type="supporting" color="secondary">
- {technique === 'hard'
- ? 'Appears instantly'
- : technique === 'draw'
- ? 'Draws along its path'
- : 'Scales in'}
+ {technique === 'draw' ? 'Draws along its path' : 'Scales in'}
</Text>
</HStack>
);
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLab.module.css b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLab.module.css
index e84bf423b2..382edee8ac 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLab.module.css
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLab.module.css
@@ -51,13 +51,20 @@
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;
-}
+/* NOTE: there is no `.loop` rule here on purpose. One used to stop continuous
+ loops under the reduced-motion policies and it never fired — nothing applies
+ the class, and LoopRig sets `animation: none` inline, which would outrank it
+ anyway. That is the same trap as the duration aliases above. The policy lives
+ in the rig; do not add a stylesheet rule back and assume it works.
+
+ Containment lives on each loop's own class below (`contain: paint`), because
+ the classes are what the demos actually apply. Three of those loops animate a
+ paint-only or layout property deliberately — they are the demonstration of
+ what criterion 13 forbids — and without containment the demonstration would
+ repaint the whole lab around itself at 60fps, which is the kt-fr88 bug being
+ committed by the page that documents it. The layer, where one is warranted,
+ is gated on no-preference so a reduced-motion reader is not charged layer
+ memory for a mark that has been stilled. */
/* ---------------------------------------------------------------- stage --- */
@@ -641,6 +648,7 @@
/* ---------------------------------------------------------------- loops --- */
.spinner {
+ contain: paint;
width: 20px;
height: 20px;
border-radius: 50%;
@@ -656,6 +664,7 @@
}
.pulseDot {
+ contain: paint;
width: 11px;
height: 11px;
border-radius: 50%;
@@ -674,6 +683,7 @@
}
.shimmer {
+ contain: paint;
height: 11px;
border-radius: 6px;
background: linear-gradient(
@@ -704,6 +714,7 @@
}
.progressFillWidth {
+ contain: paint;
position: absolute;
inset-block: 0;
inset-inline-start: 0;
@@ -714,6 +725,7 @@
}
.progressFillTransform {
+ contain: paint;
position: absolute;
inset-block: 0;
inset-inline-start: 0;
@@ -721,7 +733,6 @@
border-radius: 4px;
background: var(--color-brand);
animation: progressTransform var(--loop-duration, 1.4s) linear infinite;
- will-change: transform;
}
@keyframes progressWidth {
@@ -889,10 +900,6 @@
transition: transform var(--lab-duration-enter) var(--ease-entry);
}
-.checkHard .checkTick {
- stroke-dashoffset: 0;
-}
-
/* -------------------------------------------------------------- misc ------ */
.curveCanvas {
@@ -912,3 +919,15 @@
align-items: center;
flex-wrap: wrap;
}
+
+@media (prefers-reduced-motion: no-preference) {
+ .spinner {
+ will-change: transform;
+ }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+ .progressFillTransform {
+ will-change: transform;
+ }
+}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLabShell.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLabShell.tsx
index 73300575ab..26d8259408 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLabShell.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/MotionLabShell.tsx
@@ -55,6 +55,19 @@ const sx = stylex.create({
},
});
+/**
+ * Hrefs here are written WITHOUT the deployed basePath, and must stay that way.
+ *
+ * The sandbox deploys under a prefix (`/astryx/pr/<n>/sandbox` on a preview),
+ * and `next/link` prepends it exactly once. LinkProvider in layout.tsx routes
+ * every Astryx `Link` and `ListItem` in this section through `next/link`, so
+ * the prefix is already handled — applying it here as well produces a
+ * double-prefixed URL that 404s, which is how this was found.
+ *
+ * `usePathname()` also returns the path without the prefix, so the
+ * current-page comparison below matches these hrefs directly.
+ */
+
/** The export sets `trailingSlash: true`, so normalise before comparing. */
function isCurrent(pathname: string, href: string): boolean {
const a = pathname.endsWith('/') ? pathname : `${pathname}/`;
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/__generated__/motionAudit.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/__generated__/motionAudit.ts
index 1cd04703a5..afd0b970f5 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/__generated__/motionAudit.ts
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/__generated__/motionAudit.ts
@@ -34,7 +34,7 @@ export const AUDIT_COUNTS = {
coreComponentDirs: 104,
labComponentDirs: 17,
hardcodedInLab: 10,
- filesScanned: 698,
+ filesScanned: 701,
animatingComponents: 55,
staticComponents: 65,
animatedFiles: 88,
@@ -50,7 +50,7 @@ export const AUDIT_COUNTS = {
transitionAll: 0,
infiniteLoops: 9,
setTimeoutLiterals: 1,
- getComputedStyleReads: 33,
+ getComputedStyleReads: 34,
} as const;
export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
@@ -158,7 +158,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/Button/Button.tsx',
package: 'core',
component: 'Button',
- line: 407,
+ line: 380,
kind: 'duration',
prop: 'animationDuration',
value: '1ms',
@@ -298,7 +298,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 253,
+ line: 254,
kind: 'easing',
prop: 'transitionTimingFunction',
value: 'linear',
@@ -308,7 +308,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 255,
+ line: 256,
kind: 'duration',
prop: 'transitionDuration',
value: '0.01s',
@@ -318,7 +318,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 310,
+ line: 311,
kind: 'easing',
prop: 'transitionTimingFunction',
value: 'linear',
@@ -328,7 +328,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 312,
+ line: 313,
kind: 'duration',
prop: 'transitionDuration',
value: '0.01s',
@@ -338,7 +338,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 382,
+ line: 375,
kind: 'duration',
prop: 'transitionDuration',
value: '0.01s',
@@ -348,7 +348,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 397,
+ line: 390,
kind: 'easing',
prop: 'transitionTimingFunction',
value: 'linear',
@@ -358,7 +358,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 399,
+ line: 392,
kind: 'duration',
prop: 'transitionDuration',
value: '0.01s',
@@ -368,7 +368,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 449,
+ line: 442,
kind: 'duration',
prop: 'transitionDuration',
value: '0.01s',
@@ -378,7 +378,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 499,
+ line: 492,
kind: 'easing',
prop: 'transitionTimingFunction',
value: 'linear',
@@ -388,7 +388,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 501,
+ line: 494,
kind: 'duration',
prop: 'transitionDuration',
value: '0.01s',
@@ -418,7 +418,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'lab/Drawer/Drawer.tsx',
package: 'lab',
component: 'Drawer',
- line: 224,
+ line: 234,
kind: 'duration',
prop: 'transitionDuration',
value: '0.01s',
@@ -478,7 +478,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/Spinner/Spinner.tsx',
package: 'core',
component: 'Spinner',
- line: 138,
+ line: 265,
kind: 'easing',
prop: 'animationTimingFunction',
value: 'linear',
@@ -508,7 +508,7 @@ export const HARDCODED_SITES: ReadonlyArray<HardcodedSite> = [
file: 'core/Stepper/Step.tsx',
package: 'core',
component: 'Stepper',
- line: 387,
+ line: 388,
kind: 'easing',
prop: 'transitionTimingFunction',
value: 'linear',
@@ -672,7 +672,7 @@ export const DURATION_WITHOUT_CURVE: ReadonlyArray<SiteRef> = [
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 445,
+ line: 438,
decl: 'transitionDuration: SWAP_DURATION',
},
{
@@ -700,7 +700,7 @@ export const DURATION_WITHOUT_CURVE: ReadonlyArray<SiteRef> = [
file: 'core/Stepper/Step.tsx',
package: 'core',
component: 'Stepper',
- line: 404,
+ line: 405,
decl: 'transitionDuration:',
},
{
@@ -728,7 +728,7 @@ export const DURATION_WITHOUT_CURVE: ReadonlyArray<SiteRef> = [
file: 'lab/Drawer/Drawer.tsx',
package: 'lab',
component: 'Drawer',
- line: 222,
+ line: 232,
decl: "transitionDuration: '0.01s'",
},
];
@@ -738,7 +738,7 @@ export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
file: 'core/Banner/Banner.tsx',
package: 'core',
component: 'Banner',
- line: 331,
+ line: 340,
decl: "transitionProperty: 'transform'",
},
{
@@ -752,7 +752,7 @@ export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
file: 'core/Button/Button.tsx',
package: 'core',
component: 'Button',
- line: 90,
+ line: 91,
decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
},
{
@@ -787,21 +787,21 @@ export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
file: 'core/ComplexSelector/ComplexSelector.tsx',
package: 'core',
component: 'ComplexSelector',
- line: 134,
+ line: 128,
decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
},
{
file: 'core/ComplexSelector/ComplexSelector.tsx',
package: 'core',
component: 'ComplexSelector',
- line: 160,
+ line: 154,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/DateInput/TouchDateField.tsx',
package: 'core',
component: 'DateInput',
- line: 378,
+ line: 371,
decl: "transitionProperty: 'transform'",
},
{
@@ -822,14 +822,14 @@ export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
file: 'core/MultiSelector/MultiSelector.tsx',
package: 'core',
component: 'MultiSelector',
- line: 185,
+ line: 187,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/MultiSelector/MultiSelector.tsx',
package: 'core',
component: 'MultiSelector',
- line: 213,
+ line: 208,
decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
},
{
@@ -850,14 +850,14 @@ export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
file: 'core/Selector/Selector.tsx',
package: 'core',
component: 'Selector',
- line: 208,
+ line: 209,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/Selector/Selector.tsx',
package: 'core',
component: 'Selector',
- line: 236,
+ line: 230,
decl: "transitionProperty: 'background-image, background-color, color, opacity, transform'",
},
{
@@ -871,14 +871,14 @@ export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
file: 'core/SideNav/SideNavItem.tsx',
package: 'core',
component: 'SideNav',
- line: 126,
+ line: 140,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/Stepper/Step.tsx',
package: 'core',
component: 'Stepper',
- line: 366,
+ line: 367,
decl: "transitionProperty: 'transform'",
},
{
@@ -920,57 +920,57 @@ export const TRANSFORM_TRANSITIONS: ReadonlyArray<SiteRef> = [
file: 'core/Toast/Toast.tsx',
package: 'core',
component: 'Toast',
- line: 40,
+ line: 57,
decl: "transitionProperty: 'opacity, transform'",
},
{
file: 'core/TopNav/TopNavMegaMenu.tsx',
package: 'core',
component: 'TopNav',
- line: 113,
+ line: 114,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/TopNav/TopNavMegaMenu.tsx',
package: 'core',
component: 'TopNav',
- line: 130,
+ line: 131,
decl: "transitionProperty: 'opacity, transform, overlay, display'",
},
{
file: 'core/TopNav/TopNavMegaMenu.tsx',
package: 'core',
component: 'TopNav',
- line: 221,
+ line: 222,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/TopNav/TopNavMenu.tsx',
package: 'core',
component: 'TopNav',
- line: 100,
+ line: 101,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/TopNav/TopNavMenu.tsx',
package: 'core',
component: 'TopNav',
- line: 184,
+ line: 185,
decl: "transitionProperty: 'transform'",
},
{
file: 'core/TreeList/TreeListItem.tsx',
package: 'core',
component: 'TreeList',
- line: 225,
+ line: 219,
decl: "transitionProperty: 'transform'",
},
{
file: 'lab/Drawer/Drawer.tsx',
package: 'lab',
component: 'Drawer',
- line: 156,
- decl: "transitionProperty: 'transform, display'",
+ line: 157,
+ decl: "transitionProperty: 'transform'",
},
];
@@ -999,7 +999,7 @@ export const INFINITE_LOOPS: ReadonlyArray<SiteRef> = [
file: 'core/Spinner/Spinner.tsx',
package: 'core',
component: 'Spinner',
- line: 136,
+ line: 263,
},
{
file: 'core/StatusDot/StatusDot.tsx',
@@ -1044,7 +1044,7 @@ export const TIMEOUT_LITERALS: ReadonlyArray<{
file: 'core/MultiSelector/hooks.ts',
package: 'core',
component: 'MultiSelector',
- line: 233,
+ line: 240,
ms: 500,
},
];
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
index 6c6b5be1ef..5c808b3822 100644
--- 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
@@ -8,9 +8,17 @@
* @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.
+ * The brief calls this the single highest-leverage fix in the audit, on the
+ * strength of eleven components that animate in and vanish out. Checked
+ * against the sources the brief itself cites, most of those eleven are correct
+ * as they are: an exit earns its place when it aids orientation, and the
+ * surfaces the user has already looked away from do not qualify.
+ *
+ * So the page argues something narrower than the brief does, and has to,
+ * because three of the four surfaces it demos are named in the published docs
+ * as instant-dismissal cases. What survives is the infrastructure finding:
+ * useLayer cannot express an exit at all, which blocks the handful of surfaces
+ * that genuinely want one.
*/
import * as stylex from '@stylexjs/stylex';
@@ -25,7 +33,7 @@ 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';
+import {CORRECTED_EXIT_RULE, GUIDANCE_CONFLICTS} from '../publishedGuidance';
const sx = stylex.create({
full: {width: '100%'},
@@ -51,6 +59,77 @@ const LAYER_CONSUMERS = [
'Breadcrumbs overflow',
];
+/**
+ * The same list, sorted by whether an exit would aid orientation — which is
+ * the test the sources actually support, rather than "is it a presence
+ * surface".
+ *
+ * This is a judgement, not a measurement: the generator can see that a
+ * component has no exit, and cannot see whether it wants one. Argue with the
+ * rows. The three marked `named` are quoted verbatim in the published page as
+ * surfaces that may disappear instantly, so those are not a judgement at all.
+ */
+const EXIT_TRIAGE: ReadonlyArray<{
+ readonly surface: string;
+ readonly earns: boolean;
+ readonly named?: boolean;
+ readonly why: string;
+}> = [
+ {
+ surface: 'Dialog, AlertDialog',
+ earns: true,
+ why: 'Dismissal reveals the page underneath, and the user chose it deliberately. The published page names a dialog as its own example of an exit worth animating.',
+ },
+ {
+ surface: 'Lightbox',
+ earns: true,
+ why: 'Full-screen. Without an exit the underlying page reappears with no explanation of where the image went.',
+ },
+ {
+ surface: 'BottomSheet, MobileNav',
+ earns: true,
+ why: 'Spatially anchored to an edge, so the exit has an obvious direction and the entrance already established it.',
+ },
+ {
+ surface: 'CommandPalette',
+ earns: true,
+ why: 'Modal and it covers content — but it is also a power-user surface hit many times a day, so this is the row most likely to flip on frequency grounds.',
+ },
+ {
+ surface: 'Tooltip',
+ earns: false,
+ named: true,
+ why: 'The pointer has already left. Highest-frequency surface in the system, so criterion 2 argues against motion here even before orientation does.',
+ },
+ {
+ surface: 'HoverCard',
+ earns: false,
+ named: true,
+ why: 'Same shape as Tooltip: dismissal is a side effect of the user moving somewhere else.',
+ },
+ {
+ surface: 'DropdownMenu, ContextMenu',
+ earns: false,
+ named: true,
+ why: 'The menu has done its job the moment a pick is made, and attention has moved to whatever the pick affected.',
+ },
+ {
+ surface: 'Popover',
+ earns: false,
+ why: 'Not named on the page, but the same class. Worth a second look if a popover is ever used as a panel rather than a hint.',
+ },
+ {
+ surface: 'Selector, ComplexSelector, MultiSelector, Tokenizer',
+ earns: false,
+ why: 'Dropdown-class. Attention is on the field and the value that just landed in it, not on the list closing.',
+ },
+ {
+ surface: 'Typeahead, PowerSearch, MoreMenu, Breadcrumbs overflow',
+ earns: false,
+ why: 'Same. All of these are the user getting somewhere, and the surface closing is not the event.',
+ },
+];
+
const RIGS = [
{
title: 'Tooltip',
@@ -97,27 +176,35 @@ export default function ExitGapPage() {
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" />
- }>
+ intro="Eleven components animate in and vanish out, and the brief calls fixing all eleven the highest-leverage change in the audit. Checked against the sources it cites, most of them are already right: an exit earns its place when it aids orientation, and a surface the user has already looked away from does not qualify. What survives is narrower and still worth doing — useLayer cannot express an exit at all, which blocks the four or five surfaces that genuinely want one."
+ decides="Which surfaces earn an animated exit, and what enter and exit cost on the ones that do."
+ badges={<Badge variant="warning" label="the brief overreaches here" />}>
{conflict != null && (
<Banner
status="warning"
- title="This is not drift — it is the published guidance, correctly followed"
+ title="Not drift, and not a standoff — the sources settle this one"
description={
<VStack gap={2}>
<Text {...stylex.props(sx.quote)}>
<em>&ldquo;{conflict.published}&rdquo;</em>
</Text>
+ <Text>{conflict.reading}</Text>
+ <Text>
+ So this is not the usual which-document-wins problem. The
+ brief&rsquo;s own reference says high-frequency UI often should
+ not animate its exit, and the published page says the same thing
+ about the same surfaces. The rule the sources support is
+ narrower:
+ </Text>
+ <Text {...stylex.props(sx.quote)}>
+ <em>{CORRECTED_EXIT_RULE}</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.
+ Criterion 7 has been narrowed to match, which also resolves a
+ contradiction inside the rubric: Tooltip is high-frequency
+ enough that criterion 2 says give it no motion, while criterion
+ 7 as written made an instant dismissal a blocker. Both could not
+ hold.
</Text>
</VStack>
}
@@ -135,13 +222,63 @@ export default function ExitGapPage() {
<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.
+ Exit ships shorter than enter, which is beUI&rsquo;s rule — old
+ content should leave faster than new arrives. Treat it as a default
+ rather than a law. Emil scopes asymmetric timing to system responses
+ versus deliberate actions, and a dialog the user chose to close and
+ is watching may want the full enter duration. Drag them equal and
+ judge it per surface rather than globally.
</Text>
</DemoBody>
</DemoCard>
+ <DemoCard
+ title="Which of the eleven actually earn an exit"
+ question="Orientation is the test, not presence. Three of these are named in the published page as instant-dismissal surfaces — the rest is judgement, so argue with it.">
+ <DemoBody>
+ <VStack gap={2} {...stylex.props(sx.full)}>
+ {EXIT_TRIAGE.map(row => (
+ <HStack key={row.surface} gap={3} vAlign="start">
+ <Badge
+ variant={row.earns ? 'success' : 'neutral'}
+ label={row.earns ? 'earns one' : 'instant is fine'}
+ />
+ <VStack gap={0.5}>
+ <HStack gap={2} vAlign="center">
+ <Text weight="semibold">{row.surface}</Text>
+ {row.named === true && (
+ <Badge variant="warning" label="named in the docs" />
+ )}
+ </HStack>
+ <Text type="supporting" color="secondary">
+ {row.why}
+ </Text>
+ </VStack>
+ </HStack>
+ ))}
+ </VStack>
+ <Text type="supporting" color="secondary">
+ Four surfaces earn an exit and seven do not, which inverts the
+ brief&rsquo;s framing: the fix is not eleven components short of a
+ dismissal animation, it is a shared primitive that cannot express
+ one for the four that want it. The work is the same size. The
+ justification, and the rubric gate that follows from it, are not.
+ </Text>
+ </DemoBody>
+ </DemoCard>
+
+ <Heading level={2}>
+ What an exit looks like on a surface that may not want one
+ </Heading>
+ <Text color="secondary">
+ All four demos below are surfaces the triage puts in the &ldquo;instant
+ is fine&rdquo; column, and three are named in the published page. They
+ are still worth looking at — you cannot judge whether a dismissal aids
+ orientation without seeing the alternative — but read them as the
+ question rather than the fix. The card that follows them, Dialog, is the
+ clear case for.
+ </Text>
+
{RIGS.map(rig => (
<DemoCard
key={rig.title}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/layout.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/layout.tsx
index 162322045e..98c42d5b96 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/layout.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/layout.tsx
@@ -2,7 +2,7 @@
/**
* @file layout.tsx
- * @input The Motion Lab provider and shell
+ * @input The Motion Lab provider, the link provider, and the shell
* @output The /pages/motion-lab section frame
* @position Next.js segment layout
*
@@ -12,16 +12,35 @@
* 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.
+ *
+ * LinkProvider is here for a subtler reason. The sandbox deploys under a
+ * basePath (`/astryx/pr/<n>/sandbox` on a PR preview, `/astryx/sandbox` on
+ * main), and `next/link` prepends it automatically — which is why the rest of
+ * the app links correctly. Astryx's own `Link` renders a plain anchor, so a
+ * root-absolute `href="/pages/motion-lab/..."` written by hand escapes the
+ * basePath entirely and lands on the org's root site. Pointing LinkProvider at
+ * `next/link` makes every Astryx `Link` in this section route through Next and
+ * pick the prefix up.
+ *
+ * `ListItem` routes through the same provider, so the nav panel is covered
+ * too. Nothing in this section should prepend the basePath by hand: Next does
+ * it exactly once, and doing it again yields a double-prefixed URL that 404s.
*/
+'use client';
+
+import NextLink from 'next/link';
import type {ReactNode} from 'react';
+import {LinkProvider} from '@astryxdesign/core/Link';
import {MotionLabProvider} from './MotionLabStore';
import {MotionLabShell} from './MotionLabShell';
export default function MotionLabLayout({children}: {children: ReactNode}) {
return (
- <MotionLabProvider>
- <MotionLabShell>{children}</MotionLabShell>
- </MotionLabProvider>
+ <LinkProvider component={NextLink}>
+ <MotionLabProvider>
+ <MotionLabShell>{children}</MotionLabShell>
+ </MotionLabProvider>
+ </LinkProvider>
);
}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/motionCost.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/motionCost.ts
new file mode 100644
index 0000000000..9c609dad39
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/motionCost.ts
@@ -0,0 +1,314 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file motionCost.ts
+ * @input Every continuous animation in core, lab, and this lab's own stylesheet
+ * @output A cost tier per technique, and the inventory behind it
+ * @position Motion Lab data module; no React, no side effects
+ *
+ * DESIGN.md's hard rule is "aesthetics never outrank performance". This file is
+ * the mechanics for the one case where a motion decision keeps costing after
+ * the interaction ends: an animation that loops.
+ *
+ * A one-shot transition costs once. A loop costs every frame it runs, on every
+ * page it appears on, for as long as the page is open — including while the
+ * user is doing nothing at all. That is a different kind of decision from
+ * "which curve", and the rubric did not have a criterion for it.
+ *
+ * The background is kt-fr88: the working marks' ambient colour fade repainted
+ * the FULL DOCUMENT at 60fps on an idle page — 1,591 document paints in 28s
+ * with the GPU 78% busy. The property was the whole bug. Fixing it took a 4s
+ * idle window from ~1,414 paints to under 100.
+ *
+ * What the rule asks for, in order of how much it buys:
+ *
+ * 1. Compositor properties only — opacity and transform. Never animate a
+ * paint-only property (colour, box-shadow, background-position) or a
+ * layout property (width, inset, height) continuously. If something must
+ * move that cannot be expressed as a transform, step it at the lowest
+ * legible cadence with steps(), not per frame.
+ * 2. Contain the paint. A loop paints inside its own box: `contain: paint`
+ * plus a deliberate layer (`will-change: transform`), so a repaint cannot
+ * escape into the document.
+ * 3. Gate the layer on `prefers-reduced-motion: no-preference`, so a user who
+ * asked for less motion is not charged layer memory for a stilled mark.
+ * 4. Every loop has a reduced-motion arm that stills the movement and leaves
+ * the state legible.
+ *
+ * Evidence: D117309888 — idle paints 1,414 -> 93, raster tasks 12,060 -> 480,
+ * style time 543ms -> 155ms, in a 4s window.
+ */
+
+/**
+ * What a technique costs while nothing is happening.
+ *
+ * The tiers are about IDLE cost specifically. A one-shot transition can be
+ * expensive for 200ms and still be `idle` here, because it stops. That is the
+ * point of the distinction: criterion 6 already governs which properties a
+ * transition may animate, and this governs what keeps running afterwards.
+ */
+export type MotionCost = 'idle' | 'low' | 'medium' | 'high';
+
+export const COST_LABEL: Readonly<Record<MotionCost, string>> = {
+ idle: 'Idle',
+ low: 'Low',
+ medium: 'Medium',
+ high: 'High',
+};
+
+export const COST_VARIANT: Readonly<
+ Record<MotionCost, 'neutral' | 'success' | 'warning' | 'error'>
+> = {
+ idle: 'neutral',
+ low: 'success',
+ medium: 'warning',
+ high: 'error',
+};
+
+export const COST_TIERS: ReadonlyArray<{
+ readonly cost: MotionCost;
+ readonly meaning: string;
+ readonly gate: string;
+}> = [
+ {
+ cost: 'idle',
+ meaning:
+ 'Nothing runs once the interaction is over. Cost is paid per interaction and bounded by the duration.',
+ gate: 'No cost review needed. Criterion 6 still governs which properties it may touch.',
+ },
+ {
+ cost: 'low',
+ meaning:
+ 'Loops, but on compositor properties only, inside its own paint box, with a deliberate layer and a reduced-motion arm.',
+ gate: 'Ships. This is the target shape for anything that must run continuously.',
+ },
+ {
+ cost: 'medium',
+ meaning:
+ 'Loops on compositor properties, but the paint is not contained — so a repaint can escape into the document, and the cost scales with how many instances are on screen.',
+ gate: 'Ships for a single small instance. Needs containment before it is used in a list, a table, or anywhere it multiplies.',
+ },
+ {
+ cost: 'high',
+ meaning:
+ 'Loops on a paint-only, inherited, or layout property. This is the kt-fr88 shape: it repaints or re-lays-out every frame, forever, on an idle page.',
+ gate: 'Blocker. Move it to transform/opacity, or step it with steps() at the lowest legible cadence.',
+ },
+];
+
+export const COST_RULE =
+ 'A looping animation runs forever, so it is judged on idle cost, not duration. Compositor properties only; contain the paint and take a deliberate layer; gate the layer on prefers-reduced-motion: no-preference; and give every loop an arm that stills it.';
+
+export const COST_EVIDENCE =
+ 'kt-fr88: an ambient colour fade repainted the full document at 60fps on an idle page \u2014 1,591 document paints in 28s, GPU 78% busy. D117309888 cut a 4s idle window from 1,414 paints to 93, raster tasks from 12,060 to 480, and style time from 543ms to 155ms.';
+
+/**
+ * Every continuous animation in the two published packages and in this lab's
+ * own stylesheet, with the property it actually animates.
+ *
+ * Read off the source rather than assumed, because the property is the whole
+ * finding: two loops that look identical on screen can differ by an order of
+ * magnitude in what they cost, and the difference is invisible until you read
+ * the keyframes.
+ */
+export type LoopSite = {
+ readonly where: 'core' | 'lab' | 'motion-lab';
+ readonly component: string;
+ readonly file: string;
+ /** The property the keyframes actually animate. */
+ readonly animates: string;
+ readonly compositorSafe: boolean;
+ readonly contained: boolean;
+ readonly hasLayer: boolean;
+ readonly hasReducedMotionArm: boolean;
+ readonly cost: MotionCost;
+ readonly note: string;
+};
+
+export const LOOP_INVENTORY: ReadonlyArray<LoopSite> = [
+ // ---------------------------------------------------------------- core ---
+ {
+ where: 'core',
+ component: 'Spinner',
+ file: 'core/Spinner/Spinner.tsx',
+ animates: 'transform: rotate',
+ compositorSafe: true,
+ contained: false,
+ hasLayer: true,
+ hasReducedMotionArm: true,
+ cost: 'low',
+ note: 'The best-behaved loop in either package, and the only one that takes a deliberate layer. Still not paint-contained, and the layer is unconditional rather than gated on prefers-reduced-motion.',
+ },
+ {
+ where: 'core',
+ component: 'Skeleton',
+ file: 'core/Skeleton/Skeleton.tsx',
+ animates: 'opacity',
+ compositorSafe: true,
+ contained: false,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'medium',
+ note: 'Correct property, and the most-multiplied loop in the system: a loading table is dozens of these at once, each repainting uncontained. This is the strongest containment candidate in core.',
+ },
+ {
+ where: 'core',
+ component: 'ProgressBar',
+ file: 'core/ProgressBar/ProgressBar.tsx',
+ animates: 'transform (indeterminate slide)',
+ compositorSafe: true,
+ contained: false,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'medium',
+ note: 'The indeterminate loop is transform and fine. Separately, line 244 transitions `width` on the determinate fill \u2014 one-shot per data change, so not a loop, but a bar fed by a fast upload ticks often enough to behave like one.',
+ },
+ {
+ where: 'core',
+ component: 'StatusDot',
+ file: 'core/StatusDot/StatusDot.tsx',
+ animates: 'opacity',
+ compositorSafe: true,
+ contained: false,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'medium',
+ note: 'Correct property. Multiplies the same way Skeleton does \u2014 a status column is one of these per row, all pulsing uncontained.',
+ },
+ {
+ where: 'core',
+ component: 'Chat (message metadata)',
+ file: 'core/Chat/ChatMessageMetadata.tsx',
+ animates: 'opacity',
+ compositorSafe: true,
+ contained: false,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'medium',
+ note: 'Correct property, single small instance, so the containment gap is theoretical here rather than urgent.',
+ },
+ // ----------------------------------------------------------------- lab ---
+ {
+ where: 'lab',
+ component: 'Chat (typing indicator)',
+ file: 'lab/Chat/ChatTypingIndicator.tsx',
+ animates: 'transform + opacity',
+ compositorSafe: true,
+ contained: false,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'medium',
+ note: 'Correct properties. Three dots, each its own loop, staggered by hardcoded 160ms and 320ms delays.',
+ },
+ {
+ where: 'lab',
+ component: 'ChatReasoning',
+ file: 'lab/ChatReasoning/ChatReasoning.tsx',
+ animates: 'background-position',
+ compositorSafe: false,
+ contained: false,
+ hasLayer: false,
+ hasReducedMotionArm: false,
+ cost: 'high',
+ note: 'The worst loop in either package, and the only one failing on every axis at once: a paint-only property, uncontained, no layer, and no reduced-motion arm \u2014 running for 4s per iteration, forever, behind streaming text the user is already reading.',
+ },
+ {
+ where: 'lab',
+ component: 'CircularProgress',
+ file: 'lab/CircularProgress/CircularProgress.tsx',
+ animates: 'stroke-dasharray + stroke-dashoffset',
+ compositorSafe: false,
+ contained: false,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'high',
+ note: 'SVG geometry, so the path is re-rasterised every frame. The sibling rotation loop on the same component is a clean transform \u2014 the two sit side by side, which makes this the clearest teaching case in the audit. Has no row in the preview plan at all.',
+ },
+ // ----------------------------------------------------------- this lab ---
+ {
+ where: 'motion-lab',
+ component: 'Loop demo \u2014 spinner',
+ file: 'MotionLab.module.css .loopSpinner',
+ animates: 'transform: rotate',
+ compositorSafe: true,
+ contained: true,
+ hasLayer: true,
+ hasReducedMotionArm: true,
+ cost: 'low',
+ note: 'Contained after this audit.',
+ },
+ {
+ where: 'motion-lab',
+ component: 'Loop demo \u2014 pulse dot',
+ file: 'MotionLab.module.css .pulseDot',
+ animates: 'box-shadow',
+ compositorSafe: false,
+ contained: true,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'high',
+ note: 'A spreading box-shadow on a colour-mix, per frame \u2014 structurally the kt-fr88 bug. Kept deliberately: it is the demo of what the rule forbids, and it is now paint-contained so the demonstration cannot repaint the page around it.',
+ },
+ {
+ where: 'motion-lab',
+ component: 'Loop demo \u2014 shimmer',
+ file: 'MotionLab.module.css .shimmer',
+ animates: 'background-position',
+ compositorSafe: false,
+ contained: true,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'high',
+ note: 'The skeleton-shimmer idiom, and the same violation as ChatReasoning. Kept as the demo; contained after this audit.',
+ },
+ {
+ where: 'motion-lab',
+ component: 'Loop demo \u2014 progress (width)',
+ file: 'MotionLab.module.css .progressFillWidth',
+ animates: 'inset-inline-start',
+ compositorSafe: false,
+ contained: true,
+ hasLayer: false,
+ hasReducedMotionArm: true,
+ cost: 'high',
+ note: 'A layout property animated continuously \u2014 the most expensive shape available, running layout for its containing block every frame. This is the "before" pane of the compositor demo, so it earns its place, but it was uncontained until this audit.',
+ },
+ {
+ where: 'motion-lab',
+ component: 'Loop demo \u2014 progress (transform)',
+ file: 'MotionLab.module.css .progressFillTransform',
+ animates: 'transform: translateX',
+ compositorSafe: true,
+ contained: true,
+ hasLayer: true,
+ hasReducedMotionArm: true,
+ cost: 'low',
+ note: 'The "after" pane, and already the target shape: transform with a deliberate layer.',
+ },
+];
+
+/** Rolled up for the summary line, so the counts cannot drift from the table. */
+export const LOOP_COUNTS = {
+ total: LOOP_INVENTORY.length,
+ core: LOOP_INVENTORY.filter(l => l.where === 'core').length,
+ lab: LOOP_INVENTORY.filter(l => l.where === 'lab').length,
+ motionLab: LOOP_INVENTORY.filter(l => l.where === 'motion-lab').length,
+ high: LOOP_INVENTORY.filter(l => l.cost === 'high').length,
+ paintOrLayout: LOOP_INVENTORY.filter(l => !l.compositorSafe).length,
+ uncontained: LOOP_INVENTORY.filter(l => !l.contained).length,
+ missingArm: LOOP_INVENTORY.filter(l => !l.hasReducedMotionArm).length,
+ /** Published packages only — what a consumer of Astryx actually pays. */
+ publishedUncontained: LOOP_INVENTORY.filter(
+ l => l.where !== 'motion-lab' && !l.contained,
+ ).length,
+} as const;
+
+/**
+ * The finding, in one paragraph, for anyone who reads only the summary.
+ *
+ * Worth stating plainly because it is not the result anyone expected: core is
+ * the clean part. Every loop it ships is opacity or transform and every one has
+ * a reduced-motion arm. The property discipline is already there.
+ */
+export const COST_SUMMARY =
+ 'Core is clean on the part that matters most: all five of its loops animate opacity or transform, and all five have a reduced-motion arm. The two high-cost loops are both in lab \u2014 ChatReasoning animates background-position with no reduced-motion arm at all, and CircularProgress animates SVG stroke geometry. The systemic gap is containment: of the nine loops the two packages publish, exactly one takes a deliberate layer (Spinner) and none are paint-contained, so every loop can repaint beyond its own box. That costs least on a lone spinner and most on Skeleton and StatusDot, which are the two that multiply.';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/motionTokens.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/motionTokens.ts
index 34f6398ba8..4090aa4689 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/motionTokens.ts
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/motionTokens.ts
@@ -138,7 +138,7 @@ export const SEMANTIC_DURATIONS: ReadonlyArray<SemanticDuration> = [
primitive: '--duration-fast',
job: 'Dismissal.',
budget: [100, 250],
- note: 'Deliberately shorter than enter, because old content should leave faster than new content arrives.',
+ note: 'Shorter than enter, which beUI states plainly — old content should leave faster than new arrives. Treat it as a default rather than a law: Emil scopes asymmetric timing to system responses versus deliberate actions, and a dismissal the user chose and is watching may want the full enter duration. Nothing cited supports the ratio as a universal rule.',
},
{
name: '--duration-reveal',
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/openQuestions.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/openQuestions.ts
index 226cf2171f..a6f2cd12b0 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/openQuestions.ts
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/openQuestions.ts
@@ -261,7 +261,7 @@ export const COMMITMENTS: ReadonlyArray<Commitment> = [
{
item: 'Layer exit + shared presence primitive',
level: 'committed',
- why: 'Eleven components from one change. The highest-leverage item in the audit.',
+ why: 'Four surfaces that genuinely want an exit, blocked by one primitive that cannot express one. The brief counts eleven; the triage on the exit-gap page argues most of those are correct as they are.',
},
{
item: 'Dialog, AlertDialog, CommandPalette exit + backdrop',
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
index edc0c7c1e4..dc68dcc28d 100644
--- 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
@@ -14,6 +14,7 @@
* by the general shape.
*/
+import {COST_LABEL, COST_VARIANT} from '../motionCost';
import {useMemo, useState} from 'react';
import {Badge} from '@astryxdesign/core/Badge';
import {Banner} from '@astryxdesign/core/Banner';
@@ -92,12 +93,24 @@ function RowCard({row}: {row: PreviewRow}) {
}
/>
<Badge label={PRIORITY_LABEL[row.priority]} />
+ {row.motionCost !== 'idle' && (
+ <Badge
+ variant={COST_VARIANT[row.motionCost]}
+ label={`${COST_LABEL[row.motionCost]} idle cost`}
+ />
+ )}
</HStack>
<HStack gap={3} wrap="wrap">
<Text type="supporting" color="secondary">
{`Today: ${row.today}`}
</Text>
</HStack>
+ {row.motionCostWhy != null && (
+ <Text type="supporting" color="secondary">
+ <strong>{`${COST_LABEL[row.motionCost]} idle cost: `}</strong>
+ {row.motionCostWhy}
+ </Text>
+ )}
<Text type="supporting" color="secondary">
{`Gap: ${row.gap}`}
</Text>
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previewPlan.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previewPlan.ts
index becc7c917f..f7d5a29c8c 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previewPlan.ts
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previewPlan.ts
@@ -17,6 +17,7 @@
* instead of trusting the brief. Several rows do not survive that check.
*/
+import type {MotionCost} from './motionCost';
import {
ANIMATING_COMPONENTS,
STATIC_COMPONENTS,
@@ -29,6 +30,14 @@ export type PreviewRow = {
readonly component: string;
readonly group: string;
readonly verdict: Verdict;
+ /**
+ * What this row costs while nothing is happening. `idle` is the default and
+ * the overwhelming majority: a one-shot transition stops. Anything else
+ * loops, and is judged on idle cost rather than duration. See motionCost.ts.
+ */
+ readonly motionCost: MotionCost;
+ /** Only where the cost is not `idle` — what runs, and what it animates. */
+ readonly motionCostWhy?: string;
/** Core directories this row covers, for the measurement cross-check. */
readonly dirs: ReadonlyArray<string>;
readonly today: string;
@@ -65,6 +74,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Tooltip',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Tooltip'],
today: 'Direction-aware fade and scale in.',
gap: 'Hard-cuts on every dismiss, on the highest-frequency surface in the system.',
@@ -89,6 +99,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'HoverCard',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['HoverCard'],
today: 'Fade and scale in.',
gap: 'No exit; the most visible instance of the gap because the surface is large.',
@@ -107,6 +118,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Popover',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Popover'],
today: 'Fade and scale in.',
gap: 'No exit.',
@@ -125,6 +137,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'DropdownMenu',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['DropdownMenu'],
today: 'Fade and scale in, submenus too.',
gap: 'No exit; menus snap shut.',
@@ -148,6 +161,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'ContextMenu',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['ContextMenu'],
today: 'Fade and scale in.',
gap: 'No exit.',
@@ -166,6 +180,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Selector / ComplexSelector / MultiSelector',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Selector', 'ComplexSelector', 'MultiSelector'],
today: 'Chevron rotate plus layer entry.',
gap: 'No exit. The brief also claims three dead no-op transition rules here.',
@@ -190,6 +205,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'PowerSearch / Typeahead / MoreMenu',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['PowerSearch', 'Typeahead', 'MoreMenu'],
today: 'Layer entry only.',
gap: 'No exit, and no motion when tokens or results are added and removed.',
@@ -213,6 +229,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Dialog',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Dialog'],
today: 'Directional keyframe entry.',
gap: 'No exit, and the backdrop has no transition at all, so the scrim hard-cuts.',
@@ -236,13 +253,14 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'AlertDialog',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
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.',
+ 'Confirming a destructive action. The dialog should be gone before the consequence appears — the clearest case for a shorter exit, and worth contrasting with a dialog the user simply closes, where the dismissal is deliberate and may want the full enter duration.',
controls: ['panel duration', 'exit duration', 'confirm vs cancel path'],
status: 'built',
rig: 'DialogRig',
@@ -254,6 +272,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'CommandPalette',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['CommandPalette'],
today: 'Inherits the Dialog entry.',
gap: 'No exit, and no motion on the result list as it filters.',
@@ -276,6 +295,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Lightbox',
group: 'Overlays & layers',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Lightbox'],
today: 'Image zoom and pan only.',
gap: 'A full-screen surface with no open or close at all.',
@@ -295,6 +315,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'BottomSheet',
group: 'Overlays & layers',
verdict: 'GOOD',
+ motionCost: 'idle',
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.',
@@ -313,6 +334,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'MobileNav',
group: 'Overlays & layers',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['MobileNav'],
today:
'Slide plus backdrop; reads its own computed duration to time the close.',
@@ -332,6 +354,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Overlay / scrim',
group: 'Overlays & layers',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Overlay'],
today: 'Per-edge slide, both directions.',
gap: 'None — the template the presence primitive should generalise.',
@@ -350,6 +373,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Drawer (lab)',
group: 'Overlays & layers',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: [],
today: 'Slide plus backdrop.',
gap: 'Closes after a hardcoded 250ms while the slide is 410ms, so the exit is cut at ~60%.',
@@ -371,6 +395,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Collapsible',
group: 'Disclosure & expansion',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Collapsible'],
today: 'Height interpolation, offset content fade, theme-tunable.',
gap: 'None, but it is the only component doing it this way.',
@@ -389,6 +414,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'CodeBlock',
group: 'Disclosure & expansion',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['CodeBlock'],
today: 'Grid-track expand plus chevron.',
gap: 'A different technique from Collapsible, for the same job.',
@@ -407,6 +433,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Table row expansion',
group: 'Disclosure & expansion',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Table'],
today: 'Chevron rotate only.',
gap: 'The revealed content appears instantly.',
@@ -424,6 +451,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Table tree / grouped rows',
group: 'Disclosure & expansion',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Table'],
today: 'Chevron rotate only.',
gap: 'Same as row expansion, plus the hardcoded 150ms values.',
@@ -443,6 +471,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'TreeList',
group: 'Disclosure & expansion',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['TreeList'],
today: 'Row tint plus chevron.',
gap: 'The child list reveal is instant.',
@@ -460,6 +489,9 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Chat tool calls / reasoning',
group: 'Disclosure & expansion',
verdict: 'PARTIAL',
+ motionCost: 'high',
+ motionCostWhy:
+ 'ChatReasoning animates `background-position` — paint-only, 4s per iteration, forever, with no reduced-motion arm and no containment. It fails every axis of the rule at once, behind streaming text the user is already reading. The highest-cost animation in either package.',
dirs: ['Chat'],
today: 'Grid-track expand; a 1.5s reasoning shimmer.',
gap: 'A third disclosure technique, and the shimmer has no reduced-motion escape.',
@@ -480,6 +512,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'SideNav',
group: 'Navigation',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['SideNav'],
today: 'Sub-list expand, chevron, collapse button.',
gap: 'The rail\u2019s own collapse is not animated; only the chevron rotates.',
@@ -497,6 +530,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'TabList',
group: 'Navigation',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['TabList'],
today: 'Per-tab indicator cross-fade.',
gap: 'The indicator does not slide between tabs; each tab owns its own bar.',
@@ -515,6 +549,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'SegmentedControl',
group: 'Navigation',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['SegmentedControl'],
today: 'Per-item background tint.',
gap: 'No sliding thumb, so the selected pill jumps.',
@@ -533,6 +568,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'TopNav',
group: 'Navigation',
verdict: 'PARTIAL',
+ motionCost: 'idle',
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.',
@@ -556,6 +592,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'NavItem / NavMenu',
group: 'Navigation',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['NavItem', 'NavMenu'],
today: 'Nothing.',
gap: 'No hover or active transition, unlike every sibling nav item.',
@@ -574,6 +611,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Outline',
group: 'Navigation',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Outline'],
today: 'Marker slide plus item tint.',
gap: 'Animates top and height, which thrashes layout.',
@@ -592,6 +630,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Breadcrumbs',
group: 'Navigation',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Breadcrumbs'],
today: 'Overflow menu entry.',
gap: 'Crumb collapse on resize is instant.',
@@ -609,6 +648,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Pagination',
group: 'Navigation',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Pagination'],
today: 'Cell tint.',
gap: 'Page change is an instant content swap.',
@@ -629,6 +669,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Button',
group: 'Inputs & controls',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Button'],
today: 'Tint, press scale, loading swap.',
gap: 'The brief calls the press transform transition the main Motion conflict.',
@@ -648,6 +689,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'IconButton / ToggleButton',
group: 'Inputs & controls',
verdict: 'GOOD',
+ motionCost: 'idle',
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.',
@@ -667,6 +709,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Switch',
group: 'Inputs & controls',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Switch'],
today: 'Track tint plus thumb travel.',
gap: 'Animates the thumb width and height, which are layout properties.',
@@ -684,6 +727,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'CheckboxInput / RadioList / Indicator',
group: 'Inputs & controls',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['CheckboxInput', 'RadioList', 'Indicator'],
today: 'Box tint and border.',
gap: 'The tick and the dot never draw or scale in.',
@@ -703,6 +747,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Field / TextInput / TextArea / NumberInput',
group: 'Inputs & controls',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Field', 'TextInput', 'TextArea', 'NumberInput'],
today: 'Border and focus ring transitions.',
gap: 'TextArea auto-grow is not animated.',
@@ -722,6 +767,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Slider',
group: 'Inputs & controls',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Slider'],
today: 'Thumb tint and shadow.',
gap: 'The thumb does not transition on keyboard step.',
@@ -740,6 +786,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Calendar / DateInput',
group: 'Inputs & controls',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Calendar', 'DateInput'],
today:
'Cell tint; the touch wheel is scroll-driven and genuinely advanced.',
@@ -759,6 +806,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Tokenizer / Token',
group: 'Inputs & controls',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Tokenizer', 'Token'],
today: 'Background transition on the token only.',
gap: 'Chip add and remove, the canonical scale-in case, is instant.',
@@ -782,6 +830,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'FileInput',
group: 'Inputs & controls',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['FileInput'],
today: 'Dropzone border and tint.',
gap: 'File chips add and remove with no motion.',
@@ -799,6 +848,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Resizable',
group: 'Inputs & controls',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Resizable'],
today: 'Handle tint and grip.',
gap: 'Panel snap and collapse are instant.',
@@ -819,6 +869,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Toast',
group: 'Feedback & status',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Toast'],
today: 'Entry, exit, and stack collapse.',
gap: 'None, though it animates grid tracks and padding.',
@@ -842,6 +893,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Banner',
group: 'Feedback & status',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Banner'],
today: 'Chevron rotate.',
gap: 'A dismissible banner appearing and leaving is unanimated.',
@@ -860,6 +912,9 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Skeleton',
group: 'Feedback & status',
verdict: 'ADD',
+ motionCost: 'medium',
+ motionCostWhy:
+ 'An opacity loop: correct property, no containment. The most-multiplied loop in the system — a loading table is dozens of these at once, each able to repaint beyond its own box. Strongest containment candidate in core.',
dirs: ['Skeleton'],
today: 'Staggered pulse.',
gap: 'No skeleton-to-content crossfade; content hard-swaps.',
@@ -878,6 +933,9 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Spinner',
group: 'Feedback & status',
verdict: 'PARTIAL',
+ motionCost: 'low',
+ motionCostWhy:
+ 'A rotation loop on transform, with a deliberate layer and a reduced-motion arm — the best-behaved loop in either package. Not paint-contained, which is the only thing between it and the target shape.',
dirs: ['Spinner'],
today: 'Rotation.',
gap: 'Reduced motion slows the loop to 3s rather than stopping it.',
@@ -895,6 +953,9 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'ProgressBar',
group: 'Feedback & status',
verdict: 'PARTIAL',
+ motionCost: 'medium',
+ motionCostWhy:
+ 'The indeterminate slide is a clean transform loop, uncontained. Separately ProgressBar.tsx:244 transitions `width` on the determinate fill: one-shot per data change, but a bar fed by a fast upload ticks often enough to behave like a layout loop.',
dirs: ['ProgressBar'],
today: 'Width fill plus an indeterminate slide.',
gap: 'Animates width; reduced motion slows rather than stops.',
@@ -913,6 +974,9 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'StatusDot',
group: 'Feedback & status',
verdict: 'PARTIAL',
+ motionCost: 'medium',
+ motionCostWhy:
+ 'An opacity loop, uncontained, and it multiplies the way Skeleton does — a status column is one per row, all pulsing at once.',
dirs: ['StatusDot'],
today: 'A pulse at a hardcoded 2s with ease-in-out.',
gap: 'Bypasses the scale entirely, because the scale stops at 1300ms.',
@@ -931,6 +995,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'FieldStatus',
group: 'Feedback & status',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['FieldStatus'],
today: 'Slide-down entry, via the shared entry hook.',
gap: 'Error text leaves instantly.',
@@ -950,6 +1015,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Badge',
group: 'Feedback & status',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Badge'],
today: 'Nothing.',
gap: 'Count changes pop in.',
@@ -967,6 +1033,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Avatar / AvatarGroup',
group: 'Feedback & status',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['Avatar', 'AvatarGroup'],
today: 'Nothing.',
gap: 'Image load and member enter/leave both pop in.',
@@ -987,6 +1054,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Markdown',
group: 'Content & data',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Markdown'],
today: 'Streaming chunk fade-in.',
gap: 'None — well built, and the only streaming-aware motion in the system.',
@@ -1005,6 +1073,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Thumbnail',
group: 'Content & data',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Thumbnail'],
today: 'Hover-intent reveal for actions.',
gap: 'None — the only consumer of the most sophisticated motion code in the repo.',
@@ -1023,6 +1092,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Table rows',
group: 'Content & data',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Table'],
today: 'Row tint.',
gap: 'No reduced-motion handling anywhere in Table, and nine hardcoded 150ms values.',
@@ -1041,6 +1111,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Carousel',
group: 'Content & data',
verdict: 'PARTIAL',
+ motionCost: 'idle',
dirs: ['Carousel'],
today: 'Edge fade plus control opacity.',
gap: 'A paint-heavy mask transition, and no explicit slide.',
@@ -1058,6 +1129,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'List / OverflowList',
group: 'Content & data',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['List', 'OverflowList'],
today: 'Item tint only.',
gap: 'Add, remove and reorder are all instant.',
@@ -1076,6 +1148,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'EmptyState',
group: 'Content & data',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: ['EmptyState'],
today: 'Nothing.',
gap: 'The archetypal content-swap surface, entirely static.',
@@ -1093,6 +1166,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Stepper',
group: 'Content & data',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: ['Stepper'],
today: 'Connector fill and node tint.',
gap: 'Step content swap is instant.',
@@ -1111,6 +1185,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'ListInput (lab)',
group: 'Content & data',
verdict: 'GOOD',
+ motionCost: 'idle',
dirs: [],
today: 'View Transitions reorder.',
gap: 'None — the only View Transitions user in the repo.',
@@ -1130,6 +1205,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'TransferList (lab)',
group: 'Content & data',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: [],
today: 'Nothing.',
gap: 'Moving an item between lists — the whole point of the component — is instant.',
@@ -1149,6 +1225,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Stat (lab)',
group: 'Content & data',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: [],
today: 'Nothing.',
gap: 'Numeric value changes with no motion.',
@@ -1168,6 +1245,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
component: 'Chart / Radial / Sankey / Schedule (lab)',
group: 'Content & data',
verdict: 'ADD',
+ motionCost: 'idle',
dirs: [],
today: 'Axis ticks only, via inline styles.',
gap: 'No transition on data change, and outside the token system entirely.',
@@ -1188,6 +1266,7 @@ export const PREVIEW_PLAN: ReadonlyArray<PreviewRow> = [
'Layout primitives (Stack, Grid, Card, Divider, Text, Heading, Kbd + 19 more)',
group: 'Content & data',
verdict: 'NONE',
+ motionCost: 'idle',
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.',
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
index e3e258fc93..593cf55a52 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previews/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/previews/page.tsx
@@ -72,6 +72,18 @@ export default function PreviewsPage() {
/>
<DemoBody>
<TokenSlider token="--duration-reveal" label="travel" max={700} />
+ <Text type="supporting" color="secondary">
+ Both panes here are core&rsquo;s <code>TabList</code>. The right one
+ is a swizzled copy of that same source with three changes — a{' '}
+ <code>hasTravellingIndicator</code> prop, one indicator in the strip
+ positioned over the selected tab, and a context flag telling each
+ Tab to suppress the indicator it draws for itself. It lives at{' '}
+ <code>proposed/TabList/</code>, so the difference you are watching
+ is the diff. The position is measured from the DOM rather than
+ tracked in state, because the tabs size themselves — that
+ ResizeObserver is the only real cost the proposal adds, and is the
+ part to review if it ships.
+ </Text>
<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
@@ -143,6 +155,21 @@ export default function PreviewsPage() {
un-reflowed until the end, which reads worse than the layout cost.
Worth prototyping both before granting the exception.
</Text>
+ <Text type="supporting" color="secondary">
+ <strong>
+ Both panes here are approximated, not the real component.{' '}
+ </strong>
+ A fork of core&rsquo;s <code>SideNav</code> needs{' '}
+ <code>SideNavCollapseContext</code> on the public surface —{' '}
+ <code>SideNav</code> is a provider and core exports only the reader
+ hook. Importing the context by relative path compiles and is
+ silently wrong: the app resolves to <code>dist</code> while the
+ relative path reaches <code>src</code>, so the fork provides one
+ context object and core&rsquo;s own children read another. The
+ one-line fix is a public API surface change and wants its own
+ review, so this demo stays weaker than the TabList one below it
+ until that lands.
+ </Text>
</DemoBody>
</DemoCard>
@@ -231,7 +258,7 @@ export default function PreviewsPage() {
panes={[
{
tone: 'before',
- label: 'Today',
+ label: 'Today — real CheckboxInput',
content: <CheckTickRig technique="hard" />,
},
{
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/Tab.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/Tab.tsx
new file mode 100644
index 0000000000..185613b50b
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/Tab.tsx
@@ -0,0 +1,438 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Tab.tsx
+ * @input Uses React, StyleX, TabListContext
+ * @output Exports Tab component and TabProps type
+ * @position Core tab item; renders as button or anchor in navigation with a
+ * divider-overlay selected indicator. Where the TabList speaks the tabs
+ * pattern it is a button with role="tab".
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/TabList/TabList.doc.mjs
+ * - /packages/core/src/TabList/index.ts
+ * - /packages/core/src/TabList/TabList.test.tsx
+ * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
+ *
+ * MOTION LAB FORK — see ./index.ts. The one change here is
+ * `indicatorSuppressed`: when the strip owns a travelling indicator, this tab
+ * keeps its own in the tree but hidden. Marked PROPOSED.
+ */
+
+import React, {useCallback, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ sizeVars,
+ radiusVars,
+ durationVars,
+ easeVars,
+ fontWeightVars,
+ typeScaleVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import type {BaseProps} from '@astryxdesign/core/BaseProps';
+import {useTabListContext} from './TabListContext';
+import type {TabListSize} from './TabListContext';
+import {tabScope} from './tab.markers.stylex';
+import {useLinkComponent} from '@astryxdesign/core/Link';
+import type {LinkComponentType} from '@astryxdesign/core/Link';
+import {mergeProps} from '@astryxdesign/core/utils';
+import {useDevWarning} from '@astryxdesign/core/hooks';
+import {EDGE_COMP_ATTR} from '@astryxdesign/core/Layout';
+import {themeProps} from '@astryxdesign/core/utils';
+import {focusOutlineProps} from '@astryxdesign/core/utils';
+
+export interface TabProps extends BaseProps<HTMLButtonElement> {
+ /**
+ * Custom component to render instead of `<a>` for link tabs.
+ * Overrides the provider-level default set by LinkProvider.
+ * Only applies when `href` is provided. Must accept href, className, style, and children props.
+ */
+ as?: LinkComponentType;
+ ref?: React.Ref<HTMLButtonElement>;
+ /**
+ * Unique value for this tab. Matched against TabListContext.value.
+ */
+ value: string;
+ /**
+ * Accessible label for this tab. Used as visible text by default, or
+ * as aria-label when isLabelHidden is true.
+ */
+ label: string;
+ /**
+ * Whether the label is visually hidden. When true, only the icon and
+ * endContent are displayed, and label is used as aria-label for accessibility.
+ * @default false
+ */
+ isLabelHidden?: boolean;
+ /**
+ * URL to navigate to. When provided, renders as an anchor element.
+ *
+ * Ignored in a TabList given an explicit `role="tablist"`: activating a tab
+ * there swaps a panel in place, so a tab that navigates would be a false
+ * statement.
+ */
+ href?: string;
+ /**
+ * Id of the panel this tab controls, wired up as `aria-controls` where the
+ * TabList speaks the tabs pattern. Put the same id on the panel element.
+ *
+ * Has no effect under the navigation pattern, where there is no panel to
+ * associate — a development warning says so.
+ */
+ panelId?: string;
+ /**
+ * Icon element shown when tab is not selected.
+ */
+ icon?: ReactNode;
+ /**
+ * Icon element shown when tab is selected. Falls back to `icon` if not provided.
+ */
+ selectedIcon?: ReactNode;
+ /**
+ * Content rendered after the label (e.g. a badge or status dot).
+ */
+ endContent?: ReactNode;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ base: {
+ position: 'relative',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-3'],
+ backgroundColor: 'transparent',
+ borderWidth: 0,
+ borderStyle: 'none',
+ borderRadius: radiusVars['--radius-element'],
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--text-label-size'],
+ lineHeight: typeScaleVars['--text-label-leading'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ color: colorVars['--color-text-secondary'],
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled,[aria-disabled="true"])': 'default',
+ },
+ textDecoration: 'none',
+ whiteSpace: 'nowrap',
+ transitionProperty: 'color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ hoverBg: {
+ position: 'absolute',
+ inset: 0,
+ margin: 'auto',
+ width: '100%',
+ borderRadius: radiusVars['--radius-element'],
+ pointerEvents: 'none',
+ backgroundColor: {
+ default: 'transparent',
+ [stylex.when.ancestor(':hover', tabScope)]: {
+ '@media (hover: hover)': colorVars['--color-overlay-hover'],
+ },
+ },
+ transitionProperty: 'background-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ selected: {
+ color: colorVars['--color-text-primary'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ },
+ indicator: {
+ position: 'absolute',
+ // Sits on the tab's bottom edge by default (-1px). When the tab strip
+ // reserves space for a divider rail — TabList `hasDivider` or a Toolbar
+ // with a bottom divider — that ancestor sets `--_tab-indicator-bottom`
+ // to drop the indicator onto the rail beneath the reserved gap.
+ bottom: 'var(--_tab-indicator-bottom, -1px)',
+ insetInlineStart: spacingVars['--spacing-3'],
+ insetInlineEnd: spacingVars['--spacing-3'],
+ height: '2px',
+ borderRadius: radiusVars['--radius-full'],
+ pointerEvents: 'none',
+ transitionProperty: 'opacity, background-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ indicatorSelected: {
+ backgroundColor: colorVars['--color-accent'],
+ opacity: 1,
+ },
+ indicatorUnselected: {
+ backgroundColor: 'transparent',
+ opacity: 0,
+ },
+ /**
+ * PROPOSED — not in core.
+ *
+ * When the strip owns a single travelling indicator, this tab must not draw
+ * its own or the two stack: two bars on the selected tab, one of them
+ * cross-fading while the other slides in.
+ *
+ * `display: 'none'` rather than unmounting the element. The indicator is
+ * absolutely positioned, so hiding it costs no layout — but keeping the node
+ * in the tree keeps the DOM shape identical between the two panes of the
+ * comparison, which is the point: the only difference a reviewer sees is the
+ * motion, not a different tree.
+ */
+ indicatorSuppressed: {
+ display: 'none',
+ },
+ icon: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ flexShrink: 0,
+ },
+ labelContainer: {
+ display: 'inline-grid',
+ },
+ labelText: {
+ gridRowStart: 1,
+ gridColumnStart: 1,
+ },
+ labelSizer: {
+ gridRowStart: 1,
+ gridColumnStart: 1,
+ visibility: 'hidden',
+ pointerEvents: 'none',
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ },
+ endContentWrapper: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ flexShrink: 0,
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {height: sizeVars['--size-element-sm']},
+ md: {height: sizeVars['--size-element-md']},
+ lg: {height: sizeVars['--size-element-lg']},
+});
+
+// Hover bg uses the standard element size (one step smaller than tab)
+const hoverSizeStyles = stylex.create({
+ sm: {height: sizeVars['--size-element-sm']},
+ md: {height: sizeVars['--size-element-md']},
+ lg: {height: sizeVars['--size-element-lg']},
+});
+
+const layoutStyles = stylex.create({
+ fill: {
+ flex: 1,
+ justifyContent: 'center',
+ },
+});
+
+const iconSizeStyles = stylex.create({
+ sm: {width: '14px', height: '14px'},
+ md: {width: '16px', height: '16px'},
+ lg: {width: '18px', height: '18px'},
+});
+
+/**
+ * Tab item component. Renders as an anchor when `href` is provided,
+ * otherwise as a button.
+ *
+ * @example
+ * ```
+ * <TabList value={tab} onChange={setTab}>
+ * <Tab value="general" label="General" />
+ * <Tab value="advanced" label="Advanced" />
+ * </TabList>
+ * ```
+ */
+export function Tab({
+ as,
+ ref,
+ value,
+ label,
+ isLabelHidden = false,
+ href,
+ panelId,
+ icon,
+ selectedIcon,
+ endContent,
+ xstyle,
+ className,
+ style,
+ ...restProps
+}: TabProps) {
+ const tabListCtx = useTabListContext();
+ const LinkComponent = useLinkComponent(as);
+
+ const isSelected = tabListCtx.value === value;
+ const size: TabListSize = tabListCtx.size;
+ const isFill = tabListCtx.layout === 'fill';
+ const isTabsPattern = tabListCtx.pattern === 'tabs';
+ // PROPOSED — not in core. The strip sets this when it draws the single
+ // travelling indicator; this tab then keeps its own indicator in the tree
+ // but hidden, so exactly one bar is painted.
+ const hasTravellingIndicator = tabListCtx.hasTravellingIndicator === true;
+ const isLink = href != null && !isTabsPattern;
+ const isTabRole = isTabsPattern && !isLink;
+ const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
+ const hasVisibleLabel = !isLabelHidden && label !== '';
+
+ const handleSelect = useCallback(() => {
+ tabListCtx.onChange(value);
+ }, [tabListCtx, value]);
+
+ useDevWarning(
+ 'Tab',
+ 'href is ignored in a role="tablist" TabList — a tab swaps a panel in ' +
+ 'place rather than navigating. Drop the href, or drop the role for the ' +
+ 'navigation pattern.',
+ isTabRole && href != null,
+ );
+
+ // A consumer who wired aria-controls by hand already said which panel this
+ // is, so panelId is the sugar, not the only way in.
+ const controls = panelId ?? restProps['aria-controls'];
+
+ useDevWarning(
+ 'Tab',
+ 'a tab in a role="tablist" TabList controls nothing: pass panelId with ' +
+ 'the id of the panel it opens, so assistive technology can associate ' +
+ 'the two.',
+ isTabRole && controls == null,
+ );
+
+ useDevWarning(
+ 'Tab',
+ 'panelId does nothing outside a role="tablist" TabList — the navigation ' +
+ 'pattern has no panel to associate. Give the TabList role="tablist", ' +
+ 'or drop the panelId.',
+ !isTabsPattern && panelId != null,
+ );
+
+ const iconElement = displayIcon ? (
+ <span {...stylex.props(styles.icon, iconSizeStyles[size])}>
+ {displayIcon}
+ </span>
+ ) : null;
+
+ const sharedProps = {
+ ...restProps,
+ ...(isLabelHidden ? {'aria-label': label} : {}),
+ [EDGE_COMP_ATTR]: '',
+ 'data-tab-value': value,
+ ...(isTabRole
+ ? {
+ role: 'tab' as const,
+ 'aria-selected': isSelected,
+ // Only when there is a panel to point at: an aria-controls whose
+ // target does not exist is an invalid attribute value, which is a
+ // worse state than saying nothing. The dev warning above asks for
+ // the id instead.
+ 'aria-controls': controls,
+ }
+ : {
+ // Generic `true` ("the current item within a set"), not `page`: the
+ // strip switches views in place at least as often as it navigates,
+ // and claiming "current page" when no page changed is a false
+ // statement to a screen reader. Stays truthful for the `href` case
+ // too, just less specific. A tab role states this with
+ // aria-selected instead.
+ 'aria-current': isSelected ? ('true' as const) : undefined,
+ }),
+ // Roving tabindex: the tab strip is a single Tab stop. The selected tab is
+ // the tabbable one; the rest are reachable via arrow keys (handled by
+ // TabList's onKeyDown). When no tab is selected, TabList's repair effect
+ // makes the first stop tabbable.
+ tabIndex: isSelected ? 0 : -1,
+ ...mergeProps(
+ themeProps('tab', {
+ selected: isSelected ? 'selected' : null,
+ }),
+ focusOutlineProps.focusVisible(
+ styles.base,
+ sizeStyles[size],
+ isSelected && styles.selected,
+ isFill && layoutStyles.fill,
+ tabScope,
+ xstyle,
+ ),
+ className,
+ style,
+ ),
+ };
+
+ const hoverBgElement = (
+ <span
+ aria-hidden="true"
+ {...stylex.props(styles.hoverBg, hoverSizeStyles[size])}
+ />
+ );
+
+ const indicatorElement = (
+ <span
+ {...mergeProps(
+ themeProps('tab-indicator', {
+ selected: isSelected ? 'selected' : null,
+ }),
+ stylex.props(
+ styles.indicator,
+ isSelected ? styles.indicatorSelected : styles.indicatorUnselected,
+ // PROPOSED — not in core. Last in the list so it wins: the strip's
+ // travelling indicator is the only bar painted.
+ hasTravellingIndicator && styles.indicatorSuppressed,
+ ),
+ )}
+ />
+ );
+
+ const labelElement = hasVisibleLabel ? (
+ <span {...stylex.props(styles.labelContainer)}>
+ <span {...stylex.props(styles.labelText)}>{label}</span>
+ <span aria-hidden="true" {...stylex.props(styles.labelSizer)}>
+ {label}
+ </span>
+ </span>
+ ) : null;
+
+ const endContentElement = endContent ? (
+ <span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
+ ) : null;
+
+ if (isLink) {
+ return (
+ <LinkComponent
+ ref={ref}
+ href={href}
+ onClick={handleSelect}
+ {...sharedProps}>
+ {hoverBgElement}
+ {iconElement}
+ {labelElement}
+ {endContentElement}
+ {indicatorElement}
+ </LinkComponent>
+ );
+ }
+
+ return (
+ <button ref={ref} type="button" onClick={handleSelect} {...sharedProps}>
+ {hoverBgElement}
+ {iconElement}
+ {labelElement}
+ {endContentElement}
+ {indicatorElement}
+ </button>
+ );
+}
+
+Tab.displayName = 'Tab';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabList.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabList.tsx
new file mode 100644
index 0000000000..17c4f49e55
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabList.tsx
@@ -0,0 +1,964 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TabList.tsx
+ * @input Uses React, StyleX, TabListContext, useListFocus, useKeyboardHint,
+ * useScrollOverflow, Icon
+ * @output Exports TabList component, TabListProps and TabListOverflow types
+ * @position Tab strip wrapper; provides TabListContext to Tab and TabMenu
+ * children. A `<nav>` landmark by default; speaks the WAI-ARIA tabs pattern
+ * where the caller asks for it with `role="tablist"`. Owns
+ * roving-tabindex keyboard navigation (Arrow/Home/End) across the tab
+ * strip via the shared useListFocus hook so it is a single Tab stop, and
+ * owns horizontal scrolling when the tabs are wider than the strip.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/TabList/TabList.doc.mjs
+ * - /packages/core/src/TabList/index.ts
+ * - /packages/core/src/TabList/TabList.test.tsx
+ * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
+ *
+ * MOTION LAB FORK — swizzled from core, carrying ONE proposed change: the
+ * strip owns a single travelling indicator instead of each Tab cross-fading
+ * its own. Opt in with `hasTravellingIndicator`; off, this is core verbatim.
+ * Every changed line is marked PROPOSED. See ./index.ts for the full argument
+ * and for the swizzle bug this fork had to work around. The SYNC list above is
+ * core's and does not apply here — nothing in this directory ships.
+ */
+
+import React, {
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ type AriaRole,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ borderVars,
+ colorVars,
+ durationVars,
+ easeVars,
+ focusVars,
+ radiusVars,
+ shadowVars,
+ sizeVars,
+ spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import type {BaseProps} from '@astryxdesign/core/BaseProps';
+import {TabListContext} from './TabListContext';
+import type {TabListSize} from './TabListContext';
+import {useSize} from '@astryxdesign/core/SizeContext';
+import {mergeProps, rtlStyles} from '@astryxdesign/core/utils';
+import {useListFocus} from '@astryxdesign/core/hooks';
+import {useKeyboardHint} from '@astryxdesign/core/hooks';
+import {useScrollOverflow} from '@astryxdesign/core/hooks';
+// SWIZZLE BUG: `isRtlElement` is not part of the package's public surface, so
+// the swizzler's rewrite to '@astryxdesign/core/hooks' does not typecheck.
+// Pointed at the package source instead. See index.ts for the full list.
+import {isRtlElement} from '../../../../../../../../../packages/core/src/hooks/isRtlElement';
+import {Icon} from '@astryxdesign/core/Icon';
+import {EDGE_COMP_ATTR} from '@astryxdesign/core/Layout';
+import {themeProps} from '@astryxdesign/core/utils';
+import {observeResize, unobserveResize} from '@astryxdesign/core/utils';
+import {devWarn} from '@astryxdesign/core/utils';
+import {focusOutlineProps} from '@astryxdesign/core/utils';
+import {useTranslator} from '@astryxdesign/core/i18n';
+
+import {useMergedRefs} from '@astryxdesign/core/hooks';
+/**
+ * Selector matching the focusable stops in the tab strip: every Tab
+ * (`[data-tab-value]`) and every TabMenu trigger (`[data-tab-menu]`),
+ * in DOM order. Disabled stops are filtered out by the handler.
+ */
+const TAB_STOP_SELECTOR = '[data-tab-value],[data-tab-menu]';
+
+function preventFocus(e: React.MouseEvent) {
+ e.preventDefault();
+}
+
+/** Fraction of the visible strip an arrow press scrolls. */
+const SCROLL_PAGE_RATIO = 0.8;
+
+/**
+ * How a strip narrower than its tabs behaves.
+ *
+ * - `'auto'` — the component picks the strategy. Today that is always
+ * `'scroll'`.
+ * - `'scroll'` — the tabs scroll horizontally. Every tab stays a tab.
+ * - `'visible'` — no overflow handling: tabs keep their intrinsic widths and
+ * spill out of the strip, as they did before overflow existed.
+ */
+export type TabListOverflow = 'auto' | 'scroll' | 'visible';
+
+export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {
+ ref?: React.Ref<HTMLElement>;
+ /**
+ * The currently selected tab value.
+ */
+ value: string;
+ /**
+ * Callback fired when a tab is selected.
+ */
+ onChange: (value: string) => void;
+ /**
+ * Size of the tab hover targets. Uses the same element size tokens
+ * as Button and TextInput (`sm` = 28px, `md` = 32px, `lg` = 36px).
+ * @default 'md'
+ */
+ size?: TabListSize;
+ /**
+ * Layout mode for tab sizing.
+ * - `'hug'` (default): each tab hugs its content width.
+ * - `'fill'`: tabs stretch equally to fill the container width.
+ * @default 'hug'
+ */
+ layout?: 'hug' | 'fill';
+ /**
+ * Whether to show a bottom divider under the tab list.
+ * @default false
+ */
+ hasDivider?: boolean;
+ /**
+ * ARIA role for the strip.
+ *
+ * `"tablist"` asks for the WAI-ARIA tabs pattern: `role="tablist"` /
+ * `role="tab"` and `aria-selected`, with each tab pointing at the panel it
+ * controls via its `panelId`. Only tabs may live in a tablist strip, and a
+ * tab does not navigate — an `href` is ignored there.
+ *
+ * Left unset, the strip is a `<nav>` landmark marking the current tab with
+ * `aria-current`. Any other value is passed through to the element
+ * unchanged.
+ */
+ role?: AriaRole;
+ /**
+ * What happens when the tabs are wider than the strip.
+ *
+ * `'auto'` lets the component choose; today it always scrolls. `'scroll'`
+ * scrolls the tabs horizontally, with edge fades and — for pointers that
+ * can hover — arrow affordances. `'visible'` turns overflow handling off and
+ * lets the tabs spill out of the strip.
+ *
+ * The selected tab is always scrolled back into view.
+ * @default 'auto'
+ */
+ overflow?: TabListOverflow;
+ /**
+ * Tab and TabMenu children.
+ */
+ children: ReactNode;
+ /**
+ * PROPOSED — not in core.
+ *
+ * Hands the selected indicator to the strip: one bar, positioned over the
+ * selected tab and moved with `transform`, instead of the per-tab bars core
+ * cross-fades today. Each Tab keeps its own indicator in the tree but hidden
+ * (see `hasTravellingIndicator` in TabListContext), so exactly one is
+ * painted and layout is unchanged.
+ *
+ * Off by default: with the flag unset this component renders precisely what
+ * core renders, which is what makes the two panes of the Motion Lab
+ * comparison a diff rather than two different components.
+ *
+ * @default false
+ */
+ hasTravellingIndicator?: boolean;
+}
+
+/**
+ * A scroll container clips at its padding box, and two things a tab paints sit
+ * outside its own box: the focus ring (offset + width) and the selected
+ * indicator, which `--_tab-indicator-bottom` pushes further down when a
+ * divider rail is reserved. The strip pads by that much and takes the padding
+ * straight back off with a negative margin, so nothing is clipped and the tabs
+ * stay exactly where they were.
+ *
+ * A bleed is not free, though. The padding is real geometry: the strip's
+ * border box sticks out of the TabList's, and any ancestor that scrolls counts
+ * that as something to scroll to. So the ring's share of the bleed is taken
+ * only while a ring is actually drawn inside the strip -- the same
+ * `:has(:focus-visible)` condition that draws it -- and at rest the strip is
+ * exactly as wide and as tall as the TabList, as it was before the strip could
+ * scroll. The indicator's share is always taken, because the indicator is
+ * always drawn.
+ *
+ * Turning the bleed on moves nothing: padding and negative margin cancel, so
+ * the border box grows outwards and the content stays put.
+ */
+const RING_BLEED = `calc(${focusVars['--focus-outline-width']} + ${focusVars['--focus-outline-offset']})`;
+const BLEED_VAR = '--_tab-strip-bleed';
+const BLEED = `var(${BLEED_VAR})`;
+const INDICATOR_BLEED = 'calc(-1 * var(--_tab-indicator-bottom, -1px))';
+const BLOCK_END_BLEED = `max(${BLEED}, ${INDICATOR_BLEED})`;
+
+/** How far the edge fade runs; wide enough to sit under an arrow. */
+const FADE_WIDTH = spacingVars['--spacing-8'];
+
+/**
+ * Where the fade turns fully opaque, and — the same distance, for the same
+ * reason — how far a revealed stop is kept clear of the edge. Declared as
+ * scroll-padding so the browser's own focus scrolling uses it too, and read
+ * back from the computed style so the arithmetic below has one source of
+ * truth with the CSS.
+ */
+const SCROLL_EDGE_INSET = `calc(${BLEED} + ${FADE_WIDTH})`;
+
+/**
+ * The fade reaches transparent at the strip's *own* edge, not at the bleed
+ * edge — otherwise the scroll container paints tabs past the TabList's box,
+ * past a divider rail, and past the scroll arrow that caps that edge. Masking
+ * the bleed costs nothing: only a faded edge is masked, and a stop at a faded
+ * edge never holds focus, so the bleed is still there when the ring needs it.
+ */
+const FADE_FROM_START = `linear-gradient(to right, transparent ${BLEED}, black ${SCROLL_EDGE_INSET})`;
+const FADE_FROM_END = `linear-gradient(to left, transparent ${BLEED}, black ${SCROLL_EDGE_INSET})`;
+
+const styles = stylex.create({
+ nav: {
+ display: 'flex',
+ alignItems: 'stretch',
+ gap: spacingVars['--spacing-0-5'],
+ maxWidth: '100%',
+ minWidth: 0,
+ position: 'relative',
+ },
+ fill: {
+ width: '100%',
+ },
+ divider: {
+ borderBottomWidth: borderVars['--border-width'],
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ // Reserve a gap between the tabs and the divider rail so the hover pill
+ // (which fills the tab height) no longer touches the underline, and an
+ // adjacent same-size Button aligns to the tabs rather than butting the
+ // rail. The tabs keep their element-size height; this padding grows the
+ // strip. `--_tab-indicator-bottom` drops the selected indicator through
+ // the reserved gap (+ the 1px border) so it still sits on the rail.
+ paddingBlockEnd: spacingVars['--spacing-1'],
+ '--_tab-indicator-bottom': `calc(-1 * (${spacingVars['--spacing-1']} + ${borderVars['--border-width']}))`,
+ },
+ strip: {
+ display: 'flex',
+ alignItems: 'stretch',
+ // Inherited rather than restated so an `xstyle` gap override on the
+ // TabList still reaches the tabs.
+ gap: 'inherit',
+ flexGrow: 1,
+ flexShrink: 1,
+ minWidth: 0,
+ // Content-height, not stretched: the bleed padding below is inside the
+ // strip's own height, and a stretched height would push the tabs out of
+ // the scrollport.
+ alignSelf: 'flex-start',
+ },
+ stripScroll: {
+ overflowX: 'auto',
+ overflowY: 'hidden',
+ overscrollBehaviorX: 'contain',
+ scrollPaddingInline: SCROLL_EDGE_INSET,
+ scrollbarWidth: 'none',
+ scrollBehavior: {
+ default: 'smooth',
+ '@media (prefers-reduced-motion: reduce)': 'auto',
+ },
+ [BLEED_VAR]: {
+ default: '0px',
+ ':has(:focus-visible)': RING_BLEED,
+ },
+ paddingBlockStart: BLEED,
+ marginBlockStart: `calc(-1 * (${BLEED}))`,
+ paddingBlockEnd: BLOCK_END_BLEED,
+ marginBlockEnd: `calc(-1 * (${BLOCK_END_BLEED}))`,
+ paddingInline: BLEED,
+ marginInline: `calc(-1 * (${BLEED}))`,
+ maskImage: 'none',
+ transitionProperty: 'mask-image',
+ transitionDuration: {
+ default: durationVars['--duration-medium'],
+ '@media (prefers-reduced-motion: reduce)': '0ms',
+ },
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ fadeStart: {
+ maskImage: {
+ default: FADE_FROM_START,
+ ':is([dir="rtl"] *)': FADE_FROM_END,
+ },
+ },
+ fadeEnd: {
+ maskImage: {
+ default: FADE_FROM_END,
+ ':is([dir="rtl"] *)': FADE_FROM_START,
+ },
+ },
+ fadeBoth: {
+ maskImage: `linear-gradient(to right, transparent ${BLEED}, black ${SCROLL_EDGE_INSET}, black calc(100% - ${SCROLL_EDGE_INSET}), transparent calc(100% - ${BLEED}))`,
+ },
+ arrow: {
+ position: 'absolute',
+ insetBlockStart: 0,
+ // A pointer-only affordance: keyboard and assistive-technology users move
+ // through the strip with the arrow keys, which scrolls the focused tab
+ // into view on its own.
+ display: {
+ default: 'none',
+ '@media (hover: hover)': 'flex',
+ },
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ borderRadius: radiusVars['--radius-full'],
+ // Opaque, because it sits over the tabs it scrolls: the strip's edge fade
+ // thins the content underneath but does not clear it.
+ backgroundColor: colorVars['--color-background-popover'],
+ boxShadow: shadowVars['--shadow-low'],
+ color: {
+ default: colorVars['--color-text-secondary'],
+ ':hover:where(:not(:disabled,[aria-disabled="true"]))':
+ colorVars['--color-text-primary'],
+ },
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled,[aria-disabled="true"])': 'default',
+ },
+ },
+ arrowStart: {
+ insetInlineStart: 0,
+ },
+ arrowEnd: {
+ insetInlineEnd: 0,
+ },
+
+ // ===========================================================================
+ // PROPOSED — not in core. The strip-owned travelling indicator.
+ // ===========================================================================
+
+ /**
+ * The strip becomes the containing block for the indicator. Deliberately the
+ * strip and not the `<nav>` wrapper: the strip is the scroll container, so an
+ * indicator positioned against it scrolls with the tabs it is pointing at
+ * rather than sliding off them.
+ */
+ stripPositioned: {
+ position: 'relative',
+ },
+ travellingIndicator: {
+ position: 'absolute',
+ // The same custom property the per-tab indicator reads, so a divider rail
+ // (`hasDivider`, or a Toolbar with a bottom divider) drops this bar onto
+ // the rail exactly as it drops core's.
+ bottom: 'var(--_tab-indicator-bottom, -1px)',
+ // Physical `left`, not `insetInlineStart`: the offset below is a physical
+ // `getBoundingClientRect()` delta, and translateX is a physical axis. Under
+ // RTL a logical anchor would flip the origin out from under a delta that
+ // did not flip, and the bar would travel the wrong way.
+ left: 0,
+ height: '2px',
+ borderRadius: radiusVars['--radius-full'],
+ backgroundColor: colorVars['--color-accent'],
+ // A 2px decoration lying across the bottom of every tab: without this it
+ // would swallow clicks along that edge.
+ pointerEvents: 'none',
+ // The move curve, not an entry curve. An entry curve (an accent on
+ // arrival) is for something appearing — it earns attention for a thing the
+ // eye has not seen yet. This bar is already on screen and already has the
+ // eye; what it owes the viewer is a legible *path* from the old tab to the
+ // new one, so the standard easing carries it and nothing accents the end.
+ // The whole point of the proposal is that the eye follows the bar instead
+ // of re-finding it, and an arrival accent would put the emphasis back on
+ // the destination.
+ transitionProperty: 'transform, width',
+ transitionDuration: {
+ default: durationVars['--duration-medium-min'],
+ '@media (prefers-reduced-motion: reduce)': '0.01s',
+ },
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ /**
+ * The one thing a strip-owned bar has to pay for that a per-tab bar does
+ * not: its containing block is the strip's *padding* box, and a scrolling
+ * strip pads itself (see RING_BLEED above) to keep the focus ring and the
+ * indicator from being clipped. So the anchors have to give that padding
+ * back, in the strip's own terms:
+ *
+ * - `bottom` adds the block-end bleed, which puts the bar exactly where
+ * core's per-tab bar sits — flush with the padding edge, and therefore not
+ * clipped by `overflow-y: hidden`. Without this the bar sits a bleed lower
+ * and the scrollport shaves the bottom half off it.
+ * - `left` moves the origin from the padding edge to the content edge, the
+ * same place the measurement below reckons from.
+ *
+ * Both terms are zero at rest, so this changes nothing about where the bar
+ * normally is. They exist because the bleed is not constant: it grows while
+ * a focus ring is drawn inside the strip. Tracked here in CSS rather than
+ * re-measured in JS so the correction lands in the same style recalculation
+ * as the padding it cancels — a JS correction would arrive a frame later and
+ * the bar would visibly slide a few pixels every time the strip took focus.
+ */
+ travellingIndicatorBleed: {
+ bottom: `calc(var(--_tab-indicator-bottom, -1px) + ${BLOCK_END_BLEED})`,
+ left: BLEED,
+ },
+ /**
+ * Before the first measurement the bar has no position worth showing, so it
+ * is not shown. Transitions are off here as well as opacity: the first
+ * measurement writes the transform while this variant is still applied, and
+ * a transition would animate that write — the bar would slide in from the
+ * strip's left edge on mount, an entrance the proposal never claimed.
+ */
+ travellingIndicatorHidden: {
+ opacity: 0,
+ transitionProperty: 'none',
+ },
+});
+
+/**
+ * PROPOSED — not in core.
+ *
+ * How far the bar is inset from each side of the tab it marks. Matches the
+ * per-tab indicator, which is inset by `--spacing-3` at both ends
+ * (`insetInlineStart`/`insetInlineEnd` on `indicator` in Tab.tsx) so the bar
+ * spans the label rather than the tab's full hover target. Read here as a
+ * number because the placement is arithmetic on measured pixels, not CSS.
+ */
+const TRAVELLING_INDICATOR_INSET = 12;
+
+/**
+ * PROPOSED — not in core.
+ *
+ * The selected tab, under either ARIA pattern the component supports: a
+ * `role="tablist"` strip marks it with `aria-selected`, a `<nav>` strip with
+ * `aria-current` (`"true"` today, `"page"` accepted because a caller may set
+ * it by hand on a link tab). Matching only one of these would leave the
+ * indicator stranded in the other half of the component's API.
+ */
+const SELECTED_TAB_SELECTOR =
+ '[aria-selected="true"], [aria-current="page"], [aria-current="true"]';
+
+const arrowSizeStyles = stylex.create({
+ sm: {
+ width: sizeVars['--size-element-sm'],
+ height: sizeVars['--size-element-sm'],
+ },
+ md: {
+ width: sizeVars['--size-element-md'],
+ height: sizeVars['--size-element-md'],
+ },
+ lg: {
+ width: sizeVars['--size-element-lg'],
+ height: sizeVars['--size-element-lg'],
+ },
+});
+
+/**
+ * Tab navigation wrapper. Provides context for value/onChange/size
+ * to Tab and TabMenu children.
+ *
+ * @example
+ * ```
+ * <TabList value={activeTab} onChange={setActiveTab}>
+ * <Tab value="home" label="Home" />
+ * <Tab value="settings" label="Settings" />
+ * <TabMenu label="More">
+ * <Tab value="analytics" label="Analytics" />
+ * <Tab value="reports" label="Reports" />
+ * </TabMenu>
+ * </TabList>
+ * ```
+ */
+export function TabList({
+ ref,
+ value,
+ onChange,
+ size: sizeProp,
+ layout = 'hug',
+ hasDivider = false,
+ role,
+ overflow = 'auto',
+ hasTravellingIndicator = false,
+ xstyle,
+ className,
+ style,
+ children,
+ onKeyDown: onKeyDownProp,
+ onFocus: onFocusProp,
+ onBlur: onBlurProp,
+ 'aria-label': ariaLabelFromProps,
+ 'aria-labelledby': ariaLabelledBy,
+ 'aria-orientation': _ariaOrientation,
+ [EDGE_COMP_ATTR]: _edgeCompAttr,
+ ...restProps
+}: TabListProps) {
+ const t = useTranslator();
+ const ariaLabel = ariaLabelFromProps ?? t('@astryx.tabList.label');
+ const size = useSize(sizeProp, 'md');
+ const hasScroll = overflow !== 'visible';
+
+ const stripRef = useRef<HTMLDivElement | null>(null);
+ // Only an asserted `role="tablist"` switches the pattern. Left unset the
+ // strip is the `<nav>` it has always been, and every other role passes
+ // through to the element untouched.
+ const isTabList = role === 'tablist';
+
+ // Roving-tabindex keyboard navigation across the tab strip via the shared
+ // hook. Under the navigation pattern `orientation: 'both'` accepts both
+ // arrow axes per the WAI-ARIA APG allowance for tab strips
+ // (ArrowRight/ArrowDown advance, ArrowLeft/ArrowUp retreat). A tablist
+ // reports itself as horizontal, so there the strip takes only the
+ // horizontal arrows and leaves ArrowUp and ArrowDown to scroll the page. We
+ // do not set `aria-orientation` on the `<nav>`: that attribute is invalid on
+ // the navigation role and triggers an axe `aria-allowed-attr` violation.
+ //
+ // `hasRovingTabIndex` makes the hook own the single tab stop: it stamps
+ // tabindex 0/-1, repairs the stop on mount and as stops mount/unmount or
+ // toggle disabled, and -- via `handleFocus` on the nav -- keeps the stop in
+ // sync after clicks or programmatic focus. Individual Tabs still render
+ // `tabIndex={isSelected ? 0 : -1}` (see Tab.tsx) as the initial source of
+ // truth; the hook's repair preserves an existing tab stop and only promotes
+ // the first enabled stop when none is tabbable.
+ const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLElement>({
+ itemSelector: TAB_STOP_SELECTOR,
+ orientation: isTabList ? 'horizontal' : 'both',
+ hasRovingTabIndex: true,
+ });
+
+ const {
+ hintElement,
+ onKeyDown: onHintKeyDown,
+ onFocus: onHintFocus,
+ onBlur: onHintBlur,
+ } = useKeyboardHint();
+
+ const {scrollRef, overflowStart, overflowEnd} = useScrollOverflow();
+
+ const attachStrip = useCallback(
+ (el: HTMLDivElement | null) => {
+ stripRef.current = el;
+ scrollRef(hasScroll ? el : null);
+ },
+ [hasScroll, scrollRef],
+ );
+
+ const revealStop = useCallback(
+ (stop: HTMLElement | null) => {
+ const strip = stripRef.current;
+ if (!hasScroll || !strip || !stop) {
+ return;
+ }
+ const stripBox = strip.getBoundingClientRect();
+ const stopBox = stop.getBoundingClientRect();
+ const inset = parseFloat(getComputedStyle(strip).scrollPaddingLeft) || 0;
+ const pastEnd = stopBox.right - (stripBox.right - inset);
+ const pastStart = stopBox.left - (stripBox.left + inset);
+ // A stop wider than the space kept clear cannot be shown whole, so show
+ // its reading start, the way `scrollIntoView({inline: 'nearest'})` does.
+ const tooWide = stopBox.width > stripBox.width - 2 * inset;
+ const delta = tooWide
+ ? isRtlElement(strip)
+ ? pastEnd
+ : pastStart
+ : pastEnd > 0
+ ? pastEnd
+ : pastStart < 0
+ ? pastStart
+ : 0;
+ if (delta !== 0) {
+ // Not an animation: the strip has to arrive already showing the right
+ // tab, so this overrides the CSS smooth behaviour arrow presses use.
+ strip.scrollBy({left: delta, behavior: 'instant'});
+ }
+ },
+ [hasScroll],
+ );
+
+ const revealSelectedTab = useCallback(() => {
+ const strip = stripRef.current;
+ if (!strip) {
+ return;
+ }
+ revealStop(
+ Array.from(strip.querySelectorAll<HTMLElement>('[data-tab-value]')).find(
+ el => el.dataset.tabValue === value,
+ ) ?? null,
+ );
+ }, [revealStop, value]);
+
+ // Both reveals below reach the callback through a ref instead of depending
+ // on it: its identity also changes with `overflow`, and that is not a reason
+ // to scroll anything.
+ const revealSelectedTabRef = useRef(revealSelectedTab);
+ useEffect(() => {
+ revealSelectedTabRef.current = revealSelectedTab;
+ }, [revealSelectedTab]);
+
+ // The tab you are on has to be visible. Selection can move without focus —
+ // on mount, or when the host sets `value` itself — and neither scrolls the
+ // strip the way clicking or arrowing to a tab does. The check is what makes
+ // a selection change the trigger, rather than the effect happening to run.
+ const revealedValueRef = useRef<string | null>(null);
+ useEffect(() => {
+ if (revealedValueRef.current === value) {
+ return;
+ }
+ revealedValueRef.current = value;
+ revealSelectedTabRef.current();
+ }, [value]);
+
+ // ...and it has to stay visible when the strip is what moved. A strip that
+ // fitted at one width can hide the selected tab at a narrower one, and no
+ // prop changes when that happens. This one re-reveals the same selection by
+ // design, which is why the check above sits in the effect rather than in
+ // `revealSelectedTab`.
+ //
+ // The wrapper is observed rather than the strip because the shared observer
+ // keeps one callback per element and `useScrollOverflow` already holds the
+ // strip's.
+ useEffect(() => {
+ const root = listRef.current;
+ if (!hasScroll || !root) {
+ return;
+ }
+ const onResize = () => revealSelectedTabRef.current();
+ observeResize(root, onResize);
+ return () => unobserveResize(root);
+ }, [hasScroll, listRef]);
+
+ const scrollByPage = useCallback((direction: -1 | 1) => {
+ const strip = stripRef.current;
+ if (!strip) {
+ return;
+ }
+ // Under RTL the scroll axis is inverted, so flip the physical delta.
+ const rtlSign = isRtlElement(strip) ? -1 : 1;
+ strip.scrollBy({
+ left: rtlSign * direction * strip.clientWidth * SCROLL_PAGE_RATIO,
+ });
+ }, []);
+
+ const scrollToStart = useCallback(() => scrollByPage(-1), [scrollByPage]);
+ const scrollToEnd = useCallback(() => scrollByPage(1), [scrollByPage]);
+
+ const contextValue = useMemo(
+ () => ({
+ value,
+ onChange,
+ size,
+ layout,
+ pattern: isTabList ? ('tabs' as const) : ('nav' as const),
+ // PROPOSED — not in core. Tells each Tab to keep its own indicator in the
+ // tree but hidden, so the strip's single bar is the only one painted.
+ hasTravellingIndicator,
+ }),
+ [value, onChange, size, layout, isTabList, hasTravellingIndicator],
+ );
+
+ const handleRootKeyDown = useCallback(
+ (e: React.KeyboardEvent<HTMLElement>) => {
+ onKeyDownProp?.(e);
+ if (e.defaultPrevented) {
+ return;
+ }
+ onHintKeyDown(e);
+ handleKeyDown(e);
+ },
+ [onKeyDownProp, onHintKeyDown, handleKeyDown],
+ );
+
+ const handleRootFocus = useCallback(
+ (e: React.FocusEvent<HTMLElement>) => {
+ onFocusProp?.(e);
+ if (e.defaultPrevented) {
+ return;
+ }
+ onHintFocus(e);
+ handleFocus(e);
+ // The browser scrolls a focused element into view only when it is
+ // entirely outside the scrollport, so arrowing onto a half-visible stop
+ // leaves it cut off under the fade. Finish the job it started.
+ revealStop(e.target.closest(TAB_STOP_SELECTOR));
+ },
+ [onFocusProp, onHintFocus, handleFocus, revealStop],
+ );
+
+ const handleRootBlur = useCallback(
+ (e: React.FocusEvent<HTMLElement>) => {
+ onBlurProp?.(e);
+ if (e.defaultPrevented) {
+ return;
+ }
+ onHintBlur(e);
+ },
+ [onBlurProp, onHintBlur],
+ );
+
+ // `role="tablist"` owns only tabs, so anything else in the strip is invalid
+ // markup. Dev-only, and only under the asserted role — nothing else in the
+ // component reads the rendered DOM.
+ const hasWarnedContentRef = useRef(false);
+ useEffect(() => {
+ const strip = stripRef.current;
+ if (
+ process.env.NODE_ENV === 'production' ||
+ !isTabList ||
+ !strip ||
+ hasWarnedContentRef.current
+ ) {
+ return;
+ }
+ const stranger = Array.from(strip.children).find(
+ child =>
+ child.getAttribute('role') !== 'tab' &&
+ // PROPOSED — not in core. The travelling indicator lives in the strip
+ // but is `aria-hidden`, so it is not in the accessibility tree and the
+ // tablist does not own it. Without this the fork would warn about its
+ // own decoration on every mount.
+ child.getAttribute('aria-hidden') !== 'true',
+ );
+ if (stranger) {
+ hasWarnedContentRef.current = true;
+ devWarn(
+ 'TabList',
+ `role="tablist" owns only tabs, but the strip contains a <${stranger.tagName.toLowerCase()}> that is not one. ` +
+ 'Render menus and other controls outside the strip, or drop the role for the navigation pattern.',
+ );
+ }
+ // No dependency list: the check is on rendered DOM, which can change
+ // without any prop this component could watch.
+ });
+
+ // ===========================================================================
+ // PROPOSED — not in core. One indicator, owned by the strip.
+ // ===========================================================================
+
+ const travellingIndicatorRef = useRef<HTMLSpanElement | null>(null);
+ // The bar has nowhere sensible to be until it has been measured once, so it
+ // renders hidden and reveals itself on the first successful placement.
+ const [isIndicatorMeasured, setIsIndicatorMeasured] = useState(false);
+
+ /**
+ * Why the position is read out of the DOM instead of tracked in React state:
+ * there is no state to track. A tab's geometry is not a prop of anything —
+ * the tabs size themselves from their own content, so `layout="fill"`
+ * redistributing width, a webfont swapping in and re-measuring every label,
+ * a container query narrowing the strip, or the strip simply being scrolled
+ * all move the target while React renders nothing at all. Anything derived
+ * from props would be stale for exactly the cases the indicator most needs
+ * to be right about, so the measurement is the source of truth and the
+ * effect writes it straight onto the element.
+ *
+ * That is also why the cost below is real and worth naming: a
+ * `ResizeObserver` on the strip is the ONE thing this proposal adds that
+ * core does not already pay. Everything else is a style swap. It is one
+ * observer per TabList, it fires only when the strip's box actually changes,
+ * and its callback is two `getBoundingClientRect()` reads and two style
+ * writes — but a reviewer should be pricing it deliberately, not
+ * discovering it. (Core's own resize handling can't be reused here: the
+ * shared observer keeps a single callback per element and `useScrollOverflow`
+ * already holds the strip's.)
+ *
+ * `useEffect`, deliberately, not `useLayoutEffect`: the sandbox statically
+ * prerenders every route, and a layout effect warns on the server. Nothing
+ * is lost by running a frame later, because the bar is hidden until the
+ * first measurement lands — there is no pre-paint position to correct.
+ */
+ useEffect(() => {
+ const strip = stripRef.current;
+ const indicator = travellingIndicatorRef.current;
+ if (!hasTravellingIndicator || !strip || !indicator) {
+ return;
+ }
+
+ const place = () => {
+ const selected = strip.querySelector<HTMLElement>(SELECTED_TAB_SELECTOR);
+ if (!selected) {
+ // Nothing is selected — a valid state for the navigation pattern —
+ // so there is nothing to point at. Hide rather than leave the bar
+ // stranded under whichever tab was selected last.
+ setIsIndicatorMeasured(false);
+ return;
+ }
+ const stripBox = strip.getBoundingClientRect();
+ const tabBox = selected.getBoundingClientRect();
+ // Both rects are viewport coordinates, so their delta is where the tab
+ // sits on screen. Two corrections turn that into the coordinate the
+ // indicator is laid out in:
+ //
+ // - `scrollLeft`, because the indicator is a child of the strip, which
+ // is the scroll container: it lives in the strip's *content*
+ // coordinates and scrolls with the tabs. Without this the bar would be
+ // right only at scrollLeft 0 and drift by the scroll distance.
+ // - the strip's inline padding, because the rect is measured to the
+ // padding edge while the bar is anchored to the content edge (see
+ // `travellingIndicatorBleed`). Zero at rest; non-zero exactly while a
+ // focus ring is drawn inside the strip.
+ const padStart = parseFloat(getComputedStyle(strip).paddingLeft) || 0;
+ const offset =
+ tabBox.left -
+ stripBox.left -
+ padStart +
+ strip.scrollLeft +
+ TRAVELLING_INDICATOR_INSET;
+ // Clamped: a tab narrower than its own padding would otherwise ask for a
+ // negative width, which is invalid CSS and drops the declaration.
+ const width = Math.max(0, tabBox.width - TRAVELLING_INDICATOR_INSET * 2);
+ indicator.style.width = `${width}px`;
+ indicator.style.transform = `translateX(${offset}px)`;
+ setIsIndicatorMeasured(true);
+ };
+
+ place();
+
+ const observer = new ResizeObserver(place);
+ observer.observe(strip);
+ return () => observer.disconnect();
+ // `children` is here because a tab added, removed, or relabelled moves the
+ // target with no other signal — the same reason the position is measured
+ // rather than derived. It re-subscribes the observer more often than
+ // strictly needed (JSX hands back a fresh `children` each render), which is
+ // cheap: `observe()` on an already-measured element costs one extra
+ // idempotent `place()` on the next frame.
+ }, [hasTravellingIndicator, value, children]);
+
+ const fadeStyle = !hasScroll
+ ? null
+ : overflowStart && overflowEnd
+ ? styles.fadeBoth
+ : overflowStart
+ ? styles.fadeStart
+ : overflowEnd
+ ? styles.fadeEnd
+ : null;
+
+ // A tablist is not navigation, so the landmark element is only right under
+ // the navigation pattern. The role is fixed by a prop rather than by what
+ // the strip happens to hold, so this is settled once at the callsite.
+ const Wrapper = isTabList ? 'div' : 'nav';
+
+ return (
+ <TabListContext value={contextValue}>
+ <Wrapper
+ ref={useMergedRefs(ref, listRef)}
+ {...restProps}
+ role={isTabList ? undefined : role}
+ aria-label={isTabList ? undefined : ariaLabel}
+ aria-labelledby={isTabList ? undefined : ariaLabelledBy}
+ onKeyDown={handleRootKeyDown}
+ onFocus={handleRootFocus}
+ onBlur={handleRootBlur}
+ {...{[EDGE_COMP_ATTR]: ''}}
+ {...mergeProps(
+ themeProps('tab-list', {size}),
+ stylex.props(
+ styles.nav,
+ layout === 'fill' && styles.fill,
+ hasDivider && styles.divider,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ <div
+ ref={attachStrip}
+ role={isTabList ? 'tablist' : undefined}
+ aria-label={isTabList ? ariaLabel : undefined}
+ // The name belongs to whichever element carries the widget role.
+ aria-labelledby={isTabList ? ariaLabelledBy : undefined}
+ {...mergeProps(
+ themeProps('tab-strip'),
+ stylex.props(
+ styles.strip,
+ hasScroll && styles.stripScroll,
+ fadeStyle,
+ // PROPOSED — not in core. The containing block for the bar below.
+ hasTravellingIndicator && styles.stripPositioned,
+ ),
+ )}>
+ {children}
+ {/*
+ PROPOSED — not in core. The single indicator, owned by the strip
+ rather than by each Tab, so selection moves it instead of
+ cross-fading two of them. Inside the strip because the strip is
+ what scrolls: an indicator outside it would slide off the tab it
+ marks the moment the strip scrolled. Purely decorative and
+ `aria-hidden` — selection is already stated by `aria-selected` /
+ `aria-current` on the tab itself, and this bar must not add a
+ second, contradictory voice.
+ */}
+ {hasTravellingIndicator && (
+ <span
+ ref={travellingIndicatorRef}
+ aria-hidden="true"
+ {...mergeProps(
+ themeProps('tab-travelling-indicator'),
+ stylex.props(
+ styles.travellingIndicator,
+ hasScroll && styles.travellingIndicatorBleed,
+ !isIndicatorMeasured && styles.travellingIndicatorHidden,
+ ),
+ )}
+ />
+ )}
+ </div>
+ {hasScroll && overflowStart && (
+ <button
+ type="button"
+ aria-hidden="true"
+ tabIndex={-1}
+ // Nothing hidden from assistive technology should end up holding
+ // focus, and a click would put it here.
+ onMouseDown={preventFocus}
+ onClick={scrollToStart}
+ {...mergeProps(
+ themeProps('tab-scroll-button'),
+ focusOutlineProps.focusVisible(
+ styles.arrow,
+ styles.arrowStart,
+ arrowSizeStyles[size],
+ ),
+ )}>
+ <Icon
+ icon="chevronLeft"
+ size="sm"
+ color="inherit"
+ xstyle={rtlStyles.mirror}
+ />
+ </button>
+ )}
+ {hasScroll && overflowEnd && (
+ <button
+ type="button"
+ aria-hidden="true"
+ tabIndex={-1}
+ onMouseDown={preventFocus}
+ onClick={scrollToEnd}
+ {...mergeProps(
+ themeProps('tab-scroll-button'),
+ focusOutlineProps.focusVisible(
+ styles.arrow,
+ styles.arrowEnd,
+ arrowSizeStyles[size],
+ ),
+ )}>
+ <Icon
+ icon="chevronRight"
+ size="sm"
+ color="inherit"
+ xstyle={rtlStyles.mirror}
+ />
+ </button>
+ )}
+ {hintElement}
+ </Wrapper>
+ </TabListContext>
+ );
+}
+
+TabList.displayName = 'TabList';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabListContext.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabListContext.ts
new file mode 100644
index 0000000000..0ba6e464d4
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabListContext.ts
@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TabListContext.ts
+ * @input React createContext, use
+ * @output Exports TabListContext, useTabListContext, TabListPattern
+ * @position Context provider; consumed by Tab.tsx, TabMenu.tsx
+ *
+ * SYNC: When modified, update /packages/core/src/TabList/TabList.doc.mjs
+ *
+ * MOTION LAB FORK — see ./index.ts. The one change here is the optional
+ * `hasTravellingIndicator` field on `TabListContextValue`. Marked PROPOSED.
+ */
+
+import {createContext, use} from 'react';
+
+/**
+ * Size variants for tab list items.
+ * Uses hardcoded px values (sizeVars not available on this branch).
+ */
+export type TabListSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Layout mode for tab sizing.
+ * - `'hug'`: each tab hugs its content width.
+ * - `'fill'`: tabs stretch equally to fill the container width.
+ */
+export type TabListLayout = 'hug' | 'fill';
+
+/**
+ * ARIA pattern the strip resolved to.
+ * - `'nav'`: a `<nav>` of links or buttons, current item marked with
+ * `aria-current`.
+ * - `'tabs'`: the WAI-ARIA tabs pattern — `role="tablist"` / `role="tab"`,
+ * `aria-selected`, and `aria-controls` for the panel each tab owns.
+ */
+export type TabListPattern = 'nav' | 'tabs';
+
+/**
+ * Context for communicating value/onChange/size/layout and the resolved ARIA
+ * pattern from TabList to children.
+ */
+export interface TabListContextValue {
+ value: string;
+ onChange: (value: string) => void;
+ size: TabListSize;
+ layout: TabListLayout;
+ pattern: TabListPattern;
+ /**
+ * PROPOSED — not in core.
+ *
+ * Set by a TabList rendering the single travelling indicator itself. The
+ * strip owns one indicator that slides between tabs, so each Tab has to stop
+ * drawing the one it owns today or the two stack: the per-tab indicator
+ * stays in the tree (layout is unchanged) but is hidden.
+ *
+ * Optional, and read as falsy everywhere else, so a Tab under core's TabList
+ * — or under this one with the prop off — behaves exactly as it does today.
+ */
+ hasTravellingIndicator?: boolean;
+}
+
+export const TabListContext = createContext<TabListContextValue | null>(null);
+TabListContext.displayName = 'TabListContext';
+
+/**
+ * Returns TabListContext value or throws if used outside TabList.
+ */
+export function useTabListContext(): TabListContextValue {
+ const ctx = use(TabListContext);
+ if (ctx == null) {
+ throw new Error(
+ 'useTabListContext must be used within TabList. ' +
+ 'Wrap your Tab/TabMenu in <TabList>.',
+ );
+ }
+ return ctx;
+}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabMenu.tsx b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabMenu.tsx
new file mode 100644
index 0000000000..ab39effb98
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/TabMenu.tsx
@@ -0,0 +1,460 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TabMenu.tsx
+ * @input Uses React, StyleX, usePopover, TabListContext
+ * @output Exports TabMenu component, TabMenuProps type, TabMenuOption type
+ * @position Menu trigger button; opens dropdown of overflow menu items and
+ * mirrors selected tab indicator positioning
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/TabList/TabList.doc.mjs
+ * - /packages/core/src/TabList/index.ts
+ * - /packages/core/src/TabList/TabList.test.tsx
+ * - /packages/cli/assets/templates/blocks/components/TabList/ (showcase blocks)
+ */
+
+import React, {useCallback, useId, useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Icon} from '@astryxdesign/core/Icon';
+import {renderIconSlot, type IconType} from '@astryxdesign/core/Icon';
+import {
+ colorVars,
+ spacingVars,
+ sizeVars,
+ radiusVars,
+ durationVars,
+ easeVars,
+ fontWeightVars,
+ typeScaleVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import {focusOutlineProps} from '@astryxdesign/core/utils';
+import {usePopover} from '@astryxdesign/core/Popover';
+// SWIZZLE BUG: `MENU_ITEM_SELECTOR` is internal to DropdownMenu and is not
+// re-exported from the package, so the swizzler's rewrite to
+// '@astryxdesign/core/DropdownMenu' does not typecheck. Pointed at the package
+// source instead. See index.ts for the full list.
+import {MENU_ITEM_SELECTOR} from '../../../../../../../../../packages/core/src/DropdownMenu/menuItemRoles';
+import {useListFocus} from '@astryxdesign/core/hooks';
+import {useTabListContext} from './TabListContext';
+import type {TabListSize} from './TabListContext';
+import {tabScope} from './tab.markers.stylex';
+import {mergeProps} from '@astryxdesign/core/utils';
+import {useMergedRefs} from '@astryxdesign/core/hooks';
+import type {BaseProps} from '@astryxdesign/core/BaseProps';
+import {themeProps} from '@astryxdesign/core/utils';
+
+export interface TabMenuOption {
+ value: string;
+ label: string;
+ /**
+ * Icon to display before the label.
+ */
+ icon?: ReactNode | IconType;
+}
+
+export interface TabMenuProps extends Pick<
+ BaseProps<HTMLButtonElement>,
+ 'xstyle' | 'className' | 'style'
+> {
+ ref?: React.Ref<HTMLButtonElement>;
+ /**
+ * Label for the trigger button and dropdown heading.
+ * Displayed as trigger text when no option is selected.
+ */
+ label: string;
+ /**
+ * Menu options rendered in the dropdown.
+ */
+ options: TabMenuOption[];
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ trigger: {
+ position: 'relative',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-3'],
+ backgroundColor: 'transparent',
+ borderWidth: 0,
+ borderStyle: 'none',
+ borderRadius: radiusVars['--radius-element'],
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--text-label-size'],
+ lineHeight: typeScaleVars['--text-label-leading'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ color: colorVars['--color-text-secondary'],
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled,[aria-disabled="true"])': 'default',
+ },
+ textDecoration: 'none',
+ transitionProperty: 'color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ triggerSelected: {
+ color: colorVars['--color-text-primary'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ },
+ triggerLabel: {
+ position: 'relative',
+ display: 'inline-grid',
+ alignItems: 'center',
+ alignSelf: 'stretch',
+ },
+ triggerLabelText: {
+ gridRowStart: 1,
+ gridColumnStart: 1,
+ },
+ triggerLabelSizer: {
+ gridRowStart: 1,
+ gridColumnStart: 1,
+ visibility: 'hidden',
+ pointerEvents: 'none',
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ },
+ indicator: {
+ position: 'absolute',
+ // Mirrors Tab's indicator: sits on the bottom edge by default (-1px), or
+ // drops onto the divider rail when an ancestor (TabList `hasDivider` or a
+ // Toolbar with a bottom divider) sets `--_tab-indicator-bottom`.
+ bottom: 'var(--_tab-indicator-bottom, -1px)',
+ insetInlineStart: spacingVars['--spacing-3'],
+ insetInlineEnd: spacingVars['--spacing-3'],
+ height: '2px',
+ borderRadius: radiusVars['--radius-full'],
+ pointerEvents: 'none',
+ transitionProperty: 'opacity, background-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ indicatorSelected: {
+ backgroundColor: colorVars['--color-icon-primary'],
+ opacity: 1,
+ },
+ hoverBg: {
+ position: 'absolute',
+ inset: 0,
+ margin: 'auto',
+ width: '100%',
+ borderRadius: radiusVars['--radius-element'],
+ pointerEvents: 'none',
+ backgroundColor: {
+ default: 'transparent',
+ [stylex.when.ancestor(':hover', tabScope)]: {
+ '@media (hover: hover)': colorVars['--color-overlay-hover'],
+ },
+ },
+ transitionProperty: 'background-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ chevron: {
+ width: spacingVars['--spacing-4'],
+ height: spacingVars['--spacing-4'],
+ flexShrink: 0,
+ },
+ // Applied to the chevron <Icon> (via `xstyle`) rather than its wrapper, so the
+ // element that rotates is the element a theme targets.
+ chevronIcon: {
+ transitionProperty: 'transform',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ },
+ chevronOpen: {
+ transform: 'rotate(180deg)',
+ },
+ dropdown: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0-5'],
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-1'],
+ },
+ menuItem: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'space-between',
+ gap: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ borderRadius: radiusVars['--radius-element'],
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--text-label-size'],
+ lineHeight: typeScaleVars['--text-label-leading'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ color: colorVars['--color-text-primary'],
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled,[aria-disabled="true"])': 'default',
+ },
+ transitionProperty: 'background-color',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ backgroundColor: {
+ default: 'transparent',
+ ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
+ '@media (hover: hover)': colorVars['--color-overlay-hover'],
+ },
+ },
+ },
+ menuItemSelected: {
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ },
+ menuItemContent: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ },
+ itemCheckmark: {
+ flexShrink: 0,
+ width: 16,
+ height: 16,
+ color: colorVars['--color-icon-primary'],
+ },
+ menuHeading: {
+ fontSize: typeScaleVars['--text-supporting-size'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ color: colorVars['--color-text-secondary'],
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-3'],
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {height: sizeVars['--size-element-sm']},
+ md: {height: sizeVars['--size-element-md']},
+ lg: {height: sizeVars['--size-element-lg']},
+});
+
+// Hover bg uses the standard element size (one step smaller than tab)
+const hoverSizeStyles = stylex.create({
+ sm: {height: sizeVars['--size-element-sm']},
+ md: {height: sizeVars['--size-element-md']},
+ lg: {height: sizeVars['--size-element-lg']},
+});
+
+/**
+ * Tab menu trigger that opens a dropdown of additional tab options.
+ * Shows the selected option's label as trigger text when an option is active.
+ * Dropdown includes a heading showing the menu's label prop.
+ *
+ * @example
+ * ```
+ * <TabList value={tab} onChange={setTab}>
+ * <Tab value="overview" label="Overview" />
+ * <TabMenu label="More" options={[
+ * { value: "settings", label: "Settings" },
+ * { value: "history", label: "History" },
+ * ]} />
+ * </TabList>
+ * ```
+ */
+export function TabMenu({
+ ref,
+ label,
+ options,
+ xstyle,
+ className,
+ style,
+}: TabMenuProps) {
+ const tabListCtx = useTabListContext();
+ const menuId = useId();
+ const buttonRef = useRef<HTMLButtonElement>(null);
+
+ const popover = usePopover({
+ hasLightDismiss: true,
+ hasCloseButton: false,
+ hasAutoFocus: false,
+ // The popup's own role="menu" is the exposed semantics; a modal dialog
+ // wrapper would announce an unnamed dialog around the menu.
+ role: 'none',
+ // Return focus to the trigger when the menu closes (Escape, Tab, select,
+ // or light dismiss) so keyboard focus is never dropped to <body>.
+ onHide: useCallback(() => {
+ buttonRef.current?.focus();
+ }, []),
+ });
+
+ // The overflow menu is a composite widget: a single roving tab stop with
+ // arrow-key navigation between items, per the APG menu pattern. The hook owns
+ // item tabindex — items render tabIndex={-1} and exactly one is promoted to 0.
+ const {
+ listRef,
+ handleKeyDown: handleListKeyDown,
+ handleFocus,
+ focusFirst,
+ } = useListFocus<HTMLDivElement>({
+ hasRovingTabIndex: true,
+ // Options render as menuitemradio (single-select menu), which the
+ // default '[role="menuitem"]' selector would not match.
+ itemSelector: MENU_ITEM_SELECTOR,
+ onEscape: () => popover.hide(),
+ });
+
+ const handleToggle = useCallback(() => {
+ if (popover.isOpen) {
+ popover.hide();
+ } else {
+ popover.show();
+ // Move focus into the menu on open so arrow navigation works and the
+ // roving tab stop lands on a real item (APG menu-button focus-on-open).
+ requestAnimationFrame(() => focusFirst());
+ }
+ }, [popover, focusFirst]);
+
+ const handleMenuKeyDown = useCallback(
+ (e: React.KeyboardEvent) => {
+ // APG menu-button: Tab leaves the menu rather than walking its items.
+ // Close and let onHide return focus to the trigger, from which the
+ // browser's default Tab continues to the next element.
+ if (e.key === 'Tab') {
+ popover.hide();
+ return;
+ }
+ handleListKeyDown(e);
+ },
+ [handleListKeyDown, popover],
+ );
+
+ const selectedOption = options.find(o => o.value === tabListCtx.value);
+ const triggerLabel = selectedOption?.label ?? label;
+ const hasSelectedOption = selectedOption != null;
+
+ const size: TabListSize = tabListCtx.size;
+
+ const handleSelect = useCallback(
+ (value: string) => {
+ tabListCtx.onChange(value);
+ popover.hide();
+ },
+ [tabListCtx, popover],
+ );
+
+ const setButtonRef = useMergedRefs<HTMLButtonElement>(
+ popover.triggerRef,
+ buttonRef,
+ ref,
+ );
+
+ return (
+ <>
+ <button
+ ref={setButtonRef}
+ type="button"
+ aria-haspopup="menu"
+ aria-expanded={popover.isOpen}
+ aria-controls={menuId}
+ data-tab-menu=""
+ tabIndex={hasSelectedOption ? 0 : -1}
+ onClick={handleToggle}
+ {...mergeProps(
+ themeProps('tab-menu'),
+ focusOutlineProps.focusVisible(
+ styles.trigger,
+ sizeStyles[size],
+ hasSelectedOption && styles.triggerSelected,
+ tabScope,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ <span
+ aria-hidden="true"
+ {...stylex.props(styles.hoverBg, hoverSizeStyles[size])}
+ />
+ <span {...stylex.props(styles.triggerLabel)}>
+ <span {...stylex.props(styles.triggerLabelText)}>{triggerLabel}</span>
+ <span aria-hidden="true" {...stylex.props(styles.triggerLabelSizer)}>
+ {triggerLabel}
+ </span>
+ </span>
+ <span aria-hidden="true" {...stylex.props(styles.chevron)}>
+ <Icon
+ icon="chevronDown"
+ size="sm"
+ color="inherit"
+ xstyle={[styles.chevronIcon, popover.isOpen && styles.chevronOpen]}
+ />
+ </span>
+ {hasSelectedOption && (
+ <span
+ {...mergeProps(
+ themeProps('tab-indicator', {selected: 'selected'}),
+ stylex.props(styles.indicator, styles.indicatorSelected),
+ )}
+ />
+ )}
+ </button>
+ {popover.render(
+ <div
+ ref={listRef}
+ id={menuId}
+ role="menu"
+ aria-label={label}
+ onKeyDown={handleMenuKeyDown}
+ onFocus={handleFocus}
+ {...mergeProps(
+ themeProps('tab-menu-dropdown'),
+ stylex.props(styles.dropdown),
+ )}>
+ <span role="presentation" {...stylex.props(styles.menuHeading)}>
+ {label}
+ </span>
+ {options.map(option => {
+ const isSelected = tabListCtx.value === option.value;
+ return (
+ <div
+ key={option.value}
+ // The menu is single-select: exactly one option can be the
+ // active tab, so options are radio menu items with
+ // aria-checked (APG menu-button), not plain menuitems with
+ // aria-current.
+ role="menuitemradio"
+ tabIndex={-1}
+ aria-checked={isSelected}
+ onClick={() => handleSelect(option.value)}
+ onKeyDown={e => {
+ if (e.key === 'Enter' || e.key === ' ') {
+ e.preventDefault();
+ handleSelect(option.value);
+ }
+ }}
+ {...mergeProps(
+ themeProps('tab-menu-item'),
+ focusOutlineProps.focusVisible(
+ styles.menuItem,
+ isSelected && styles.menuItemSelected,
+ ),
+ )}>
+ <span {...stylex.props(styles.menuItemContent)}>
+ {option.icon &&
+ renderIconSlot(option.icon, {
+ size: 'sm',
+ color: 'secondary',
+ })}
+ {option.label}
+ </span>
+ {isSelected && <Icon icon="check" size="sm" color="accent" />}
+ </div>
+ );
+ })}
+ </div>,
+ {placement: 'below', alignment: 'start'},
+ )}
+ </>
+ );
+}
+
+TabMenu.displayName = 'TabMenu';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/index.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/index.ts
new file mode 100644
index 0000000000..afc301d54b
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/index.ts
@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from the forked TabList component files
+ * @output Exports TabList, Tab, TabMenu and their types
+ * @position Motion Lab fork of core's TabList, carrying ONE proposed change.
+ * Entry point for the lab's "after" pane.
+ *
+ * ===========================================================================
+ * WHAT THIS IS
+ * ===========================================================================
+ *
+ * `astryx swizzle TabList` against core, plus a single behavioural change, so
+ * the Motion Lab can mount the SAME component twice — core's, and
+ * core's-plus-the-proposal — and the visible difference between the two panes
+ * IS the diff. The previous "after" pane was hand-built HTML, which could
+ * demonstrate a motion but could not demonstrate that the motion was
+ * achievable in the component, at what cost, or without breaking anything
+ * else. This can.
+ *
+ * THE PROPOSAL. In core each `Tab` renders its own absolutely-positioned
+ * indicator and they transition `opacity, background-color`, so selection
+ * cross-fades: nothing travels, and the eye has to re-find the selection.
+ * Here the strip owns ONE indicator, positioned over the selected tab and
+ * moved with `transform` — it travels, and the eye follows it. Each Tab
+ * suppresses the indicator it draws for itself (kept in the tree, hidden) so
+ * the two do not stack.
+ *
+ * Opt-in via `hasTravellingIndicator` on TabList (default false). With the
+ * flag off this fork renders exactly what core renders, which is what makes
+ * the comparison a diff and not two different components.
+ *
+ * Every proposed line in these files is marked `PROPOSED`. Search for it to
+ * read the change on its own:
+ * - TabListContext.ts — `hasTravellingIndicator` on `TabListContextValue`
+ * - Tab.tsx — `indicatorSuppressed`, applied from the context flag
+ * - TabList.tsx — the prop, the styles, and the measuring effect
+ *
+ * ===========================================================================
+ * SWIZZLE BUG — report upstream
+ * ===========================================================================
+ *
+ * The swizzler rewrites core's relative imports to package specifiers, but it
+ * does that for internals the package does not export, so a freshly swizzled
+ * TabList does not typecheck. Two here, both repointed at package source with
+ * a relative path (see the `SWIZZLE BUG` comments at each import):
+ *
+ * - `isRtlElement` rewritten to '@astryxdesign/core/hooks'
+ * real file: packages/core/src/hooks/isRtlElement.ts
+ * used by TabList.tsx (RTL scroll direction)
+ * - `MENU_ITEM_SELECTOR` rewritten to '@astryxdesign/core/DropdownMenu'
+ * real file: packages/core/src/DropdownMenu/menuItemRoles.ts
+ * used by TabMenu.tsx (roving focus in the overflow menu)
+ *
+ * Either the swizzler should not rewrite an import the package cannot serve,
+ * or these two should join the public surface. Every other named import from
+ * those same modules resolves fine, so the fix is per-symbol, not per-module.
+ */
+
+// The lab mounts both: TabList carries the proposal's prop, Tab is what
+// suppresses its own indicator when the strip takes over.
+export {TabList} from './TabList';
+export type {TabListProps, TabListOverflow} from './TabList';
+
+export {Tab} from './Tab';
+export type {TabProps} from './Tab';
+
+export {TabMenu} from './TabMenu';
+export type {TabMenuProps, TabMenuOption} from './TabMenu';
+
+export {useTabListContext} from './TabListContext';
+export type {
+ TabListContextValue,
+ TabListSize,
+ TabListLayout,
+ TabListPattern,
+} from './TabListContext';
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/tab.markers.stylex.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/tab.markers.stylex.ts
new file mode 100644
index 0000000000..4d79da44d7
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/proposed/TabList/tab.markers.stylex.ts
@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Scoped marker for Tab ancestor selectors.
+ * Used by both Tab and TabMenu to scope hover background styles
+ * and ensure they don't leak from parent containers.
+ */
+export const tabScope = stylex.defineMarker();
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
index b56225baa7..e937ba585f 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/published/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/published/page.tsx
@@ -16,6 +16,7 @@
*/
import {Badge} from '@astryxdesign/core/Badge';
+import * as stylex from '@stylexjs/stylex';
import {Banner} from '@astryxdesign/core/Banner';
import {Button} from '@astryxdesign/core/Button';
import {Card} from '@astryxdesign/core/Card';
@@ -35,12 +36,22 @@ import {ComparePanes, DemoCard} from '../LabPrimitives';
import {LayerRig, LoopRig} from '../LabDemos';
import {LabPage} from '../PageFrame';
import {
+ CORRECTED_EXIT_RULE,
GUIDANCE_CONFLICTS,
+ SOURCES,
PUBLISHED_PAGE_URL,
PUBLISHED_SECTIONS,
type GuidanceConflict,
} from '../publishedGuidance';
+const sx = stylex.create({
+ quote: {
+ borderInlineStart: '2px solid var(--color-border)',
+ paddingInlineStart: '12px',
+ maxWidth: '62ch',
+ },
+});
+
type Severity = GuidanceConflict['severity'];
const SEVERITY: Record<
@@ -55,6 +66,11 @@ const SEVERITY: Record<
question:
'Two documents give opposite instructions. One of them has to move first.',
},
+ overreach: {
+ variant: 'warning',
+ question:
+ 'The proposal claims more than its own cited sources support, and the published text sits closer to them. Narrow the proposal rather than rewriting the page.',
+ },
extension: {
variant: 'warning',
question:
@@ -118,7 +134,7 @@ export default function PublishedGuidancePage() {
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.">
+ decides="Which proposals are bug fixes, which are reversals of published guidance, and which overreach their own sources.">
<Banner
status="error"
title={`${reversals.length} of the ${GUIDANCE_CONFLICTS.length} conflicts reverse published guidance`}
@@ -221,6 +237,46 @@ export default function PublishedGuidancePage() {
))}
<VStack gap={3}>
+ <Heading level={2}>Where the exit rules come from</Heading>
+ <Text color="secondary">
+ Two of the conflicts above are marked <em>overreach</em> rather than{' '}
+ <em>reversal</em>, which is a claim about evidence and so it should
+ show its working. The brief cites Emil Kowalski&rsquo;s animation
+ guidance and beUI as references, so those are the standard it can be
+ held to. Read against them the word &ldquo;exit&rdquo; comes apart
+ into two rules with very different support.
+ </Text>
+ <VStack gap={4}>
+ {SOURCES.map(entry => (
+ <Card key={entry.claim} variant="muted">
+ <VStack gap={2}>
+ <Text weight="semibold">{entry.claim}</Text>
+ {entry.support.map(sup => (
+ <VStack key={sup.source} gap={0.5}>
+ <Text type="supporting" color="secondary">
+ {sup.source}
+ </Text>
+ <Text {...stylex.props(sx.quote)}>
+ <em>&ldquo;{sup.says}&rdquo;</em>
+ </Text>
+ </VStack>
+ ))}
+ <Text type="supporting">{entry.verdict}</Text>
+ </VStack>
+ </Card>
+ ))}
+ </VStack>
+ <Banner
+ status="success"
+ title="The rule the sources actually support"
+ description={<Text>{CORRECTED_EXIT_RULE}</Text>}
+ endContent={
+ <AstryxLink href="/pages/motion-lab/exit-gap/">
+ Which surfaces that covers
+ </AstryxLink>
+ }
+ />
+
<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.`}
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/publishedGuidance.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/publishedGuidance.ts
index 91f99264ad..f2da8feb55 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/publishedGuidance.ts
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/publishedGuidance.ts
@@ -12,10 +12,12 @@
* 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.
+ * Two of the proposals here are genuine reversals — the docs and the proposal
+ * cannot both stand, and a human has to pick. But the exit rule is a third
+ * thing, and worth separating from them: checked against the sources the brief
+ * itself cites, the published paragraph is the better-supported statement and
+ * the proposal is the one that overreached. See SOURCES below. That is not a
+ * decision to be made; it is a claim to be narrowed.
*
* Quotes are verbatim from the page as published, so they can be diffed
* against it later.
@@ -31,13 +33,89 @@ export type GuidanceConflict = {
readonly reading: string;
/** What has to happen for the proposal to be legitimate. */
readonly resolution: string;
- readonly severity: 'reversal' | 'extension' | 'aligned';
+ /**
+ * reversal — docs and proposal conflict; a human picks one.
+ * overreach — the proposal claims more than its own sources support, and the
+ * published text is closer to them. Narrow the proposal.
+ * extension — the proposal adds something the page leaves out.
+ * aligned — same rule, said twice.
+ */
+ readonly severity: 'reversal' | 'overreach' | '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';
+/**
+ * Where the exit rules actually come from.
+ *
+ * The brief cites Emil Kowalski's animation guidance and beUI as its
+ * references, so they are the standard it can be held to. Read against them,
+ * the two halves of "exit" come apart: direction is unanimous, timing is not.
+ */
+export const SOURCES: ReadonlyArray<{
+ readonly claim: string;
+ readonly support: ReadonlyArray<{
+ readonly source: string;
+ readonly says: string;
+ }>;
+ readonly verdict: string;
+}> = [
+ {
+ claim: 'An exit should retrace the entrance path.',
+ support: [
+ {
+ source: 'Astryx, Movement Principles',
+ says: 'When you do animate exit, match the entrance. A panel that slides in from the right should slide back out to the right.',
+ },
+ {
+ source: 'Emil Kowalski, animation guidance',
+ says: 'Exit the way it entered.',
+ },
+ ],
+ verdict:
+ 'Unanimous, and the published page already says it. This half of the rule is safe to enforce.',
+ },
+ {
+ claim: 'An exit should be shorter than its entrance.',
+ support: [
+ {
+ source: 'beUI, motion guidance',
+ says: 'Let old content leave faster than new content arrives.',
+ },
+ {
+ source: 'Emil Kowalski, animation guidance',
+ says: 'Asymmetric timing, argued around deliberate actions versus system responses — not as a universal rule.',
+ },
+ ],
+ verdict:
+ 'One source states it plainly; the other scopes it to a distinction the brief drops. Nothing supports it as a law that applies to every exit, which is how the token mapping encodes it.',
+ },
+ {
+ claim: 'Every presence surface should animate out.',
+ support: [
+ {
+ source: 'Emil Kowalski, animation guidance',
+ says: 'High-frequency UI often should not animate its exit at all.',
+ },
+ {
+ source: 'Astryx, Movement Principles',
+ says: 'Elements the user is moving away from \u2014 tooltips, hover cards, and dropdown menus \u2014 can disappear instantly. The user has already shifted their attention.',
+ },
+ ],
+ verdict:
+ 'Both sources say the opposite of the proposal, and one of them is the brief\u2019s own reference. Criterion 7 as written is not supported by anything cited.',
+ },
+];
+
+/**
+ * The rule the sources actually support, as opposed to the one the brief
+ * proposes. This is what criterion 7 should be narrowed to.
+ */
+export const CORRECTED_EXIT_RULE =
+ 'Animate an exit only when it aids orientation. When it is animated, its direction is spatially consistent with the entrance. Timing may be shorter when the dismissal is a system response, but is chosen by purpose and frequency rather than applied universally.';
+
export const GUIDANCE_CONFLICTS: ReadonlyArray<GuidanceConflict> = [
{
id: 'exit-optional',
@@ -47,12 +125,26 @@ export const GUIDANCE_CONFLICTS: ReadonlyArray<GuidanceConflict> = [
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.',
+ '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. This is also the one conflict the sources settle: Emil\u2019s guidance, which the brief cites as a reference, says high-frequency UI often should not animate its exit at all. Both sources agree with the page; neither supports the criterion.',
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',
+ 'Narrow the criterion rather than rewrite the paragraph. An exit is warranted when it aids orientation — a panel closing, a dialog revealing what was underneath — and is not warranted on a surface the user has already looked away from. The published paragraph mostly stands; what it lacks is the direction rule, which is the next conflict.',
+ severity: 'overreach',
href: '/pages/motion-lab/exit-gap/',
},
+ {
+ id: 'exit-shorter',
+ section: 'Movement Principles',
+ published:
+ 'The page says nothing about exit duration. It asks only that the exit match the entrance.',
+ proposed:
+ '--duration-exit is 175ms against --duration-enter at 230ms: every exit is shorter than every entrance, by construction.',
+ reading:
+ 'The token mapping encodes a universal law and the sources do not carry one. beUI states it plainly — "let old content leave faster than new content arrives" — but Emil argues asymmetric timing around deliberate actions versus system responses, a distinction the brief drops. A dismissal the user deliberately triggered and is watching is not the same as one the system performs on their behalf, and only the second clearly wants to be quick.',
+ resolution:
+ 'Keep both tokens — the values are good defaults — but stop asserting the ratio as a rule. Name which dismissals are system responses (a toast expiring, a menu closing after a pick) and which are deliberate (a dialog the user chose to close), and let the second kind reach for --duration-enter without failing a review.',
+ severity: 'overreach',
+ href: '/pages/motion-lab/tokens/',
+ },
{
id: 'reduced-motion-delete',
section: 'Respecting User Preferences',
@@ -75,9 +167,9 @@ export const GUIDANCE_CONFLICTS: ReadonlyArray<GuidanceConflict> = [
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.',
+ 'The strongest rule in the proposal, and the only exit claim both sources state outright — the page says match the entrance, Emil says exit the way it entered. It survives the narrowing criterion 7 needs: whenever an exit IS animated, this governs it. The proposal adds the part the page leaves out, the curve — 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.',
+ 'Extend the paragraph rather than replace it: same path, opposite curve. Leave duration out of it — see the exit-timing conflict.',
severity: 'extension',
href: '/pages/motion-lab/tokens/',
},
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric.ts
index f9b922f7d1..faf1a32e31 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric.ts
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric.ts
@@ -19,6 +19,7 @@
* regenerated audit moves the rubric's citations with it.
*/
+import {LOOP_COUNTS} from './motionCost';
import {
AUDIT_COUNTS,
HARDCODED_SITES,
@@ -58,8 +59,11 @@ export type Criterion = {
/** Measured, from __generated__/motionAudit.ts. */
readonly evidence?: string;
/** How the criterion sits against the published Motion page. */
- readonly guidance?: 'reversal' | 'aligned';
+ readonly guidance?: 'reversal' | 'overreach' | 'aligned';
readonly guidanceNote?: string;
+ /** Another criterion this one pulls against, if any. */
+ readonly contradicts?: number;
+ readonly contradictionNote?: string;
};
export const SEVERITY_LABEL: Readonly<Record<Severity, string>> = {
@@ -124,6 +128,9 @@ export const RUBRIC_CRITERIA: ReadonlyArray<Criterion> = [
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.`,
+ contradicts: 7,
+ contradictionNote:
+ 'This criterion decides whether a presence surface earns an exit at all. Criterion 7 as the brief wrote it overrode that for anything classed as an overlay, which made Tooltip simultaneously required to have no motion and required to animate out. Criterion 7 has been narrowed so this one wins.',
},
{
n: 3,
@@ -180,16 +187,20 @@ export const RUBRIC_CRITERIA: ReadonlyArray<Criterion> = [
id: 'presence',
title: 'Enter and exit',
severity: 'blocker',
- severityNote: 'Blocker for overlays and presence surfaces.',
+ severityNote:
+ 'Blocker for surfaces whose dismissal reveals content underneath — dialogs, drawers, sheets, lightboxes. Not applicable to surfaces the user has already looked away from.',
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',
+ rule: 'An exit is animated when it aids orientation — the surface is spatially anchored, or its dismissal reveals what was underneath. When animated it retraces the entry path. A surface the user has already looked away from may dismiss instantly.',
+ pass: 'A drawer that slid in from the right slides back out to the right, on the exit curve. A tooltip disappears instantly, because the pointer has already left it.',
+ fail: 'A drawer that slides in and is removed on the next frame. Or an exit that leaves by a different edge than it arrived from.',
+ guidance: 'overreach',
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.',
+ 'Narrowed from the brief, which failed any surface that animated in and vanished out. That version contradicted the published page and the brief\u2019s own cited source: Emil\u2019s guidance says high-frequency UI often should not animate its exit at all. Orientation is the test, not presence. What survives unchanged is the direction rule, which every source states outright.',
+ contradicts: 2,
+ contradictionNote:
+ 'As the brief wrote it, this criterion and criterion 2 could not both be satisfied. Tooltip is the highest-frequency surface in the system, so criterion 2 says give it no motion; it is also an overlay, so criterion 7 made an instant dismissal a blocker. The narrowing resolves it — frequency decides whether an exit is warranted, and this criterion governs only the exits that are.',
},
{
n: 8,
@@ -259,6 +270,24 @@ export const RUBRIC_CRITERIA: ReadonlyArray<Criterion> = [
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.`,
},
+ {
+ n: 13,
+ id: 'idle-cost',
+ title: 'Idle cost',
+ severity: 'blocker',
+ severityNote:
+ 'Blocker for anything that loops. Not applicable to one-shot transitions, which criterion 6 already governs.',
+ automatable: 'partly',
+ check:
+ 'Lint can read the animated property off an infinite keyframe set and check for a reduced-motion arm. Whether the containment is right, and whether the loop should exist at all, needs a trace.',
+ rule: 'A loop animates transform and opacity only, paints inside its own box (contain: paint plus a deliberate layer gated on prefers-reduced-motion: no-preference), and has an arm that stills it. Motion that cannot be a transform is stepped with steps() at the lowest legible cadence, never per frame.',
+ pass: 'A spinner that rotates on transform inside a contained box, and stops \u2014 rather than slows \u2014 under reduced motion.',
+ fail: 'A shimmer on background-position, a pulse on box-shadow, or a bar on inset. Each repaints or re-lays-out every frame, forever, on a page where nothing is happening.',
+ evidence: `${LOOP_COUNTS.total} loops measured across core, lab and this lab. ${LOOP_COUNTS.paintOrLayout} animate a paint-only or layout property; ${LOOP_COUNTS.publishedUncontained} of the ${LOOP_COUNTS.core + LOOP_COUNTS.lab} the packages publish are uncontained, and one has no reduced-motion arm at all.`,
+ guidance: 'aligned',
+ guidanceNote:
+ 'The published page already warns that motion the user sees constantly is where motion hurts. This criterion is that warning applied to the one case where the cost does not stop when the user does.',
+ },
];
export const AUTOMATABLE_LABEL: Readonly<Record<Automatable, string>> = {
@@ -317,5 +346,5 @@ export const MISSING_PRINCIPLE = {
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.',
+ 'Fold it into criterion 4 as a fourth pairing rule, or add it as a fourteenth criterion \u2014 thirteen is now idle cost. Either way the rubric should be a superset of the published guidance, not a divergent list.',
} as const;
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
index 724d955707..29908e2f8c 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/rubric/page.tsx
@@ -14,6 +14,14 @@
* trust.
*/
+import {
+ COST_EVIDENCE,
+ COST_LABEL,
+ COST_RULE,
+ COST_SUMMARY,
+ COST_VARIANT,
+ LOOP_INVENTORY,
+} from '../motionCost';
import type {ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Badge} from '@astryxdesign/core/Badge';
@@ -332,6 +340,9 @@ function CriterionCard({criterion}: {criterion: Criterion}) {
{criterion.guidance === 'reversal' && (
<Badge variant="error" label="Reverses published guidance" />
)}
+ {criterion.guidance === 'overreach' && (
+ <Badge variant="warning" label="Narrowed to fit its sources" />
+ )}
{criterion.guidance === 'aligned' && (
<Badge variant="success" label="Already published" />
)}
@@ -353,12 +364,20 @@ function CriterionCard({criterion}: {criterion: Criterion}) {
{criterion.evidence}
</Text>
)}
+ {criterion.contradictionNote != null && (
+ <Text type="supporting" color="secondary">
+ <strong>Pulls against criterion {criterion.contradicts}: </strong>
+ {criterion.contradictionNote}
+ </Text>
+ )}
{criterion.guidanceNote != null && (
<Text type="supporting" color="secondary">
<strong>
{criterion.guidance === 'reversal'
? 'Contradicts the published Motion page: '
- : 'Cites the published Motion page: '}
+ : criterion.guidance === 'overreach'
+ ? 'Claimed more than its sources support: '
+ : 'Cites the published Motion page: '}
</strong>
{criterion.guidanceNote}{' '}
<Link href="/pages/motion-lab/published/">See the conflicts</Link>
@@ -465,7 +484,7 @@ export default function MotionRubricPage() {
</VStack>
<VStack gap={3}>
- <Heading level={2}>The twelve</Heading>
+ <Heading level={2}>The thirteen</Heading>
{RUBRIC_CRITERIA.map(criterion => (
<CriterionCard key={criterion.id} criterion={criterion} />
))}
@@ -714,6 +733,63 @@ export default function MotionRubricPage() {
</VStack>
<VStack gap={3}>
+ <Heading level={2}>Every loop in the system, and what it costs</Heading>
+ <Text color="secondary">{COST_SUMMARY}</Text>
+ <Banner
+ status="info"
+ title="Why a loop gets its own criterion"
+ description={
+ <VStack gap={2}>
+ <Text>{COST_RULE}</Text>
+ <Text type="supporting" color="secondary">
+ {COST_EVIDENCE}
+ </Text>
+ </VStack>
+ }
+ />
+ <Table density="balanced">
+ <TableHeader>
+ <TableRow>
+ <TableHeaderCell>Loop</TableHeaderCell>
+ <TableHeaderCell>Animates</TableHeaderCell>
+ <TableHeaderCell>Contained</TableHeaderCell>
+ <TableHeaderCell>Reduced-motion arm</TableHeaderCell>
+ <TableHeaderCell>Idle cost</TableHeaderCell>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {LOOP_INVENTORY.map(loop => (
+ <TableRow key={`${loop.where}-${loop.component}`}>
+ <TableCell>
+ <VStack gap={0.5}>
+ <Text weight="semibold">{loop.component}</Text>
+ <Text type="supporting" color="secondary">
+ {loop.file}
+ </Text>
+ <Text type="supporting" color="secondary">
+ {loop.note}
+ </Text>
+ </VStack>
+ </TableCell>
+ <TableCell>
+ <Badge
+ variant={loop.compositorSafe ? 'success' : 'error'}
+ label={loop.animates}
+ />
+ </TableCell>
+ <TableCell>{loop.contained ? 'yes' : 'no'}</TableCell>
+ <TableCell>{loop.hasReducedMotionArm ? 'yes' : 'no'}</TableCell>
+ <TableCell>
+ <Badge
+ variant={COST_VARIANT[loop.cost]}
+ label={COST_LABEL[loop.cost]}
+ />
+ </TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
+ </Table>
+
<Heading level={2}>A principle the rubric drops</Heading>
<Card padding={4}>
<VStack gap={2}>
diff --git a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/sections.ts b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/sections.ts
index 7779a067de..e596f7d6be 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/motion-lab/sections.ts
+++ b/apps/sandbox/src/app/(sandbox)/pages/motion-lab/sections.ts
@@ -66,7 +66,7 @@ export const MOTION_SECTIONS: ReadonlyArray<MotionSection> = [
title: 'The exit gap',
group: 'Presence',
decides:
- 'Whether presence surfaces should animate out at all, and what enter and exit cost.',
+ 'Which surfaces earn an animated exit, and what enter and exit cost on the ones that do.',
},
{
href: '/pages/motion-lab/bugs/',