Go Wiki: Go CSS 编码规范

在编辑此页面之前，请先讨论更改，即使是微小的更改。很多人都有自己的想法，这里不是进行编辑战的地方。

Go 的命名约定借鉴了Medium 的风格指南以及SUIT CSS 框架中的工作。也就是说，它依赖于结构化的类名和有意义的连字符（即，不只是用连字符来分隔单词）。这是为了帮助绕过当前将 CSS 应用于 DOM 的限制（即缺乏样式封装），并更好地传达类之间的关系。

我们要求使用纯 CSS 而非预处理器，如 LESS、SASS 等。这是为了避免额外的工具依赖。

JavaScript

语法：js-<targetName>

特定于 JavaScript 的类可以减少由于组件结构或主题的更改而无意中影响任何必需的 JavaScript 行为和复杂功能的风险。如果您通过 JavaScript 与 DOM 交互，则必须使用这些类。在实践中，它们看起来是这样的：

<a href="/login" class="Button Button--primary js-login"></a>

再次强调，在任何情况下，都不能对特定于 JavaScript 的类进行样式设置。

组件

语法：[namespace-]<ComponentName>[-descendantName][--modifierName]

在阅读和编写 HTML 和 CSS 时，组件驱动开发提供了多种好处。

它有助于区分组件根、后代元素和修饰符的类。
它保持了选择器的特异性较低。
它有助于将表现语义与文档语义解耦。

您可以将组件视为包含特定语义、样式和行为的自定义元素。

命名空间（可选）

如果需要，组件可以加上命名空间前缀。例如，您可能希望通过为所有组件添加命名空间前缀来避免库与您的自定义组件之间发生潜在的冲突。

.godoc-Button { /* … */ }
.godoc-Tabs { /* … */ }

这使得在阅读 HTML 时可以清楚地知道哪些组件是您的库的一部分。

ComponentName

组件的名称必须使用驼峰式命名法。

.MyComponent { /* … */ }
<article class="MyComponent">
  …
</article>

ComponentName–modifierName

组件修饰符是修改基础组件某种表现形式的类。修饰符名称必须使用驼峰式命名法，并用两个连字符与组件名称分隔。该类应该额外包含在 HTML 中，而不是替换基础组件类。

/* Core button */
.Button { /* … */ }
/* Default button style */
.Button--default { /* … */ }
<button class="Button Button--primary">…</button>

ComponentName-descendantName

组件后代是指附加到组件后代节点上的类。它负责代表特定组件直接应用表现到后代上。后代名称必须使用驼峰式命名法。

<article class="Tweet">
  <header class="Tweet-header">
    <img class="Tweet-avatar" src="{$src}" alt="{$alt}">
    …
  </header>
  <div class="Tweet-body">
    …
  </div>
</article>

ComponentName[aria-]

几乎所有情况下，组件的状态都可以使用 ARIA（aria-expanded、aria-disabled 等）来表示，因此它们推荐用于基于状态的组件修改。在极少数情况下，如果存在无法使用 ARIA 表示的状态，则可以使用格式为 is-stateName 的 CSS 类。CSS 状态名称必须使用驼峰式命名法。切勿直接样式化这些属性/类；它们应始终用作相邻类或属性。

JavaScript 可以添加/删除这些属性/类。每个组件都必须定义自己的状态样式（因为它们是组件作用域的）。

.Tweet { /* … */ }
.Tweet[aria-expanded=true] { /* … */ }
.Tweet.is-blorked { /* … */ }
<article class="Tweet is-blorked" aria-expanded="true">
  …
</article>

颜色

优先使用小写十六进制值、RGB 或 RGBA，而不是命名值、HSL 或 HSLA 值。在适用时使用短格式十六进制值。

正确

#fff;
#f1f2f3;
rgb(50, 50, 50);
rgba(50, 50, 50, 0.2);

错误

#FFFFFF;
#F1F2F3;
white;
hsl(120, 100%, 50%);
hsla(120, 100%, 50%, 1);

格式化

以下是一些高级页面格式化样式规则。

间距

CSS 规则应以逗号分隔，但每条规则应另起一行。

正确

.Content,
.Content-edit {
  …
}

错误

.Content, .Content-edit {
  …
}

CSS 块之间应用单个换行符分隔。不要用两个，也不要用零个。

正确

.Content {
  …
}
.Content-edit {
  …
}

错误

.Content {
  …
}

.Content-edit {
  …
}

引号

CSS 中的引号是可选的。我们使用单引号，因为它在视觉上更清楚地表明字符串不是选择器或样式属性。

正确

background-image: url('/img/you.jpg');
font-family: 'Helvetica Neue Light', 'Helvetica Neue', Helvetica, Arial;

错误

background-image: url(/img/you.jpg);
font-family: Helvetica Neue Light, Helvetica Neue, Helvetica, Arial;

编写简单的选择器

避免使用简单的选择器序列（“复合选择器”）。

唯一的例外是基于状态的选择器，这些选择器是动态添加的，用于指示状态更改（例如，一个显示“[aria-expanded=true]”的推文）。

正确

/* State-based simple selector. */
tweet[aria-expanded=true] {
  ...
}

错误

/* Sequence of simple selectors. */
button.foo.bar {
  ...
}

图片

在 HTML 标记中为图片添加 height 和 width 属性，以帮助最小化页面加载期间的布局偏移。

<img src="url/to/image.png" height="240" width="160">

此内容是 Go Wiki 的一部分。