Primer is an extensible Design System/Pattern Library written in PHP. By default it utilises Twig for templating and Markdown/YAML for Documentation.
To create a new Primer project run the following command:
composer create-project rareloop/primer my-primer-folder --remove-vcs
The easiest way to get up and running is to use the inbuilt PHP Standalone Server:
composer server
And then open the following URL in your browser http://localhost:8080.
If you need to specify the port you can pass this as an argument to the command:
composer server 1234
Primer has three separate sections:
- Documents - A place to store the written documentation for your Design System.
- Patterns - A Pattern Library that catalogues all the components within your system.
- Templates - A way to view the various Page Templates available in your system.
Patterns are the building blocks of your system and Primer provides a simple way to view your entire catalogue, a selection or just a single item. Patterns are located in the resources/patterns folder and are themselves a folder that contain all it's related files.
Each Pattern has an implicit id and title.
The id is the path used to identify it under the patterns folder, e.g. elements/forms/input.
A patterns title is built from the name of the pattern's folder, e.g. elements/lists/ordered-list => Ordered List.
Each pattern folder can contain the following:
- A template A Twig template used to build the pattern's HTML (
template.twig) - One or more data files A file to provide the state data required by the template file
Out of the box, Primer supports State Data in two formats, PHP or JSON.
PHP State Data files are named data.php and must return an array of key/values. This data is then passed to your Twig template at render time.
<?php
return [
'title' => 'Page Title',
];State Data can also be provided as JSON files which are named data.json. This data is then passed to your Twig template at render time.
{
"title": "Page Title"
}When building a Pattern Library it is important to be able to easily test the different states a component can be in and Primer makes this easy. Alternative states can be provided by adding additional files to your Pattern folder in the format:
data~statename.(php|json)
For example to show the error state for an input component you could create a file called data~error.php.
Any pattern can be included within another by using the standard Twig include and referencing the Pattern with it's id, e.g.
{% include 'components/common/site-header' %}Templates can be built up using a mix of custom HTML and Pattern includes and are stored in resources/templates. If required additional grouping/nesting can be achieved by adding folders.
All templates should extend from primer-base.twig and your custom content should be added to the templateContent block, e.g.
{% extends 'primer-base.twig' %}
{% block templateContent %}
<h1>Example Template</h1>
<p>This is an example page template that extends from the <code>primer-base.twig</code> file.</p>
{% endblock %}
Primer provides a simple way to present your Design System Documentation using MarkDown files.
To add a new Documentation Page, simply add a Markdown file (with the .md extension) to resources/docs folder. You can create grouping/nesting by including folders in the structure.
By default Primer will give your Page a title based on the filename but this can be overwritten by adding YAML FrontMatter to your file. For example, to specify the Title and Description you could do the following:
---
title: Page Title
description: This is a description
---
# Heading 1
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Hic placeat iusto animi architecto quasi, praesentium.
Both title & description are keywords that Primer knows how to handle but you are free to add any additional meta data to the FrontMatter that you like. All Markdown files are also passed through the Twig Environment, so custom meta can be used to dynamically generate HTML.
---
title: Page Title
description: This is a description
colours:
- ff0000
- 00ff00
- 0000ff
---
# Colours
<ul>
{% for colour in colours %}
<li>{{ colour }}</li>
{% endfor %}
</ul>
These are the colours we use!
Primer is un-opinionated about what Frontend stack you choose to use. Once you're ready to add CSS and JavaScript assets to your HTML, you should do this in the views/primer-base.twig file. This is a common ancestor that all Primer requests use which will ensure your Patterns and Templates will render as you'd expect.