# 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 版本或显式远程刷新时更新。