开源软件名称：doyoe/html-css-guide
开源软件地址：https://github.com/doyoe/html-css-guide
开源编程语言：
开源软件介绍：HTML/CSS开发规范指南
目录
- 规范概述
- 基本信息
- 通用约定
- HTML约定
- CSS约定
- 图像约定
- 结语
规范概述
规范的制定是我们长期以来对工作的积累与沉淀的产物，帮助我们更快、更好、更高效的完成繁重、复杂、多样化的任务，我们制作规范的主要目的在于：
- 降低每个组员介入项目的门槛成本；
- 提高工作效率及协同开发的便捷性；
- 高度统一的代码风格；
- 提供一整套HTML、CSS解决方案，来帮助开发人员快速做出高质量的符合要求的页面。
基本信息
| 规范名称 |
Cook |
| 当前版本 |
v1.0 beta |
| 规范发起 |
杜瑶(@doyoe) |
| 参与人群 |
Qunar FED |
| 最后更新 |
2015.03.20 |
通用约定
1.文档目录结构
|-- 项目名
|-- src 开发环境
|-- html 静态页面模板目录
|-- bgimg 背景图目录（假设有的话）
|-- image 前景图目录（假设有的话）
|-- font 字体目录（假设有的话）
|-- scripts 脚本目录
|-- styles（Yo） 样式目录
|-- lib 基础库
|-- core 核心代码：reset
|-- element 元素
|-- fragment 公用碎片
|-- layout 布局
|-- widget 组件
|-- usage 项目具体实现
|-- project 某个子项目
|-- core 核心代码：桥接lib中的core，可以进行项目级扩展
|-- fragment 项目公用碎片
|-- module 模块
|-- page page桥接文件目录：src-list
|-- export page pack之后的文件目录
|-- prd 生产环境
|-- bgimg 背景图目录（假设有的话）
|-- image 前景图目录（假设有的话）
|-- font 字体目录（假设有的话）
|-- scripts 脚本目录
|-- styles（Yo） 样式目录
|-- project1 子项目
|-- index.css
|-- login.css
|-- and etc...
|-- project2 子项目
|-- index.css
|-- login.css
|-- and etc...
|-- and etc...
src, scripts, styles 三个目录是为了和现有项目保持一致，避免修改过大，所以保持不变。
html 目录，用于存放前端开发做的静态页面，以备查阅、备份、review或给后端套页面。
bgimg, image, font 三个目录在Qunar一般不会直接存在，因为我们有source服务器，这些资源都会在那上面管理；不过特殊情况也会有，比如一些独立的项目，没有使用source的，那么就需要遵循这样的目录划分。
至于 html, bgimg, image, font 这几个目录为什么没有加 s，主要是因为不希望大家去想某个目录是否为复数，简单点就好。
prd 为生产环境目录，以 xxx 项目中的一个子项目 mobile 为例，其生产环境中的某个CSS外链大致如下：//sitename.com/prd/styles/mobile/index.css
2.分离
结构（HTML）、表现（CSS）、行为分离（JavaScript）
将结构与表现、行为分离，保证它们之间的最小耦合，这对前期开发和后期维护都至关重要。
3.文件命名
假定有这样一个模块：
.m-detail { sRules; }
.m-detail-hd { sRules; }
.m-detail-bd { sRules; }
.m-detail-ft { sRules; }
那么该模块的文件名应该为：m-detail.css
- CSS页面文件，其文件名必须与HTML文件名一致；
假定有一个HTML页面叫 product.html，那么其相对应的CSS页面文件名应该为：product.css
假定现在有一个 product.html，里面有2个模块：
+<section class="m-list">
+<section class="m-info">
那么开发人员能快速找到与该页面相关的3个直接CSS文件，包括：product.css, m-list.css, m-info.css
4.缩进
使用tab（4个空格宽度）来进行缩进，可以在IDE里进行设置
5.编码
- 以 UTF-8 无 BOM 编码作为文件格式；
- 在HTML中文档中用
<meta charset="utf-8" /> 来指定编码；
- 为每个CSS文档显示的定义编码，在文档首行定义
@charset "utf-8";
在 Sass 中，如果文档中出现中文，却未显示定义编码，将会编译出错，为了统一各种写法，且提前规避错误几率，统一要求每个CSS文档都需要定义编码
6.小写
- 所有的HTML标签必须小写；
- 所有的HTML属性必须小写；
- 所有的样式名及规则必须小写。
7.注释
尽可能的为你的代码写上注释。解释为什么要这样写，它是新鲜的方案还是解决了什么问题。
8.待办事项
用 TODO 标示待办事项和正在开发的条目
<!-- TODO: 图文混排 -->
<div class="g-imgtext">
<img src="1.png" alt="" />
...
/* TODO: 图文混排 comm: g-imgtext */
.g-imgtext { sRules; }
9.行尾空格
删除行尾空格，这些空格没有必要存在
10.省略嵌入式资源协议头
省略图像、媒体文件、样式表和脚本等URL协议头部声明 ( http: , https: )。如果不是这两个声明的URL则不省略。
省略协议声明，使URL成相对地址，防止内容混淆问题和导致小文件重复下载（这个主要是指http和https交杂的场景中）。
不推荐：
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
推荐：
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
不推荐：
.example {
background: url(http://www.google.com/images/example);
}
推荐：
.example {
background: url(//www.google.com/images/example);
}
注：省略协议头在IE7-8下会有一点小问题，外部CSS文件（link和@import）会被下载两遍，所以该条目的约定看具体项目。
11.代码有效性
代码验证不是最终目的，真的目的在于让开发者在经过多次的这种验证过程后，能够深刻理解到怎样的语法或写法是非标准和不推荐的，即使在某些场景下被迫要使用非标准写法，也可以做到心中有数。
HTML约定
1.文档类型
- 统一使用HTML5的标准文档类型：
<!DOCTYPE html>；
HTML5文档类型具备前后兼容的特质，并且易记易书写
- 在文档doctype申明之前，不允许加上任何非空字符；
任何出现在doctype申明之前的字符都将使得你的HTML文档进入非标准模式
避免出现不可控的问题
2.省略type属性
在调用CSS和JavaScript时，可以将type属性省略不写
不允许：
<link type="text/css" rel="stylesheet" href="base.css" />
<script type="text/javascript" src="base.js"></script>
应该：
<link rel="stylesheet" href="base.css" />
<script src="base.js"></script>
因为HTML5在引入CSS时，默认type值为text/css；在引入JavaScript时，默认type值为text/javascript
3.省略属性值
非必须属性值可以省略
不允许：
<input type="text" readonly="readonly" />
<input type="text" disabled="disabled" />
应该：
<input type="text" readonly />
<input type="text" disabled />
这里的 readonly 和 disabled 属性的值是非必须的，可以省略不写，我们知道HTML5表单元素新增了很多类似的属性，如: required
4.用双引号包裹属性值
所有的标签属性值必须要用双引号包裹，同时也不允许有的用双引号，有的用单引号的情况
不允许：
<a href=http://www.qunar.com class=home>去哪儿网</a>
应该：
<a href="http://www.qunar.com" class="home">去哪儿网</a>
5.嵌套
所有元素必须正确嵌套
不允许：
<span><dfn>交叉嵌套</span></dfn>
应该：
<span><dfn>交叉嵌套</dfn></span>
不允许：
<ul>
<h3>xx列表</h3>
<li>asdasdsdasd</li>
<li>asdasdsdasd</li>
</ul>
应该：
<div>
<h3>xx列表</h3>
<ul>
<li>asdasdsdasd</li>
<li>asdasdsdasd</li>
</ul>
</div>
不推荐：
<span>
<h1>这是一个块级h1元素</h1>
<p>这是一个块级p元素</p>
</span>
推荐：
<div>
<h1>这是一个块级h1元素</h1>
<p>这是一个块级p元素</p>
</div>
规则可参考：
HTML4/XHTML1.0 Strict: 嵌套规则。
HTML5: 嵌套规则
举个例子，在HTML5中，a元素同时属于 Flow content, Phrasing content, Interactive content, Palpable content 4个分类，那些子元素是 phrasing 元素的元素可以是 a 的父元素，a 允许的子元素是以它的父元素允许的子元素为准，但不能包含 interactive 元素。
6.标签闭合
所有标签必须闭合
不允许：
<div>balabala...
<link rel="stylesheet" href="*.css">
应该：
<div>balabala...</div>
<link rel="stylesheet" href="*.css" />
虽然有些标记没有要求必须关闭，但是为了避免出错的几率，要求必须全部关闭，省去判断某标记是否需要关闭的时间
7.多媒体替代方案
- 为img元素加上alt属性；
- 为视频内容提供音轨替代；
- 为音频内容提供字母替代等等。
不推荐：
推荐：
<img src="banner.jpg" alt="520即将到来，爱就大声说出来" />
alt属性的内容为对该图片的简要描述，这对于盲人用户和图像损毁都非常有意义，即无障碍。对于纯粹的装饰性图片，alt属性值可以留空，如 alt=""
8.有效操作
为表单元素label加上for属性
不允许：
<input type="radio" name="color" value="0" /><label>蓝色</label>
<input type="radio" name="color" value="1" /><label>粉色</label>
应该：
<input type="radio" id="blue" name="color" value="0" /><label for="blue">蓝色</label>
<input type="radio" id="pink" name="color" value="1" /><label for="pink">粉色</label>
for属性能让点击label标签的时候，同时focus到对应的 input 和 textarea上，增加响应区域
9.按模块添加注释
在每个模块开始和结束的地方添加注释
<!-- 新闻列表模块 -->
<div class="m-news g-mod"
...
<!-- /新闻列表模块 -->
<!-- 排行榜模块 -->
<div class="m-topic g-mod"
...
<!-- /排行榜模块 -->
注释内容左右两边保留和注释符号有1个空格位，在注释内容内不允许再出现中划线“-”，某些浏览器会报错。
注释风格保持与原生HTML的语法相似：成对出现 <!-- comment --><!-- /comment -->
10.格式
- 将每个块元素、列表元素或表格元素都放在新行；
- inline元素视情况换行，以长度不超过编辑器一屏为宜；
- 每个子元素都需要相对其父级缩进（参见缩进约定）。
不推荐：
<div><h1>asdas</h1><p>dff<em>asd</em>asda<span>sds</span>dasdasd</p></div>
推荐：
<div>
<h1>asdas</h1>
<p>dff<em>asd</em>asda<span>sds</span>dasdasd</p>
</div>
11.语义化标签
- 根据HTML元素的本身用途去使用它们；
- 禁止使用被废弃的用于表现的标签，如 center, font 等；
- 部分在XHTML1中被废弃的标签，在HTML5中被重新赋予了新的语义，在选用时请先弄清其语义，如:b, i, u等。
不允许：
应该：
虽然使用p标签，也可以通过CSS去定义它的外观和标题相同，但p标签本身的并不是表示标题，而是表示文本段落
参阅：HTML5 Elements
12.模块化
- 每个模块必须有一个模块名；
- 每个模块的基本组成部分应该一致；
- 模块的子节点类名需带上模块名（防止模块间嵌套时产生不必要的覆盖）；
- 孙辈节点无需再带模块名。
代码如：
<section class="m-detail">
<header class="m-detail-hd">
<h1 class="title">模块标题</h1>
</header>
<div class="m-detail-bd">
<p class="info">一些实际内容</p>
</div>
<footer class="m-detail-ft">
<a href="#" class="more">更多</a>
</footer>
</section>
其中 .m-detail-hd, .m-detail-bd, .m-detail-ft 为可选，视具体模块情况决定是否需要抽象为这种 头，中，尾 的结构
CSS约定
1.文件引用
- 一律使用link的方式调用外部样式
- 不允许在页面中使用
<style> 块；
- 不允许在
<style> 块中使用 @import；
- 不允许使用
style 属性写行内样式。
一般情况下，在页面中只允许使用 <link /> 标签来引用CSS文件，
2.命名-组成元素
- 命名必须由单词、中划线①或数字组成；
- 不允许使用拼音（约定俗成的除外，如：youku, baidu），尤其是缩写的拼音、拼音与英文的混合。
不推荐：
.xiangqing { sRules; }
.news_list { sRules; }
.zhuti { sRules; }
推荐：
.detail { sRules; }
.news-list { sRules; }
.topic { sRules; }
①我们使用中划线 “-” 作为连接字符，而不是下划线 "_"。
我们知道2种方式都有不少支持者，但 "-" 能让你少按一次shift键，并且更符合CSS原生语法，所以我们只选一种目前业内普遍使用的方式
3.命名-词汇规范
- 不依据表现形式来命名；
- 可根据内容来命名；
- 可根据功能来命名。
不推荐：
left, right, center, red, black
推荐：
nav, aside, news, type, search
4.命名-缩写规范
- 保证缩写后还能较为清晰保持原单词所能表述的意思；
- 使用业界熟知的或者约定俗成的。
不推荐：
navigation => navi
header => head
description => des
推荐：
navigation => nav
header => hd
description => desc
5.命名-前缀规范
| 前缀 |
说明 |
示例 |
| g- |
全局通用样式命名，前缀g全称为global，一旦修改将影响全站样式 |
g-mod |
| m- |
模块命名方式 |
m-detail |
| ui- |
组件命名方式 |
ui-selector |
| js- |
所有用于纯交互的命名，不涉及任何样式规则。JSer拥有全部定义权限 |
js-switch |
不推荐：
.info { sRules; }
.current { sRules; }
.news { sRules; }
因为这样将给我们带来不可预知的管理麻烦以及沉重的历史包袱。你永远也不会知道哪些样式名已经被用掉了，如果你是一个新人，你可能会遭遇，你每定义个样式名，都有同名的样式已存在，然后你只能是换样式名或者覆盖规则。
推荐：
.m-detail .info { sRules; }
.m-detail .current { sRules; }
.m-detail .news { sRules; }
所有的选择器必须是以 g-, m-, ui- 等有前缀的选择符开头的，意思就是说所有的规则都必须在某个相对的作用域下才生效，尽可能减少全局污染。
js- 这种级别的className完全交由JSer自定义，但是命名的规则也可以保持跟重构一致，比如说不能使用拼音之类的
6.id与class
重构工程师只允许使用class（因历史原因及大家的习惯做出妥协）。
7.书写格式
- 选择器与大括号之间保留一个空格；
- 分号之后保留一个空格；
- 逗号之后保留一个空格；
- 所有规则需换行；
- 多组选择器之间需换行。
不推荐：
main{
display:inline-block;
}
h1,h2,h3{
margin:0;
background-color:rgba(0,0,0,.5);
}
推荐：
main {
display: inline-block;
}
h1,
h2,
h3 {
margin: 0;
background-color: rgba(0, 0, 0, .5);
}
8.规则与分号
每条规则结束后都必须加上分号
不推荐：
body {
margin: 0;
padding: 0;
font-size: 14px
}
推荐：
body {
margin: 0;
padding: 0;
font-size: 14px;
}
9.0与单位
如果属性值为0，则不需要为0加单位
不推荐：
body {
margin: 0px;
padding: 0px;
}
推荐：
body {
margin: 0;
padding: 0;
}
10.0与小数
如果是0开始的小数，前面的0可以省略不写
不推荐：
body {
opacity: 0.6;
text-shadow: 1px 1px 5px rgba(0, 0, 0, 0.5);
}
推荐：
body {
opacity: .6;
text-shadow: 1px 1px 5px rgba(0, 0, 0, .5);
}
| 
客服电话
APP下载
官方微信
