55 lines
1.8 KiB
Markdown
55 lines
1.8 KiB
Markdown
# AGENTS.md — @app/ui
|
||
|
||
## 职责
|
||
|
||
Monorepo 共享 **shadcn 风格基础 UI 组件**（源码直出，无 dist 预构建）。
|
||
视觉依赖 `@app/design-tokens` 的 CSS 变量；组件类内不写死色值。
|
||
|
||
## 结构
|
||
|
||
```
|
||
src/
|
||
index.ts # 桶导出（唯一公共入口 "."）
|
||
utils.ts # cn()
|
||
button.tsx | card.tsx | input.tsx | label.tsx | badge.tsx
|
||
separator.tsx | avatar.tsx | dropdown-menu.tsx | table.tsx | sonner.tsx
|
||
stories/ # Storybook stories
|
||
.storybook/ # main.ts / preview.ts
|
||
```
|
||
|
||
## 消费方式
|
||
|
||
```ts
|
||
import { Button, Card, cn } from "@app/ui";
|
||
```
|
||
|
||
- `package.json` `exports` 指向 `src/index.ts`（源码直出）。
|
||
- `@app/web`：`astro.config.ts` alias + `tsconfig` paths 指到本包 `src`；`ssr.noExternal` 含 `@app/ui`。
|
||
- 相对 import 带 `.js` 后缀（bundler 解析）。
|
||
|
||
## 修改指南
|
||
|
||
- 新组件：`src/<name>.tsx` → 在 `index.ts` 导出 → `stories/<name>.stories.tsx` 补 story。
|
||
- 颜色/圆角一律 CSS 变量（`var(--color-*)`），禁止写死 hex。
|
||
- `cn()` 只从本包导出；web 的 `~/lib/utils` 是 re-export，勿再复制实现。
|
||
- 改依赖后在仓库根 `yarn install`。
|
||
|
||
## Storybook
|
||
|
||
```bash
|
||
yarn workspace @app/ui storybook # :6006
|
||
yarn workspace @app/ui build-storybook # 静态产物 storybook-static/
|
||
```
|
||
|
||
- 样式：`src/styles/storybook.css` 加载 Tailwind 4 + 相对路径引入 `design-tokens/src/tokens.css`（`@tailwindcss/vite` 不走包 exports）。
|
||
- 主题：toolbar 切换 `light` / `dark`（`html.light` / `html.dark`，与 web 的 `app-theme` 类名一致）。
|
||
- Storybook CLI 依赖装在仓库根 `devDependencies`（保证 `@storybook/react-vite/preset` 可被解析）。
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
yarn workspace @app/ui typecheck
|
||
yarn workspace @app/ui lint
|
||
yarn workspace @app/ui storybook
|
||
```
|