Skip to content

Instantly share code, notes, and snippets.

@kxxoling
Last active March 17, 2020 10:10
Show Gist options
  • Save kxxoling/ba20e1339ca66fcad445 to your computer and use it in GitHub Desktop.
Save kxxoling/ba20e1339ca66fcad445 to your computer and use it in GitHub Desktop.
Dropbox (S)CSS 样式指南中文翻译

Dropbox (S)CSS 样式指南翻译

开源许可

“Every line of code should appear to be written by a single person, no matter the number of contributors.” —@mdo

通用部分

反例

  • 避免在 CSS 使用 HTML 标签选择器
    • 例如, .o-modal {} 要优于 div.o-modal {}
    • 相对于 HTML 标签,你应该优先使用类(除非是重置 CSS 这样的特殊情况)
  • 不要使用 id 选择器
    • #header 相比 .header 太过具体,难以覆盖其样式。
    • CSS 中使用 id 选择器的更多坏处可以参见这篇文章
  • 嵌套曾测不应该超过 3 层
    • 层次嵌套过深意味着太过具体,覆盖其样式时则需要更具体的选择器,这很容易引起维护问题。
    • 除伪类选择器和状态选择器外,应尽量避免过度嵌套。
    • 嵌套 :hover, :focus, ::before 等选择器没问题,但是嵌套普通选择器应当避免。
  • 不要使用 !important
    • 永远!
    • 如果一定要使用它必须留下足够详细的注释。你应当在使用 !important 前尽可能地使用其它方法解决问题。
    • !important 会大幅提升 CSS 规则的优先级,极难覆盖,除非再使用一个 !important
  • 不要使用 margin-top
    • 垂直 margin 会折叠在一起。优先设定 padding-top 或者前面元素的 margin-bottom
  • 避免使用属性简称(除非真的有必要)
    • 在有些情况下你可以考虑这样使用,比如使用 background: #fff 而不是 background-color: #fff,但是这样做会覆盖该简写属性所包含的所有属性。(在这个例子中 background-image 会被覆盖为 none。)
    • 一个简写就能覆盖所有的属性:比如 border, margin, padding, font 等等。

空格

  • 四个缩进
  • 属性定义中 : 后应放置空格
    • 比如 color: red; 而不是 color:red;
  • 定义规则时 { 前应有空格
    • .o-modal { 而不应该 .o-modal{
  • 每条 CSS 规则单独成行
  • 规则定义结束应在 } 后换行
  • 聚合规则时,每条规则应单独成行
  • 规则定义结尾的 } 应单独成行
  • .scss 文件的结尾添加空行
  • 不要使用多余的空格

格式

  • 所有选择器都应该是小写,使用连此符连接,也就是 “spinal case” 表示法。例如:.my-class-name
  • 优先使用 Sass 双斜线 // 注释,即使块级注释也是如此。
  • 零值不需要单位,比如: margin: 0; 而不要 margin: 0px;
  • 样式规则后面应该加上分号
  • 小数前面应该保留 0 opacity: 0.4; 而不要 opacity: .4;
  • 自选择器前后加上空格, div > span 要优于 div>span

Sass 特定

.scss 文件内部顺序

  1. import 语句
  2. 变量
  3. 基础样式
  4. 试验样式

例如:

//------------------------------
// Modal
//------------------------------

@import "../constants";
@import "../helpers";

$DBmodal-namespace: "c-modal" !default;
$DBmodal-padding: 32px;

$DBmodal-background: #fff !default;
$DBmodal-background-alt: color(gray, x-light) !default;

.o-modal { ... }

// Many lines later...

// EXPERIMENT: experiment-rule-name
.o-modal--experiment { ... }
// END EXPERIMENT: experiment-rule-name

变量

  • 应该在文件的顶部紧跟在 import 后的地方定义变量
  • 本地变量前应当加上文件名(SASS 没有文档级变量)
    • 例如 business_contact.scss$business_contact_font_size: 14px;
  • 本地变量应当遵循蛇形命名 $snake_lowercase
  • 本地常量应当是大写蛇形 $SNAKE_ALL_CAPS

颜色

  • 使用颜色变量来定义颜色
  • 表示颜色的十六进制数值应当全部小写,如: #fffff
  • alpha 通道最多保持两位有效数字。不要省去前面的 0

示例:

// Bad
.c-link {
  color: #007ee5;
  border-color: #FFF;
  background-color: rgba(#FFF, .0625);
}

// Good
.c-link {
  color: color(blue);
  border-color: #ffffff;
  background-color: rgba(#ffffff, 0.1);
}

试验性规则

试验性规则应当以注释包裹:

// EXPERIMENT: experiment-rule-name
.stuff { ... }
// END EXPERIMENT: experiment-rule-name

规则顺序

属性以及嵌套的声明应当按照以下顺序排列,每种规则间以换行隔开:

  1. 所有 @ 规则
  2. 布局及盒模型规则
  • margin, padding, box-sizing, overflow, position, display, width/height 等等
  1. 排版属性
  • 例如 font-*, line-height, letter-spacing, text-* 等等
  1. 样式属性
  • color, background-*, animation, border 等等
  1. UI 属性
  • appearance, cursor, user-select, pointer-events 等等
  1. 伪元素
  • ::after, ::before, ::selection 等等
  1. 伪选择器
  • :hover, :focus, :active 等等
  1. 装饰类
  2. 嵌套元素

综合示例:

.c-btn {
    @extend %link--plain;

    display: inline-block;
    padding: 6px 12px;

    text-align: center;
    font-weight: 600;

    background-color: color(blue);
    border-radius: 3px;
    color: white;

    &::before {
        content: '';
    }

    &:focus, &:hover {
        box-shadow: 0 0 0 1px color(blue, .3);
    }

    &--big {
        padding: 12px 24px;
    }

    > .c-icon {
        margin-right: 6px;
    }
}

嵌套

  • 出于可读性的考虑,应当避免三层以上的选择器嵌套

  • 优先使用嵌套样式而不是嵌套元素。例如:

    .block {
        padding: 24px;
    
        &--mini {
            padding: 12px;
        }
    }

可以通过优秀的类命名方法(BEM)来减少嵌套。应当避免直接使用标签选择器。


BEM

Block(块):独立、有意义的名字,样式的逻辑单元。应当避免过度简化

  • Good: .alert-box or .recents-intro or .button
  • Bad: .feature or .content or .btn

Element(元素):块的子元素才拥有的样式,块本身也是元素。元素的类名应当是块名加上两个下划线加上元素名。例如:

  • .alert-box__close
  • .expanding-section__section

Modifier(修饰符):重载或者扩张块或者元素的基础样式 。其类名应当是块或者元素名加上两个下划线加上元素名。例如:

  • .alert-box--success
  • .expanding-section--expanded

BEM 最佳实践

不要基于块元素样式 @extend(扩展)修饰符。

  • Good: <div class="my-block my-block--modifier">
  • Bad: <div class="my-block--modifier">

不要在元素中创建元素。如果你真的认为有必要,先试着将元素转换为 block。

  • Bad: .alert-box__close__button

明智地选择修饰符。下面两条规则的意义完全不同:

.block--modifier .block__element { color: red; }
.block__element--modifier { color: red; }

选择器命名

  • 为类型使用基于 BEM 的中文)命名方式。
    • 使用修饰符类时,永远应当加上基类/未修改的类。
  • 像这样使用嵌套的 SASS 来管理 BEM 选择器:
    .block {
        &--modifier { //编译为 .block--modifier
            text-align: center;
        }
    
        &__element { // 编译为 .block__element
            color: red;
    
            &--modifier { // 编译为 .block__element--modifier
                color: blue;
            }
        }
    }

类的命名

类型命名空间中有一些保留名,用于全局抽象。

  • .o- 表示 CSS 对象。对象通常是基于通用设计模式(比如 Flag 对象),修改这项元素可能会引起严重问题。
  • .c- 表示 CSS 组件。组件通常是基于 UI 的设计元素,比如按钮、输入框、模态窗以及横幅。
  • .u- 表示帮助工具。工具类通常是用于单一目的,拥有高优先级。比如浮动元素、消除 margin 等等。
  • .is-, .has- 表示状态类,遵循 SMACSS 形式。这些类用于表示临时、可选或者短期存在的状态和样式。
  • ._ 一些 hack 用法。当你需要使用 !important 或者增加 specificity 时应当使用这种类名。只应当临时使用,不应该绑定使用。
  • .t- 主题类。在独立样式的页面或者需要覆盖组件/对象的样式时应当使用主题类。

分类思想(One Thing Well™)

你应该尽可能地提取出相同的 padding、字体、布局模式,并将其抽象为可重用的基于名字空间的类,可以保证绑定的元素只提供单一约束。这样做有助于防止规则的覆盖和重复,并且有助于按方面区分。

// 糟糕的例子
// HTML:
// <div class="modal compact">...</div>
.modal {
    padding: 32px;
    background-color: color(gray, x-light);

    &.compact {
        padding: 24px;
    }
}

// 优秀的例子
// HTML:
// <div class="c-modal u-l-island">...</div>
// <div class="c-modal u-l-isle">...</div>

// components/_modal.scss
.c-modal {
    background-color: color(gray, x-light);
}

// helpers/_layout.scss
.u-l-island {
    padding: 32px;
}

.u-l-isle {
    padding: 24px;
}

Media Query

Media query 应当以 SMACSS 的形式写在 CSS 选择器中。

.selector {
      float: left;

      @media only screen and (max-width: 767px) {
        float: none;
      }
}

应该为经常用到的断点(breakpoint)设置变量

$SCREEN_SM_MAX: "max-width: 767px";

.selector {
      float: left;

      @media only screen and ($SCREEN_SM_MAX) {
        float: none;
      }
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment