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

tools/vf-component-library/src/site/_includes/layouts/base.njk

@@ -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 }}
 

tools/vf-component-library/src/site/_includes/layouts/components.njk

@@ -2,7 +2,6 @@
 layout: layouts/base.njk
 pageClass: components
 templateEngineOverride: njk
-hideSectionNavigation: true
 ---
 {% set component = pagination.items[0] %}
 {% set collectionComponents = component.items %}

tools/vf-component-library/src/site/design-tokens/spacing.njk

@@ -2,7 +2,6 @@
 title: Spacing and sizing
 date: 2018-10-19 12:24:50
 section: designtokens
-hideSectionNavigation: true
 templateEngineOverride: njk
 tags:
   - posts

tools/vf-component-library/src/site/design-tokens/theming.njk

@@ -3,7 +3,6 @@ title: Theme colours
 date: 2021-06-22 12:24:50
 section: designtokens
 templateEngineOverride: njk
-hideSectionNavigation: true
 tags:
   - posts
   - sections

tools/vf-component-library/src/site/design-tokens/typography.njk

@@ -2,7 +2,6 @@
 title: Type sizes
 date: 2021-06-22 12:24:50
 section: designtokens
-hideSectionNavigation: true
 templateEngineOverride: njk
 tags:
   - posts

tools/vf-component-library/src/site/guidance/component-types.md

+---
+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>

tools/vf-component-library/src/site/guidance/components-and-patterns.md

@@ -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,52 +13,71 @@ layout: layouts/section.njk
 templateEngineOverride: njk, md
 ---
 
-## Type 1: Components
-
-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
-
-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.
-
-### Component types
-
-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
-
-[More about the atomic design concept here](http://bradfrost.com/blog/post/atomic-web-design/#atoms).
-
-### Components have
-
-- 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
-    - you should avoid npm-requiring other VF components
-  - `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
-  - `vf-sample.njk`: A Nunjuck-based template
-  - `vf-sample.scss`: Styling
-  - `vf-sample.js`: JavaScript
-  - `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
-
-## Type 2: Patterns
+<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:
+
+  - 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.
+
+  When naming components, use something simple and obvious.
+
+  ### Component types
+
+  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
+
+  [More about VF component types](/guidance/components-and-patterns/)
+
+  ### Components have
+
+  - 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
+      - you should avoid npm-requiring other VF components
+    - `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
+    - `vf-sample.njk`: A Nunjuck-based template
+    - `vf-sample.scss`: Styling
+    - `vf-sample.js`: JavaScript
+    - `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,
 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>