CSS 编码规范

本规范适用于 CSS 及其预编译语言（Sass、Less）的编码风格，部分规则可通过 stylelint 工具实现。

1 CSS

1.1 编码规范

具体规则如下：

1.1.1 【强制】所有声明必须以分号结尾

stylelint: declaration-block-trailing-semicolon

虽然 CSS 语法中最后一条声明的分号是可选的，但统一使用分号能提高代码一致性和可维护性。

/* bad */
.selector {margin-top: 10pxpadding-left: 15px
}/* good */
.selector {margin-top: 10px;padding-left: 15px;
}

1.1.2 【推荐】使用 2 个空格缩进

stylelint: indentation

/* bad */
.selector {padding-left: 15px;
}/* good */
.selector {padding-left: 15px;
}

1.1.3 【推荐】选择器与 { 之间保留一个空格

stylelint: block-opening-brace-space-before

/* bad */
.selector{padding-left: 15px;
}/* good */
.selector {padding-left: 15px;
}

1.1.4 【推荐】属性值规范

stylelint: declaration-colon-space-after, declaration-colon-space-before

/* bad */
.selector {margin-top : 10px;padding-left:15px;
}/* good */
.selector {margin-top: 10px;padding-left: 15px;
}

1.1.5 【推荐】组合器规范

stylelint: selector-combinator-space-before, selector-combinator-space-after

/* bad */
.selector>.children {padding-left: 15px;
}
.selector+.brother {padding-left: 15px;
}/* good */
.selector > .children {padding-left: 15px;
}
.selector + .brother {padding-left: 15px;
}

1.1.6 【推荐】逗号分隔规范

stylelint: value-list-comma-space-after

/* bad */
.selector {background-color: rgba(0,0,0,0.5);box-shadow: 0px 1px 2px rgba(0,0,0,0.5),inset 0 1px 0 rgba(255,255,255,0.5);
}/* good */
.selector {background-color: rgba(0, 0, 0, 0.5);box-shadow: 0px 1px 2px rgba(0, 0, 0, 0.5), inset 0 1px 0 rgba(255, 255, 255, 0.5);
}

1.1.7 【推荐】注释规范

stylelint: comment-whitespace-inside

/* bad */
.selector {/*comment*//*  comment  *//***comment*/padding-left: 15px;
}/* good */
.selector {/* comment *//*** comment*/padding-left: 15px;
}

1.1.8 【推荐】右大括号规范

声明块的右大括号 } 应单独成行。

/* 不推荐 */
.selector {padding-left: 15px;}/* 推荐 */
.selector {padding-left: 15px;
}

1.1.9 【推荐】属性声明规范

属性声明应单独成行。
stylelint: declaration-block-single-line-max-declarations

/* 不推荐 */
.selector {padding-left: 15px;  margin-left: 10px;
}/* 推荐 */
.selector {padding-left: 15px;margin-left: 10px;
}

1.1.10 【推荐】代码行长度规范

单行代码长度不超过 100 个字符。
stylelint: max-line-length
例外情况：

• 使用 url() 函数时
• 属性值本身无法换行（不含空格或逗号）

/* 不推荐 */
background-image: -webkit-gradient(linear, left bottom, left top, color-stop(0.04, rgb(88, 94, 124)), color-stop(0.52, rgb(115, 123, 162)));/* 推荐 */
background-image: -webkit-gradient(linear,left bottom,left top,color-stop(0.04, rgb(88, 94, 124)),color-stop(0.52, rgb(115, 123, 162))
);

1.1.11 【参考】多选择器规范

多个选择器应分行书写。
stylelint: selector-list-comma-newline-after

/* 不推荐 */
.selector, .selector-secondary, .selector-third {padding: 15px;margin-bottom: 15px;
}/* 推荐 */
.selector,
.selector-secondary,
.selector-third {padding: 15px;margin-bottom: 15px;
}

1.1.12 【参考】单行声明规范

即使声明块内只有一条语句，也应使用多行格式。

/* 不推荐 */
.selector { padding-left: 15px; }/* 推荐 */
.selector {padding-left: 15px;
}

1.1.13 【参考】注释规范

注释上方需留空行（除非上方是注释或块顶部）。
stylelint: comment-empty-line-before

/* 不推荐 */
.selector {/* 注释 */padding-left: 15px;/* 注释 */padding-right: 15px;
}/* 推荐 */
.selector {/* 注释 */padding-left: 15px;/* 注释 */padding-right: 15px;
}

1.2 选择器规范

1.2.1 【参考】避免使用 ID 选择器

stylelint: selector-max-id
ID 选择器优先级过高，会导致后续样式难以覆盖，可能引发 !important 滥用。

/* 不推荐 */
#special {padding: 15px;
}/* 推荐 */
.special {padding: 15px;
}

1.2.2 【参考】属性选择器引号规范

属性选择器的值需用双引号包裹。
stylelint: selector-attribute-quotes

/* 不推荐 */
input[type=text] {height: 20px;
}/* 推荐 */
input[type="text"] {height: 20px;
}

1.2.3 【参考】选择器性能优化

优化建议：

1. 优先使用 class 而非元素标签
2. 避免在常用组件中使用属性选择器（如 [class^=“…”])
3. 控制选择器长度（不超过3个组合）

选择器效率排序（高→低）：
ID 选择器（#header）
类选择器（.header）
标签选择器（div）
相邻兄弟选择器（h2 + p）
子选择器（ul > li）
后代选择器（ul a）
通配符选择器（*）
属性选择器（[class^=“grid-”]）
伪类/伪元素选择器（a:hover, a::before）

1.3.属性和属性值

1.3.1.【推荐】使用简短的十六进制值。

stylelint: color-hex-length

/* 不推荐 */
.selector {color: #ffffff;
}/* 推荐 */
.selector {color: #fff;
}

1.3.2.【推荐】避免使用!important覆盖样式。

1.3.3.【推荐】十六进制值统一使用小写字母（更易辨识）。

stylelint: color-hex-case

/* 不推荐 */
.selector {color: #FEFEFE;
}/* 推荐 */
.selector {color: #fefefe;
}

1.3.4.【推荐】当长度值为0时，省略单位。

stylelint: length-zero-no-unit

/* 不推荐 */
.selector {margin-top: 0px;font-size: 0em;
}/* 推荐 */
.selector {margin-top: 0;font-size: 0;
}

1.3.5.【参考】保留小数点前的0。

stylelint: number-leading-zero

/* 不推荐 */
.selector {opacity: .5;left: -.5px;
}/* 推荐 */
.selector {opacity: 0.5;left: -0.5px;
}

1.3.6.【参考】属性声明顺序建议：

1. 定位属性（position、z-index等）
2. 盒模型属性（display、width等）
3. 排版属性（font、color等）
4. 外观属性（background等）
5. 其他属性

1.3.7.【参考】合理使用简写属性。

stylelint: declaration-block-no-shorthand-property-overrides

/* 不推荐 */
.selector {margin: 0 0 10px;
}/* 推荐 */
.selector {margin-bottom: 10px;
}

1.4.其他

1.4.1.【推荐】避免使用CSS的@import。

与 相比，@import 会在关键渲染路径上增加更多的往返（即关键路径的深度变长），这样会导致浏览器处理 CSS 文件速度变慢，因此我们应该避免使用 @import。

/* 不推荐 */
<style>@import url("more.css");
</style>/* 推荐 */
<link rel="stylesheet" href="more.css">

2.Sass和Less

2.1.【推荐】运算符两侧保留空格：

/* 推荐 */
.selector {width: $default-width / 2;
}

2.2.【推荐】Mixin格式规范：

/* 推荐 */
.selector {.size(30px, 20px);.clearfix();
}

2.3.【推荐】代码组织顺序：

1. @import语句
2. 全局变量声明
3. 样式声明

2.4.【推荐】块内属性声明顺序：

1. 标准属性
2. mixin调用
3. 嵌套选择器

2.5.【推荐】嵌套选择器不超过3层。

2.6.【推荐】注释规范：

• 双斜杠注释编译后会被删除
• /**/注释会被保留

2.7.【推荐】优先使用Mixin而非@extend。

使用 Mixin（通过 @mixin 和 @include 指令）提升代码复用性，遵循 DRY 原则（Don’t Repeat Yourself），同时增强代码抽象能力并降低复杂度。

不建议使用 @extend 指令，因其存在以下问题：

1. 可读性较差，尤其在嵌套选择器中表现尤为明显
2. 具有潜在风险，当选择器顺序发生变化时（特别是跨文件引用时）可能导致样式异常

虽然 @extend 相比无参数 Mixin 能减少编译后的代码量（避免重复输出），但现代压缩工具（如 gzip）能有效处理重复代码。因此，建议优先使用 Mixin 来实现 DRY 原则。