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

@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 时只导入前者。

<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

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、shadcn/ui theming。

3.8 KiB Raw Blame History Unescape Escape