Maofeng
114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# @workspace/ui
|
|
|
|
`@workspace/ui` is the source-owned UI foundation for Simple React App Kit. It
|
|
provides reusable React components, interaction primitives, theme tokens,
|
|
icons, localization, and responsive utilities for the applications in this
|
|
workspace.
|
|
|
|
The package began with the shadcn/ui component model and has deliberately
|
|
evolved as a local design-system implementation. It is not a wrapper around a
|
|
published shadcn/ui runtime package: applications compile and own the source in
|
|
this directory.
|
|
|
|
## Relationship to shadcn/ui
|
|
|
|
The package keeps the parts of shadcn/ui that make it effective:
|
|
|
|
- Components are copied into the repository and remain editable.
|
|
- Base UI primitives provide accessible behavior for composite components.
|
|
- Tailwind CSS v4 and CSS custom properties provide styling and theming.
|
|
- `components.json` remains the entry point for generating or updating
|
|
components with the shadcn CLI.
|
|
- Components support RTL layouts and expose `data-slot` attributes for
|
|
composition and customization.
|
|
|
|
This workspace also has intentional differences from upstream shadcn/ui:
|
|
|
|
- Icons use the local Icones adapter instead of importing Lucide icons
|
|
directly.
|
|
- Components can consume a framework-neutral `I18nProvider`; the maintained
|
|
catalogs are `zh-Hans` and `en-US`.
|
|
- Buttons include the workspace ripple interaction.
|
|
- Responsive hooks synchronize mobile, tablet, and desktop state with root
|
|
document classes.
|
|
- Popover and anchored-surface components expose additional positioning,
|
|
arrow, viewport, and imperative-handle capabilities.
|
|
- Higher-level message, bubble, attachment, and overlay-oriented components
|
|
are maintained alongside the lower-level primitives.
|
|
- Imports use explicit package subpaths. There is intentionally no catch-all
|
|
component barrel.
|
|
|
|
Because the source is locally owned, an upstream shadcn update is treated as a
|
|
reviewed merge, not as a dependency upgrade. Preserve local behavior when
|
|
regenerating a component and inspect the diff before accepting it.
|
|
|
|
## Color semantics
|
|
|
|
This package intentionally uses different names for two shadcn color roles:
|
|
|
|
| This package | shadcn/ui equivalent | Meaning |
|
|
| ------------ | -------------------- | --------------------------------------------------------------------------------------------------- |
|
|
| `accent` | `primary` | The product or brand color used for primary actions, selected controls, links, and strong emphasis. |
|
|
| `highlight` | `accent` | A temporary or local surface used for hover, focus, open, and softly selected states. |
|
|
| `muted` | `muted` | A subdued surface or lower-emphasis foreground. |
|
|
|
|
Each role has a matching foreground token where needed:
|
|
`accent-foreground` and `highlight-foreground`. Sidebar tokens follow the same
|
|
model with `sidebar-accent` and `sidebar-highlight`.
|
|
|
|
This naming makes “accent color” consistently mean the configurable brand
|
|
color throughout the workspace. It also avoids using `accent` for shadcn's
|
|
neutral interaction background, where `highlight` describes the visual effect
|
|
more directly.
|
|
|
|
When adapting an upstream snippet, translate its semantic utilities:
|
|
|
|
```text
|
|
bg-primary text-primary-foreground
|
|
-> bg-accent text-accent-foreground
|
|
|
|
hover:bg-accent hover:text-accent-foreground
|
|
-> hover:bg-highlight hover:text-highlight-foreground
|
|
```
|
|
|
|
Do not translate Tailwind's native `accent-*` utilities such as
|
|
`accent-indigo-600`; those utilities control the CSS `accent-color` property
|
|
and are unrelated to these theme roles.
|
|
|
|
## Usage
|
|
|
|
Import components from explicit subpaths:
|
|
|
|
```tsx
|
|
import { Button } from "@workspace/ui/components/button"
|
|
import { Icon } from "@workspace/ui/components/icon"
|
|
import { cn } from "@workspace/ui/lib/utils"
|
|
```
|
|
|
|
Load the shared stylesheet once near the application root:
|
|
|
|
```tsx
|
|
import "@workspace/ui/globals.css"
|
|
```
|
|
|
|
The dark theme is activated by the escaped root class `ui:dark`, rather than
|
|
shadcn's default `.dark` selector. Appearance preferences normally apply this
|
|
class and the generated color variables for the application.
|
|
|
|
## Adding or updating components
|
|
|
|
Run the shadcn CLI from the workspace root and target the application that owns
|
|
the registry configuration:
|
|
|
|
```bash
|
|
bunx shadcn@latest add button -c apps/web
|
|
```
|
|
|
|
After generation:
|
|
|
|
1. Compare the result with the existing component and its Git history.
|
|
2. Restore local Icones, localization, ripple, RTL, and positioning behavior
|
|
where applicable.
|
|
3. Convert upstream `primary`/`accent` color roles to this package's
|
|
`accent`/`highlight` vocabulary.
|
|
4. Format, lint, type-check, and test the affected workspace packages. |