---
title: 概览
description: 了解 @workspace/ui 的职责、上游基线和本仓库的扩展。
order: 1
toc:
  - id: package-role
    title: 包的职责
  - id: source-model
    title: 源码模型
  - id: local-adaptations
    title: 本地适配
  - id: learning-path
    title: 学习路线
  - id: package-boundaries
    title: 包边界
---

## 包的职责 {#package-role}

`@workspace/ui` 是整个工作区的视觉基础。它提供可编辑的 React 组件源码、Tailwind CSS 主题变量、响应式与交互 Hooks、统一图标入口，以及组件自身使用的本地化消息。

这个包只负责通用界面能力。路由、数据请求、持久化和业务流程仍由应用或领域 package 管理。

## 源码模型 {#source-model}

组件以 [shadcn/ui Base UI 版本](https://ui.shadcn.com/docs/components/base)和其 [GitHub registry 源码](https://github.com/shadcn-ui/ui/tree/main/apps/v4/registry/bases/base/ui)为基线。与 shadcn/ui 一样，它们不是不可修改的第三方黑盒：源码位于 `packages/ui/src`，可以直接审查、组合和演进。

本仓库使用 `base-vega` 风格、CSS 变量、Tailwind CSS v4、Base UI primitives 和 RTL 输出。`components.json` 只控制生成方式；运行时 API 以本仓库源码为准。

## 本地适配 {#local-adaptations}

本仓库在上游基础上做了这些有意保留的调整：

- 使用 `@icones/react` 封装统一的 `components/icon` 入口，不直接依赖 `lucide-react`。
- `Button` 默认接入指针波纹反馈。
- 增加 `I18nProvider`，让 Breadcrumb、Calendar、Carousel、Pagination、Sidebar、Toast 等组件使用应用的翻译器。
- 只发布 `en-US` 和 `zh-Hans` 两套 UI 词典与日历 locale。
- 增加 mobile、tablet、desktop 三段式断点 Hooks 和根节点 class 同步。
- 扩展 `PopoverContent` 的自定义锚点、定位方式、连续尾巴和独立滚动视口。
- 增加 `AnchoredSurface`，并保留消息、气泡、附件和消息滚动器等组合组件。

升级 shadcn/ui 组件时不要盲目覆盖这些差异。完整清单见“本仓库适配”。

## 学习路线 {#learning-path}

先完成“项目配置”，再通过“组件目录”确定入口；浮层和反馈类组件有独立指南。需要 SSR、响应式行为或多语言时，再阅读进阶章节。示例章节展示可直接组合进应用的完整结构。

## 包边界 {#package-boundaries}

- 使用 `@workspace/ui` 构建按钮、表单、菜单、弹层、列表和反馈等基础界面。
- 使用 `@workspace/blocks` 组合应用外壳、导航、聊天和通知等完整区域。
- 使用 `@workspace/media`、`@workspace/search`、`@workspace/lexical` 等 package 承载领域交互。
- 使用 `@workspace/appearance` 与 `@workspace/preferences` 聚合主题偏好和持久化。