跳到内容
必威体育论坛必威精装下载APPRedfin解决方案的标志必威体育论坛必威精装下载APPRedfin解决方案的标志 联系
图书馆里的书按颜色分类

入门赫尔曼:生活方式指南和模式库

这一切都始于一条无辜的推特:

https://twitter.com/mirisuzanne/status/948637526612324352

“很高兴宣布我们新的开源,sass驱动的模式库生成器!去设计一些系统吧!”

我在推特上关注米里亚姆,因为我喜欢她做过的一切。在雷德必威体育论坛芬,我们是苏西的超级粉丝,直到她告诉我们不要再用了.就像Drupal社区和网络开发者社区的其他人一样,我们听到的关于Drupal的消息越来越多原子设计以及使用模式库来建立网站。我们被鼓励建立和使用规范的生活方式指南。在Drupal世界中,已经出现了许多工具模式的实验室一直是大赢家。

在Re必威体育论坛dfin,我们尝试了很多这样的工具,包括Sam Richard的风格的原型并参加了模式实验室的培训。我们也尝试过KSS用于记录Sass并生成样式指南。

为什么赫尔曼

赫尔曼吸引我的是中小型项目的普遍困境,以及它的预算能力(或无力)交付这些原型。从赫尔曼公告Oddbird:

创造美丽的Salesforce闪电设计系统需要一个持续的专职团队。我们这些从事代理工作的人通常没有这种奢侈,但我们的客户仍然需要一个对他们有效的系统。

那么,我们如何使设计系统成为敏捷过程的一部分——与应用程序一起缓慢增长,就像我们在任何项目中编写和维护测试覆盖率一样?我们如何使文档和设计的一致性成为阻力最小的路径?

我是系统的忠实信徒。也就是说,我是系统的忠实信徒那项工作.如果一个人不想使用一个系统因为它有太多的障碍,那么系统已经失败的,不是人。所以,“阻力最小的路径”的想法很吸引我(或者也许我只是懒惰,但是,系统应该为懒惰者构建)。

赫曼带着承诺和光芒来了我决定试一试。首先,赫尔曼的基础很大程度上是SassDoc.SassDoc与KSS有着相似的目的,不过,现在我已经使用了它,我发现它的语法更容易理解一些。也许吧,我已经知道了Drupal注释, SassDoc中的注释感觉很自然。

开始使用SassDoc

为此,赫尔曼实际上只是一个“主题”SassDoc。因此,首先,您将初始化一个新的SassDoc项目。像今天的大多数前端世界一样,新的前端项目是使用类似于NPM.在Re必威体育论坛dfin,我们使用Yarn,所以我们使用“Yarn init”初始化我们的项目,并回答适当的问题。

初始化之后,我们添加了两个依赖项——SassDoc和Herman主题:

纱线添加sassdoc sassdoc-theme-herman

一旦完成,你就搭建了一个赫尔曼项目。你现在需要的是你所有的无礼!创建一个sass文件夹开始并放置一个样式。里面有SCSS文件。我们从一些简单的开始:

.button {border-radius: 5px;背景颜色:绿色;颜色:白色;粗细:大胆的;}

这是我们想要记录的第一个简单组件。也许,如果你幸运的话,你之前在里面有什么字条,比如//典型的按钮样式什么的。

SassDoc使用“三斜杠”语法将注释作为文档拉入。让我们加强一下。

///组件:在站点上使用的小型、可重复使用的组件。/// @group components /// @name Button /// @group components /// @example html /// Click me % Button {border-radius: 5px;背景颜色:绿色;颜色:白色;粗细:大胆的;}

第一个注释被一个换行符与其他注释抵消,称为“自由浮动注释”。它只是“在那里”,没有附加任何东西。但是,请注意使用“group”注释(@group组件我能够把它分配到一个组里。使用其他注释,比如名称和示例,我就能够生成我的风格指南(在一天结束的时候,只是一个静态站点)。

要生成,你需要在项目的根目录下运行:

node_modules / sassdoc / bin / sassdoc sass——主题=赫尔曼

这给了你如下的静态站点(通过访问/sassdoc/index.html从你的站点根目录找到它):

继续

让我们把一些不同的东西放在一起,更高级一点。让我们加入一个mixin。

@mixin嵌入容器($width, $height) {$ratio: ($height / $width) * 100%;位置:相对;padding-bottom:美元比率;高度:0;溢出:隐藏;max-width: 100%;Iframe,对象,嵌入{位置:绝对;上图:0;左:0;宽度:100%; height: 100%; } }

这个mixin的灵感来自Smashing杂志关于这个主题的永恒的文章

现在,让我们来注释!把它直接放在你的mixin上面。

/// Mixins:我们使用的自定义可重用但可配置的工具。/// @group Mixins /// Helper mixin drop on the wrapper for an iframe ///你想要响应。/// /// @group Mixins /// @author Smashing Magazine /// /// @param {Length} $width -元素的宽度/// @param {Length} $height -元素的高度/// @output包装器和内部iframe的CSS,在它被调整大小时保持aspect ///比率。/// /// @example SCSS - /// .embed-container {/// @include embed-container(400px, 300px);/ / /}

上面的文档向我们介绍了@ phase注释,它允许我们记录参数、类型、名称、默认值和描述,使用语法:

/// @param {type} $name[默认值]- description . //

还要注意,这里我们没有为@example注释显示标记;相反,我们使用SCSS作为输出语法。对于mixin,这是非常有用的,因为它可以告诉我们使用这个mixin编译后的CSS是什么!让我们继续并再次编译(node_modules/sassdoc/bin/sassdoc sass——theme=herman)。

啊哦!

»[WARNING] Error compilation @example scss: no mixin named embed-container Backtrace: stdin:2 .embed-container {@include embed-container(400px, 300px);}

边注:除了感到困惑之外,我打赌你已经厌倦了详细说明——主题=赫尔曼每次都在命令行上?让我们一举两得。

您可以在JSON或YAML文件中指定它们,而不是每次在命令行上指定Herman参数。这样,你就只能指定了- c /路径/ /配置每一次。当然,此时此刻,你是拆东墙补西墙。将一个命令行选项切换为另一个。

还有更好的选择。只要将配置文件命名为.sassdocrc,并将其放在项目的根目录下,它就会被自动使用。该文件的全部内容(到目前为止):

主题:赫尔曼

但是,我们还没有解决“没有mixin命名”的问题。请看,来自SassDoc的@example注释本身并不支持将Sass编译成它的CSS对应版本。这是赫尔曼送的礼物。然而,为了让Herman将SCSS编译成CSS,每个@example必须能够独立存在,这是一个领域真的把我绊倒了.谢天谢地,米里亚姆在那里帮忙。

要使此工作,一个选项是导入我们需要的Sass文件,以使示例独立运行。把你的例子改成这样:

/// @example SCSS - /// @import "style. "Scss " /// .embed-container {/// @include embed-container(400px, 300px);/ / /}

在您运行并编译之前,我将为您节省一些时间——这仍然不能工作。但是,这很容易解决。回到你的。sassdocrc并指定一个带有一些配置的“herman”对象。(赫尔曼对象配置的完整细节。

现在让你的。sassdocrc像这样:

主题:Herman: sass: incldepaths: - 'sass'

includepaths指令是重要的,以便赫尔曼可以解决您的进口声明。想做得更好吗?你可以使用另一个声明来自动导入一个或多个路径,但是要注意,你的自动包含不会生成任何实际的Sass输出,否则它会出现在每个例子中。这最好用于您的实用程序文件,如_extends。scss _mixins。scss,等等(参考我们自己的打包机壳主题来看看我们是如何安排的。)例如:

主题:Herman Herman: sass: incldepaths: - 'sass' includes: - 'util/mixins'

如果你自动包含你的util/mixins (really ./sass/util/_mixins.scss),那么你就可以使用你的mixins,而不需要在每个@example中放入@import !

另一个边注:自述

[WARNING] Description file not found: ' ./README. ' ./README. '医学博士’。”最好有一个自述文件。Md为你的项目。它显示为SassDoc项目顶层的index.html页面的文本。我只是创建了一个简单的。这是一个SassDoc配置值,如果您想创建一个与项目的主要README分开的样式指南介绍,您可以设置descriptionPath在。sassdocrc文件中。

升级了

这一切都很好,但我们需要升级。赫尔曼还能提供什么?

没有人比他们自己的自述更能说明这一点了:

除了核心的SassDoc注释,我们的@icons注释允许您显示给定文件夹中的SVG图标,我们扩展了核心@example注释显示编译的Sass/Nunjucks输出和渲染样本组件。我们还提供@font注释用于显示字体样本,以及用于显示的@colors、@sizes和@ratio注释调色板文本和间距大小,以及模块比率."

图标

这个很简单,我们从这里开始。添加一个评论并使用@icons \,你就在那里了!它自动生成你的图标预览文件名,甚至优化他们,因为它去。(请记住,SVG应该指定一个viewBox,否则它们在预览中可能会非常非常小。)它期望每个图标都有一个带有独立SVG文件的文件夹。

字体堆栈预览

事情从这里开始变得有点棘手。对于字体、颜色、比率和大小标注,您需要生成一些前端JavaScript/模板可以使用的JSON。有一个叫做sass- JSON的插件可以帮你做到这一点——获取sass映射并将它们写进编码的JSON中——但是为了做到这一点,你需要导出数据。那么,让我们首先分析一下字体注释。

/ / / @font关键(风格、展示)

在本例中,' key'是Sass映射的变量名,保存着关于字体样式的信息,而(风格,展示)是你想显示的字体权重/样式的列表,例如:(普通、粗体、粗体斜体)

注意,至少对于谷歌字体来说,在粗体和常规关键字之外使用数字是更加一致的。我在使用“半bold”或“light”之类的预览时没有成功。(这是因为他们只支持有效的CSS值的字体-重量-尽管有讨论:https://github.com/oddbird/sassdoc-theme-herman/issues/250)。

最后,第二行是缩进的,以表明它仍然是@font注释的一部分,它包含字体正确呈现所需的任何标记(JavaScript标记、链接标记等)。

所以,在现实生活中,这看起来像:

/// @font Sans -stack (300, 300 italic, regular, 600) /// $ Sans -stack: ('name': 'Work Sans', 'source': 'https://fonts.google.com/specimen/Work+Sans', 'stack': ("Helvetica Neue", "Lucida Grande"),);

对于这样一个web字体,我们使用名称(也就是说,实际的字体名称可以使用如果你显示在一个字体类型属性),源(这显示为一个外部链接预览时显示),和堆栈(回退你选择当这个字体不可用)。

让它渲染,尽管…

这是所有与字体相关的注释,但是现在我们需要将这个Sass地图更全局地包含到“herman”地图中。Herman提供了一个方便的mixin,叫做“Herman -add”,我们可以使用它来实现这一点。在地图之后,我写上:

@include herman-add(' fonts', ' sans-stack', $sans-stack);

为了使用这个Herman -add mixin,你需要包括Herman的实用程序(mixin定义的地方),所以在我的文件的顶部我放:

@ import“. . / node_modules / sassdoc-theme-herman / scss /工具/ _utilities.scss”;

最后,我们需要将Herman地图最终导出为JSON。在我的Sass文件的底部,我写道:

@include herman-export;

这确保了herman映射被导出为JSON,以便前端可以接收它。Herman团队目前正在改进这一过程,但就目前而言,这仍然是一种相当干净的处理方法。如果你比我更喜欢你的部分,你可以有一个Sass文件,只输出herman map JSON,所以你不需要污染你的常规CSS如果你不想。

记住这个模式,因为赫尔曼的大部分出色之处都依赖于它。我们继续,你会看到的。

颜色

既然我们已经建立了一种模式,我们希望继续遵循它。对于在SassDoc静态站点中生成的调色板,我们将遵循类似的模式。首先,注释:

/// @group colors /// @colors demo-colors $demo-colors:('alto': #d8d8d8, 'scorpion': #5b5b5b, 'tree-poppy': #f36c38, 'white':白色,'wild-sand': #f5f5f5, 'grey-light': #d5dbe4,);@include herman-add('colors', 'demo-colors', $demo-colors);

首先,我使用@group注释将它放在左侧的“colors”导航栏中。然后,实际的@colors注释将您将要使用的地图键添加到Herman地图。我们将这些颜色添加到地图中,最后使用herman-add将$demo-colors映射到$herman中。这样,我们在最后调用的herman-export也将在静态站点中包含这个调色板。

大小

对于文本大小,可以生成一个很棒的预览,以显示您想使用的各种标题或大小。找到规律了吗?我们来看看:

///我们拥有的所有大小。/// @group sizing /// @sizes font-size {text} $font-size: ('base': 16px, 'important': 1.8rem, '最大':3rem,);@include herman-add('size ', 'font-size ', $font-size);

比率

比率的表现几乎相同:

///我们正在使用的比率。/// @group sizing /// @ratio my-ratio $my-ratio: ('line-height': 1.4, 'gutter': 0.5,);@include herman-add('ratio ', 'my-ratio ', $my-ratio);

唯一需要知道的是,您可以选择将文本大小(或间距大小或页面大小)显示为标尺,尽管默认情况下是显示文本预览。为此,在size注释之后添加可选的“{rules}”或“{rules -large}”(而不是默认的“{text}”)。

双节棍-武术模板提高了一个档次

对于比一些简单的HTML更复杂的标记,您可以编写Nunjucks模板来生成预览的输出。让我们用Nunjucks模板来增强我们的按钮示例。

/// @group components /// @name buttonset /// @example NJK /// {% set items = [{"name": "do something", "label": "open"}, {"name": "do something else", "label": "close"}] %}Njk ' %} /// .buttonset {li {display: inline-block;list-style-type:没有;margin-right: 1 em;} a{显示:inline-block;@extend %按钮;} }

你会注意到我仍然把它放在组件组中,但我把我的常规按钮变成了buttonset。您还会立即注意到这次@example注释指定了“njk”语法,意思是“编译Nunjucks代码”。在注释中使用njk时,需要在配置中指定一个模板路径。(或者,您可以指定一个完整的Nunjucks环境,但要做到这一点,您必须使用Node API版本,而我不是。)把这个加到你的。sassdocrc里面:

nunjucks: templatepath:’。/模板”

因此,我在项目的根目录下创建了一个“templates”文件夹,并放置了一个简单的buttonset。NJK文件。(亲爱的drupal爱好者们,不要害怕Nunjucks——这是Django/金贾的基于JavaScript的模板,方法是一样的嫩枝是基于Django/ jinja的PHP模板!)

{% for item in items %}

  • {{item.name}}李标签}}< / > < / > {% endfor %}”< / ul > {% endblock %}

    现在我已经配置了一个模板目录,并且设置了使用模板的语法,我得到了一个完整呈现的示例。它包括(a)用来生成它的Nunjucks语言,(b)完全编译的HTML标记,(c)一个完全渲染的例子与我所有的风格!

    想要额外加分,请查看Nunjucks宏,这将帮助您进一步将标记组件化为易于复制的代码片段。如果我们这样做,我们可以把顺序颠倒过来。首先,我们导入定义宏的njk文件:

    /// @name buttonset /// @example NJK /// {% import 'buttonset.macro. txt . txt;Njk ' as my宏%}/// {{my宏。buttonset([{“名称”:“做些什么”、“标签”:“开放”},{“名称”:“别的东西”、“标签”:“关闭”}])}}

    ...而我们的Nunjucks模板略有不同,它使用宏调用包装块。宏类似于“函数”。

    {% macro buttonset(items) %}

  • Baidu