Commit f2b9b51d authored by Ken Hawkins's avatar Ken Hawkins
Browse files

Initial copy of vf-child-template

parent c2c5075a
# Auto detect text files and perform LF normalization
* text=auto
.sass-cache/
*.css.map
node_modules/
*.log
.DS_Store
build
public
components/**/*.css
*.tgz
{
"plugins": [
"stylelint-order",
"stylelint-scss"
],
"extends": [
"./node_modules/prettier-stylelint/config.js"
],
"rules": {
"string-quotes": "single",
"color-named": "never",
"color-no-hex": true,
"order/order": [
[
"custom-properties",
"dollar-variables",
{
type: "at-rule",
name: "include",
parameter: "set-*",
message: "Stop being lazy and flatten your classnames"
},
"declarations",
"rules",
{
type: "at-rule",
name: "media",
hasBlock: true
}
]
],
"order/properties-alphabetical-order": true,
"block-no-empty": true,
"color-no-invalid-hex": true,
"declaration-colon-space-after": "always",
"declaration-colon-space-before": "never",
"function-comma-space-after": "always",
"media-feature-colon-space-after": "always",
"media-feature-colon-space-before": "never",
"media-feature-name-no-vendor-prefix": true,
"max-empty-lines": 3,
"max-nesting-depth": 3,
"selector-nested-pattern": [ "^(?!&__|&--|&-|&_).*", {
"message": "Stop being lazy and flatten your classnames",
"severity": "warning"
} ],
"number-leading-zero": "never",
"number-no-trailing-zeros": true,
"property-no-vendor-prefix": true,
"selector-list-comma-space-before": "never",
"selector-list-comma-newline-after": "always",
"value-no-vendor-prefix": true,
"indentation": [ 2, {
"message": "Please use 2 spaces for indentation. Tabs make Stuart very grumpy.",
"severity": "warning"
} ]
}
}
# A template Travis CI file you can use to publish
# your child theme to gh-pages
# Deploy the pattern library to gh-pages
language: node_js
node_js:
- 10
branches:
only:
- master
- develop
stages:
- deploy
before_script:
- npm install
- npm install -g gulp-cli
- gulp build
deploy:
provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN # Set in the settings page of your repository, as a secure variable
keep-history: true
target-branch: gh-pages
local-dir: build
cache:
paths:
- node_modules
on:
branch:
- master
# vf-embl
\ No newline at end of file
## 🚨 Pre-alpha 🚨
Warning: the `vf-child-template` is pre-alpha, things will change. We welcome usage and feedback, but updates will be tricky.
# Visual Framework Child template
tl;dr Clone and edit me.
This is a child template to use [the core Visual Framework (`vf-core`)](https://github.com/visual-framework/vf-core#visual-framework-20)
patterns, override them and add your own.
Why use a child? Programatically use (and update from)
Visual Framework core patterns, but with complete flexibility in the look
and function of your patterns (in addition to the Visual Framework's [style
isolation principles](https://blogs.embl.org/communications/2018/09/12/faster-scientific-websites-through-reusability/)).
## 🚼 Know the basics
If you've not already, take a few minutes to [read the basics of the Visual Framework](https://github.com/visual-framework/vf-core#visual-framework-20).
## 1️⃣ 📦 Clone the Visual Framework Child template
*(You'll need gulp and node; [head here if you don't know what those are](https://github.com/visual-framework/vf-core/blob/develop/SETTINGUP.md))*
- `git clone https://github.com/khawkins98/vf-child-playground.git` (add repo url once ready)
- `cd vf-child-playground`
- `npm install`
## 2️⃣ 🎫 Decide on project name, namespace
Open `pacakage.json` and edit:
```
"vfConfig": {
"vfName": "Visual Framework Child pattern library",
"vfNamespace": "vct-"
},
```
- `vfName` examples:
- My Company Name pattern library
- Visual Framework for My Company Name
- `vfNamespace` prefix:
- Custom patterns will be prefixed by a short abbreviation or phrase. So, your
custom pattern for a countdown timer might be `acme-countdown-timer` or if you're
building for Bob's Pizza, `bp-countdown-timer`. We'd encourage you to make it:
- unique
- no longer than four letters
## 3️⃣ ⌨️ Launch the local pattern library
Enter `gulp dev` and the pattern library will build and open in your browser.
Be sure to keep an eye on the console for any compile errors or style linting.
## 4️⃣ 🖌 Make and edit patterns
### Override `vf-core` patterns
1. If you haven't already, install the pattern via `npm`
- `npm install --save @visual-framework/vf-heading`
1. Move a pattern's source folder from `./components/vf-core-patterns` to `./components`
- `mv components/vf-core-patterns/vf-heading components/vf-heading`
1. If the pattern is present in `package.json` remove its reference
- Delete: ` "@visual-framework/vf-heading": "0.0.21",`
1. Edit the pattern in `./components` as you see fit
### Install additional patterns
You can install patterns from vf-core or from other Visual Framework-compliant pattern libraries.
To add additional Visual Framework core patterns, find one you like and use npm;
for example, the `vf-heading` pattern:
```
npm install --save @visual-framework/vf-heading
```
If a pattern you wish to use isn't available on npm, copy it to your `/components`
directory.
In either case, after adding the pattern you'll needed to reference the Sass in
your `/components/vf-core/index.scss`
### Create new patterns
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)
1. Create a new component
- Run `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.
- You customised template pattern will have been added to your `/components` directory.
1. Add the `@import 'vfc-your-pattern.scss';` to `/components/vf-core/index.scss`.
1. Developing your component
- Edit your template files in the `/components/your-pattern-name` folder
- Run `gulp dev` to compile and preview the pattern
1. Sharing you component back
- Publish it to npm; or
- 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).
## 5️⃣ 💅 Customise the pattern library
The Visual Framework uses the [Fractal pattern library](https://fractal.build/).
You can customise the layout of the pattern library by editing the Fractal theme
in `tools/frctl-mandelbrot-vf-subtheme`.
For more guidance, [see the Fractal documentation](https://fractal.build/guide/customisation/web-themes.html#configuring-themes).
## 6️⃣ 🏎 Put your pattern library into use
Once you've configured your pattern library, selected patterns and made a few new ones,
here's how you make use of them.
### Generate CSS and JS for your website
Running `gulp build` will generate a `/build` directory where you'll find:
- global assets
- `css/styles.css`
- `scripts/scripts.js`
- per-pattern JavaScript and image assets
- `assets/vf-*`
### Consume patterns as Sass
You can `@import` your sass, follow the example in `components/vf-core/index.scss`.
### Deploy your pattern library
To come.
### Keeping you pattern template up to date
The `vf-child-template` follows the [`vf-core` versioning](https://github.com/visual-framework/vf-core#versioning), that means you shouldn't have to update very often; that said:
1. Most improvements will be found by updating VF patterns, to see what updates are available: `npm outdated`
1. Watch for [new releases of `vf-child-template`](https://github.com/visual-framework/vf-child-template/releases). We'll provide guidance on how to update.
1. Any updates will be easier if you're using a git repository, you are doing that, right?
## 7️⃣ 🎁 Contribute your Patterns
To come: how to add patterns back to the global `vf-core`
## 8️⃣ ⁉️ Ask the community
- [Slack](https://embl-vf.slack.com/messages)
- [GitHub issues](https://github.com/visual-framework/vf-core/issues/)
<!DOCTYPE html>
<html lang="en" class="vf-no-js">
<head>
{% render '@vf-no-js' %}
<title>{{ _target.title }} | {{ _config.project.title }}</title>
<meta charset="utf-8">
<meta content="width=device-width, initial-scale=1, minimum-scale=1" name="viewport">
{% render '@vf-favicon' %}
{% if _config.project.environment.local %}
<link rel="stylesheet" href="{{ '/css/styles.css' | path }}">
{% endif %}
{% if _config.project.environment.production %}
<link rel="stylesheet" href="https://dev.assets.emblstatic.net/vf/develop/css/styles.css">
{% endif %}
</head>
<body class="">
<div class="vf-grid">
<div class="vf-component__container">
{{ yield | safe }}
</div>
</div>
<script src="{{ '/scripts/scripts.js' | path }}"></script>
</body>
</html>
<!DOCTYPE html>
<html lang="en" class="vf-no-js">
<head>
{% render '@vf-no-js' %}
<title>{{ _target.title }} | {{ _config.project.title }}</title>
<meta charset="utf-8">
<meta content="width=device-width, initial-scale=1, minimum-scale=1" name="viewport">
{% render '@vf-favicon' %}
{% if _config.project.environment.local %}
<link rel="stylesheet" href="{{ '/css/styles.css' | path }}">
{% endif %}
{% if _config.project.environment.production %}
<link rel="stylesheet" href="https://dev.assets.emblstatic.net/vf/develop/css/styles.css">
{% endif %}
</head>
<body class="">
<div class="vf-grid">
<div class="vf-component__container">
{{ yield | safe }}
</div>
</div>
<script src="{{ '/scripts/scripts.js' | path }}"></script>
</body>
</html>
<!DOCTYPE html>
<html lang="en" class="vf-no-js">
<head>
{% render '@vf-no-js' %}
<title>{{ _target.title }} | {{ _config.project.title }}</title>
<meta charset="utf-8">
<meta content="width=device-width, initial-scale=1, minimum-scale=1" name="viewport">
{% render '@vf-favicon' %}
{% if _config.project.environment.local %}
<link rel="stylesheet" href="{{ '/css/styles.css' | path }}">
{% endif %}
{% if _config.project.environment.production %}
<link rel="stylesheet" href="https://dev.assets.emblstatic.net/vf/develop/css/styles.css">
{% endif %}
</head>
<body>
{{ yield | safe }}
<script src="{{ '/scripts/scripts.js' | path }}"></script>
</body>
</html>
<!DOCTYPE html>
<html lang="en" class="vf-no-js">
<head>
{% render '@vf-no-js' %}
<title>{{ _target.title }} | {{ _config.project.title }}</title>
<meta charset="utf-8">
<meta content="width=device-width, initial-scale=1, minimum-scale=1" name="viewport">
{% render '@vf-favicon' %}
{% if _config.project.environment.local %}
<link rel="stylesheet" href="{{ '/css/styles.css' | path }}">
{% endif %}
{% if _config.project.environment.production %}
<link rel="stylesheet" href="https://dev.assets.emblstatic.net/vf/develop/css/styles.css">
{% endif %}
</head>
<body class="vf-body">
<div class="vf-grid">
<div class="vf-component__container">
{{ yield | safe }}
</div>
</div>
<script src="{{ '/scripts/scripts.js' | path }}"></script>
</body>
</html>
# 0.1.0
### Added
- added this
- added that
### Changes
- changed this
- changed that
### Removed
- deleted this
- deleted that
# child-test-pattern Pattern
[![npm version](https://badge.fury.io/js/%40visual-framework%2Fchild-test-pattern.svg)](https://badge.fury.io/js/%40visual-framework%2Fchild-test-pattern)
## Install
This repository is distributed with [npm][npm]. After [installing npm][install-npm], you can install `primer-buttons` with this command.
```
$ npm install --save @visual-framework/child-test-pattern
```
## Usage
The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
```
@import "@visual-framework/child-test-pattern/index.scss";
```
_Make sure you import any requirements along with the modules._
title: child-test-pattern
label: child-test-pattern
context:
pattern-type: block
<div class="child-test-pattern">
/* child-test-pattern template file */
</div>
// child-test-pattern
.child-test-pattern {
}
// setup files required
// sass-lint:disable clean-import-paths
@import 'vf-global-variables';
@import 'vf-variables';
@import 'vf-functions';
@import 'vf-mixins';
// pattern specific styles
@import 'child-test-pattern.scss';
{
"version": "0.0.1",
"name": "child-test-pattern",
"description": "child-test-pattern component",
"homepage": "http://dev.beta.embl.org/guidelines/visual-framework/dev-docs/",
"author": "VF",
"license": "Apache 2.0",
"style": "child-test-pattern.css",
"sass": "index.scss",
"main": "build/index.js",
"files": [
"index.scss",
"child-test-pattern.css"
],
"test": "echo \"Error: no test specified\" && exit 1",
"repo": "https://github.com/visual-framework/vf-core/tree/master/tree/master/components/child-test-pattern",
"bugs": {
"url": "https://github.com/visual-framework/vf-core/issues"
},
"dependencies": {
"@visual-framework/vf-sass-config": "^0.0.12"
},
"keywords": [
"fractal",
"component"
]
}
# Change Log
All notable changes to this project will be documented in this file.
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
## 0.0.14 (2019-03-28)
**Note:** Version bump only for package @visual-framework/vf-boilerplate-page
## 0.0.13 (2019-02-28)
**Note:** Version bump only for package @visual-framework/vf-boilerplate-page
## 0.0.12 (2019-02-28)
**Note:** Version bump only for package @visual-framework/vf-boilerplate-page
# 0.1.0
### Added
- added this
- added that
### Changes
- changed this
- changed that
### Removed
- deleted this
- deleted that
# VF Boilerplate page
The basic structure of a simplified Visual Framework page.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment