@mfranzke/plugin-node-uiextension v1.0.1

UI Extension Plugin for Pattern Lab Node

The UI Extension plugin allows users to customize the Pattern Lab frontend style guide without having to fork UIKit Workshop. It is intended for styling overrides and navigation additions. If you need anything further, it's suggested that you fork the UIKit Bare repo and consume your own custom frontend.

Installation

To add the UI Extension Plugin to your project using npm type:

npm install @mfranzke/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.

Configuration

Post-installation, you will see the following in your patternlab-config.json:

Example:

"plugins": {
  "@mfranzke/plugin-node-uiextension": {
    "enabled": true,
    "initialized": false,
    "options": {
      "stylesheets": [
        "css/pattern-scaffolding.css"
      ],
      "navLinks": {
        "before": [],
        "after": []
      },
      "toolLinks": {
        "before": [],
        "after": []
      }
    }
  }
}

CSS

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.

Adding Links

A navLinks and toolLinks 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": "https://example.com/writing-guide", "class": ""}
  ],
  "after": [
    { "text": "Contribute", "url": "https://example.com/contribute", "class": ""},
    { "text": "Downloads", "url": "https://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.

Within the toolLinks you do have an additional property called icon that you could choose from - just use the filename without the .svg ending for this property: https://github.com/pattern-lab/patternlab-node/tree/master/packages/uikit-workshop/src/icons

...
"toolLinks": {
  "before": [
    { "text": "Voice and Tone", "url": "http://example.com/writing-guide", "class": "", "icon": "help"}
  ],
  "after": []
},
...

Enabling / Disabling the Plugin

After install, you may manually enable or disable the plugin by finding the @mfranzke/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.