gitea-themes/docs/official-style-map.md

官方样式来源映射

当前基线

当前 github-dev 主题以 Gitea 官方 light 主题为基线，并迁移 .github-theme 的 GitHub Light 增量。github-dev-dark 使用同一套 primitive、component 和 page 规则，但切换到 themes/github-dark/ 的 dark token 源。

官方主题文件：

/.gitea/web_src/css/themes/theme-gitea-light.css

项目入口：

/styles/tokens/index.ts

主题源：

/themes/github-light/index.ts

/themes/github-dark/index.ts

构建输出：

/dist/theme-github-dev.css

/dist/theme-github-dev-dark.css

Gitea custom 输出：

/.gitea/custom/public/assets/css/theme-github-dev.css

/.gitea/custom/public/assets/css/theme-github-dev-dark.css

主题层拆解

themes/github-light/ 当前承载 GitHub Light 颜色主题源数据。themes/github-dark/ 承载 GitHub Dark 颜色主题源数据，当前优先覆盖未登录 explore 页面需要的 body、navbar、input、menu、card、button 等变量。styles/tokens/ 只接收主题对象并渲染成 Gitea 可识别的 :root CSS 变量。构建时不直接读取 .gitea，.gitea 只作为官方源码参考和测试基线。

主题拆分文件：

themes/github-light/theme-meta.ts：主题显示名称和色彩模式元信息。

themes/github-light/core.ts：核心 primary、secondary 和基础明暗变量。

themes/github-light/console.ts：Actions console 和 console 文件使用的颜色。

themes/github-light/named-colors.ts：red、orange、green、blue 等命名色及明暗变体。

themes/github-light/ansi-colors.ts：终端 ANSI 颜色。

themes/github-light/semantic-colors.ts：页面、边框、文本、差异、markup、代码等语义颜色。

themes/github-light/target-colors.ts：组件和状态面向的目标变量，例如 input、menu、card、button、issue、notification、heatmap 等。

styles/tokens/index.ts：读取 currentTheme，通过 token 渲染器输出最终 token CSS。

styles/tokens/render-theme.ts：控制主题 token 输出格式，并在构建时触发必需变量校验。

styles/tokens/required.ts：维护 Gitea 主题必须提供的变量清单。

styles/tokens/derived.ts：维护派生 token 和兼容别名，例如旧样式里使用的 camelCase 变量名。

styles/primitives/ 当前承载 .github-theme/styles/public/ 的源码级迁移模块，例如按钮、输入框、下拉框、菜单、标签、表格、弹窗、提示框等基础控件。官方基础控件来源主要在 .gitea/web_src/css/modules/，例如 button.css、input.css、form.css、checkbox.css、dropdown.css、table.css、menu.css、tippy.css。

styles/components/ 当前承载 .github-theme/styles/components/ 中非页面级业务组件，以及 .github-theme/styles/templates/ 的模板专属样式迁移。官方可复用业务组件来源主要在 .gitea/web_src/css/repo/、.gitea/web_src/css/features/、.gitea/web_src/css/shared/，例如 repo/home-file-list.css、repo/clone.css、features/heatmap.css、features/gitgraph.css、shared/flex-list.css。

styles/pages/ 当前承载 .github-theme/styles/components/ 中实际属于页面布局的迁移模块，例如 dashboard、explore、newrepo、org、setting、signin、user。官方页面级来源主要在 .gitea/web_src/css/ 根目录，例如 dashboard.css、explore.css、install.css、org.css、repo.css、user.css、admin.css、actions.css。

迁移原则

第一阶段已经完成官方主题 token 拆分。当前阶段迁移 .github-theme 的 GitHub Light token、primitive、component 和 page/template 覆盖。

样式迁移采用源码模块级迁移，不落地第三方编译后的单文件 CSS。styles/primitives/、styles/components/、styles/pages/ 下的模块都对应 .github-theme/styles/ 的原始职责目录，并保留可读的嵌套 CSS 结构。

.github-theme/templates/ 已迁移到本项目 templates/，构建时同步到 .gitea/custom/templates/。

.github-theme/options/ 已迁移到本项目 options/，构建时同步到 .gitea/custom/options/。

后续迁移时，如果只是改颜色主题值，优先放到 themes/。styles/tokens/ 只负责把当前主题输出成 CSS 变量，不直接维护具体颜色表。

如果要改所有按钮、输入框、表单、下拉菜单等基础控件，放到 styles/primitives/，并确认这是全站影响。

如果只改仓库列表、热力图、动态列表、clone 面板等业务组件，放到 styles/components/。

如果只改 dashboard、explore、登录页、组织创建页等页面布局，放到 styles/pages/。

校验方式

bun run test 会执行四步：

1. 构建 theme-github-dev.css 和 theme-github-dev-dark.css。
2. 检查 dist/ 和 .gitea/custom/ 输出存在且非空。
3. 检查生成的 CSS 包含 GitHub Light/Dark token、全局控件、仓库组件、登录页和模板专属规则。
4. 检查模板覆盖和 locale 输出已经同步到 .gitea/custom/。

bun run docker:test 会执行三步：

1. 构建 theme-github-dev.css 和 theme-github-dev-dark.css。
2. 启动 Gitea Docker 预览容器。
3. 检查首页返回 200，首页 HTML 加载 /assets/css/theme-github-dev-dark.css，并确认 light/dark 主题 CSS 内包含迁移后的变量和组件规则。