Unverified Commit 20bfcd73 authored by Ken Hawkins's avatar Ken Hawkins Committed by GitHub

Docs: getting started the VF's npm components (#1247)

parent 33dd9b0c
const { DateTime } = require('luxon');
const { DateTime } = require("luxon");
// Some various reusable configuration
module.exports = {
siteInformation: {
title: "The Visual Framework 2.0",
short_description: 'A front-end toolkit to quickly build better life science websites.',
short_description: "A front-end toolkit to quickly build better life science websites.",
url: "https://stable.visual-framework.dev/",
author: "Visual Framework system",
email: "ken.hawkins@embl.de",
},
buildTime: DateTime.fromISO(new Date().toISOString()),
// vfVersion: global.vfVersion,
vfVersion: 'v2.3.3-rc.3',
vfVersion: "v2.3.3-rc.3",
sections: {
about: {
url: '/about',
title: 'About'
url: "/about",
title: "About"
},
designtokens: {
url: "/design-tokens",
title: "Design tokens"
},
guidelines: {
url: '/guidelines',
title: 'Guidelines'
url: "/guidelines",
title: "Guidelines"
},
developing: {
url: "/developing",
title: "Developing"
},
patterns: {
url: '/patterns',
title: 'Patterns'
url: "/patterns",
title: "Patterns"
},
styles: {
url: '/styles',
title: 'Styles'
url: "/styles",
title: "Styles"
},
components: {
url: '/components',
title: 'Components'
url: "/components",
title: "Components"
}
}
};
......@@ -51,7 +51,7 @@
{% render '@vf-logo', {logo_href: '/' | url, sreen_reader_text: 'Visual Framework 2.0', image: siteConfig.siteInformation.url + 'assets/vf-logo/assets/logo.svg', "hidden_text": true } %}
<nav class="vf-navigation vf-navigation--global">
<ul class="vf-navigation__list | vf-list--inline">
<li class="vf-navigation__item">
{# <li class="vf-navigation__item">
<a href="{{ '/about' | url }}" class="vf-navigation__link">About</a>
</li>
<li class="vf-navigation__item">
......@@ -59,12 +59,15 @@
</li>
<li class="vf-navigation__item">
<a href="{{ '/patterns' | url }}" class="vf-navigation__link">Examples</a>
</li>
</li> #}
<li class="vf-navigation__item">
<a href="{{ '/search' | url }}" class="vf-navigation__link">Search</a>
</li>
<li class="vf-navigation__item">
<a href="https://join.slack.com/t/visual-framework/shared_invite/enQtNDAxNzY0NDg4NTY0LWFhMjEwNGY3ZTk3NWYxNWVjOWQ1ZWE4YjViZmY1YjBkMDQxMTNlNjQ0N2ZiMTQ1ZTZiMGM4NjU5Y2E0MjM3ZGQ" class="vf-navigation__link">Help, chat</a>
<a href="https://github.com/visual-framework/vf-core" class="vf-navigation__link">GitHub</a>
</li>
<li class="vf-navigation__item">
<a href="https://join.slack.com/t/visual-framework/shared_invite/enQtNDAxNzY0NDg4NTY0LWFhMjEwNGY3ZTk3NWYxNWVjOWQ1ZWE4YjViZmY1YjBkMDQxMTNlNjQ0N2ZiMTQ1ZTZiMGM4NjU5Y2E0MjM3ZGQ" class="vf-navigation__link">Slack</a>
</li>
</ul>
</nav>
......
---
layout: layouts/base.njk
pageClass: developing
templateEngineOverride: njk, md
---
<section class="vf-intro | embl-grid embl-grid--has-centered-content">
<div></div>
<div>
<h1 class="vf-intro__heading">{{title}}</h1>
{% if subtitle %}
<div class="vf-lede">{{subtitle | markdown | safe | replace("<p>", "<span class='vf-content'>") | replace("</p>", "</span>") }}</div>
{% endif %}
{% if intro %}
<div class="vf-intro__text">{{intro | markdown | safe | replace("<p>", "<span class='vf-content'>") | replace("</p>", "</span>") }}</div>
{% endif %}
</div>
</section>
<main class="vf-content | embl-grid embl-grid--has-centered-content">
<div></div>
<div>
{{ content | safe }}
<cite class="vf-cite">
Last updated on <time datetime="{{ date }}">{{ date | dateDisplay }}</time>
</cite>
</div>
</main>
<!-- layout: layouts/developing.njk -->
......@@ -25,7 +25,7 @@ templateEngineOverride: njk, md
{%- endif %}
{# See if a section has subposts. #}
{# Unfortunately there's not a more elegent way to see how many posts there are with a data attribute without adding 11ty config overhead #}
{# Unfortunately there's not a more elegant way to see how many posts there are with a data attribute without adding 11ty config overhead #}
{% set sectionHasSubposts = false %}
{%- for post in collections.posts %}
{% if section == post.data.section %}
......
---
layout: layouts/base.njk
pageClass: posts
templateEngineOverride: njk, md
---
{# Use this template for main tokens of a site. #}
<h1 class="vf-intro__heading" style="margin-bottom: 0 !important;">{{ title }}</h1>
<p class="vf-lede">{{ subtitle }}</p>
<nav class="vf-navigation vf-navigation--main">
<ul class="vf-navigation__list | vf-list--inline">
<li class="vf-navigation__item">
<a href="{{ '/design-tokens/' | url}}"class="vf-navigation__link">Overview</a>
</li>
<li class="vf-navigation__item">
<a href="{{ '/design-tokens/theming' | url}}" class="vf-navigation__link">Theming</a>
</li>
<li class="vf-navigation__item">
<a href="{{ '/design-tokens/colours' | url}}" class="vf-navigation__link">Colours</a>
</li>
<li class="vf-navigation__item">
<a href="{{ '/design-tokens/spacing' | url}}" class="vf-navigation__link">Spacing</a>
</li>
<li class="vf-navigation__item">
<a href="{{ '/design-tokens/typography' | url}}" class="vf-navigation__link">Typography</a>
</li>
<li class="vf-navigation__item">
<a href="{{ '/design-tokens/breakpoints' | url}}" class="vf-navigation__link">Breakpoints</a>
</li>
</ul>
</nav>
{%- if content | length > 1 -%}
{{ content | safe }}
{%- endif %}
......@@ -25,7 +25,7 @@ It's also a good introduction into integrating VF components into an application
## A pre-made boilerplate using VF components
Uses the performant [11ty](https://www.11ty.io/) as a static site generator to build sites with VF components. This approach pre-integrates the VF Core, giving you easy access to component assets and a rollup build process to generate compiled CSS and JS.
Uses the preferment [11ty](https://www.11ty.io/) as a static site generator to build sites with VF components. This approach pre-integrates the VF Core, giving you easy access to component assets and a rollup build process to generate compiled CSS and JS.
[`vf-eleventy` boilerplate](https://github.com/visual-framework/vf-eleventy)
......@@ -59,6 +59,6 @@ A demonstration React-based project using VF components.
The most basic use of the Visual Framework components allows usage directly into your existing build environment. This approach gets you a components Sass, JS, template and any other assets and lets you build what you need.
This approach is recommended for more advanced developers who are highly familar with Node and Sass.
This approach is recommended for more advanced developers who are highly familiar with Node and Sass.
- `yarn add @visual-framework/vf-sass-config @visual-framework/vf-inlay`
---
is_index: true
title: Component overview
title: Component list
subtitle: These components are available.
date: 2019-04-09 12:24:50
section: components
......
---
is_index: true
title: Design Tokens
subtitle: Breakpoints
title: Breakpoints
date: 2018-10-19 12:24:50
section: components
section: designtokens
templateEngineOverride: njk
layout: layouts/tokens.njk
hideSubPosts: true
tags:
- posts
- sections
- designtokens
layout: layouts/base.njk
---
<h1 class="vf-intro__heading">{{ title }}</h1>
<main class="vf-grid vf-grid__col-3">
{% for item in tokens.breakpoints.properties %}
......
---
is_index: true
title: Design Tokens
subtitle: Colours
title: Colours
date: 2018-10-19 12:24:50
section: components
section: designtokens
templateEngineOverride: njk
layout: layouts/tokens.njk
hideSubPosts: true
tags:
- posts
- sections
- designtokens
layout: layouts/base.njk
---
<h1 class="vf-intro__heading">{{ title }}</h1>
<main class="vf-grid vf-grid__col-3">
{% for item in tokens.colours.properties %}
......
---
is_index: true
title: Design Tokens
subtitle: The colour, typography, spacing, and other stylistic decisions as design tokens for consumption.
date: 2018-10-16 12:24:50
section: components
tags: sections
section: designtokens
tags:
- sections
- designtokens
templateEngineOverride: njk
layout: layouts/tokens.njk
hideSubPosts: true
layout: layouts/section.njk
hideSubPosts: false
---
<article class="vf-content">
{% markdown %}
These are the colour, typography, spacing, and other stylistic decisions as design tokens for consumption
The Design Tokens used within `vf-core` are generated from several `.yml` files. These are then compiled into various Sass files as needed.
In the future we hope to offer Sketch and Photoshop colour palettes.
......@@ -27,6 +25,3 @@ If you required a different format (LESS, iOS, Android). Please get in touch.
## Building
To update these run `gulp vf-tokens` from `./components/vf-design-tokens`.
{% endmarkdown %}
</article>
---
is_index: true
title: Design Tokens
subtitle: Spacing
title: Spacing
date: 2018-10-19 12:24:50
section: components
section: designtokens
templateEngineOverride: njk
layout: layouts/tokens.njk
hideSubPosts: true
tags:
- posts
- sections
- designtokens
layout: layouts/base.njk
---
<h1 class="vf-intro__heading">{{ title }}</h1>
<main class="vf-grid vf-grid__col-3">
{% for item in tokens.spacing.properties %}
<article class="vf-card">
......
---
is_index: true
title: Design Tokens
subtitle: Theming
title: Theming
date: 2018-10-19 12:24:50
section: components
section: designtokens
templateEngineOverride: njk
layout: layouts/tokens.njk
hideSubPosts: true
tags:
- posts
- sections
- designtokens
layout: layouts/base.njk
---
<h1 class="vf-intro__heading">{{ title }}</h1>
<main class="vf-grid vf-grid__col-3">
......
---
is_index: true
title: Design Tokens
subtitle: Typography
title: Typography
date: 2018-10-19 12:24:50
section: components
section: designtokens
templateEngineOverride: njk
layout: layouts/tokens.njk
hideSubPosts: true
tags:
- posts
- sections
- designtokens
layout: layouts/base.njk
---
<h1 class="vf-intro__heading">{{ title }}</h1>
<main class="vf-grid vf-grid__col-3">
{% for item in tokens.typographySans.properties %}
......
{
"tags": ["documentation", "contributing components", "posts"]}
......@@ -3,8 +3,13 @@ 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
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 1
tags:
- contributing components
- developing
- documentation
---
1. Install Yeoman
......
---
title: Deprecating components
subtitle: Inevitably code will be replaced and improved, leaving components stale and or outdated.
subtitle: Inevitably code will be replaced and improved, leaving components stale and or outdated.
intro: So we should tell developers to not use them.
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 3
tags:
- contributing components
- developing
- documentation
---
Here's what we need to make sure we do:
......
......@@ -3,8 +3,13 @@ title: Updating, versioning a component
subtitle: "Like the Visual Framework 2.0, components follow [semantic versioning](https://semver.org/) by increasing their full version number every time they have breaking changes."
intro: "However the version number of components its not tied to the version number of the Visual Framework's `vf-core`; that is:"
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 2
tags:
- contributing components
- developing
- documentation
---
- `vf-core​@2.1.2` might use `vf-button​@1.0.1` and `vf-component-x​@8.2.1`
......
---
title: What's a component
subtitle: Components are a modular set of extendable Sass/CSS styling, JavaScript and templating (Nunjucks).
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
layout: layouts/developing.njk
layout: layouts/section.njk
templateEngineOverride: njk, md
section: developing
order: 1
tags:
- contributing components
- developing
- documentation
---
## What's in a component?
......
---
title: Code of conduct
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 4
tags:
- getting started
- developing
- documentation
---
We don't yet have a full policy but, in general: be nice, respectful
......
......@@ -3,8 +3,13 @@ title: Naming things
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
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 4
tags:
- getting started
- developing
- documentation
---
## Type 1: Components
......
---
title: Making your first Pull Request
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 5
tags:
- getting started
- developing
- documentation
---
To contribute code back, you'll need to make a PR ([Pull Request](https://help.github.com/en/articles/about-pull-requests)),
......
......@@ -2,8 +2,13 @@
title: Setting up your development environment
subtitle: To develop the Visual Framework your will need some free software.
date: 2020-03-18 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 3
tags:
- getting started
- developing
- documentation
---
## Development tools
......
---
title: Structure of the Visual Framework core
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 2
tags:
- getting started
- developing
- documentation
---
## Design decisions and tokens
......
---
is_index: true
title: Sass and CSS guidelines
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 10
tags:
- guidelines
- developing
- documentation
---
## CSS Naming conventions
......@@ -19,7 +26,7 @@ Components in the Visual Framework follow the BEM naming convention.
}
```
## Namespacing
## Namespace
We namespace all universal components with a prefix of `vf-`. This ensures that the component will not break an existing codebase.
......@@ -198,4 +205,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.
\ No newline at end of file
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.
---
title: Governance of the Visual Framework
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
---
[This has been suprerseeded by the consultation process]({{ '/about/consultation/' | url }}).
---
is_index: true
title: JavaScript guidelines
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
order: 10
tags:
- guidelines
- developing
- documentation
---
## Just enough JavaScript
......
---
is_index: true
title: User base and needs
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
layout: layouts/section.njk
section: developing
order: 10
tags:
- guidelines
- developing
- documentation
---
The Visual Framework core ('vf-core') is not intended for direct consumption into
......
---
title: Versioning
title: Versioning
subtitle: The Visual Framework `vf-core` and its components have self-contained versions.
date: 2019-04-09 12:24:50
layout: layouts/developing.njk
section: developing
order: 10
tags:
- guidelines
- developing
- documentation
layout: layouts/section.njk
---
The Visual Framework uses [semantic versioning](https://docs.npmjs.com/about-semantic-versioning) across all projects and packages. Here are some highlights of what this means:
......
---
is_index: true
title: Developing `vf-core`
subtitle: Developing and contributing to the Visual Framework core.
intro: A guide to what you need to do, how you should write it and how to maintain <code>vf-core</code> components.
title: Contributing
subtitle: Developing and contributing to the Visual Framework Core and its components.
intro: A guide to what you need to do, how you should write it and how to maintain <code class="vf-code-example">vf-core</code> components.
date: 2019-04-09 12:24:50
section: developing
order: 1
tags:
- developing
- documentation
- sections
layout: layouts/section.njk
......@@ -14,10 +16,7 @@ templateEngineOverride: njk, md
#### In the right place?
Need to just make a VF-powered site?
If you're not looking to develop the vf-core or add components for global use,
then you might be in the wrong place. If you want to make a site or design system that uses
Need to just make a VF-powered site? If you want to make a site or design system that uses
Visual Framework components, then [check out the "Visual Framework building guide"]({{ '/building' | url }}).
#### Getting started <a id="getting-started"></a>
......
......@@ -5,42 +5,45 @@ date: 2018-08-22 12:24:50
layout: layouts/base.njk
---