@dsh-plugin/dsh-ui-components 0.0.1 → 0.1.0-dev.43613492370

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026, dsh-ui-components contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026, dsh-ui-components contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -1,21 +1,21 @@
-/* dsh-ui-components 第三方组件声明
- *
- * 本包在运行期依赖以下第三方作品，按其许可证要求在此声明来源与授权：
- *
- * 1. IconPark（@icon-park/react 1.4.2，Apache License 2.0）
- *    https://github.com/bytedance/IconPark
- *    本包 src/icons/ 下的 2658 个图标模块由脚本从该包的 es/icons/ 于安装时
- *    直接转导出，不复制其源码；src/icons-index.ts 的图标元数据由该包
- *    icons.json 生成。图标图形的著作权归 IconPark 及其贡献者所有。
- *    消费方使用本包即同时受 Apache License 2.0 约束，该许可证全文见
- *    https://www.apache.org/licenses/LICENSE-2.0
- *
- * 2. Arco Design（@arco-design/web-react 2.66.18，MIT License）
- *    https://github.com/arco-design/arco-design
- *    本包不复制、不打包 Arco 源码，仅在运行期通过 @dsh-plugin/dsh-loader
- *    提供的 Arco 单例使用其组件，并以 CSS 变量重绑的方式覆盖其外观。
- *
- * 3. DeepSeek Harness 设计令牌（--dsw-*）
- *    令牌名称与取值来自 DSH 源码 packages/client/ui-theme/src/styles/。
- *    本包只引用变量名并附带回退值，不内联其样式表。
- */
+/* dsh-ui-components 第三方组件声明
+ *
+ * 本包在运行期依赖以下第三方作品，按其许可证要求在此声明来源与授权：
+ *
+ * 1. IconPark（@icon-park/react 1.4.2，Apache License 2.0）
+ *    https://github.com/bytedance/IconPark
+ *    本包 src/icons/ 下的 2658 个图标模块由脚本从该包的 es/icons/ 于安装时
+ *    直接转导出，不复制其源码；src/icons-index.ts 的图标元数据由该包
+ *    icons.json 生成。图标图形的著作权归 IconPark 及其贡献者所有。
+ *    消费方使用本包即同时受 Apache License 2.0 约束，该许可证全文见
+ *    https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * 2. Arco Design（@arco-design/web-react 2.66.18，MIT License）
+ *    https://github.com/arco-design/arco-design
+ *    本包不复制、不打包 Arco 源码，仅在运行期通过 @dsh-plugin/dsh-loader
+ *    提供的 Arco 单例使用其组件，并以 CSS 变量重绑的方式覆盖其外观。
+ *
+ * 3. DeepSeek Harness 设计令牌（--dsw-*）
+ *    令牌名称与取值来自 DSH 源码 packages/client/ui-theme/src/styles/。
+ *    本包只引用变量名并附带回退值，不内联其样式表。
+ */

package/README.md

@@ -1,136 +1,136 @@
-<div align="center">
-
-# dsh-ui-components
-
-**A React component library that restyles Arco Design with DeepSeek Harness design tokens and exposes the full IconPark icon set by name.**
-
-English | [简体中文](README.zh_CN.md)
-
-</div>
-
-## What this is
-
-Plugins in the DSH family each hand-roll their own buttons, inputs and dialogs, so the same product ends up with three different border radii. This package is the shared answer: the semantics and keyboard behavior of [Arco Design](https://arco.design), skinned with the DeepSeek Harness `--dsw-*` design tokens, plus the [IconPark](https://iconpark.oceanengine.com) icon set.
-
-It ships as an unbundled ESM source library. Your plugin's bundler inlines it, so React and Arco stay the single instances the host already owns, and no CSS pipeline is needed on your side.
-
-## Install
-
-```sh
-npm install @dsh-plugin/dsh-ui-components
-```
-
-`react`, `react-dom` and `@dsh-plugin/dsh-loader` are peer dependencies; the host provides all three.
-
-## Use
-
-Wrap your plugin's React root once, then import components from the package root.
-
-```tsx
-import { DshProvider, Card, Field, Input, Button, Switch } from '@dsh-plugin/dsh-ui-components'
-
-export function SettingsPage() {
-  return (
-    <DshProvider>
-      <Card title="Proxy">
-        <Field label="Host" description="Affects requests made through global fetch." htmlFor="host">
-          <Input id="host" mono placeholder="127.0.0.1" />
-        </Field>
-        <Field label="Enabled" layout="inline">
-          <Switch defaultChecked />
-        </Field>
-        <Button variant="primary">Save</Button>
-      </Card>
-    </DshProvider>
-  )
-}
-```
-
-`DshProvider` injects the skin, mounts icon defaults, and routes every Arco overlay through a container that carries the same CSS variables. Components render without it, but popups would then attach to `body` and lose the skin.
-
-In your `tsdown` config, keep these three external:
-
-```js
-const CLIENT_EXTERNALS = [
-  'react',
-  'react/jsx-runtime',
-  'react-dom',
-  'react-dom/client',
-  '@dsh-plugin/dsh-loader/client',
-]
-```
-
-## Theming
-
-Colours are not configurable props and do not need to be. The skin is a single CSS variable bridge that rebinds Arco's own variables onto DSH semantic tokens, so light and dark follow the host's `body[data-ds-dark-theme]` attribute with no JavaScript involved and no theme branching in component code.
-
-The bridge sits on a `.dsh-ui` class rather than on `body`, which keeps the host's own Arco theme untouched. `scripts/verify-tokens.mjs` checks every host variable referenced by this package against the host stylesheets, so a rename in DSH fails offline instead of silently dropping styles.
-
-## Icons
-
-Three channels, because inlining all 2658 icons into every plugin would be indefensible:
-
-```tsx
-// 1. Curated set, intent-named (~110 icons, tree-shaken to what you use)
-import { Icon, Icons } from '@dsh-plugin/dsh-ui-components'
-<Icon name="Settings" size={18} />
-<Icons.GitBranch />
-
-// 2. Any of the 2658 icons, by subpath — only that icon enters your bundle
-import Rocket from '@dsh-plugin/dsh-ui-components/icons/Rocket'
-<Icon of={Rocket} size={18} />
-
-// 3. Full metadata for pickers and search, imports no icon modules
-import { ICON_INDEX } from '@dsh-plugin/dsh-ui-components/icons-index'
-```
-
-Subpath names are the PascalCase form of the IconPark name: `a-cane` is `ACane`, `setting` is `Setting`. Every entry in `ICON_INDEX` carries `name`, `pascal`, `title`, `titleZh`, `category`, `tags` and `rtl`.
-
-Icons inherit `currentColor`, so they follow the surrounding text colour automatically.
-
-## Components
-
-| Group | Exports |
-|---|---|
-| Foundation | `DshProvider`, `Icon`, `Icons`, `ICON_NAMES`, `DshIconProvider`, `G`, `cx`, `ICON_INDEX` |
-| Buttons | `Button`, `IconButton` |
-| Inputs | `Input`, `Textarea`, `InputNumber`, `Select`, `AutoComplete` |
-| Toggles | `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `Switch`, `Slider`, `Rate` |
-| Form | `Form`, `FormItem`, `Field` |
-| Display | `Card`, `Tag`, `Pill`, `Avatar`, `Badge`, `Divider`, `Descriptions`, `Typography`, `Text`, `Paragraph`, `Empty`, `Skeleton`, `Spin`, `Tooltip`, `Popover`, `HoverCard`, `Collapse`, `CollapseItem` |
-| Feedback | `Alert`, `Progress`, `Result`, `Popconfirm`, `Modal`, `confirm`, `Drawer`, `Message`, `Notification`, `message`, `messageSuccess`, `messageError`, `messageWarning` |
-| Navigation | `Menu`, `MenuItem`, `Dropdown`, `Tabs`, `TabPane`, `Breadcrumb`, `BreadcrumbItem`, `Pagination`, `Steps`, `Step`, `SegmentedControl`, `DisclosureRow`, `StateDot` |
-| Data | `Table`, `List`, `ListItem`, `Tree`, `DatePicker`, `TimePicker`, `Cascader`, `TreeSelect`, `Transfer`, `Statistic`, `Timeline`, `TimelineItem`, `Calendar`, `Carousel`, `Image` |
-| DSH composites | `SettingsCard`, `SettingsRow`, `PanelShell`, `MenuSelect`, `JsonTree`, `CodeBlockShell`, `FileTypeBadge`, `StatusLine` |
-
-Every control forwards native props and `className`, so escaping the defaults never requires forking a component.
-
-`SettingsCard` + `SettingsRow` render the host's settings-page card. `PanelShell` is a plain overlay shell that already satisfies the 120px top and bottom margin rule and scrolls its body through the host's `Scrollbar`. `MenuSelect` is the self-drawn dropdown for settings pages, where a native `<select>` popup cannot follow the DSH theme.
-
-## Preview
-
-```sh
-npm run gen:tokens   # copy the host token sheets into docs/preview/
-npm run preview      # http://localhost:5178
-```
-
-The preview site renders every component against the host's own token values, with a light/dark switch and a searchable index over all 2658 icons. It reads the package source directly, so a change shows up on refresh without a build.
-
-## Development
-
-```sh
-npm install
-npm run gen:icons     # regenerate the 2658 icon modules and metadata
-npm run typecheck
-npm run build
-npm test
-npm run verify        # token names, icon channels, literal colours, package size
-```
-
-`npm run verify:tokens` needs the DSH host stylesheets. Point `DSH_UI_THEME_DIR` at `packages/client/ui-theme/src/styles` of a DSH checkout, or keep one at `.dsh/temp/session-tree-harness` in the parent directory.
-
-See [PLAN.md](PLAN.md) for the batch scope and current progress, and [docs/tokens.md](docs/tokens.md) for the token mapping table.
-
-## License
-
-MIT. IconPark artwork is Apache-2.0; see [NOTICE](NOTICE).
+<div align="center">
+
+# dsh-ui-components
+
+**A React component library that restyles Arco Design with DeepSeek Harness design tokens and exposes the full IconPark icon set by name.**
+
+English | [简体中文](README.zh_CN.md)
+
+</div>
+
+## What this is
+
+Plugins in the DSH family each hand-roll their own buttons, inputs and dialogs, so the same product ends up with three different border radii. This package is the shared answer: the semantics and keyboard behavior of [Arco Design](https://arco.design), skinned with the DeepSeek Harness `--dsw-*` design tokens, plus the [IconPark](https://iconpark.oceanengine.com) icon set.
+
+It ships as an unbundled ESM source library. Your plugin's bundler inlines it, so React and Arco stay the single instances the host already owns, and no CSS pipeline is needed on your side.
+
+## Install
+
+```sh
+npm install @dsh-plugin/dsh-ui-components
+```
+
+`react`, `react-dom` and `@dsh-plugin/dsh-loader` are peer dependencies; the host provides all three.
+
+## Use
+
+Wrap your plugin's React root once, then import components from the package root.
+
+```tsx
+import { DshProvider, Card, Field, Input, Button, Switch } from '@dsh-plugin/dsh-ui-components'
+
+export function SettingsPage() {
+  return (
+    <DshProvider>
+      <Card title="Proxy">
+        <Field label="Host" description="Affects requests made through global fetch." htmlFor="host">
+          <Input id="host" mono placeholder="127.0.0.1" />
+        </Field>
+        <Field label="Enabled" layout="inline">
+          <Switch defaultChecked />
+        </Field>
+        <Button variant="primary">Save</Button>
+      </Card>
+    </DshProvider>
+  )
+}
+```
+
+`DshProvider` injects the skin, mounts icon defaults, and routes every Arco overlay through a container that carries the same CSS variables. Components render without it, but popups would then attach to `body` and lose the skin.
+
+In your `tsdown` config, keep these three external:
+
+```js
+const CLIENT_EXTERNALS = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@dsh-plugin/dsh-loader/client',
+]
+```
+
+## Theming
+
+Colours are not configurable props and do not need to be. The skin is a single CSS variable bridge that rebinds Arco's own variables onto DSH semantic tokens, so light and dark follow the host's `body[data-ds-dark-theme]` attribute with no JavaScript involved and no theme branching in component code.
+
+The bridge sits on a `.dsh-ui` class rather than on `body`, which keeps the host's own Arco theme untouched. `scripts/verify-tokens.mjs` checks every host variable referenced by this package against the host stylesheets, so a rename in DSH fails offline instead of silently dropping styles.
+
+## Icons
+
+Three channels, because inlining all 2658 icons into every plugin would be indefensible:
+
+```tsx
+// 1. Curated set, intent-named (~110 icons, tree-shaken to what you use)
+import { Icon, Icons } from '@dsh-plugin/dsh-ui-components'
+<Icon name="Settings" size={18} />
+<Icons.GitBranch />
+
+// 2. Any of the 2658 icons, by subpath — only that icon enters your bundle
+import Rocket from '@dsh-plugin/dsh-ui-components/icons/Rocket'
+<Icon of={Rocket} size={18} />
+
+// 3. Full metadata for pickers and search, imports no icon modules
+import { ICON_INDEX } from '@dsh-plugin/dsh-ui-components/icons-index'
+```
+
+Subpath names are the PascalCase form of the IconPark name: `a-cane` is `ACane`, `setting` is `Setting`. Every entry in `ICON_INDEX` carries `name`, `pascal`, `title`, `titleZh`, `category`, `tags` and `rtl`.
+
+Icons inherit `currentColor`, so they follow the surrounding text colour automatically.
+
+## Components
+
+| Group | Exports |
+|---|---|
+| Foundation | `DshProvider`, `Icon`, `Icons`, `ICON_NAMES`, `DshIconProvider`, `G`, `cx`, `ICON_INDEX` |
+| Buttons | `Button`, `IconButton` |
+| Inputs | `Input`, `Textarea`, `InputNumber`, `Select`, `AutoComplete` |
+| Toggles | `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `Switch`, `Slider`, `Rate` |
+| Form | `Form`, `FormItem`, `Field` |
+| Display | `Card`, `Tag`, `Pill`, `Avatar`, `Badge`, `Divider`, `Descriptions`, `Typography`, `Text`, `Paragraph`, `Empty`, `Skeleton`, `Spin`, `Tooltip`, `Popover`, `HoverCard`, `Collapse`, `CollapseItem` |
+| Feedback | `Alert`, `Progress`, `Result`, `Popconfirm`, `Modal`, `confirm`, `Drawer`, `Message`, `Notification`, `message`, `messageSuccess`, `messageError`, `messageWarning` |
+| Navigation | `Menu`, `MenuItem`, `Dropdown`, `Tabs`, `TabPane`, `Breadcrumb`, `BreadcrumbItem`, `Pagination`, `Steps`, `Step`, `SegmentedControl`, `DisclosureRow`, `StateDot` |
+| Data | `Table`, `List`, `ListItem`, `Tree`, `DatePicker`, `TimePicker`, `Cascader`, `TreeSelect`, `Transfer`, `Statistic`, `Timeline`, `TimelineItem`, `Calendar`, `Carousel`, `Image` |
+| DSH composites | `SettingsCard`, `SettingsRow`, `PanelShell`, `MenuSelect`, `JsonTree`, `CodeBlockShell`, `FileTypeBadge`, `StatusLine` |
+
+Every control forwards native props and `className`, so escaping the defaults never requires forking a component.
+
+`SettingsCard` + `SettingsRow` render the host's settings-page card. `PanelShell` is a plain overlay shell that already satisfies the 120px top and bottom margin rule and scrolls its body through the host's `Scrollbar`. `MenuSelect` is the self-drawn dropdown for settings pages, where a native `<select>` popup cannot follow the DSH theme.
+
+## Preview
+
+```sh
+npm run gen:tokens   # copy the host token sheets into docs/preview/
+npm run preview      # http://localhost:5178
+```
+
+The preview site renders every component against the host's own token values, with a light/dark switch and a searchable index over all 2658 icons. It reads the package source directly, so a change shows up on refresh without a build.
+
+## Development
+
+```sh
+npm install
+npm run gen:icons     # regenerate the 2658 icon modules and metadata
+npm run typecheck
+npm run build
+npm test
+npm run verify        # token names, icon channels, literal colours, package size
+```
+
+`npm run verify:tokens` needs the DSH host stylesheets. Point `DSH_UI_THEME_DIR` at `packages/client/ui-theme/src/styles` of a DSH checkout, or keep one at `.dsh/temp/session-tree-harness` in the parent directory.
+
+See [PLAN.md](PLAN.md) for the batch scope and current progress, and [docs/tokens.md](docs/tokens.md) for the token mapping table.
+
+## License
+
+MIT. IconPark artwork is Apache-2.0; see [NOTICE](NOTICE).

package/README.zh_CN.md

@@ -1,136 +1,136 @@
-<div align="center">
-
-# dsh-ui-components
-
-**一套用 DeepSeek Harness 设计令牌重塑 Arco Design 外观、并按名暴露全量 IconPark 图标的 React 组件库。**
-
-[English](README.md) | 简体中文
-
-</div>
-
-## 这是什么
-
-DSH 生态里的插件各自手写按钮、输入框与弹窗，同一个产品最后会出现三种圆角。本包是这些控件的统一实现：交互与键盘行为来自 [Arco Design](https://arco.design)，外观由 DeepSeek Harness 的 `--dsw-*` 设计令牌驱动，图标取自 [IconPark](https://iconpark.oceanengine.com)。
-
-产物是不打包的 ESM 源码库。插件自己的构建器把它内联进产物，因此运行期 React 与 Arco 仍是宿主持有的唯一实例，插件侧也不需要任何 CSS 处理管线。
-
-## 安装
-
-```sh
-npm install @dsh-plugin/dsh-ui-components
-```
-
-`react`、`react-dom` 与 `@dsh-plugin/dsh-loader` 是 peer 依赖，三者都由宿主提供。
-
-## 使用
-
-在插件的 React 树根部挂一次 `DshProvider`，随后从包根导入组件。
-
-```tsx
-import { DshProvider, Card, Field, Input, Button, Switch } from '@dsh-plugin/dsh-ui-components'
-
-export function SettingsPage() {
-  return (
-    <DshProvider>
-      <Card title="代理">
-        <Field label="地址" description="仅影响走全局 fetch 的请求。" htmlFor="host">
-          <Input id="host" mono placeholder="127.0.0.1" />
-        </Field>
-        <Field label="启用" layout="inline">
-          <Switch defaultChecked />
-        </Field>
-        <Button variant="primary">保存</Button>
-      </Card>
-    </DshProvider>
-  )
-}
-```
-
-`DshProvider` 注入皮肤、统一图标默认值，并把 Arco 的全部浮层收进持有同一套 CSS 变量的容器。不挂它组件也能渲染，但浮层会挂到 `body` 下而丢掉皮肤。
-
-打包配置里把这三项保持为 external：
-
-```js
-const CLIENT_EXTERNALS = [
-  'react',
-  'react/jsx-runtime',
-  'react-dom',
-  'react-dom/client',
-  '@dsh-plugin/dsh-loader/client',
-]
-```
-
-## 主题
-
-颜色不是可配置的 props，也不需要是。皮肤是一张把 Arco 自身变量整体改指 DSH 语义令牌的 CSS 变量桥，因此深浅色跟随宿主的 `body[data-ds-dark-theme]` 属性自动切换，不涉及任何 JavaScript，组件代码里也没有主题分支。
-
-桥接表挂在 `.dsh-ui` 类上而不是 `body` 上，宿主自己的 Arco 主题因此不受影响。`scripts/verify-tokens.mjs` 会把本包引用的每个宿主变量与宿主样式表比对，DSH 改名时在离线阶段直接报错，而不是等到样式静默失效。
-
-## 图标
-
-三条通道，因为把 2658 个图标全量内联进每个插件并不合理：
-
-```tsx
-// 1. 策划命名集（约 110 个，未使用的会被 tree-shaking 移除）
-import { Icon, Icons } from '@dsh-plugin/dsh-ui-components'
-<Icon name="Settings" size={18} />
-<Icons.GitBranch />
-
-// 2. 全量 2658 个，按子路径引入 —— 只有该图标进入产物
-import Rocket from '@dsh-plugin/dsh-ui-components/icons/Rocket'
-<Icon of={Rocket} size={18} />
-
-// 3. 全量元数据，供选择器与搜索使用，不导入任何图标模块
-import { ICON_INDEX } from '@dsh-plugin/dsh-ui-components/icons-index'
-```
-
-子路径名是 IconPark 名字的 PascalCase 形式：`a-cane` 对应 `ACane`，`setting` 对应 `Setting`。`ICON_INDEX` 的每条记录带 `name`、`pascal`、`title`、`titleZh`、`category`、`tags` 与 `rtl` 七个字段。
-
-图标继承 `currentColor`，颜色跟随周围文字。
-
-## 组件
-
-| 分组 | 导出 |
-|---|---|
-| 基础层 | `DshProvider`、`Icon`、`Icons`、`ICON_NAMES`、`DshIconProvider`、`G`、`cx`、`ICON_INDEX` |
-| 按钮 | `Button`、`IconButton` |
-| 输入 | `Input`、`Textarea`、`InputNumber`、`Select`、`AutoComplete` |
-| 选择 | `Checkbox`、`CheckboxGroup`、`Radio`、`RadioGroup`、`Switch`、`Slider`、`Rate` |
-| 表单 | `Form`、`FormItem`、`Field` |
-| 展示 | `Card`、`Tag`、`Pill`、`Avatar`、`Badge`、`Divider`、`Descriptions`、`Typography`、`Text`、`Paragraph`、`Empty`、`Skeleton`、`Spin`、`Tooltip`、`Popover`、`HoverCard`、`Collapse`、`CollapseItem` |
-| 反馈 | `Alert`、`Progress`、`Result`、`Popconfirm`、`Modal`、`confirm`、`Drawer`、`Message`、`Notification`、`message`、`messageSuccess`、`messageError`、`messageWarning` |
-| 导航 | `Menu`、`MenuItem`、`Dropdown`、`Tabs`、`TabPane`、`Breadcrumb`、`BreadcrumbItem`、`Pagination`、`Steps`、`Step`、`SegmentedControl`、`DisclosureRow`、`StateDot` |
-| 数据 | `Table`、`List`、`ListItem`、`Tree`、`DatePicker`、`TimePicker`、`Cascader`、`TreeSelect`、`Transfer`、`Statistic`、`Timeline`、`TimelineItem`、`Calendar`、`Carousel`、`Image` |
-| DSH 组合件 | `SettingsCard`、`SettingsRow`、`PanelShell`、`MenuSelect`、`JsonTree`、`CodeBlockShell`、`FileTypeBadge`、`StatusLine` |
-
-所有控件都透传原生 props 与 `className`，因此想脱离默认样式时不必 fork 组件。
-
-`SettingsCard` 加 `SettingsRow` 组成宿主设置页的卡片结构。`PanelShell` 是自带 120px 上下留白、内容区走宿主 `Scrollbar` 的浮层外壳。`MenuSelect` 是设置页用的自绘下拉，因为原生 `<select>` 的弹层无法跟随 DSH 主题。
-
-## 预览
-
-```sh
-npm run gen:tokens   # 把宿主令牌样式表复制到 docs/preview/
-npm run preview      # http://localhost:5178
-```
-
-预览站用宿主自己的令牌取值渲染全部组件，带深浅主题切换与覆盖 2658 个图标的可搜索索引。它直接读包源码，改完刷新即可看到效果，不必先构建。
-
-## 开发
-
-```sh
-npm install
-npm run gen:icons     # 重新生成 2658 个图标模块与元数据
-npm run typecheck
-npm run build
-npm test
-npm run verify        # 令牌名、图标通道、字面颜色、包体积
-```
-
-`npm run verify:tokens` 需要宿主样式表。把 `DSH_UI_THEME_DIR` 指向 DSH 检出里的 `packages/client/ui-theme/src/styles`，或在上级目录保留一份 `.dsh/temp/session-tree-harness`。
-
-分批范围与当前进度见 [PLAN.md](PLAN.md)，令牌对照表见 [docs/tokens.md](docs/tokens.md)。
-
-## 许可
-
-MIT。IconPark 图形为 Apache-2.0，详见 [NOTICE](NOTICE)。
+<div align="center">
+
+# dsh-ui-components
+
+**一套用 DeepSeek Harness 设计令牌重塑 Arco Design 外观、并按名暴露全量 IconPark 图标的 React 组件库。**
+
+[English](README.md) | 简体中文
+
+</div>
+
+## 这是什么
+
+DSH 生态里的插件各自手写按钮、输入框与弹窗，同一个产品最后会出现三种圆角。本包是这些控件的统一实现：交互与键盘行为来自 [Arco Design](https://arco.design)，外观由 DeepSeek Harness 的 `--dsw-*` 设计令牌驱动，图标取自 [IconPark](https://iconpark.oceanengine.com)。
+
+产物是不打包的 ESM 源码库。插件自己的构建器把它内联进产物，因此运行期 React 与 Arco 仍是宿主持有的唯一实例，插件侧也不需要任何 CSS 处理管线。
+
+## 安装
+
+```sh
+npm install @dsh-plugin/dsh-ui-components
+```
+
+`react`、`react-dom` 与 `@dsh-plugin/dsh-loader` 是 peer 依赖，三者都由宿主提供。
+
+## 使用
+
+在插件的 React 树根部挂一次 `DshProvider`，随后从包根导入组件。
+
+```tsx
+import { DshProvider, Card, Field, Input, Button, Switch } from '@dsh-plugin/dsh-ui-components'
+
+export function SettingsPage() {
+  return (
+    <DshProvider>
+      <Card title="代理">
+        <Field label="地址" description="仅影响走全局 fetch 的请求。" htmlFor="host">
+          <Input id="host" mono placeholder="127.0.0.1" />
+        </Field>
+        <Field label="启用" layout="inline">
+          <Switch defaultChecked />
+        </Field>
+        <Button variant="primary">保存</Button>
+      </Card>
+    </DshProvider>
+  )
+}
+```
+
+`DshProvider` 注入皮肤、统一图标默认值，并把 Arco 的全部浮层收进持有同一套 CSS 变量的容器。不挂它组件也能渲染，但浮层会挂到 `body` 下而丢掉皮肤。
+
+打包配置里把这三项保持为 external：
+
+```js
+const CLIENT_EXTERNALS = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@dsh-plugin/dsh-loader/client',
+]
+```
+
+## 主题
+
+颜色不是可配置的 props，也不需要是。皮肤是一张把 Arco 自身变量整体改指 DSH 语义令牌的 CSS 变量桥，因此深浅色跟随宿主的 `body[data-ds-dark-theme]` 属性自动切换，不涉及任何 JavaScript，组件代码里也没有主题分支。
+
+桥接表挂在 `.dsh-ui` 类上而不是 `body` 上，宿主自己的 Arco 主题因此不受影响。`scripts/verify-tokens.mjs` 会把本包引用的每个宿主变量与宿主样式表比对，DSH 改名时在离线阶段直接报错，而不是等到样式静默失效。
+
+## 图标
+
+三条通道，因为把 2658 个图标全量内联进每个插件并不合理：
+
+```tsx
+// 1. 策划命名集（约 110 个，未使用的会被 tree-shaking 移除）
+import { Icon, Icons } from '@dsh-plugin/dsh-ui-components'
+<Icon name="Settings" size={18} />
+<Icons.GitBranch />
+
+// 2. 全量 2658 个，按子路径引入 —— 只有该图标进入产物
+import Rocket from '@dsh-plugin/dsh-ui-components/icons/Rocket'
+<Icon of={Rocket} size={18} />
+
+// 3. 全量元数据，供选择器与搜索使用，不导入任何图标模块
+import { ICON_INDEX } from '@dsh-plugin/dsh-ui-components/icons-index'
+```
+
+子路径名是 IconPark 名字的 PascalCase 形式：`a-cane` 对应 `ACane`，`setting` 对应 `Setting`。`ICON_INDEX` 的每条记录带 `name`、`pascal`、`title`、`titleZh`、`category`、`tags` 与 `rtl` 七个字段。
+
+图标继承 `currentColor`，颜色跟随周围文字。
+
+## 组件
+
+| 分组 | 导出 |
+|---|---|
+| 基础层 | `DshProvider`、`Icon`、`Icons`、`ICON_NAMES`、`DshIconProvider`、`G`、`cx`、`ICON_INDEX` |
+| 按钮 | `Button`、`IconButton` |
+| 输入 | `Input`、`Textarea`、`InputNumber`、`Select`、`AutoComplete` |
+| 选择 | `Checkbox`、`CheckboxGroup`、`Radio`、`RadioGroup`、`Switch`、`Slider`、`Rate` |
+| 表单 | `Form`、`FormItem`、`Field` |
+| 展示 | `Card`、`Tag`、`Pill`、`Avatar`、`Badge`、`Divider`、`Descriptions`、`Typography`、`Text`、`Paragraph`、`Empty`、`Skeleton`、`Spin`、`Tooltip`、`Popover`、`HoverCard`、`Collapse`、`CollapseItem` |
+| 反馈 | `Alert`、`Progress`、`Result`、`Popconfirm`、`Modal`、`confirm`、`Drawer`、`Message`、`Notification`、`message`、`messageSuccess`、`messageError`、`messageWarning` |
+| 导航 | `Menu`、`MenuItem`、`Dropdown`、`Tabs`、`TabPane`、`Breadcrumb`、`BreadcrumbItem`、`Pagination`、`Steps`、`Step`、`SegmentedControl`、`DisclosureRow`、`StateDot` |
+| 数据 | `Table`、`List`、`ListItem`、`Tree`、`DatePicker`、`TimePicker`、`Cascader`、`TreeSelect`、`Transfer`、`Statistic`、`Timeline`、`TimelineItem`、`Calendar`、`Carousel`、`Image` |
+| DSH 组合件 | `SettingsCard`、`SettingsRow`、`PanelShell`、`MenuSelect`、`JsonTree`、`CodeBlockShell`、`FileTypeBadge`、`StatusLine` |
+
+所有控件都透传原生 props 与 `className`，因此想脱离默认样式时不必 fork 组件。
+
+`SettingsCard` 加 `SettingsRow` 组成宿主设置页的卡片结构。`PanelShell` 是自带 120px 上下留白、内容区走宿主 `Scrollbar` 的浮层外壳。`MenuSelect` 是设置页用的自绘下拉，因为原生 `<select>` 的弹层无法跟随 DSH 主题。
+
+## 预览
+
+```sh
+npm run gen:tokens   # 把宿主令牌样式表复制到 docs/preview/
+npm run preview      # http://localhost:5178
+```
+
+预览站用宿主自己的令牌取值渲染全部组件，带深浅主题切换与覆盖 2658 个图标的可搜索索引。它直接读包源码，改完刷新即可看到效果，不必先构建。
+
+## 开发
+
+```sh
+npm install
+npm run gen:icons     # 重新生成 2658 个图标模块与元数据
+npm run typecheck
+npm run build
+npm test
+npm run verify        # 令牌名、图标通道、字面颜色、包体积
+```
+
+`npm run verify:tokens` 需要宿主样式表。把 `DSH_UI_THEME_DIR` 指向 DSH 检出里的 `packages/client/ui-theme/src/styles`，或在上级目录保留一份 `.dsh/temp/session-tree-harness`。
+
+分批范围与当前进度见 [PLAN.md](PLAN.md)，令牌对照表见 [docs/tokens.md](docs/tokens.md)。
+
+## 许可
+
+MIT。IconPark 图形为 Apache-2.0，详见 [NOTICE](NOTICE)。