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

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 ADDED
@@ -0,0 +1,44 @@
1
+ # Facto UI: AI entry point
2
+
3
+ This package includes its own version-matched Agent Skill and design contracts. Start here when building UI or adopting `@facto-to/design-system` 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
+
5
+ ## Canonical design contracts (read in order)
6
+
7
+ This package separates visual rules from non-visual QA invariants into two concise, non-overlapping files:
8
+
9
+ 1. **Visual & Token Contract**: [DESIGN.md](DESIGN.md) (mirrored at [dist/ai/references/DESIGN.md](dist/ai/references/DESIGN.md)) — the sole source of truth for palette, warm stone ramp, brand green split (`#00d64f` signal vs `#0b6b4b` text), `rem` typography, 4px spacing, nested radii, button tiers (`md` 40px / `operate` 44–46px / `lg` 52px), 1:1 square OTP, and Do's/Don'ts.
10
+ 2. **Engineering, Accessibility & QA Contract**: [qa-contract.md](dist/ai/references/qa-contract.md) — non-visual invariants covering UI-only logic safety (`G01`), input focus & `forced-colors` (`V03`), `44px` touch/mixed targets (`C04/R03`), WCAG 2.2 (`320px` reflow & `200%` text scaling), overlay/toast coexistence (`O00–O05`), and verification evidence discipline.
11
+
12
+ Host-specific business workflows, APIs, and auth ceremonies stay in the host repository.
13
+
14
+ ## Read only what this task needs
15
+
16
+ All paths below are relative to this installed package directory:
17
+
18
+ 1. Read [version metadata](dist/ai/references/version.json) and compare the target application's resolved package/React versions. Prefer the installed package's contracts over any global skill snapshot.
19
+ 2. Read [SKILL.md](dist/ai/SKILL.md) for the workflow. For multiple repositories, read [multi-repo.md](dist/ai/references/multi-repo.md); inspect and verify each repository separately.
20
+ 3. Find actual exports in [catalog.json](dist/ai/references/catalog.json), then search [dist/index.d.ts](dist/index.d.ts) for the selected component's exact props. Do not guess shadcn or other libraries' APIs.
21
+ 4. For replacements, read [migration.md](dist/ai/references/migration.md). Preserve routes, data, auth, form validation and event behavior. Use a scoped token adapter for widgets without a Facto equivalent.
22
+ 5. For fonts/themes, read [integration.md](dist/ai/references/integration.md), [DESIGN.md](DESIGN.md), and only the relevant properties in [tokens.css](dist/tokens.css).
23
+ 6. For composed workflows, read [composition.md](dist/ai/references/composition.md) and [components.md](dist/ai/references/components.md) for state ownership, async guards, auth kit composition, 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.
24
+
25
+ Quick constraints: React/React DOM 19; `styles.css` includes tokens; `fonts.css` registers self-hosted 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"` and supports `size="sm" | "md" | "operate" | "lg"` (use `size="operate"` for auth/onboarding Step 1 forms to match the auth kit); `Toast` is composed of provider/root/viewport (or `NotificationsProvider` + `useToast()`), not global `toast.success()`. There is no exported data table, chart, date picker or router.
26
+
27
+ For optional animation and reduced-motion behavior, read [motion.md](dist/ai/references/motion.md). Motion never owns application requests or completion timing.
28
+
29
+ ## Optional skill installation
30
+
31
+ From the frontend repository where this package is installed:
32
+
33
+ ```sh
34
+ # Team/project-scoped Codex skill
35
+ node node_modules/@facto-to/design-system/bin/facto-ui-skill.mjs --target .agents/skills
36
+ # Team/project-scoped Claude Code skill
37
+ node node_modules/@facto-to/design-system/bin/facto-ui-skill.mjs --target .claude/skills
38
+ ```
39
+
40
+ The installed command `facto-ui-skill --target <skills-directory>` is also exposed through package-manager execution. The direct Node form above uses only the already installed package, with no download or server. For hoisted/Plug'n'Play workspaces, use the package manager's local binary runner from the correct workspace.
41
+
42
+ An explicit destination is required. Existing skills are never overwritten. For updates, compare and move the old directory outside skill search locations first. Personal skill locations can be used instead of project directories. Skill discovery is client-specific; explicit invocation is reliable after the client discovers it. Use `$facto-ui` in Codex or `/facto-ui` in Claude Code.
43
+
44
+ Alternatively, ask any coding assistant with filesystem access to read this `AI.md` directly; installing the Skill is optional. Give it the paths of the target repositories and the desired migration scope. This grants no automatic access to other repositories or deployment accounts.
package/DESIGN.md ADDED
@@ -0,0 +1,196 @@
1
+ ---
2
+ name: Facto Design System
3
+ description: Restrained daylight operate interface for Facto financial, developer, partner, and console web applications.
4
+ contractVersion: "2.0"
5
+ colors:
6
+ canvas: "#f5f5f4"
7
+ auth-canvas: "#fdfdfd"
8
+ surface: "#ffffff"
9
+ surface-hover: "#fafaf9"
10
+ subtle: "#f3f3f2"
11
+ input-bg: "#f5f5f5"
12
+ input-filled: "#efefed"
13
+ text-primary: "#121411"
14
+ text-secondary: "#4a4d47"
15
+ text-muted: "#62655f"
16
+ line: "#e7e7e5"
17
+ line-strong: "#d4d5d1"
18
+ action-primary: "#171716"
19
+ action-primary-hover: "#2c2e2a"
20
+ action-primary-pressed: "#080908"
21
+ action-disabled-bg: "#eaeae7"
22
+ action-disabled-border: "#e4e4e1"
23
+ action-disabled-text: "#62655f"
24
+ brand-signal: "#00d64f"
25
+ brand-ink: "#0b6b4b"
26
+ brand-soft: "#e7fbf2"
27
+ brand-border: "#b7efd0"
28
+ danger: "#9f2333"
29
+ danger-soft: "#fff0f2"
30
+ danger-border: "#f3b8c0"
31
+ warning: "#805300"
32
+ warning-soft: "#fff7df"
33
+ warning-border: "#efd796"
34
+ info: "#175c9c"
35
+ info-soft: "#eaf3fb"
36
+ info-border: "#b7d5ef"
37
+ badge-dot: "#ed174c"
38
+ typography:
39
+ heading-lg:
40
+ fontFamily: "Inter, -apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, Roboto, sans-serif"
41
+ fontSize: "1.5rem"
42
+ fontWeight: 600
43
+ lineHeight: 1.333
44
+ letterSpacing: "-0.02em"
45
+ heading-md:
46
+ fontFamily: "Inter, -apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, Roboto, sans-serif"
47
+ fontSize: "1.25rem"
48
+ fontWeight: 600
49
+ lineHeight: 1.4
50
+ letterSpacing: "-0.02em"
51
+ heading-sm:
52
+ fontFamily: "Inter, -apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, Roboto, sans-serif"
53
+ fontSize: "1rem"
54
+ fontWeight: 600
55
+ lineHeight: 1.5
56
+ letterSpacing: "0em"
57
+ input:
58
+ fontFamily: "Inter, -apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, Roboto, sans-serif"
59
+ fontSize: "1rem"
60
+ fontWeight: 400
61
+ lineHeight: 1.5
62
+ letterSpacing: "0em"
63
+ body:
64
+ fontFamily: "Inter, -apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, Roboto, sans-serif"
65
+ fontSize: "0.875rem"
66
+ fontWeight: 400
67
+ lineHeight: 1.428
68
+ letterSpacing: "0em"
69
+ label:
70
+ fontFamily: "Inter, -apple-system, BlinkMacSystemFont, SF Pro Text, Segoe UI, Roboto, sans-serif"
71
+ fontSize: "0.75rem"
72
+ fontWeight: 500
73
+ lineHeight: 1.333
74
+ letterSpacing: "0em"
75
+ mono-data:
76
+ fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
77
+ fontSize: "0.875rem"
78
+ fontWeight: 500
79
+ lineHeight: 1.428
80
+ letterSpacing: "0.06em"
81
+ rounded:
82
+ nested-control: "10px"
83
+ control: "12px"
84
+ card: "16px"
85
+ sheet: "24px"
86
+ pill: "999px"
87
+ spacing:
88
+ xs: "4px"
89
+ sm: "8px"
90
+ md: "16px"
91
+ lg: "24px"
92
+ xl: "32px"
93
+ components:
94
+ button-md:
95
+ backgroundColor: "{colors.action-primary}"
96
+ textColor: "{colors.surface}"
97
+ rounded: "{rounded.pill}"
98
+ minHeight: "40px"
99
+ padding: "8px 16px"
100
+ button-operate:
101
+ backgroundColor: "{colors.action-primary}"
102
+ textColor: "{colors.surface}"
103
+ rounded: "{rounded.pill}"
104
+ minHeight: "44px"
105
+ touchMinHeight: "46px"
106
+ padding: "10px 20px"
107
+ button-lg:
108
+ backgroundColor: "{colors.action-primary}"
109
+ textColor: "{colors.surface}"
110
+ rounded: "{rounded.pill}"
111
+ minHeight: "52px"
112
+ padding: "12px 24px"
113
+ button-nested-utility:
114
+ backgroundColor: "{colors.surface}"
115
+ textColor: "{colors.text-primary}"
116
+ rounded: "{rounded.nested-control}"
117
+ minHeight: "40px"
118
+ touchMinHeight: "44px"
119
+ padding: "6px 12px"
120
+ otp-cell:
121
+ backgroundColor: "{colors.input-bg}"
122
+ textColor: "{colors.text-primary}"
123
+ rounded: "{rounded.control}"
124
+ size: "54px"
125
+ ---
126
+
127
+ ## Overview
128
+
129
+ `DESIGN.md` is the **sole canonical visual and token contract** for `@facto-to/design-system`, owned by `Facto-to/design-system` and shipped directly in the npm package alongside `tokens.css` and `qa-contract.md`.
130
+
131
+ Facto uses a **Restrained Daylight Operate** visual system across its user, partner, developer, and console surfaces. Chrome stays quiet in warm neutral stone tones so financial data, verification inputs, and security decisions remain the immediate focal point. Every public component in `@facto-to/design-system` is UI-only: networking, authentication ceremonies, routing, and persistence remain in the host application. For non-visual engineering, accessibility, focus, and QA invariants, read `qa-contract.md`.
132
+
133
+ ## Colors
134
+
135
+ - **Warm neutral ramp**: `#fdfdfd` (`--facto-auth-canvas`, standalone auth canvas) -> `#f5f5f4` (`--facto-canvas`, workspace canvas) -> `#ffffff` (`--facto-surface`, primary surface) -> `#fafaf9` (`--facto-surface-hover`) -> `#f3f3f2` (`--facto-subtle`, secondary panel/button fill) -> `#e7e7e5` (`--facto-line`, 1px hairline) -> `#d4d5d1` (`--facto-line-strong`).
136
+ - **Three-step ink ramp** (all > 5.9:1 on white):
137
+ - `#121411` (`--facto-text`): primary headings, values, and active labels.
138
+ - `#4a4d47` (`--facto-text-secondary`): supporting lists and confirmation copy.
139
+ - `#62655f` (`--facto-muted`): captions, helper text, and secondary metadata.
140
+ - **Primary action ink**: `#171716` with `#ffffff` foreground (hover `#2c2e2a`, pressed `#080908`). Disabled primary buttons recede with `#eaeae7` (`--facto-action-disabled`) and hairline `#e4e4e1` (`--facto-action-disabled-border`) so they never overpower active inputs.
141
+ - **Brand green split**:
142
+ - `#00d64f` (`--facto-accent`): strictly for non-text status dots, live indicators, and visual marks. Never use for text on light surfaces.
143
+ - `#0b6b4b` (`--facto-accent-strong` / `--facto-control-selected-background`): all accessible green text, links, checkbox checks, active step progress, and verified icons (contrast > 6.3:1 on white).
144
+ - `#e7fbf2` (`--facto-accent-soft`): subtle confirmation tint with `#b7efd0` (`--facto-notice-success-border`) hairline border.
145
+ - **Muted semantics**: danger `#9f2333` / `#fff0f2`, warning `#805300` / `#fff7df`, info `#175c9c` / `#eaf3fb`. Native switch checked track uses `#00d66f` (`--facto-switch-track-checked`).
146
+
147
+ ## Typography
148
+
149
+ - **Single sans family**: self-hosted `Inter` across all headings, controls, labels, and body copy (system CJK fallback).
150
+ - **Relative `rem` scale**: declare font sizes in `rem` so 200% browser text zoom scales cleanly without clipping; all control heights are `min-height`, never rigid clipping heights.
151
+ - **Weights**: `400` body and inputs (`1rem` / `16px` input text prevents iOS Safari zoom), `500` controls and labels, `600` headings. Avoid `700`-`900` heavy display weights.
152
+ - **Monospace**: reserved strictly for codes, keys, identifiers, and tabular amounts, always paired with `font-variant-numeric: tabular-nums`.
153
+ - **No decorative kickers**: headings carry their own weight without uppercase eyebrow labels above them.
154
+
155
+ ## Layout
156
+
157
+ - **4px base spacing rhythm**: tight intervals inside groups (`4px`, `8px`, `12px`) and generous separation between groups (`16px`, `20px`, `24px`, `32px`).
158
+ - **Responsive page gutters**: `24px` on wide viewports, dropping to `16px` below `600px` content width (including `AuthFlowShell`). Cards use `24px` padding (`20px` compact, `16px` narrow).
159
+ - **Focused auth axis**: standalone verification and onboarding steps use a centered `380px` column (`620px` via `wide` for multi-column selection cards) so identity pills, 6-digit OTP grids, and primary actions align along one vertical edge.
160
+ - **Zero horizontal overflow down to `320px`**: every layout and auth step adapts cleanly across `1440px`, `834px`, `390px`, `375px`, and `320px` WCAG reflow viewports.
161
+
162
+ ## Elevation & Depth
163
+
164
+ - **Declare elevation once**: cards, inline panels, and badges use flat `1px` hairlines (`--facto-line`) with `--facto-shadow-card: none`.
165
+ - **Floating overlays only**: `Sheet`, `Dialog`, `Popover`, `DropdownMenu`, `Select` popper, and `Toast` earn soft neutral shadows (`0 8px 32px rgba(18, 20, 17, 0.12)`). Modal scrim uses `rgba(18, 20, 17, 0.32)`.
166
+
167
+ ## Shapes
168
+
169
+ - **Strict nested radius hierarchy**:
170
+ - Overlays (`Sheet` / `Dialog`): `24px` (uniform `20px` internal padding across sizes; default compact width `400px`, wide `580px`, right drawer `480px`)
171
+ - Cards and panels: `16px`
172
+ - Form controls, notices, toasts, menus, and OTP squares: `12px`
173
+ - Utility controls nested inside a `16px` card (e.g., recovery code chips and `Copy codes` / `Download .txt` toolbar actions): `10px`
174
+ - Primary, secondary, and danger `Button` controls & `Badge`: `999px` pill
175
+ - **1:1 square OTP cells**: segmented verification code cells always maintain `aspect-ratio: 1 / 1` across all code lengths (`4`, `6`, `8`) and viewports (`320px` to `1440px`).
176
+
177
+ ## Components
178
+
179
+ - **Button size tiers (single primitive `<Button>`)**:
180
+ - `size="md"` (default): `min-height: 40px`, `padding: 8px 16px`, `14/20/500`, `999px` pill for standard toolbar, card, and modal actions.
181
+ - `size="operate"` (auth, verification & onboarding primary CTA): `min-height: 44px` on desktop (`46px` on coarse touch pointers or `<=640px`), `padding: 10px 20px`, `14/20/500`, `999px` pill. Use `<Button variant="primary" size="operate" fullWidth>` in Step 1 forms so they match `EmailVerificationStep`, `PasskeySetupCard`, `TotpEnrollmentCard`, and `RecoveryCodesStep` seamlessly.
182
+ - `size="lg"`: `min-height: 52px`, `padding: 12px 24px`, `16/24/500`, `999px` pill for comfortable standalone/checkout submit actions when explicitly chosen.
183
+ - **Core Primitives**: `Button`, `IconButton` (`44px` hit target, `28/38/44px` visible circle), `TextField`, `Textarea`, `SearchField`, `EnhancedSearchField`, `Field`, `OtpInput`, `ResendCodeButton`, `Select` (borderless default, `bordered` opt-in), `Checkbox` (`44x44` hit target, `20px` visual), `Switch` (`44x44` hit target, `34x20` track), `Badge`, `Notice`, `Surface`, `Card`, `Sheet`, `Dialog`, `ModalHeader`, `ModalFooter`, `Tabs`, `Tooltip`, `Popover`, `DropdownMenu`, `Toast`, `NotificationsProvider`, `FactoTheme`, `FactoMotionProvider`.
184
+ - **Auth & Verification Kit**: `AuthFlowShell`, `StepProgress`, `IdentityEchoPill`, `CopyableSecretKey`, `EmailVerificationStep`, `PasskeySetupCard`, `TotpEnrollmentCard`, `RecoveryCodesStep`, `formatRecoveryCodesText`, `SelectionCardGroup`.
185
+ - **Focus & Toast**: Text inputs use `#f5f5f5` idle surface and white focused surface with one `2px` dark inset outline (`outline-offset: -2px`, no shadow). Non-input controls use keyboard-only `2px` dark outer outline (`outline-offset: 2px`). Toasts sit top-right (`24px` desktop max-width `420px`; `16px` mobile full available width).
186
+
187
+ ## Do's and Don'ts
188
+
189
+ - **Do** treat `DESIGN.md` as the sole visual truth source and `qa-contract.md` as the engineering/a11y QA floor; never maintain duplicate visual contracts.
190
+ - **Do** use `<Button size="operate">` across Step 1 auth/onboarding forms so every step shares one button primitive with the auth kit.
191
+ - **Do** use `OtpInput` (one native `<input autocomplete="one-time-code">` layered over 1:1 square visual cells) and isolated `ResendCodeButton` so countdown ticks never steal focus.
192
+ - **Do** place the primary CTA cleanly outside quiet informational panels (`PasskeySetupCard`, `RecoveryCodesStep`) and align card-embedded `10px` utility buttons to the exact 2-column grid above them.
193
+ - **Don't** build OTP fields from multiple `<input maxlength="1">` elements or bypass library `Button`/`TextField`/`Checkbox` primitives with ad-hoc styles.
194
+ - **Don't** hardcode hex colors outside `tokens.css`, use `<16px` text input fonts, strip focus outlines, or put `#00d64f` directly on white text.
195
+ - **Don't** nest `999px` pill utility buttons inside `16px` cards next to `10px` rectangular code chips, or use outlined rectangles for ordinary secondary buttons.
196
+ - **Don't** add decorative glows, gradient text, surface hue gradients, or non-semantic looping animations.
package/README.md CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  React components and extensible design tokens with the Facto Dashboard appearance as the default. Includes self-hosted Inter fonts and TypeScript declarations.
4
4
 
5
+ [Source repository](https://github.com/Facto-to/design-system) · [Integration guide](https://github.com/Facto-to/design-system/blob/main/docs/usage.md)
6
+
7
+ Repository access is controlled separately from the public npm package; installing the package does not require GitHub access.
8
+
9
+ ## AI-assisted adoption and migration
10
+
11
+ Coding assistants: start with [AI.md](./AI.md). This package includes the version-matched [Facto UI Skill](./dist/ai/SKILL.md), the canonical [DESIGN.md](./DESIGN.md) visual contract, the [QA contract](./dist/ai/references/qa-contract.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](./AI.md).
12
+
13
+ ## Visual contract & releases
14
+
15
+ `DESIGN.md` (`v2.0`) is the sole visual and token contract owned by `Facto-to/design-system`, paired with [qa-contract.md](./dist/ai/references/qa-contract.md) for engineering, focus, accessibility, and 320px reflow invariants.
16
+
17
+ - **0.1.0-beta.10**: Consolidates `DESIGN.md` + `qa-contract.md` directly in the npm package, adds `<Button size="operate">` (44px desktop / 46px coarse touch) so Step 1 forms and the auth kit share one button primitive, aligns inline auth edit input with `V03` focus (`16px` font), upgrades `RecoveryCodesStep` to Radix `Checkbox` (`44x44` hit target), eliminates hardcoded hex outside `tokens.css`, and verifies `320px` reflow.
18
+ - **0.1.0-beta.9**: Adds borderless `Select`, 1:1 square `OtpInput`, shared auth/verification kit (`AuthFlowShell`, `StepProgress`, `IdentityEchoPill`, `CopyableSecretKey`, `EmailVerificationStep`, `PasskeySetupCard`, `TotpEnrollmentCard`, `RecoveryCodesStep`, `SelectionCardGroup`), and coordinated step motion.
19
+ - **Earlier defaults**: pill buttons, dark single-layer field focus, 44px targets, quieter 16px cards, semantic feedback colors, 20px modal padding, top-right responsive Toast, and compact `DialogContent` (`size="sm"` 400px default; `size="md"` 580px wide variant). See [DESIGN.md](./DESIGN.md) and [qa-contract.md](./dist/ai/references/qa-contract.md) for exact recipes and acceptance guidance.
20
+
5
21
  ## Requirements
6
22
 
7
23
  - React and React DOM 19.
@@ -10,16 +26,16 @@ React components and extensible design tokens with the Facto Dashboard appearanc
10
26
 
11
27
  ## Install
12
28
 
13
- Once the package is published:
29
+ Install the beta (requires React 19):
14
30
 
15
31
  ```sh
16
- npm install @facto-to/design-system@beta react@^19 react-dom@^19
32
+ npm install --save-exact @facto-to/design-system@0.1.0-beta.10 react@^19 react-dom@^19
17
33
  ```
18
34
 
19
- Before publication, install the generated archive by its local path:
35
+ For local development, you can also install a generated archive:
20
36
 
21
37
  ```sh
22
- npm install /path/to/facto-to-design-system-0.1.0-beta.1.tgz
38
+ npm install /path/to/facto-to-design-system-0.1.0-beta.10.tgz
23
39
  ```
24
40
 
25
41
  ## Usage
@@ -90,7 +106,7 @@ To use only the tokens in a separate UI, import `@facto-to/design-system/tokens.
90
106
 
91
107
  ## Package boundaries
92
108
 
93
- The package contains components, CSS, types, and fonts. Storybook, sample data, tests, business APIs, authentication, wallet integrations, and environment files are not included. Components do not initiate business API calls or persist form values; applications own their data and event handlers.
109
+ The package contains components, CSS, types, fonts, public AI guidance, an optional skill installer and a small synthetic adoption recipe. The Storybook application, business datasets, tests, business APIs, authentication, wallet integrations, and environment files are not included. Components do not initiate business API calls or persist form values; applications own their data and event handlers.
94
110
 
95
111
  React and React DOM are peer dependencies; Radix primitives are runtime dependencies. Inter font files retain their SIL Open Font License in `dist/fonts/OFL.txt`. Font licensing is separate from the component source license.
96
112
 
@@ -122,7 +138,7 @@ Toasts use a provider and a single viewport per notification group. Manage notif
122
138
 
123
139
  Both examples assume the named components are imported from `@facto-to/design-system`. Tooltip content and the toast viewport are portalled to the document body; theme overrides remain scoped through `FactoTheme`. Toasts support Radix's keyboard, hover/focus pause, and swipe interactions. Toast surfaces retain Radix's default `touch-action: none` while handling swipe gestures. Tooltip and toast colors may be overridden with `--facto-tooltip-background`, `--facto-tooltip-foreground`, `--facto-toast-background`, and `--facto-toast-foreground`; they otherwise use the documented source defaults. Layer tokens are `--facto-layer-tooltip` and `--facto-layer-toast`.
124
140
 
125
- `SearchField` follows the Dashboard list filter: a compact native search input, without an added icon or clear button. It supports native `value`/`onChange`, uncontrolled `defaultValue`, and form reset. Provide an accessible name via `label` or `aria-label`.
141
+ `SearchField` follows the Dashboard list filter: a neutral filled native search input, without an added icon or clear button. It supports native `value`/`onChange`, uncontrolled `defaultValue`, and form reset. Provide an accessible name via `label` or `aria-label`.
126
142
 
127
143
  ```tsx
128
144
  <SearchField aria-label="Search pipelines" value={query} onChange={event => setQuery(event.target.value)} />
@@ -132,13 +148,67 @@ Both examples assume the named components are imported from `@facto-to/design-sy
132
148
 
133
149
  ## Source fidelity and library extensions
134
150
 
135
- - Toast defaults follow the Dashboard's final CSS: bottom-center placement, 13px radius, 13px × 17px padding, dark success surface, and 2600ms duration. Error (`tone="danger"`) uses the later white surface/red outline override. Desktop bottom offset is 24px, mobile 16px.
136
- - 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.
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.
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.
137
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.
138
- - SearchField follows the compact Dashboard list-search appearance and native events. EnhancedSearchField is an optional richer control, not a source-exact Dashboard widget.
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.
139
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.
140
156
  - Visual baseline checks cover named properties and states; they do not certify every component, interaction, or browser as pixel-identical to the original application.
141
157
 
142
158
  ## License
143
159
 
144
160
  Copyright 2026 Facto. Component code is licensed under Apache-2.0; see [LICENSE](./LICENSE). Bundled Inter fonts remain under SIL OFL 1.1 in `dist/fonts/OFL.txt`.
161
+
162
+ ### Overlay motion (beta.6)
163
+
164
+ `DialogContent` 与 `SheetContent` 支持 `motionVariant="auto" | "bottom" | "none"`。默认 `auto` 保持现有行为:移动端 ≤700px 上滑入场,桌面静态。`bottom` 在所有宽度开启 Dashboard 风格的 28px 上移淡入和反向退场(240ms),`none` 关闭表面与遮罩动画。系统减少动态效果偏好始终优先。
165
+
166
+ ```tsx
167
+ <Dialog open={open} onOpenChange={setOpen}>
168
+ <DialogContent motionVariant="bottom">
169
+ <DialogTitle>Disconnect account?</DialogTitle>
170
+ <DialogDescription>You can reconnect later.</DialogDescription>
171
+ <DialogClose asChild><Button>Cancel</Button></DialogClose>
172
+ </DialogContent>
173
+ </Dialog>
174
+ ```
175
+
176
+ 保持 Root/Content 挂载,通过 `open` 控制开关以保留退场动画;直接卸载整个组件会跳过退场。`SheetContent side` 决定位置,`motionVariant` 独立决定动效。可通过 `--facto-motion-overlay-bottom-duration`、`--facto-motion-overlay-bottom-distance` 调整节奏和距离。
177
+
178
+ ### Public UI additions (beta.6)
179
+
180
+ - `Button` supports `leadingIcon`, `trailingIcon` and width-preserving `loading`. Use `IconButton` for back/close/add controls; its hit area and visual glyph are separate.
181
+ - `Field` provides inset-label input chrome with leading/trailing slots. `TextField`, `Textarea` and `EnhancedSearchField` remain available for standard labelled fields.
182
+ - `OtpInput` is a controlled native input displayed as code cells. It supports paste/autofill, delayed completion, error and pending presentation. `ResendCodeButton` accepts an application-owned deadline; it never sends a request or imposes a backend rate limit.
183
+ - `NotificationsProvider` / `useToast` provide scoped success/error/warning/info/loading notifications, same-id updates, dismissal and promise transitions. Loading stays visible until resolved or dismissed. Errors from `toast.promise` are rethrown to the caller. No process-global notification store is required.
184
+ - `Popover` and `DropdownMenu` provide portal positioning, keyboard dismissal and focus restoration. Use Tooltip only for supplementary non-interactive text.
185
+ - `FilterChip` is a controlled filter toggle; `ListSkeleton` presents loading rows without owning fetching.
186
+ - `ListGroup` / `ListRow` provide aligned leading, title, description, value, status and trailing slots. Rows are static by default, links with `href`, buttons with `onClick`. Do not nest interactive controls inside an interactive row.
187
+ - `Avatar` / `LogoStack` provide generic image fallbacks; `ErrorState`, `LoadingMore` and `StepChecklist` provide presentation without request, routing or business rules.
188
+
189
+ ```tsx
190
+ function SaveAction() {
191
+ const toast = useToast()
192
+ return <Button onClick={() => toast.success('Saved', { id: 'save' })}>Save</Button>
193
+ }
194
+ // Keep the provider mounted around consumers and within FactoTheme when themed.
195
+ <NotificationsProvider><SaveAction /></NotificationsProvider>
196
+ ```
197
+
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.
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ import { installSkill } from './install-skill-lib.mjs'
3
+ await installSkill(new URL('../dist/ai/', import.meta.url), process.argv.slice(2))
@@ -0,0 +1,38 @@
1
+ import { cp, lstat, mkdir, readdir, rm, realpath } from 'node:fs/promises'
2
+ import path from 'node:path'
3
+ import { fileURLToPath } from 'node:url'
4
+
5
+ export async function installSkill(sourceUrl, args) {
6
+ if (args.length !== 2 || args[0] !== '--target' || !args[1]) {
7
+ throw new Error('Usage: facto-ui-skill --target <skills-directory> (creates facto-ui; refuses existing files)')
8
+ }
9
+ const source = await realpath(fileURLToPath(sourceUrl))
10
+ async function checkTree(directory) {
11
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
12
+ if (entry.isSymbolicLink()) throw new Error('Skill must not contain symlinks')
13
+ if (entry.isDirectory()) await checkTree(path.join(directory, entry.name))
14
+ else if (!entry.isFile()) throw new Error('Skill must contain only regular files')
15
+ }
16
+ }
17
+ await checkTree(source)
18
+ const parent = path.resolve(args[1])
19
+ // Check lexical containment before creating anything, then real containment for symlinked parents.
20
+ const inside = candidate => candidate === source || candidate.startsWith(source + path.sep)
21
+ if (inside(parent)) throw new Error('Destination cannot be inside the source skill')
22
+ await mkdir(parent, { recursive: true })
23
+ if (inside(await realpath(parent))) throw new Error('Destination cannot be inside the source skill')
24
+ const target = path.join(parent, 'facto-ui')
25
+ await mkdir(target) // non-recursive: existing directories and symlinks are never overwritten
26
+ try {
27
+ // The target is reserved above. Copy its children: Node 22 rejects cp of
28
+ // the source directory itself onto an existing target with errorOnExist.
29
+ for (const entry of await readdir(source)) {
30
+ await cp(path.join(source, entry), path.join(target, entry), { recursive: true, force: false, errorOnExist: true })
31
+ }
32
+ if (!(await lstat(path.join(target, 'SKILL.md'))).isFile()) throw new Error('Missing SKILL.md')
33
+ } catch (error) {
34
+ await rm(target, { recursive: true, force: true })
35
+ throw error
36
+ }
37
+ console.log(`Installed Facto UI skill: ${target}`)
38
+ }
@@ -0,0 +1,204 @@
1
+ Copyright 2026 Facto
2
+
3
+
4
+ Apache License
5
+ Version 2.0, January 2004
6
+ http://www.apache.org/licenses/
7
+
8
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
9
+
10
+ 1. Definitions.
11
+
12
+ "License" shall mean the terms and conditions for use, reproduction,
13
+ and distribution as defined by Sections 1 through 9 of this document.
14
+
15
+ "Licensor" shall mean the copyright owner or entity authorized by
16
+ the copyright owner that is granting the License.
17
+
18
+ "Legal Entity" shall mean the union of the acting entity and all
19
+ other entities that control, are controlled by, or are under common
20
+ control with that entity. For the purposes of this definition,
21
+ "control" means (i) the power, direct or indirect, to cause the
22
+ direction or management of such entity, whether by contract or
23
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
24
+ outstanding shares, or (iii) beneficial ownership of such entity.
25
+
26
+ "You" (or "Your") shall mean an individual or Legal Entity
27
+ exercising permissions granted by this License.
28
+
29
+ "Source" form shall mean the preferred form for making modifications,
30
+ including but not limited to software source code, documentation
31
+ source, and configuration files.
32
+
33
+ "Object" form shall mean any form resulting from mechanical
34
+ transformation or translation of a Source form, including but
35
+ not limited to compiled object code, generated documentation,
36
+ and conversions to other media types.
37
+
38
+ "Work" shall mean the work of authorship, whether in Source or
39
+ Object form, made available under the License, as indicated by a
40
+ copyright notice that is included in or attached to the work
41
+ (an example is provided in the Appendix below).
42
+
43
+ "Derivative Works" shall mean any work, whether in Source or Object
44
+ form, that is based on (or derived from) the Work and for which the
45
+ editorial revisions, annotations, elaborations, or other modifications
46
+ represent, as a whole, an original work of authorship. For the purposes
47
+ of this License, Derivative Works shall not include works that remain
48
+ separable from, or merely link (or bind by name) to the interfaces of,
49
+ the Work and Derivative Works thereof.
50
+
51
+ "Contribution" shall mean any work of authorship, including
52
+ the original version of the Work and any modifications or additions
53
+ to that Work or Derivative Works thereof, that is intentionally
54
+ submitted to Licensor for inclusion in the Work by the copyright owner
55
+ or by an individual or Legal Entity authorized to submit on behalf of
56
+ the copyright owner. For the purposes of this definition, "submitted"
57
+ means any form of electronic, verbal, or written communication sent
58
+ to the Licensor or its representatives, including but not limited to
59
+ communication on electronic mailing lists, source code control systems,
60
+ and issue tracking systems that are managed by, or on behalf of, the
61
+ Licensor for the purpose of discussing and improving the Work, but
62
+ excluding communication that is conspicuously marked or otherwise
63
+ designated in writing by the copyright owner as "Not a Contribution."
64
+
65
+ "Contributor" shall mean Licensor and any individual or Legal Entity
66
+ on behalf of whom a Contribution has been received by Licensor and
67
+ subsequently incorporated within the Work.
68
+
69
+ 2. Grant of Copyright License. Subject to the terms and conditions of
70
+ this License, each Contributor hereby grants to You a perpetual,
71
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
72
+ copyright license to reproduce, prepare Derivative Works of,
73
+ publicly display, publicly perform, sublicense, and distribute the
74
+ Work and such Derivative Works in Source or Object form.
75
+
76
+ 3. Grant of Patent License. Subject to the terms and conditions of
77
+ this License, each Contributor hereby grants to You a perpetual,
78
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
79
+ (except as stated in this section) patent license to make, have made,
80
+ use, offer to sell, sell, import, and otherwise transfer the Work,
81
+ where such license applies only to those patent claims licensable
82
+ by such Contributor that are necessarily infringed by their
83
+ Contribution(s) alone or by combination of their Contribution(s)
84
+ with the Work to which such Contribution(s) was submitted. If You
85
+ institute patent litigation against any entity (including a
86
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
87
+ or a Contribution incorporated within the Work constitutes direct
88
+ or contributory patent infringement, then any patent licenses
89
+ granted to You under this License for that Work shall terminate
90
+ as of the date such litigation is filed.
91
+
92
+ 4. Redistribution. You may reproduce and distribute copies of the
93
+ Work or Derivative Works thereof in any medium, with or without
94
+ modifications, and in Source or Object form, provided that You
95
+ meet the following conditions:
96
+
97
+ (a) You must give any other recipients of the Work or
98
+ Derivative Works a copy of this License; and
99
+
100
+ (b) You must cause any modified files to carry prominent notices
101
+ stating that You changed the files; and
102
+
103
+ (c) You must retain, in the Source form of any Derivative Works
104
+ that You distribute, all copyright, patent, trademark, and
105
+ attribution notices from the Source form of the Work,
106
+ excluding those notices that do not pertain to any part of
107
+ the Derivative Works; and
108
+
109
+ (d) If the Work includes a "NOTICE" text file as part of its
110
+ distribution, then any Derivative Works that You distribute must
111
+ include a readable copy of the attribution notices contained
112
+ within such NOTICE file, excluding those notices that do not
113
+ pertain to any part of the Derivative Works, in at least one
114
+ of the following places: within a NOTICE text file distributed
115
+ as part of the Derivative Works; within the Source form or
116
+ documentation, if provided along with the Derivative Works; or,
117
+ within a display generated by the Derivative Works, if and
118
+ wherever such third-party notices normally appear. The contents
119
+ of the NOTICE file are for informational purposes only and
120
+ do not modify the License. You may add Your own attribution
121
+ notices within Derivative Works that You distribute, alongside
122
+ or as an addendum to the NOTICE text from the Work, provided
123
+ that such additional attribution notices cannot be construed
124
+ as modifying the License.
125
+
126
+ You may add Your own copyright statement to Your modifications and
127
+ may provide additional or different license terms and conditions
128
+ for use, reproduction, or distribution of Your modifications, or
129
+ for any such Derivative Works as a whole, provided Your use,
130
+ reproduction, and distribution of the Work otherwise complies with
131
+ the conditions stated in this License.
132
+
133
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
134
+ any Contribution intentionally submitted for inclusion in the Work
135
+ by You to the Licensor shall be under the terms and conditions of
136
+ this License, without any additional terms or conditions.
137
+ Notwithstanding the above, nothing herein shall supersede or modify
138
+ the terms of any separate license agreement you may have executed
139
+ with Licensor regarding such Contributions.
140
+
141
+ 6. Trademarks. This License does not grant permission to use the trade
142
+ names, trademarks, service marks, or product names of the Licensor,
143
+ except as required for reasonable and customary use in describing the
144
+ origin of the Work and reproducing the content of the NOTICE file.
145
+
146
+ 7. Disclaimer of Warranty. Unless required by applicable law or
147
+ agreed to in writing, Licensor provides the Work (and each
148
+ Contributor provides its Contributions) on an "AS IS" BASIS,
149
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
150
+ implied, including, without limitation, any warranties or conditions
151
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
152
+ PARTICULAR PURPOSE. You are solely responsible for determining the
153
+ appropriateness of using or redistributing the Work and assume any
154
+ risks associated with Your exercise of permissions under this License.
155
+
156
+ 8. Limitation of Liability. In no event and under no legal theory,
157
+ whether in tort (including negligence), contract, or otherwise,
158
+ unless required by applicable law (such as deliberate and grossly
159
+ negligent acts) or agreed to in writing, shall any Contributor be
160
+ liable to You for damages, including any direct, indirect, special,
161
+ incidental, or consequential damages of any character arising as a
162
+ result of this License or out of the use or inability to use the
163
+ Work (including but not limited to damages for loss of goodwill,
164
+ work stoppage, computer failure or malfunction, or any and all
165
+ other commercial damages or losses), even if such Contributor
166
+ has been advised of the possibility of such damages.
167
+
168
+ 9. Accepting Warranty or Additional Liability. While redistributing
169
+ the Work or Derivative Works thereof, You may choose to offer,
170
+ and charge a fee for, acceptance of support, warranty, indemnity,
171
+ or other liability obligations and/or rights consistent with this
172
+ License. However, in accepting such obligations, You may act only
173
+ on Your own behalf and on Your sole responsibility, not on behalf
174
+ of any other Contributor, and only if You agree to indemnify,
175
+ defend, and hold each Contributor harmless for any liability
176
+ incurred by, or claims asserted against, such Contributor by reason
177
+ of your accepting any such warranty or additional liability.
178
+
179
+ END OF TERMS AND CONDITIONS
180
+
181
+ APPENDIX: How to apply the Apache License to your work.
182
+
183
+ To apply the Apache License to your work, attach the following
184
+ boilerplate notice, with the fields enclosed by brackets "[]"
185
+ replaced with your own identifying information. (Don't include
186
+ the brackets!) The text should be enclosed in the appropriate
187
+ comment syntax for the file format. We also recommend that a
188
+ file or class name and description of purpose be included on the
189
+ same "printed page" as the copyright notice for easier
190
+ identification within third-party archives.
191
+
192
+ Copyright [yyyy] [name of copyright owner]
193
+
194
+ Licensed under the Apache License, Version 2.0 (the "License");
195
+ you may not use this file except in compliance with the License.
196
+ You may obtain a copy of the License at
197
+
198
+ http://www.apache.org/licenses/LICENSE-2.0
199
+
200
+ Unless required by applicable law or agreed to in writing, software
201
+ distributed under the License is distributed on an "AS IS" BASIS,
202
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
203
+ See the License for the specific language governing permissions and
204
+ limitations under the License.