@rxdrag/website-lib 0.0.151 → 0.0.153

package/components//345/216/237/345/255/220/345/206/273/347/273/223/346/270/205/345/215/225.md

@@ -1,260 +1,270 @@
-# 原子冻结清单（Frozen Atomic Layer）
-
-Frozen ≠ 不扩展，而是「语义与接口永不破坏」
-
-## 一、冻结的总体规则（先定宪法）
-
-以下 4 条，比具体组件更重要：
-
-### 1️⃣ 冻结的是「语义 + Props 结构」
-允许内部 Tailwind / DOM 变，不允许 Props 含义变化
-
-### 2️⃣ 冻结的是「层级关系」
-Section > Layout > Content > Action（永远不交叉）
-
-### 3️⃣ 冻结的是「参数空间」
-枚举值只加不改，默认值永不删除
-
-### 4️⃣ 冻结的是「AI 可操作边界」
-AI 只能改 frozen props，新能力通过新增原子，不改旧原子
-
----
-
-## 二、🧊 真正“永远不动”的原子（核心冻结层）
-
-> 语义和接口永不改变，AI 只能操作内容
-
-### 🧱 1. Structure (结构) - 绝对冻结
-
-**Section** ✅
-```ts
-interface SectionProps {
-  id?: string
-  tone?: "light" | "dark" | "brand"
-  density?: "compact" | "normal" | "relaxed"
-  maxWidth?: "sm" | "md" | "lg" | "xl" | "full"
-}
-```
-*原因：页面骨架，全站升级依赖它*
-
-**Container** ✅
-```ts
-interface ContainerProps {
-  size?: "sm" | "md" | "lg" | "xl"
-  align?: "left" | "center"
-}
-```
-*原因：限宽核心*
-
-**Main** ✅
-```ts
-interface MainProps {
-  class?: string
-  className?: string
-  backgrounds?: BackgroundConfig[]
-}
-```
-*原因：页面主内容区域，对应 `<main>` 标签，与 Header/Footer 平级，设计模式需独立渲染*
-
-### 🧱 2. Layout (布局) - 高优先冻结
-
-**Grid** ✅
-```ts
-interface GridProps {
-  cols?: Responsive<number>
-  gap?: GapToken
-  align?: "start" | "center" | "end"
-}
-```
-
-**Stack** ✅
-```ts
-interface StackProps {
-  direction?: "vertical" | "horizontal"
-  gap?: GapToken
-  align?: "start" | "center" | "end"
-}
-```
-
-**Split** ✅
-```ts
-interface SplitProps {
-  ratio?: "1:1" | "2:1" | "3:2"
-  reverse?: boolean
-}
-```
-
-### 🧱 3. Content (内容) - 语义冻结
-
-**Heading** ✅
-```ts
-interface HeadingProps {
-  level?: 1 | 2 | 3 | 4
-  emphasis?: "strong" | "normal" | "soft"
-}
-```
-
-**Text** ✅
-```ts
-interface TextProps {
-  size?: "sm" | "md" | "lg"
-  tone?: "normal" | "muted"
-}
-```
-
-**Media** ✅
-```ts
-interface MediaProps {
-  src: string
-  type?: "image" | "video"
-  ratio?: AspectRatio
-}
-```
-
-**Link** ✅
-```ts
-interface LinkProps {
-  href: string
-  external?: boolean
-  variant?: "default" | "muted" | "nav"
-}
-```
-
-### 🧱 4. Action (转化) - 转化冻结
-
-**Button / CTA** ✅
-```ts
-interface ButtonProps {
-  variant?: "primary" | "secondary" | "ghost"
-  size?: "sm" | "md" | "lg"
-}
-```
-
-### 🧱 5. Semantic & Form (业务冻结)
-
-**Feature** (卖点) ✅
-```ts
-interface FeatureProps {
-  title: string
-  description: string
-  icon?: string
-  emphasis?: "normal" | "strong"
-}
-```
-
-**SpecList / Table** (参数) ✅
-```ts
-interface SpecListProps { items: { label: string; value: string }[]; layout?: "list" | "grid" }
-interface TableProps { columns: any[]; rows: any[]; striped?: boolean }
-```
-
-**FAQ / Breadcrumb** (SEO) ✅
-*语义稳定，对应 Schema 结构*
-
-**Input / Select / Textarea** (询盘) ✅
-*HTML 表单标准语义*
-
----
-
-## 三、❄️ 半冻结原子（规则冻结，形态可扩）
-
-> 不允许破坏规则，但允许新增形态 (Variant)
-
-**Box** (装饰容器)
-*规则稳定 (padding/radius)，但 background 可扩*
-
-**Prose** (富文本)
-*Typography 规则稳定*
-
-**Spacer / Align / Divider**
-*空间规则稳定*
-
-**Badge / Icon**
-*基础元数据稳定，样式可扩*
-
-**LogoCloud / Testimonial / Rating / PriceTag**
-*信任组件，核心字段稳定，UI 风格可变*
-
----
-
-## 四、🔥 明确 “永远不冻结”的原子
-
-> 设计趋势变化快，形态多变，AI 需在受控范围操作
-
-- **❌ Repeat** (工具组件，render 不稳定)
-- **❌ Pagination** (交互多变)
-- **❌ Countdown** (样式多变)
-- **❌ Carousel / Tabs / Modal** (易滥用)
-- **❌ Animation** (装饰层)
-
-### Animation 治理规则（装饰层，不冻结）
-
-**使用方式**：直接在元素上写 `data-aos-*` 属性，无需 wrapper
-
-```html
-<h2 data-aos="fade-up">标题</h2>
-<p data-aos="fade-up" data-aos-delay="80">文案</p>
-<button data-aos="fade-up" data-aos-delay="160">按钮</button>
-```
-
-**可用字段**：
-- `data-aos`：动画类型（fade-up / fade-down / fade-left / fade-right / zoom-in / slide-up 等）
-- `data-aos-delay`：延迟（ms），用于 stagger 效果
-- `data-aos-duration`：持续时间（ms）
-- `data-aos-offset`：触发偏移（px）
-- `data-aos-easing`：缓动函数
-- `data-aos-once`：是否只播放一次
-
-**治理红线**（校验器守门）：
-- **禁止嵌套**：父子不能同时带 `data-aos`
-- **禁止首屏主 CTA**：hero 区域主按钮不加动画
-- **移动端降级**：≤768px 只允许 fade 系 + duration≤300ms
-- **支持全局关闭**：提供一键禁用开关
-
-**AI 约束**：
-- 只能改 `data-aos-*` 值
-- 不能把 Animation 升级为 frozen 原子
-
-原因
-
-- **设计趋势变化快**
-- **AI 容易滥用**
-- **对外贸转化非核心**
-
----
-
-## 五、冻结层的工程落地
-
-### 1️⃣ 在代码里显式标记
-
-```ts
-/**
- * @frozen
- * DO NOT CHANGE PROPS SEMANTICS
- */
-export interface SectionProps { ... }
-```
-
-### 2️⃣ 校验器规则（AI 守门）
-
-- **禁止删除 frozen props**
-- **禁止改 enum 含义**
-- **禁止替换 frozen component**
-
-### 3️⃣ 版本策略
-
-```txt
-frozenAtomsVersion: "1.x"
-```
-
----
-
-## 六、一句话总结
-
-你不是在做组件库，你是在做一套“**长期稳定的设计语言内核**”。
-
-这份冻结清单一旦立住：
-- **AI 永远不乱**
-- **模板永远可升级**
-- **客户永远可定制**
-- **系统越用越值钱**
+# 原子冻结清单（Frozen Atomic Layer）
+
+Frozen ≠ 不扩展，而是「语义与接口永不破坏」
+
+## 一、冻结的总体规则（先定宪法）
+
+以下 4 条，比具体组件更重要：
+
+### 1️⃣ 冻结的是「语义 + Props 结构」
+允许内部 Tailwind / DOM 变，不允许 Props 含义变化
+
+### 2️⃣ 冻结的是「层级关系」
+Section > Layout > Content > Action（永远不交叉）
+
+### 3️⃣ 冻结的是「参数空间」
+枚举值只加不改，默认值永不删除
+
+### 4️⃣ 冻结的是「AI 可操作边界」
+AI 只能改 frozen props，新能力通过新增原子，不改旧原子
+
+---
+
+## 二、🧊 真正“永远不动”的原子（核心冻结层）
+
+> 语义和接口永不改变，AI 只能操作内容
+
+### 🧱 1. Structure (结构) - 绝对冻结
+
+**Section** ✅
+```ts
+interface SectionProps {
+  id?: string
+  tone?: "light" | "dark" | "brand"
+  density?: "compact" | "normal" | "relaxed"
+  maxWidth?: "sm" | "md" | "lg" | "xl" | "full"
+}
+```
+*原因：页面骨架，全站升级依赖它*
+
+**Container** ✅
+```ts
+interface ContainerProps {
+  size?: "sm" | "md" | "lg" | "xl"
+  align?: "left" | "center"
+}
+```
+*原因：限宽核心*
+
+**Main** ✅
+```ts
+interface MainProps {
+  class?: string
+  className?: string
+  backgrounds?: BackgroundConfig[]
+}
+```
+*原因：页面主内容区域，对应 `<main>` 标签，与 Header/Footer 平级，设计模式需独立渲染*
+
+**Frame** ✅
+```ts
+interface FrameProps extends HTMLAttributes<HTMLTag> {
+  className?: string
+  backgrounds?: BackgroundConfig[]
+  tag?: string
+}
+```
+*原因：设计系统基础裁剪容器，负责 `relative isolate` 定位 + BackgroundGroup 渲染，通过 `tag` 可切换底层标签，所有需要背景层的容器都应基于 Frame*
+
+### 🧱 2. Layout (布局) - 高优先冻结
+
+**Grid** ✅
+```ts
+interface GridProps {
+  cols?: Responsive<number>
+  gap?: GapToken
+  align?: "start" | "center" | "end"
+}
+```
+
+**Stack** ✅
+```ts
+interface StackProps {
+  direction?: "vertical" | "horizontal"
+  gap?: GapToken
+  align?: "start" | "center" | "end"
+}
+```
+
+**Split** ✅
+```ts
+interface SplitProps {
+  ratio?: "1:1" | "2:1" | "3:2"
+  reverse?: boolean
+}
+```
+
+### 🧱 3. Content (内容) - 语义冻结
+
+**Heading** ✅
+```ts
+interface HeadingProps {
+  level?: 1 | 2 | 3 | 4
+  emphasis?: "strong" | "normal" | "soft"
+}
+```
+
+**Text** ✅
+```ts
+interface TextProps {
+  size?: "sm" | "md" | "lg"
+  tone?: "normal" | "muted"
+}
+```
+
+**Media** ✅
+```ts
+interface MediaProps {
+  src: string
+  type?: "image" | "video"
+  ratio?: AspectRatio
+}
+```
+
+**Link** ✅
+```ts
+interface LinkProps {
+  href: string
+  external?: boolean
+  variant?: "default" | "muted" | "nav"
+}
+```
+
+### 🧱 4. Action (转化) - 转化冻结
+
+**Button / CTA** ✅
+```ts
+interface ButtonProps {
+  variant?: "primary" | "secondary" | "ghost"
+  size?: "sm" | "md" | "lg"
+}
+```
+
+### 🧱 5. Semantic & Form (业务冻结)
+
+**Feature** (卖点) ✅
+```ts
+interface FeatureProps {
+  title: string
+  description: string
+  icon?: string
+  emphasis?: "normal" | "strong"
+}
+```
+
+**SpecList / Table** (参数) ✅
+```ts
+interface SpecListProps { items: { label: string; value: string }[]; layout?: "list" | "grid" }
+interface TableProps { columns: any[]; rows: any[]; striped?: boolean }
+```
+
+**FAQ / Breadcrumb** (SEO) ✅
+*语义稳定，对应 Schema 结构*
+
+**Input / Select / Textarea** (询盘) ✅
+*HTML 表单标准语义*
+
+---
+
+## 三、❄️ 半冻结原子（规则冻结，形态可扩）
+
+> 不允许破坏规则，但允许新增形态 (Variant)
+
+**Box** (装饰容器)
+*规则稳定 (padding/radius)，但 background 可扩*
+
+**Prose** (富文本)
+*Typography 规则稳定*
+
+**Spacer / Align / Divider**
+*空间规则稳定*
+
+**Badge / Icon**
+*基础元数据稳定，样式可扩*
+
+**LogoCloud / Testimonial / Rating / PriceTag**
+*信任组件，核心字段稳定，UI 风格可变*
+
+---
+
+## 四、🔥 明确 “永远不冻结”的原子
+
+> 设计趋势变化快，形态多变，AI 需在受控范围操作
+
+- **❌ Repeat** (工具组件，render 不稳定)
+- **❌ Pagination** (交互多变)
+- **❌ Countdown** (样式多变)
+- **❌ Carousel / Tabs / Modal** (交互逻辑复杂，易滥用)
+- **❌ Animation** (装饰层)
+
+### Animation 治理规则（装饰层，不冻结）
+
+**使用方式**：直接在元素上写 `data-aos-*` 属性，无需 wrapper
+
+```html
+<h2 data-aos="fade-up">标题</h2>
+<p data-aos="fade-up" data-aos-delay="80">文案</p>
+<button data-aos="fade-up" data-aos-delay="160">按钮</button>
+```
+
+**可用字段**：
+- `data-aos`：动画类型（fade-up / fade-down / fade-left / fade-right / zoom-in / slide-up 等）
+- `data-aos-delay`：延迟（ms），用于 stagger 效果
+- `data-aos-duration`：持续时间（ms）
+- `data-aos-offset`：触发偏移（px）
+- `data-aos-easing`：缓动函数
+- `data-aos-once`：是否只播放一次
+
+**治理红线**（校验器守门）：
+- **禁止嵌套**：父子不能同时带 `data-aos`
+- **禁止首屏主 CTA**：hero 区域主按钮不加动画
+- **移动端降级**：≤768px 只允许 fade 系 + duration≤300ms
+- **支持全局关闭**：提供一键禁用开关
+
+**AI 约束**：
+- 只能改 `data-aos-*` 值
+- 不能把 Animation 升级为 frozen 原子
+
+原因
+
+- **设计趋势变化快**
+- **AI 容易滥用**
+- **对外贸转化非核心**
+
+---
+
+## 五、冻结层的工程落地
+
+### 1️⃣ 在代码里显式标记
+
+```ts
+/**
+ * @frozen
+ * DO NOT CHANGE PROPS SEMANTICS
+ */
+export interface SectionProps { ... }
+```
+
+### 2️⃣ 校验器规则（AI 守门）
+
+- **禁止删除 frozen props**
+- **禁止改 enum 含义**
+- **禁止替换 frozen component**
+
+### 3️⃣ 版本策略
+
+```txt
+frozenAtomsVersion: "1.x"
+```
+
+---
+
+## 六、一句话总结
+
+你不是在做组件库，你是在做一套“**长期稳定的设计语言内核**”。
+
+这份冻结清单一旦立住：
+- **AI 永远不乱**
+- **模板永远可升级**
+- **客户永远可定制**
+- **系统越用越值钱**