@facto-to/design-system 0.1.0-beta.1 → 0.1.0-beta.2

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.
@@ -0,0 +1,213 @@
1
+ import * as TooltipPrimitive from '@radix-ui/react-tooltip';
2
+ import * as ToastPrimitive from '@radix-ui/react-toast';
3
+ import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
4
+ import * as DialogPrimitive from '@radix-ui/react-dialog';
5
+ import * as SwitchPrimitive from '@radix-ui/react-switch';
6
+ import * as TabsPrimitive from '@radix-ui/react-tabs';
7
+ import type { AnchorHTMLAttributes, ButtonHTMLAttributes, ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, HTMLAttributes, InputHTMLAttributes, ReactNode, TextareaHTMLAttributes } from 'react';
8
+ import './styles.css';
9
+ export type FactoThemeTokens = Partial<Record<`--facto-${string}`, string | number>>;
10
+ type ThemeTokens = FactoThemeTokens;
11
+ export interface FactoThemeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
12
+ /** Scoped overrides; unspecified tokens inherit the dashboard defaults or parent theme. */
13
+ tokens?: FactoThemeTokens;
14
+ /** Inline styles take precedence over the tokens prop. */
15
+ style?: CSSProperties & Partial<ThemeTokens>;
16
+ }
17
+ /** Scoped token container. Inline `--facto-*` values are forwarded to portalled overlays. */
18
+ export declare function FactoTheme({ className, tokens, style, ...props }: FactoThemeProps): import("react").JSX.Element;
19
+ /** Button hierarchy based on the final Facto user application controls. */
20
+ export type ButtonVariant = 'primary' | 'secondary' | 'danger' | 'text';
21
+ export type ButtonSize = 'sm' | 'md' | 'lg';
22
+ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
23
+ variant?: ButtonVariant;
24
+ size?: ButtonSize;
25
+ fullWidth?: boolean;
26
+ /** Shows a non-interactive progress indicator and disables the control. */
27
+ loading?: boolean;
28
+ }
29
+ export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
30
+ /** Accessible icon-only action. `ariaLabel` is required because there is no visible text. */
31
+ export interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'aria-label'> {
32
+ ariaLabel: string;
33
+ size?: ButtonSize;
34
+ }
35
+ export declare const IconButton: import("react").ForwardRefExoticComponent<IconButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
36
+ /** Elevated neutral content container. */
37
+ export interface SurfaceProps extends HTMLAttributes<HTMLDivElement> {
38
+ padding?: 'none' | 'sm' | 'md' | 'lg';
39
+ }
40
+ export declare function Surface({ padding, className, ...props }: SurfaceProps): import("react").JSX.Element;
41
+ /** Semantic alias for a card-shaped `Surface`. */
42
+ export declare function Card(props: SurfaceProps): import("react").JSX.Element;
43
+ /** Compact overview widget preset (20px padding) from the Facto dashboard. */
44
+ export interface WidgetProps extends Omit<SurfaceProps, 'padding'> {
45
+ span?: 1 | 2;
46
+ }
47
+ export declare function Widget({ span, className, ...props }: WidgetProps): import("react").JSX.Element;
48
+ /** Responsive 194px dashboard widget grid with its own query container. */
49
+ export declare function DashboardGrid({ className, children, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
50
+ export interface WidgetHeaderProps extends HTMLAttributes<HTMLDivElement> {
51
+ withAction?: boolean;
52
+ }
53
+ export declare function WidgetHeader({ withAction, className, ...props }: WidgetHeaderProps): import("react").JSX.Element;
54
+ export declare function WidgetList({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
55
+ export declare function WidgetKeyValue({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
56
+ export declare function WidgetAmount({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
57
+ export interface WidgetActionButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
58
+ dark?: boolean;
59
+ href?: never;
60
+ }
61
+ export interface WidgetActionLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
62
+ dark?: boolean;
63
+ href: string;
64
+ }
65
+ export type WidgetActionProps = WidgetActionButtonProps | WidgetActionLinkProps;
66
+ /** Use href for navigation; omit it for a button action. */
67
+ export declare function WidgetAction(props: WidgetActionProps): import("react").JSX.Element;
68
+ export declare function WidgetRow({ className, type, ...props }: ButtonHTMLAttributes<HTMLButtonElement>): import("react").JSX.Element;
69
+ export interface TextFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
70
+ label?: ReactNode;
71
+ helperText?: ReactNode;
72
+ error?: ReactNode;
73
+ containerClassName?: string;
74
+ }
75
+ /** Labelled text input with linked helper or error description. */
76
+ export declare function TextField({ label, helperText, error, id, containerClassName, className, ...props }: TextFieldProps): import("react").JSX.Element;
77
+ export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
78
+ label?: ReactNode;
79
+ helperText?: ReactNode;
80
+ error?: ReactNode;
81
+ containerClassName?: string;
82
+ }
83
+ /** Labelled multiline input with linked helper or error description. */
84
+ export declare function Textarea({ label, helperText, error, id, containerClassName, className, ...props }: TextareaProps): import("react").JSX.Element;
85
+ export type BadgeTone = 'success' | 'warning' | 'danger' | 'neutral';
86
+ export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
87
+ tone?: BadgeTone;
88
+ }
89
+ /** Compact explicit status label. */
90
+ export declare function Badge({ tone, className, ...props }: BadgeProps): import("react").JSX.Element;
91
+ export interface SelectItem {
92
+ value: string;
93
+ label: ReactNode;
94
+ disabled?: boolean;
95
+ }
96
+ export interface SelectProps {
97
+ options: readonly SelectItem[];
98
+ value?: string;
99
+ defaultValue?: string;
100
+ onValueChange?: (value: string) => void;
101
+ placeholder?: string;
102
+ label?: ReactNode;
103
+ error?: ReactNode;
104
+ disabled?: boolean;
105
+ name?: string;
106
+ id?: string;
107
+ ariaLabel?: string;
108
+ 'aria-describedby'?: string;
109
+ className?: string;
110
+ }
111
+ /** Controlled or uncontrolled Radix select. Use `options` for stable value/label pairs. */
112
+ export declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): import("react").JSX.Element;
113
+ export interface SwitchProps extends Omit<ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, 'children'> {
114
+ label?: ReactNode;
115
+ description?: ReactNode;
116
+ }
117
+ /** Radix switch with optional visible label and description. */
118
+ export declare function Switch({ label, description, className, id, ...props }: SwitchProps): import("react").JSX.Element;
119
+ export interface CheckboxProps extends Omit<ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, 'children'> {
120
+ label?: ReactNode;
121
+ description?: ReactNode;
122
+ }
123
+ /** Radix checkbox with optional visible label and description. */
124
+ export declare function Checkbox({ label, description, className, id, ...props }: CheckboxProps): import("react").JSX.Element;
125
+ export declare const Tabs: import("react").ForwardRefExoticComponent<TabsPrimitive.TabsProps & import("react").RefAttributes<HTMLDivElement>>;
126
+ export declare function TabsList({ className, ...props }: ComponentPropsWithoutRef<typeof TabsPrimitive.List>): import("react").JSX.Element;
127
+ export declare function TabsTrigger({ className, ...props }: ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>): import("react").JSX.Element;
128
+ export declare function TabsContent({ className, ...props }: ComponentPropsWithoutRef<typeof TabsPrimitive.Content>): import("react").JSX.Element;
129
+ export declare const Dialog: import("react").FC<DialogPrimitive.DialogProps>;
130
+ export declare const DialogTrigger: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
131
+ export declare const DialogClose: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
132
+ export declare const DialogTitle: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogTitleProps & import("react").RefAttributes<HTMLHeadingElement>>;
133
+ export declare const DialogDescription: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & import("react").RefAttributes<HTMLParagraphElement>>;
134
+ export interface DialogContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
135
+ size?: 'sm' | 'md';
136
+ }
137
+ /** Focus-managed modal content. Place title and description inside for accessible announcements. */
138
+ export declare function DialogContent({ size, className, style, children, ...props }: DialogContentProps): import("react").JSX.Element;
139
+ export declare const Sheet: import("react").FC<DialogPrimitive.DialogProps>;
140
+ export declare const SheetTrigger: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
141
+ export declare const SheetClose: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
142
+ export declare const SheetTitle: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogTitleProps & import("react").RefAttributes<HTMLHeadingElement>>;
143
+ export declare const SheetDescription: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & import("react").RefAttributes<HTMLParagraphElement>>;
144
+ export interface SheetContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
145
+ side?: 'center' | 'right' | 'bottom';
146
+ }
147
+ /** Focus-managed side or mobile-bottom sheet. */
148
+ export declare function SheetContent({ side, className, style, children, ...props }: SheetContentProps): import("react").JSX.Element;
149
+ export interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
150
+ width?: string | number;
151
+ height?: string | number;
152
+ circle?: boolean;
153
+ }
154
+ /** Decorative neutral loading placeholder. */
155
+ export declare function Skeleton({ width, height, circle, className, style, ...props }: SkeletonProps): import("react").JSX.Element;
156
+ export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
157
+ title: ReactNode;
158
+ description?: ReactNode;
159
+ action?: ReactNode;
160
+ icon?: ReactNode;
161
+ }
162
+ /** Centred zero-data state. */
163
+ export declare function EmptyState({ title, description, action, icon, className, ...props }: EmptyStateProps): import("react").JSX.Element;
164
+ export type NoticeTone = 'info' | 'success' | 'warning' | 'danger';
165
+ export interface NoticeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
166
+ tone?: NoticeTone;
167
+ title: ReactNode;
168
+ description?: ReactNode;
169
+ action?: ReactNode;
170
+ }
171
+ /** Inline contextual notice; use `danger` for blocking errors. */
172
+ export declare function Notice({ tone, title, description, action, className, ...props }: NoticeProps): import("react").JSX.Element;
173
+ export interface StackProps extends HTMLAttributes<HTMLDivElement> {
174
+ gap?: 1 | 2 | 3 | 4 | 5 | 6;
175
+ direction?: 'vertical' | 'horizontal';
176
+ align?: 'start' | 'center' | 'end' | 'stretch';
177
+ justify?: 'start' | 'center' | 'end' | 'between';
178
+ }
179
+ /** Small flex layout primitive using Facto spacing tokens. */
180
+ export declare function Stack({ gap, direction, align, justify, className, ...props }: StackProps): import("react").JSX.Element;
181
+ export declare function TooltipProvider({ delayDuration, ...props }: ComponentPropsWithRef<typeof TooltipPrimitive.Provider>): import("react").JSX.Element;
182
+ export declare const Tooltip: import("react").FC<TooltipPrimitive.TooltipProps>;
183
+ export declare const TooltipTrigger: import("react").ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
184
+ export interface TooltipContentProps extends ComponentPropsWithRef<typeof TooltipPrimitive.Content> {
185
+ variant?: 'default' | 'content';
186
+ }
187
+ /** Supplemental plain text; interactive content belongs in a dialog or popover. */
188
+ export declare function TooltipContent({ variant, className, style, sideOffset, children, ...props }: TooltipContentProps): import("react").JSX.Element;
189
+ /** Dashboard notifications default to 2.6 seconds. */
190
+ export declare function ToastProvider({ duration, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Provider>): import("react").JSX.Element;
191
+ export interface ToastProps extends ComponentPropsWithRef<typeof ToastPrimitive.Root> {
192
+ tone?: NoticeTone;
193
+ }
194
+ /** Controlled or uncontrolled notification. Render a ToastViewport inside the provider. */
195
+ export declare function Toast({ tone, className, style, children, ...props }: ToastProps): import("react").JSX.Element;
196
+ export declare function ToastTitle({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Title>): import("react").JSX.Element;
197
+ export declare function ToastDescription({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Description>): import("react").JSX.Element;
198
+ export declare function ToastAction({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Action>): import("react").JSX.Element;
199
+ export declare function ToastClose({ className, children, 'aria-label': label, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Close>): import("react").JSX.Element;
200
+ export declare function ToastViewport({ className, style, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Viewport>): import("react").ReactPortal | null;
201
+ export interface EnhancedSearchFieldProps extends Omit<TextFieldProps, 'value' | 'defaultValue' | 'type' | 'onChange'> {
202
+ value?: string;
203
+ defaultValue?: string;
204
+ onValueChange?: (value: string) => void;
205
+ clearLabel?: string;
206
+ }
207
+ /** Local input only; filtering and requests are owned by the consuming application. */
208
+ export declare function EnhancedSearchField({ value, defaultValue, onValueChange, clearLabel, label, helperText, error, id, containerClassName, className, disabled, readOnly, ...props }: EnhancedSearchFieldProps): import("react").JSX.Element;
209
+ /** Dashboard list search: native input changes, no added icon or clear action. */
210
+ export interface SearchFieldProps extends Omit<TextFieldProps, 'type'> {
211
+ }
212
+ export declare function SearchField({ className, ...props }: SearchFieldProps): import("react").JSX.Element;
213
+ export {};
@@ -0,0 +1,190 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "package": "@facto-to/design-system",
4
+ "packageVersion": "0.1.0-beta.2",
5
+ "exports": [
6
+ "Badge",
7
+ "Button",
8
+ "Card",
9
+ "Checkbox",
10
+ "DashboardGrid",
11
+ "Dialog",
12
+ "DialogClose",
13
+ "DialogContent",
14
+ "DialogDescription",
15
+ "DialogTitle",
16
+ "DialogTrigger",
17
+ "EmptyState",
18
+ "EnhancedSearchField",
19
+ "FactoTheme",
20
+ "IconButton",
21
+ "Notice",
22
+ "SearchField",
23
+ "Select",
24
+ "Sheet",
25
+ "SheetClose",
26
+ "SheetContent",
27
+ "SheetDescription",
28
+ "SheetTitle",
29
+ "SheetTrigger",
30
+ "Skeleton",
31
+ "Stack",
32
+ "Surface",
33
+ "Switch",
34
+ "Tabs",
35
+ "TabsContent",
36
+ "TabsList",
37
+ "TabsTrigger",
38
+ "TextField",
39
+ "Textarea",
40
+ "Toast",
41
+ "ToastAction",
42
+ "ToastClose",
43
+ "ToastDescription",
44
+ "ToastProvider",
45
+ "ToastTitle",
46
+ "ToastViewport",
47
+ "Tooltip",
48
+ "TooltipContent",
49
+ "TooltipProvider",
50
+ "TooltipTrigger",
51
+ "Widget",
52
+ "WidgetAction",
53
+ "WidgetAmount",
54
+ "WidgetHeader",
55
+ "WidgetKeyValue",
56
+ "WidgetList",
57
+ "WidgetRow"
58
+ ],
59
+ "tokens": [
60
+ "--facto-accent",
61
+ "--facto-accent-soft",
62
+ "--facto-accent-strong",
63
+ "--facto-action-disabled",
64
+ "--facto-action-disabled-text",
65
+ "--facto-action-primary",
66
+ "--facto-action-primary-foreground",
67
+ "--facto-action-primary-hover",
68
+ "--facto-badge-padding",
69
+ "--facto-button-danger-padding",
70
+ "--facto-button-font-size",
71
+ "--facto-button-line-height",
72
+ "--facto-button-padding",
73
+ "--facto-button-padding-lg",
74
+ "--facto-button-padding-sm",
75
+ "--facto-button-text-padding",
76
+ "--facto-canvas",
77
+ "--facto-checkbox-border",
78
+ "--facto-checkbox-foreground",
79
+ "--facto-control-text",
80
+ "--facto-danger",
81
+ "--facto-danger-soft",
82
+ "--facto-dashboard-gap",
83
+ "--facto-focus",
84
+ "--facto-font-sans",
85
+ "--facto-font-size",
86
+ "--facto-font-size-amount",
87
+ "--facto-font-size-heading-lg",
88
+ "--facto-font-size-heading-md",
89
+ "--facto-font-size-heading-sm",
90
+ "--facto-font-size-label",
91
+ "--facto-font-weight-bold",
92
+ "--facto-font-weight-medium",
93
+ "--facto-font-weight-regular",
94
+ "--facto-font-weight-semibold",
95
+ "--facto-icon-button-size",
96
+ "--facto-input-background",
97
+ "--facto-input-font-size",
98
+ "--facto-input-height",
99
+ "--facto-input-line-height",
100
+ "--facto-input-padding",
101
+ "--facto-input-placeholder",
102
+ "--facto-layer-dialog",
103
+ "--facto-layer-overlay",
104
+ "--facto-layer-select",
105
+ "--facto-layer-toast",
106
+ "--facto-layer-tooltip",
107
+ "--facto-line",
108
+ "--facto-line-height",
109
+ "--facto-line-height-amount",
110
+ "--facto-line-height-heading-lg",
111
+ "--facto-line-height-heading-md",
112
+ "--facto-line-height-heading-sm",
113
+ "--facto-line-height-label",
114
+ "--facto-muted",
115
+ "--facto-muted-on-subtle",
116
+ "--facto-notice-danger-border",
117
+ "--facto-notice-info-border",
118
+ "--facto-notice-success-border",
119
+ "--facto-notice-warning-border",
120
+ "--facto-overlay-background",
121
+ "--facto-radius-card",
122
+ "--facto-radius-control",
123
+ "--facto-radius-control-lg",
124
+ "--facto-radius-control-sm",
125
+ "--facto-radius-danger",
126
+ "--facto-radius-dialog",
127
+ "--facto-radius-input",
128
+ "--facto-radius-sheet",
129
+ "--facto-radius-sheet-mobile",
130
+ "--facto-search-placeholder",
131
+ "--facto-shadow-card",
132
+ "--facto-shadow-dialog",
133
+ "--facto-shadow-select",
134
+ "--facto-shadow-sheet",
135
+ "--facto-shadow-sheet-bottom",
136
+ "--facto-shadow-switch-thumb",
137
+ "--facto-shadow-tabs-trigger-active",
138
+ "--facto-skeleton-background",
139
+ "--facto-space-1",
140
+ "--facto-space-2",
141
+ "--facto-space-3",
142
+ "--facto-space-4",
143
+ "--facto-space-5",
144
+ "--facto-space-6",
145
+ "--facto-subtle",
146
+ "--facto-success",
147
+ "--facto-success-soft",
148
+ "--facto-success-strong",
149
+ "--facto-surface",
150
+ "--facto-surface-border",
151
+ "--facto-surface-padding",
152
+ "--facto-switch-thumb",
153
+ "--facto-switch-track",
154
+ "--facto-switch-track-checked",
155
+ "--facto-tabs-list-background",
156
+ "--facto-text",
157
+ "--facto-toast-default-description",
158
+ "--facto-toast-default-foreground",
159
+ "--facto-toast-error-accent",
160
+ "--facto-toast-error-description",
161
+ "--facto-toast-error-shadow",
162
+ "--facto-toast-gap",
163
+ "--facto-toast-max-width",
164
+ "--facto-toast-offset",
165
+ "--facto-toast-offset-mobile",
166
+ "--facto-toast-padding",
167
+ "--facto-toast-radius",
168
+ "--facto-toast-shadow",
169
+ "--facto-tooltip-content-shadow",
170
+ "--facto-tooltip-default-background",
171
+ "--facto-tooltip-default-foreground",
172
+ "--facto-tooltip-font-size",
173
+ "--facto-tooltip-line-height",
174
+ "--facto-tooltip-padding",
175
+ "--facto-tooltip-radius",
176
+ "--facto-tooltip-shadow",
177
+ "--facto-tracking",
178
+ "--facto-tracking-heading",
179
+ "--facto-tracking-heading-lg",
180
+ "--facto-tracking-heading-tight",
181
+ "--facto-warning",
182
+ "--facto-warning-soft",
183
+ "--facto-widget-action-background",
184
+ "--facto-widget-action-hover",
185
+ "--facto-widget-focus",
186
+ "--facto-widget-heading",
187
+ "--facto-widget-muted",
188
+ "--facto-widget-padding"
189
+ ]
190
+ }
@@ -0,0 +1,15 @@
1
+ # Component selection
2
+
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
+
5
+ - Actions: Button (primary/secondary/danger/text; sm/md/lg), IconButton (ariaLabel required). Button does not implement asChild.
6
+ - Forms: TextField, Textarea, SearchField (native events); EnhancedSearchField (string callback); Select (options + onValueChange); Checkbox and Switch (Radix checked callbacks).
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
+ - 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
+ - Tabs: Tabs, TabsList, TabsTrigger, TabsContent; matching value strings, keep accessible tab labels.
10
+ - Dialog: Dialog, DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogClose. Sheet has corresponding six parts. Use trigger/close asChild to wrap a Button; supply title and description in content.
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
+ - Toast: ToastProvider, Toast, ToastTitle, ToastDescription, ToastAction, ToastClose, ToastViewport. App controls open/onOpenChange. Default duration 2600ms, bottom center, dark success; danger uses white/red. One viewport per group. ToastAction requires altText. No imperative global notification store is exported.
13
+ - Theme: FactoTheme and FactoThemeTokens type. Defaults work without custom values; inline token overrides are forwarded to portals.
14
+
15
+ 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.
@@ -0,0 +1,40 @@
1
+ # Composing Facto workflows
2
+
3
+ Use this reference for filterable lists, async forms, nested overlays and notifications. The SDK supplies UI primitives; the host owns state, validation, requests and transactional behavior. Build one coherent workflow and verify it before repeating the pattern across repositories.
4
+
5
+ ## Select components and tokens accurately
6
+
7
+ Prefer Surface for a standard panel rather than rebuilding its padding/border/shadow CSS. Use native semantic tables or the host's table library; there is no Facto DataTable. Check every --facto-* variable against the installed catalog/tokens.css before using it. A guessed name with a fallback can appear to work while silently bypassing the design system. Use an application-specific prefix for genuinely new host variables. Secondary copy on canvas/subtle uses --facto-muted-on-subtle rather than --facto-muted.
8
+
9
+ ## State and asynchronous forms
10
+
11
+ Keep one canonical record collection. Derive table rows, counts and the open Sheet's record from it; store a selected id rather than a stale record object. Compose search, Select and Tabs predicates explicitly and provide an empty state/reset path for their intersection.
12
+
13
+ In a Dialog form, keep native onChange for TextField and string onValueChange for Select. Set Button type="submit" explicitly. Associate field errors with the actual failing field. Preserve input after a failed request; reset after success/cancel according to the app's existing behavior.
14
+
15
+ Button loading disables the button, not every possible submit event. Guard the submit handler synchronously (e.g. with a ref), disable related controls during an in-flight operation and clean up mock timers on unmount. Real requests require their own cancellation/idempotency policy; do not imply that a UI lock prevents duplicate backend operations. An Undo action should target the created/changed record by stable id and must not replace the whole collection with an old snapshot that discards later edits.
16
+
17
+ ## Sheet → Dialog → Select
18
+
19
+ Nest React providers/roots according to ownership; triggers and their content must share their root. Use asChild on supported Dialog/Sheet/Tooltip triggers to wrap a single ref-capable Button. Button itself has no asChild prop. Include distinct titles/descriptions and one ToastViewport per notification group.
20
+
21
+ Default Dialog and Sheet overlays share layer tokens. For a child dialog that should dim the parent Sheet, scope a higher overlay/dialog layer to the child via FactoTheme. Keep Select/Tooltip/Toast above that child. For the default layer scale, the tested example is:
22
+
23
+ ```tsx
24
+ <FactoTheme
25
+ tokens={{ '--facto-layer-overlay': 1010, '--facto-layer-dialog': 1011 }}
26
+ style={{ background: 'transparent' }}
27
+ >
28
+ <Dialog>{/* trigger, title/description and content */}</Dialog>
29
+ </FactoTheme>
30
+ ```
31
+
32
+ This is a default-theme example, not a universal value: inspect host overrides first. Keep the nested FactoTheme wrapper outside invalid HTML contexts. Scoped props propagate tokens to body portals; increasing a wrapper's CSS z-index alone does not.
33
+
34
+ If many row triggers share one Sheet root, retain the actual clicked button and restore focus to it through onCloseAutoFocus. If editing/filtering removes that row, use a meaningful stable fallback such as a focusable queue heading. One-root/one-trigger cases normally use the built-in return behavior; do not override it unnecessarily.
35
+
36
+ Test Escape one layer at a time. In the tested Radix composition, an open Select closes first, then its Dialog, then its Sheet. A newly created Toast is also a dismissable layer: Escape can dismiss it before the Sheet. Avoid global Escape handlers that close several layers at once. Focus return is deferred; browser tests should wait for the expected active element rather than checking immediately after the old DOM disappears.
37
+
38
+ ## Observable acceptance
39
+
40
+ Exercise empty filters, invalid fields, request failure/retry, synchronous duplicate submit attempts, success updates, Undo without losing other edits, nested Select keyboard interaction, focus return (including a filtered-out trigger), scoped portal themes, and narrow layouts. Inspect the child overlay visually: functional focus isolation alone does not prove that the parent Sheet is dimmed. Check serious/critical accessibility issues and actual font loading. These checks do not certify all browsers or all host frameworks.
@@ -0,0 +1,34 @@
1
+ # Facto Dashboard design intent
2
+
3
+ Default visual language: warm neutral canvas, white surfaces, near-black text and primary actions, restrained green status/accent, compact consistent controls, generous panel radii, quiet borders and shadows. Do not turn every primary action green just because the brand accent is green. Avoid substituting gradients, oversized hero typography or a different spacing scale unless asked.
4
+
5
+ The generated tokens.css is the authoritative default value reference. Core roles:
6
+
7
+ | Role | Token / default |
8
+ | --- | --- |
9
+ | Canvas / surface / subtle | --facto-canvas #f5f5f4 / --facto-surface #fff / --facto-subtle #f3f3f2 |
10
+ | Text / secondary | --facto-text #121411 / --facto-muted #757575 |
11
+ | Secondary on tinted background | --facto-muted-on-subtle #6c6c67; use this on canvas/subtle and recheck contrast |
12
+ | Border | --facto-line #e7e7e5 |
13
+ | Body | Inter, 14px / 21px via font tokens |
14
+ | Page heading | --facto-font-size-heading-lg 28px / --facto-line-height-heading-lg 36px |
15
+ | Control / input / card radius | 10px / 14px / 24px |
16
+ | Surface / compact Widget padding | 26px / 20px |
17
+ | Dashboard grid | 194px tracks, --facto-dashboard-gap 8px |
18
+
19
+ Surface is a general content container. DashboardGrid/Widget is the compact overview preset; choosing a different general page layout does not make it a pixel-identical Dashboard clone. Use semantic HTML and host-scoped token CSS for tables, headings and navigation that have no exported component.
20
+
21
+ Keep semantic color pairs together when customizing: canvas/text, surface/text, primary/primary-foreground, status/status-soft, tooltip background/foreground and toast background/foreground. Recheck contrast and disabled/focus/hover states. Default warning text has an intentional accessibility adjustment; do not revert it to an earlier application color.
22
+
23
+ Theme extension example (partial tokens inherit defaults):
24
+
25
+ ```tsx
26
+ <FactoTheme tokens={{
27
+ '--facto-canvas': '#edf5ff',
28
+ '--facto-action-primary': '#1458c0',
29
+ '--facto-action-primary-hover': '#10489e',
30
+ '--facto-action-primary-foreground': '#ffffff',
31
+ }}>{children}</FactoTheme>
32
+ ```
33
+
34
+ Tokens-only adoption is an intentional intermediate result. Identify components still using legacy appearance so the user understands the remaining scope.
@@ -0,0 +1,54 @@
1
+ # Installation and integration
2
+
3
+ ## Version and framework
4
+
5
+ Read version.json for the version used to generate this skill. Check the target workspace's manifest and resolved lockfile/package version. Use its package manager; avoid creating a second lockfile. The supported baseline is React/React DOM 19, ESM, CSS imports and font asset handling. Do not use --force or --legacy-peer-deps to hide a mismatch. In a React 18 project, explain the compatibility constraint and assess the framework upgrade separately; tokens/fonts may be evaluated independently without importing the React entry.
6
+
7
+ For a new compatible project with no installed package:
8
+
9
+ ```sh
10
+ npm install --save-exact @facto-to/design-system@0.1.0-beta.2
11
+ ```
12
+
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.
14
+
15
+ ## Components plus style
16
+
17
+ Import once at the host's CSS entry/root layout:
18
+
19
+ ```tsx
20
+ import '@facto-to/design-system/styles.css'
21
+ import '@facto-to/design-system/fonts.css'
22
+ ```
23
+
24
+ styles.css includes tokens.css. fonts.css registers self-hosted variable Inter; it does not apply a font by itself. FactoTheme sets font, body-size, tracking, text and canvas on its wrapper. It is a div: do not place it in table rows or other invalid HTML contexts. It adds no page height, resets or body margin rules. Use scoped host layout CSS intentionally.
25
+
26
+ Interactive components/handlers need a client boundary in React Server Component frameworks. Import global CSS at the framework's allowed root; keep client state in a client component. The package ships a use-client entry, but the verified consumer is Vite; verify other frameworks in the actual host before claiming compatibility.
27
+
28
+ ## Typography/token-only adoption
29
+
30
+ For a project not replacing React controls, import only:
31
+
32
+ ```ts
33
+ import '@facto-to/design-system/tokens.css'
34
+ import '@facto-to/design-system/fonts.css'
35
+ ```
36
+
37
+ Apply tokens to a scoped wrapper and the specific legacy controls that need them. See adoption.css's .facto-adoption rules. Native controls often do not inherit fonts, and native headings have browser margins/sizes. Specify their font/typography intentionally. Importing tokens alone does not turn a legacy button into a Facto Button. Inter's bundled subsets cover Latin/Latin Extended; Chinese and other scripts fall back to system fonts.
38
+
39
+ ## Theme scope and portals
40
+
41
+ Default: <FactoTheme>…</FactoTheme>. Change only requested values using its tokens prop. Values such as radii need units. The accepted prefix is --facto-; a made-up variable has no effect unless some CSS consumes it.
42
+
43
+ Use FactoTheme tokens or inline style for scoped overrides that must reach Dialog, Sheet, Select, Tooltip and Toast portals. A CSS class confined to a wrapper cannot reliably theme a body portal. Do not set root variables for a single themed panel. Keep one ToastViewport per notification group. For multiple themes, keep providers and portals within the relevant React theme subtree.
44
+
45
+ ## Verify font loading in the browser
46
+
47
+ After the adopted UI has rendered, evaluate in the browser (or its test runner):
48
+
49
+ ```js
50
+ const faces = await document.fonts.load('14px Inter', 'Facto')
51
+ const interLoaded = faces.length > 0 && faces.every(face => face.status === 'loaded')
52
+ ```
53
+
54
+ Also inspect computed font-family on the adopted text. A CSS declaration alone does not prove the font downloaded, and document.fonts.check alone can pass when no matching face exists. If loading fails, inspect the font request and import path. Linked workspaces can hit development-server filesystem boundaries; verify a production preview or a normal package installation before changing application styles or broadening server access.
@@ -0,0 +1,43 @@
1
+ # Incremental migration of an existing demo
2
+
3
+ ## Before changing presentation
4
+
5
+ Identify the actual target route/components and record the important behaviors: handlers, submit semantics, validation/error text, focus, loading/disabled states, filtering, navigation and async results. Inspect the relevant CSS cascade, not only JSX. Do not print .env, cookies, private keys or user datasets. Use existing mocks or synthetic records for tests.
6
+
7
+ Choose scope from the user's request:
8
+
9
+ - Fonts/colors only: import tokens and fonts, scope host typography/background/border rules. Retain interactive components.
10
+ - Selected components: integrate styles, replace one coherent component group, then verify it before expanding.
11
+ - Full visual alignment: also adjust surfaces, heading hierarchy, spacing, density and layout where requested; preserve business logic and data.
12
+
13
+ Summarize proposed mappings briefly and continue authorized local changes. Do not require repeated approval for routine replacements. A framework upgrade, unsupported widget replacement or ambiguous business behavior may require a separate decision; still complete independent safe work.
14
+
15
+ ## Mapping and behavioral hazards
16
+
17
+ | Existing UI | Facto replacement | Preserve/check |
18
+ | --- | --- | --- |
19
+ | Primary/secondary button | Button | onClick, disabled, loading; explicitly type="submit" in forms, since default is button |
20
+ | Icon-only action | IconButton | required ariaLabel, keyboard, existing action |
21
+ | Input/textarea | TextField / Textarea | name/id/value/defaultValue/onChange, validation, autocomplete; wrapper may affect grid selectors |
22
+ | Compact list search | SearchField | native onChange(event), filter/debounce/request logic |
23
+ | Search with clear button | EnhancedSearchField | onValueChange(string), including clear/reset; no native onChange prop |
24
+ | Native select | Select | options with nonempty values, onValueChange(string), controlled state, name and form reset; not children/option or event callback |
25
+ | Checkbox/switch | Checkbox / Switch | checked + onCheckedChange; checkbox may emit 'indeterminate', use value === true for booleans |
26
+ | Card/panel | Surface / Card | content/layout; padding values are none/sm/md/lg, not numbers |
27
+ | Compact metric widgets | DashboardGrid + Widget | data and responsive density; use span 1 or 2 |
28
+ | Modal/drawer | Dialog / Sheet compound parts | open/onOpenChange, accessible title/description, Escape, focus return, portal layering |
29
+ | Notifications | ToastProvider + Toast parts + ToastViewport | app-owned state, tone and timing; no toast.success API |
30
+ | Tooltip | TooltipProvider + Tooltip parts | asChild only on supported trigger; no nested button, supplemental text only |
31
+ | Complex table/chart/date picker/navigation | Keep existing implementation | use public tokens in a scoped adapter; no Facto equivalents are exported in this version |
32
+
33
+ Do not replace real data with example mock arrays. Keep any existing notification service as an adapter if it is widely used; migrate its visual renderer rather than rewriting all callers. When keeping an old overlay/widget, verify its z-index and focus coexist with the new ones. Remove a dependency only after proving no remaining uses.
34
+
35
+ ## Cascade cleanup
36
+
37
+ Check global button/input rules, high-specificity selectors, !important, CSS modules, Tailwind utilities, resets and CSS layers. Unlayered CSS can override layered utilities regardless of import order. Do not rely solely on moving an import to the bottom.
38
+
39
+ On migrated components, remove conflicting presentation classes such as bg-*, text color/size, rounded-*, p-*, border/shadow utilities. Retain necessary positioning and layout classes. Preserve selectors still used elsewhere. Avoid !important patches and broad *, button, input resets. Check the computed result for font, color, background, padding, radius and focus state. Font and color changes alone do not reproduce the Dashboard hierarchy.
40
+
41
+ ## Acceptance
42
+
43
+ Use the application's existing checks. Exercise the modified submit, selection, validation, search, notification and dialog flows that actually apply. Compare before/after business results with synthetic data. Inspect desktop and narrow viewport, long labels, empty/loading/error/disabled states and keyboard access. Check no horizontal overflow, accessible names and contrast on both surface and canvas. Verify font faces load (a successful font check with no matching face is insufficient). State what remains unverified rather than calling typecheck a full UI pass.
@@ -0,0 +1,24 @@
1
+ # Adopt Facto across several frontend repositories
2
+
3
+ Work only in the repositories the user identifies. Treat each as a separate consumer: do not assume matching React versions, frameworks, CSS pipelines, component APIs, lockfiles or release schedules.
4
+
5
+ ## Read the installed SDK first
6
+
7
+ In each target package/workspace, find its resolved @facto-to/design-system version and read the package's AI.md. Prefer that installed package's dist/ai/references/catalog.json and dist/index.d.ts over a globally installed skill's snapshot. The installed package may be newer or older than the skill. If AI.md is absent (e.g. 0.1.0-beta.1), use its README, dist/index.d.ts and dist/tokens.css; explain that AI guidance requires a newer SDK rather than inventing an entry point. Do not upgrade without checking compatibility and the requested scope.
8
+
9
+ Use the catalog to choose a component, search declarations for just that export, and read migration.md for event/behavior differences. Avoid reading the entire library source or every reference before a simple change. Do not assume that package discovery causes automatic skill invocation.
10
+
11
+ ## Inventory, then migrate incrementally
12
+
13
+ Keep a compact per-repository summary:
14
+
15
+ | Repository / app | Framework + React | Installed SDK | Requested scope | Components to replace / retain | Verification | Result / remaining work |
16
+ | --- | --- | --- | --- | --- | --- | --- |
17
+
18
+ First identify shared visual needs (fonts, canvas, surfaces, control styles), then map components separately in each application. Preserve each application's routing, providers, requests, auth, validation, state and persistence. Keep advanced tables/charts that have no SDK replacement and style them through tokens.
19
+
20
+ Implement a small representative slice in one compatible repo, verify its behavior, then apply the demonstrated pattern to the other requested repos. Reuse the design rules and compatible adapters, not blind textual replacements. A shared local component wrapper is useful where it preserves existing callers, but do not introduce a new cross-repository package unless required.
21
+
22
+ Use each repo's package manager, CSS entry, client boundaries and test commands. Do not silently upgrade React 18, delete an existing UI library still in use, overwrite AGENTS.md/CLAUDE.md, or commit/push/deploy all repos. An incompatible repo does not block independent compatible repos: report its constraint and complete the rest within scope.
23
+
24
+ Verify each changed repo independently (build/typecheck plus affected interactions and styles). Record which pages/components were migrated, which remain legacy or token-only, and which checks actually ran. Passing in one repo is not evidence that all repos work. Keep this inventory in the response or an authorized private work record rather than creating public planning files automatically.