Documentation: General updates

src/site/developing/components/creating-new-components.njk

@@ -1,8 +1,8 @@
 ---
 title: Creating a new component
 subtitle: This codebase includes a folder and file creation tool. 
-intro: It allows you to quickly create all the required files to make a component -- it gives you the option to create am element, block, or container.
-date: 2019-04-09 12:24:50
+intro: It allows you to quickly create all the required files to make a component — it gives you the option to create am element, block, or container.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 order: 1
 ---
@@ -27,14 +27,14 @@ order: 1
 1. Sharing you component back
    - Publish it to npm; and/or
    - If you think your component is useful to the global `vf-core` community, [make a Pull Request](https://github.com/visual-framework/vf-core/pulls) or [open an issue](https://github.com/visual-framework/vf-core/issues/new/choose) to discuss.
-
- <div class="vf-box">
- Tip: also consult the [guidelines]({{ '/developing/guidelines' | url }}) for the naming of things and coding standards.
- </div>
+   - Tip: also consult the [guidelines]({{ '/developing/guidelines' | url }}) for the naming of things and coding standards and [governance]({{ '/developing/guidelines/governance/' | url }}).
 
  ## Language and spelling of documentation, code
 
  The `vf-core` project is being led by EMBL where British English and we're aware that most code is American English (`colour` vs `color`); so:
 
- - 📚🇬🇧 Documentation is written in British English 💂‍ `Rarely use centred text, always use colours`
- - ⌨️🇺🇸 Code is written in American english 🧢 `$vf-main-color: green;`
+ - 📚🇬🇧 Documentation is written in British English 💂‍ 
+   > Rarely use centred text, always use colours
+ - ⌨️🇺🇸 Code is written in American english 🧢
+   > `$vf-main-color: green;`
+

src/site/developing/components/what-is-a-component.njk

@@ -1,8 +1,8 @@
 ---
-title: What's a component
-subtitle: Components are a modular set of extendable Sass/CSS styling, JavaScript and templating (Nunjucks). 
-intro: Think of components as lego blocks you can use to build the look, behaviour and content of your sites.
-date: 2019-04-09 12:24:49
+title: What is a component
+subtitle: Think of components as lego blocks you can use to build the look, behaviour and content of your sites.
+intro: Components are a modular set of extendable Sass/CSS styling, JavaScript and [Nunjucks templating](https://mozilla.github.io/nunjucks/). 
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 templateEngineOverride: njk, md
 order: 1
@@ -12,24 +12,26 @@ order: 1
 
 A component is made up of these files:
 
-- CHANGELOG.md
+- [CHANGELOG.md](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - Notable changes
-- index.scss
+- [index.scss](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - Used to generate a standalone version of the component's CSS
-- package.json
+- [package.json](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - Version information and any npm required dependencies; you should avoid npm-requiring other VF components
-- README.md
+- [README.md](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - Information on the role and how to use a component
-- vf-sample.config.yml
+- [vf-sample.config.yml](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - Configuration information about the compont, release status, type of component, variants
-- vf-sample.njk
+- [vf-sample.njk](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - A Nunjuck-based template
-- vf-sample.scss
+- [vf-sample.scss](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - Styling
-- vf-sample.js
+- [vf-sample.js](https://github.com/visual-framework/vf-core/tree/develop/tools/component-generator/templates)
   - JavaScript
 
-## Some files will also be dynamically made at build time
+### Dynamic files
+
+Some files will also be dynamically made at build time:
 
 - _package.variables.scss_
   - Varaibles extratcted from pacakge.json that can be used in the Sass, such as a version number
@@ -38,3 +40,13 @@ A component is made up of these files:
 - _vf-sample.css_
   - Standoline CSS made from the index.scss
 
+<div class="vf-box vf-box--inlay">
+{% markdown %}
+
+## What goes in `vf-core`?
+
+Components can be made and used for local projects or [contribute it back to `vf-core`]({{ '/developing/guidelines/governance/' | url }}). 
+
+{% endmarkdown %}
+</div>
+

src/site/developing/getting-started/code-of-conduct.njk

@@ -1,9 +1,8 @@
 ---
 title: Code of conduct
-date: 2019-04-09 12:24:50
+subtitle: "We don't yet have a full policy but, in general: be nice, respectful and considerate. The maintainers will do the same."
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 order: 4
 ---
 
-We don't yet have a full policy but, in general: be nice, respectful
-and considerate. The maintainers will do the same.

src/site/developing/getting-started/naming.njk

@@ -1,8 +1,8 @@
 ---
-title: Naming things
+title: "Naming things: components and patterns"
 subtitle: The Visual Framework uses a dual approach for the naming of things.
 intro: At the lower level there are **components** which are a type of "ingredient" used to assembl into the higher level **patterns** that are richer templates with usability guidance.
-date: 2019-04-09 12:24:50
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 order: 4
 ---
@@ -42,11 +42,9 @@ and be large and italic text.
 
 ### Patterns have
 
-- Lots of code
-    - Generally that CSS/Sass and some JS
+- Less code
 - An HTML code template (Nunjucks)
-- Documentation on how to use
-
+- Lots of guidance on how to use
 
 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).

src/site/developing/getting-started/pull-requests.njk

@@ -1,26 +1,27 @@
 ---
-title: Making your first Pull Request
-date: 2019-04-09 12:24:50
+title: "Contributing: making Pull Requests"
+subtitle: To contribute code back, you'll need to make a PR ([Pull Request](https://help.github.com/en/articles/about-pull-requests)).
+intro: This is a more user-friendly feature of GitHub that allows you to contribute to `vf-core` without direct write access.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 order: 5
 ---
 
-To contribute code back, you'll need to make a PR ([Pull Request](https://help.github.com/en/articles/about-pull-requests)),
-as you won't have write access, GitHub will prompt you to fork the `vf-core` repository
-and then you'll be able to push your branch and open a pull request.
-
 ## What?
 
 If you're thoroughly confused, here are a few helpful links:
 
 - [About branches](https://help.github.com/en/articles/about-branches)
 - [Making a fork and pull request](https://www.youtube.com/watch?v=rgbCcBNZcdQ) (video)
-
+- If you get stuck, just make [a normal issue in GitHub](https://github.com/visual-framework/vf-core/issues/new/choose) or [chat us](https://join.slack.com/t/visual-framework/shared_invite/enQtNDAxNzY0NDg4NTY0LWFhMjEwNGY3ZTk3NWYxNWVjOWQ1ZWE4YjViZmY1YjBkMDQxMTNlNjQ0N2ZiMTQ1ZTZiMGM4NjU5Y2E0MjM3ZGQ).
 
 ## Branch naming conventions
 
-In general `type/brief-description-of-branch`, example: `component/advanced-search`,
-or `fix/grid-breaks-on-ios`
+- The typical format is:
+  - `{type}/{brief-description-of-branch}`
+- examples: 
+  - `component/advanced-search`
+  - `fix/grid-breaks-on-ios`
 
 Here are the most common `type`s:
 

src/site/developing/getting-started/setting-up.njk

@@ -1,12 +1,11 @@
 ---
 title: Setting up your development environment
-date: 2019-04-09 12:24:50
+subtitle: To develop the Visual Framework your will need some software.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 order: 3
 ---
 
-To develop the Visual Framework your will need some software.
-
 ## Development environment
 
 If you don't already have a code editor and are new to git, a good starting point is to:

src/site/developing/getting-started/structure.njk

@@ -1,20 +1,11 @@
 ---
-title: Structure of the Visual Framework core
-date: 2019-04-09 12:24:50
+title: File structure of the Visual Framework core
+subtitle: A map to the most important files and directories.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 order: 2
 ---
 
-## Design decisions and tokens
-
-The Visual Framework uses the [Design Token concept](https://medium.com/eightshapes-llc/tokens-in-design-systems-25dd82d58421) to specify design (colour, spacing, type) as reusable JSON or YAML that are translated from `.yml` data into `.scss` using [Theo](https://github.com/salesforce-ux/theo#-theo).
-
-This Design Token abstraction [helps portability and integration](https://uxdesign.cc/design-tokens-for-dummies-8acebf010d71) with other technical systems.
-
-You can find the Design Tokens in `vf-core/components/vf-design-tokens`.
-
-## File structure
-
 {# Tree map generated with
    tree -L 2 . -I 'node_modules|cache|test_*|.git|.github|bin' -a
 #}

src/site/developing/guidelines/css.njk

@@ -1,6 +1,7 @@
 ---
 title: Sass and CSS guidelines
-date: 2019-04-09 12:24:50
+subtitle: The Visual Framework uses [Sass](https://sass-lang.com/) to build its CSS, here are some conventions to follow for both your Sass and CSS approaches.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 ---
 
@@ -198,4 +199,4 @@ Your code editor can help you find these when mopping up before a project goes l
 
 ## Related: Building your first Visual Framework page
 
-If you're looking for some hands-on help with Visual Framework syntax, [see this blog post on a quick start](https://work.allaboutken.com/posts/20191118-first-page-with-the-visual-framework.html) on how to work with Visual Framework 2.0 CSS, JS and structure your HTML.
+If you're looking for some hands-on help with Visual Framework syntax, [see this blog post on a quick start](https://work.allaboutken.com/posts/20191118-first-page-with-the-visual-framework.html) on how to work with Visual Framework 2.0 CSS, JS and structure your HTML.

src/site/developing/guidelines/design-tokens.njk

@@ -0,0 +1,17 @@
+---
+title: Design tokens and  decisions
+subtitle: The Visual Framework uses the [Design Token concept](https://medium.com/eightshapes-llc/tokens-in-design-systems-25dd82d58421) to specify design (colour, spacing, type) as reusable JSON or YAML that are translated from `.yml` data into `.scss` using [Theo](https://github.com/salesforce-ux/theo#-theo).
+date: 2020-01-13 12:24:50
+layout: layouts/developing.njk
+---
+
+This Design Token abstraction [helps portability and integration](https://uxdesign.cc/design-tokens-for-dummies-8acebf010d71) with other technical systems.
+
+> Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.
+> [<cite>— Salesforce, Lightning Design System.</cite>](https://www.lightningdesignsystem.com/design-tokens/)
+
+The Design Tokens used within `vf-core` are generated from several `.yml` files. These are then compiled into various Sass files as needed. You can find the Design Tokens in [`vf-core/components/vf-design-tokens`](https://github.com/visual-framework/vf-core/tree/develop/components/vf-design-tokens).
+
+In the future we hope to offer Sketch and Photoshop colour palettes.
+
+If you required a different format (LESS, iOS, Android). Please get in touch.

src/site/developing/guidelines/governance.njk

@@ -1,12 +1,11 @@
 ---
 title: Governance of the Visual Framework
-date: 2019-04-09 12:24:50
+subtitle: The Visual Framework 2.0 is an open source project meant for the wider life science community, so the maintainers aim to be transparent about what goes in `vf-core`, what doesn't and why decisions are made.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 ---
 
-The Visual Framework 2.0 is an open source project meant for the wider life
-science community, so the maintainers aim to be transparent about what goes in
-`vf-core`, what doesn't and why decisions are made.
+
 
 The guiding spirit of the Visual Framework can be summed up as:
 
@@ -47,8 +46,7 @@ In spirit, "the community" but in practice that falls to the maintainers and
 those asking for change.
 
 Who are the maintainers? Currently (as of April 2019) it's limited to EMBL and
-EMBL-EBI developers, but we aim to expand this into a consultative group after
-`beta.1` in late spring/summer 2019.
+EMBL-EBI developers, but we aim to expand this into a consultative group in 2020.
 
 ## The decision process
 

src/site/developing/guidelines/javascript.njk

@@ -1,13 +1,12 @@
 ---
 title: JavaScript guidelines
-date: 2019-04-09 12:24:50
+subtitle: The Visual Framework isn't intended as a general-purpose JavaScript solution, however we know it is helpful that a minimal amount of basic functionality is supported.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 ---
 
 ## Just enough JavaScript
 
-The Visual Framework isn't intended as a general-purpose JavaScript solution, however we know it is helpful that a minimal amount of basic functionality is supported.
-
 All components are provided as functional solutions, so where JavaScript is required (such as [tabs](https://github.com/visual-framework/vf-core/tree/develop/components/vf-tabs)) there is a fully functional set of JavaScript bundled and available in:
 
 - [`vf-tabs.js`](https://github.com/visual-framework/vf-core/blob/develop/components/vf-tabs/vf-tabs.js) and

src/site/developing/guidelines/user-base.njk

@@ -1,13 +1,10 @@
 ---
 title: User base and needs
-date: 2019-04-09 12:24:50
+subtitle: The Visual Framework core ([`vf-core`](https://github.com/visual-framework/vf-core)) is not intended for direct consumption into websites as prebuilt CSS and JS, rather it's a component library that should be installed as an npm and Sass dependency to build design systems.
+date: 2020-01-13 12:24:50
 layout: layouts/developing.njk
 ---
 
-The Visual Framework core ('vf-core') is not intended for direct consumption into
-websites, rather it's a component library that should be installed as an npm and
-Sass dependency to build design systems.
-
 ## Common needs
 
 For all supported audiences, we work to address shared needs:
@@ -25,7 +22,7 @@ For all supported audiences, we work to address shared needs:
 
 Our target audience sits in three layers:
 
-1. Maintainers of design systems for life science websites <span class="vf-badge vf-badge--tertiary">Primary</span>
+1. Maintainers of design systems for life science websites 
     - needs:
        - create a design system that utilises the `vf-core`
        - add a vf-core component to an existing vf-core compatible system