chuan
5.5 KiB
Gitea 主题项目规则
项目目标
本项目用于创建 Gitea 使用的主题样式和模板覆盖。样式使用 Bun + TypeScript token + Lightning CSS + Preview 的组合：TypeScript 负责组织 token 和样式片段，Lightning CSS 负责最终 CSS 转换和压缩，Preview 用于快速查看基础效果。
目录职责
themes/ 放颜色主题源数据，方便快速扩展新主题。当前维护 themes/github-light/ 和 themes/github-dark/，颜色、语义变量、目标变量、主题元信息都从这里维护；构建时不直接读取 .gitea。
styles/tokens/ 负责把当前 themes/ 主题渲染成 Gitea 可识别的 CSS 变量，并承载必需变量校验、派生 token、兼容别名和输出格式控制。这里不应该直接维护一套颜色表，也不应该出现具体页面选择器。
styles/primitives/ 放全站基础控件规则，例如 .ui.button、.ui.input、input[type="checkbox"]、.ui.dropdown、.tippy-box。这一层可以使用 token，但不应该处理具体页面布局。
styles/components/ 放 Gitea 可复用业务组件样式，例如顶部导航、仓库列表、热力图、动态列表、登录表单、clone 面板。它比 primitive 更具体，但还不是页面级。
styles/pages/ 放某个页面的布局修复和局部覆盖，例如 dashboard 首页、explore 仓库页、org/create 页面、登录页布局。这里可以写具体页面选择器，但改动范围必须尽量局部。
templates/ 放 Gitea 模板覆盖文件。模板修改应尽量保持最小化，避免把样式逻辑写进模板。
options/locale/ 放当前 Gitea 版本的官方 locale 基线。options/locale-overrides/ 放本项目新增或修改的 locale 增量 key。Gitea 运行时需要完整 locale 文件，所以构建时会合并基线和增量覆盖并输出到 .gitea/custom/options/locale/。
src/ 放构建辅助代码、类型和聚合逻辑。这里不直接承载某个具体页面的样式规则。
.gitea/ 放 Gitea custom 目录和源代码参考资源。构建产物会输出到 .gitea/custom/public/assets/css/theme-github-dev.css 和 .gitea/custom/public/assets/css/theme-github-dev-dark.css。
dist/ 放本地构建产物，主要用于检查和 Preview。
分层原则
一个规则只应该属于一个层级。按钮、输入框、下拉菜单等基础控件问题放到 primitives/；仓库列表、导航栏、动态流等可复用业务块放到 components/；只在某个页面成立的间距、布局和覆盖放到 pages/。
低层不能依赖高层。tokens/ 不能依赖 primitives/、components/ 或 pages/；primitives/ 不能依赖页面结构；components/ 不应该修复具体页面布局。
避免重复定义颜色、阴影、圆角和间距。颜色主题值优先在 themes/ 中新增或修改，再通过 styles/tokens/ 输出为官方兼容的 var(--color-*)。
页面级选择器必须足够具体，避免影响全站控件。例如登录页按钮间距问题应该放在登录页或登录组件范围内，不应该修改所有 .ui.button。
命名规则
主题 CSS 变量优先保持 Gitea 官方兼容命名，例如 --color-primary、--color-body、--color-input-background。只有新增且无法映射到官方变量的项目私有变量，才使用自定义前缀。
主题名与 Gitea CSS 文件名保持一致。当前主题名是 github-dev 和 github-dev-dark，输出文件分别是 theme-github-dev.css 和 theme-github-dev-dark.css。不要使用 gitea、gitea-auto、arc-green 这类内置主题名，避免 Gitea 加载内置 hashed 资源而不是 custom 主题文件。
样式模块默认导出字符串常量，由 styles/index.ts 按 tokens -> primitives -> components -> pages 顺序聚合。styles/tokens/index.ts 必须通过 render-theme.ts 输出当前主题，不直接拼接主题源数据。
构建与预览
使用 bun run build 构建未压缩 CSS。
使用 bun run build:min 构建压缩 CSS。
使用 bun run dev 监听样式、主题和 src 文件变化。
使用 bun run preview 启动本地预览页面。
使用 bun run locale:sync 从本地 options/locale/ 基线合并 options/locale-overrides/。需要刷新官方基线时，运行 bun scripts/locale.ts --remote。
使用 bun run test 构建 light/dark 两套主题并检查必要输出是否存在。
使用 bun run compose:up 启动 Gitea 开发容器，使用 bun run compose:down 停止容器。
修改流程
官方样式基线和源码映射见 docs/official-style-map.md。当前项目先拆分官方 theme-gitea-light.css，再在当前仓库内维护 GitHub Light 风格的主题增量。
新增视觉值时，先判断是否应该成为 token。颜色和主题值放到 themes/；派生变量、Gitea 兼容别名和必需变量校验放到 styles/tokens/。
修改控件外观时，优先检查 styles/primitives/，确保不会破坏页面级布局。
修改业务组件时，优先放到 styles/components/，并使用组件范围选择器约束影响面。
修改单个页面问题时，放到 styles/pages/，并写明页面级父选择器。
修改模板时，先确认 Gitea 原始模板结构，再把覆盖文件放入 templates/。bun run build 会同步到 .gitea/custom/templates/。
修改翻译时，只改 options/locale-overrides/ 里的增量 key。不要手工编辑 options/locale/locale_*.json；它是当前 Gitea 版本的官方基线缓存，仅在升级 Gitea 版本或显式远程刷新时更新。