docs(ui): expand bilingual component guides

packages/ui/docs/zh-Hans/guide/setup.mdx

@@ -1,39 +1,91 @@
 ---
 title: 项目配置
-description: 导入全局样式，并从显式组件子路径开始使用。
+description: 配置 workspace 依赖、全局样式、Tailwind 扫描和 shadcn CLI。
 order: 10
 toc:
-  - id: import-styles
-    title: 导入样式
-  - id: import-a-component
-    title: 导入组件
-  - id: entry-points
-    title: 包入口
+  - id: dependency
+    title: 添加依赖
+  - id: global-styles
+    title: 全局样式
+  - id: imports
+    title: 显式导入
+  - id: shadcn-cli
+    title: shadcn CLI
+  - id: browser-components
+    title: 浏览器组件
+  - id: verify
+    title: 验证配置
 ---
 
-## 导入样式 {#import-styles}
+## 添加依赖 {#dependency}
 
-在应用入口中导入一次全局样式：
+应用通过 workspace 协议引用 UI 包：
 
-```ts
-import "@workspace/ui/globals.css"
-```
-
-它提供组件所需的共享 Tailwind 层、设计变量、字体配置和工具类。
-
-## 导入组件 {#import-a-component}
-
-```tsx
-import { Button } from "@workspace/ui/components/button"
-
-export function SaveButton() {
-  return <Button>保存</Button>
+```json
+{
+  "dependencies": {
+    "@workspace/ui": "workspace:*"
+  }
 }
 ```
 
-## 包入口 {#entry-points}
+仓库中的应用已经完成此配置。这个 package 当前是私有 workspace package，不需要从 npm 安装。
 
-- `@workspace/ui/components/*` 导出单个组件模块。
-- `@workspace/ui/hooks/*` 导出可复用的交互和媒体查询状态。
-- `@workspace/ui/lib/utils` 导出共享的类名组合工具。
-- `@workspace/ui/locales/*` 导出指定语言的词典。
+## 全局样式 {#global-styles}
+
+在应用的全局 CSS 中导入一次：
+
+```css
+@import "@workspace/ui/globals.css";
+```
+
+该入口会加载 Tailwind CSS、shadcn 的 Tailwind 扩展、动画工具、Inter Variable 字体、语义颜色、圆角变量和基础样式。主题通过根节点上的 `.ui:light` 与 `.ui:dark` class 切换；组件代码不要自行复制这些变量。
+
+`globals.css` 中的 `@source` 已覆盖本仓库的 `apps` 与组件目录。如果将 package 移到另一种目录结构，应同步调整扫描路径，否则生产构建可能缺少组件使用的 utility。
+
+## 显式导入 {#imports}
+
+package 没有聚合式 barrel。始终从具体子路径导入，便于追踪依赖并避免意外扩大客户端 bundle：
+
+```tsx
+import { Button } from "@workspace/ui/components/button"
+import { SaveIcon } from "@workspace/ui/components/icon"
+import { useIsMobile } from "@workspace/ui/hooks/use-breakpoint"
+import { cn } from "@workspace/ui/lib/utils"
+```
+
+公开入口包括：
+
+- `@workspace/ui/components/*`：组件与局部类型。
+- `@workspace/ui/hooks/*`：断点和波纹交互。
+- `@workspace/ui/locales`：支持的 locale 与消息 ID 类型。
+- `@workspace/ui/locales/en-US`、`@workspace/ui/locales/zh-Hans`：消息与日历 locale。
+- `@workspace/ui/globals.css`：全局样式。
+
+## shadcn CLI {#shadcn-cli}
+
+仓库根目录运行：
+
+```sh
+bunx shadcn@latest add button -c apps/web
+```
+
+应用和 UI package 的 `components.json` 使用同一套 `base-vega`、neutral、CSS variables、Lucide 词汇和 RTL 配置；别名会把生成文件放到 `packages/ui/src/components`。这与 shadcn 官方的 [monorepo 工作流](https://ui.shadcn.com/docs/monorepo)一致。
+
+CLI 生成完成后必须检查 diff。生成器不知道本仓库的 Icones、国际化、波纹和 Popover 扩展，更新已有组件时可能覆盖本地适配。`components.json` 各字段的含义可参考[官方说明](https://ui.shadcn.com/docs/components-json)。
+
+## 浏览器组件 {#browser-components}
+
+多数交互组件依赖事件、Portal 或浏览器 API。使用 React Server Components 的消费端应从自身的客户端边界导入它们。本仓库配置为 `rsc: false`，组件文件不会统一插入框架专用指令；少数组件因自身需要显式包含 `"use client"`。
+
+## 验证配置 {#verify}
+
+修改组件或配置后运行：
+
+```sh
+bun run --cwd packages/ui typecheck
+bun run lint
+bun run format:check
+```
+
+如果改动涉及消费方式，再运行应用或文档的构建，确认 Tailwind 能扫描到新 class，并检查浅色、深色与 RTL。