@facto-to/design-system 0.1.0-beta.5 → 0.1.0-beta.7
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 +5 -1
- package/README.md +44 -4
- package/dist/ai/SKILL.md +5 -1
- package/dist/ai/references/api.d.ts +304 -91
- package/dist/ai/references/catalog.json +27 -2
- package/dist/ai/references/component-adoption.json +4 -0
- package/dist/ai/references/components.md +26 -0
- package/dist/ai/references/design.md +4 -2
- package/dist/ai/references/integration.md +1 -1
- package/dist/ai/references/standard-target.json +5 -0
- package/dist/ai/references/standard-version.json +9 -0
- package/dist/ai/references/tokens.css +2 -0
- package/dist/ai/references/ui-standard-reference.md +498 -0
- package/dist/ai/references/ui-standard.md +195 -0
- package/dist/ai/references/version.json +12 -3
- package/dist/index.d.ts +304 -91
- package/dist/index.js +845 -437
- package/dist/styles.css +1 -1
- package/dist/tokens.css +2 -0
- package/package.json +8 -4
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,7 +17,7 @@ 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
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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.
|
|
@@ -156,3 +158,41 @@ Both examples assume the named components are imported from `@facto-to/design-sy
|
|
|
156
158
|
## License
|
|
157
159
|
|
|
158
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.
|
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.
|
|
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.
|