# Tailwind CSS / shadcn/ui 接入

## Workspace 依赖

在消费应用的 `package.json` 声明 `"@endoleap/brand": "workspace:*"`，按仓库独立锁文件策略更新该应用锁文件。包为私有内部资源，无需 npm 发布、React peer dependency 或运行时主题库。

Studio / Wiki 已声明 `workspace:*` 依赖。Docker 构建在 `/repo/apps/<app>` 保留与 `/repo/packages/brand` 的相对位置；Next.js 的模块解析与文件追踪都以 `/repo` 为根，standalone 保留 `apps/<app>` 层次。运行镜像复制完整 standalone 到 `/app`，在 `/app/apps/<app>` 执行服务；静态文件、图标、worker 与健康检查文件都放在对应应用目录。保持消费应用与品牌包的相对位置，不恢复原有孤立安装流程。

## Tailwind CSS v4

```css
@import "tailwindcss";
@import "@endoleap/brand/themes.css";
@import "@endoleap/brand/tailwind.css";
```

`themes.css` 提供原生变量；`tailwind.css` 以 `@theme inline` 映射为 `bg-background`、`text-foreground`、`border-input`、`ring-ring` 等工具类，并声明 `.dark` / 显式 dark 主题变体。仅使用普通 CSS 时只导入前者。

```tsx
<main data-theme="canvas-dark" className="bg-background text-foreground">
  <section className="bg-card text-card-foreground border border-border">
    <button className="bg-primary text-primary-foreground hover:bg-primary-hover focus-visible:ring-2 focus-visible:ring-ring">
      开始创作
    </button>
  </section>
</main>
```

在页面根节点选择 `home-light` / `home-dark` / `canvas-light` / `canvas-dark`；不要将官网背景变量继承成编辑器画板内容。`.dark` 无显式主题时回退到 `home-dark`。使用 `dark:` 工具类时保持一个根明暗上下文，不在 `.dark` 祖先下混用嵌套浅色变体；嵌套不同表面优先使用相同语义工具类。

## shadcn/ui

消费应用在自己的 `components.json` 保留 `tailwind.cssVariables: true`，`tailwind.css` 指向导入上述品牌样式的全局 CSS 文件。应用自行选择已有风格、图标库和组件路径，不把配置文件放到品牌资源包，也不运行 `init` 覆盖已有全局样式。

本包已提供 background/card/popover、各 foreground、primary/secondary/muted/accent、destructive、border/input/ring、chart-1…5、完整 sidebar 变量与 radius。`accent` 是交互表面；装饰摩卡请用 `brand-mocha` / `bg-brand-mocha`。无需在每个组件复制色值。

这表示主题兼容，不表示 shadcn 组件或动画样式已安装。组件自己的依赖、动画及 className 合并工具由应用现有架构负责。

## JS / TypeScript

```ts
import { getTheme, type ThemeName } from '@endoleap/brand/tokens';
const name: ThemeName = 'canvas-dark';
const lineColor = getTheme(name).connector;
```

CSS 与 JS 主题名称一致。ESM 使用 JSON import attributes；包提供类型声明，TypeScript 消费方需支持 JSON 模块解析。CSS 中使用主题变量，Canvas/WebGL 中使用解析值；切换主题后由渲染器重画 UI，不能修改用户文档颜色。

## 静态图片

SVG 可通过包文件路径由构建器处理。每个应用的 `brand:prepare` 在已授权的远程构建中调用 `scripts/prepare-app.mjs`，按明确映射复制三个 SVG、favicon 和 Apple Touch 图片到 public。生成副本被 gitignore 排除，唯一资产源仍在本包。PWA manifest 由应用另行配置。例如 favicon 源是 `@endoleap/brand/assets/icons/favicon.ico`。必须显式指定文件映射，不复制整个资产包到 public，也不提交人为维护的第二套图形源。

应用有 basePath 时，按应用现有部署方式确认浏览器 URL；不要把内部包路径当作公开 URL。平台 manifest、主题切换和实际网页接入不由品牌包自动注入。

## 版本与兼容范围

适配本仓库 Tailwind v4.3 与 CSS 变量式 shadcn/ui。Tailwind v3 需要另写 config 映射，本包不宣称已测试 v3。

官方依据：[Tailwind theme variables](https://tailwindcss.com/docs/theme)、[shadcn/ui theming](https://ui.shadcn.com/docs/theming)。

## 已接入的产品主题

两个应用使用同源 `endoleap.theme` 偏好（light / dark），默认浅色。首屏脚本在绘制前恢复偏好；普通页面选择 home，图形编辑与无限画布选择 canvas。主题开关仅修改 UI 根节点与此偏好，不改任何草稿、模板或用户作品。浏览器 favicon 在普通路径与 `/studio` basePath 分别提供；固定版本查询参数用于替换旧缓存。