前端 CSS 代码规范

说明

CSS 规范这里主要集成三个规则集，这三个规则集分别对 CSS 规范中分别对可能的错误、写法、以及书写顺序做了一定的规范，下面会详细列出校验的规则，如果想要添加额外的规则则可以查看 stylelint 官方文档，这里提供了其余 100+ 规则，此文档的规则是检查代码中可能为导致问题的，所以全是强制打开，其余 formatter 相关的规则用户可以自行设置。
stylelint-config-recommended
stylelint-config-rational-order
stylelint-config-prettier

架构前端代码规范
- 遵循最小交集原则
- 遵循最小扯皮原则
- 遵循代码质量优先原则

规则（强制）

1. 颜色应由 6 或 8 个 16 进制数字表示，速记表示应由 3 或 4 个 16 进制数字来表示

✅ 正确例子

a { color: #000; }
a { color: #000f; }
a { color: #fff1a0; }
a { color: #123450aa; }

❌ 错误例子

a { color: #00; }
a { color: #fff1az; }
a { color: #12345aa; }

StyleLint 规则

'color-no-invalid-hex': true,

2. grid 命名必须遵循规范

每一行有相同数量的列标识
至少有一个列标识

✅ 正确例子

a { grid-template-areas: "a a a"
                         "b b b"; }

❌ 错误例子

a { grid-template-areas: "" }
a { grid-template-areas: "a a a"
                         "b b b b"; }
a { grid-template-areas: "a a a"
                         "b b a"; }

StyleLint 规则

'named-grid-areas-no-valid': true

3. 对渐变色函数 linear-gradient() 的第一个参数进行限制，参数必须为合法值

角度
to 标识符到一个边或一个角落

✅ 正确例子

.foo { background: linear-gradient(to top, #fff, #000); }
.foo { background: linear-gradient(to bottom right, #fff, #000
.foo { background: linear-gradient(45deg, #fff, #000); }
.foo { background: linear-gradient(1.57rad, #fff, #000); }
/* Direction defaults to "to bottom" */
.foo { background: linear-gradient(#fff, #000); }

❌ 错误例子

.foo { background: linear-gradient(top, #fff, #000); }
.foo { background: linear-gradient(bottom, #fff, #000); }
.foo { background: linear-gradient(left, #fff, #000); }
.foo { background: linear-gradient(45, #fff, #000); }
.foo { background: linear-gradient(to top top, #fff, #000); }

StyleLint 规则

'function-linear-gradient-no-nonstandard-direction': true

4. 规范声明在 CSS 中字符串不能直接换行，必须使用转义符

✅ 正确例子

a {
  content: "first\Asecond";
}
a {
  content: "first\\nsecond";
}
[title="nothing\
  is wrong"] {}
a {
  font-family: "Times New Roman";
}

❌ 错误例子

a {
  content: "first
    second";
}
[title="something
is probably wrong"] {}
a {
  font-family: "Times
    New
    Roman";
}

StyleLint 规则

'string-no-newline': true

5. 不能使用未在 CSS 标准中声明的单位

✅ 正确例子

a {
  width: 10px;
}
a {
  width: 10Px;
}
a {
  width: 10pX;
}
a {
  width: calc(10px + 10px);
}

❌ 错误例子

a {
  width: 10pixels;
}
a {
  width: calc(10px + 10pixels);
}

StyleLint 规则

'unit-no-unknown': true

6. 自定义属性不能丢失 var 方法

✅ 正确例子

:root { --foo: red; }
a { color: var(--foo); }

❌ 错误例子

:root { --foo: red; }
a { color: --foo; }

StyleLint 规则

'custom-property-no-missing-var-function': true

7. keyframe 声明中使用 !important 会被某些浏览器忽略

✅ 正确例子

@keyframes foo {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

❌ 错误例子

@keyframes foo {
  from {
    opacity: 0;
  }
  to {
    opacity: 1 !important;
  }
}

StyleLint 规则

'keyframe-declaration-no-important': true

8. 在同一个 block 中，这都是开发者的疏忽，因为短规则会覆盖长规则

✅ 正确例子

a { padding: 10px; padding-left: 20px; }
a { transition-property: opacity; } a { transition: opacity 1s linear; }
a { transition-property: opacity; -webkit-transition: opacity 1s linear; }

❌ 错误例子

a {
  padding-left: 10px;
  padding: 20px;
}
a {
  transition-property: opacity;
  transition: opacity 1s linear;
}
a {
  border-top-width: 1px;
  top: 0;
  bottom: 3px;
  border: 2px solid blue;
}

StyleLint 规则

'declaration-block-no-shorthand-property-overrides': true

9. 伪类不能是不规范的

✅ 正确例子

a:hover {}
a:focus {}
:not(p) {}
input:-moz-placeholder {}

❌ 错误例子

a:unknown {}
a:UNKNOWN {}
a:hoverr {}

StyleLint 规则

'selector-pseudo-class-no-unknown': true

10. 伪元素不能是不规范的

✅ 正确例子

a:before {}
a::before {}
::selection {}
input::-moz-placeholder {}

❌ 错误例子

a::pseudo {}
a::PSEUDO {}
a::element {}

StyleLint 规则

'selector-pseudo-element-no-unknown': true

11. 选择器不能是不规范的

✅ 正确例子

input {}
ul li {}

❌ 错误例子

unknown {}
tag {}

StyleLint 规则

'selector-type-no-unknown': true

12. 媒体特性的名称不能是不规范的

✅ 正确例子

@media all and (monochrome) {}
@media (min-width: 700px) {}
@media (min-width: 700px) and (orientation: landscape) {}

❌ 错误例子

@media screen and (unknown) {}
@media screen and (unknown: 10px) {}
@media screen and (unknown > 10px) {}

StyleLint 规则

'media-feature-name-no-unknown': true

13. @ 后的规则名不能是不规范的

✅ 正确例子

@charset "UTF-8";
@media (max-width: 960px) {}
@font-feature-values Font One {
  @styleset {}
}

❌ 错误例子

@unknown {}

StyleLint 规则

'at-rule-no-unknown': true

14. 禁用多余的分号

✅ 正确例子

@import "x.css";
a {
  color: pink;
}

❌ 错误例子

@import "x.css";;

a {
  ;color: pink;
}

a {
  color: red;
}
;
b {
  color: white;
}

StyleLint 规则

'no-extra-semicolons': true

15. 任何 @import 规则都必须位于样式表中所有其他有效的 @ 规则和样式规则之前（忽略 @charset），否则 @import 规则无效

✅ 正确例子

@import 'foo.css';
a {}

@charset 'utf-8';
@import 'foo.css';

❌ 错误例子

a {}
@import 'foo.css';

@media print {}
@import 'foo.css';

StyleLint 规则

'no-invalid-position-at-import-rule': true

16. 不能使用未声明的动画

✅ 正确例子

a { animation-name: fancy-slide; }
@keyframes fancy-slide {}

@keyframes fancy-slide {}
a { animation-name: fancy-slide; }

@keyframes fancy-slide {}
a { animation: fancy-slide 2s linear; }

❌ 错误例子

a { animation-name: fancy-slide; }

a { animation-name: fancccy-slide; }
@keyframes fancy-slide {}

a { animation: fancy-slide 2s linear; }

StyleLint 规则

'no-unknown-animations': true

17. CSS 书写顺序，按照合理的顺序书写

Positioning
Box Model
Typography
Visual
Animation
Misc

✅ 正确例子

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 10;
 
  /* Box Model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;
  margin: 10px;
  padding: 10px;
 
  /* Typography */
  color: #888;
  font: normal 16px Helvetica, sans-serif;
  line-height: 1.3;
  text-align: center;
 
  /* Visual */
  background-color: #eee;
  border: 1px solid #888;
  border-radius: 4px;
  opacity: 1;
 
  /* Animation */
  transition: all 1s;
 
  /* Misc */
  user-select: none;
}

StyleLint 规则

'plugin/rational-order': [
  true,
  {
    'border-in-box-model': false,
    'empty-line-between-groups': false,
    'no-empty-lines-between-properties': true,
  },
]

18. 声明中禁用 important，使用 important 会导致样式无法覆盖

✅ 正确例子

a { color: pink; }

❌ 错误例子

a { color: pink !important; }
a { color: pink!important; }

StyleLint 规则

'declaration-no-important': true

19. 检查 font 和 font-family 中是否有重复的属性值，禁止出现重复的 font 属性值

✅ 正确例子

a { font-family: Times, serif; }

❌ 错误例子

a { font-family: 'Times', Times, serif; }

StyleLint 规则

'font-family-no-duplicate-names': true

20. 检查声明块中是否存在重复的自定义属性，重复的属性可能导致意料之外的结果

✅ 正确例子

a { --custom-property: pink; }

❌ 错误例子

a { --custom-property: pink; --custom-property: orange; }

StyleLint 规则

'declaration-block-no-duplicate-custom-properties': true

21. 检查是否存在重复的属性

✅ 正确例子

a { color: pink; }

❌ 错误例子

a { color: pink; color: orange; }

StyleLint 规则

'declaration-block-no-duplicate-properties': true

22. 在样式表中不能存在相同的导入

✅ 正确例子

@import "a.css";
@import "b.css";

@import url('a.css') projection;
@import url('a.css') tv;

❌ 错误例子

@import 'a.css';
@import 'a.css';

@import url("a.css");
@import url("a.css");

StyleLint 规则

'no-duplicate-at-import-rules': true

23. 样式表中不能存在相同的选择器，可能导致样式被覆盖

✅ 正确例子

.foo {
  .foo {}
}

.foo {}
.bar {}
.foo .bar {}
.bar .foo {}

❌ 错误例子

.foo,
.bar,
.foo {}

.foo, .bar {}.bar, .foo {}

StyleLint 规则

'no-duplicate-selectors': true

配置文件

export default {
  extends: [
    'stylelint-config-recommended',
    'stylelint-config-rational-order',
    'stylelint-config-prettier',
  ],
  rules: {
    // 不能使用未声明的动画
    'no-unknown-animations': true,
    // 不能在声明中使用important
    'declaration-no-important': true,
  },
};