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 @@ ...@@ -291,6 +291,7 @@
</li> </li>
{% endif %} {% endif %}
{% endif %} {% endif %}
{% if section %} {% if section %}
{# don't show section link on a section #} {# don't show section link on a section #}
{# load section breadcrumbs from siteConfig.js #} {# load section breadcrumbs from siteConfig.js #}
...@@ -312,6 +313,14 @@ ...@@ -312,6 +313,14 @@
</li> </li>
{% endif %} {% endif %}
{% 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 #} {# Standard page title #}
<li class="vf-breadcrumbs__item" aria-current="location"> <li class="vf-breadcrumbs__item" aria-current="location">
{% if pagination.items[0].name %} {% if pagination.items[0].name %}
...@@ -326,13 +335,6 @@ ...@@ -326,13 +335,6 @@
{# Hero for sections #} {# Hero for sections #}
{% if section and is_index -%} {% 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 = { {%- set context = {
"spacing": 400, "spacing": 400,
"vf_hero_heading": siteConfig.sections[section].title, "vf_hero_heading": siteConfig.sections[section].title,
...@@ -345,29 +347,8 @@ ...@@ -345,29 +347,8 @@
-%} -%}
{# "modifier_class": "vf-component-library--hero", #} {# "modifier_class": "vf-component-library--hero", #}
{%- include "vf-core-components/vf-hero/vf-hero.njk" -%} {%- include "vf-core-components/vf-hero/vf-hero.njk" -%}
{% elseif section and (hideSectionNavigation != true) %} {% endif %}
{# 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 -%}
{% render '@vf-navigation', {
"classModifier": "main",
"navigation": navigationList
} %}
{%- endif %}
{{ content | safe }} {{ content | safe }}
......
...@@ -2,7 +2,6 @@ ...@@ -2,7 +2,6 @@
layout: layouts/base.njk layout: layouts/base.njk
pageClass: components pageClass: components
templateEngineOverride: njk templateEngineOverride: njk
hideSectionNavigation: true
--- ---
{% set component = pagination.items[0] %} {% set component = pagination.items[0] %}
{% set collectionComponents = component.items %} {% set collectionComponents = component.items %}
......
...@@ -2,7 +2,6 @@ ...@@ -2,7 +2,6 @@
title: Spacing and sizing title: Spacing and sizing
date: 2018-10-19 12:24:50 date: 2018-10-19 12:24:50
section: designtokens section: designtokens
hideSectionNavigation: true
templateEngineOverride: njk templateEngineOverride: njk
tags: tags:
- posts - posts
......
...@@ -3,7 +3,6 @@ title: Theme colours ...@@ -3,7 +3,6 @@ title: Theme colours
date: 2021-06-22 12:24:50 date: 2021-06-22 12:24:50
section: designtokens section: designtokens
templateEngineOverride: njk templateEngineOverride: njk
hideSectionNavigation: true
tags: tags:
- posts - posts
- sections - sections
......
...@@ -2,7 +2,6 @@ ...@@ -2,7 +2,6 @@
title: Type sizes title: Type sizes
date: 2021-06-22 12:24:50 date: 2021-06-22 12:24:50
section: designtokens section: designtokens
hideSectionNavigation: true
templateEngineOverride: njk templateEngineOverride: njk
tags: tags:
- posts - 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 ...@@ -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. 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 date: 2020-12-11 19:33:50
section: building section: building
full_width: true
tags: tags:
- posts - posts
- guidance - guidance
...@@ -12,52 +13,71 @@ layout: layouts/section.njk ...@@ -12,52 +13,71 @@ layout: layouts/section.njk
templateEngineOverride: njk, md templateEngineOverride: njk, md
--- ---
## Type 1: Components <section class="embl-grid embl-grid--has-centered-content">
{% render '@vf-section-header', {
Components are intended for re-use and should be named for what they are; that is: "section_title": "Type 1: Components",
"id": "components",
- vf-box (not "vf-introduction") "vf_section__content": [
- vf-button (not "vf-call-to-action") ""
- vf-grid (not "vf-wide-layout") ]
- vf-header (not "vf-big-headline") } %}
- vf-form <article class="vf-content">
This ensures that that a box will always be rectangular-ish pattern on pages, Components are intended for re-use and should be named for what they are; that is:
whereas an "introduction" may be a box today, but become simply large text after a redesign.
- vf-box (not "vf-introduction")
When naming components, use something simple and obvious. - vf-button (not "vf-call-to-action")
- vf-grid (not "vf-wide-layout")
### Component types - vf-header (not "vf-big-headline")
- vf-form
We use a variation of the atomic design methodology. We use: elements, blocks, and containers.
This ensures that that a box will always be rectangular-ish pattern on pages,
- `element`: a heading or button whereas an "introduction" may be a box today, but become simply large text after a redesign.
- `block`: a teaser, summary or search form
- `container`: would be a group of summaries When naming components, use something simple and obvious.
[More about the atomic design concept here](http://bradfrost.com/blog/post/atomic-web-design/#atoms). ### Component types
### Components have We use a variation of the atomic design methodology. We use: elements, blocks, and containers.
- Lots of code - `element`: a heading or button
- `CHANGELOG.md`: Notable changes - `block`: a teaser, summary or search form
- `index.scss`: Used to generate a standalone version of the component's CSS - `container`: would be a group of summaries
- `package.json`: Version information and any required npm dependencies
- you should avoid npm-requiring other VF components [More about VF component types](/guidance/components-and-patterns/)
- `README.md`: Information on the role and how to use a component
- `vf-sample.config.yml`: Configuration information about the compony, release status, type of component, variants ### Components have
- `vf-sample.njk`: A Nunjuck-based template
- `vf-sample.scss`: Styling - Lots of code
- `vf-sample.js`: JavaScript - `CHANGELOG.md`: Notable changes
- `vf-sample.react.js`: [React wrapper](https://github.com/visual-framework/vf-core/tree/develop/tools/vf-extensions-react#box-component) - `index.scss`: Used to generate a standalone version of the component's CSS
- `Dynamic files made at build time` - `package.json`: Version information and any required npm dependencies
- `_package.variables.scss_`: Variables extracted from package.json that can be used in the Sass, such as a version number - you should avoid npm-requiring other VF components
- `_vf-sample.precompiled.js_`: A compiled version of the Nunjucks template - `README.md`: Information on the role and how to use a component
- `_vf-sample.css_`: Standalone CSS made from the index.scss - `vf-sample.config.yml`: Configuration information about the compony, release status, type of component, variants
- An HTML code template (Nunjucks) - `vf-sample.njk`: A Nunjuck-based template
- Documentation on how to use - `vf-sample.scss`: Styling
- `vf-sample.js`: JavaScript
## Type 2: Patterns - `vf-sample.react.js`: [React wrapper](https://github.com/visual-framework/vf-core/tree/develop/tools/vf-extensions-react#box-component)
- `Dynamic files made at build time`
- `_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
</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, 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: give it a name that is attached to the role it performs; that is:
...@@ -75,10 +95,25 @@ and be large and italic text. ...@@ -75,10 +95,25 @@ and be large and italic text.
- An HTML code template (Nunjucks) - An HTML code template (Nunjucks)
- Documentation on how to use - 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). 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