Fractal guidelines
Fractal is a powerful component library & styleguide that fit the way you work. It includes a local server for rapid development and a powerful styleguide. Learn more here: https://fractal.build/
Heres a short intro to using Fractal. For more information take a look at Fractal guide.
For starting a local server with watch and sync run:
npm run fractalFor building the static site run:
npm run fractal:buildFor each pattern we need to declare three files.
- yxz.config.json
- yxz.css
- yxz.hbs
The config file is where we declare information and content about the pattern. We don't use the config for creating modifiers. If a modifier is needed a new variant handlebars file should always be created. This way we can keep track of modifiers both by looking in fractal and also in our file tree.
{
"title": "Button",
"status": "prototype",
"context": {
"text": "Button"
},
"variants": [
{
"name": "ghost",
"context": {
"text": "Ghost Button"
}
},
{
"name": "large",
"context": {
"text": "Large Button"
}
},
{
"name": "link",
"context": {
"text": "Link Button",
"linkUrl":"http://www.novicell.dk",
"linkTitle":"Novicell"
}
}
]
}If you need to have some HTML inside your data, you can use the triple bracket handlebars syntax.
Config (JSON) example:
...
"pageInfoText ": "<em>Lorem ipsum dolor</em> sit amet, consetetur <strong>sadipscing</strong> elitr, <mark>sed diam nonumy eirmod tempor invidunt ut labore et dolore</mark> <span>magna</span> aliquyam erat, sed diam voluptua.",
...View (HBS) example:
<section class="page-section">
<div class="page-section__info">
{{{ pageInfoText }}}
</div>
</section>It contains pattern specific styling. Any variable should be declared in here with a pattern prefix like --button-
:root {
--button-color-primary: var(--color-primary, red);
--button-color-text: var(--color-white, yellow);
--button-base-font-family: var(--base-font-family, blue);
}
/* Default button*/
.button {
cursor: pointer;
background-image: none; /* Reset unusual Firefox-on-Android default style; see https://github.com/necolas/normalize.css/issues/214*/
background-color: var(--button-color-primary);
position: relative;
font-weight: 600;
font-family: var(--button-base-font-family);
font-size: 14px;
color: var(--button-color-text);
border: 1px solid transparent;
text-decoration: none;
border-radius: 4px;
height: 40px;
line-height: 40px;
padding: 0 20px;
display: inline-block;
white-space: nowrap;
text-align: center;
/* Ghost button*/
&--ghost {
color: var(--button-color-primary);
border: solid 1px var(--button-color-primary);
background-color: transparent;
&:hover,
&:focus {
color: var(--button-color-text);
background-color: var(--button-color-primary);
}
}
&--large {
height: 50px;
padding: 0 40px;
font-size: 24px;
}
}The handlebars file is where the templating is happening. You can print out content directly from the context, or you can pass a property from your context into a pattern
<article class="box-image">
<div class="box-image__inner" style="background-image: url({{ boxImage.url }});">
<div class="box-image__content">
{{ render '@heading--column' header }}
<p>{{ boxImage.content }}</p>
</div>
</div>
</article>- _base
- 01-atoms
- 02-molecules
- 03-organisms
- 04-pages
All the global styles should be placed here. e.g. base and variables. don’t place component styling in here
Atoms are the most basic form of a pattern. e.g. a Title. Each atom can have multiple variants, that modifies the layout.
The context inside .config.json should contain fallback/default values.
Molecules can be a combination of multiple atoms or other molecules. e.g. Box. It should only contain the styling of the molecule, not the atoms. If a special atom styling is needed a new pattern should be created (or a variant of an existing one).
The context inside .config.json should contain component specific values, so the molecules can be rendered without any specific context.
Organisms can be a combination of multiple atoms or molecules. Organisms are used to declare specific layouts. Styling of organisms should rarely be used.
The context inside .config.json should contain layout specific values. It could be a specific list of links due to the layout
Page can be a combination of multiple atoms, molecules and organisms. Pages do NOT contain styling. Only use this to layout pages, not style them.
The context inside .config.json should not contain any values. Try to keep the context inside the organisms.
This renders the pattern NOTE: If the context of the current pattern matches the context of the rendered pattern. The rendered pattern will inherit.
This renders the pattern and overrides a specific property with a specific value. NOTE: If the context of the current pattern matches the context of the rendered pattern. The rendered pattern will inherit.
<!-- The pattern -->
<p class="paragraph {{ modifier }} {{ class }}">{{ text }}</p>
<!-- Override of the pattern -->
{{> @paragraph modifier="paragraph--hero" }}
<!-- Output -->
<p class="paragraph paragraph--hero} {{ class }}">{{ text }}</p>This renders the pattern with the inherited context
This renders the pattern with a context specified in the current pattern.
This embeds a pattern. By using the #block functionality you have the possibility to override default-content. e.g.
<!-- The pattern -->
<div class="grid-column">
{{#block "grid-column-content"}}
{{/block}}
</div>
<!-- Embed of the pattern -->
{{#embed '@grid-column'}}
{{#content 'grid-column-content'}}
Test
{{/content}}
{{/embed}}
<!-- Output -->
<div class="grid-column">
Test
</div>You can use this if you want to create a variant of a more complex pattern. Let’s say the grid.
<!-- The pattern -->
<div class="grid-container {{ containerClass }}">
{{#block "grid-container-content"}}
{{/block}}
</div>
<!-- Extend of the pattern -->
{{#extend "@grid-container" containerClass="grid-container--site-width"}}
{{#content "grid-container-content"}}
{{#block "content"}}
{{/block}}
{{/content}}
{{/extend}}