直接从 Sass 构建样式指南

去年秋季，我们的开发团队想要开始使用样式指南。 我们团队中增加了一位新成员，在他开始学习的过程中，我们意识到我们的项目文档有多么缺乏。 如果你曾经在文档薄弱的团队中担任过新开发者，你就会知道，在没有文档的情况下尝试熟悉十几个项目是多么令人困惑。

在决定样式指南方法时，我们提出了两个主要要求

1. 低摩擦样式指南应该易于查找、易于阅读和易于维护。 能够融入我们现有的开发工作流程将非常棒。 为示例标记和文档文件添加新目录将不会那么棒。
2. 平台无关我们最常使用 WordPress、Drupal 和 CakePHP，我们想要一个在所有三个平台上都能以相同方式运行的东西。 我们希望这易于维护，对我们来说，这意味着将文档与 CSS 保持在一起。

Node-KSS 的基础知识

为了实现平台无关、低摩擦样式指南的目标，我们选择了 kss-node，它本身是 Knyle Style Sheets (KSS) 的 Node.js 实现，这是一个 Ruby 库，它

…为团队提供了一种编写可维护、有文档的 CSS 的方法。 具体来说，KSS 是一种文档规范和样式指南格式。

基本原理是，您的样式指南是通过您在 CSS、SCSS、Sass、LESS 等中创建的注释生成的。

您编写一些像这样的 CSS

// Bold Button
//
// Use this class for a bolder, stronger looking button.
//
// Markup:
// <button class="btn btn-bold">Click Me</button>
//
// Styleguide Components.Buttons.bold
.btn.btn-bold {
    position: relative;
    font-weight: bold;
    text-transform: uppercase;
}

并获得这样的精美输出

您可以根据自己的喜好组织文档，它还会为您生成一个漂亮的导航和文档结构

因为它存在于您的 CSS 中，所以更新它自然地适合现有的开发工作流程。 如果您更新了一些 CSS 属性，样式指南会自动更新。 如果您需要更新文档，文档文本就坐在您正在处理的组件的顶部。 即使您从未访问过生成的样式指南，您也会在每次打开 CSS 文件时看到样式指南。 低摩擦？ 确定。

此外，由于我们在所有 Web 项目中都使用 CSS 和构建流程，因此它与我们需要的平台无关。

让我们开始吧！

初始设置

在您的项目目录中，您需要将 kss-node 安装为项目依赖项。 我们还将安装 michelangelo，这是一个用于样式指南的不错的主题

$ npm install --save-dev kss michelangelo

您可以通过运行以下命令来验证它是否已安装

$ ./node_modules/.bin/kss --version

我们将创建一个名为 kss-config.json 的文件来配置我们的 KSS 设置。

在您的文件中，创建如下所示的对象（请注意，我下面的注释仅供参考，为了获得最佳效果，请从您的配置文件中删除它们）

{
  "title": "Title of the Style Guide",

  // Source tells KSS where the CSS, Sass, or SCSS is that it should parse for documentation comments. 
  // Here we are assuming your sass is in a directory at the root level of your project.
  "source": "sass/",

  // Destination tells KSS where to compile your style guide to.
  "destination": "styleguide/",

  // Builder tells KSS where to look for a theme. 
  // If you aren't using michelangelo, you don't need this.
  "builder": "node_modules/michelangelo/kss_styleguide/custom-template/",

  // CSS gives KSS the path to your CSS, so it can pull your styles into the style guide. 
  // The path needs to be relative to your style guide destination.
  // Here, our style guide is in /styleguide and our compiled css is at our project root.
  "css": [
    "../main.css"
  ],

  // If you want to include any javascript files, add this block, with the path to your javascript file. 
  // Also relative to your style guide destination.
 // Optional.
  "js" : [
    "../bundle.js"
  ]
}

这假设一个简单的项目目录树，如下所示

js/
sass/
bundle.js
index.html
main.css

您可以尝试通过运行以下命令来编译样式指南

$ ./node_modules/.bin/kss --config kss-config.json

如果您想要一个更简洁的命令来运行，请在 package.json 中的 scripts 块中添加一个脚本

"scripts": {
  "kss": "kss --config kss-config.json"
},

现在，您可以运行 $ npm run kss 来编译您的样式指南。（我将在后面使用这种方法，但如果您愿意，也可以使用 $ ./node_modules/.bin/kss --config kss-config.json）。

但是，由于我们还没有编写任何文档，因此您可能会收到以下消息

错误：在源文件中未发现 KSS 文档。

让我们通过记录我们的第一个组件来解决这个问题！

创建并记录一个简单的组件

我们将创建一个示例帖子标题组件。

这是我们的 CSS

.post-title {
  font-size: 3em;
  text-align: center;
  font-family: fantasy;
}

为了创建我们的文档，我们将创建一个注释

// Post Title (this will be the title of your component)
//
// Large, **in charge**, and centered. (this is the description of your component. you can use markdown in here.)
//
// Markup (define the markup to be used in your styleguide):
// <h1 class="post-title">A Post Title</h1>
//
// Styleguide Components.article.post-title 
// (ꜛ this controls the organization of your style guide. Here, I'm filing this component inside Components / Article / Post Title) 

.post-title { 
    font-size: 3em; 
    text-align: center;
    font-family: fantasy; 
}

运行 $ npm run kss，您的样式指南应该会编译！ 您可以根据您提供的目标路径访问它。 在这个示例中，我们有一个静态站点，我将其编译到 /styleguide 中，因此这是我用来查找它的 URL。 以下是使用 michelangelo 主题时它应该是什么样子（我已经删除了括号中的注释）

以下是发生的事情

1. KSS 为我们的帖子标题创建了一个文档部分，其中包含我们提供的标题、描述、标记和 CSS。 您可以看到渲染的 HTML 和 CSS 以及原始 HTML。
2. KSS 看到我们将帖子标题嵌套在 Components / Article 下面，因此它创建了一个 Components 顶级部分和一个 Components.article 部分。 我们的帖子标题嵌套在这两者之下。
3. KSS 根据这种层次结构生成了一个导航。

如果您想提供有关 Components 的更多信息，您可以提供一个文档块（实际上在 CSS 的任何地方都可以），如下所示

// Components
//
// Components are ingredients of our design system. They may be made up of smaller groups of styles.
//
// Styleguide Components

同样，您可以通过定义一个使用 Styleguide Components.article 方法定位该项目的文档块来提供有关 article 组件的更多信息

// Article
//
// An article is made up of a title, featured image, and some default
// typographic settings for links, italics, bold, and blockquotes.
//
// Styleguide Components.article

使用这些新的文档块，再次编译您的样式指南 ($ npm run kss)，您将看到您的大纲会更完整一些

记录组件状态和变体

我们的帖子标题组件非常简单，但我们需要在我们的样式指南中显示更复杂的信息。 KSS 可以轻松处理组件的变体以及交互式状态，例如 :hover 或 :focus。 我们将记录一个按钮来显示这一点。

我们的按钮将为 :focus 和 :hover 提供不同的样式，以及一个小的变体和一个大的变体。 以下是我们将要使用的 CSS

.button {
  padding: 1em 2em;
  margin: .5em;
  display: inline-block;
  font-size: .9em;
  font-family: Helvetica, sans-serif;
  font-weight: bold;
  text-transform: uppercase;
  color: #f56476;
  background-color: #fff;
  border: 2px solid #f56476;
  transition: .2s color, .2s background-color, .2s border-color;
}

.button:hover {
  color: #fff;
  background-color: #f56476;
}

.button:focus {
  color: #3ddc97;
  border-color: currentColor;
}

.button--small {
  font-size: .5em;
}

.button--large {
  font-size: 1.5em;
}

我们将像我们为帖子标题所做的那样格式化我们的文档，并添加两个补充内容：我们将向所有将获得修改器元素添加一个占位符类 {{modifier_class}}，并将直接在我们标记的下方定义我们的状态/变体。 我们的注释块将如下所示（我已经添加了一些注释，括号中是说明）

// Buttons (title, same as before)
//
// Various button styles. (description, just as before)
//
// Markup: (we add the `{{modifier_class}}` to every element that has a modifier)
// Link Button
// <button class="button {{modifier_class}}">Button Element</button>
// <input class="button {{modifier_class}}" type="button" value="Input Button" />
//
// (a new modifiers section)
// :hover - When user hovers over button.
// :focus - When button is focused.
// .button--small - A small button.
// .button--large - A large button.
//
// Styleguide Components.button (organization, just as before)

您可以看到，我已经为我在 CSS 中声明的每个变体添加了一个变体。 格式为

// .class-name - Description

或

// :state - Description

编译样式指南后，您将获得以下新文档

您可以看到，您现在有了您在修饰符部分描述的每个状态和变体的示例，并应用了相应的 CSS。

这种技术也适用于比这个按钮更复杂的组件。 假设您有一个 .card 组件，其中包含内部的子元素，这些子元素需要在用户悬停在卡片上时更改。 要记录这一点，您只需将 {{modifier_class}} 添加到 .card 元素并像上面一样指定悬停状态。

组织

默认情况下，部分将按其标题的字母顺序组织。 例如，在上面的示例中，我们的按钮组件将出现在我们的文章组件之后。 但是，如果您想更改组件或其他部分的顺序，可以为组件提供权重。 权重越高，组件在其部分中越靠下。 权重越低，组件在其部分中越靠上。

使用 Sass 或 SCSS 时，我将组织注释放在 main.sass 或我导入部分的位置。 例如，在一个最近的项目中，我有一个 Typography 部分和一个 Elements 部分，它们都归档在 Base 顶级部分之下。 自然地，KSS 会按字母顺序组织这些部分，但我希望 Typography 首先出现。 以下是我在 main.sass 文件中更改权重的方式

// Typography
//
// Weight: 1
//
// Styleguide base.typography
@import "base/typography"

// Elements
//
// Weight: 2
//
// Styleguide base.elements
@import "base/elements"

调色板

我们正在使用的 Michelangelo 主题提供了一个很酷的调色板生成器。如果你正在使用 Sass 或 SCSS，你可以记录你的颜色变量名称，KSS 会格式化一个小的调色板块。

就像这样注释

// Highlight Colors
//
// Colors we use for higlighting states.
//
// $highlight-blue - #1460aa; primary blue
// $highlight-purple - #674172; secondary purple
// $highlight-red - #d50000; danger red
//
// Styleguide Base.colors

KSS 会创建一个调色板，方便你像这样参考

自动编译样式指南

与其每次修改 CSS 时都运行 $ npm run kss，不如添加一个监视任务，以便每次我们的 CSS 文件发生变化时都重新生成样式指南。我将在下一步中介绍如何使用 npm Scripts 和 Grunt 来实现。

npm Scripts

我们已经使用 npm 脚本来构建样式指南，我们只需要添加一个脚本，它将监视我们的样式指南。

我们将使用 onchange 包。首先安装它

$ npm install onchange --save-dev

然后在我们的脚本对象中添加一个新的脚本

"scripts": {
  "watch": "onchange 'sass/**/*.sass' -- npm run kss",
  "kss": "kss --config kss-config.json"
},

监视任务告诉 onchange 监视我们在 glob 模式 ('sass/**/*.sass') 中指定的 ​​文件，并且当它检测到更改时，运行我们在 -- 后指定的命令：npm run kss。

现在运行 $ npm run watch 将监视我们的 .sass 文件，并在每次检测到 Sass 中的更改时重新生成样式指南。

Grunt

KSS 有一个官方的 Grunt 插件，grunt-kss。你可以将其配置为监视你的 .sass 或 .scss 文件以查看更改，并在你开发时重新编译样式指南。

这是一个 Grunt 配置示例。使用此设置，你不需要单独的 kss-config.json 文件，所有配置都可以在你的 Gruntfile 中进行。

module.exports = function(grunt) {
  grunt.initConfig({
    kss: {
      options: {
        title: 'Title of the Style Guide',
        builder: "./node_modules/michelangelo/kss_styleguide/custom-template/",
        css: [
          "../path/to/compiled/css.css",
        ],
        js: [
          "../path/to/compiled/javascript.js",
        ]
      },
      dist: {
        src: "path/to/css/src",
        dest: "styleguide/",
      }
    },
    watch: {
      sass: {
        files: [
          './path/to/**/*.sass'
        ],
        tasks: ['kss']
      },
    }
  });

  grunt.loadNpmTasks('grunt-kss');
  grunt.loadNpmTasks('grunt-contrib-watch');

  grunt.registerTask('dev', ['kss', 'watch']);
}

运行 $ grunt dev 将首先生成样式指南，然后监视我们的 .sass 文件以查看更改，并在检测到更改时重新生成样式指南。

总结

在官方 KSS 仓库 中还有更多关于注释解析和其他功能的详细信息，这些功能我在本文中没有提及。本文已经提供了足够的信息让你开始使用，但有一些内容我没有深入介绍，包括自定义主页、实验/弃用标志和预处理器的帮助程序。

如果你想更进一步，可以开发自己的样式指南来代替我们使用的 Michelangelo 主题。查看 使用自定义模板的文档 以了解更多信息。