此手冊主要實現的目標:代碼一致性和最佳實踐。通過代碼風格的一致性,降低維護代碼的成本以及改善多人協作的效率。同時遵守最佳實踐,確保頁面性能得到最佳優化和高效的代碼。
此手冊是在開發中積累下來的經驗和參考其它規范/指南制定的,它只是起指導作用,除個別條目強制之外,大多數為非強制約束,開發者可根據自己的實際情況自行決定是否要遵守 該指南只是保證大方向一致性和最佳實踐的階段性總結,不是最后結論,它會隨著時間而變化。
基本原則
結構、樣式、行為分離
盡量確保文檔和模板只包含 HTML 結構,樣式都放到樣式表里,行為都放到腳本里。
縮進
統一4個空格縮進,不要使用 Tab 或者 Tab、空格混搭。
一律使用小寫字母
推薦寫法:

color: #e5e5e5;
以下寫法不推薦:
<A HREF="/">Home</A>
color: #E5E5E5;
統一注釋
通過配置編輯器,可以提供快捷鍵來輸出一致認可的注釋模式。
HTML 注釋
- 模塊注釋
<!-- 文章列表列表模塊 -->
<div class="article-list">
...
</div>
- 區塊注釋
<!--
@name: Drop Down Menu
@description: Style of top bar drop down menu.
@author: Ashu(Aaaaaashu@gmail.com)
-->
CSS 注釋
組件塊和子組件塊以及聲明塊之間使用一空行分隔,子組件塊之間三空行分隔;
/* ==========================================================================
組件塊
============================================================================ */
/* 子組件塊
============================================================================ */
.selector {
padding: 15px;
margin-bottom: 15px;
}
/* 子組件塊
============================================================================ */
.selector-secondary {
display: block; /* 注釋*/
}
.selector-three {
display: span;
}
JavaScript 注釋
- 單行注釋
必須獨占一行。// 后跟一個空格,縮進與下一行被注釋說明的代碼一致。 - 多行注釋
避免使用 /.../ 這樣的多行注釋。有多行注釋內容時,使用多個單行注釋。
函數/方法注釋
- 函數/方法注釋必須包含函數說明,有參數和返回值時必須使用注釋標識。;
- 參數和返回值注釋必須包含類型信息和說明;
- 當函數是內部函數,外部不可訪問時,可以使用 @inner 標識;
文件注釋
文件注釋用于告訴不熟悉這段代碼的讀者這個文件中包含哪些東西。 應該提供文件的大體內容, 它的作者, 依賴關系和兼容性信息。
代碼驗證
- 使用 W3C HTML Validator 來驗證你的HTML代碼有效性;
- 使用 W3C CSS Validator 來驗證你的CSS代碼有效性;
代碼驗證不是最終目的,真的目的在于讓開發者在經過多次的這種驗證過程后,能夠深刻理解到怎樣的語法或寫法是非標準和不推薦的,即使在某些場景下被迫要使用非標準寫法,也可以做到心中有數。
HTML
通用約定
標簽
- 自閉合(self-closing)標簽,無需閉合 ( 例如: img input br hr 等 );
- 可選的閉合標簽(closing tag),需閉合 ( 例如:</li> 或 </body> );
- 盡量減少標簽數量,不使用無意義的標簽;

<input type="text" name="title">
<ul>
<li>Style</li>
<li>Guide</li>
</ul>
<!-- Not recommended -->
<span class="avatar">

</span>
<!-- Recommended -->

Class 與 ID
- class 應以功能或內容命名,不以表現形式命名;
- class 與 id 單詞字母小寫,多個單詞組成時,采用中劃線-分隔;
- 使用唯一的 id 作為 Javascript hook, 同時避免創建無樣式信息的 class;
<!-- Not recommended -->
<div class="j-hook left contentWrapper"></div>
<!-- Recommended -->
<div id="j-hook" class="sidebar content-wrapper"></div>
嵌套
a 不允許嵌套 div 這種約束屬于語義嵌套約束,與之區別的約束還有嚴格嵌套約束,比如a 不允許嵌套 a。
嚴格嵌套約束在所有的瀏覽器下都不被允許;而語義嵌套約束,瀏覽器大多會容錯處理,生成的文檔樹可能相互不太一樣。
布爾值屬性
HTML5 規范中 disabled、checked、selected 等屬性不用設置值。
語義化
參考 sofish 寫的文章 這樣去寫你的 HTML
HEAD
文檔類型
為每個 HTML 頁面的第一行添加標準模式(standard mode)的聲明, 這樣能夠確保在每個瀏覽器中擁有一致的表現。
<!DOCTYPE html>
語言屬性
<!-- 中文 -->
<html lang="zh-Hans">
<!-- 簡體中文 -->
<html lang="zh-cmn-Hans">
<!-- 繁體中文 -->
<html lang="zh-cmn-Hant">
<!-- English -->
<html lang="en">
字符編碼
- 以無 BOM 的 utf-8 編碼作為文件格式;
- 指定字符編碼的 meta 必須是 head 的第一個直接子元素
<html>
<head>
<meta charset="utf-8">
......
</head>
<body>
......
</body>
</html>
IE 兼容模式
優先使用最新版本的IE 和 Chrome 內核
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
SEO 優化
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<!-- SEO -->
<title>Style Guide</title>
<meta name="keywords" content="your keywords">
<meta name="description" content="your description">
<meta name="author" content="author,email address">
</head>
viewport
- viewport: 一般指的是瀏覽器窗口內容區的大小,不包含工具條、選項卡等內容;
- width: 瀏覽器寬度,輸出設備中的頁面可見區域寬度;
- device-width: 設備分辨率寬度,輸出設備的屏幕可見寬度;
- initial-scale: 初始縮放比例;
- maximum-scale: 最大縮放比例;
為移動端設備優化,設置可見區域的寬度和初始縮放比例。
<meta name="viewport" content="width=device-width, initial-scale=1.0">
iOS 圖標
- apple-touch-icon 圖片自動處理成圓角和高光等效果;
- apple-touch-icon-precomposed 禁止系統自動添加效果,直接顯示設計原圖;
<!-- iPhone 和 iTouch,默認 57x57 像素,必須有 -->
<link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-57x57-precomposed.png">
<!-- iPad,72x72 像素,可以沒有,但推薦有 -->
<link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-72x72-precomposed.png" sizes="72x72">
<!-- Retina iPhone 和 Retina iTouch,114x114 像素,可以沒有,但推薦有 -->
<link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-114x114-precomposed.png" sizes="114x114">
<!-- Retina iPad,144x144 像素,可以沒有,但推薦有 -->
<link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-144x144-precomposed.png" sizes="144x144">
favicon
在未指定 favicon 時,大多數瀏覽器會請求 Web Server 根目錄下的 favicon.ico 。為了保證 favicon 可訪問,避免404,必須遵循以下兩種方法之一:
- 在 Web Server 根目錄放置 favicon.ico 文件;
- 使用 link 指定 favicon;
<link rel="shortcut icon" href="path/to/favicon.ico">
HEAD 模板
<!DOCTYPE html>
<html lang="zh-cmn-Hans">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Style Guide</title>
<meta name="description" content="不超過150個字符">
<meta name="keywords" content="">
<meta name="author" content="name, email@gmail.com">
<!-- 為移動設備添加 viewport -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- iOS 圖標 -->
<link rel="apple-touch-icon-precomposed" href="/apple-touch-icon-57x57-precomposed.png">
<link rel="alternate" type="application/rss+xml" title="RSS" href="/rss.xml" />
<link rel="shortcut icon" href="path/to/favicon.ico">
</head>
CSS
通用約定
代碼組織
- 以組件為單位組織代碼段;
- 制定一致的注釋規范;
- 組件塊和子組件塊以及聲明塊之間使用一空行分隔,子組件塊之間三空行分隔;
- 如果使用了多個 CSS 文件,將其按照組件而非頁面的形式分拆,因為頁面會被重組,而組件只會被移動;
良好的注釋是非常重要的。請留出時間來描述組件(component)的工作方式、局限性和構建它們的方法。不要讓你的團隊其它成員 來猜測一段不通用或不明顯的代碼的目的。
提示:通過配置編輯器,可以提供快捷鍵來輸出一致認可的注釋模式。
/* ==========================================================================
組件塊
============================================================================ */
/* 子組件塊
============================================================================ */
.selector {
padding: 15px;
margin-bottom: 15px;
}
/* 子組件塊
============================================================================ */
.selector-secondary {
display: block; /* 注釋*/
}
.selector-three {
display: span;
}
Class 和 ID
- 使用語義化、通用的命名方式;
- 使用連字符 - 作為 ID、Class 名稱界定符,不要駝峰命名法和下劃線;
- 避免選擇器嵌套層級過多,盡量少于 3 級;
- 避免選擇器和 Class、ID 疊加使用;
出于性能考量,在沒有必要的情況下避免元素選擇器疊加 Class、ID 使用。
元素選擇器和 ID、Class 混合使用也違反關注分離原則。如果HTML標簽修改了,就要再去修改 CSS 代碼,不利于后期維護。
/* Not recommended */
.red {}
.box_green {}
.page .header .login #username input {}
ul#example {}
/* Recommended */
#nav {}
.box-video {}
#username input {}
#example {}
聲明塊格式
- 選擇器分組時,保持獨立的選擇器占用一行;
- 聲明塊的左括號 { 前添加一個空格;
- 聲明塊的右括號 } 應單獨成行;
- 聲明語句中的 : 后應添加一個空格;
- 聲明語句應以分號 ; 結尾;
- 一般以逗號分隔的屬性值,每個逗號后應添加一個空格;
- rgb()、rgba()、hsl()、hsla() 或 rect() 括號內的值,逗號分隔,但逗號后不添加一個空格;
- 對于屬性值或顏色參數,省略小于 1 的小數前面的 0 (例如,.5 代替 0.5;-.5px 代替 -0.5px);
- 十六進制值應該全部小寫和盡量簡寫,例如,#fff 代替 #ffffff;
- 避免為 0 值指定單位,例如,用 margin: 0; 代替 margin: 0px;
/* Not recommended */
.selector, .selector-secondary, .selector[type=text] {
padding:15px;
margin:0px 0px 15px;
background-color:rgba(0, 0, 0, 0.5);
box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}
/* Recommended */
.selector,
.selector-secondary,
.selector[type="text"] {
padding: 15px;
margin-bottom: 15px;
background-color: rgba(0,0,0,.5);
box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}
引號使用
url() 、屬性選擇符、屬性值使用雙引號。 參考 Is quoting the value of url() really necessary?
/* Not recommended */
@import url(//www.google.com/css/maia.css);
html {
font-family: 'open sans', arial, sans-serif;
}
/* Recommended */
@import url("http://www.google.com/css/maia.css");
html {
font-family: "open sans", arial, sans-serif;
}
.selector[type="text"] {
}
媒體查詢(Media query)的位置
將媒體查詢放在盡可能相關規則的附近。不要將他們打包放在一個單一樣式文件中或者放在文檔底部。如果你把他們分開了,將來只會被大家遺忘。
.element { ... }
.element-avatar { ... }
.element-selected { ... }
@media (max-width: 768px) {
.element { ...}
.element-avatar { ... }
.element-selected { ... }
}
不要使用 @import
與 <link> 相比,@import 要慢很多,不光增加額外的請求數,還會導致不可預料的問題。
替代辦法:
- 使用多個 元素;
- 通過 Sass 或 Less 類似的 CSS 預處理器將多個 CSS 文件編譯為一個文件;
- 其他 CSS 文件合并工具;
字體排印
暫時參考網頁字體排印指南
模塊組織
任何超過 1000 行的 CSS 代碼,你都曾經歷過這樣的體驗:
這個 class 到底是什么意思呢?
這個 class 在哪里被使用呢?
如果我創建一個 xxoo class,會造成沖突嗎?
Reasonable System for CSS Stylesheet Structure 的目標就是解決以上問題,它不是一個框架,而是通過規范,讓你構建更健壯和可維護的 CSS 代碼。
Components(組件)

從 Components 的角度思考,將網站的模塊都作為一個獨立的 Components。
Naming components (組件命名)
Components 最少以兩個單詞命名,通過 - 分離,例如:
- 點贊按鈕 (.like-button)
- 搜索框 (.search-form)
- 文章卡片 (.article-card)
Elements (元素)

Elements是 Components中的元素
Naming elements (元素命名)
Elements 的類名應盡可能僅有一個單詞。
.search-form {
> .field { /* ... */ }
> .action { /* ... */ }
}
On multiple words (多個單詞)
對于倘若需要兩個或以上單詞表達的 Elements 類名,不應使用中劃線和下劃線連接,應直接連接。
.profile-box {
> .firstname { /* ... */ }
> .lastname { /* ... */ }
> .avatar { /* ... */ }
}
Avoid tag selectors (避免標簽選擇器)
任何時候盡可能使用 classnames。標簽選擇器在使用上沒有問題,但是其性能上稍弱,并且表意不明確。
.article-card {
> h3 { /* ? avoid */ }
> .name { /* ? better */ }
}
Variants (變體)

Components 和 Elements 可能都會擁有 Variants。
Naming variants (變體命名)
Variants 的 classname 應帶有前綴中劃線 -
.like-button {
&.-wide { /* ... */ }
&.-short { /* ... */ }
&.-disabled { /* ... */ }
}
Element variants (元素變體)
.shopping-card {
> .title { /* ... */ }
> .title.-small { /* ... */ }
}
Dash prefixes (中劃線前綴)
為什么使用中劃線作為變體的前綴?
- 它可以避免歧義與 Elements
- CSS class 僅能以單詞和 _ 或 - 開頭
- 中劃線比下劃線更容易輸出
Layout (布局)

Avoid positioning properties (避免定位屬性)
Components 應該在不同的上下文中都可以復用,所以應避免設置以下屬性:
- Positioning (position, top, left, right, bottom)
- Floats (float, clear)
- Margins (margin)
- Dimensions (width, height) *
Fixed dimensions (固定尺寸)
頭像和 logos 這些元素應該設置固定尺寸(寬度,高度...)。
Define positioning in parents (在父元素中設置定位)
倘若你需要為組件設置定位,應將在組件的上下文(父元素)中進行處理,比如以下例子中,將 widths 和 floats 應用在 list component(.article-list) 當中,而不是 component(.article-card) 自身。
.article-list {
& {
@include clearfix;
}
> .article-card {
width: 33.3%;
float: left;
}
}
.article-card {
& { /* ... */ }
> .image { /* ... */ }
> .title { /* ... */ }
> .category { /* ... */ }
}
Avoid over-nesting (避免過分嵌套)
當出現多個嵌套的時候容易失去控制,應保持不超過一個嵌套。
/* ? Avoid: 3 levels of nesting */
.image-frame {
> .description {
/* ... */
> .icon {
/* ... */
}
}
}
/* ? Better: 2 levels */
.image-frame {
> .description { /* ... */ }
> .description > .icon { /* ... */ }
}
Summary (總結)
- 以 Components 的角度思考,以兩個單詞命名(.screenshot-image)
- Components 中的 Elements,以一個單詞命名(.blog-post .title)
- Variants,以中劃線-作為前綴(.shop-banner.-with-icon)
- Components 可以互相嵌套
- 記住,你可以通過繼承讓事情變得更簡單
性能優化
慎重選擇高消耗的樣式
高消耗屬性在繪制前需要瀏覽器進行大量計算:
- box-shadows
- border-radius
- transparency
- transforms
- CSS filters(性能殺手)
避免過分重排
當發生重排的時候,瀏覽器需要重新計算布局位置與大小,更多詳情。
常見的重排元素:
width
height
padding
margin
display
border-width
position
top
left
right
bottom
font-size
float
text-align
overflow-y
font-weight
overflow
font-family
line-height
vertical-align
clear
white-space
min-height
正確使用 Display 的屬性
Display 屬性會影響頁面的渲染,請合理使用。
display: inline后不應該再使用 width、height、margin、padding 以及 float;
display: inline-block 后不應該再使用 float;
display: block 后不應該再使用 vertical-align;
display: table-* 后不應該再使用 margin 或者 float;
不濫用 Float
Float在渲染時計算量比較大,盡量減少使用。
動畫性能優化
動畫的實現原理,是利用了人眼的“視覺暫留”現象,在短時間內連續播放數幅靜止的畫面,使肉眼因視覺殘象產生錯覺,而誤以為畫面在“動”。
動畫的基本概念:
幀:在動畫過程中,每一幅靜止畫面即為一“幀”;
幀率:即每秒鐘播放的靜止畫面的數量,單位是fps(Frame per second);
幀時長:即每一幅靜止畫面的停留時間,單位一般是ms(毫秒);
跳幀(掉幀/丟幀):在幀率固定的動畫中,某一幀的時長遠高于平均幀時長,導致其后續數幀被擠壓而丟失的現象。
一般瀏覽器的渲染刷新頻率是 60 fps,所以在網頁當中,幀率如果達到 50-60 fps 的動畫將會相當流暢,讓人感到舒適。如果使用基于 javaScript 的動畫,盡量使用 requestAnimationFrame. 避免使用 setTimeout, setInterval.
避免通過類似 jQuery animate()-style 改變每幀的樣式,使用 CSS 聲明動畫會得到更好的瀏覽器優化。
使用 translate 取代 absolute 定位就會得到更好的 fps,動畫會更順滑。
多利用硬件能力,如通過 3D 變形開啟 GPU 加速
一般在 Chrome 中,3D或透視變換(perspective transform)CSS屬性和對 opacity 進行 CSS 動畫會創建新的圖層,在硬件加速渲染通道的優化下,GPU 完成 3D 變形等操作后,將圖層進行復合操作(Compesite Layers),從而避免觸發瀏覽器大面積重繪和重排。
注:3D 變形會消耗更多的內存和功耗。
使用 translate3d 右移 500px 的動畫流暢度要明顯優于直接使用 left:
.ball-1 {
transition: -webkit-transform .5s ease;
-webkit-transform: translate3d(0, 0, 0);
}
.ball-1.slidein{
-webkit-transform: translate3d(500px, 0, 0);
}
.ball-2 {
transition: left .5s ease; left:0;
}
.ball-2.slidein {
left:500px;
}
提升 CSS 選擇器性能
CSS 選擇器對性能的影響源于瀏覽器匹配選擇器和文檔元素時所消耗的時間,所以優化選擇器的原則是應盡量避免使用消耗更多匹配時間的選擇器。而在這之前我們需要了解 CSS 選擇器匹配的機制, 如子選擇器規則:
#header > a {font-weight:blod;}
我們中的大多數人都是從左到右的閱讀習慣,會習慣性的設定瀏覽器也是從左到右的方式進行匹配規則,推測這條規則的開銷并不高。
我們會假設瀏覽器以這樣的方式工作:尋找 id 為 header 的元素,然后將樣式規則應用到直系子元素中的 a 元素上。我們知道文檔中只有一個 id 為 header 的元素,并且它只有幾個 a 元素的子節點,所以這個 CSS 選擇器應該相當高效。
事實上,卻恰恰相反,CSS 選擇器是從右到左進行規則匹配。了解這個機制后,例子中看似高效的選擇器在實際中的匹配開銷是很高的,瀏覽器必須遍歷頁面中所有的 a 元素并且確定其父元素的 id 是否為 header 。
如果把例子的子選擇器改為后代選擇器則會開銷更多,在遍歷頁面中所有 a 元素后還需向其上級遍歷直到根節點。
#header a {font-weight:blod;}
理解了CSS選擇器從右到左匹配的機制后,明白只要當前選擇符的左邊還有其他選擇符,樣式系統就會繼續向左移動,直到找到和規則匹配的選擇符,或者因為不匹配而退出。我們把最右邊選擇符稱之為關鍵選擇器?!?a href="http://www.lxweimin.com/p/268c7f3dd7a6" target="_blank">更多詳情
1、避免使用通用選擇器
/* Not recommended */
.content * {color: red;}
瀏覽器匹配文檔中所有的元素后分別向上逐級匹配 class 為 content 的元素,直到文檔的根節點。因此其匹配開銷是非常大的,所以應避免使用關鍵選擇器是通配選擇器的情況。
2、避免使用標簽或 class 選擇器限制 id 選擇器
/* Not recommended */
button#backButton {…}
/* Recommended */
#newMenuIcon {…}
3、避免使用標簽限制 class 選擇器
/* Not recommended */
treecell.indented {…}
/* Recommended */
.treecell-indented {…}
/* Much to recommended */
.hierarchy-deep {…}
4、避免使用多層標簽選擇器。使用 class 選擇器替換,減少css查找
/* Not recommended */
treeitem[mailfolder="true"] > treerow > treecell {…}
/* Recommended */
.treecell-mailfolder {…}
5、避免使用子選擇器
/* Not recommended */
treehead treerow treecell {…}
/* Recommended */
treehead > treerow > treecell {…}
/* Much to recommended */
.treecell-header {…}
6、使用繼承
/* Not recommended */
#bookmarkMenuItem > .menu-left { list-style-image: url(blah) }
/* Recommended */
#bookmarkMenuItem { list-style-image: url(blah) }