Commit 0bba977f authored by Ken Hawkins's avatar Ken Hawkins
Browse files

Initial alpha of VF v2.0

We've moved from the internal gitlab server to github to improve collaboration.

#changelog #documentation
parent 4e190cea
# For more information about the properties used in
# this file, please see the EditorConfig documentation:
# http://editorconfig.org/
root = true
[*]
charset = utf-8
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true
end_of_line = lf
.sass-cache/
*.css.map
node_modules/
*.log
.DS_Store
build
public
components/**/*.css
\ No newline at end of file
# This script runs on gitlabci.ebi.ac.uk
# https://gitlabci.ebi.ac.uk/emblorg/visual-framework
# We do it to deploy the pattern library for view
# http://dev.beta.embl.org/guidelines/visual-framework/dev-docs/
# https://dev.assets.emblstatic.net/vf/
image: node:10.9.0
variables:
# project specific variables can be defined here
VM_DEV: wp-np2-10
VM_PROD: wp-p1m-12 wp-p1m-13 wp-p2m-12 wp-p2m-13
VM_PATH: /var/www/drupal/beta.embl.org.guidelines.visual-framework.dev-docs
SSH_OWNER_ID: wd_drupl
SSH_APACHE_ID: w3_wd01
S3_BUCKET_DEV: origin.dev.vf.assets.emblstatic.net
S3_BUCKET_PROD: origin.vf.assets.emblstatic.net
# set secrets in Settings -> Pipelines -> Secret Variables
SSH_OWNER_KEY: secret-key
SSH_APACHE_KEY: secret-key
AWS_KEY: key
AWS_SECRET: secret-key
stages:
- build
- deploy
build:
stage: build
tags:
- docker
script:
- npm install
- npm install -g gulp-cli
- gulp build
artifacts:
paths:
- build
cache:
paths:
- node_modules
deploy-dev:
stage: deploy
image: ebiwd/alpine-ssh
tags:
- docker
before_script:
- add-ssh-key ${SSH_OWNER_ID} "${SSH_OWNER_KEY}" ${SSH_APACHE_ID} "${SSH_APACHE_KEY}"
- add-search-domain ebi.ac.uk
script:
- for VM in ${VM_DEV}; do rsync -acv --delete-after build/. ${SSH_OWNER_ID}@${VM}:${VM_PATH}/; done;
only:
- master
deploy-prod:
stage: deploy
image: ebiwd/alpine-ssh
tags:
- docker
before_script:
- add-ssh-key ${SSH_OWNER_ID} "${SSH_OWNER_KEY}" ${SSH_APACHE_ID} "${SSH_APACHE_KEY}"
- add-search-domain ebi.ac.uk
script:
- for VM in ${VM_PROD}; do rsync -acv --delete-after build/. ${SSH_OWNER_ID}@${VM}:${VM_PATH}/; done;
only:
- tags
except:
- branches
deploy-aws-dev:
stage: deploy
image: ebiwd/alpine-ssh
tags:
- docker
before_script:
- add-aws-key ${AWS_KEY} ${AWS_SECRET}
script:
- bin/deploy-aws
only:
- master
deploy-aws-prod:
stage: deploy
image: ebiwd/alpine-ssh
tags:
- docker
before_script:
- add-aws-key ${AWS_KEY} ${AWS_SECRET}
script:
- bin/deploy-aws prod
only:
- tags
except:
- branches
# CHANGELOG
See http://dev.beta.embl.org/guidelines/visual-framework/dev-docs/changelog
# EMBL Visual Framework principles and methods
## Principles
The spirit of what we're doing here.
1. Science first
- Built with the life sciences in mind
2. Evolution
- We’re just getting started, and we’re planning for the future
3. Clarity
- We’ll enable clear communication of challenging topics
4. Right choices are easy
- We provide the better choices as defaults
5. Compatibility and integration
- We don’t dictate the tech solution. Bring Angular or vanilla. This framework is here to help
6. For you, with you
- We’re building for the community and we’re asking for your help, directly or indirectly
## Methods
How we're going to do the above.
### 1. Open development, consultations
- We'll have some sort of regular meetings, discussions with stakeholders to ensure we're addressing the community's needs;
- We'll ensure scientific stakeholders are a part of the decision process;
- We'll welcome pull requests to code; and
- We'll have a Slack workspace (or some type of online support)
- [Join our embl-vf.slack.com group here](https://join.slack.com/t/embl-vf/shared_invite/enQtNDAxNzY0NDg4NTY0LTMwOGZhYThiZDE1OGFmYTM0ODgxNTkyZDllNjgyODU4MDgwOTRkZWU4OWY4M2I2OTgwZGMxZDRiOTI4NzVkYTI)
### 2. We flex to organisational needs
The framework is designed to adjust the look and feel according to the parent page's brand layer -- content on the EMBL.org site can look different (but of the same family) to the same content on a research team, service or training page.
### 3. Whole enchelada or modular
You can either use the central CSS+JS, or use NPM and pull in code for each block or container.
### 4. Vanilla first
We'll build our patterns targeting vanilla CSS and JS sites first and then build to support React, Angular, Drupal, Wordpress and any other supported environments. CSS and JS are the standard, and targeting these ensures the most longevity of the code base.
### 5. A shop front and workshop
We'll have a spot for developer (workshop) and a spot that targets a wider audience (workshop). https://github.com/visual-framework/vf-core-tooling-prototype/issues/10
### 6. Atomic-style design
Instead of the atomic names, we're using the spirit and calling them `elements` > `blocks` > `containers` > `page`. We believe this is more understanable and will be less contentious in a scientific enviorment.
- Elements are:
- a heading
- a paragraph
- an images
- Blocks are made of Elements to create:
- a 'teaser', et al.
- Containers are made of Blocks to create:
- a layout of three teasers
- Pages are made of Containers
### 7. CSS naming conventions
#### Element-classed naming
The `element` > `blocks` > `containers` are reflected in CSS names, so `.button` is `.e-button`, and that's combined with name-sapcing, see the next point:
#### Name-spaced CSS classes
Combined with element-classed naming, we're name-spacing with `embl`, so `.e-button` is `.embl-e-button`. This ensures styles won't conflict with framework X, and allows other groups to namespace their element, i.e. `.uniprot-e-button`.
#### No styles on the element
We won't apply CSS to `ul` and `h1` elements, but `embl-e-heading-xl` and `embl-e-list embl-e-list--unordered`.
This is more verbose, but ensures we only engage with HTML elements that developers want us to -- so we can play nice with CSS/JS framework X. It also seperates semantic structure from visual style.
#### Linting
We'll have recommended (S)CSS (and JS?) linting setups -- the specifics are still under discussion: https://github.com/visual-framework/vf-core-tooling-prototype/issues/11
### 8. Browser support
We'll support IE11 and the latest two versions of other major browsers. Beyond those we aim for graceful degradation.
# vf-core
\ No newline at end of file
# Visual Framework 2.0
- [Setting Up](#Setting-Up)
## What is this?
This project helps ensure brand consistency and the easy use of modern web design best practices -- such as responsive design, iterative maintenance cycles, and UX-tested patterns. It also does so with particular consideration for life science content: guidance for tables, graphs, data-heavy typography.
### Can I find an updated version on the web?
When we release an update to the Visual Framework to the master is compiled and [the pattern library is published to embl.org/guidelines/visual-framework/dev-docs](dev.beta.embl.org/guidelines/visual-framework/dev-docs).
### Do I need to install this?
This is meant for those wanting to develop or customise the Visual Framework. If you're building a basic integration with vanilla HTML, Angular, React, Wordpress or Drupal, see the integration guides [LINK TO BE MADE].
### I have an idea or concern!
There are three ways that we discuss and track ideas:
- General: Slack at [embl-vf.slack.com](https://embl-vf.slack.com/messages) for general ideas and discussion
- Creative: [Trello](https://trello.com/b/TpdoWYC5/visual-framework-20) for conceptual things like new design patterns and approaches to CSS standards and HTML guidelines
- Technical: [GitHub issues here](https://github.com/visual-framework/vf-ebi/issues) for implementing deeply technical and specific issues, like the Sass build process, browser bugs
Why use three things? Because there is no one tool that's good for all problems and all types of stakeholders.
## Versioning
As not all users of the Visual Framework will be able to update to the very latest and we do not wish to hold others back, we are using a semantic versioning style of releases.
| Major release | Minor release | Note |
| ------------- | ------------- | ---- |
| (Branch) | (Tag) | |
| 2.0 | v2.0.0 | Initial release evolving from Compliance theme |
| " | v2.0.1 | Tagged minor release |
| " | v2.0.2 | Tagged minor release |
| " | v2.0.3 | Tagged minor release |
| 2.1 | v2.1.0 | Documented, breaking release |
| " | v2.1.1 | Tagged minor release |
| 2.2 | v2.2.0 | Documented, breaking release |
Difference between major, minor releases:
- Major releases (.1, .2, .3...) can have breaking changes and any such changes will be detailed and tested.
- Minor releases (0.0.X) will not have changes to code structure or parts and will mainly add features or update visual assets (such as logos or icon fonts).
We support the last two major releases with bug fixes and branding. New features will only be added to the current and development versions.
Where's version 1.X, you ask? That's the [EMBL-EBI Visual Framework](https://github.com/ebiwd/EBI-Framework) from where this concept [originated, and evolved](https://blogs.embl.org/communications/2018/09/12/faster-scientific-websites-through-reusability/).
### Test releases
Testing releases will be identified in their tag, a la: `v2.0-alpha.1`, where `-alpha.1` is the tag. `-alpha`, `-beta` and `-rc` are tag suffixes.
### Alpha development of v2.0
As the Visual Framework is in heavy, active development, we will have many `v2.0.0-alpha.X` releases. With new alphas planned on a weekly basis (Fridays).
## Setting Up
To use the Visual Framework your machine will require some software to be installed to start.
The software you will need is:
- Node.js
- Gulp
You can check to see if you have these installed in the command line by entering the name of the package with -v afterwards, for example.
```
$ node -v
$ gulp -v
```
If either of these throw an error in your command line application then you will need to install them.
### To install Node
The easiest way to download and install Node is via the official [downloads page](https://nodejs.org/download/) where you can download the correct version for your operating system.
### To install Gulp
Once you have Node install you can easily install the Gulp task manager by entering the following command into your command line application:
```
npm install gulpjs/gulp-cli -g
```
## Installing the Visual Framework
You will need to install this repo onto your machine so that you can update, amend, and and delete patterns to the Visual Framework as required.
#### 1. Clone this repo
```
git clone https://github.com/visual-framework/vf-ebi.git
cd visual-framework-tooling-prototype
```
#### 2. Install [fractal](https://github.com/frctl/fractal)
You might need to use `sudo`.
```
npm i -g @frctl/fractal
```
#### 3. Download all the things
```
npm install
```
#### 4. Run a dev build
You're now setup to run the visual framework's component library, run a dev build:
```
gulp dev
```
## Creating a new component
This codebase includes a folder and file creation tool. 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.
1. Install Yeoman
- If you've come this far and you don't have `yo`, you should be able to install it with `npm install -g yo@latest`
- If you get stuck, [see the official install guide](http://yeoman.io/codelab/setup.html)
2. Create a new component
- You will need to use the vf-font-monospace-stack `gulp component` and answer the questions when prompted.
- **Type of component:** We use a variation of the atomic design methodology, [read about the differences here](http://bradfrost.com/blog/post/atomic-web-design/#atoms). We use: elements, blocks, and containers.
- an element would be a heading, or a button
- a block would be a teaser, or a search form
- a container would be a group of teasers
- **Name of component:** Go for something simple and obvious (todo: we need a guide/documentation on how we name things). Don't worry about namespacing and prefixing, the tooling will take care of this.
- **NPM package:** If you're making something interesting (probably not an 'element'), then saying 'yes' will allow the component to be shared as an optional part of the framework on NPM.
3. Developing your component
- Detailed guide to come, but for now edit the new files and develop with `gulp dev`
4. Sharing you component back
- If you didn't make it an NPM package: Make a pull request?
- If it is an NPM package: Submit guide here?
## Design Tokens
The [Design Token concept](https://medium.com/eightshapes-llc/tokens-in-design-systems-25dd82d58421) specifies 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).
.Preview-iframe {
border: 1px solid #b3b3b3;
padding: 12px 0 0 12px;
}
.Tree-depth-2 > h4 {
font-size: 24px;
margin-bottom: 12px;
}
.Tree-depth-3 {
h4 {
font-weight: 400;
}
ul {
padding-left: 6px;
margin-bottom: 12px;
}
}
.Tree-depth-2 {
& > h4 {
margin-top: 24px;
}
}
.select2 {
display: none !important;
}
.Browser-controls {
margin-bottom: 16px;
}
// retrieve color from $colors map ie. `set-color(base, primary)`
@function set-color($color-name, $color-variant:null) {
// color variant is optional
@if ($color-variant != null) {
// map inception
@return map-get(map-get($vf-colors-map, $color-name), $color-variant);
} @else {
@return map-get($vf-colors-map, $color-name);
}
}
@import "map-deep-get";
@import "string-replace";
@import "set-color";
// functions to get relevant font informtation from sass maps --- --- --- ---
@function map-deep-get($map, $keys...) {
@each $key in $keys {
$map: map-get($map, $key);
}
@return $map;
}
// str-replace function
// --------------------
// This is used to slice off the first amount($number) of characters from the $name value passed.
// Primarily used to replace the start of variables for the utility class generation.
@function str-replace($name, $number) {
@return str-slice($name, $number);
}
@mixin blockquote() {
@include set-type(body--l);
margin: 0;
padding: 10px 8px 10px 32px;
position: relative;
&::before {
content: '';
border-left: 4px solid map-get($vf-colors-map, vf-color-gray-bright);
position: absolute;
left: 12px;
height: 100%;
top: 0;
}
}
// vf-divider
@mixin divider() {
background-color: map-get($vf-colors-map, vf-color-gray);
margin: 0 map-get($vf-spacing-map, vf-spacing-xxl);
}
@mixin figure($has-caption: true) {
margin: 0;
&__image {
@include margin--block(bottom, 21px);
}
@if $has-caption == true {
&__caption {
@include set-type(body--s);
color: map-get($vf-colors-map, vf-color-gray);
font-style: italic;
}
}
}
@mixin inline-link($vf-link-color: $vf-link-color, $vf-link-hover-color: $vf-link-hover-color) {
color: $vf-link-color;
&:visited {
color: $vf-link-visited-color;
}
&:hover {
color: $vf-link-hover-color;
}
&[disabled] {
color: $vf-link-disabled-color;
cursor: not-allowed;
}
}
@mixin button-link($vf-link-color, $vf-link-hover-color) {
background-color: $vf-link-color;
border: 2px solid $vf-link-color;
color: map-get($vf-colors-map, vf-color-white);
&:visited {
background-color: $vf-link-visited-color;
}
&:hover {
background-color: $vf-link-hover-color;
border-color: $vf-link-hover-color;
}
&[disabled] {
background-color: $vf-link-disabled-color;
cursor: not-allowed;
}
}
@mixin button-link--ghost($vf-link-color: $vf-link-color, $vf-link-hover-color: $vf-link-hover-color) {
background-color: map-get($vf-colors-map, vf-color-white);
border: 2px solid $vf-link-color;
color: $vf-link-color;
&:visited {
background-color: $vf-link-visited-color;
}
&:hover {
background-color: $vf-link-hover-color;
border-color: $vf-link-hover-color;
color: map-get($vf-colors-map, vf-color-white);
}
&[disabled] {
background-color: $vf-link-disabled-color;
cursor: not-allowed;
}
}
@mixin list($classname, $type: null) {
@if $type == null {
list-style-type: none;
padding: 0 0 0 40px;
}
margin: 0;
@if $type == unordered {
padding-left: 40px;
list-style-type: disc;
// .vf-list__item {
// padding-left: 0;
// position: relative;
//
// &:before {
// content: '•';
// left: -30px;
// position: absolute;
// }
// }
}
@else if $type == ordered {
list-style-type: decimal;
padding-left: 40px;
// counter-reset: step-counter 0;
// & > & {
// padding-left: 40px;
// }
// .vf-list__item {
// counter-increment: step-counter;
//
// &:before {
// content: counter(step-counter)'.';
// margin-right: 5px;
// }
// }
}
@else if $type == inline {
padding: 0;
@if $classname == null {
li {
display: inline;
}
}
@else {
[class*=__item] {
display: inline;
}
}
}
@if $classname != null {
@at-root .#{$classname} {
@at-root .#{$classname}__item {
margin-bottom: map-get($vf-spacing-map, vf-spacing-r);
}
}
}
@else {
li {
margin-bottom: map-get($vf-spacing-map, vf-spacing-r);
}
}
}
@mixin margin--block($size1, $size2) {
@if $size1 == all {
margin-bottom: $size2;
margin-top: $size2;
}
@else if $size1 == top {
margin: $size2 0 0 0;
}
@else if $size1 == bottom {
margin: 0 0 $size2 0;
}
@else {
margin-bottom: $size2;
margin-top: $size1;
}
}
@mixin margin--inline($size1, $size2) {
@if $size1 == all {
margin-left: $size2;
margin-right: $size2;
}
@else if $size1 == left {
margin-left: 0 0 0 $size;
}
@else if $size1 == right {
margin-right: 0 $size2 0 0;