Apostrophe Design System / Pattern Library
This bundle allows you to build design system, pattern library or just document your UI components directly in Apostrophe CMS v3 application. It comes with tools like layout nunjucks tags, color and typography presentation with auto-detection (fonts, contrast, etc) macros.
Installation
From the root of your Apostrophe CMS v3 application:
npm i @corllete/apos-ds@alpha
Publish the assets from the bundle
In development
node app @corllete/apos-ds-page-type:publish-assets
In production you need to explcitly set the node environment to production or Bad Things will happen.
NODE_ENV=production node app @corllete/apos-ds-page-type:publish-assets
Integrate with your Apostrophe v3 application
NOTE: the esiest way to see it in action and learn is running the Demo app
Let's suppose you have a local/npm module theme
which contains your website UI componenets (macros, fragments and includes).
Open app.js
and add:
'@corllete/apos-ds': {
options: {
modules: [ 'theme' ]
}
},
'@corllete/apos-ds-page-type': {
options: {
// enable the built-in documentation - yes, in the form of stories
docs: true
}
},
// your imaginery components module
theme: {},
// The rest of your apostrophe configuration
Now you can start creating your design system documentation pages, create your component stories and potentially see stories from other developers (3rd pary apostrophe modules using the component documentation feature of the design system).
Write your first story
Stories are declared and found by story configuratoins. The default pattern (can be changed from your app.js options) is *.stories.js
.
Let's create a story configuration. Inside our imaginery module create APOS_ROOT/modules/theme/views/buttons/buttons.stories.js
like this
// modules/theme/views/buttons/buttons.stories.js
module.exports = {
// Globaly unique!
name: 'my-theme-buttons',
label: 'Buttons',
category: 'My Theme :: Buttons',
stories: [
{
// Uniqie in the context of this file
name: 'button',
label: 'Button',
// relative path to the story;
// `.story.` is not required, just a convention;
// the same with `.njk`
template: 'buttons/button.story.njk',
// one of complete | inreview | inprogress
state: 'inreview'
}
]
};
Now the story itself:
{# modules/theme/views/buttons/button.story.njk #}
{% extends dsPreview %}
{% import "theme:buttons/buttons.html" as buttons %}
{% block previewSimple %}
{{ buttons.primary('Primary') }}
{{ buttons.secondary('Secondary') }}
</div>
{% endblock %}
{% block tagline %}
The button variants.
{% endblock %}
{% block description %}
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Quae cum essent dicta, discessimus. Disserendi artem nullam habuit.
Quae contraria sunt his, malane? Dici enim nihil potest verius.
</p>
{% endblock %}
You can add code examples, variants to showcase the different rendering options, any kind of additional details you need and somewhere in the future - the macro parameters documentation.
Your component is a regular nunjucks macro - a naive implementation:
{# modules/theme/views/buttons/buttons.html #}
{% macro primary(label) %}
render(label, 'primary')
{% endmacro %}
{% macro secondary(label) %}
render(label, 'secondary')
{% endmacro %}
{% macro render(label, type) %}
<button class="theme-button theme-button--{{ type }}">
<span class="theme-button__label">{{ label }}</span>
</button>
{% endmacro %}
Tip
If you wanna suppress the module docs listing but still see them in the navigation menu change your configuration like this
'@corllete/apos-ds': {
options: {
modules: [ 'theme' ]
},
categories: {
add: {
'ds-docs': {
label: 'Docs',
list: false
}
}
}
},
'@corllete/apos-ds-page-type': {
options: {
docs: true
}
},
Development
# Watch
npm run watch
# Build for development
npm run build
# Build for production
npm run build:prod