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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,195 @@
1
+ # Facto UI Standard — 简明执行规范
2
+
3
+ **设计规则 v1.2 · 文档修订 v1.2.24 · 公开版1 · 2026-09-29**
4
+
5
+ 用于 Facto 的 Dashboard、管理端、开发者端、登录/Hosted 流程和 Web Demo。目标:**清楚、克制、一致,桌面、平板和手机都可读、可操作。** 借鉴 Link 的层级与比例,采用 Facto 自己的设计值;不要求像素复制 Link,也不代表第三方认证。原生 App 另设平台规范。
6
+
7
+ **当前有效入口:** 本文件与同版附录。旧 v1.0/v1.1、审计草案及历史截图只作追溯;不要从旧报告复制设计值。项目采用时固定规则版本与文档修订号。
8
+
9
+ **阅读方式:** 先读本文件即可确定常用设计;实施时按下文链接查询涉及的状态或组件细节。[详细附录](ui-standard-reference.md) 收录完整规则,与主文共同构成同一标准。v1.2统一常规输入的白底深色单层焦点,并定义公共组件的多端及几何验收;这不是产品通过声明。不得凭摘要猜测缺失规则。
10
+
11
+ **公共适用边界(1.2.24):** 本标准只规定可公共化的字体、字重、色彩、间距、表面、组件状态、多端适配、可访问性和验收证据。页面业务状态、卡计划归并、支付路径、认证提交策略和分页查询规则不属于公共UI标准,由各应用在自己的仓库中定义。业务场景资料不随公共包分发。公共组件接收展示状态和动作,由业务层决定含义与触发。
12
+
13
+ ## 1. 第一原则:UI 优化不改逻辑和 API
14
+
15
+ - **允许:** 字体、颜色、间距、尺寸、边框、圆角、图标尺寸、对齐、响应式排版,以及不改变语义与操作结果的展示标记/class。
16
+ - **禁止借 UI 修改:** 计算/格式化、权限/鉴权、校验、可见/可用条件、disabled 条件、state/effect/hook、事件、焦点管理、路由、存储、feature flag、SDK,以及 API/RPC/订阅的参数、次数、顺序、触发、取消或重试。
17
+ - **保留组件身份:** 不改有状态组件的类型、key、挂载条件/数量、provider 或 portal 边界;不用“两套组件分别隐藏”实现响应式。
18
+ - **布局也要验证:** 隐藏、裁切、重排、固定定位、层级、点击区域、wrapper、表单关联及 label/ARIA 的改动,要检查键盘/触控、焦点、滚动和副作用。
19
+ - **超出范围的缺陷:** 若必须改逻辑/API,记录为 `OUT-OF-SCOPE-OPEN`;不能偷偷修,也不能标为通过。
20
+
21
+ 本条适用于 UI-only 工作。明确授权的业务开发按其独立需求处理。完整边界见 [附录:边界](ui-standard-reference.md#boundaries)。
22
+
23
+ ## 2. 在不同 Facto 前端中怎么用
24
+
25
+ SDK 同步不移植 Dashboard 的路由、鉴权或业务组件。每次 SDK 发布均固定准确包版本与本标准文档修订;构建和产物/资源完整性检查后,分别复核桌面、手机、键盘及减弱动效路径,并在独立安装该包的消费者中验证。同步 SDK 随包提供的 skill/reference;Dashboard 验收证据不能代替 SDK 或消费者通过结论。
26
+
27
+ 新组件按本规范设计;既有 Demo 按组件逐步迁移。共享样式改动必须检查所有受影响页面。特殊变体需记录名字、用途、数值和验证结果,不靠页面选择器形成隐形例外。采用记录与例外规则见 [附录](ui-standard-reference.md#adoption)。
28
+
29
+ ## 3. 常用视觉数值
30
+
31
+ 尺寸均为 **100% 缩放、根字号16px时的 CSS px**。高度是最小值,不是裁字的固定高度;文字变大或换行时允许增长。字体优先 `rem`,行高随文字增长。
32
+
33
+ ### 字体
34
+
35
+ Latin 用 **Inter**,中文/日文等用系统字体回退;验证字体实际加载。常规字重只用400/500/600,不把全部标签加粗。字距默认0;页面标题/金额可登记 −0.02em 展示变体。
36
+
37
+ | 用途 | 字号 / 行高 | 字重 |
38
+ |---|---:|---:|
39
+ | 页面标题 | 24 / 32 | 600 |
40
+ | 外壳页头 / 默认 Sheet 标题 | 20 / 28 | 600 |
41
+ | 区块标题 | 16 / 24 | 600 |
42
+ | 设置分组名,如 Profile | 13 / 20 | 600 |
43
+ | 设置项名称 / 设置值 | 16 / 24 | 500 / 400 |
44
+ | 输入文字 | 16 / 24 | 400 |
45
+ | 正文、说明、错误、表格值 | 14 / 20 | 400 |
46
+ | 外置字段标签、数据标签、常规操作 | 14 / 20 | 500 |
47
+ | 浮动标签、状态标签、表头 | 12 / 16 | 500 |
48
+ | 次要时间等元信息 | 12 / 16 | 400 |
49
+ | 舒适主操作 | 16 / 24 | 500 |
50
+ | 摘要金额 | 28 / 36 | 600 |
51
+ | 连续阅读正文 / 代码 | 16 / 28、13 / 20 | 400 |
52
+
53
+ 主内容宽小于600时,外壳页头可用18/28/600;不是把所有标题一起缩小。完整角色见 [字体附录](ui-standard-reference.md#typography)。
54
+
55
+ ### 颜色
56
+
57
+ 以下按用途映射为 token,不在每个页面重复硬编码。相同色值也保留独立用途,例如链接、成功和焦点。
58
+
59
+ | 用途 | 浅色配方 |
60
+ |---|---|
61
+ | 画布 / 主内容面 / 次级面 | `#f5f5f4` / `#ffffff` / `#f3f3f2` |
62
+ | 主文字 / 辅助文字 | `#121411` / `#62655f` |
63
+ | 主按钮底 / 文字 | `#171716` / `#ffffff` |
64
+ | 主按钮 hover / pressed | `#2c2e2a` / `#080908` |
65
+ | 次按钮底 / 文字 / 边框 | `#f3f3f2` / `#121411` / transparent |
66
+ | 次按钮 hover / pressed | `#eaeae7` / `#ddded9` |
67
+ | 链接 / 选中标记底 | `#0b6b4b`;选中标记文字为白色 |
68
+ | 焦点 | `#121411`;输入为内描边,非输入键盘焦点为外轮廓 |
69
+ | 成功文字 / 底色 | `#0b6b4b` / `#e7fbf2` |
70
+ | 警告文字 / 底色 | `#805300` / `#fff7df` |
71
+ | 错误文字 / 底色 | `#9f2333` / `#fff0f2` |
72
+ | 信息文字 / 底色 | `#175c9c` / `#eaf3fb` |
73
+ | 装饰分隔线 | `#e7e7e5`;不适用于中性填充输入默认态 |
74
+ | 中性填充输入默认底 / 边框 | `#f5f5f5` / transparent |
75
+ | 禁用文字 / 底色 / 边框 | `#62655f` / `#eaeae7` / `#e7e7e5` |
76
+ | 品牌亮绿 | `#00d64f`,用于克制强调,不默认搭配白字 |
77
+
78
+ 文字通常至少4.5:1,识别控件/状态所需的非文字视觉至少3:1;装饰线不等于控件边界。文字已清晰可辨的按钮外围不因3:1而一概补边框。彩色背景、透明色及品牌卡面重新测量;状态不能只靠颜色。危险按钮、链接/控件各状态及例外条件查询 [完整色彩配方](ui-standard-reference.md#colors)。
79
+
80
+ ### 间距与表面
81
+
82
+ | 用途 | 默认值 |
83
+ |---|---|
84
+ | 常用空间尺度 | 4 / 8 / 12 / 16 / 20 / 24 / 32;大区块40 / 48 / 64 |
85
+ | 标签到说明 / 外置标签到输入 | 4 / 8 |
86
+ | 字段纵向 / 两列字段间 / 段落间 | 16 / 12 / 16 |
87
+ | 分组标题到卡片 / 卡片之间 / 区块之间 | 12 / 16 / 32 |
88
+ | 页面水平留白 | 24;主内容宽小于600时16 |
89
+ | 卡片内边距 | 24;compact变体20;主内容宽小于600时均为16 |
90
+ | 设置行 | 内边距16,图标/内容/尾部间16;单行最小56,带说明最小80 |
91
+ | 表单 / 数据工作区 / 阅读列最大宽 | 640 / 1280 / 72ch |
92
+ | 控件 / 卡片 / 弹窗圆角 | 12 / 16 / 24;按钮与badge为pill |
93
+ | 普通卡片 / 浮层 | 卡片无阴影;浮层阴影 `0 8px 32px rgba(18,20,17,.12)` |
94
+ | 遮罩 | `rgba(18,20,17,.32)` |
95
+
96
+ “小于600”看**可用主内容或声明的父容器宽度**,不包含侧栏;嵌套卡片不重复添加页面留白。标题、字段、列表沿同一阅读轴。独立登录/Hosted表单采用居中变体。[详细布局条件](ui-standard-reference.md#spacing)。
97
+
98
+ ## 4. 组件默认配方
99
+
100
+ | 组件 | 尺寸与排版 |
101
+ |---|---|
102
+ | 普通按钮 / 独立文字操作 | 最小高40(精细指针)/44(触控或混合),14/20/500,padding 8 16 |
103
+ | 登录、Hosted、主表单提交 | 最小高52,16/24/500,padding 12 24 |
104
+ | 图标按钮 / 关闭或返回 | 交互目标44;可见图形按16/20/24图标配方,圆形底面为具名变体;静态为安静灰色,无常显深色轮廓 |
105
+ | 普通输入 | 最小高44,16/24/400,padding 8 12,圆角12 |
106
+ | Select定位 | 触发器最小高44;菜单与触发器间距8,按可用空间翻转和限制高度;宽度按内容登记,不覆盖触发器或裁切选项 |
107
+ | 自定义 Select 菜单 | 容器 padding12、圆角12、共享浮层阴影;选项最小44、padding 8 12、14/20/500 |
108
+ | 浮动标签输入 | 最小高60,标签12/16/500、输入16/24/400;标签和值分别留足空间 |
109
+ | Switch / checkbox / radio | 点击目标44×44;原生switch轨道34×20、白色滑块16、checked `#00d66f`。滑块位移只用一种机制;在开发与交付构建中实测checked/unchecked、enabled/disabled的最终`translate`与`transform`,确认滑块完全在轨道内;不套用文字input规则。 |
110
+ | Badge | 12/16/500,padding 4 8,默认不可操作 |
111
+ | Tabs / 导航 / 菜单项 | 默认目标44;选中、焦点、当前项可辨,不只靠色差 |
112
+ | 数据表 | 表头12/16/500、值14/20/400;行最小48、padding 12 16,数字右对齐 |
113
+ | 空态 / 错误 / 加载说明 | 标题16/24/600、说明14/20/400;内容gap8,操作gap16 |
114
+ | Banner / Toast | padding 12 16、gap8、圆角12;正文14/20。Toast统一fixed右上,桌面top/right24、最大宽420;窄屏top16(兼顾safe-area)、占满扣除页面gutter后的可用宽度,左右沿用--space-4(16px)并兼顾safe-area;内部横向padding16,有限高度内换行/滚动。不得插入root布局行、改变页面底色,或盖住已开Modal的footer/唯一操作或焦点;窄屏Modal在完整scrim内顶部预留反馈空间。时长由反馈类型与采用者配置;UI-only迁移保留已有时长。 |
115
+
116
+ 提醒按任务重要性排列,不能被长列表推到页面底部;关键阻断异常须直接说明影响与下一步;补充原因可展开,触控和键盘须有等价入口。手机列表的状态和日期必须以文字/图标等可读信息保留,不能只剩颜色点。长 URL/地址在值列换行或可滚动,不改原字符串、缩写或格式化。先调整展示位置与换行,不改变状态判断、文案来源或点击结果。
117
+
118
+ compact按钮36及紧凑表格等,只用于明确无触控需求的fine+hover场景,需登记变体;不按“屏幕大”自动启用。表格可在自己的区域横滚,金额、币种、费用、末四位和操作含义不能被裁掉、缩成小字或只能hover查看。不改舍入、地址缩写或格式化算法来解决排版。
119
+
120
+ 按钮按角色取色:主操作黑色、次操作浅灰、危险操作暗红,禁用共享灰。常规操作均为pill与14/20/500;角色不要求同色或同宽,宽度按文案和任务内容自然确定。loading/disabled不得改变按钮形状。
121
+
122
+ 每个组件都检查已有的 default、hover、pressed、focus、selected、disabled、loading、invalid 状态;保留readonly与disabled的区别。常规文本输入、搜索、textarea、原生/自定义select默认`#f5f5f5`、透明边框;焦点为白底单层2px深色内描边、`outline-offset:-2px`且无阴影。复合输入只在整组外壳画一层。checkbox/radio/switch、range、color、file及按钮型input按各自配方,不套用文本输入的灰底/白底规则。按钮等非输入仅keyboard focus为2px深色外轮廓、外距2px且无重复阴影;深色背景的白色隔离例外须实测登记。forced-colors使用Highlight;invalid+focus仍须同时清楚表达错误;不改变状态的语义标签或绿色品牌/成功映射。无文字按钮需有可理解名称,Tooltip不承载唯一关键信息。具体控件查 [控件附录](ui-standard-reference.md#controls);图表、日志、队列、第三方控件等查 [组件族附录](ui-standard-reference.md#families),不直接套一个通用卡片了事。
123
+
124
+ ### 弹窗:容器 padding 统一20px
125
+
126
+ | 类型 | 最大宽 | 内部 padding | 标题 |
127
+ |---|---:|---:|---|
128
+ | 紧凑 Dialog建议起点 | 400,按内容登记变体 | 20 | 20/28/600 |
129
+ | 详情 Drawer | 480 | 24;窄内容20 | 20/28/600 |
130
+ | Popover | 默认320 | 12 | 正文14/20 |
131
+
132
+ - Modal容器边框到标题、正文、按钮的内边距四周统一20;窄屏不降到16。新产品可从紧凑400开始;改变宽度须说明内容理由并复核桌面与窄屏实际结果,不按“复杂任务”自动取560,也不因安全任务自动增大标题。平板分屏按实际可用宽度处理。底部安全区按实际需要额外计入一次。
133
+ - 屏幕到浮层的外侧留白是另一项:浮动弹窗至少16,加上对应安全区;已有移动端贴底Sheet保留原有贴边形态。
134
+ - 弹窗header单行布局基准32,标题和关闭图形垂直居中;长标题或文字放大时自然增高,不锁死height;极端长标题可在自身区域滚动,须保留正文空间。标题只在实际溢出时加入Tab序列并可用键盘滚动;不溢出不新增Tab stop。44点击区上下可各扩出6,不参与撑高header,也不得覆盖正文控件。header/body/footer默认间距20。字段纵向16;两列内容不足332时单列。
135
+ - footer普通单按钮按内容宽靠右;全宽操作作为具名变体登记。多按钮空间不足时纵排,不按“弹窗小于400”一律拉满。新组合gap12,既有具名变体另验;标题可换行,不锁固定总高度。
136
+ - 关闭和返回保留原生按钮语义与44点击目标;可见圆圈28分别贴齐正文的右、左边缘,透明点击区向现有padding扩展,不制造8px视觉缩进。返回圆圈到标题间距16。
137
+ - 同级审阅内容块间距统一16,不混用15;header/body/footer分区仍按20。普通Dialog默认不显示FACTO kicker;仅调用方显式传入且确有语义时显示。
138
+ - 长内容有明确滚动区;短屏仍由内部滚动保证正文、footer和关闭可达。检查嵌套菜单、弹窗和Toast共存:Toast不盖footer、不制造backdrop空区。关闭后跨 resize 恢复仍可见的等价 opener;若原 opener 不可见或不可用,则恢复到 main 或页面 heading。不得靠任意增大z-index或重建portal解决问题。
139
+
140
+ 浮层层级与高风险内容规则见 [浮层附录](ui-standard-reference.md#overlays)。
141
+
142
+ ## 5. 多端适配:分别看四件事
143
+
144
+ 菜单尾部使用固定容器,状态点有无不影响chevron横坐标。设置的短标签/值保持同行;真实长值可换行,但尾部chevron/复制图标独立占列。只读邮箱不伪装可点击。页头随文字放大自然增高;帮助页脚在短页靠底、长页随内容滚动,不遮挡菜单。
145
+
146
+ 底部滑入作为可选Sheet动效变体,适用范围、时长和验收以附录R06a为准;不强制全部弹窗采用。
147
+
148
+ | 决定因素 | 要求 |
149
+ |---|---|
150
+ | 可用宽度 | 先减少列数、再换行;不用整体缩小字体维持桌面布局 |
151
+ | 输入方式 | iPad、触屏笔记本、鼠标平板都可能是混合输入;触控目标至少44,重要操作不依赖hover |
152
+ | 可用高度 | 横屏、短窗口、软键盘出现时,内容与提交/关闭操作仍可滚动到达;安全区只计算一次 |
153
+ | 内容压力 | 长姓名/邮箱/地址、多语言、大金额、多行错误、空/加载/失败状态都能容纳 |
154
+
155
+ 检查过程中还要旋转、resize和分屏;已输入内容不丢失,不出现双导航、重复请求、残留遮罩或滚动锁死。Hosted 行内 `a` 如承担按钮布局,须保持连续可点击承载面,不能因 inline 布局断开背景。高对比模式保留选中和焦点;reduce-motion去掉非必要动画,但不改业务计时。[完整响应式要求](ui-standard-reference.md#responsive)。
156
+
157
+ ## 6. 如何验收,才可以说“完成”
158
+
159
+ 1. **先列清单:** 对账在范围内的页面、组件变体、已有状态和共享消费者;每项对应测试或写明排除原因。登录、资金、安全、权限等核心任务及失败恢复不能漏掉。
160
+ 2. **用真实组件做Mock:** 固定数据与状态,从真实路由操作。启动前对HTTP/RPC/WebSocket/SSE、导航和第三方请求建立精确allowlist,其他请求分派前拦截;写入仅在隔离环境精确模拟,未知请求记缺口,不发真实邮件、不连生产钱包或后端。
161
+ 3. **检查实际页面:** 基础宽/中/窄样本为1440×900、834×1194、390×844;另查320、短高横屏、实际断点前/中/后与连续宽度。区分触控/鼠标/键盘,不能用一个尺寸代替全部。
162
+ 4. **检查可读与可操作:** 键盘、滚动、200%文字、320 reflow、文字间距压力、实际支持的主题和系统辅助模式分别验证。真实浏览器缩放、CSS字体压力与真机测试不是同一种证据。
163
+ 5. **保留证据:** 截图 + computed style/geometry + 交互断言,并记录源码/fixture版本、环境、网络/存储行为、重跑命令。基线与候选用相同数据和动作比较;空白页、class匹配或axe零告警不能算通过。
164
+ 6. **做工程与视觉复核:** 跑目标项目实际的typecheck/lint/build和相关测试,审查diff确保逻辑/API不变;主审与独立审查者对照宽/中/窄实图检查层级、对齐、密度和状态。
165
+
166
+ 这是阅读入口,**完整必测矩阵、case字段、计数与门槛仍按 [验收附录](ui-standard-reference.md#acceptance) 执行**。缺fixture/设备/浏览器,或测试中断,均保留为 `UNVERIFIED`;不能删除漏项后宣称“全部通过”。
167
+
168
+ 报告分开写:①改了什么;②逻辑/API是否保持;③哪些Mock/浏览器/真机已通过;④哪些未验证或超范围。**规范文档就绪、UI-only安全、产品验收是三个结论**;只有完成声明范围内全部必测项,且没有未解决缺陷或未验证项,才能声称该范围通过。批准的设计例外另列,不能豁免逻辑边界或真实可访问性缺陷。[完整判定](ui-standard-reference.md#governance)。
169
+
170
+ ## 7. 可直接交给 AI 的任务模板
171
+
172
+ ```text
173
+ 基于 Facto UI Standard 规则v1.2(文档修订v1.2.24)优化 <目标项目/app/页面> 的 UI。
174
+ 先读简明执行规范,再按涉及组件查阅详细附录。
175
+ 保留现有框架、业务逻辑、API、交互结果;不新增主题、不强制换库。
176
+ 先盘点页面/组件/状态、共享消费者、允许修改的文件,列出现状问题。
177
+ 按统一字体、颜色、间距和组件配方,完成本次已授权的视觉修改。
178
+ 覆盖桌面、平板、手机、混合输入、长内容和核心任务状态。
179
+ 用真实组件与隔离Mock验收,检查逻辑/API非回归和最终diff。
180
+ 交付修改摘要、可操作预览、验收证据、已通过范围和未验证项。
181
+ ```
182
+
183
+ 需要理解设计来源时,再读 [公开参考与证据边界](ui-standard-reference.md#sources)。日常实施不需要从旧审计报告拼接规则。
184
+
185
+ ## 8. 1.2.24修订与采用
186
+
187
+ 本版收敛公共规范,Dashboard业务场景和采用记录移至独立文档。公共验收不依赖特定页面、provider或API状态。字体/字重、色彩/对比、间距/密度、组件状态、响应式布局、键盘/触控/辅助技术及可重跑证据为核心维度。
188
+
189
+ 常规弹窗以内容决定最大宽度;窄宿主可使用具名全宽Sheet,宽宿主使用居中Dialog。采用者登记断点、宽度、内距、滚动和安全区;不因名为iPad或PC推断输入方式。不把Dashboard的400px宽度和700px断点强制给全部消费者。错误若需要用户处理,应在相关区域持续可见,单次变化只使用一个自动播报渠道。业务提交和冷却策略由场景规范决定。
190
+
191
+ 文档修订不等于产品或SDK通过;组件、消费者与场景分别验收。历史修订内容见采用记录,不作为并行规则。
192
+
193
+
194
+
195
+ 本版维护规则:此公开规范与SDK组件采用状态分别版本化;消费者按安装包元数据判断实际支持范围。
@@ -1,11 +1,20 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "package": "@facto-to/design-system",
4
- "packageVersion": "0.1.0-beta.6",
4
+ "packageVersion": "0.1.0-beta.8",
5
5
  "peerDependencies": {
6
6
  "react": "^19.0.0",
7
7
  "react-dom": "^19.0.0"
8
8
  },
9
- "apiSha256": "315045b5fcd7259485085df7b3795228e9c947f2b9d6a81bf90847e087fb0426",
9
+ "standard": {
10
+ "rulesVersion": "1.2",
11
+ "documentRevision": "1.2.24",
12
+ "publicEdition": 1,
13
+ "componentAdoption": {
14
+ "documentRevision": "1.2.21",
15
+ "scope": "Existing component baseline only; public standard 1.2.24 is a target, not a full adoption claim."
16
+ }
17
+ },
18
+ "apiSha256": "9a691d648e97a4088c1fba21c102bdbc14531e7985d620a201a6ef449cd884e9",
10
19
  "tokensSha256": "87694ef0c56c366f356f781ccc9860f390017f852726ddd3f29caf59545cdca9"
11
20
  }
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import * as react from 'react';
2
- import { ImgHTMLAttributes, ReactNode, HTMLAttributes, MouseEventHandler, AnchorHTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, SVGProps, TextareaHTMLAttributes } from 'react';
2
+ import { ReactNode, HTMLAttributes, RefObject, ImgHTMLAttributes, MouseEventHandler, AnchorHTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, SVGProps, TextareaHTMLAttributes } from 'react';
3
3
  import * as PopoverPrimitive from '@radix-ui/react-popover';
4
4
  import * as MenuPrimitive from '@radix-ui/react-dropdown-menu';
5
5
  import * as TooltipPrimitive from '@radix-ui/react-tooltip';
@@ -9,6 +9,79 @@ import * as DialogPrimitive from '@radix-ui/react-dialog';
9
9
  import * as SwitchPrimitive from '@radix-ui/react-switch';
10
10
  import * as TabsPrimitive from '@radix-ui/react-tabs';
11
11
 
12
+ /** Auto enables motion while respecting the operating system's reduced-motion preference. */
13
+ type MotionMode = 'auto' | 'none';
14
+ /** Shared presentation timings in milliseconds, independent of application timing. */
15
+ declare const motionTokens: {
16
+ readonly duration: {
17
+ readonly feedback: 160;
18
+ readonly content: 180;
19
+ readonly surface: 220;
20
+ readonly overlay: 240;
21
+ };
22
+ readonly easing: {
23
+ readonly standard: "cubic-bezier(.22, 1, .36, 1)";
24
+ };
25
+ };
26
+ declare function useMotion(override?: MotionMode): {
27
+ motion: MotionMode;
28
+ reduced: boolean;
29
+ enabled: boolean;
30
+ };
31
+ /** Nest to override a section. The display-contents boundary adds no layout box. */
32
+ declare function FactoMotionProvider({ motion, children }: {
33
+ motion?: MotionMode;
34
+ children: ReactNode;
35
+ }): react.JSX.Element;
36
+
37
+ type MotionOverride = 'auto' | 'none';
38
+ interface StepTransitionProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
39
+ stepKey: string | number;
40
+ children: ReactNode;
41
+ motion?: MotionOverride;
42
+ }
43
+ /** Replaces step content immediately while coordinating the surrounding height. */
44
+ declare function StepTransition({ stepKey, children, motion, className, ...props }: StepTransitionProps): react.JSX.Element;
45
+ interface AnimatedDisclosureProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
46
+ open: boolean;
47
+ children: ReactNode;
48
+ motion?: MotionOverride;
49
+ }
50
+ /** Controlled region whose closed content is immediately removed from keyboard navigation. */
51
+ declare function AnimatedDisclosure({ open, children, motion, className, ...props }: AnimatedDisclosureProps): react.JSX.Element;
52
+ interface AnimatedFeedbackProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
53
+ show: boolean;
54
+ children: ReactNode;
55
+ motion?: MotionOverride;
56
+ }
57
+ /** Controlled feedback presentation; consumer validation and alert semantics change synchronously. */
58
+ declare function AnimatedFeedback({ show, children, motion, className, role, ...props }: AnimatedFeedbackProps): react.JSX.Element;
59
+ interface ContentRevealProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
60
+ children: ReactNode;
61
+ ready?: boolean;
62
+ motion?: MotionOverride;
63
+ }
64
+ /** Reveals only when pending content becomes ready; later content updates remain still. */
65
+ declare function ContentReveal({ children, ready, motion, className, ...props }: ContentRevealProps): react.JSX.Element;
66
+
67
+ type ListMotionKey = string | number;
68
+ /**
69
+ * Applies FLIP movement to rows with a `data-list-motion-key` matching an item key.
70
+ * Rows removed by React are never retained for an exit animation.
71
+ */
72
+ declare function useKeyedListMotion<Key extends ListMotionKey>(rootRef: RefObject<HTMLElement | null>, itemKeys: readonly Key[], { motion }?: {
73
+ motion?: MotionMode;
74
+ }): void;
75
+ interface SelectionMotionProps extends HTMLAttributes<HTMLDivElement> {
76
+ /** Overrides the nearest Facto motion setting for this visual treatment. */
77
+ motion?: MotionMode;
78
+ }
79
+ /**
80
+ * Positions a decorative surface beneath the selected descendant. Selection and
81
+ * keyboard behavior remain the responsibility of the controls it contains.
82
+ */
83
+ declare function SelectionMotion({ motion, className, children, ...props }: SelectionMotionProps): react.JSX.Element;
84
+
12
85
  interface ListRowSlots {
13
86
  leading?: ReactNode;
14
87
  title: ReactNode;
@@ -191,12 +264,13 @@ type FactoThemeTokens = Partial<Record<`--facto-${string}`, string | number>>;
191
264
  type ThemeTokens = FactoThemeTokens;
192
265
  interface FactoThemeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
193
266
  /** Scoped overrides; unspecified tokens inherit the dashboard defaults or parent theme. */
267
+ motion?: MotionMode;
194
268
  tokens?: FactoThemeTokens;
195
269
  /** Inline styles take precedence over the tokens prop. */
196
270
  style?: CSSProperties & Partial<ThemeTokens>;
197
271
  }
198
272
  /** Scoped token container. Inline `--facto-*` values are forwarded to portalled overlays. */
199
- declare function FactoTheme({ className, tokens, style, ...props }: FactoThemeProps): react.JSX.Element;
273
+ declare function FactoTheme({ className, tokens, style, motion, ...props }: FactoThemeProps): react.JSX.Element;
200
274
  /** Shared decorative symbols; name the containing control, not the glyph. */
201
275
  type IconName = 'close' | 'arrowLeft' | 'check' | 'chevronDown' | 'chevronRight' | 'info' | 'warning' | 'plus' | 'chevronLeft' | 'copy' | 'search';
202
276
  interface IconProps extends SVGProps<SVGSVGElement> {
@@ -215,6 +289,7 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
215
289
  size?: ButtonSize;
216
290
  fullWidth?: boolean;
217
291
  /** Shows a non-interactive progress indicator and disables the control. */
292
+ motion?: MotionMode;
218
293
  loading?: boolean;
219
294
  leadingIcon?: ReactNode;
220
295
  trailingIcon?: ReactNode;
@@ -294,6 +369,8 @@ interface SelectProps {
294
369
  placeholder?: string;
295
370
  label?: ReactNode;
296
371
  error?: ReactNode;
372
+ /** Opt in to a visible control border; default is borderless. */
373
+ bordered?: boolean;
297
374
  disabled?: boolean;
298
375
  name?: string;
299
376
  id?: string;
@@ -302,7 +379,7 @@ interface SelectProps {
302
379
  className?: string;
303
380
  }
304
381
  /** Controlled or uncontrolled Radix select. Use `options` for stable value/label pairs. */
305
- declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
382
+ declare function Select({ options, value, defaultValue, onValueChange, placeholder, label, error, disabled, bordered, name, id, ariaLabel, 'aria-describedby': ariaDescribedBy, className, }: SelectProps): react.JSX.Element;
306
383
  interface SwitchProps extends Omit<ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>, 'children'> {
307
384
  label?: ReactNode;
308
385
  description?: ReactNode;
@@ -328,10 +405,11 @@ declare const DialogDescription: typeof DialogPrimitive.Description;
328
405
  type OverlayMotionVariant = 'auto' | 'bottom' | 'none';
329
406
  interface DialogContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
330
407
  size?: 'sm' | 'md';
408
+ motion?: MotionMode;
331
409
  motionVariant?: OverlayMotionVariant;
332
410
  }
333
411
  /** Focus-managed modal content. Place title and description inside for accessible announcements. */
334
- declare function DialogContent({ size, motionVariant, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
412
+ declare function DialogContent({ size, motionVariant, motion, className, style, children, ...props }: DialogContentProps): react.JSX.Element;
335
413
  declare const Sheet: react.FC<DialogPrimitive.DialogProps>;
336
414
  declare const SheetTrigger: react.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
337
415
  declare const SheetClose: react.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
@@ -339,10 +417,11 @@ declare const SheetTitle: react.ForwardRefExoticComponent<Omit<DialogPrimitive.D
339
417
  declare const SheetDescription: react.ForwardRefExoticComponent<DialogPrimitive.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>>;
340
418
  interface SheetContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
341
419
  side?: 'center' | 'right' | 'bottom';
420
+ motion?: MotionMode;
342
421
  motionVariant?: OverlayMotionVariant;
343
422
  }
344
423
  /** Focus-managed side or mobile-bottom sheet. */
345
- declare function SheetContent({ side, motionVariant, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
424
+ declare function SheetContent({ side, motionVariant, motion, className, style, children, ...props }: SheetContentProps): react.JSX.Element;
346
425
  interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
347
426
  width?: string | number;
348
427
  height?: string | number;
@@ -386,11 +465,12 @@ declare function TooltipContent({ variant, className, style, sideOffset, collisi
386
465
  /** Dashboard notifications default to 2.6 seconds. */
387
466
  declare function ToastProvider({ duration, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Provider>): react.JSX.Element;
388
467
  interface ToastProps extends ComponentPropsWithRef<typeof ToastPrimitive.Root> {
468
+ motion?: MotionMode;
389
469
  icon?: ReactNode;
390
470
  tone?: NoticeTone;
391
471
  }
392
472
  /** Controlled or uncontrolled notification. Render a ToastViewport inside the provider. */
393
- declare function Toast({ tone, icon, className, style, children, ...props }: ToastProps): react.JSX.Element;
473
+ declare function Toast({ tone, icon, className, style, motion, children, ...props }: ToastProps): react.JSX.Element;
394
474
  declare function ToastTitle({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Title>): react.JSX.Element;
395
475
  declare function ToastDescription({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Description>): react.JSX.Element;
396
476
  declare function ToastAction({ className, ...props }: ComponentPropsWithRef<typeof ToastPrimitive.Action>): react.JSX.Element;
@@ -432,5 +512,5 @@ interface ListSkeletonProps extends HTMLAttributes<HTMLDivElement> {
432
512
  /** Loading placeholder only: consumers own the query and loading state. */
433
513
  declare function ListSkeleton({ rows, label, className, ...props }: ListSkeletonProps): react.JSX.Element;
434
514
 
435
- export { Avatar, Badge, Button, Card, Checkbox, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptyState, EnhancedSearchField, ErrorState, FactoTheme, Field, FilterChip, Icon, IconButton, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, Popover, PopoverClose, PopoverContent, PopoverTrigger, ResendCodeButton, SearchField, Select, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, Surface, Switch, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Widget, WidgetAction, WidgetAmount, WidgetHeader, WidgetKeyValue, WidgetList, WidgetRow, useToast };
436
- export type { AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, DialogContentProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };
515
+ export { AnimatedDisclosure, AnimatedFeedback, Avatar, Badge, Button, Card, Checkbox, ContentReveal, DashboardGrid, Dialog, DialogClose, DialogContent, DialogDescription, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptyState, EnhancedSearchField, ErrorState, FactoMotionProvider, FactoTheme, Field, FilterChip, Icon, IconButton, ListGroup, ListRow, ListSkeleton, LoadingMore, LogoStack, ModalFooter, ModalHeader, Notice, NotificationsProvider, OtpInput, Popover, PopoverClose, PopoverContent, PopoverTrigger, ResendCodeButton, SearchField, Select, SelectionMotion, Sheet, SheetClose, SheetContent, SheetDescription, SheetTitle, SheetTrigger, Skeleton, Stack, StepChecklist, StepTransition, Surface, Switch, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, Toast, ToastAction, ToastClose, ToastDescription, ToastProvider, ToastTitle, ToastViewport, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Widget, WidgetAction, WidgetAmount, WidgetHeader, WidgetKeyValue, WidgetList, WidgetRow, motionTokens, useKeyedListMotion, useMotion, useToast };
516
+ export type { AnimatedDisclosureProps, AnimatedFeedbackProps, AvatarProps, BadgeProps, BadgeTone, ButtonProps, ButtonSize, ButtonVariant, CheckboxProps, ContentRevealProps, DialogContentProps, EmptyStateProps, EnhancedSearchFieldProps, ErrorStateProps, FactoThemeProps, FactoThemeTokens, FieldProps, FilterChipProps, IconButtonProps, IconName, IconProps, ListGroupProps, ListRowButtonProps, ListRowLinkProps, ListRowProps, ListRowSlots, ListRowStaticProps, ListSkeletonProps, LoadingMoreProps, LogoStackItem, LogoStackProps, MotionMode, MotionOverride, NoticeProps, NoticeTone, NotificationsProviderProps, OtpInputProps, OverlayMotionVariant, ResendCodeButtonProps, SearchFieldProps, SelectItem, SelectProps, SelectionMotionProps, SheetContentProps, SkeletonProps, StackProps, StepChecklistItem, StepChecklistProps, StepChecklistState, StepTransitionProps, SurfaceProps, SwitchProps, TextFieldProps, TextareaProps, ToastActionOptions, ToastApi, ToastId, ToastOptions, ToastPromiseMessages, ToastProps, ToastTone, ToastUpdate, TooltipContentProps, WidgetActionButtonProps, WidgetActionLinkProps, WidgetActionProps, WidgetHeaderProps, WidgetProps };