1. 首页
  2. css

CSS直接从Sass建立一个样式指南

去年秋天,我们的开发团队想开始使用样式指南。我们为团队增加了一名新成员,随着他的进步,我们意识到我们的项目文档是多么的缺乏。如果你曾经是一个文档薄弱的团队中的新开发人员,那么你就知道在没有文档的情况下尝试熟悉十几个项目是多么令人困惑。
在决定样式指南方法时,我们提出了两个主要要求:
1. 低摩擦样式指南应该很容易找到,易于阅读,易于维护。一些适合我们现有的开发工作流程的东西将会非常棒。为示例标记和文档文件添加新目录并不可怕。
2. 平台无关性我们最常使用WordPress、Drupal和CakePHP,并且我们希望在所有三个平台上都能以相同的方式工作。我们希望它易于维护,对我们来说,这意味着将文档与CSS放在一起。
3. 节点.jsKnyle样式表(KSS)的实现,一个Ruby库:…提供了一种在团队中编写可维护的、文档化的CSS的方法。具体来说,KSS是一种文档规范和样式指南格式。基本原则是通过在CSS、scs、Sass、LESS等中创建的注释生成样式指南。您可以这样编写一些CSS:// Bold Button//// Use this class for a bolder, stronger looking button.//// Markup:// And get this lovely output:Screenshot of the generated documentation for the bold buttonYou are able to organize your documentation however you like and it generates a nice little navigation and document structure for you as well:Because it lives inside your CSS, updating it fits naturally in existing development workflows. If you update some CSS properties, the style guide is automatically updated. If you need to update the documentation, the documentation text is sitting right on top of the component you are working on. Even if you never visit the generated style guide, you will see the style guide any time you open a CSS file. Low friction? Check.Additionally, since we use CSS and build processes in all our web projects, it\”s as platform agnostic as we need it to be.Let\”s get started!Initial SetupIn your project directory, you want to install kss-node as a project dependency. We\”re also going to install michelangelo, a nice theme for the style guide:$ npm install –save-dev kss michelangelo您可以通过运行创建一个名为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.jsindex.htmlmain.css如果希望运行更干净的命令,可以尝试编译样式指南:$ ./node_modules/.bin/kss –config kss-config.json,将脚本添加到`包.json`用法:\”scripts\”: {\”kss\”: \”kss –config kss-config.json\”},现在可以运行$ npm run kss来编译样式指南。(我将继续使用此方法,但如果需要,您可以使用$ ./node_modules/.bin/kss –config kss-config.json)。由于我们还没有编写任何文档,您可能会收到这样的消息:错误:在源文件中找不到KSS文档。让我们通过记录第一个组件来解决这个问题!创建并记录一个简单的组件。!您可以根据指定的目标路径访问它。在这个例子中,我们有一个静态站点,我在/styleguide中编译了它,所以我将使用这个url来查找它。如果你使用米开朗基罗主题(我去掉了括号中的注释),应该是这样的:文章标题文档发生了这样的事情:KSS为我们的文章标题创建了一个文档部分,包括标题、描述、标记,以及我们提供的CSS。您可以看到呈现的HTML和CSS以及原始HTML。KSS看到我们将post标题嵌套在Components/Article下面,因此它创建了一个Components顶层部分和一个组件.文章部分。我们的文章标题嵌套在这两个标题之下。KSS根据这个层次结构生成了一个导航。,您可以通过定义一个文档块来提供关于文章组件的更多信息,该文档块通过Styleguide Components.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),您将看到您的大纲得到了更多的填写:组件和文章文档记录组件状态和变化我们的post title组件非常简单,但是我们需要在样式指南中显示更复杂的信息。KSS可以很容易地处理组件的变化以及像:hover或:focus这样的交互状态。我们将记录一个按钮来显示这一点。对于:focus和:hover,我们的按钮将有不同的样式,还有小的变化和大的变化。以下是我们将要开始的CSS:我们将用2个附加项来格式化我们的文档,就像我们对文章标题所做的那样:我们将向所有的ou添加一个占位符类{{modifier_class}}
4. KSS为我们的文章标题创建了一个文档部分,包括标题、描述、标记,以及我们提供的CSS。您可以看到呈现的HTML和CSS以及原始HTML。
5. KSS看到我们将post标题嵌套在Components/Article下面,因此它创建了一个Components顶层部分和一个组件.文章部分。我们的文章标题嵌套在这两个标题之下。
6. KSS根据这个层次结构生成了一个导航。
7. ,您可以通过定义一个文档块来提供关于文章组件的更多信息,该文档块通过Styleguide Components.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),您将看到您的大纲得到了更多的填写:组件和文章文档记录组件状态和变化我们的post title组件非常简单,但是我们需要在样式指南中显示更复杂的信息。KSS可以很容易地处理组件的变化以及像:hover或:focus这样的交互状态。我们将记录一个按钮来显示这一点。对于:focus和:hover,我们的按钮将有不同的样式,还有小的变化和大的变化。以下是我们将要开始的CSS:我们将用2个附加项来格式化我们的文档,就像我们对文章标题所做的那样:我们将向所有的ou添加一个占位符类{{modifier_class}}

CSS直接从Sass建立一个样式指南 为WP2原创文章,链接:https://www.wp2.cn/css/css%e7%9b%b4%e6%8e%a5%e4%bb%8esass%e5%bb%ba%e7%ab%8b%e4%b8%80%e4%b8%aa%e6%a0%b7%e5%bc%8f%e6%8c%87%e5%8d%97/