Repository files navigation

Quickly generateSketch libraries from HTML documents and living style guides, powered byhtml-sketchapp andPuppeteer.

Add some simple markup to your page, for example:

<divdata-sketch-symbol="Button/Primary">...</div><divdata-sketch-text="Heading">...</div><divdata-sketch-color="#212121">...</div>

Then run thehtml-sketchapp command to generate JSON files in html-sketchapp's"Almost Sketch" format, ready to beimported into Sketch.

$ html-sketchapp --file sketch.html --out-dir dist/sketch

Please note: html-sketchapp-cli requiresNode.js and targets the latest"Active LTS" version. Older versions of Node are unsupported.

If you're in a hurry and just want to try it out, you can install html-sketchapp-cli globally, along with html-sketchapp's Sketch plugin:

$ npm install --global html-sketchapp-cli$ html-sketchapp install

However, when using html-sketchapp-cli in the context of a project, you should install it locally instead:

$ npm install --save-dev html-sketchapp-cli

Then, add some scripts to yourpackage.json:

{"scripts": {"html-sketchapp-install":"html-sketchapp install","html-sketchapp":"html-sketchapp [...args]"  }}

Once these scripts have been added, the following commands can be run within your project:

$ npm run html-sketchapp-install$ npm run html-sketchapp

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 withdata-sketch-symbol attributes. Note that forward slashes will create nested menu items within Sketch.

<divdata-sketch-symbol="Button/Primary">  ...</div>

Annotatenested symbols withdata-sketch-symbol-instance attributes, where the attribute values reference existing symbols defined elsewhere in the document.

<divdata-sketch-symbol="Icon/Reply">...</div><divdata-sketch-symbol="Icon/Retweet">...</div><divdata-sketch-symbol="Icon/Like">...</div><divdata-sketch-symbol="IconRow"><divdata-sketch-symbol-instance="Icon/Reply">...</div><divdata-sketch-symbol-instance="Icon/Retweet">...</div><divdata-sketch-symbol-instance="Icon/Like">...</div></div>

Annotate all text styles withdata-sketch-text attributes.

<divdata-sketch-text="Heading">  ...</div>

Annotate all colors withdata-sketch-color attributes. Note that colors are unnamed in Sketch, so only the hex value needs to be provided.

<divdata-sketch-color="#212121">  ...</div>

For a real world example, check outSEEK Style Guide's sketch exports page and the correspondingsource code.

If your page is self-contained, you can import from a local HTML file.

$ html-sketchapp --file sketch.html --out-dir dist

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

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

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 asButton/Primary/Desktop andButton/Primary/Mobile.

Optionally, you can set the pixel density for a given viewport by adding an@ followed by the desired scaling factor to the end of the viewport's resolution. For example, you can simulate a 1.5x and 2x display like so:

$ html-sketchapp --viewports.HigherDensity 1024x768@1.5 --viewports.Retina 1024x768@2 --file sketch.html --out-dir dist

If no scaling factor is provided, a default of1 will be used.

All options can be provided via anhtml-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

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, selectPlugins > From *Almost* Sketch to Sketch. In the file picker, select bothdocument.asketch.json andpage.asketch.json, and clickChoose.

Congratulations! You should now have your symbols, text styles and document colors available within Sketch! 💎🎉

If you need to see what Puppeteer is doing, you can provide the--debug flag which will do the following things:

• Turn off headless mode
• Bring the browser window to the front
• Forwardconsole calls to the terminal
• Stop the browser from closing until you exit the CLI tool

For example:

$ html-sketchapp --url http://localhost:3000 --out-dir dist --debug

If you need to provide command line arguments to the browser instance viaPuppeteer, you can provide thepuppeteer-args option.

Since Puppeteer usesChromium internally, you can refer to theList 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, youmust use an equals sign and quotes when providing this option via the command line (as seen above).

By default, Puppeteer is configured to consider the page loaded when there are no more than 2 network connections for at least 500ms (networkidle2). This is so that html-sketchapp-cli can handle development environments with long-lived connections.

If the page you're requesting has 2 or fewer resources that stall for longer than 500ms and doesn't complete loading, you can switch back tonetworkidle0 via thepuppeteer-wait-until argument:

$ html-sketchapp --puppeteer-wait-until networkidle0 --file sketch.html --out-dir dist

For the full list of available options forwaitUntil, view thePuppeteerpage.goto() API documentation.

If you'd like to override the Chromium used by Puppeteer, you can provide a path to the executable with thepuppeteer-executable-path option.

$ html-sketchapp --puppeteer-executable-path google-chrome-unstable --file sketch.html --out-dir dist

If you need to call out to lower-level html-sketchapp APIs, you can provide middleware functions that allow you to modify the underlying Sketch classes as they're generated.

It's recommended that you provide middleware via aconfig file as inline functions, for example:

module.exports={symbolLayerMiddleware:(args)=>{ ...}};

Alternatively, you can also provide middleware as standalone JavaScript files, configured via the command line:

$ html-sketchapp --symbol-layer-middleware symbol.layer.middleware.js

This assumes that your middleware is a JavaScript module that exports the function:

module.exports=(args)=>{ ...};

However, in order to keep the documentation streamlined, all examples will use the config file notation.

This middleware is executed for every layer within a symbol.

The typical use case for this is html-sketchapp'slayer.setResizingConstraint API which allows you to configure how a layer should behave when a symbol is resized.

module.exports={symbolLayerMiddleware:args=>{ ...}};

The following arguments are passed into your middleware function:

• layer: the html-sketchapp layer instance
• SVG: The SVG class for type checking of layer
• Text: The Text class for type checking of layer
• Rectangle: The Rectangle class for type checking of layer
• ShapeGroup: The ShapeGroup class for type checking of layer
• RESIZING_CONSTRAINTS: Object containing constants for thesetResizingConstraint API

For example, when handling SVGs differently from other layers:

module.exports={symbolLayerMiddleware:(args)=>{const{ layer,SVG,RESIZING_CONSTRAINTS}=args;layer.setResizingConstraint(RESIZING_CONSTRAINTS.LEFT,RESIZING_CONSTRAINTS.TOP);if(layerinstanceofSVG){layer.setResizingConstraint(RESIZING_CONSTRAINTS.TOP,RESIZING_CONSTRAINTS.LEFT,RESIZING_CONSTRAINTS.WIDTH,RESIZING_CONSTRAINTS.HEIGHT);}}};

This middleware is executed for every symbol within a document.

module.exports={symbolMiddleware:args=>{ ...}};

The following arguments are passed into your middleware function:

• symbol: The current symbol master
• node: The source HTML node
• suffix: The symbol name suffix (e.g./Desktop)
• RESIZING_CONSTRAINTS: Object containing constants for thesetResizingConstraint API

This middleware is executed for every symbol instance within a document.

module.exports={symbolInstanceMiddleware:args=>{ ...}};

The following arguments are passed into your middleware function:

• symbolInstance: The current symbol instance
• symbolMaster: The symbol master that the symbol instance is referencing
• node: The source HTML node
• RESIZING_CONSTRAINTS: Object containing constants for thesetResizingConstraint API

Refer toCONTRIBUTING.md.

MIT.