chuan
3.8 KiB
Gitea 主题项目规则
项目目标
本项目用于创建 Gitea 使用的主题样式和模板覆盖。样式使用 Bun + TypeScript token + Lightning CSS + Preview 的组合：TypeScript 负责组织 token 和样式片段，Lightning CSS 负责最终 CSS 转换和压缩，Preview 用于快速查看基础效果。
目录职责
themes/ 放颜色主题和主题 token，例如 light.ts。主题文件只定义值，不写 Gitea 选择器。
styles/tokens/ 放最底层设计变量，例如颜色、字号、间距、圆角、阴影、动效时长。这里不应该出现具体页面选择器。
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 模板覆盖文件。模板修改应尽量保持最小化，避免把样式逻辑写进模板。
src/ 放构建辅助代码、类型和聚合逻辑。这里不直接承载某个具体页面的样式规则。
.gitea/ 放 Gitea custom 目录和源代码参考资源。构建产物会输出到 .gitea/custom/public/assets/css/theme-gitea-auto.css。
dist/ 放本地构建产物，主要用于检查和 Preview。
分层原则
一个规则只应该属于一个层级。按钮、输入框、下拉菜单等基础控件问题放到 primitives/；仓库列表、导航栏、动态流等可复用业务块放到 components/；只在某个页面成立的间距、布局和覆盖放到 pages/。
低层不能依赖高层。tokens/ 不能依赖 primitives/、components/ 或 pages/；primitives/ 不能依赖页面结构；components/ 不应该修复具体页面布局。
避免重复定义颜色、阴影、圆角和间距。优先在 themes/ 与 styles/tokens/ 中新增 token，再在其他层使用 var(--gt-*)。
页面级选择器必须足够具体，避免影响全站控件。例如登录页按钮间距问题应该放在登录页或登录组件范围内，不应该修改所有 .ui.button。
命名规则
自定义 CSS 变量统一使用 --gt-* 前缀，例如 --gt-color-accent、--gt-radius-md、--gt-space-lg。
主题名与 Gitea CSS 文件名保持一致。当前默认主题名是 gitea-auto，输出文件是 theme-gitea-auto.css。
样式模块默认导出字符串常量，由 styles/index.ts 按 tokens -> primitives -> components -> pages 顺序聚合。
构建与预览
使用 bun run build 构建未压缩 CSS。
使用 bun run build:min 构建压缩 CSS。
使用 bun run dev 监听样式、主题和 src 文件变化。
使用 bun run preview 启动本地预览页面。
使用 bun run test 构建并检查必要输出是否存在。
使用 bun run compose:up 启动 Gitea 开发容器，使用 bun run compose:down 停止容器。
修改流程
新增视觉值时，先判断是否应该成为 token。能复用的值放到 themes/ 或 styles/tokens/。
修改控件外观时，优先检查 styles/primitives/，确保不会破坏页面级布局。
修改业务组件时，优先放到 styles/components/，并使用组件范围选择器约束影响面。
修改单个页面问题时，放到 styles/pages/，并写明页面级父选择器。
修改模板时，先确认 Gitea 原始模板结构，再把覆盖文件放入 templates/ 或同步到 .gitea/custom/templates/。