argon-theme/.kiro/steering/code-style.md

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 规范

格式化规则

• 使用 Tab 缩进（1 Tab = 4 空格宽度）
• 每个属性独占一行
• 属性之间不要有空行
• 规则块之间保留一个空行
• 选择器与 { 之间有一个空格
• 属性值后的 ; 前不要有空格

示例

/* 正确 */
.selector {
	property: value;
	another-property: value;
}

.another-selector {
	property: value;
}

/* 错误 - 属性之间有空行 */
.selector {

	property: value;

	another-property: value;

}

注释规范

/* ==========================================================================
   大区块标题
   ========================================================================== */

/* ---------- 小区块标题 ---------- */

/* 普通注释 */

---

JavaScript 规范

格式化规则

• 使用 Tab 缩进
• 字符串优先使用单引号 '
• 比较运算符使用严格相等 === 和 !==
• 语句末尾必须有分号 ;
• 函数名与括号之间无空格
• 关键字后有空格（if, for, while, function 等）

变量声明

• 优先使用 let 和 const
• 避免使用 var（除非需要函数作用域或全局变量）

注释规范

// ==========================================================================
// 大区块标题
// ==========================================================================

// ---------- 小区块标题 ----------

/**
 * 函数说明
 * @param {string} param - 参数说明
 * @returns {boolean} 返回值说明
 */
function functionName(param) {
	// 单行注释
	if (param === 'value') {
		return true;
	}
	return false;
}

---

PHP 规范

格式化规则

• 使用 Tab 缩进
• 字符串优先使用单引号
• 数组使用短语法 []
• 类名使用 PascalCase
• 函数名使用 snake_case（遵循 WordPress 规范）
• 箭头操作符 -> 前后不要有空格

WordPress 特定

• 使用 esc_html(), esc_attr() 等函数转义输出
• 使用 wp_nonce_field() 进行安全验证
• 遵循 WordPress Coding Standards

示例

// 正确
$theme->Version
get_option('argon_theme_color')

// 错误
$theme -> Version

---

规范化历史

2026-01-16 规范化

• CSS: 移除 4292 行多余空行，添加结构化注释
• JS: 89 个 var 改为 let，添加模块目录和 JSDoc
• PHP: 修复 200+ 处箭头操作符空格问题
• 备份位置: tmp/ 目录