README
sketch-book
An opinionated workflow and CLI tool for generating design documentation from typical files/artifacts of the design process and serving it up as a website. It has been designed to minimize friction between design and development through automation with these carefully chosen features:
Export crisp and measurable SVGs from Sketch
Parse color, typography, and other specs from Sketch artboards
Gather reference images
Generate a static site from Markdown files with access to all of the above
Deploy to GitHub Pages or anywhere
Usage
sketch-book requires node.js to run. Install it with npm which hopefully is already in use for development in your project. Once installed, these commands are available:
$ sketchbook --help
Usage
$ sketchbook <file|directory|glob>... [-o output path]
Any mix of Sketch, image, and Markdown files are accepted as input.
Supported globs: https://git.io/vrluA
Options
-o, --output Path to write rendered pages and prepped assets to
-t, --template Path to a custom Handlebars layout template
Input
Markdown
Each Markdown file is rendered to a like-named HTML file. The hierarchy of any directories is also preserved.
markdown-it parses your content following the CommonMark spec and these plugins:
- markdown-it-anchor adds anchors to each heading for linking
- markdown-it-deflist adds support for definition lists
- markdown-it-header-sections wraps content after headings in a
<section>
for styling - markdown-it-implicit-figures wraps standalone images and alt text in a
<figure>
- markdown-it-linkify-images automatically links images to simplify enlarging and sharing
You can also embed other pages like this:
{{> example_folder/markdown_file}}
Sketch Files
In addition to being a source for visual examples, your Sketch files themselves can also be parsed for color and text style specs. Make any artboards that contain examples of these exportable to SVG. Name layers containing examples as they should appear in your documentation. Parsed specs are available to render within pages using built-in templates, specified like this:
{{ colors: Example Artboard }}
{{ styles: Example Artboard }}
Images
- SVG
- PNG
- JPEG
- GIF
Images are copied to your output path as assets for your static site. Be sure to size them appropriately for display on the web.
Recommendations
What your documentation consists of exactly is up to you! And your team, and your process. But plenty of previously published projects should help provide some precedent and ideas to get started.
- iOS Human Interface Guidelines
- Google Material Design Guidelines
- IBM Design Language
- Styleguides
- Wikipedia: Human Interface Guidelines
GitHub
Strongly consider applying the GitHub Flow to design, this will help you collaborate with developers on your team and perhaps approach design more methodically. With Git LFS you can even commit your Sketch files!
Install git-sketch-plugin to get visual diffs and Git commands right in Sketch.
Sketch
Symbols were made for this! Consider maintaining a library of reusable components with which you can compose documentation examples showing them in isolation, in pairs, and brought together into full mockups.
MIT LICENSE
copyright © 2016 sparkart group, inc.