README
html-sketchapp-cli
Quickly generate Sketch libraries from HTML documents and living style guides, powered by html-sketchapp and Puppeteer.
Add some simple markup to your page, for example:
<div data-sketch-symbol="Button/Primary">...</div>
<div data-sketch-text="Heading">...</div>
<div data-sketch-color="#212121">...</div>
Then run the html-sketchapp
command to generate JSON files in html-sketchapp's "Almost Sketch" format, ready to be imported into Sketch.
$ html-sketchapp --file sketch.html --out-dir dist/sketch
Install
$ npm install --global html-sketchapp-cli
Then, install the Sketch plugin.
$ html-sketchapp install
Page Setup
Before using this tool, you'll need to add some hooks to your page so that everything can be selected, extracted and named correctly.
Annotate symbols with data-sketch-symbol
attributes. Note that forward slashes will create nested menu items within Sketch.
<div data-sketch-symbol="Button/Primary">
...
</div>
Annotate all text styles with data-sketch-text
attributes.
<div data-sketch-text="Heading">
...
</div>
Annotate all colors with data-sketch-color
attributes. Note that colors are unnamed in Sketch, so only the hex value needs to be provided.
<div data-sketch-color="#212121">
...
</div>
For a real world example, check out SEEK Style Guide's sketch exports page and the corresponding source code.
CLI Usage
Importing from a local file
If your page is self-contained, you can import from a local HTML file.
$ html-sketchapp --file sketch.html --out-dir dist
Importing from a local static web server
If your page needs to be hosted on a static web server, you can provide a local directory to serve and a root relative URL to import from.
$ html-sketchapp --serve docs --url /sketch --out-dir dist
Importing from existing web server
If your page is hosted on an existing web server, you can provide an absolute URL.
$ html-sketchapp --url http://localhost:3000 --out-dir dist
Viewport sizes and responsive design
If you provide a set of one or more named viewports, every symbol and text style will be rendered for each screen size.
$ html-sketchapp --viewports.Desktop 1024x768 --viewports.Mobile 320x568 --file sketch.html --out-dir dist
If multiple screen sizes are provided, the viewport name will be being appended to all symbol and text style names. For example, Button/Primary
will be exported as Button/Primary/Desktop
and Button/Primary/Mobile
.
Puppeteer args
If you need to provide command line arguments to the browser instance via Puppeteer, you can provide the puppeteer-args
option.
Since Puppeteer uses Chromium internally, you can refer to the List of Chromium Command Line Switches for available options.
For example, if you'd like to disable the browser sandbox:
$ html-sketchapp --puppeteer-args="--no-sandbox --disable-setuid-sandbox" --file sketch.html --out-dir dist
Note: Because Puppeteer args are prefixed with hyphens, you must use an equals sign and quotes when providing this option via the command line (as seen above).
Chromium executable
If you'd like to override the Chromium used by Puppeteer, you can provide a path to the executable with the puppeteer-executable-path
option.
$ html-sketchapp --puppeteer-executable-path google-chrome-unstable --file sketch.html --out-dir dist
Config file
All options can be provided via an html-sketchapp.config.js
file.
module.exports = {
file: 'sketch.html',
outDir: 'dist/sketch',
viewports: {
Desktop: '1024x768',
Mobile: '320x568'
},
puppeteerArgs: '--no-sandbox --disable-setuid-sandbox',
puppeteerExecutablePath: 'google-chrome-unstable'
};
You can provide an alternate config file path with the --config
option.
$ html-sketchapp --config example.config.js
Importing into Sketch
Once this command has successfully run, the following files will be generated in the output directory.
document.asketch.json
page.asketch.json
These need to be imported into Sketch via html-sketchapp's corresponding Sketch plugin. To ease the install process, you can run the following command.
$ html-sketchapp install
Then, open a new Sketch document and, from the menu, select Plugins > From *Almost* Sketch to Sketch
. In the file picker, select both document.asketch.json
and page.asketch.json
, and click Choose
.
Congratulations! You should now have your symbols, text styles and document colors available within Sketch! 💎🎉
Contributing
Refer to CONTRIBUTING.md.
License
MIT.