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

@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 可通过包文件路径由构建器处理。每个应用的 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、shadcn/ui theming。

已接入的产品主题

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

4.5 KiB Raw Blame History Unescape Escape