update contributing

2026-10-28 09:44:55 +00:00 · 2026-06-05 19:32:54 +08:00
1 parent bc62222bb7
commit 43ca7d2c3d
@@ -2,16 +2,25 @@

 ## 目录结构

-| 目录              | 说明                         |
-| ----------------- | ---------------------------- |
-| src               | 主题生成框架与辅助工具的包   |
-| src/core          | 主题生成框架                 |
-| src/functions     | 主题辅助工具                 |
-| src/types         | 主题的颜色变量定义           |
-| styles            | 主题样式                     |
-| styles/components | 具体页面的元素的样式         |
-| styles/public     | 基础元素或跨页面的元素的样式 |
-| themes            | 颜色主题                     |
+| 目录              | 说明                                      |
+| ----------------- | ----------------------------------------- |
+| src               | 主题生成框架与辅助工具的包                |
+| src/core          | 主题生成框架（CSS 变量、语法高亮样式）    |
+| src/functions     | 主题辅助工具（颜色计算等）                |
+| src/palette       | 主题调色板（GitHub / Gitea / Catppuccin） |
+| src/types         | 主题颜色变量类型定义                      |
+| src/vite-plugin   | 主题的 Vite 构建插件                      |
+| styles            | 主题样式覆盖                              |
+| styles/common     | 可复用的 CSS 样式片段                     |
+| styles/public     | 基础元素或跨页面元素的样式                |
+| styles/components | 具体页面的样式                            |
+| styles/templates  | 模板专属样式                              |
+| themes            | 颜色主题定义                              |
+| primer            | 自动生成的 Primer 设计令牌                |
+| scripts           | 构建和工具脚本                            |
+| templates         | Gitea 模板覆盖（可选）                    |
+| gitea             | 上游 Gitea 参考文件                       |
+| screenshots       | 主题截图                                  |

 ## 贡献说明

@@ -25,11 +34,11 @@

 > [!IMPORTANT]
 >
-> 提交 PR 时, 请执行 `npm run commit`
+> 提交 PR 时, 请执行 `bun commit`

 ## 开发环境

-主题仅依赖于 Node.js 环境, 请确保你的环境中已经安装了 Node.js, 推荐使用 Node.js 20 或以上版本.
+主题依赖于 Bun 环境, 请确保你的环境中已经安装了 Bun, 推荐使用 Bun 1.3.14 或以上版本.

 请使用 VSCode 开发, 并安装仓库中推荐的插件.

@@ -42,7 +51,7 @@
 ### 安装依赖

 ```bash
-npm install
+bun install
 ```

 ### 设置环境变量
@@ -53,119 +62,123 @@ npm install

 ### 编译主题

-编译开发中的主题
+编译并同步到远程服务器预览

 ```bash
-npm run dev
+bun bundle:dev
 ```

 编译所有主题

 ```bash
-npm run build
+bun bundle
 ```

 格式化项目中的代码

 ```bash
-npm run format
+bun format
 ```

 用于 PR, 检查并编译项目中的所有代码并进行格式化

 ```bash
-npm run commit
+bun commit
 ```

 ## 开发规范

-`src`, `styles`, `themes` 为项目的主目录, 主目录下的第一个目录为模块.
+`src`, `styles`, `themes` 为项目的主目录.

-主目录或主目录下模块互相引用时, 请使用绝对路径, 例如 `import { defineTheme } from "src"`
+跨模块引用时使用 package exports 路径, 例如 `import { defineTheme } from "@lutinglt/gitea-github-theme/core"`

-模块下的文件互相引用时, 请使用相对路径, 例如 `import { defineTheme } from "./theme"`
+同模块内文件互相引用时使用相对路径, 例如 `import { defineTheme } from "./theme"`

 ## 颜色主题贡献

-颜色主题名称格式: `主题名称-dark.css.ts` 或 `主题名称-light.css.ts`, 分别表示深色和亮色主题.
+主题文件命名格式: `主题名称.ts`，配合 `theme.config.ts` 注册使用。

-如果主题有深色和亮色模式, 会自动生成自动颜色主题, 不需要手动添加.
+如果主题同时有深色和亮色变体, 框架会自动生成 auto 自动颜色主题.

 项目接受自定义主题并会附加到发布的版本中, 但项目所有者不参与维护和审核.

 请在颜色主题文件头部附加自己的作者信息, 方便 Issue 提问者找到你 `@`.

-推荐使用 `import { defineTheme, type ThemeColor } from "src"` 导入主题生成框架, 声明主题颜色, 然后使用 `defineTheme`
-函数生成主题所有 CSS 变量, defineTheme 中设置了一些经过计算得到的 Gitea 变量可以减少工作量, 具体请查看函数说明和定义.
+推荐使用 `defineTheme` 配合 `ThemeColor` 类型来定义主题颜色, 框架会自动计算生成所有 Gitea CSS 变量.

-颜色计算函数可以从 `src/functions` 导入, 例如 `import { scaleColorLight } from "src/functions"`, 或者使用 `polished` 库.
+颜色计算函数可从 `@lutinglt/gitea-github-theme/core` 导入 `scaleColorLight`, 或使用 `polished` 库.

-例: `themes/主题名称-dark.css.ts`
+例: `themes/主题名称.ts`

 ```ts
 /**
 * @author 你的名字
 * @description 主题描述
 */
-import { defineTheme, type ThemeColor } from "src";
-export const 主题名称DarkColors: ThemeColor = {
-  ...
-}
-export default defineTheme(主题名称DarkColors);
-// 使用其他主题颜色作为基础
-import dark from "themes/dark";
-import { darkColors } from "themes/dark";
-export const 主题名称DarkColors: ThemeColor = darkColors;
-export default defineTheme({
-  ...dark,
-  ...
-});
-```
+import { defineTheme, scaleColorLight } from "@lutinglt/gitea-github-theme/core";
+import type { ThemeColor, Syntax } from "@lutinglt/gitea-github-theme/core";

-如果不需要自定义代码高亮色, 则不传递 chroma 参数, 框架会自动根据主题的暗色或亮色生成代码高亮色.
-
-如果需要完全自定义每个 Gitea 变量, 请导入 `import type { Theme } from "src"`
-
-例: `themes/主题名称-dark.css.ts`
-
-```ts
-/**
- * @author 你的名字
- * @description 主题描述
- */
-import type { Theme, Chroma, Primary, Secondary, ... } from "src";
-export const primary: Primary = ...;
-export const secondary: Secondary =...;
-export const chroma: Chroma =...;
-...
-export default theme: Theme = {
-  primary,
-  secondary,
-  chroma,
-  ...
+const themeColor: ThemeColor = {
+  isDarkTheme: true,
+  primary: "#0969da",
+  primaryContrast: "#f0f6fc",
+  secondary: "#30363d",
+  base: { red: "#f85149", orange: "#d29922" /* ... */ },
+  console: {
+    /* ... */
+  },
+  diff: {
+    /* ... */
+  },
+  other: {
+    /* ... */
+  },
+  github: {
+    /* ... */
+  },
 };
+
+const syntaxColor: Syntax = {
+  /* 自定义代码高亮色, 或导入使用其他主题的代码高亮色 */
+};
+
+export default defineTheme({ colorType: "theme", themeColor, syntaxColor });
 ```

-完成主题颜色开发后, 请在某个仓库的代码文件列表页, 打开 Code 菜单选择 Tea Cli 进行截图, 并放入 `screenshots`
-目录下, 截图名与主题名相同. (推荐克隆本仓库, 避免泄露个人隐私)
+如需使用 Gitea 原生颜色格式, 使用 `colorType: "gitea"` 配合 `GiteaColor` 类型:

-然后将截图信息添加到 `README.md` 文件中, 可以在折叠部分中添加自己的说明.
+```ts
+import type { GiteaColor, Syntax } from "@lutinglt/gitea-github-theme/core";
+import { defineTheme } from "@lutinglt/gitea-github-theme/core";

-主题颜色复用案例可以参考本主题的色盲主题.
+const giteaColor: GiteaColor = {
+  /* ... */
+};
+const syntaxColor: Syntax = {
+  /* ... */
+};
+export default defineTheme({ colorType: "gitea", themeColor: giteaColor, syntaxColor });
+```
+
+完成主题颜色开发后, 在 `theme.config.ts` 中注册主题系列, 编译后在 Gitea 实例中截图放入 `screenshots`
+目录, 截图名与主题名相同. (推荐克隆本仓库, 避免泄露个人隐私)
+
+然后将截图信息添加到 `README.md` 文件中.
+
+颜色复用案例可参考 `themes/github.ts` 的色盲主题实现.

 ## 主题样式贡献

-主题样式使用 TypeScript 的 css 模板字符串开发, 该模板字符串会经过 sass 预处理器处理, 支持 SCSS 语法并且主题只接受 SCSS 嵌套语法, 请不要使用 CSS 语法, 如果一定要用请说明原因.
+主题样式使用 `css()`
+模板字符串开发，字符串经过 LightningCSS 处理, 支持 CSS 嵌套语法。请勿使用 SCSS 函数，如需复杂处理请使用 TypeScript 相关库，比如项目自带的
+`polished` 库。

-请尽量不要使用 SCSS 的函数, `vscode-styled-components` 插件会报错, 请使用 TypeScript 相关库处理, 比如主题自带的
-`polished` 库.
+推荐需要复杂处理时，提取逻辑到 `src/functions` 目录下的函数中。

-推荐需要使用复杂处理时, 提取逻辑到 `src/functions` 目录下的函数中, 然后在 `src/styles` 目录下的样式文件中使用.
+主题样式中使用到的所有颜色必须使用颜色变量，导入 `import { themeVars } from "@lutinglt/gitea-github-theme/core"`

-主题样式中使用到的所有颜色必须使用颜色变量, 颜色变量导入 `import { themeVars } from "src/types/vars"`
-
-涉及到主题自己的颜色变量 `${themeVars.github.xxx}`, 在使用时请将使用的文件和变量添加到对应变量的注释中
+涉及到主题自己的颜色变量 `${themeVars.github.xxx}`，在使用时请将使用的文件和变量添加到对应变量的注释中
 `src/types/color/github`

-小型圆角(6px)请使用全局圆角变量, 圆角变量导入 `import { otherThemeVars } from "src/types/vars"`
-`${otherThemeVars.border.radius}`
+小型圆角 (6px) 请使用全局圆角变量，导入
+`import { otherThemeVars } from "@lutinglt/gitea-github-theme/core"`，`${otherThemeVars.border.radius}`