docs(ui): expand bilingual component guides
This commit is contained in:
Maofeng
@@ -1,39 +1,91 @@
|
||||
---
|
||||
title: Project setup
|
||||
description: Import the global stylesheet and begin with explicit component subpaths.
|
||||
description: Configure the workspace dependency, global styles, Tailwind scanning, and the shadcn CLI.
|
||||
order: 10
|
||||
toc:
|
||||
- id: import-styles
|
||||
title: Import styles
|
||||
- id: import-a-component
|
||||
title: Import a component
|
||||
- id: entry-points
|
||||
title: Entry points
|
||||
- id: dependency
|
||||
title: Add the dependency
|
||||
- id: global-styles
|
||||
title: Global styles
|
||||
- id: imports
|
||||
title: Explicit imports
|
||||
- id: shadcn-cli
|
||||
title: shadcn CLI
|
||||
- id: browser-components
|
||||
title: Browser components
|
||||
- id: verify
|
||||
title: Verify the setup
|
||||
---
|
||||
|
||||
## Import styles {#import-styles}
|
||||
## Add the dependency {#dependency}
|
||||
|
||||
Import the global stylesheet once at the application entry:
|
||||
Applications reference the UI package through the workspace protocol:
|
||||
|
||||
```ts
|
||||
import "@workspace/ui/globals.css"
|
||||
```
|
||||
|
||||
It provides the shared Tailwind layers, design variables, font setup, and utilities expected by the components.
|
||||
|
||||
## Import a component {#import-a-component}
|
||||
|
||||
```tsx
|
||||
import { Button } from "@workspace/ui/components/button"
|
||||
|
||||
export function SaveButton() {
|
||||
return <Button>Save</Button>
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"@workspace/ui": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Entry points {#entry-points}
|
||||
The applications in this repository are already configured this way. The package is currently private to the workspace and does not need to be installed from npm.
|
||||
|
||||
- `@workspace/ui/components/*` exposes one component module.
|
||||
- `@workspace/ui/hooks/*` exposes reusable interactions and media-query state.
|
||||
- `@workspace/ui/lib/utils` exposes shared class-name composition.
|
||||
- `@workspace/ui/locales/*` exposes language-specific catalogs.
|
||||
## Global styles {#global-styles}
|
||||
|
||||
Import the stylesheet once from the application's global CSS:
|
||||
|
||||
```css
|
||||
@import "@workspace/ui/globals.css";
|
||||
```
|
||||
|
||||
This entry loads Tailwind CSS, shadcn's Tailwind extension, animation utilities, the Inter Variable font, semantic colors, radius variables, and base styles. Themes switch through `.ui:light` and `.ui:dark` on the root element; component code should not copy these variables.
|
||||
|
||||
The `@source` directives in `globals.css` cover this repository's `apps` and component directories. Update those paths if the package moves into another directory layout, or production builds may omit utilities used by components.
|
||||
|
||||
## Explicit imports {#imports}
|
||||
|
||||
There is no aggregated barrel. Import concrete subpaths so dependencies remain visible and client bundles do not grow accidentally:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
Public entry points include:
|
||||
|
||||
- `@workspace/ui/components/*` for components and their local types.
|
||||
- `@workspace/ui/hooks/*` for breakpoint and ripple interactions.
|
||||
- `@workspace/ui/locales` for supported locales and message ID types.
|
||||
- `@workspace/ui/locales/en-US` and `@workspace/ui/locales/zh-Hans` for messages and calendar locales.
|
||||
- `@workspace/ui/globals.css` for global styles.
|
||||
|
||||
## shadcn CLI {#shadcn-cli}
|
||||
|
||||
Run the command from the repository root:
|
||||
|
||||
```sh
|
||||
bunx shadcn@latest add button -c apps/web
|
||||
```
|
||||
|
||||
The application and UI package `components.json` files agree on `base-vega`, neutral, CSS variables, the Lucide vocabulary, and RTL output. Their aliases place generated files under `packages/ui/src/components`, following shadcn's official [monorepo workflow](https://ui.shadcn.com/docs/monorepo).
|
||||
|
||||
Always inspect the diff after generation. The generator does not know about this workspace's Icones layer, localization, ripple behavior, or Popover extensions and can overwrite them when updating an existing component. See the official [`components.json` reference](https://ui.shadcn.com/docs/components-json) for the meaning of each setting.
|
||||
|
||||
## Browser components {#browser-components}
|
||||
|
||||
Most interactive components depend on events, portals, or browser APIs. Consumers using React Server Components should import them from their own client boundary. This workspace has `rsc: false`; component files do not receive a framework-specific directive globally, although a few components include `"use client"` when they require it.
|
||||
|
||||
## Verify the setup {#verify}
|
||||
|
||||
After changing a component or configuration, run:
|
||||
|
||||
```sh
|
||||
bun run --cwd packages/ui typecheck
|
||||
bun run lint
|
||||
bun run format:check
|
||||
```
|
||||
|
||||
When a change affects consumption, also build the application or docs so Tailwind scanning is exercised, then verify light, dark, and RTL modes.
|
||||
|
||||
Reference in New Issue
Block a user