Refactor theme management and update documentation

- Removed `.github-theme` from .gitignore as it is no longer needed. - Updated `official-style-map.md` to clarify the maintenance of GitHub Light style increments within the current repository. - Revised `rules.md` to reflect the new approach to maintaining GitHub Light theme increments. - Changed test script in `package.json` to verify generated theme instead of GitHub migration. - Added `verify-generated-theme.ts` script to validate the generated theme files. - Migrated various styles from `.github-theme` to the new structure, updating comments and references accordingly.
2026-05-18 01:26:17 +08:00
parent c0fd79dca8
commit 434161de5b
63 changed files with 12 additions and 87 deletions
@@ -1,5 +1,4 @@
 .gitea
-.github-theme
 .gitea-data
 dist
 release
@@ -2,7 +2,7 @@

 ## 当前基线

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

 官方主题文件：

@@ -58,21 +58,21 @@ Gitea custom 输出：

 `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/primitives/` 当前承载本项目基础控件模块，例如按钮、输入框、下拉框、菜单、标签、表格、弹窗、提示框等。官方基础控件来源主要在 `.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/components/` 当前承载本项目非页面级业务组件，以及模板专属样式。官方可复用业务组件来源主要在 `.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`。
+`styles/pages/` 当前承载本项目页面布局模块，例如 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 覆盖。
+第一阶段已经完成官方主题 token 拆分。当前阶段在本仓库内维护 GitHub Light token、primitive、component 和 page/template 覆盖。

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

-`.github-theme/templates/` 已迁移到本项目 `templates/`，构建时同步到 `.gitea/custom/templates/`。
+模板覆盖由本项目 `templates/` 维护，构建时同步到 `.gitea/custom/templates/`。

-`.github-theme/options/` 的 locale 增量已迁移到本项目 `options/locale-overrides/`。构建时 `scripts/locale.ts` 会从 Gitea 官方 `v1.26.1` 获取完整 locale，再合并本项目增量并输出到 `.gitea/custom/options/locale/`。
+locale 增量由本项目 `options/locale-overrides/` 维护。构建时 `scripts/locale.ts` 会从 Gitea 官方 `v1.26.1` 获取完整 locale，再合并本项目增量并输出到 `.gitea/custom/options/locale/`。

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

@@ -62,7 +62,7 @@

 ## 修改流程

-官方样式基线和源码映射见 `docs/official-style-map.md`。当前项目先拆分官方 `theme-gitea-light.css`，再按当前分层迁移 `.github-theme` 的 GitHub Light 增量。
+官方样式基线和源码映射见 `docs/official-style-map.md`。当前项目先拆分官方 `theme-gitea-light.css`，再在当前仓库内维护 GitHub Light 风格的主题增量。

 新增视觉值时，先判断是否应该成为 token。颜色和主题值放到 `themes/`；派生变量、Gitea 兼容别名和必需变量校验放到 `styles/tokens/`。

@@ -12,7 +12,7 @@
        "dev": "bun scripts/build.ts --watch",
        "preview": "bun run build && bun scripts/preview.ts",
        "build:min": "bun scripts/build.ts --minify",
-        "test": "bun run build && bun scripts/verify-theme.ts && bun scripts/verify-github-migration.ts",
+        "test": "bun run build && bun scripts/verify-theme.ts && bun scripts/verify-generated-theme.ts",
        "compose:up": "docker compose -f compose.dev.yaml up -d",
        "compose:down": "docker compose -f compose.dev.yaml down",
        "compose:logs": "docker compose -f compose.dev.yaml logs -f server",
@@ -36,22 +36,6 @@ if (packageJson.version !== "1.26.1") {
  throw new Error(`project version must be 1.26.1, got ${packageJson.version}`);
 }

-try {
-  const githubThemePackageJson = JSON.parse(
-    await readFile(join(root, ".github-theme", "package.json"), "utf8"),
-  ) as { version?: string };
-
-  if (githubThemePackageJson.version !== "1.26.1") {
-    throw new Error(`.github-theme version must be 1.26.1, got ${githubThemePackageJson.version}`);
-  }
-} catch (error) {
-  const code = error instanceof Error && "code" in error ? error.code : undefined;
-
-  if (code !== "ENOENT") {
-    throw error;
-  }
-}
-
 await access(join(root, "themes", "index.ts"));
 await access(join(themeSourceDir, "index.ts"));
 await access(join(darkThemeSourceDir, "index.ts"));
@@ -94,7 +78,7 @@ for (const file of ["theme-meta.ts", "core.ts", "github-colors.ts", "target-colo

 for (const snippet of requiredSnippets) {
  if (!generated.includes(snippet)) {
-    throw new Error(`generated theme is missing migrated GitHub theme snippet: ${snippet}`);
+    throw new Error(`generated theme is missing required snippet: ${snippet}`);
  }
 }

@@ -104,4 +88,4 @@ for (const snippet of requiredDarkSnippets) {
  }
 }

-console.log("generated GitHub theme migration verified");
+console.log("generated theme verified");
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/actions/action_svg.ts.

 export const actionSVG = `
 .page-content.repository.actions,
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/actions/actions.ts.

 export const actions = `
 /* 避免锚中设置界面里的 Actions */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/actions/workflow_runs.ts.

 export const actionViewHeader = `
 .action-view-header {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/actions/workflow_steps.ts.

 export const actionViewRight = `
 .action-view-right {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/actions/workflow_summary.ts.

 export const summaryView = `
 .action-view-right:has(.action-run-summary-view) {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/footer.ts.

 export const footer = `
 .page-footer {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/heatmap.ts.

 export const heatmap = `
 #user-heatmap {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/issues/issue.ts.

 export const button = `
 /* 工单&PR标题右侧按钮 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/issues/issue_comment.ts.

 export const comment = `
 .comment .comment-container {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/issues/issue_list.ts.

 export const issueList = `
 /* 仓库页面的里程碑列表菜单栏 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/issues/issue_sidebar.ts.

 export const issueSidebar = `
 /* 创建PR页面 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/issues/issue_timeline.ts.

 export const timeline = `
 .repository.view.issue {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/navbar.ts.

 export const navbarRight = `
 #navbar {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/notification.ts.

 export const notification = `
 .page-content.user.notification {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/clone.ts.

 export const clone = `
 .tippy-box {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/commit.ts.

 export const commit = `
 .page-content.repository.commits {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/diff.ts.

 export const diff = `
 /* 这里的折叠行和代码行高度与 GitHub 的 release 和 review 的差异对比时的高度一致, 不需要像 commit 中的差异对比那样行高过高 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/milestones.ts.

 export const milestone = `
 /* 里程碑头部 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/packages.ts.

 export const packagesList = `
 .page-content.packages {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/release.ts.

 export const releaseTagMenu = `
 .page-content.repository {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/repo.ts.

 export const repoHeader = `
 .page-content.repository .repo-header {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/repo_file_view.ts.

 export const repoFileView = `
 /* 隐藏主内容的下内容和页脚, 避免滚动文件树时滚动条遮挡 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/repo_files.ts.

 export const branchButton = `
 .page-content.repository.file.list {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/repo/repo_sidebar.ts.

 export const repoGrid = `
 .repo-grid-filelist-sidebar {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/templates/repo/commit_sign_badge.ts.

 export const commitSignBadge = `
 a.ui.label.commit-id-short.gitea-github-theme-commit-sha {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/templates/repo/commits_list.ts.

 export const commitsList = `
 ul.gitea-github-theme-templates-commits-list {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/templates/repo/view_content.ts.

 export const repoButtonRow = `
 .gitea-github-theme-templates {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/templates/repo/view_list.ts.

 export const repoFileLastCommit = `
 /* 仓库页和文件列表文件夹页的最后一次提交 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/dashboard.ts.

 export const dashboard = `
 .page-content.dashboard {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/explore.ts.

 export const repoList = `
 /* 组织 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/newrepo.ts.

 export const newRepo = `
 .page-content.repository.new-repo {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/org.ts.

 export const org = `
 .page-content.organization {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/setting.ts.

 export const button = `
 /* 不包含管理员的设置界面 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/signin.ts.

 export const signIn = `
 .page-content.user.signin {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/components/user.ts.

 export const stars = `
 .page-content.user.profile {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/attached.ts.

 export const attached = `
 /* 设置右面板的内容 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/base.ts.

 export const body = `
 body {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/button.ts.

 export const baseButton = `
 .ui.button {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/dropdown/branch_dropdown.ts.

 export const branchDropdown = `
 .ui.dropdown.branch-selector-dropdown > .menu {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/dropdown/dropdown.ts.

 export const dropdown = `
 .ui.dropdown,
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/dropdown/emoji_dropdown.ts.

 export const emojiDropdown = `
 .ui.dropdown.action.select-reaction.active .menu:has(.emoji) {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/dropdown/selection_dropdown.ts.

 export const selectionDropdown = `
 /* 排除可以选择的输入搜索框和创建仓库的拥有者 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/input.ts.

 export const input = `
 textarea,
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/label/label.ts.

 export const label = `
 .ui.label {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/label/repo_label.ts.

 export const repoLabel = `
 span,
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/label/sha_label.ts.

 export const shaLabel = `
 a.ui.label.sha,
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/label/task_status_label.ts.

 export const taskStatusLabel = `
 .runner-container .ui.label.task-status- {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/menu/compact_menu.ts.

 export const smallCompactMenu = `
 /* 编辑/预览切换菜单(仓库编辑文件时的编辑器操作栏左侧) */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/menu/menu.ts.

 export const menu = `
 .ui.menu {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/menu/pagination_menu.ts.

 export const paginationMenu = `
 .ui.borderless.pagination.menu {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/menu/secondary_menu.ts.

 export const secondaryMenu = `
 /* 二级菜单, 比如 Issue/PR/Actions 的筛选菜单 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/menu/vertical_menu.ts.

 export const verticalMenu = `
 /* 垂直菜单, 用于左侧边栏 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/modal.ts.

 export const modal = `
 .ui.modal {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/other.ts.

 export const text = `
 /* 默认颜色是 --color-text-light, 主题下此颜色是亮白色, 修改为灰色 */
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/radius.ts.

 export const radius = `
 .ui.form textarea,
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/table.ts.

 export const table = `
 .ui.table > tr > td,
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/tippy.ts.

 export const tippyBox = `
 .tippy-box {
@@ -1,4 +1,3 @@
-// Migrated from .github-theme/styles/public/transition.ts.

 export const transition = `
 /* 差异对比的代码折叠按钮 */