60 lines
3.8 KiB
Markdown
60 lines
3.8 KiB
Markdown
# 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)。
|