diff --git a/README.md b/README.md index d6275e8..70c3de8 100644 --- a/README.md +++ b/README.md @@ -335,3 +335,9 @@ $SCREEN_SM_MAX: "max-width: 767px"; } } ``` + +## Translation + + This style guide is also available in other languages: + + -  **Chinese (Simplified)**: [Gabriel/css-style-guide](./Translation/README-zh.md) diff --git a/Translation/README-zh.md b/Translation/README-zh.md new file mode 100644 index 0000000..05a5065 --- /dev/null +++ b/Translation/README-zh.md @@ -0,0 +1,339 @@ +# Dropbox (S)CSS 样式风格指南 + +> “每一行代码都应该由一个人来写,不管贡献者的数量是多少。”-@mdo + +## 一般原则 +### 不要做! + +- 避免在CSS选择器中使用HTML标记 + - 例如 `.o-modal {}` 优于 `div.o-modal {}` + - 总是推荐使用类而不是HTML标签(除了一些例外,如CSS重置) +- 不要在选择器中使用id + - `#header`与`.header`相比过于具体。并且样式更难以重写 + - 请阅读更多关于CSS中与IDs相关的重要问题的[文章](http://csswizardry.com/2011/09/when-using-ids-can-be-a-pain-in-the-class/)。 +- 嵌套层级不要超过3层 + - 嵌套选择器增加了特异性,这意味着需要使用更具体的选择器来覆盖其中的任何CSS设置。这很快就成为一个重要的维护问题。 +- 除了伪选择器和状态选择器外,避免对其他任何东西使用嵌套 + - 例如,嵌套`:hover`, `:focus`, `::before`, 等是可以的,但是应该避免在选择器中嵌套选择器。 +- 不要用`!important` + - 永远别 + - 如果你一定要这么做,那就留下你的注释,在使用 `!important`这个词之前,优先解决具体的问题。 + - `!important`极大地增强了CSS声明的能力,使得将来很难重写它。这是唯一可能的重写是在后面的级联中的另一个`!important`的声明。 +- 不要使用`margin-top`。 + - Vertical margins [collapse](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Mastering_margin_collapsing). Always prefer `padding-top` or`margin-bottom` on preceding elements +- 避免简化属性(除非确实需要) + - 使用' background: #fff '而不是' background-color: #fff '可能很诱人,但是这样做会覆盖由简化属性封装的其他值。(在本例中,' background-image '及其关联属性被设置为" none "。 + - 这适用于所有具有简写的属性: border, margin, padding, font等。 + +### 空格缩进 + +- 缩进代码用四个空格 +- 在属性声明的':'后面加上空格 + - E.g. `color: red;` instead of `color:red;` +- 在规则声明中'{'前面加上空格 + - E.g. `.o-modal {` instead of `.o-modal{` +- 每个属性的CSS代码写在一行 +- 在`}`结束规则声明之后添加一个换行符 +- 当对选择器进行分组时,请将各个选择器保持在一行上 +- 将大括号`}`放在新行上 +- 在.scss文件的末尾添加新行 +- 移除多余的空格 + +### 格式化 + +- 所有的选择器都是小写的,用连字符隔开又称“spinal case” 例如 `.my-class-name` +- 总是推荐Sass的双斜杠' // '注释,即使是块注释 +- 避免为零值指定单位。使用`margin: 0;` 而不是`margin: 0px;` +- 总是在属性/值声明的末尾添加分号 +- 将`opacity: .4;`替换为`opacity: 0.4;` +- 将空格放在子选择器`div > span`之前和之后而不是 `div>span` + +---------- + +## Sass Specifics Sass的细节 +### 一个.scss文件的内部顺序 + +1. Imports +2. Variables +3. Base Styles +4. Experiment Styles + +例如: + +```scss +//------------------------------ +// 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 +``` + +### Variables - 变量 + +- 在import之后的文件顶部定义所有变量 +- 具有文件名的命名空间局部变量(SASS没有文档级范围) + - eg `business_contact.scss` →`$business_contact_font_size: 14px;` +- 本地变量应该是,小写(snake_case) ' $snake_lowercase ' +- 全局变量应该是,大写(SCREAMING_SNAKE_CASE)' $SNAKE_ALL_CAPS ' + +### Color - 颜色值 + +- 通过color函数使用定义的颜色常量 +- 小写所有十六进制值' #fffff ' +- 将alpha值限制为最多两位小数。总是使用前导零。 + +例如: + +```scss +// 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); +} +``` + +### Experiments - 实验 + +用注释包裹实验的样式: + +```scss +// EXPERIMENT: experiment-rule-name +.stuff { ... } +// END EXPERIMENT: experiment-rule-name +``` + +---------- + +## 规则排序 + +属性和嵌套声明应按以下顺序显示,组之间应有换行符: + +1. 任何“@”规则 +2. 布局和盒模型属性 + - margin, padding, box-sizing, overflow, position, display, width/height, etc. +3. 排版属性 + - E.g. font-*, line-height, letter-spacing, text-*, etc. +4. 风格属性 + - color, background-*, animation, border, etc. +5. UI属性 + - appearance, cursor, user-select, pointer-events, etc. +6. 伪元素 + - ::after, ::before, ::selection, etc. +7. 伪选择器 + - :hover, :focus, :active, etc. +8. Modifier classes +修饰符类,(&--big) +> 译者注: 不建议使用&--big 类似这样的命名方式, 对项目搜索不太友好 +9. 嵌套元素 + +这里有一个综合的例子: + +```scss +.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; + } +} +``` + +---------- + +## Nesting - 嵌套 + +- 一般来说,避免将选择器嵌套在超过3层的深度 +- 推荐使用嵌套作为一个方便的扩展父选择器而不是目标嵌套的元素。例如: + ```scss + .block { + padding: 24px; + + &--mini { + padding: 12px; + } + } + ``` + +通过智能类命名(在BEM的帮助下)和避免裸标记选择器可以很容易地避免嵌套。 + +---------- + +## BEM + +块:一个逻辑样式单元唯一的、有意义的名称。避免过度简化。 +- Good: `.alert-box` or `.recents-intro` or `.button` +- Bad: `.feature` or `.content` or `.btn` + +元素:仅应用于块的子元素的样式。元素本身也可以是块。类名是块名、两个下划线和元素名的串联。例子: +- `.alert-box__close` +- `.expanding-section__section` + +修饰符:用修饰符样式覆盖或扩展块或元素的基本样式。类名是块(或元素)名、两个连字符和修饰符名的组合。例子: +- `.alert-box--success` +- `.expanding-section--expanded` + +### BEM Best practices - BEM 最佳实践 + +不要使用块基来`@extend`块修饰符。 +- Good: `