The UI Extension plugin allows users to customize the Pattern Lab frontend style guide without having to fork styleguide-assets-default. It is intended for styling overrides and navigation additions. If you need anything further, it's suggested that you fork the styleguide-assets-default
repo and consume your own custom frontend.
To add the UI Extension Plugin to your project using npm type:
npm install plugin-node-uiextension --save
Or add it directly to your project's package.json
file and run npm install
During installation, the plugin is added as a key to the plugins
object in your main Pattern Lab project's patternlab-config.json
file
If you don't see this object, try running
npm run postinstall
within the root of your project.
Post-installation, you will see the following in your patternlab-config.json
:
Example:
"plugins": {
"plugin-node-uiextension": {
"enabled": true,
"initialized": false,
"options": {
"stylesheets": [
"../../../css/pattern-scaffolding.css"
],
"navLinks": {
"before": [],
"after": []
},
"gearLinks": {
"before": [],
"beforeSearch": []
}
}
}
}
Note the defaulted pattern-scaffolding.css
file, which is relative to the installation location within the /public/
output.
At this time, loading external CSS is not supported.
This file is already responsible for meta-styling of your patterns, and is usually only scoped to the viewer <iframe/>
. With this default, you now have a useful CSS file for altering both the Pattern Lab UI inside the ish <iframe/>
as well as the main frontend. You can use a mockup of Pattern Lab on Codepen to alter the look and feel, and then export or append the compiled css back into pattern-scaffolding.css
.
Here's a Pattern Lab light theme quickly created using the CodePen above.
This is also a good way to build custom pattern states and have their colors represented on the UI.
A navLinks
and gearLinks
object are also initialized post-installation, and allow you to add arbitrary anchor tags to the front end in various locations.
For example, adding the following snippet:
...
"navLinks": {
"before": [
{ "text": "Voice and Tone", "url": "http://example.com/writing-guide", "class": ""}
],
"after": [
{ "text": "Contribute", "url": "http://example.com/contribute", "class": ""},
{ "text": "Downloads", "url": "http://example.com/resources", "class": ""}
]
},
...
would add a link to the Voice and Tone
before the main navigation, with a Contribute
and Downloads
link to follow.
After install, you may manually enable or disable the plugin by finding the plugin-node-uiextension
key within your main Pattern Lab project's patternlab-config.json
file and setting the enabled
flag. In the future this will be possible via CLI.