# Tailwind CSS / shadcn/ui 接入

## Workspace 依赖

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

当前 Studio / Wiki Dockerfile 把单个应用复制为孤立项目；增加 workspace 依赖时，必须一并调整 Docker 构建上下文和工作目录，复制根 workspace 配置、消费应用与 `packages/brand`，使 `workspace:*` 的相对位置保持有效。不要只加依赖后仍保留孤立安装流程。本 PR 不迁移这两套应用构建。

## 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 可通过包文件路径由构建器处理。favicon、Apple Touch 与 PWA 图片需要在应用资源准备阶段复制到应用的 public 根目录，再由页面元信息引用。例如 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)。