docs(ui): expand bilingual component guides

packages/ui/docs/en-US/overview.mdx

@@ -1,24 +1,53 @@
 ---
 title: Overview
-description: Learn where the UI package fits and how its explicit entry points support composition.
+description: Understand the role, upstream baseline, and workspace-specific extensions of @workspace/ui.
 order: 1
 toc:
   - id: package-role
     title: Package role
-  - id: tutorial-map
-    title: Tutorial map
-  - id: ui-or-blocks
-    title: UI or Blocks
+  - id: source-model
+    title: Source model
+  - id: local-adaptations
+    title: Local adaptations
+  - id: learning-path
+    title: Learning path
+  - id: package-boundaries
+    title: Package boundaries
 ---
 
 ## Package role {#package-role}
 
-`@workspace/ui` contains reusable React primitives, composite controls, hooks, icons, styles, and locale catalogs. It is the visual foundation shared by applications and higher-level feature packages.
+`@workspace/ui` is the visual foundation of the workspace. It provides editable React component source, Tailwind CSS theme variables, responsive and interaction hooks, a shared icon entry point, and the localized messages used by the components themselves.
 
-## Tutorial map {#tutorial-map}
+The package owns generic interface behavior only. Routing, data access, persistence, and product workflows remain in the application or a domain package.
 
-This tutorial installs the styles, introduces component subpaths, builds a small form through composition, adds responsive behavior, and connects locale catalogs.
+## Source model {#source-model}
 
-## UI or Blocks {#ui-or-blocks}
+The components use the [shadcn/ui Base UI implementation](https://ui.shadcn.com/docs/components/base) and its [GitHub registry source](https://github.com/shadcn-ui/ui/tree/main/apps/v4/registry/bases/base/ui) as their baseline. Like shadcn/ui, they are editable source rather than an opaque component dependency: the implementation lives in `packages/ui/src` and can be reviewed, composed, and evolved locally.
 
-Use UI components when the application owns the workflow. Use `@workspace/blocks` for complete application-shell features such as navigation and notifications, and focused packages such as `@workspace/media` or `@workspace/search` for domain workflows.
+This workspace selects the `base-vega` style, CSS variables, Tailwind CSS v4, Base UI primitives, and RTL output. `components.json` controls generation; the checked-in workspace source is the runtime authority.
+
+## Local adaptations {#local-adaptations}
+
+The workspace intentionally preserves these changes on top of the upstream baseline:
+
+- A shared `components/icon` entry point backed by `@icones/react`, instead of direct `lucide-react` imports.
+- Pointer ripple feedback built into `Button`.
+- An `I18nProvider` that localizes Breadcrumb, Calendar, Carousel, Pagination, Sidebar, Toast, and related controls through the application's translator.
+- UI catalogs and calendar locales for `en-US` and `zh-Hans` only.
+- Mobile, tablet, and desktop breakpoint hooks with root-class synchronization.
+- Custom anchors, positioning methods, a continuous tail, and an independent scroll viewport on `PopoverContent`.
+- `AnchoredSurface` plus message, bubble, attachment, and message-scroller composition primitives.
+
+Do not overwrite these differences blindly when updating from shadcn/ui. The “Workspace adaptations” chapter contains the full checklist.
+
+## Learning path {#learning-path}
+
+Start with “Project setup”, then use the “Component catalog” to find the right entry point. Overlays and feedback have focused guides. Continue to the advanced chapters when the application needs SSR-safe responsive behavior or localization. The examples assemble the primitives into application-ready structures.
+
+## Package boundaries {#package-boundaries}
+
+- Use `@workspace/ui` for buttons, forms, menus, overlays, lists, and generic feedback.
+- Use `@workspace/blocks` for complete application areas such as shells, navigation, chat, and notifications.
+- Use domain packages such as `@workspace/media`, `@workspace/search`, and `@workspace/lexical` for domain interaction.
+- Use `@workspace/appearance` with `@workspace/preferences` to compose theme preferences and persistence.