You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+4-82
Original file line number
Diff line number
Diff line change
@@ -82,96 +82,18 @@ There are a few ways that we discuss and track ideas:
82
82
- ⚙️ 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
83
83
- 🏢 E-mail: if you have a sweeping Big Idea™️, e-mail Ken Hawkins <ken.hawkins@embl.de>
84
84
85
-
### Contributing and branch naming
85
+
### Contributing
86
86
87
-
[See the Contributing and branch naming guide](https://github.com/visual-framework/vf-core/blob/develop/CONTRIBUTING.md)
87
+
[See the contributing guide](https://github.com/visual-framework/vf-core/blob/develop/docs)
88
88
89
89
## Versioning
90
90
91
-
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](https://semver.org/) style of releases.
| 2.1 | v2.1.0 | Minor release with possible breaking changes |
101
-
| " | v2.1.1 | Tagged patch release |
102
-
| 2.2 | v2.2.0 | Minor release with possible breaking changes |
103
-
| 3.0 | v3.0.0 | Major release with many breaking changes|
104
-
105
-
We support the last two minor releases with bug fixes and branding. New features will only be added to the current and development versions.
106
-
107
-
Where's version 1.X, you ask? That's the [EMBL-EBI specific 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/).
108
-
109
-
### Test releases
110
-
111
-
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.
91
+
[See the versioning guide](https://github.com/visual-framework/vf-core/blob/develop/docs/contributing/versioning)
112
92
113
93
### Alpha development of v2.0
114
94
115
95
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 monthly basis (last Thursday of each month).
116
96
117
97
## Local development
118
98
119
-
### Setting Up
120
-
121
-
To use the Visual Framework your machine will require some software to be installed to start. [See the SETTINGUP.md guide](https://github.com/visual-framework/vf-core/blob/develop/SETTINGUP.md).
122
-
123
-
### Installing the Visual Framework
124
-
125
-
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. You probably want the develop branch (or [your new feature branch](https://github.com/visual-framework/vf-core/blob/develop/CONTRIBUTING.md))
132
-
-`git checkout develop`
133
-
1. Install [fractal](https://github.com/frctl/fractal) You might need to use `sudo`.
134
-
-`npm i -g @frctl/fractal`
135
-
1. Download all the things
136
-
-`npm install`
137
-
1. Run a dev build and open in your browser
138
-
-`gulp dev`
139
-
140
-
## Creating a new component
141
-
142
-
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.
143
-
144
-
1. Install Yeoman
145
-
- 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`
146
-
- If you get stuck, [see the official install guide](http://yeoman.io/codelab/setup.html)
147
-
1. Create a new component
148
-
- Run `gulp component` and answer the questions when prompted.
149
-
-**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.
150
-
- an element would be a heading, or a button
151
-
- a block would be a teaser, or a search form
152
-
- a container would be a group of teasers
153
-
-**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.
154
-
-**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.
155
-
- You customised template pattern will have been added to your `/components` directory.
156
-
1. Add the `@import 'vfc-your-pattern.scss';` to `/assets/scss/styles.scss`.
157
-
1. Developing your component
158
-
- Edit your template files in the `/components/your-pattern-name` folder
159
-
- Run `gulp dev` to compile and preview the pattern
160
-
1. Sharing you component back
161
-
- Publish it to npm; or
162
-
- If you think your pattern is of use to the wider `vf-core` community, [make a Pull Request](https://github.com/visual-framework/vf-core/pulls).
163
-
164
-
## Global colour, typography and spacing.
165
-
166
-
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).
167
-
168
-
This Design Token abstraction [helps portability and integration](https://uxdesign.cc/design-tokens-for-dummies-8acebf010d71) with other technical systems.
169
-
170
-
You can find the Design Tokens in `components/vf-design-tokens`.
171
-
172
-
## Language and spelling of documentation, code
173
-
174
-
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:
175
-
176
-
- 📚🇬🇧 Documentation is written in British English 💂 `Rarely use centred text, always use colours`
177
-
- ⌨️🇺🇸 Code is written in American english 🧢 `$vf-main-color: green;`
99
+
To use the Visual Framework your machine will require some software to be installed to start. [See the "Setting up" guide](https://github.com/visual-framework/vf-core/blob/develop/docs/contributing/setting-up.njk).
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.
8
+
9
+
1. Install Yeoman
10
+
- 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`
11
+
- If you get stuck, [see the official install guide](http://yeoman.io/codelab/setup.html)
12
+
1. Create a new component
13
+
- Run `gulp component` and answer the questions when prompted.
14
+
- **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.
15
+
- an element would be a heading, or a button
16
+
- a block would be a teaser, or a search form
17
+
- a container would be a group of teasers
18
+
- **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.
19
+
- **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.
20
+
- You customised template pattern will have been added to your `/components` directory.
21
+
1. Add the `@import 'vfc-your-pattern.scss';` to `/assets/scss/styles.scss`.
22
+
1. Developing your component
23
+
- Edit your template files in the `/components/your-pattern-name` folder
24
+
- Run `gulp dev` to compile and preview the pattern
25
+
1. Sharing you component back
26
+
- Publish it to npm; or
27
+
- If you think your pattern is of use to the wider `vf-core` community, [make a Pull Request](https://github.com/visual-framework/vf-core/pulls).
28
+
29
+
<divclass="vf-box">
30
+
Tip: also consult the [guidelines](guidelines) for the naming of things and coding standards.
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](https://semver.org/) style of releases.
| 2.1 | v2.1.0 | Minor release with possible breaking changes |
17
+
| " | v2.1.1 | Tagged patch release |
18
+
| 2.2 | v2.2.0 | Minor release with possible breaking changes |
19
+
| 3.0 | v3.0.0 | Major release with many breaking changes|
20
+
21
+
We support the last two minor releases with bug fixes and branding. New features will only be added to the current and development versions.
22
+
23
+
Where's version 1.x, you ask? That's the [EMBL-EBI specific 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/).
24
+
25
+
### Test releases
26
+
27
+
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.
Copy file name to clipboardexpand all lines: docs/getting-started/index.md
+6-10
Original file line number
Diff line number
Diff line change
@@ -5,15 +5,11 @@ order: 200
5
5
isIndex: true
6
6
---
7
7
8
-
<aid="get-started"></a>Here are ways to utilise the Visual Framework:
8
+
There's no need to download or clone the `vf-core` repository, instead you can use
9
+
its patterns to enhance or build your design system:
9
10
10
-
1. 🛍 [Browse the online patterns](https://visual-framework.github.io/vf-core)
11
-
1. 🏎 Utilise the whole, unaltered Framework: include the [CSS, JS and copy a boilerplate](https://visual-framework.github.io/vf-core/components/render/vf-boilerplate-page)
12
-
1. 🚰 [Install a specific pattern from npm](https://www.npmjs.com/org/visual-framework) and include the Sass/JS
13
-
1. 🏗 Get a custom look and patterns with [your own Visual Framework child theme](https://github.com/khawkins98/vf-child-playground)
11
+
- Use the [Visual Framework child theme](https://github.com/khawkins98/vf-child-playground) as a boilerplate
12
+
-[Install a specific pattern from npm](https://www.npmjs.com/org/visual-framework)
14
13
15
-
([This is pulled from the README.md](https://github.com/visual-framework/vf-core#-get-started))
16
-
17
-
## to-do
18
-
19
-
- Once we have the generic VF available on unpkg, we need to add links
14
+
If those don't cover your use case, and you just need some CSS and JS to plug-in to
15
+
your website, [let us know](https://github.com/visual-framework/vf-core/issues/new/choose).
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).
9
+
10
+
This Design Token abstraction [helps portability and integration](https://uxdesign.cc/design-tokens-for-dummies-8acebf010d71) with other technical systems.
11
+
12
+
You can find the Design Tokens in `components/vf-design-tokens`.
Copy file name to clipboardexpand all lines: docs/guidelines/index.njk
-12
Original file line number
Diff line number
Diff line change
@@ -6,15 +6,3 @@ isIndex: true
6
6
---
7
7
8
8
What to do and what not to do.
9
-
10
-
## Things we want to take another look at:
11
-
12
-
- CSS order: as we are using grid and flexbox for layout it feels like alphabetical is a little antiquated as we would are writing CSS for the component and the components children in the same ruleset.
13
-
14
-
- CSS custom properties: How do we include these, how do we make sure older browsers still get something.
15
-
16
-
- Browser support documentation: I guess we can borrow this from current VF?
17
-
18
-
- Universal Components: how we should be writing code for everyone, including screen readers. Where to add `aria` things etc.
19
-
20
-
- JavaScript: although the docs essentially say "don't use this" we need to work _how_ we are going to write JS for any component that needs it and how we should be writing that. We will need JS for outage notifications, global footers, GDPR...
Copy file name to clipboardexpand all lines: docs/guidelines/naming.njk
+7
Original file line number
Diff line number
Diff line change
@@ -28,3 +28,10 @@ If your pattern is primarily intended to be used for particular websites or a br
28
28
- vf-yourbrand-display-headline
29
29
30
30
Why? Naming for the role the pattern does allows us to change the future visual structure, so a "display headline" today may have a black background, but tomorrow might have no background and be large and italic text.
31
+
32
+
## Language and spelling of documentation, code
33
+
34
+
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:
35
+
36
+
- 📚🇬🇧 Documentation is written in British English 💂 `Rarely use centred text, always use colours`
37
+
- ⌨️🇺🇸 Code is written in American english 🧢 `$vf-main-color: green;`
0 commit comments