@fangxinyan/lumina 0.6.2 → 0.6.4

package/dist/{tokens-BIIUTPKN.css → tokens-EF34LSWI.css}

@@ -20,42 +20,52 @@
 
   /* Distance multiplier — driven by ThemeProvider `intensity` (1..10 → 0.4..1.6). */
   --d: 1;
+  --shadow-scale: 1;
+  --shadow-float-scale: 1;
 
-  --shadow-blur: calc(16px * var(--d));
-  --shadow-offset: calc(6px * var(--d));
-  --shadow-inset-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(4px * var(--d));
+  --shadow-blur: calc(16px * var(--d) * var(--shadow-scale));
+  --shadow-offset: calc(6px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(4px * var(--d) * var(--shadow-scale));
 
-  --neu-out:
+  --neu-shadow-panel:
     var(--shadow-offset) var(--shadow-offset) var(--shadow-blur) var(--shadow-dark),
     calc(var(--shadow-offset) * -1) calc(var(--shadow-offset) * -1) var(--shadow-blur) var(--shadow-light);
 
-  --neu-out-sm:
+  --neu-shadow-control:
     calc(var(--shadow-offset) * 0.5) calc(var(--shadow-offset) * 0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-dark),
     calc(var(--shadow-offset) * -0.5) calc(var(--shadow-offset) * -0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-light);
 
-  --neu-out-lg:
+  --neu-shadow-lift:
     calc(var(--shadow-offset) * 1.6) calc(var(--shadow-offset) * 1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-dark),
     calc(var(--shadow-offset) * -1.6) calc(var(--shadow-offset) * -1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-light);
 
-  --neu-in:
+  --neu-shadow-inset-strong:
     inset var(--shadow-inset-offset) var(--shadow-inset-offset) var(--shadow-inset-blur) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -1) calc(var(--shadow-inset-offset) * -1) var(--shadow-inset-blur) var(--shadow-light);
 
-  --neu-in-sm:
+  --neu-shadow-inset:
     inset calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-light);
 
-  --neu-flat:
+  --neu-shadow-subtle:
     1px 1px 2px var(--shadow-dark),
     -1px -1px 2px var(--shadow-light);
 
   /* Floating-overlay elevation.
      No top-left highlight — there's no continuous surface beneath an overlay
      panel, so the neumorphic light-reflection metaphor would read as a halo. */
-  --neu-float:
-    0 calc(var(--shadow-offset) * 1.8) calc(var(--shadow-blur) * 2.2) var(--shadow-dark),
-    0 calc(var(--shadow-offset) * 0.4) calc(var(--shadow-blur) * 0.7) var(--shadow-dark);
+  --neu-shadow-float:
+    0 calc(var(--shadow-offset) * 1.8 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 2.2 * var(--shadow-float-scale)) var(--shadow-dark),
+    0 calc(var(--shadow-offset) * 0.4 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 0.7 * var(--shadow-float-scale)) var(--shadow-dark);
+
+  --neu-out: var(--neu-shadow-panel);
+  --neu-out-sm: var(--neu-shadow-control);
+  --neu-out-lg: var(--neu-shadow-lift);
+  --neu-in: var(--neu-shadow-inset-strong);
+  --neu-in-sm: var(--neu-shadow-inset);
+  --neu-flat: var(--neu-shadow-subtle);
+  --neu-float: var(--neu-shadow-float);
 
   /* ---- Accent (default sky) ---- */
   --accent: oklch(68% 0.14 235);
@@ -89,7 +99,13 @@
 
   /* ---- Control sizes (density) ---- */
   --ctrl-h: 40px;
+  --ctrl-h-sm: 30px;
+  --ctrl-h-lg: 52px;
+  --field-h-sm: 32px;
+  --field-h-lg: 48px;
   --ctrl-pad-x: 18px;
+  --ctrl-pad-x-sm: 12px;
+  --ctrl-pad-x-lg: 24px;
 
   /* ---- Type ---- */
   --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
@@ -97,6 +113,11 @@
                "Noto Sans CJK SC", sans-serif;
   --font-mono: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace;
   --font-display: "SF Pro Display", var(--font-sans);
+  --fs-xs: 11px;
+  --fs-sm: 12px;
+  --fs-md: 13px;
+  --fs-lg: 14px;
+  --fs-xl: 15px;
 
   /* ---- Motion ---- */
   --ease: cubic-bezier(0.22, 0.61, 0.36, 1);
@@ -123,13 +144,17 @@
   --shadow-dark: rgba(0, 0, 0, 0.55);
   --shadow-light: rgba(130, 145, 180, 0.06);
   /* 同时收紧阴影尺寸,深色模式下拟态更内敛 */
-  --shadow-offset: calc(4px * var(--d));
-  --shadow-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(3px * var(--d));
-  --shadow-inset-blur: calc(7px * var(--d));
+  --shadow-offset: calc(4px * var(--d) * var(--shadow-scale));
+  --shadow-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(3px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(7px * var(--d) * var(--shadow-scale));
   --accent-soft: oklch(35% 0.06 235);
   --accent-ink: oklch(82% 0.09 235);
   --accent-glow: oklch(68% 0.14 235 / 0.18);
+  --info:    oklch(78% 0.12 235);
+  --success: oklch(78% 0.14 150);
+  --warning: oklch(82% 0.14 75);
+  --danger:  oklch(76% 0.16 25);
 }
 
 /* 深色模式的 accent-glow 统一降低强度,避免按钮外圈过亮 */

package/dist/tokens.css

@@ -20,42 +20,52 @@
 
   /* Distance multiplier — driven by ThemeProvider `intensity` (1..10 → 0.4..1.6). */
   --d: 1;
+  --shadow-scale: 1;
+  --shadow-float-scale: 1;
 
-  --shadow-blur: calc(16px * var(--d));
-  --shadow-offset: calc(6px * var(--d));
-  --shadow-inset-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(4px * var(--d));
+  --shadow-blur: calc(16px * var(--d) * var(--shadow-scale));
+  --shadow-offset: calc(6px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(4px * var(--d) * var(--shadow-scale));
 
-  --neu-out:
+  --neu-shadow-panel:
     var(--shadow-offset) var(--shadow-offset) var(--shadow-blur) var(--shadow-dark),
     calc(var(--shadow-offset) * -1) calc(var(--shadow-offset) * -1) var(--shadow-blur) var(--shadow-light);
 
-  --neu-out-sm:
+  --neu-shadow-control:
     calc(var(--shadow-offset) * 0.5) calc(var(--shadow-offset) * 0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-dark),
     calc(var(--shadow-offset) * -0.5) calc(var(--shadow-offset) * -0.5) calc(var(--shadow-blur) * 0.6) var(--shadow-light);
 
-  --neu-out-lg:
+  --neu-shadow-lift:
     calc(var(--shadow-offset) * 1.6) calc(var(--shadow-offset) * 1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-dark),
     calc(var(--shadow-offset) * -1.6) calc(var(--shadow-offset) * -1.6) calc(var(--shadow-blur) * 1.4) var(--shadow-light);
 
-  --neu-in:
+  --neu-shadow-inset-strong:
     inset var(--shadow-inset-offset) var(--shadow-inset-offset) var(--shadow-inset-blur) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -1) calc(var(--shadow-inset-offset) * -1) var(--shadow-inset-blur) var(--shadow-light);
 
-  --neu-in-sm:
+  --neu-shadow-inset:
     inset calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-offset) * 0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-dark),
     inset calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-offset) * -0.6) calc(var(--shadow-inset-blur) * 0.6) var(--shadow-light);
 
-  --neu-flat:
+  --neu-shadow-subtle:
     1px 1px 2px var(--shadow-dark),
     -1px -1px 2px var(--shadow-light);
 
   /* Floating-overlay elevation.
      No top-left highlight — there's no continuous surface beneath an overlay
      panel, so the neumorphic light-reflection metaphor would read as a halo. */
-  --neu-float:
-    0 calc(var(--shadow-offset) * 1.8) calc(var(--shadow-blur) * 2.2) var(--shadow-dark),
-    0 calc(var(--shadow-offset) * 0.4) calc(var(--shadow-blur) * 0.7) var(--shadow-dark);
+  --neu-shadow-float:
+    0 calc(var(--shadow-offset) * 1.8 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 2.2 * var(--shadow-float-scale)) var(--shadow-dark),
+    0 calc(var(--shadow-offset) * 0.4 * var(--shadow-float-scale)) calc(var(--shadow-blur) * 0.7 * var(--shadow-float-scale)) var(--shadow-dark);
+
+  --neu-out: var(--neu-shadow-panel);
+  --neu-out-sm: var(--neu-shadow-control);
+  --neu-out-lg: var(--neu-shadow-lift);
+  --neu-in: var(--neu-shadow-inset-strong);
+  --neu-in-sm: var(--neu-shadow-inset);
+  --neu-flat: var(--neu-shadow-subtle);
+  --neu-float: var(--neu-shadow-float);
 
   /* ---- Accent (default sky) ---- */
   --accent: oklch(68% 0.14 235);
@@ -89,7 +99,13 @@
 
   /* ---- Control sizes (density) ---- */
   --ctrl-h: 40px;
+  --ctrl-h-sm: 30px;
+  --ctrl-h-lg: 52px;
+  --field-h-sm: 32px;
+  --field-h-lg: 48px;
   --ctrl-pad-x: 18px;
+  --ctrl-pad-x-sm: 12px;
+  --ctrl-pad-x-lg: 24px;
 
   /* ---- Type ---- */
   --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
@@ -97,6 +113,11 @@
                "Noto Sans CJK SC", sans-serif;
   --font-mono: ui-monospace, "SF Mono", "JetBrains Mono", Consolas, monospace;
   --font-display: "SF Pro Display", var(--font-sans);
+  --fs-xs: 11px;
+  --fs-sm: 12px;
+  --fs-md: 13px;
+  --fs-lg: 14px;
+  --fs-xl: 15px;
 
   /* ---- Motion ---- */
   --ease: cubic-bezier(0.22, 0.61, 0.36, 1);
@@ -123,13 +144,17 @@
   --shadow-dark: rgba(0, 0, 0, 0.55);
   --shadow-light: rgba(130, 145, 180, 0.06);
   /* 同时收紧阴影尺寸,深色模式下拟态更内敛 */
-  --shadow-offset: calc(4px * var(--d));
-  --shadow-blur: calc(10px * var(--d));
-  --shadow-inset-offset: calc(3px * var(--d));
-  --shadow-inset-blur: calc(7px * var(--d));
+  --shadow-offset: calc(4px * var(--d) * var(--shadow-scale));
+  --shadow-blur: calc(10px * var(--d) * var(--shadow-scale));
+  --shadow-inset-offset: calc(3px * var(--d) * var(--shadow-scale));
+  --shadow-inset-blur: calc(7px * var(--d) * var(--shadow-scale));
   --accent-soft: oklch(35% 0.06 235);
   --accent-ink: oklch(82% 0.09 235);
   --accent-glow: oklch(68% 0.14 235 / 0.18);
+  --info:    oklch(78% 0.12 235);
+  --success: oklch(78% 0.14 150);
+  --warning: oklch(82% 0.14 75);
+  --danger:  oklch(76% 0.16 25);
 }
 
 /* 深色模式的 accent-glow 统一降低强度,避免按钮外圈过亮 */

package/docs/llms/alert.md

@@ -22,12 +22,13 @@ import { Alert } from "@fangxinyan/lumina";
 <Alert tone="info" closable>仅一行的简短提示</Alert>
 ```
 
-### 隐藏图标
+### 图标控制
 
-showIcon={false} 可隐藏左侧语义图标,文本更紧凑。
+showIcon={false} 可隐藏左侧语义图标；icon 可传 IconName 或 ReactNode。
 
 ```tsx
 <Alert tone="info" showIcon={false}>纯文本提示</Alert>
+<Alert icon={<img src={iconUrl} alt="" />}>自定义图标</Alert>
 ```
 
 ### 自定义操作区
@@ -53,7 +54,7 @@ action 插槽可以放置按钮等操作元素,位于内容与关闭按钮之间
 | --- | --- | --- | --- |
 | tone | `"info" | "success" | "warning" | "danger"` | `"info"` | 语气 |
 | title | `ReactNode` | — | 标题 |
-| icon | `IconName` | — | 自定义图标 |
+| icon | `IconName | ReactNode` | — | 自定义图标,可传内置图标名或自定义节点 |
 | showIcon | `boolean` | `true` | 是否显示语义图标 |
 | action | `ReactNode` | — | 右侧操作区(如按钮) |
 | closable | `boolean` | `false` | 可关闭 |

package/docs/llms/button.md

@@ -23,12 +23,13 @@ import { Button } from "@fangxinyan/lumina";
 
 ### 图标按钮
 
-icon 在前,trailingIcon 在后。
+icon 在前,trailingIcon 在后,既支持内置 IconName,也支持外部 ReactNode。
 
 ```tsx
 <Button variant="primary" icon="sparkle">新建</Button>
 <Button icon="download">下载</Button>
 <Button trailingIcon="arrowRight">下一步</Button>
+<Button icon={<img src={iconUrl} alt="" />}>外部图标</Button>
 ```
 
 ### 加载与禁用
@@ -77,8 +78,8 @@ Button 在只有 icon 时自动呈现为方形按钮,常配合 tip 使用。
 | --- | --- | --- | --- |
 | variant | `"default" | "primary" | "ghost" | "danger"` | `"default"` | 按钮风格 |
 | size | `"sm" | "md" | "lg"` | `"md"` | 按钮尺寸 |
-| icon | `IconName` | — | 前置图标 |
-| trailingIcon | `IconName` | — | 后置图标 |
+| icon | `IconName | ReactNode` | — | 前置图标,可传内置图标名或自定义节点 |
+| trailingIcon | `IconName | ReactNode` | — | 后置图标,可传内置图标名或自定义节点 |
 | iconOnly | `boolean` | `自动` | 渲染为纯图标方形按钮 |
 | tip | `string` | — | 原生悬浮提示,常用于纯图标按钮 |
 | loading | `boolean` | `false` | 加载态 |

package/docs/llms/cascader.md

@@ -12,6 +12,8 @@ import { Cascader } from "@fangxinyan/lumina";
 
 ### 基础用法
 
+option.icon 支持 IconName 或 ReactNode。
+
 ```tsx
 <Cascader options={regions} value={addr} onChange={setAddr} />
 ```
@@ -38,6 +40,7 @@ showSearch 开启路径搜索,allowClear 提供一键清空,popupClassName 可
 | Prop | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
 | options \* | `CascaderOption[]` | — | 层级选项树 |
+| options[].icon | `IconName | ReactNode` | — | 选项前置图标,可传内置图标名或自定义节点 |
 | value / defaultValue | `string[]` | — | 受控/初始路径 |
 | onChange | `(path: string[]) => void` | — | 选择叶子时触发 |
 | placeholder | `string` | — | 占位文案 |

package/docs/llms/image.md

@@ -5,7 +5,7 @@
 ## 导入
 
 ```tsx
-import { Image, ImageGrid } from "@fangxinyan/lumina";
+import { Image, ImageGrid, SpriteImage, LayeredImage } from "@fangxinyan/lumina";
 ```
 
 ## 示例
@@ -16,10 +16,43 @@ import { Image, ImageGrid } from "@fangxinyan/lumina";
 <Image src={url} width={240} height={160} />
 ```
 
+### 图标 / 原始资源
+
+variant="icon" 会默认去掉外层 padding,适合 1:1 装备、物品、头像缩略图；variant="raw" 保留原始图片比例。
+
+```tsx
+<Image variant="icon" src={iconUrl} width={56} height={56} preview={false} />
+<Image variant="raw" src={bannerUrl} width={220} height={84} objectFit="contain" />
+```
+
+### Sprite 裁剪
+
+SpriteImage 用 background-position 裁剪同一张雪碧图,适合 url + x/y/width/height 形式的图标资源。
+
+```tsx
+<SpriteImage src={sheetUrl} sprite={{ x: 32, y: 0, width: 32, height: 32 }} />
+```
+
+### 多图层图片
+
+LayeredImage 将多张图片叠在同一个盒子里,适合头像 + 头像框、底图 + 标记等资产。
+
+```tsx
+<LayeredImage
+  width={72}
+  height={72}
+  layers={[
+    { src: headUrl, fit: "cover" },
+    { src: frameUrl },
+  ]}
+/>
+```
+
 ### 图片组
 
 ```tsx
 <ImageGrid images={images} />
+<ImageGrid images={icons} imageProps={{ variant: "icon", preview: false }} />
 ```
 
 ## API
@@ -30,9 +63,47 @@ import { Image, ImageGrid } from "@fangxinyan/lumina";
 | --- | --- | --- | --- |
 | src | `string` | — | 图片 URL |
 | width / height | `number | string` | — | 尺寸 |
+| variant | `"framed" | "raw" | "icon"` | `"framed"` | 视觉形态 |
+| frame | `boolean` | `framed 时 true` | 是否保留内层凹陷 frame |
+| padding | `number | string` | — | 外层留白,raw/icon 默认 0 |
+| objectFit / objectPosition | `CSSProperties` | — | 底层 img 的 object-fit / object-position |
 | preview | `boolean` | `true` | 支持点击全屏预览 |
 | hover | `boolean` | `true` | 悬浮放大 |
 | placeholder | `ReactNode` | — | 占位/错误时内容 |
+| imgProps | `ImgHTMLAttributes` | — | 透传到底层 img 的属性 |
+
+
+**ImageGrid**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| images \* | `ImageGridItem[]` | — | 图片项数组,单项也可覆盖 Image props |
+| columns | `number` | — | 固定列数,不传则自动填充 |
+| itemHeight | `number` | `130` | 默认图片高度 |
+| minItemWidth | `number | string` | `160` | 自动填充时的最小列宽 |
+| gap | `number | string` | `14` | 网格间距 |
+| imageProps | `ImageProps` | — | 批量传给每个 Image 的属性 |
+
+
+**SpriteImage**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| src \* | `string` | — | sprite sheet 图片 URL |
+| sprite \* | `{ x; y; width; height }` | — | 裁剪区域 |
+| width / height | `number | string` | — | 渲染尺寸,默认使用 sprite 尺寸 |
+| scale | `number` | `1` | 未指定 width/height 时的缩放倍数 |
+| backgroundSize | `string` | — | 自定义 background-size |
+| variant / frame / padding | `ImageVariant / boolean / number` | — | 同 Image 的媒体外观控制 |
+
+
+**LayeredImage**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| layers \* | `LayeredImageLayer[]` | — | 按顺序叠放的图片层 |
+| width / height | `number | string` | — | 容器尺寸 |
+| variant / frame / padding | `ImageVariant / boolean / number` | — | 同 Image 的媒体外观控制 |
 
 
 ---

package/docs/llms/input.md

@@ -24,10 +24,11 @@ const [v, setV] = useState("");
 
 ### 前后置图标
 
-leadingIcon / trailingIcon。
+leadingIcon / trailingIcon 支持内置 IconName 或外部 ReactNode。
 
 ```tsx
 <Input placeholder="搜索..." leadingIcon="search" />
+<Input placeholder="物品名" leadingIcon={<img src={iconUrl} alt="" />} />
 ```
 
 ### Input.Password
@@ -106,7 +107,7 @@ Input.TextArea 与 Textarea 使用同一套多行输入能力,也支持 allowCle
 | onChange | `(event) => void` | — | 变更回调,传入 React 原生事件 |
 | onValueChange | `(value: string, event) => void` | — | 值回调便捷写法 |
 | placeholder | `string` | — | 占位文案 |
-| leadingIcon / trailingIcon | `IconName` | — | 前/后置图标 |
+| leadingIcon / trailingIcon | `IconName | ReactNode` | — | 前/后置图标,可传内置图标名或自定义节点 |
 | prefix | `ReactNode` | — | 左侧内嵌内容(在 leadingIcon 之后) |
 | suffix | `ReactNode` | — | 右侧内嵌内容(在 trailingIcon 之前) |
 | allowClear | `boolean` | `false` | 显示内置的清除按钮 |

package/docs/llms/select.md

@@ -29,7 +29,7 @@ multiple + Tag 形式呈现已选项。
 
 ### 搜索过滤
 
-searchable + clearable + 选项 icon/description。
+searchable + clearable + 选项 icon/description。icon 支持 IconName 或 ReactNode。
 
 ```tsx
 <Select searchable clearable
@@ -110,7 +110,7 @@ loading 时显示 spinner,emptyContent 自定义空态。
 | --- | --- | --- | --- |
 | value \* | `T` | — | 值 |
 | label | `ReactNode` | — | 显示 |
-| icon | `IconName` | — | 前置图标 |
+| icon | `IconName | ReactNode` | — | 前置图标,可传内置图标名或自定义节点 |
 | description | `ReactNode` | — | 次要描述 |
 | disabled | `boolean` | `false` | 禁用项 |
 

package/docs/llms/surface.md

@@ -0,0 +1,90 @@
+# Surface 背景面
+
+> 主题感知的背景承载容器,用于给特殊色调内容提供正确的拟态 token 语境。
+
+## 导入
+
+```tsx
+import { Surface, SURFACE_THEME_PRESETS } from "@fangxinyan/lumina";
+```
+
+## 示例
+
+### 基础承载
+
+默认继承外部主题,只提供一片稳定的拟态背景。
+
+```tsx
+<Surface padding="lg" radius="xl">
+  <Card title="运行概览" description="Surface 负责外部背景,Card 负责信息分组">
+    <Button variant="primary">开始</Button>
+  </Card>
+</Surface>
+```
+
+### 内置背景预设
+
+preset 会建立一套局部 ThemeProvider,子组件和 useTheme 都处在这套背景 token 下。
+
+```tsx
+<Surface preset="graphite" padding="lg" radius="xl">
+  <Button variant="primary">深色面板</Button>
+</Surface>
+
+<Surface preset="porcelain" padding="lg" radius="xl">
+  <Input placeholder="清亮浅色面板" />
+</Surface>
+```
+
+### 背景语义
+
+tone 只切换背景槽位;适合在同一主题里区分基底、凸起、凹陷和强调底。
+
+```tsx
+<Surface tone="base">base</Surface>
+<Surface tone="raised">raised</Surface>
+<Surface tone="sunken">sunken</Surface>
+<Surface tone="accent">accent</Surface>
+```
+
+### 自定义局部主题
+
+可直接传 mode、accent、tokens 等主题参数。themeRadius 控制子树 token, radius 控制 Surface 自身圆角。
+
+```tsx
+<Surface
+  mode="dark"
+  accent="mint"
+  themeRadius={18}
+  tokens={{
+    bg: "#171d20",
+    "bg-raised": "#20282c",
+    "bg-sunken": "#101517",
+  }}
+>
+  <Card>...</Card>
+</Surface>
+```
+
+## API
+
+**Surface**
+
+| Prop | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| preset | `"inherit" | "mist" | "porcelain" | "graphite" | "ember"` | `"inherit"` | 内置局部背景预设 |
+| tone | `"base" | "raised" | "sunken" | "accent"` | `"base"` | 可见背景槽位 |
+| variant | `"plain" | "raised" | "sunken" | "floating"` | `"plain"` | Surface 自身拟态层级 |
+| padding | `"none" | "sm" | "md" | "lg" | "xl"` | `"md"` | 内边距 |
+| radius | `"none" | "sm" | "md" | "lg" | "xl"` | `"lg"` | Surface 自身圆角 |
+| height | `"content" | "fill" | "screen"` | `"content"` | 高度语义 |
+| bordered | `boolean` | `false` | 显示 token 描边 |
+| scrollable | `boolean` | `false` | 受限高度下允许内部滚动 |
+| mode / colorScheme / accent | `ThemeConfig fields` | — | 局部主题深浅色与强调色 |
+| density / intensity / themeRadius / font | `ThemeConfig fields` | — | 局部密度、阴影、主题圆角和字体 |
+| tokens | `ThemeTokens` | — | 局部 CSS token 覆写 |
+| themes | `ThemePresets` | — | 局部自定义模式注册表 |
+
+
+---
+[← 回到索引](../llms.md)

package/docs/llms/tag.md

@@ -34,11 +34,12 @@ dot 渲染前置色块。
 
 ### 前置图标
 
-icon 使用内置 Icon 组件,颜色随语气自动适配。
+icon 可传内置 IconName 或自定义 ReactNode,颜色随语气自动适配。
 
 ```tsx
 <Tag tone="success" icon="check2">已完成</Tag>
 <Tag tone="info" icon="star">推荐</Tag>
+<Tag icon={<img src={iconUrl} alt="" />}>物品</Tag>
 ```
 
 ### 无边框
@@ -67,7 +68,7 @@ removable + onRemove 实现关闭按钮。
 | tone | `"neutral" | "accent" | "info" | "success" | "warning" | "danger"` | `"neutral"` | 色调 |
 | solid | `boolean` | `false` | 实心填充 |
 | dot | `boolean` | `false` | 前置圆点 |
-| icon | `IconName` | — | 前置图标 |
+| icon | `IconName | ReactNode` | — | 前置图标,可传内置图标名或自定义节点 |
 | bordered | `boolean` | `true` | 是否显示外框 flat 阴影 |
 | removable | `boolean` | `false` | 显示 × |
 | onRemove | `() => void` | — | 关闭回调 |