app-template/packages/ui/AGENTS.md

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

消费方式

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

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 可被解析）。

命令

yarn workspace @app/ui typecheck
yarn workspace @app/ui lint
yarn workspace @app/ui storybook