Sample UI patterns and documentation have been included in this tool to indicate what a finished Style Guide could look like. You can remove the files from
CNAMEfile to start from scratch.
To serve the files locally run the following code in terminal:
Once your style guide is complete you can publish it to Github Pages like any other Jekyll website.
All settings are contained in the
_config.yml file. To use this tool out of the box, you only need to adjust the
These are standard Jekyll configuration settings, check the documentation for information on how to use this.
Style Guide Shell Settings
These settings control the default variables used in the shell, check the Editing the Styleguide section for help on how to use them.
These settings control how documentation and pattern files are generated, and where they are located. Check the Editing the Styleguide section for help on how to use them.
These settings are used in all patterns and should be updated based on your needs.
Remember you need to
$jekyll serveyour site in terminal after changing any of the config files.
What is a Pattern?
A ‘Pattern’ is any part of the user interface, by default there are 3 types:
- Foundations are global constraints that define the basic parameters of parts of the UI.
- Example, a Typeface, Primary or Secondary Colors, Icons.
- Components are stand-alone UI patterns that can be directly used in the interface.
- They can include Foundations, or can be constructed with uniques styles.
- Example, Primary Button, Secondary Button, Card, Card Group, Table, etc.
- Templates are pre-determined page layouts.
- They can include components and foundations, or can be constructed uniquely.
- Examples, Full-Width Content Page, Sidebar Page, Two Column Page
- Write your HTML pattern in a Markdown file.
- The pattern must start with Front Matter.
- Set the
maturity, and the location of the corresponding
- Optional: Turn off the Pattern Controls by using
control: exclude- this is particularly useful for foundation patterns.
- Upload your pattern to the corresponding folder in
- You need to make sure your pattern is 4 folder levels deep to ensure they get linked correctly from the navigation and roadmap, so group you patterns in sub folders
Editing Pattern Assets
- Pattern assets are stored in the
- You can add additional styles/scripts to a pattern via the Pattern Settings in the
_config.ymlfile - styles will automatically be included in the
<head>, scripts will automatically be included before the
</body>tag in all patterns.
Keep your styles organised. Try this simple SCSS playbook.
What is Documentation?
‘Documentation’ is used to store information relating to a pattern (or group of patterns), as well as information about the style guide itself - this page is an example of a document.
By default, documentation is stored in the
_docs folder and grouped in directories that correspond to the pattern directories. An additional
/about directory is also provided, this can contain general/non-pattern specific contents (like this page).
Patterns are always loaded into a document via an iFrame, so any style guide related styles will not interfere with your pattern.
Adding any document into these folders will automatically make it appear in the style guide navigation.
These settings are defined in the
config.yml file and ensure that each document outputs with the correct Jekyll layout and meta data.
- Create your document file in Markdown format.
- Your filename can match the pattern URL, but it does not have too.
- The document must start with Front Matter.
- Set the title.
- Optional: add info which will be displayed at the top of the document page.
- Optional: add
nav: trueinto the Front Matter if you would like to display a mini contents menu at the top of the page (like this page).
- You can use any Markdown in the page content area.
- To include a pattern in the document page you must include the pattern block and specify a
urlvariable in the include. By repeating this process you can include multiple patterns on the page. See the sample below taken from the
- Note that the pattern controls and maturity are set in the pattern file.
The contents menu will automatically generate a table of contents based on any
h1items on the page.
Editing the Style Guide