# PAC design-sync 备注

## 仓库形态
- 无独立设计系统包、无 Storybook → **package 形态**。同步入口是 `apps/pac-web/src/ds/index.ts`(为 design-sync 新建的显式 re-export 桶),收录 `ui/` 14 个 shadcn 基础件 + `plan-detail/shared.tsx` 5 个工作台业务原语(Chip/PriorityBar/AIStamp/SidebarCard/MD)。
- `pkg=@pac/web`,`globalName=PAC`,`--entry apps/pac-web/src/ds/index.ts`,`--node-modules apps/pac-web/node_modules`。
- 组件清单以 `componentSrcMap`(19 条 pin)为准,不靠 .d.ts 自动发现(app 是应用不是库,无 dist/无导出类型树)。

## Tailwind v4 CSS 管线(关键)
- 无 tailwind.config.js;v4 用 `@import "tailwindcss"` + `@theme`,globals.css 在 `apps/pac-web/src/app/globals.css`。
- design-sync 用独立入口 `.design-sync/tailwind-entry.css`(@import globals + @source 扫 pac-web/src 和 previews),CLI(`@tailwindcss/cli`,装在 .ds-sync)编译到 `apps/pac-web/.ds-css/tailwind.css`(gitignored),cfg.cssEntry 指它。
- **重建顺序**:先跑 buildCmd(tailwindcss 编 CSS)→ 再 package-build。CSS 要扫到预览里的工具类,所以改了 previews/*.tsx 后必须重编 CSS 再 build,否则新类名不进产物。

## 组件排除
- `MD` 被 isComponentName 过滤掉(两字母全大写疑似常量/枚举)→ 只同步了 18/19。MD 是轻量 markdown 渲染器,设计系统里价值低,不救,接受 18。ds/index.ts 仍导出它(bundle 里有,只是无卡片)。

## 字体
- CSS 引用 "Microsoft YaHei"/"PingFang" 中文字体族,不 ship woff2(宿主/系统提供)→ 用 `runtimeFontPrefixes: ["Microsoft YaHei","PingFang"]` 抑制 [FONT_MISSING]。设计系统面板会用系统中文字体渲染,视觉无碍。

## 浮层卡片模式(cfg.overrides)
- Dialog/AlertDialog/Popover/HoverCard/DropdownMenu/Toaster → cardMode:single + 固定 viewport(open 态在卡内渲染,不逃逸)。Calendar → cardMode:column。

## 已知 render warns
- 无(本次跳过机检,--no-render-check;18 卡自检 iframe 均非空,截图确认令牌色/字体/Radix 结构正常)。

## Re-sync 风险
- **机检从未跑过**(用户选跳过 playwright)。下次若装了 chromium,去掉 --no-render-check 做一次真机检,可能暴露自检漏掉的问题。
- previews/*.tsx 里的示例文案是手写业务场景(黄莉/杭州高德诊所等),与真实数据无耦合,改 API 不影响;但组件 props 变更(如 Chip tone 增删)要同步改预览。
- ds/index.ts 是 design-sync 专属桶文件,不被 pac-web 应用引用——新增组件进设计系统需手动在此 re-export + componentSrcMap 登记。
- CSS 走 Tailwind CLI 全量扫描 apps/pac-web/src:若 pac-web 源码大改,产物类名集会变(通常无害,确定性重建即可)。
