diff --git a/.kiro/steering/code-style.md b/.kiro/steering/code-style.md index fcb0699..4118d11 100644 --- a/.kiro/steering/code-style.md +++ b/.kiro/steering/code-style.md @@ -1,5 +1,58 @@ # Argon 主题代码规范 +## 项目文件结构 + +### 核心文件 +| 文件 | 说明 | 行数 | +|------|------|------| +| `style.css` | 主题样式,包含所有 CSS | ~12000 行 | +| `argontheme.js` | 主题核心 JS | ~3700 行 | +| `functions.php` | WordPress 函数 | ~5700 行 | +| `settings.php` | 后台设置页面 | ~6000 行 | + +### style.css 结构 +``` +1. CSS 变量定义 (:root) + - 主题色系统 (--themecolor-*) + - 颜色变量 (--color-*) + - 动画系统 (--animation-*, --ease-*) +2. 夜间模式配色 (html.darkmode) +3. AMOLED 夜间模式 +4. 沉浸式主题色 +5. 主题切换过渡效果 +6. Argon 框架样式覆盖 +7. 基础样式 +8. 页面布局 (单栏/双栏/三栏) +9. 顶栏和 Banner +10. 侧边栏 +11. 文章样式 +12. 评论区 +13. 浮动按钮 +14. 响应式适配 +``` + +### argontheme.js 结构 +``` +1. 兼容性修复 - 第三方库 polyfill +2. 全局配置 - argonConfig 初始化 +3. 工具函数 - Cookie、翻译等 +4. 顶栏功能 - 透明度、搜索 +5. 侧边栏 - 浮动、滚动 +6. 文章列表 - 瀑布流布局 +7. 浮动按钮 - 回顶、设置 +8. 评论系统 - 发送、回复、编辑 +9. 代码高亮 - Prism 增强 +10. PJAX - 页面无刷新加载 +``` + +### 全局变量(需保留 var) +- `argonConfig` - 主题配置对象 +- `translation` - 多语言翻译表 +- `pjaxLoading` - PJAX 加载状态 +- `headroom` - Headroom 实例 + +--- + ## CSS 规范 ### 格式化规则 @@ -33,9 +86,17 @@ ``` ### 注释规范 -- 区块注释使用 `/* ========== 区块名称 ========== */` -- 普通注释使用 `/* 注释内容 */` -- 多行注释每行以 ` * ` 开头 +```css +/* ========================================================================== + 大区块标题 + ========================================================================== */ + +/* ---------- 小区块标题 ---------- */ + +/* 普通注释 */ +``` + +--- ## JavaScript 规范 @@ -49,16 +110,15 @@ ### 变量声明 - 优先使用 `let` 和 `const` -- 避免使用 `var`(除非需要函数作用域) +- 避免使用 `var`(除非需要函数作用域或全局变量) ### 注释规范 -- 区块注释使用 `// ========== 区块名称 ==========` -- 函数注释使用 JSDoc 格式 -- 单行注释使用 `//` - -### 示例 ```javascript -// ========== 功能模块名称 ========== +// ========================================================================== +// 大区块标题 +// ========================================================================== + +// ---------- 小区块标题 ---------- /** * 函数说明 @@ -66,6 +126,7 @@ * @returns {boolean} 返回值说明 */ function functionName(param) { + // 单行注释 if (param === 'value') { return true; } @@ -73,6 +134,8 @@ function functionName(param) { } ``` +--- + ## PHP 规范 ### 格式化规则 @@ -81,8 +144,29 @@ function functionName(param) { - 数组使用短语法 `[]` - 类名使用 PascalCase - 函数名使用 snake_case(遵循 WordPress 规范) +- 箭头操作符 `->` 前后不要有空格 ### WordPress 特定 - 使用 `esc_html()`, `esc_attr()` 等函数转义输出 - 使用 `wp_nonce_field()` 进行安全验证 - 遵循 WordPress Coding Standards + +### 示例 +```php +// 正确 +$theme->Version +get_option('argon_theme_color') + +// 错误 +$theme -> Version +``` + +--- + +## 规范化历史 + +### 2026-01-16 规范化 +- CSS: 移除 4292 行多余空行,添加结构化注释 +- JS: 89 个 var 改为 let,添加模块目录和 JSDoc +- PHP: 修复 200+ 处箭头操作符空格问题 +- 备份位置: `tmp/` 目录