Commit f31c1371 authored by Ken Hawkins's avatar Ken Hawkins
Browse files

Docs: Use breadcrumbs more consistently, build out component type guidance

parent 88644154
Pipeline #217401 passed with stages
in 8 minutes
......@@ -291,6 +291,7 @@
</li>
{% endif %}
{% endif %}
{% if section %}
{# don't show section link on a section #}
{# load section breadcrumbs from siteConfig.js #}
......@@ -312,6 +313,14 @@
</li>
{% endif %}
{% endif %}
{# Guidance section #}
{% if tags %}
{% if 'guidance' in tags %}
<li class="vf-breadcrumbs__item">
<a href="{{ '/guidance' | url }}" class="vf-breadcrumbs__link">Guidance and principles</a>
</li>
{% endif %}
{% endif %}
{# Standard page title #}
<li class="vf-breadcrumbs__item" aria-current="location">
{% if pagination.items[0].name %}
......@@ -326,13 +335,6 @@
{# Hero for sections #}
{% if section and is_index -%}
{# <style>
.vf-hero.vf-component-library--hero {
--vf-hero--bg-image:
url("https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/roundels.png"),
url("https://acxngcvroo.cloudimg.io/v7/https://www.embl.org/files/wp-content/uploads/20201202_hero_emblorg_homepage-zoom-out.jpg")
}
</style> #}
{%- set context = {
"spacing": 400,
"vf_hero_heading": siteConfig.sections[section].title,
......@@ -345,29 +347,8 @@
-%}
{# "modifier_class": "vf-component-library--hero", #}
{%- include "vf-core-components/vf-hero/vf-hero.njk" -%}
{% elseif section and (hideSectionNavigation != true) %}
{# Render sub nav for sections #}
{%- set navigationList = [] -%}
{%- for entry in collections[section] | sort(false, true, 'data.order') %}
{%- if entry.data.layout and (entry.data.is_index != true) %}
{%- set isCurrent = false -%}
{%- if entry.url == page.url %}
{%- set isCurrent = true -%}
{%- endif %}
{% set navigationList = (navigationList.push({
"text": entry.data.title,
"order": entry.data.order,
"navigation_href": entry.url | url,
"currentPage": isCurrent
}),navigationList) %}
{%- endif %}
{%- endfor -%}
{% endif %}
{% render '@vf-navigation', {
"classModifier": "main",
"navigation": navigationList
} %}
{%- endif %}
{{ content | safe }}
......
......@@ -2,7 +2,6 @@
layout: layouts/base.njk
pageClass: components
templateEngineOverride: njk
hideSectionNavigation: true
---
{% set component = pagination.items[0] %}
{% set collectionComponents = component.items %}
......
......@@ -2,7 +2,6 @@
title: Spacing and sizing
date: 2018-10-19 12:24:50
section: designtokens
hideSectionNavigation: true
templateEngineOverride: njk
tags:
- posts
......
......@@ -3,7 +3,6 @@ title: Theme colours
date: 2021-06-22 12:24:50
section: designtokens
templateEngineOverride: njk
hideSectionNavigation: true
tags:
- posts
- sections
......
......@@ -2,7 +2,6 @@
title: Type sizes
date: 2021-06-22 12:24:50
section: designtokens
hideSectionNavigation: true
templateEngineOverride: njk
tags:
- posts
......
---
title: Component types
subtitle: "We use a variation of the atomic design methodology: elements, blocks, and containers."
intro: "In addition to these three <a href='http://bradfrost.com/blog/post/atomic-web-design/#atoms'>atomic concepts</a> you'll also see utilities and layout components."
date: 2021-11-26 19:33:50
section: building
full_width: true
tags:
- posts
- guidance
- components
layout: layouts/section.njk
templateEngineOverride: njk, md
---
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Design tokens",
"id": "tokens",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
All components in the Visual Framework are dependent on [its design tokens](/design-tokens/) that provide colour, typography, spacing and other stylistic decisions as structured data.
</article>
</section>
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Elements",
"id": "elements",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
Elements are the basic building blocks of the Visual Framework and includes buttons, badges, headings, text, links and so on. Every higher level component is made of these.
</article>
</section>
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Blocks",
"id": "blocks",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
Utilising elements along with their own styling, blocks begin to make ready-made parts of a page, such as navigation, summary, profiles, card or a search form.
With these you can begin to imagine a page, but they do not provide structure between blocks.
</article>
</section>
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Containers",
"id": "containers",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
Moving up from blocks, containers assemble collections of blocks in layout containers that can be stacked to build a page: a hero, banner, intro, video container and so on.
</article>
</section>
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Utility and layout",
"id": "utility",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
Giving structure and function to the fabric of the page, layout components determine reusable structure in grids, stacking layout and reusable clusters and flags.
These are supported by utility components (utility classes, smooth scroll, show more) that allow edge customisations and behaviour of the page.
</article>
</section>
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Learn more",
"id": "more",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
- [How to make a component](/guidance/creating-components/)
- [Components vs patterns](/guidance/components-and-patterns/)
</article>
</section>
......@@ -4,6 +4,7 @@ subtitle: Think of components as lego blocks you can use to build the look and c
intro: At the lower level there are components which are a type of "ingredient" used to assemble into the higher level patterns with richer templates with usability guidance.
date: 2020-12-11 19:33:50
section: building
full_width: true
tags:
- posts
- guidance
......@@ -12,34 +13,42 @@ layout: layouts/section.njk
templateEngineOverride: njk, md
---
## Type 1: Components
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Type 1: Components",
"id": "components",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
Components are intended for re-use and should be named for what they are; that is:
Components are intended for re-use and should be named for what they are; that is:
- vf-box (not "vf-introduction")
- vf-button (not "vf-call-to-action")
- vf-grid (not "vf-wide-layout")
- vf-header (not "vf-big-headline")
- vf-form
- vf-box (not "vf-introduction")
- vf-button (not "vf-call-to-action")
- vf-grid (not "vf-wide-layout")
- vf-header (not "vf-big-headline")
- vf-form
This ensures that that a box will always be rectangular-ish pattern on pages,
whereas an "introduction" may be a box today, but become simply large text after a redesign.
This ensures that that a box will always be rectangular-ish pattern on pages,
whereas an "introduction" may be a box today, but become simply large text after a redesign.
When naming components, use something simple and obvious.
When naming components, use something simple and obvious.
### Component types
### Component types
We use a variation of the atomic design methodology. We use: elements, blocks, and containers.
We use a variation of the atomic design methodology. We use: elements, blocks, and containers.
- `element`: a heading or button
- `block`: a teaser, summary or search form
- `container`: would be a group of summaries
- `element`: a heading or button
- `block`: a teaser, summary or search form
- `container`: would be a group of summaries
[More about the atomic design concept here](http://bradfrost.com/blog/post/atomic-web-design/#atoms).
[More about VF component types](/guidance/components-and-patterns/)
### Components have
### Components have
- Lots of code
- Lots of code
- `CHANGELOG.md`: Notable changes
- `index.scss`: Used to generate a standalone version of the component's CSS
- `package.json`: Version information and any required npm dependencies
......@@ -54,10 +63,21 @@ We use a variation of the atomic design methodology. We use: elements, blocks, a
- `_package.variables.scss_`: Variables extracted from package.json that can be used in the Sass, such as a version number
- `_vf-sample.precompiled.js_`: A compiled version of the Nunjucks template
- `_vf-sample.css_`: Standalone CSS made from the index.scss
- An HTML code template (Nunjucks)
- Documentation on how to use
## Type 2: Patterns
- An HTML code template (Nunjucks)
- Documentation on how to use
</article>
</section>
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Type 2: Patterns",
"id": "patterns",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
If your pattern is primarily intended to be used for particular websites or a brand,
give it a name that is attached to the role it performs; that is:
......@@ -75,10 +95,25 @@ and be large and italic text.
- An HTML code template (Nunjucks)
- Documentation on how to use
## Learn more
</article>
</section>
<section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
"section_title": "Learn more",
"id": "more",
"vf_section__content": [
""
]
} %}
<article class="vf-content">
For further guidance on the distinctions, see: [Patterns ≠ Components](https://medium.com/eightshapes-llc/patterns-components-2ce778cbe4e8) and UK.gov's information on [patterns](https://design-system.service.gov.uk/patterns) vs [components](https://design-system.service.gov.uk/components).
<hr/>
And see these VF guidance entries:
- [How to make a component](/guidance/creating-components/)
- [Components types](/guidance/component-types/)
{% include "component-docs.njk" %}
</article>
</section>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment