@facto-to/design-system 0.1.0-beta.6 → 0.1.0-beta.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AI.md CHANGED
@@ -2,6 +2,10 @@
2
2
 
3
3
  This package includes its own version-matched Agent Skill. Start here when adopting Facto UI or replacing mismatched components/fonts/styles in one or several frontend repositories. No MCP or remote knowledge service is required. Installing npm does not automatically activate a skill in your AI client.
4
4
 
5
+ ## Shared design standard
6
+
7
+ Start with the [public standard](dist/ai/references/ui-standard.md), then consult the relevant [reference sections](dist/ai/references/ui-standard-reference.md). [Standard metadata](dist/ai/references/standard-version.json) separates target revision from component adoption. Host-specific business documentation stays in the host repository.
8
+
5
9
  ## Read only what this task needs
6
10
 
7
11
  All paths below are relative to this installed package directory:
@@ -13,10 +17,12 @@ All paths below are relative to this installed package directory:
13
17
  5. For fonts/themes, read [integration.md](dist/ai/references/integration.md), [design.md](dist/ai/references/design.md) and only the relevant properties in [tokens.css](dist/tokens.css).
14
18
  6. For composed workflows, read [composition.md](dist/ai/references/composition.md) for state ownership, async guards, layered overlays, focus and Undo behavior. Adapt the [mock recipe](dist/ai/assets/AdoptionDemo.tsx) and [scoped CSS](dist/ai/assets/adoption.css) where useful. Never replace live business data/handlers with mock example state.
15
19
 
16
- Visual baseline: Facto UI Standard rules v1.2, document revision v1.2.21. Read the bundled design.md for the updated button, focus, modal, switch and responsive recipes; old Dashboard snapshots do not override them.
20
+ Public design target: revision v1.2.24. Existing component adoption baseline: rules v1.2, revision v1.2.21; this is not a claim of full adoption of the target. Read the bundled design.md for the updated button, focus, modal, switch and responsive recipes; old Dashboard snapshots do not override them.
17
21
 
18
22
  Quick constraints: React/React DOM 19; styles.css includes tokens; fonts.css registers Inter and must be imported to load it. Legacy HTML is not automatically restyled. SearchField uses native onChange; EnhancedSearchField and Select use onValueChange; Button defaults to type="button"; Toast is composed of provider/root/viewport, not toast.success(). There is no exported data table, chart, date picker or router.
19
23
 
24
+ For optional animation and reduced-motion behavior, read [motion.md](dist/ai/references/motion.md). Motion never owns application requests or completion timing.
25
+
20
26
  ## Optional skill installation
21
27
 
22
28
  From the frontend repository where this package is installed:
package/README.md CHANGED
@@ -10,7 +10,9 @@ Repository access is controlled separately from the public npm package; installi
10
10
 
11
11
  Coding assistants: start with [AI.md](./AI.md). This package includes the version-matched [Facto UI Skill](./dist/ai/SKILL.md), component catalog, declarations, tokens and tested mock recipe. Use it to create UI or migrate components/styles across existing frontend repositories while preserving business behavior. No MCP, GitHub access or separately downloaded documentation is required after npm installation. The skill can also be installed into Codex or Claude Code; see AI.md.
12
12
 
13
- ## Visual revision: 0.1.0-beta.6
13
+ Public design targets: [standard](dist/ai/references/ui-standard.md) and [reference](dist/ai/references/ui-standard-reference.md). [Metadata](dist/ai/references/standard-version.json) distinguishes targets from the existing component baseline.
14
+
15
+ ## Visual revision: 0.1.0-beta.7
14
16
 
15
17
  Adopts Facto UI Standard rules v1.2 / document revision v1.2.21. This is a visual migration: existing callbacks, controlled/uncontrolled state, validation and Radix overlay behavior are retained. The payment/connection SDK is unaffected.
16
18
 
@@ -27,13 +29,13 @@ beta.5 updates top-right responsive Toast placement, 32px modal headers, overflo
27
29
  Install the beta (requires React 19):
28
30
 
29
31
  ```sh
30
- npm install @facto-to/design-system@0.1.0-beta.6 react@^19 react-dom@^19
32
+ npm install @facto-to/design-system@0.1.0-beta.7 react@^19 react-dom@^19
31
33
  ```
32
34
 
33
35
  For local development, you can also install a generated archive:
34
36
 
35
37
  ```sh
36
- npm install /path/to/facto-to-design-system-0.1.0-beta.6.tgz
38
+ npm install /path/to/facto-to-design-system-0.1.0-beta.7.tgz
37
39
  ```
38
40
 
39
41
  ## Usage
@@ -147,7 +149,7 @@ Both examples assume the named components are imported from `@facto-to/design-sy
147
149
  ## Source fidelity and library extensions
148
150
 
149
151
  - Toast uses the v1.2 feedback recipe: semantic status colors, 12px radius, 12px × 16px padding and 14/20 copy. Duration remains 2600ms. Placement is now top-right: desktop top/right 24px, maximum width 420px; mobile top 16px and full available width with 16px side gutters and safe-area insets.
150
- - The source notification API displays one entry at a time. This library retains composable Radix roots instead of exporting the source's global `toast.success()` store. Optional close/action buttons, multiple notifications, swipe, and pause behavior are extensions. Use `ToastAction` for a dedicated accessible action; the default toast surface is not a click target.
152
+ - The low-level Toast API uses composable Radix roots. Optional close/action buttons, multiple notifications, swipe, and pause behavior are extensions. Use `ToastAction` for a dedicated accessible action; the default toast surface is not a click target.
151
153
  - Tooltip defaults follow the shared compact dark tooltip, without an arrow. `variant="content"` follows the white merchant-detail tooltip override. Provider delay defaults to 300ms. The source's utility-based entrance/exit animations are not reproduced.
152
154
  - SearchField uses the shared 44px minimum-height neutral input recipe and native events. EnhancedSearchField is an optional richer control, not a source-exact Dashboard widget.
153
155
  - Overlay layer values are adapted to this library's shared stacking order. They are configurable and intentionally differ from the source application's z-index values.
@@ -194,3 +196,19 @@ function SaveAction() {
194
196
  ```
195
197
 
196
198
  Desktop notifications appear at the top right; mobile notifications use the available width with at least 16px side gutters and safe-area handling. Select options use full-row selected/hover backgrounds. Public behavior is demonstrated in Storybook and exercised at 375px and 1280px.
199
+ ### Optional motion policy
200
+
201
+ Motion defaults to `auto` and always respects the system's reduced-motion preference. Use `FactoMotionProvider` or `FactoTheme` to set `motion="none"` globally. Button, DialogContent, SheetContent, Toast and the motion primitives accept local overrides. An omitted value inherits; a local `auto` can override a global `none`, but never overrides reduced motion.
202
+
203
+ ```tsx
204
+ <FactoTheme motion="auto">
205
+ <Button loading={pending}>Continue</Button>
206
+ <StepTransition stepKey={step} motion="none">
207
+ {content}
208
+ </StepTransition>
209
+ </FactoTheme>
210
+ ```
211
+
212
+ `motion` controls playback; `motionVariant` continues to choose the existing overlay recipe. Turning motion off keeps loading, disabled state, dismissal and focus behavior intact. Shared primitives include `AnimatedDisclosure`, `AnimatedFeedback`, `ContentReveal`, `SelectionMotion` and `useKeyedListMotion`. They do not perform requests or own application state. See [motion guidance](dist/ai/references/motion.md) for composition and interruption checks.
213
+
214
+ Select is borderless by default. Use `<Select bordered options={options} ariaLabel="Choose an option" />` to enable a visible control border. Keyboard focus and error indicators remain available in both modes.
package/dist/ai/SKILL.md CHANGED
@@ -2,7 +2,7 @@
2
2
  name: facto-ui
3
3
  description: Adopt @facto-to/design-system in new React interfaces or migrate existing demos to Facto Dashboard components, fonts, colors and spacing. Use for Facto UI integration, replacing mismatched components, scoped restyling and theme adaptation; not for payment/backend SDK integration.
4
4
  metadata:
5
- version: "1.0.0"
5
+ version: "1.1.0"
6
6
  ---
7
7
 
8
8
  # Facto UI
@@ -11,6 +11,10 @@ Use the published npm library as the UI source of truth. Support new interfaces,
11
11
 
12
12
  For multiple repositories, read [multi-repo.md](references/multi-repo.md). Prefer references shipped with each installed SDK over this skill snapshot; use the installed package’s `AI.md` as the entry point when present.
13
13
 
14
+ ## Public standard first
15
+
16
+ Read [ui-standard.md](references/ui-standard.md) for shared typography, weights, colors, spacing and accessibility. Consult only the relevant sections of [ui-standard-reference.md](references/ui-standard-reference.md) for the task. Read [standard-version.json](references/standard-version.json): the documented target and verified component baseline are separate. Use actual installed APIs; report gaps instead of claiming complete adoption. Business rules remain in the host repository and must never be copied into public SDK guidance.
17
+
14
18
  ## Choose the smallest appropriate change
15
19
 
16
20
  1. Inspect the target app's package manager, framework, installed React and Facto versions, entry/root layout, global CSS and target components. Read [version.json](references/version.json). This skill's examples target that exact package version. For another version, inspect its installed declarations and CSS before using these examples; do not silently upgrade dependencies. React 18 and non-React apps cannot consume the React 19 components as-is.
@@ -18,7 +22,8 @@ For multiple repositories, read [multi-repo.md](references/multi-repo.md). Prefe
18
22
  3. Read [integration.md](references/integration.md) for styles, font loading, framework constraints and version handling. Read [design.md](references/design.md) to retain the default Dashboard appearance or adapt a requested theme.
19
23
  4. Select components using [components.md](references/components.md). Search [api.d.ts](references/api.d.ts) for the exact component's props, and use installed declarations as the final authority. Read only relevant declarations. Do not invent exports, props, a global toast store, a data table or a chart API.
20
24
  5. For combined workflows (filters, async forms, nested Sheet/Dialog/Select, Toast), read [composition.md](references/composition.md). Adapt [AdoptionDemo.tsx](assets/AdoptionDemo.tsx) and [adoption.css](assets/adoption.css) only if useful. They are a runnable mock reference, not a replacement for existing business data or an entire application scaffold.
21
- 6. Verify the changed workflows with the app's typecheck/build and focused interaction checks. Inspect computed styles and representative narrow/wide layouts when a browser is available. Verify Inter actually loads for Latin text, theme overrides reach portals, and existing behavior remains intact. Report any unverified paths; building alone is not a visual audit.
25
+ 6. For optional motion, read [motion.md](references/motion.md). Default to `auto`, honor reduced motion, preserve behavior when disabled, and keep business timing outside animation completion.
26
+ 7. Verify the changed workflows with the app's typecheck/build and focused interaction checks. Inspect computed styles and representative narrow/wide layouts when a browser is available. Verify Inter actually loads for Latin text, theme overrides reach portals, and existing behavior remains intact. Report any unverified paths; building alone is not a visual audit.
22
27
 
23
28
  Keep Dashboard defaults unless the user requests another palette. Prefer public components and --facto-* tokens over copying package implementation CSS. Importing the package does not automatically restyle legacy HTML. The library has no runtime environment variables or business API credentials. Do not add those for UI adoption.
24
29
 
@@ -1,5 +1,5 @@
1
1
  import * as react from 'react';
2
- import { ImgHTMLAttributes, ReactNode, HTMLAttributes, MouseEventHandler, AnchorHTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, SVGProps, TextareaHTMLAttributes } from 'react';
2
+ import { ReactNode, HTMLAttributes, RefObject, ImgHTMLAttributes, MouseEventHandler, AnchorHTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, SVGProps, TextareaHTMLAttributes } from 'react';
3
3
  import * as PopoverPrimitive from '@radix-ui/react-popover';
4
4
  import * as MenuPrimitive from '@radix-ui/react-dropdown-menu';
5
5
  import * as TooltipPrimitive from '@radix-ui/react-tooltip';
@@ -9,6 +9,79 @@ import * as DialogPrimitive from '@radix-ui/react-dialog';
9
9
  import * as SwitchPrimitive from '@radix-ui/react-switch';
10
10
  import * as TabsPrimitive from '@radix-ui/react-tabs';
11
11
 
12
+ /** Auto enables motion while respecting the operating system's reduced-motion preference. */
13
+ type MotionMode = 'auto' | 'none';
14
+ /** Shared presentation timings in milliseconds, independent of application timing. */
15
+ declare const motionTokens: {
16
+ readonly duration: {
17
+ readonly feedback: 160;
18
+ readonly content: 180;
19
+ readonly surface: 220;
20
+ readonly overlay: 240;
21
+ };
22
+ readonly easing: {
23
+ readonly standard: "cubic-bezier(.22, 1, .36, 1)";
24
+ };
25
+ };
26
+ declare function useMotion(override?: MotionMode): {
27
+ motion: MotionMode;
28
+ reduced: boolean;
29
+ enabled: boolean;
30
+ };
31
+ /** Nest to override a section. The display-contents boundary adds no layout box. */
32
+ declare function FactoMotionProvider({ motion, children }: {
33
+ motion?: MotionMode;
34
+ children: ReactNode;
35
+ }): react.JSX.Element;
36
+
37
+ type MotionOverride = 'auto' | 'none';
38
+ interface StepTransitionProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
39
+ stepKey: string | number;
40
+ children: ReactNode;
41
+ motion?: MotionOverride;
42
+ }
43
+ /** Replaces step content immediately while coordinating the surrounding height. */
44
+ declare function StepTransition({ stepKey, children, motion, className, ...props }: StepTransitionProps): react.JSX.Element;
45
+ interface AnimatedDisclosureProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
46
+ open: boolean;
47
+ children: ReactNode;
48
+ motion?: MotionOverride;
49
+ }
50
+ /** Controlled region whose closed content is immediately removed from keyboard navigation. */
51
+ declare function AnimatedDisclosure({ open, children, motion, className, ...props }: AnimatedDisclosureProps): react.JSX.Element;
52
+ interface AnimatedFeedbackProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
53
+ show: boolean;
54
+ children: ReactNode;
55
+ motion?: MotionOverride;
56
+ }
57
+ /** Controlled feedback presentation; consumer validation and alert semantics change synchronously. */
58
+ declare function AnimatedFeedback({ show, children, motion, className, role, ...props }: AnimatedFeedbackProps): react.JSX.Element;
59
+ interface ContentRevealProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
60
+ children: ReactNode;
61
+ ready?: boolean;
62
+ motion?: MotionOverride;
63
+ }
64
+ /** Reveals only when pending content becomes ready; later content updates remain still. */
65
+ declare function ContentReveal({ children, ready, motion, className, ...props }: ContentRevealProps): react.JSX.Element;
66
+
67
+ type ListMotionKey = string | number;
68
+ /**
69
+ * Applies FLIP movement to rows with a `data-list-motion-key` matching an item key.
70
+ * Rows removed by React are never retained for an exit animation.
71
+ */
72
+ declare function useKeyedListMotion<Key extends ListMotionKey>(rootRef: RefObject<HTMLElement | null>, itemKeys: readonly Key[], { motion }?: {
73
+ motion?: MotionMode;
74
+ }): void;
75
+ interface SelectionMotionProps extends HTMLAttributes<HTMLDivElement> {
76
+ /** Overrides the nearest Facto motion setting for this visual treatment. */
77
+ motion?: MotionMode;
78
+ }
79
+ /**
80
+ * Positions a decorative surface beneath the selected descendant. Selection and
81
+ * keyboard behavior remain the responsibility of the controls it contains.
82
+ */
83
+ declare function SelectionMotion({ motion, className, children, ...props }: SelectionMotionProps): react.JSX.Element;
84
+
12
85
  interface ListRowSlots {
13
86
  leading?: ReactNode;
14
87
  title: ReactNode;
@@ -191,12 +264,13 @@ type FactoThemeTokens = Partial<Record<`--facto-${string}`, string | number>>;
191
264
  type ThemeTokens = FactoThemeTokens;
192
265
  interface FactoThemeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
193
266
  /** Scoped overrides; unspecified tokens inherit the dashboard defaults or parent theme. */
267
+ motion?: MotionMode;
194
268
  tokens?: FactoThemeTokens;
195
269
  /** Inline styles take precedence over the tokens prop. */
196
270
  style?: CSSProperties & Partial<ThemeTokens>;
197
271
  }
198
272
  /** Scoped token container. Inline `--facto-*` values are forwarded to portalled overlays. */
199
- declare function FactoTheme({ className, tokens, style, ...props }: FactoThemeProps): react.JSX.Element;
273
+ declare function FactoTheme({ className, tokens, style, motion, ...props }: FactoThemeProps): react.JSX.Element;
200
274
  /** Shared decorative symbols; name the containing control, not the glyph. */
201
275
  type IconName = 'close' | 'arrowLeft' | 'check' | 'chevronDown' | 'chevronRight' | 'info' | 'warning' | 'plus' | 'chevronLeft' | 'copy' | 'search';
202
276
  interface IconProps extends SVGProps<SVGSVGElement> {
@@ -215,6 +289,7 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
215
289
  size?: ButtonSize;
216
290
  fullWidth?: boolean;
217
291
  /** Shows a non-interactive progress indicator and disables the control. */
292
+ motion?: MotionMode;
218
293
  loading?: boolean;
219
294
  leadingIcon?: ReactNode;
220
295
  trailingIcon?: ReactNode;
@@ -294,6 +369,8 @@ interface SelectProps {
294
369
  placeholder?: string;
295
370
  label?: ReactNode;
296
371
  error?: ReactNode;
372
+ /** Opt in to a visible control border; default is borderless. */
373
+ bordered?: boolean;
297
374
  disabled?: boolean;
298
375
  name?: string;
299
376
  id?: string;
@@ -302,7 +379,7 @@ interface SelectProps {
302
379
  className?: string;
303
380
  }
304
381
  /** Controlled or uncontrolled Radix select. Use `options` for stable value/label pairs. */
305
- declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
382
+ declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, bordered, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
306
383
  interface SwitchProps extends Omit<ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, 'children'> {
307
384
  label?: ReactNode;
308
385
  description?: ReactNode;
@@ -328,10 +405,11 @@ declare const DialogDescription: typeof DialogPrimitive.Description;
328
405
  type OverlayMotionVariant = 'auto' | 'bottom' | 'none';
329
406
  interface DialogContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
330
407
  size?: 'sm' | 'md';
408
+ motion?: MotionMode;
331
409
  motionVariant?: OverlayMotionVariant;
332
410
  }
333
411
  /** Focus-managed modal content. Place title and description inside for accessible announcements. */
334
- declare function DialogContent({ size, motionVariant, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
412
+ declare function DialogContent({ size, motionVariant, motion, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
335
413
  declare const Sheet: react.FC<DialogPrimitive.DialogProps>;
336
414
  declare const SheetTrigger: react.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
337
415
  declare const SheetClose: react.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
@@ -339,10 +417,11 @@ declare const SheetTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.D
339
417
  declare const SheetDescription: react.ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>;
340
418
  interface SheetContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
341
419
  side?: 'center' | 'right' | 'bottom';
420
+ motion?: MotionMode;
342
421
  motionVariant?: OverlayMotionVariant;
343
422
  }
344
423
  /** Focus-managed side or mobile-bottom sheet. */
345
- declare function SheetContent({ side, motionVariant, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
424
+ declare function SheetContent({ side, motionVariant, motion, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
346
425
  interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
347
426
  width?: string | number;
348
427
  height?: string | number;
@@ -386,11 +465,12 @@ declare function TooltipContent({ variant, className, style, sideOffset, collisi
386
465
  /** Dashboard notifications default to 2.6 seconds. */
387
466
  declare function ToastProvider({ duration, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Provider>): react.JSX.Element;
388
467
  interface ToastProps extends ComponentPropsWithRef<typeof ToastPrimitive.Root> {
468
+ motion?: MotionMode;
389
469
  icon?: ReactNode;
390
470
  tone?: NoticeTone;
391
471
  }
392
472
  /** Controlled or uncontrolled notification. Render a ToastViewport inside the provider. */
393
- declare function Toast({ tone, icon, className, style, children, ...props }: ToastProps): react.JSX.Element;
473
+ declare function Toast({ tone, icon, className, style, motion, children, ...props }: ToastProps): react.JSX.Element;
394
474
  declare function ToastTitle({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Title>): react.JSX.Element;
395
475
  declare function ToastDescription({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Description>): react.JSX.Element;
396
476
  declare function ToastAction({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Action>): react.JSX.Element;
@@ -432,5 +512,5 @@ interface ListSkeletonProps extends HTMLAttributes<HTMLDivElement> {
432
512
  /** Loading placeholder only: consumers own the query and loading state. */
433
513
  declare function ListSkeleton({ rows, label, className, ...props }: ListSkeletonProps): react.JSX.Element;
434
514
 
435
- export { Avatar, Badge, Button, Card, Checkbox, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptyState, EnhancedSearchField, ErrorState, FactoTheme, Field, FilterChip, Icon, IconButton, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, Popover, PopoverClose, PopoverContent, PopoverTrigger, ResendCodeButton, SearchField, Select, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, Surface, Switch, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Widget, WidgetAction, WidgetAmount, WidgetHeader, WidgetKeyValue, WidgetList, WidgetRow, useToast };
436
- export type { AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, DialogContentProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };
515
+ export { AnimatedDisclosure, AnimatedFeedback, Avatar, Badge, Button, Card, Checkbox, ContentReveal, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptyState, EnhancedSearchField, ErrorState, FactoMotionProvider, FactoTheme, Field, FilterChip, Icon, IconButton, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, Popover, PopoverClose, PopoverContent, PopoverTrigger, ResendCodeButton, SearchField, Select, SelectionMotion, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, StepTransition, Surface, Switch, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Widget, WidgetAction, WidgetAmount, WidgetHeader, WidgetKeyValue, WidgetList, WidgetRow, motionTokens, useKeyedListMotion, useMotion, useToast };
516
+ export type { AnimatedDisclosureProps, AnimatedFeedbackProps, AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, ContentRevealProps, DialogContentProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, MotionMode, MotionOverride, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SelectionMotionProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, StepTransitionProps, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };
@@ -1,13 +1,16 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "package": "@facto-to/design-system",
4
- "packageVersion": "0.1.0-beta.6",
4
+ "packageVersion": "0.1.0-beta.8",
5
5
  "exports": [
6
+ "AnimatedDisclosure",
7
+ "AnimatedFeedback",
6
8
  "Avatar",
7
9
  "Badge",
8
10
  "Button",
9
11
  "Card",
10
12
  "Checkbox",
13
+ "ContentReveal",
11
14
  "DashboardGrid",
12
15
  "Dialog",
13
16
  "DialogClose",
@@ -23,6 +26,7 @@
23
26
  "EmptyState",
24
27
  "EnhancedSearchField",
25
28
  "ErrorState",
29
+ "FactoMotionProvider",
26
30
  "FactoTheme",
27
31
  "Field",
28
32
  "FilterChip",
@@ -45,6 +49,7 @@
45
49
  "ResendCodeButton",
46
50
  "SearchField",
47
51
  "Select",
52
+ "SelectionMotion",
48
53
  "Sheet",
49
54
  "SheetClose",
50
55
  "SheetContent",
@@ -54,6 +59,7 @@
54
59
  "Skeleton",
55
60
  "Stack",
56
61
  "StepChecklist",
62
+ "StepTransition",
57
63
  "Surface",
58
64
  "Switch",
59
65
  "Tabs",
@@ -80,6 +86,9 @@
80
86
  "WidgetKeyValue",
81
87
  "WidgetList",
82
88
  "WidgetRow",
89
+ "motionTokens",
90
+ "useKeyedListMotion",
91
+ "useMotion",
83
92
  "useToast"
84
93
  ],
85
94
  "tokens": [
@@ -0,0 +1,4 @@
1
+ {
2
+ "documentRevision": "1.2.21",
3
+ "scope": "Existing component baseline only; public standard 1.2.24 is a target, not a full adoption claim."
4
+ }
@@ -3,13 +3,14 @@
3
3
  See catalog.json for the exact runtime exports and api.d.ts for types. The catalog is generated, not a list of independent widgets: compound parts count separately. Search declarations for the selected export rather than reading all types.
4
4
 
5
5
  - Actions: Button (primary/secondary/danger/text; sm/md/lg), IconButton (ariaLabel required; 44px target), Icon (shared decorative close/arrowLeft/check/chevronDown/info/warning). Button does not implement asChild.
6
- - Forms: TextField, Textarea, SearchField (native events); EnhancedSearchField (string callback); Select (options + onValueChange); Checkbox and Switch (Radix checked callbacks).
6
+ - Forms: TextField, Textarea, SearchField (native events); EnhancedSearchField (string callback); Select (options + onValueChange; borderless by default, bordered={true} opts in); Checkbox and Switch (Radix checked callbacks).
7
7
  - Layout: Surface/Card, Stack (gap 1–6), DashboardGrid, Widget, WidgetHeader, WidgetList, WidgetRow, WidgetKeyValue, WidgetAmount, WidgetAction. WidgetAction accepts href for a link; inspect its union type.
8
8
  - Feedback: Badge (success/warning/danger/neutral), Notice (also info), EmptyState, Skeleton. Badge has no info tone. Notice and EmptyState require title, not just children.
9
9
  - Tabs: Tabs, TabsList, TabsTrigger, TabsContent; matching value strings, keep accessible tab labels.
10
10
  - Dialog: Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose. Sheet has corresponding six parts. ModalHeader/ModalFooter are optional stateless layout slots. DialogContent defaults to sm=400px; explicit md=580px is the wide legacy variant. Use trigger/close asChild to wrap a Button; supply title and description in content.
11
11
  - Tooltip: TooltipProvider, Tooltip, TooltipTrigger, TooltipContent. Trigger asChild with a focusable control; default compact dark tooltip, variant="content" for white expanded content. Provider delay 300ms.
12
12
  - Toast: ToastProvider, Toast, ToastTitle, ToastDescription, ToastAction, ToastClose, ToastViewport. App controls open/onOpenChange. Default duration 2600ms; desktop top/right 24px with maximum width 420px, mobile top 16px and full available width with 16px side gutters and safe-area insets; semantic status surface and matching text/icon. One viewport per group. ToastAction requires altText. No imperative global notification store is exported.
13
+ - Motion: FactoMotionProvider, useMotion, motionTokens, StepTransition, AnimatedDisclosure, AnimatedFeedback, ContentReveal, SelectionMotion, useKeyedListMotion. Read [motion.md](motion.md) for global/individual controls and application-state boundaries.
13
14
  - Theme: FactoTheme and FactoThemeTokens type. Defaults work without custom values; inline token overrides are forwarded to portals.
14
15
 
15
16
  There is no exported Table, DataTable, DatePicker, Chart, Sidebar, Form controller or router. Keep host implementations for these and apply scoped tokens, or choose a separate dependency only when the task needs it. Do not import internal dist files, copy source modules or claim shadcn-compatible props merely because the implementation uses Radix.
@@ -1,3 +1,5 @@
1
+ Public target: [UI standard](ui-standard.md) and [reference](ui-standard-reference.md). This file describes the existing component baseline, not complete adoption of the newer target.
2
+
1
3
  # Facto UI visual contract
2
4
 
3
5
  This SDK release adopts **Facto UI Standard design rules v1.2, document revision v1.2.21 (2026-09-28)**. The default is the Dashboard light palette. Do not add a theme switch or persistence when adopting it. Existing scoped token overrides remain supported; test their contrast and portalled surfaces separately.
@@ -58,6 +60,6 @@ At widths up to 700px, newly opened Dialog/Sheet panels slide upward for 320ms w
58
60
 
59
61
  Toast placement is a Facto decision, not a claim about Link: top/right 24px on desktop, max-width 420px; mobile top16 and full available width minus16px side gutters and safe-area insets. Long messages scroll within a bounded surface. Test active modal actions and focused controls together with notifications, rather than auditing these surfaces separately.
60
62
 
61
- Select uses a portalled popper menu with an 8px gap, collision handling and at least148px width where space permits. It retains the Radix modal keyboard contract (arrows/typeahead, Enter selection, Escape and focus return). Dashboard's separate pagination control and its Tab-to-neighbor behavior are not exported by this SDK.
63
+ Select uses a portalled popper menu with an 8px gap, collision handling and at least148px width where space permits. It retains the Radix modal keyboard contract (arrows/typeahead, Enter selection, Escape and focus return). Consumer pagination behavior remains outside the SDK.
62
64
 
63
- Dashboard mobile routes, browser-back/scroll restoration, feature visibility, OTP auto-submit and payment/authentication requests remain application-owned. This release updates shared primitives; it does not export those product flows or automatically upgrade consumers.
65
+ Routing, visibility, submission policies and requests remain application-owned. This release updates shared primitives; it does not export those product flows or automatically upgrade consumers.
@@ -7,7 +7,7 @@ Read version.json for the version used to generate this skill. Check the target
7
7
  For a new compatible project with no installed package:
8
8
 
9
9
  ```sh
10
- npm install --save-exact @facto-to/design-system@0.1.0-beta.6
10
+ npm install --save-exact @facto-to/design-system@0.1.0-beta.8
11
11
  ```
12
12
 
13
13
  React 19 and React DOM 19 must already be compatible with the host; do not reinstall or upgrade them blindly. No Tailwind, backend SDK, API key or runtime environment variable is required.
@@ -0,0 +1,31 @@
1
+ # Optional motion
2
+
3
+ Motion is presentation only. The application owns data requests, validation, selection, navigation and completion. Never wait for an animation to finish before applying application state.
4
+
5
+ `FactoMotionProvider` accepts `motion="auto"` (default) or `motion="none"`. `FactoTheme` accepts the same property. An omitted value inherits the parent. Nested providers and supported component properties override their parent. `auto` always respects the operating system's reduced-motion preference, including changes while the interface is open; it does not force animation.
6
+
7
+ ```tsx
8
+ <FactoTheme motion="auto">
9
+ <Button loading={pending}>Continue</Button>
10
+ <Dialog>
11
+ <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
12
+ <DialogContent motion="none">
13
+ <DialogTitle>Preferences</DialogTitle>
14
+ <DialogDescription>Update your display preferences.</DialogDescription>
15
+ </DialogContent>
16
+ </Dialog>
17
+ </FactoTheme>
18
+ ```
19
+
20
+ Use `motion` to enable/disable playback and existing `motionVariant` to choose an overlay's visual treatment. Portalled overlays and notifications inherit motion settings through React context. The provider renders a display-contents boundary; it should be placed in a flow-content container, not between structural table elements.
21
+
22
+ - `StepTransition`: supply a stable `stepKey`; keep dialog title, close control and shared structure outside the changing content. Do not key/remount the dialog itself. Content height and entry coordinate without holding the previous interactive step.
23
+ - `AnimatedDisclosure`: controlled `open`; connect the trigger with `aria-expanded` and `aria-controls`. Hidden content is inert and unavailable to assistive technology.
24
+ - `AnimatedFeedback`: controlled `show`; retain application error text as needed. The wrapper does not infer error state or initiate retries.
25
+ - `ContentReveal`: controlled `ready`; use a separate layout-matched skeleton until ready. Background refresh should retain existing content.
26
+ - `SelectionMotion`: decorative indicator for existing `aria-pressed` or `aria-selected` controls. Consumers retain keyboard handling and selection semantics.
27
+ - `useKeyedListMotion`: stable item keys and `data-list-motion-key` on rows; first render is static, new rows enter and remaining rows move. Removed rows leave the DOM immediately; the hook never delays a deletion.
28
+
29
+ Buttons remain disabled and expose busy state with motion off. Turning motion off must also cancel in-flight JavaScript animations. Focus restoration, dismissal, loading state and final content must work without animation events. Do not add visible changing loading copy just to explain a spinner; keep the original accessible action name.
30
+
31
+ Verify default, global off, local override, system reduced motion and live preference changes. Exercise portals, rapid next/back, long content, narrow layouts, keyboard focus, and interruption during exit. A browser emulation check does not certify physical mobile keyboard behavior.
@@ -0,0 +1,5 @@
1
+ {
2
+ "rulesVersion": "1.2",
3
+ "documentRevision": "1.2.24",
4
+ "publicEdition": 1
5
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "rulesVersion": "1.2",
3
+ "documentRevision": "1.2.24",
4
+ "publicEdition": 1,
5
+ "componentAdoption": {
6
+ "documentRevision": "1.2.21",
7
+ "scope": "Existing component baseline only; public standard 1.2.24 is a target, not a full adoption claim."
8
+ }
9
+ }