# 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
```