feat(brand): add Endoleap assets and production theme package
Endoleap brand checks / verify (pull_request) Failing after 5s
creative workspace review checks / verify (pull_request) Has been cancelled

This commit is contained in:
2026-11-01 00:22:43 +08:00
parent 0849268232
commit c405f47916
120 changed files with 1912 additions and 1 deletions
+71
View File
@@ -0,0 +1,71 @@
# 色彩与组件规范
## 基础色与背景分工
| 色彩 | HEX | 用途 |
| --- | --- | --- |
| 摩卡 | `#A47764` | `brand-mocha`,Logo 杯口与装饰 |
| 深棕 | `#49372E` | 浅底 Logo 杯腹、标准图标底 |
| 深摩卡 | `#78523F` | Light 主操作与连线 |
| 奶霜 | `#FFF6EF` | 首页 Light 底色、反白 Logo |
| 陶橙 | `#E07242` | `brand-orange`,小面积装饰,不替代状态色 |
| 浅燕麦 | `#EDE9D0` | `brand-oat`,首页轻量选中区域 |
品牌摩卡不适合在所有浅色底上当普通小字。Light 按钮使用更深的摩卡;正文和辅助文字分别使用 `foreground`、`muted-foreground`。`accent` 在 shadcn/ui 中表示交互高亮背景,因此映射到轻量 `selection`,与装饰色 `brand-mocha` 分开。
| 正式主题 | 工作背景 | 面板 | 主按钮 | 按钮文字 |
| --- | --- | --- | --- | --- |
| `home-light` | `#FFF6EF` | `#FFFCF9` | `#78523F` | `#FFFFFF` |
| `home-dark` | `#1C1816` | `#27211E` | `#D1AA92` | `#211A17` |
| `canvas-light` | `#FAFAFA` | `#FFFFFF` | `#78523F` | `#FFFFFF` |
| `canvas-dark` | `#141414` | `#202020` | `#D1AA92` | `#211A17` |
四套主题使用相同 token 契约,完整值在对应 JSON;通过 JS `getTheme(name)` 可获得解析后的只读值。JSON 引用色板键,避免在不同主题重复维护 HEX。
## 首页
导航与 Hero 使用 `background`;标题 `foreground-strong`,正文 `foreground`,说明 `muted-foreground`。演示面板和功能卡片使用 `card` / `card-foreground`。嵌套分组使用 `muted` / `muted-foreground`,不继承浅底上可能对比不足的说明色。
推荐套餐使用 `selection` 背景加文字标记;深色 CTA 区块须成对使用反白文字。陶橙仅作少量点缀,浅燕麦只用于局部区块,不给所有卡片统一染色。
## 画布
- 无限背景使用 `background`,点阵 `grid`,工具栏和侧栏 `surface`;弹层 `popover` / `popover-foreground`。
- Light / Dark 均保持中性近白 / 近黑。品牌色集中在操作、连接、焦点和选中态。
- 普通节点用 `border`;选中节点用 2px `selection-border` 和控制点。不要把节点正文、图片或用户绘图填成选中色。
- 工具选中采用 `selection` 底与 `primary` 图标;连线采用 `connector`;加号端口使用 `primary` 底和 `primary-foreground` 图标。
- 图片、视频、用户作品和导入 SVG 保留原色。深色工作区内的白色作品画板仍为白色,导出不包含界面网格或品牌背景。
## 交互状态
| 组件 | Default | Hover | Pressed / Selected |
| --- | --- | --- | --- |
| 主按钮 | `primary` | `primary-hover` | `primary-active` |
| 次按钮 | `secondary` | `secondary-hover` | `secondary-active` |
| 菜单、列表项 | `surface` | `row-hover` / `accent` | `selection` |
| 文本链接 | `link` 并加下划线 | 保持可辨认 | 不仅靠颜色表达 |
| 输入框 | `surface`、`foreground`、`input` 边界 | 强化边界 | `ring` 外轮廓 |
主、次按钮始终使用对应 `*-foreground`,不要在 hover 时遗留原文字颜色。`focus-visible` 使用 2px `ring` 与 2px 外偏移。输入错误保留 `danger` 边界、说明和错误图标;键盘焦点作为独立外轮廓继续显示。
禁用使用 `disabled-background` / `disabled-foreground`,同时提供真正的 disabled 语义并停止 hover。禁用色不用于正常说明。加载保持原按钮主题并增加文字或进度标记,不用错误色表示。
## shadcn/ui 语义对照
`card` → 默认内容面板;`popover` → 浮层;`muted` → 低强调表面;`accent` → hover/选中表面;`destructive` → 危险动作;`input` → 必须可见的控件边界;`ring` → 焦点;`sidebar-*` → 侧栏完整配对;`chart-1` 至 `chart-5` → 每个主题自己的图表色。
每种表面都有对应前景色,包含 `destructive-foreground`。`radius` 为 `0.625rem`,Tailwind 的 `rounded-sm/md/lg/xl` 按统一比例派生。
## 状态色与图表
成功、警告、错误、信息分别使用 `success`、`warning`、`danger`、`info`,并与 `*-background` 配对。同时提供文字或图标,勿单靠颜色解释。陶橙是品牌装饰色,不自动意味着警告。
同一指标保持相同系列颜色;多系列同时增加图例、标记或线型。Light 和 Dark 的 `chart-*` 分别配置,不能把浅底图表色原样搬到深底。精细图表仍需检查真实线宽、相邻色与背景。
`border`、`grid` 是低强调分隔/装饰;必要控件边界采用更清晰的 `input`。阴影使用 `shadow` token;模态遮罩使用 `scrim`,对话框与文字不随背景一起降低透明度。
## 验收范围
静态检查覆盖语义前景/背景、主按钮三态与必要控件边界。普通文字目标 ≥4.5:1,必要非文字控件目标 ≥3:1;不是整站无障碍认证。照片叠字、透明混色、图表相邻色与真实交互另验。用户素材和模板内容不属于 UI 换色范围。
依据:[W3C 文字对比度](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum)、[非文字对比度](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast)。
+59
View File
@@ -0,0 +1,59 @@
# 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)。
Binary file not shown.

After

Width:  |  Height:  |  Size: 85 KiB

+35
View File
@@ -0,0 +1,35 @@
# Logo 规范与资源
![摩卡奶霜 Logo 版本](logo-preview.png)
杯口摩卡 `#A47764`;浅底杯腹深棕 `#49372E`;深底杯腹奶霜 `#FFF6EF`;标准图标背景深棕 `#49372E`。对应引用位于 `tokens/logo.json`,色值从 `tokens/palette.json` 解析。陶橙、浅燕麦不加入标准 Logo。
## 资源选择
| 文件(相对于 assets) | 使用场景 |
| --- | --- |
| `svg/logo-light.svg` | 白色或奶霜背景上的透明双色标志 |
| `svg/logo-dark.svg` | 近黑或深棕背景上的透明反白标志 |
| `svg/mono-dark.svg`、`mono-light.svg` | 单色印刷、水印和受限展示 |
| `svg/icon-dark.svg`、`icon-light.svg` | 有圆角容器的图标 |
| `svg/app-square.svg` | 平台后续按蒙版裁切的方形源 |
| `svg/avatar-circle.svg` | 圆形头像 |
| `icons/favicon.ico` | 默认深棕 favicon |
| `icons/favicon-transparent.ico` | 已知浅色背景下的透明 favicon |
| `icons/favicon-light.ico` | 奶霜底 favicon |
| `icons/apple-touch-icon.png` | 180px 方形平台图片 |
| `icons/pwa-192.png`、`pwa-512.png` | PWA 候选图片,应用自行配置 manifest |
`png/<版本>/endoleap-<尺寸>.png` 提供六组版本,每组包含 16、24、32、48、64、128、180、192、256、512、1024、2048px。三款 ICO 均内含 16、24、32、48、64、128、256px 的 PNG 帧。
平台图片不等于完整原生安装图标配置;平台蒙版、safe zone、资源目录与元信息由消费应用配置。字标未包含在本包内,应用产品名称应使用正常文本和现有排版。
## 一致性与修改规则
唯一轮廓来源是 `tokens/geometry.json`,包含 rim / bowl 两条路径及其 transform。所有 SVG 共用完全相同的路径、坐标和比例,仅填色或背景容器不同。PNG 和 ICO 从对应 SVG 逐尺寸渲染;不能通过图片模型重新生成某个尺寸,也不能手工拉伸某个版本。
修改颜色时同步 `palette.json`、Logo 色板引用和正式资源;修改形状时仅修改几何母版,再在 ces-control 导出所有受影响的文件。标准尺寸画布为 820×820 viewBox,标志与四周留白保持当前母版坐标。已有固定 PNG 可以从本次批准的素材直接迁入;后续渲染由远程 CI 验证。
`assets/manifest.json` 列出颜色、版本、SVG 路径、PNG 与 ICO 尺寸;静态测试核对结构和轮廓,远程 Docker 使用固定版本的 resvg/Pillow 逐像素核对 PNG。不要把探索稿、ZIP、截图、提示词或本机路径当成正式源文件。
提交 PR 时说明变动是填色、容器还是几何;附选定版本对照并记录受影响应用。不得直接推 main 或替用户合并。
+22
View File
@@ -0,0 +1,22 @@
# 品牌与包边界
中文名:**啡跃**。英文名:**Endoleap**。当前色彩方向为摩卡奶霜;Logo 是用户选定的「悬浮杯口」,形状固定,配色按背景切换。
本包采用一个包、多个目录,颜色与 Logo 由相同的基础色板约束。消费方通过 `@endoleap/brand/themes.css`、`@endoleap/brand/tailwind.css`、`@endoleap/brand/tokens` 和 `@endoleap/brand/assets/*` 按需引用。
| 路径 | 职责 |
| --- | --- |
| `tokens/palette.json` | 全部基础色与长度值;每个色值只有一个键 |
| `tokens/home-light.json`、`home-dark.json` | 官网明暗语义色 |
| `tokens/canvas-light.json`、`canvas-dark.json` | 编辑器明暗语义色 |
| `tokens/logo.json` | Logo 各部分的色板引用 |
| `tokens/geometry.json` | 两条固定路径及坐标 |
| `src/` | 可直接导入的 CSS、ESM 和类型声明 |
| `assets/` | 正式 SVG、PNG、ICO、清单 |
| `docs/` | 包内唯一品牌规范入口 |
深色主题已正式确认纳入本包,直接位于 `tokens/`。应用是否启用深色、如何存储偏好由应用决定;导入 CSS 不自动修改页面背景、用户作品或系统偏好。
本 PR 的交付范围是共享包、文档和远程验证。现有 Studio / Wiki 页面还没有接入新包,不声称网站已经更名、换色或替换 favicon。应用接入时,按 [集成说明](integration.md) 更新其依赖及 Docker 复制规则,并另做服务器视觉验收。
探索截图、图片模型提示词和 ZIP 交付包不属于运行资源。正式资产通过 Git 历史保留版本,不在包内堆积旧版目录。