Colorgy 的樣式指南、樣式表以及前端工具包。
The front-end bundle and style guide for Colorgy, based on Bootstrap 3 for the basis, and MVCSS for architecturing. Includes Materialize.
適用於任何使用 Compass/Sass/SCSS 以及 Sprockets 的專案，例如 Ruby on Rails 或 Middleman。
將以下這行加入 Gemfile 裡：
gem 'colorgy_style'然後執行：
$ bundle
在 app/assets/stylesheets/application.scss 或其他想要的地方引入 Colorgy 樣式表：
@import "colorgy-sprockets";
@import "colorgy";你也可以只拆出部分元件使用，或是調整一些變數，詳情請參考 Project Structure 段落。
在 app/assets/javascripts/application.js 或其他需要的地方導入 JavaScripts：
//= require colorgycolorgy.js 是一個將所有相依套件都打包在一起的集合包，所以你將不需要另外 require 像是 jquery 或 modernizr 之類的函式庫。
你也可以選擇只導入部分的檔案或元件，詳情請參考 Project Structure 段落。
這份懶人包同時也將一些常用的函式庫一併包含進來了，你可以查看 assets/javascripts/vendor 以及 assets/stylesheets/vendor 來找出有哪些東西可以加以利用，然後在你的 JS 或 SCSS 檔中像這樣引入它們：//= require vendor/classnames.js (JavaScript)、@import "vendor/animate"; (SCSS)。
適用於任何專案。
直接下載打包後的 colorgy.css 與 colorgy.js 檔案，並加它們加到你的網頁中。所有倚賴的 JavaScript 也已經被打包進去了，所以你不需要再引入像是 jQuery 等函式庫。
├── README.md
├── ...
├── bin
│ └── ...
├── lib
│ └── ...
├── spec
│ └── ...
├── styleguide
│ ├── layouts
│ │ └── ...
│ ├── styleblocks
│ │ └── ...
│ └── ...
└── assets
├── fonts
│ └── colorgy
│ ├── ...
| └── icons
| └── ...
├── images
│ └── colorgy
│ └── ...
├── stylesheets
| ├── ...
| ├── colorgy.scss
| ├── colorgy
| │ ├── application.scss
| │ ├── core
| │ │ └── ...
| │ ├── structures
| │ │ └── ...
| │ └── components
| │ └── ...
| └── vendor
| └── ...
└── javascripts
├── colorgy.js
├── bundle.js
├── colorgy
│ ├── application.js
│ ├── components
│ | └── ...
│ ├── lib
│ | └── ...
│ └── modernizr.js
└── vendor
└── ...
Gemfile和Gemfile.lock- 用於 Bundler 的 Ruby Gems 相依套件列表colorgy_style.gemspec- 此 Gem 的規格config.rb- 專案 builder、開發用伺服器 - Middleman、KSS - 的組態文件Rakefile- 定義用於此專案的 Rake tasks
放置可執行的 scripts。
console- 啟動 Interactive Ruby Consoleserver- 啟動本地端開發用伺服器setup- 在初次簽出專案時自動安裝所有相依套件
放置 Ruby Gem 的 Library 程式碼。
放置 Ruby Gem 的整合測試。
用於樣式指南 (Living Style Guide) 的網頁源碼。
layouts/- 各 layout 的範例styleblocks/- 與各元件 (components) 搭配的展示用 HTML- 其他檔案 - 樣式指南網頁主體
前端框架本體。
所有字型檔案。為方便與其他前端框架整合，因此所有檔案皆放置於 colorgy 目錄下作為 namespace。
icons/- icon font 的 SVG 原檔，係由該目錄底下的Icons.sketch匯出，並使用 Font Custom 產生字體
圖片檔案。為方便與其他前端框架整合，因此所有檔案皆放置於 colorgy 目錄下作為 namespace。
樣式表。為方便與其他前端框架整合，因此所有檔案皆放置於 colorgy 目錄下作為 namespace，並遵照 MVCSS-like 的目錄架構。皆使用 Sass (SCSS) 撰寫。
application.scss- 主 manifest 檔，引入所有部件core/- 基礎建設，包含config(預設組態)、fonts(字型定義)、base(基本樣式)grid(網格系統) 等最核心的部分，以及utilities(輔助調整內容的懶人 class 們) 還有helpers(通用的 function 或 mixin)structures/- 各式排版結構，被重複使用的排版容器components/- 各式元件，可獨立使用的 UI 單位
使元件具有基本互動功能，或是輔助 CSS 作為 polyfill 的簡單 JavaScripts 代碼。
目錄結構大略與樣式表 stylesheets/colorgy 一致，使得一份 css 得以搭配一份 js (若需要的話)。
application.js- manifest file for Sprocketslib/- 可跨部件使用的 helpersmodernizr.js- 客製化的 Modernizr
注意此專案為基本前端樣式，加入 JavaScript 僅是為了對需要的「單一」CSS 元件/架構/佈局進行輔助，因此尤須注意不得跨區污染，或使用過度複雜的架構。
可引入使用的第三方 JavaScript 函式庫。為了方便而直接加入在此專案中。
基本 coding style 可參考專案目錄下的 .editorconfig 並在編輯器安裝 EditorConfig 來遵守。
CSS 部分採用了 SMACSS 的方法論以及 BEM 命名架構 [*]，並遵從大部份 MVCSS 的準則。
core/目錄下放置了 stylesheet 核心，包含 config、helpers、基本元素 (base)、utilities (例如.pull-right、.text-center、.inverse) 等structures/底下收納了各種頁面的佈局結構 - 沒有實際表現風格，提供排版、又或是 RWD 輔助的鷹架，class name 通常以l-前綴components/中放置各式元件 - 無相依性、可重複使用的 UI 基本單位
[*]: Element 的命名使用 .card-header 風格，而非原始的 .card__header。Modifier 命名慣例則為一致，但某些慣用的 state，例如 .active、.disabled、.open、.collapse、.dismissible、.inverse 可以直接使用 class 表示 (而這些 class 通常也參與 JS 的互動)。
$component-name-element-name-modifier-property-property-variant
以上各部分解釋如下：
component-name: 該變數是屬於哪個 component (若有)element-name: 該變數是屬於哪個 element (若有)，注意無需再加上重複的component-namemodifier: 該變數是屬於哪個 modifier (若有)，注意無需再加上重複的component-name或element-name，例如hover、active、inverseproperty: 變數內容，例如color、bg、padding、font-sizeproperty-variant: 變數本身的變形，例如dark、large
範例：
$font-family-sans-serif、$font-family-serif$font-size-base、$font-size-large、$font-size-small$gray-darker$text-color、$text-color-inverse$padding-base-vertical、$box-padding-base-vertical$btn-border-width$btn-color、$btn-success-color
以下為一些 SCSS 的撰寫範例模板，可供開發時複製使用。
// ----- Function Name ----- //
// -> Description
//
// $arg - the argument description
@function name($arg) {
}// ----- Mixin Name ----- //
// -> Description
//
// $arg - the argument description
@mixin button-variant($arg) {
}// *************************************
//
// Component
// -> Description
//
// .component--modifier - description
//
// Styleguide StyleguideSection
//
// *************************************
// -------------------------------------
// Variables
// -------------------------------------
// ----- Colors ----- //
// ... (with the !default flag)
// ----- Sizing ----- //
// ... (with the !default flag)
// -------------------------------------
// Helpers
// -------------------------------------
// ...
// -------------------------------------
// Base
// -------------------------------------
.component {
}
// -------------------------------------
// Scaffolding
// -------------------------------------
// ----- Scaffolding Name ----- //
.component-scaffolding {
}
// -------------------------------------
// Modifiers
// -------------------------------------
// ----- Modifier Name ----- //
.component--modifier {
}寫好一個新元件後，照慣例 (KSS) 加入檔頭註解，在 styleguide/styleblocks 底下建立相對應的 sample HTML code (檔名與 css 一致)，接著編輯要歸入的 styleguide section (例如 styleguide/components.html.haml)，將 styleblock (像是 = styleblock 'button', section: 'Button') 插入即可。
REQUIREMENTS: A Mac with Homebrew installed.
After checking out the repo, run bin/setup to install dependencies. Then run bin/server to fire up the development server, or run rake rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
To complie the icon fonts from the SVGs in assets/fonts/colorgy/icons (exported from assets/fonts/colorgy/icons/Icons.sketch), run bin/fcompile.
To deploy the style guide to GitHub Pages, simply run bundle exec rake deploy and the source will be builded and pushed to gh-pages of the origin repo.
可以運用 styleguide/workspace/* 來加速撰寫 CSS —— 將開發中的元件先寫在這裡，便於做環境隔離與加速 livereload，寫完後再整理進專案裡並 commit。
Bug reports and pull requests are welcome on GitHub at https://github.com/colorgy/Style.