standards.md

# 规范 #
----------


## 1. 前端代码规范 ##


### 1.1 关键规范 ###

1. HTML文档及CSS文档中缩进使用两个空格，不使用tab，Javascript文档中缩进使用4个空格；
2. 标签属性名使用全部小写形式，id和name属性值使用驼峰命名方式，类名（class属性值）使用小写，多个单词间使用“-”分隔，其他没有规定的情况下所有代码及文件命名尽可能采用小写形式；
3. html文档类型使用HTML5，不使用XHTML，书写形式尽可能符合html5规范；
4. 在html及css中优先使用双引号，在Javascript及其他服务器语言中优先使用单引号。
4. 文档使用UTF-8 (no BOM)存储，文档中也加入 <meta charset="utf-8">；
5. 尽量忽略（Omit）协议：如 `background: url(http://www.zui.com/images/example)`; 应该写`background: url(//www.zui.com/images/example)`;以方便http与https协议切换，除非必须使用某个协议；
6. 在保证可读性及与规范不冲突的情况下，尽可能使用语法允许的缩写形式，以减少网络传输中的字节数。


### 1.2 HTML规范 ###

1. 使用HTML5规范，使用`<!DOCTYPE html>`，而不是XHTML（application/xhtml+xml）。这样可以使得代码更加简洁而且所有浏览器都支持。
2. 正确使用HTML标签，使用工具如[W3C HTML](http://validator.w3.org/nu/)验证；使用合法的HTML标签是可被衡量的规范，有助于编码者学习的技术要求和限制，并保证代码质量。
3. 使用语义话的标签，比如文章内容使用`<atricle>`，文字段落使用`<p>`，导航使用`<nav>`等。语义化地使用HTML有助于网页的可访问性，复用性，和优化代码效率。尽量少的为元素增加id和class属性，如果需要增加请使用正确的命名。
4. 不再使用type属性，因为在HMLT5中已经规定默认type值，无必要再次指定。


### 1.3 CSS规范 ###

1. 尽可能使用CSS验证，除非因为修正浏览器解析差异而编写私有属性，否则都应该使用合法的CSS代码。可以使用[W3C CSS validator](http://jigsaw.w3.org/css-validator/)测试你的CSS。使用合法的CSS同样是一个可被衡量的规则，它能标记出那些不起作用和可被删除的代码，并确保CSS的正确使用。
2. 为样式赋予合适的类名，尽量不要使用`.red`，`.big-text`等与内容无关的命名方式（如果确实要使用，这时应该反思是否是采用的UI框架缺陷）。当类名代表的意义有广泛任何的缩写形式，则可以采用缩写，例如`navigation`可以缩写为`nav`。类名中采用分词形式时（包含多个单词时）请使用间隔号`-`来连接。
3. 当CSS属性值为数字且为0时，不要添加单位，例如`border-width: 0px;`应书写为`border-width: 0;`；当属性值为16进制时，如果可以尽量使用3位表示。
4. 尽可能采用css简写形式。
5. `url()`中不要加入引号。
6. CSS属性名称与值之间使用一个空格分隔，例如`color: red;`。
7. 在开发环境下尽可能使用多行CSS属性形式，`{`和`}`各单独占一行，每行书写一个属性值且采用2空格缩进；如果使用单行CSS，选择器后加一个空格，分号“;”后加一个空格，例如`ul>li {color: red; border: 1px solid red}`；`{}`中的最后一组属性末尾不需要写`;`。
8. 使用空行来划分规则的相关性。
9. 使用正确且精简的选择器，id与类名之前不需要加标签名称，例如`ul.nav {color: red}`应写为`.nav {color: red}`。


### 1.4 Javascript规范 ###

1. 字符串优先使用单引号。

其他Javascript规范请参考：
> 禅道PHP编码规范.doc。


## 2. 框架规范 ##


### 2.1 UI元素类型及定义 ###

ZUI中包含各种各样的界面元素（或控件），例如按钮、表格、列表等，甚至一些特定场景用到的一组元素也会在ZUI中精心设计，例如评论列表。为了更好的展示我们的设计理念，把这些元素归为如下5类：

- **基本控件**：用来构建网页应用的基本界面单元，例如按钮、文本标签、输入框等。
- **组件**：通过一个以上的基本控件组合而成的较复杂的界面单元。例如表单、菜单、表格等。
- **视图**：视图是将基本控件和组件组合使用来展现网站上的通用内容，例如评论视图及文章预览列表视图。
- **模块**：模块为了实现界面上一些通用功能而实现，不仅仅包含界面部分也包含交互行为，例如单击按钮弹出有模态效果的对话框。
- **行为**：行为更多的定义了一组根据需要执行的动作，并且不会与特定的控件及组件相关联。

ZUI中的大多数界面元素都有不同的子类型、状态及参数。关于类型、状态及参数的定义如下：

- **类型**：同一种界面单元的不同类型，例如按钮有主要按钮、次要按钮及危险按钮等，导航菜单类型有普通导航及顶部固定导航等。任何时候都应该只为同一个界面元素指定一种类型，默认类型无需指定。
- **状态**：状态为同一种界面单元允许在不同的状态中切换，例如按钮有正常状态和不可用状态，下拉菜单有展开及收拢状态，菜单项目有选中和未选中状态等。在同一个界面元素中允许叠加多个状态。
- **参数**：参数作为界面单元如何展现提供依据，例如表格是否隔行变色，是否启用鼠标悬停等。可以同时指定多个参数。


### 2.2 界面元素的命名 ###

**命名原则**

- 所有控件、组件、视图、模块和行为的命名都应该使用最常见的名称，准确提现界面元素功能。例如菜单应该命名为menu，而不是navigation。
- 类型、状态及参数的命名均为元素名加上类型（或状态及参数名）前缀，中间用间隔号分隔，例如固定位置的菜单为`.menu-fixed`。对于通用类型、状态或参数可以省略前缀，例如一个菜单项目处于激活状态，则只需命名为`.active`，而不许命名为`.menu-active`。
- 所有控件、组件、视图、模块和行为的命名均不加与当前元素功能无关的前缀和额外命名，例如一个导航菜单命名为`.menu`，而不增加额外命名为`.ui.menu`或者`.zui.menu`。


### 2.2 代码文件结构 ###

    zui/
    ├── src/                        // 源码
    │   ├── fonts/                 // 字体文件
    │   ├── js/                    // js框架
    │   └── less/                  // 样式
    │       └──basic/              // 基础
    │          ├──normalize.less   // css normalize
    │          └──grid.less        // 栅格系统
    ├── dist/                       // 可用版本
    │   ├── css/
    │   ├── js/
    │   └── fonts/
    ├── examples/                   // 一些例子
    ├── asserts/                    // 其他引用的资源
    │  	└── js/
    ├── _layouts/                   // 文档模版
    └── _includes/                  // 文档内容


### 2.3 开发约定 ###

- 不在框架文档中加入与框架当前无关的资源；


## 3 基础 ##


### 3.1 css normalize ###

采用开源项目 [normalize.css](git.io/normalize) 进行样式重置。


### 3.2 栅格系统 ###

todo(azhi)：撰写栅格系统文档