Maofeng
54 lines
3.2 KiB
Plaintext
54 lines
3.2 KiB
Plaintext
---
|
|
title: Overview
|
|
description: Understand the role, upstream baseline, and workspace-specific extensions of @workspace/ui.
|
|
order: 1
|
|
toc:
|
|
- id: package-role
|
|
title: Package role
|
|
- 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` 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.
|
|
|
|
The package owns generic interface behavior only. Routing, data access, persistence, and product workflows remain in the application or a domain package.
|
|
|
|
## Source model {#source-model}
|
|
|
|
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.
|
|
|
|
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.
|