An open source design system that's fully customizable and agent ready
TypeScript
docs(motion): expand motion foundation page with guidance content (#1830)
Ted McDonald7ab776ea2049
diff --git a/packages/cli/docs/motion.doc.mjs b/packages/cli/docs/motion.doc.mjsindex c311aa37f4..f41092dd6c 100644--- a/packages/cli/docs/motion.doc.mjs+++ b/packages/cli/docs/motion.doc.mjs@@ -13,7 +13,15 @@ export const docs = {content: [{type: 'prose',- text: 'XDS motion tokens define timing in three bands: fast (micro-interactions like hover/press), medium (entrance/exit), and slow (continuous/looping). Each band has a base value with min/max variants derived from a consistent ratio.',+ text: 'Motion serves two purposes: it makes interfaces easier to understand, and it makes them more pleasant to use. A panel animating open helps the eye track what changed and where new content sits in the layout. These moments reduce cognitive load and make the interface feel responsive.',+ },+ {+ type: 'prose',+ text: 'At the same time, well-tuned motion gives an application a sense of craft and polish that users notice, even if they can\'t name it.',+ },+ {+ type: 'prose',+ text: 'XDS provides duration and easing tokens that keep these moments consistent across your application.',},],},@@ -37,6 +45,56 @@ export const docs = {},],},+ {+ title: 'Where Motion Helps',+ content: [+ {+ type: 'prose',+ text: 'Some parts of the interface benefit from animation. Panels, dialogs, and collapsible sections are disorienting when they appear instantly — animation gives the eye something to follow. Toasts and notifications need just enough entrance to be noticed without startling. State changes like a switch flipping or a selection highlighting feel more intentional with a brief transition.',+ },+ {+ type: 'prose',+ text: 'The common thread is that these are moments where the user needs to understand what happened.',+ },+ ],+ },+ {+ title: 'Where Motion Hurts',+ content: [+ {+ type: 'prose',+ text: 'Table row hovers. List item highlights. Anything the user does dozens of times per minute. Adding perceptible duration to these interactions makes the interface feel like it’s catching up to the cursor. Keep these fast enough that the user never notices a delay.',+ },+ {+ type: 'prose',+ text: 'Animations that block interaction are worse. If a user has to wait for a panel to finish sliding before they can click something inside it, the animation has become an obstacle. Motion should never stand between the user and their next action.',+ },+ ],+ },+ {+ title: 'Movement Principles',+ content: [+ {+ type: 'list',+ style: 'unordered',+ items: [+ 'Not everything needs an animated exit. Elements the user is moving away from — tooltips, hover cards, dropdown menus — can disappear instantly. The user has already shifted their attention. Animate the exit only when it helps orient the user, like a panel closing or a dialog dismissing to reveal what’s underneath.',+ 'When you do animate exit, match the entrance. A panel that slides in from the right should slide back out to the right.',+ 'Direction should match the action. Navigating deeper into content should feel like moving forward. Going back should feel like returning. This keeps the user oriented in the structure of the application.',+ 'Contextual UI should feel connected to its trigger. A dropdown should expand from the button that opened it. A popover should appear near the element it describes. This doesn’t apply to global UI like command palettes or toasts, which have their own fixed positions.',+ ],+ },+ ],+ },+ {+ title: 'Respecting User Preferences',+ content: [+ {+ type: 'prose',+ text: 'Some users experience motion sensitivity — animation that feels polished to one person can cause discomfort for another. XDS components should honor the operating system’s reduced motion setting. When it’s enabled, replace animations with instant state changes.',+ },+ ],+ },{title: 'Usage',content: [@@ -68,17 +126,18 @@ const styles = stylex.create({type: 'list',style: 'do',items: [- 'Use fast durations for state changes (hover, press, toggle).',- 'Use medium durations for element entrance/exit (dialogs, dropdowns).',- 'Use slow durations sparingly — only for continuous animations (loading spinners, progress bars).',+ 'Animate transitions that involve spatial change — panels opening, content expanding, elements entering the screen.',+ 'Use fast tokens for small, frequent interactions. Use medium tokens for larger transitions that rearrange the layout.',+ 'Honor reduced motion preferences at the OS level.',],},{type: 'list',style: 'dont',items: [- 'Use slow durations for interactive feedback — users will perceive lag.',- 'Skip easing on transitions — linear motion feels robotic.',+ 'Let hover states or high-frequency interactions feel like they’re lagging behind the user.',+ 'Let animation delay when a user can interact with new content. The transition should complete before — or not block — the next action.',+ 'Move elements in ways that contradict where they came from or where they’re going.',],},],