{"id":13398044,"url":"https://github.com/seek-oss/html-sketchapp-cli","last_synced_at":"2025-03-14T00:32:54.975Z","repository":{"id":37430953,"uuid":"114723597","full_name":"seek-oss/html-sketchapp-cli","owner":"seek-oss","description":"Quickly generate Sketch libraries from HTML documents and living style guides, powered by html-sketchapp","archived":true,"fork":false,"pushed_at":"2024-03-25T01:49:37.000Z","size":101,"stargazers_count":636,"open_issues_count":16,"forks_count":30,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-10T06:51:44.182Z","etag":null,"topics":["design","design-systems","design-tools","front-end","sketch","sketch-plugin","sketchapp","style-guides"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seek-oss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-19T05:38:16.000Z","updated_at":"2025-03-05T03:32:24.000Z","dependencies_parsed_at":"2022-07-12T13:19:36.826Z","dependency_job_id":"9f96ad59-8861-4aeb-b9cb-8780e8a1af25","html_url":"https://github.com/seek-oss/html-sketchapp-cli","commit_stats":{"total_commits":44,"total_committers":9,"mean_commits":4.888888888888889,"dds":"0.34090909090909094","last_synced_commit":"c829ee2ea623702e131033d357827b92efa8ce77"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seek-oss%2Fhtml-sketchapp-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seek-oss%2Fhtml-sketchapp-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seek-oss%2Fhtml-sketchapp-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seek-oss%2Fhtml-sketchapp-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seek-oss","download_url":"https://codeload.github.com/seek-oss/html-sketchapp-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243505189,"owners_count":20301572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design","design-systems","design-tools","front-end","sketch","sketch-plugin","sketchapp","style-guides"],"created_at":"2024-07-30T18:02:03.636Z","updated_at":"2025-03-14T00:32:53.990Z","avatar_url":"https://github.com/seek-oss.png","language":"JavaScript","readme":"[![Build Status](https://img.shields.io/travis/seek-oss/html-sketchapp-cli/master.svg?style=flat-square)](http://travis-ci.org/seek-oss/html-sketchapp-cli) [![npm](https://img.shields.io/npm/v/html-sketchapp-cli.svg?style=flat-square)](https://www.npmjs.com/package/html-sketchapp-cli) [![David](https://img.shields.io/david/seek-oss/html-sketchapp-cli.svg?style=flat-square)](https://david-dm.org/seek-oss/html-sketchapp-cli) [![David](https://img.shields.io/david/dev/seek-oss/html-sketchapp-cli.svg?style=flat-square)](https://david-dm.org/seek-oss/html-sketchapp-cli?type=dev) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square)](http://commitizen.github.io/cz-cli/)\n\n# html-sketchapp-cli\n\nQuickly generate [Sketch libraries](https://www.sketchapp.com/docs/libraries/) from HTML documents and living style guides, powered by [html-sketchapp](https://github.com/brainly/html-sketchapp) and [Puppeteer](https://github.com/GoogleChrome/puppeteer).\n\nAdd some simple markup to your page, for example:\n\n```html\n\u003cdiv data-sketch-symbol=\"Button/Primary\"\u003e...\u003c/div\u003e\n\u003cdiv data-sketch-text=\"Heading\"\u003e...\u003c/div\u003e\n\u003cdiv data-sketch-color=\"#212121\"\u003e...\u003c/div\u003e\n```\n\nThen run the `html-sketchapp` command to generate JSON files in html-sketchapp's [\"Almost Sketch\"](https://github.com/brainly/html-sketchapp#how-does-it-work) format, ready to be [imported into Sketch](#importing-into-sketch).\n\n```bash\n$ html-sketchapp --file sketch.html --out-dir dist/sketch\n```\n\n## Install\n\n*Please note: html-sketchapp-cli requires [Node.js](https://nodejs.org/) and targets the latest [\"Active LTS\" version](https://github.com/nodejs/Release#release-schedule). Older versions of Node are unsupported.*\n\nIf 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:\n\n```bash\n$ npm install --global html-sketchapp-cli\n$ html-sketchapp install\n```\n\nHowever, when using html-sketchapp-cli in the context of a project, you should install it locally instead:\n\n```bash\n$ npm install --save-dev html-sketchapp-cli\n```\n\nThen, add some scripts to your [package.json](https://docs.npmjs.com/files/package.json):\n\n```json\n{\n  \"scripts\": {\n    \"html-sketchapp-install\": \"html-sketchapp install\",\n    \"html-sketchapp\": \"html-sketchapp [...args]\"\n  }\n}\n```\n\nOnce these scripts have been added, the following commands can be run within your project:\n\n```bash\n$ npm run html-sketchapp-install\n$ npm run html-sketchapp\n```\n\n## Page Setup\n\nBefore using this tool, you'll need to add some hooks to your page so that everything can be selected, extracted and named correctly.\n\nAnnotate symbols with `data-sketch-symbol` attributes. Note that forward slashes will create nested menu items within Sketch.\n\n```html\n\u003cdiv data-sketch-symbol=\"Button/Primary\"\u003e\n  ...\n\u003c/div\u003e\n```\n\nAnnotate [nested symbols](https://www.sketchapp.com/docs/symbols/nested-symbols) with `data-sketch-symbol-instance` attributes, where the attribute values reference existing symbols defined elsewhere in the document.\n\n```html\n\u003cdiv data-sketch-symbol=\"Icon/Reply\"\u003e...\u003c/div\u003e\n\u003cdiv data-sketch-symbol=\"Icon/Retweet\"\u003e...\u003c/div\u003e\n\u003cdiv data-sketch-symbol=\"Icon/Like\"\u003e...\u003c/div\u003e\n\n\u003cdiv data-sketch-symbol=\"IconRow\"\u003e\n  \u003cdiv data-sketch-symbol-instance=\"Icon/Reply\"\u003e...\u003c/div\u003e\n  \u003cdiv data-sketch-symbol-instance=\"Icon/Retweet\"\u003e...\u003c/div\u003e\n  \u003cdiv data-sketch-symbol-instance=\"Icon/Like\"\u003e...\u003c/div\u003e\n\u003c/div\u003e\n```\n\nAnnotate all text styles with `data-sketch-text` attributes.\n\n```html\n\u003cdiv data-sketch-text=\"Heading\"\u003e\n  ...\n\u003c/div\u003e\n```\n\nAnnotate all colors with `data-sketch-color` attributes. Note that colors are unnamed in Sketch, so only the hex value needs to be provided.\n\n```html\n\u003cdiv data-sketch-color=\"#212121\"\u003e\n  ...\n\u003c/div\u003e\n```\n\nFor a real world example, check out [SEEK Style Guide's sketch exports page](http://seek-oss.github.io/seek-style-guide/sketch-exports) and the corresponding [source code](https://github.com/seek-oss/seek-style-guide/blob/master/docs/src/components/SketchExports/SketchExports.js).\n\n## CLI Usage\n\n### Importing from a local file\n\nIf your page is self-contained, you can import from a local HTML file.\n\n```bash\n$ html-sketchapp --file sketch.html --out-dir dist\n```\n\n### Importing from a local static web server\n\nIf 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.\n\n```bash\n$ html-sketchapp --serve docs --url /sketch --out-dir dist\n```\n\n### Importing from existing web server\n\nIf your page is hosted on an existing web server, you can provide an absolute URL.\n\n```bash\n$ html-sketchapp --url http://localhost:3000 --out-dir dist\n```\n\n### Viewport sizes and responsive design\n\nIf you provide a set of one or more named viewports, every symbol and text style will be rendered for each screen size.\n\n```bash\n$ html-sketchapp --viewports.Desktop 1024x768 --viewports.Mobile 320x568 --file sketch.html --out-dir dist\n```\n\nIf 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`.\n\nOptionally, 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:\n\n```bash\n$ html-sketchapp --viewports.HigherDensity 1024x768@1.5 --viewports.Retina 1024x768@2 --file sketch.html --out-dir dist\n```\n\nIf no scaling factor is provided, a default of `1` will be used.\n\n### Config file\n\nAll options can be provided via an `html-sketchapp.config.js` file.\n\n```js\nmodule.exports = {\n  file: 'sketch.html',\n  outDir: 'dist/sketch',\n  viewports: {\n    Desktop: '1024x768',\n    Mobile: '320x568'\n  },\n  puppeteerArgs: '--no-sandbox --disable-setuid-sandbox',\n  puppeteerExecutablePath: 'google-chrome-unstable'\n};\n```\n\nYou can provide an alternate config file path with the `--config` option.\n\n```bash\n$ html-sketchapp --config example.config.js\n```\n\n### Importing into Sketch\n\nOnce this command has successfully run, the following files will be generated in the output directory.\n\n- `document.asketch.json`\n- `page.asketch.json`\n\nThese need to be imported into Sketch via html-sketchapp's corresponding Sketch plugin. To ease the install process, you can run the following command.\n\n```bash\n$ html-sketchapp install\n```\n\nThen, open a new Sketch document and, from the menu, select `Plugins \u003e From *Almost* Sketch to Sketch`. In the file picker, select both `document.asketch.json` and `page.asketch.json`, and click `Choose`.\n\nCongratulations! You should now have your symbols, text styles and document colors available within Sketch! 💎🎉\n\n## Advanced Usage\n\n### Debug mode\n\nIf you need to see what Puppeteer is doing, you can provide the `--debug` flag which will do the following things:\n- Turn off headless mode\n- Bring the browser window to the front\n- Forward `console` calls to the terminal\n- Stop the browser from closing until you exit the CLI tool\n\nFor example:\n\n```bash\n$ html-sketchapp --url http://localhost:3000 --out-dir dist --debug\n```\n\n### Puppeteer args\n\nIf you need to provide command line arguments to the browser instance via [Puppeteer](https://github.com/GoogleChrome/puppeteer), you can provide the `puppeteer-args` option.\n\nSince Puppeteer uses [Chromium](https://www.chromium.org/Home) internally, you can refer to the [List of Chromium Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches) for available options.\n\nFor example, if you'd like to disable the browser sandbox:\n\n```bash\n$ html-sketchapp --puppeteer-args=\"--no-sandbox --disable-setuid-sandbox\" --file sketch.html --out-dir dist\n```\n\n*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).*\n\n### Puppeteer `waitUntil`\n\nBy 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.\n\nIf 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 to `networkidle0` via the `puppeteer-wait-until` argument:\n\n```bash\n$ html-sketchapp --puppeteer-wait-until networkidle0 --file sketch.html --out-dir dist\n```\n\nFor the full list of available options for `waitUntil`, view the [Puppeteer `page.goto()` API documentation](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagegotourl-options).\n\n### Chromium executable\n\nIf you'd like to override the Chromium used by Puppeteer, you can provide a path to the executable with the `puppeteer-executable-path` option.\n\n```bash\n$ html-sketchapp --puppeteer-executable-path google-chrome-unstable --file sketch.html --out-dir dist\n```\n\n### Middleware\n\nIf 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.\n\nIt's recommended that you provide middleware via a [config file](#config-file) as inline functions, for example:\n\n```js\nmodule.exports = {\n  symbolLayerMiddleware: (args) =\u003e { ... }\n};\n```\n\nAlternatively, you can also provide middleware as standalone JavaScript files, configured via the command line:\n\n```bash\n$ html-sketchapp --symbol-layer-middleware symbol.layer.middleware.js\n```\n\nThis assumes that your middleware is a JavaScript module that exports the function:\n\n```js\nmodule.exports = (args) =\u003e { ... };\n```\n\nHowever, in order to keep the documentation streamlined, all examples will use the config file notation.\n\n#### Symbol Layer Middleware\n\nThis middleware is executed for every layer within a symbol.\n\nThe typical use case for this is html-sketchapp's `layer.setResizingConstraint` API which allows you to configure how a layer should behave when a symbol is resized.\n\n```js\nmodule.exports = {\n  symbolLayerMiddleware: args =\u003e { ... }\n};\n```\n\nThe following arguments are passed into your middleware function:\n- layer: the html-sketchapp layer instance\n- SVG: The SVG class for type checking of layer\n- Text: The Text class for type checking of layer\n- Rectangle: The Rectangle class for type checking of layer\n- ShapeGroup: The ShapeGroup class for type checking of layer\n- RESIZING_CONSTRAINTS: Object containing constants for the `setResizingConstraint` API\n\nFor example, when handling SVGs differently from other layers:\n\n```js\nmodule.exports = {\n  symbolLayerMiddleware: (args) =\u003e {\n    const { layer, SVG, RESIZING_CONSTRAINTS } = args;\n\n    layer.setResizingConstraint(RESIZING_CONSTRAINTS.LEFT, RESIZING_CONSTRAINTS.TOP);\n\n    if(layer instanceof SVG) {\n      layer.setResizingConstraint(RESIZING_CONSTRAINTS.TOP, RESIZING_CONSTRAINTS.LEFT, RESIZING_CONSTRAINTS.WIDTH, RESIZING_CONSTRAINTS.HEIGHT);\n    }\n  }\n};\n\n```\n\n#### Symbol Middleware\n\nThis middleware is executed for every symbol within a document.\n\n```js\nmodule.exports = {\n  symbolMiddleware: args =\u003e { ... }\n};\n```\n\nThe following arguments are passed into your middleware function:\n- symbol: The current symbol master\n- node: The source HTML node\n- suffix: The symbol name suffix (e.g. `/Desktop`)\n- RESIZING_CONSTRAINTS: Object containing constants for the `setResizingConstraint` API\n\n\n#### Symbol Instance Middleware\n\nThis middleware is executed for every symbol instance within a document.\n\n```js\nmodule.exports = {\n  symbolInstanceMiddleware: args =\u003e { ... }\n};\n```\n\nThe following arguments are passed into your middleware function:\n- symbolInstance: The current symbol instance\n- symbolMaster: The symbol master that the symbol instance is referencing\n- node: The source HTML node\n- RESIZING_CONSTRAINTS: Object containing constants for the `setResizingConstraint` API\n\n## Contributing\n\nRefer to [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nMIT.\n","funding_links":[],"categories":["JavaScript","Sketch"],"sub_categories":["Handoff"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseek-oss%2Fhtml-sketchapp-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseek-oss%2Fhtml-sketchapp-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseek-oss%2Fhtml-sketchapp-cli/lists"}