A pattern library designed to be easier to maintain
Q. What is a pattern library?
A pattern library, also known as a style guide, is a way of showing example usage of HTML and CSS for components (React components, or plain HTML).
When sites comprise different technologies or are very large then having this example usage can help achieve design consistency.
Q. How can I make patterns for an existing website?
One of the advantages of Pattern-Book is that it detects the CSS Rules being applied, so you can put your entire site's CSS files on the page and then write HTML that uses them and Pattern-Book will only display the relevant CSS (no need to manually associate CSS with a particular <Book>
). This means that it's hopefully a lot less effort to repurpose your existing CSS as a pattern library.
Unlike most Pattern Libaries, also known as Style Guides, there's no need to define components in the way that the framework understands. Instead Pattern-Book works with your existing components and it auto-detects the code being used.
Usage:
;;; // contains h6 { color: red; } { return <div> <h5>Heading Patterns</h5> <hr /> <Book> <h6>My Heading 6</h6> </Book> </div> ; }
Will look like
Heading Patterns
My Heading 6
HTML
<h6>My Heading 6</h6>CSS
h6 { color: red; }
Q. This is a pattern library so where's the dev webserver?
Great question.
pattern-book
doesn't include a dev server because other projects do it better.
So instead just use Create-React-App or, add <Book>
tags to a new route in your existing app, or use whatever boilerplate you like.
Pattern-Book is very specifically targetting just the render and code preview of your components.
Q. How does pattern-book organise the page of patterns... with headings, accordions, tabs, or what?
Imagine that your pattern library had 5 components then it probably should be organised quite differently to another library with 1000 components, so this software is unopinionated about organisation. Pattern-Book just renders the component preview so decide for yourself how to organise them (do try [react-accessible-accordion though!).
So, long story short, it doesn't organise them, so design it however you want! (headings are nice and simple though)
Code Preview Themes
Use `pattern-book/theme/solarize.css`.
Features
- [x] Minimal
- [x] React
- [x] CSS Rule Autodetection, so there's no need to manually associate CSS with a component
- [x] HTML beautifier
- [x] CSS beautifier
- [x] CSS rule whitelist and blacklist. Pass in 'blacklist' prop with value of 'stylesheet' to string match against attributes of `<link>` or `<style>`, 'stylesheets' to pass in an array of those, or 'rule' to match against selectors, or rules for an array of those.
- [x] CSS Rule whitelist (probably only useful to opt-in specific stylesheets while ignoring others)
- [x] Render prop overrides for HTML and CSS
Who's using it? / Demo
You? Tweet me to be added.
ToDo
- [ ] ZIP download of particular components (including assets, eg backgrounds images and fonts).
- [ ] ...and show prop types, somehow? (`prop-types` or Flow/TS?). Sadly I'm not sure how we could support FlowType/TypeScript types because those are removed at compile-time.
- [ ] Detect basic JSX React Components... this is almost working
- [ ] Make it support interactive components (eg accumulating CSS across these multiple states).
- [ ] Make the `<Book>` not render until it scrolls into view (pattern libraries are notorious for having hundreds of compnents on a long page, so this is hopefully an easy optimisation)
- [ ] Parse SourceMaps to derive Sass (etc) if possible.