{"id":22403328,"url":"https://github.com/springload/grunticon-pigment","last_synced_at":"2025-07-31T16:31:53.251Z","repository":{"id":18407022,"uuid":"21588688","full_name":"springload/grunticon-pigment","owner":"springload","description":"Fork of filamentgroup grunt-grunticon. Creates colourised versions of SVG icons.","archived":false,"fork":false,"pushed_at":"2019-08-05T04:55:05.000Z","size":62,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":35,"default_branch":"master","last_synced_at":"2024-11-07T20:13:59.963Z","etag":null,"topics":["grunticon","grunticon-pigment","pigment","svg-icons"],"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/springload.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-07-07T22:13:57.000Z","updated_at":"2017-04-11T16:03:08.000Z","dependencies_parsed_at":"2022-09-02T06:44:26.922Z","dependency_job_id":null,"html_url":"https://github.com/springload/grunticon-pigment","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springload%2Fgrunticon-pigment","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springload%2Fgrunticon-pigment/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springload%2Fgrunticon-pigment/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/springload%2Fgrunticon-pigment/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/springload","download_url":"https://codeload.github.com/springload/grunticon-pigment/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228267806,"owners_count":17893841,"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":["grunticon","grunticon-pigment","pigment","svg-icons"],"created_at":"2024-12-05T09:16:48.922Z","updated_at":"2024-12-05T09:16:50.346Z","avatar_url":"https://github.com/springload.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"grunt-grunticon-pigment [![npm](https://img.shields.io/npm/v/grunt-grunticon-pigment.svg?style=flat-square)](https://www.npmjs.com/package/grunt-grunticon-pigment) [![Build Status](https://img.shields.io/travis/springload/grunticon-pigment.svg?style=flat-square)](https://travis-ci.org/springload/grunticon-pigment)\n===========================\n\n\u003e A collection of grunt tasks around filamentgroup's grunticon, that also creates colourised versions of svg images\n\nWith grunticon-pigment we combined several grunt tasks into one handy plugin. It's basically copies [grunticon](https://github.com/filamentgroup/grunticon)'s funciontality, applies some new default values and adds the ability to create colour variations without significantly increasing filesize.\n\n### A mystical CSS icon solution\n\ngrunticon is a [Grunt.js](https://github.com/cowboy/grunt/) task that makes it easy to manage icons and background images for all devices, preferring HD (retina) SVG icons but also provides fallback support for standard definition browsers, and old browsers alike. From a CSS perspective, it's easy to use, as it generates a class referencing each icon, and doesn't use CSS sprites.\n\ngrunticon takes a [folder of SVG/PNG files](https://github.com/filamentgroup/grunticon/tree/master/example/source) (typically, icons that you've drawn in an application like Adobe Illustrator), and [outputs them](https://github.com/filamentgroup/grunticon/tree/master/example/output) to CSS in 3 formats: [svg data urls](https://github.com/filamentgroup/grunticon/blob/master/example/output/icons.data.svg.css), [png data urls](https://github.com/filamentgroup/grunticon/blob/master/example/output/icons.data.png.css), and [a third fallback CSS file with references to regular png images](https://github.com/filamentgroup/grunticon/blob/master/example/output/icons.fallback.css), which are also automatically [generated and placed in a folder](https://github.com/filamentgroup/grunticon/tree/master/example/output/png).\n\ngrunticon also generates [a small bit of JavaScript and CSS](https://github.com/filamentgroup/grunticon/blob/master/tasks/grunticon/static/grunticon.loader.js) to drop into your site, which asynchronously loads the appropriate icon CSS depending on a browser's capabilities, and a preview HTML file with that loader script in place.\n\n\n## Getting Started\nThis plugin requires Grunt `~0.4.5`\n\nIf you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:\n\n```shell\nnpm install grunt-grunticon-pigment --save-dev\n```\n\nOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:\n\n```js\ngrunt.loadNpmTasks('grunt-grunticon-pigment');\n```\n\n## The \"grunticon_pigment\" task\n\n### Overview\nIn your project's Gruntfile, add a section named `grunticon_pigment` to the data object passed into `grunt.initConfig()`.\n\n```js\ngrunt.initConfig({\n  grunticon_pigment: {\n    foo: {\n        files: [{\n            cwd: 'example/source',\n            dest: 'example/output'\n        }],\n        options: {\n            ...\n        }\n    },\n  },\n});\n```\n\n\n### Options\n\n#### options.svgFolder\nType: `String`\nDefault value: `\"source\"`\n\nThe name of the folder containing the source svg files.\n\n#### options.svgColorFolder\nType: `String`\nDefault value: `\"source-colourise\"`\n\nThe name of the folder containing the source svg files that get colourised.\n\n*Please note* All elements of the svg files must be within one grouped element at root level.\nOnly shapes will be colourised, so make sure, to convert strokes into outlines (Object \u003e Path \u003e Outline Stroke in Illustrator) before saving your svg.\nPlease also have a look at [Creating SVG Artwork](#creating-svg-artwork) in the Tips section.\n\n#### options.svgColors\nType: `Array`\nDefault value: `\"[]\"`\n\nArray of colour variations in hex format.\n\n#### options.datasvgcss\nType: `String`\nDefault value: `\"icons-data-svg.css\"`\n\nThe name of the generated CSS file containing SVG data uris.\n\n#### options.datapngcss\nType: `String`\nDefault value: `\"icons-data-png.css\"`\n\nThe name of the generated CSS file containing PNG data uris.\n\n#### options.urlpngcss\nType: `String`\nDefault value: `\"icons-fallback.css\"`\n\nThe name of the generated CSS file containing external png url references.\n\n#### options.previewhtml\nType: `String`\nDefault value: `\"icons-preview.html\"`\n\nThe name of the generated HTML preview file.\n\n#### options.loadersnippet\nType: `String`\nDefault value: `\"grunticon-loader.txt\"`\n\n The name of the generated text file containing the grunticon loading snippet.\n\n#### options.pngfolder\nType: `String`\nDefault value: `\"png\"`\n\n The name of the generated folder containing the generated PNG images.\n\n#### options.pngpath\nType: `String`\nDefault value: value of `options.pngfolder`\n\nAllows you to specify a custom URL to serve fallback PNGs at.\n\nExample:\n\n```\n{\n    pngpath: \"/assets/icons/png\"\n}\n```\n\nWill generate PNG fallbacks like:\n\n```\n.i-bar {\n\tbackground-image: url('/assets/icons/png/bar.png');\n\tbackground-repeat: no-repeat;\n}\n```\n\n#### options.cssprefix\nType: `String`\nDefault value: `\".i-\"`\n\na string to prefix all css classes with.\n\n#### options.customselectors\nType: `Object`\n\nAllows you to specify custom selectors (in addition to the generated `cssprefix + filename - extension` class) for individual files.\n\nExample:\n\n```\n{\n\t\"foo\": [\".i-bar\", \".baz\"]\n}\n```\n\nwill produce:\n\n```\n.i-bar,\n.bar,\n.i-foo {\n\t//css\n}\n```\n\nYou can also use an asterisk in your custom selector!\n\nExamples:\n\n```\ncustomselectors: {\n  \"*\": [\".i-$1:before\", \".i-$1-what\", \".hey-$1\"]\n},\nprefix: \".i-\"\n```\n\nShould give the file bear.svg the css\n```\n.i-bear:before,\n.i-bear-what,\n.hey-bear,\n.i-bear {\n // CSS THINGS\n}\n```\n\nAnd if there are files bear.svg and cat.svg, the css should be like:\n\n```\n.i-bear:before,\n.i-bear-what,\n.hey-bear,\n.i-bear {\n // CSS THINGS\n}\n\n.i-cat:before,\n.i-cat-what,\n.hey-cat,\n.i-cat {\n // CSS THINGS\n}\n```\n\nThis should give you more flexibility with your selectors.\n\n#### options.defaultWidth\nType: `String`\nDefault value: `\"32px\"`\n\na string that MUST be defined in px that will be the size of the PNG if there is no width given in the SVG element.\n\n#### options.defaultHeight\nType: `String`\nDefault value: `\"32px\"`\n\nsimilar to defaultWidth, but for height\n\n#### options.previewTemplate\nType: `String`\nDefault value: Goes to the example/preview.hbs file\n\nTakes a path to the template that will be used for the preview.html. Example of .hbs file contents:\n\n```\n\u003c!doctype HTML\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003eIcons Preview!\u003c/title\u003e\n    \u003cstyle\u003e\n      body {\n        background-image: linear-gradient(#eee 25%, transparent 25%, transparent), linear-gradient(#eee 25%, transparent 25%, transparent), linear-gradient(transparent 75%, #eee 75%), linear-gradient(transparent 75%, #eee 75%);\n        width: 100%;\n        background-size: 10px 10px;\n      }\n    \u003c/style\u003e\n    \u003cscript\u003e\n      {{{loaderText}}}\n      grunticon([\"icons-data-svg.css\", \"icons-data-png.css\", \"icons-fallback.css\"]);\n    \u003c/script\u003e\n  \u003cnoscript\u003e\u003clink href=\"icons-fallback.css\" rel=\"stylesheet\"\u003e\u003c/noscript\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    {{#each icons}}\n      {{#with this}}\n      \u003cpre\u003e\u003ccode\u003e{{prefix}}{{name}}:\u003c/code\u003e\u003c/pre\u003e\u003cdiv class=\"{{prefixClass}}{{name}}\" style=\"width: {{width}}px; height: {{height}}px;\" \u003e\u003c/div\u003e\u003chr/\u003e\n      {{/with}}\n    {{/each}}\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n#### options.tmpDir\nType: `String`\nDefault value: `\"grunticon-tmp\"`\n\nLet's you specify a tmp-folder. Useful when having multiple grunticon tasks and using [grunt-concurrent](https://github.com/sindresorhus/grunt-concurrent \"grunt-concurrent on github\").\n\n#### options.template\nType: `String`\nDefault value: `\"\"`\n\nLocation of a handlebars template that will allow you to structure your\nCSS file the way that you choose. As more data becomes available via\n[directory-encoder](https://github.com/filamentgroup/directory-encoder),\nmore options will be available for you to tap into during templating.\n\n\nExample of .hbs file contents:\n\n```\n{{#each customselectors}}{{this}},{{/each}}\n{{prefix}}{{name}} {\n\tbackground-image: url('{{datauri}}');\n\tbackground-repeat: no-repeat;\n}\n```\n\n\n#### options.colors\n\nAllows you to predefine colors as variables that can be used in filename color configuration.\n\n\n#### Automating color variations\n\nGrunticon allows you to output any icon in different colors simply by changing its filename to the following syntax: `myfilename.colors-red-aa0000-gray.svg`. In this example, any color names or hexidecimal values that follow `colors-` and are separated by a dash will be used to generate additional icons of that color. By default, each icon will be assigned a numbered class name for CSS use. You can improve the class naming conventions by defining color variables in your Gruntfile's `colors` option shown above. When defined, you can reference a color variable in place of a color in your file names, and the generated classes will use that variable name as well. See the `Gruntfile.js`'s `colors` option and the sample bear svg for an example of color automation.\n\n*A note on filesize impact:* Adding color variations of an icon involves creating duplicates of that icon's SVG source in the CSS, so unfortunately, each color variation will cause an increase in filesize. However, transferring CSS with gzip compression can negate much of this filesize increase, and we highly recommend always transferring with gzip. In testing, we found that creating a color variation of every icon in our example set increased overall size by 25%, rather than 100% as a raw text duplicate would increase. That said, size increases for non-SVG-supporting browsers will be more dramatic, as the fallback PNGs will not have the heavy transfer compression as SVG enjoys. We advise using this feature on a case-by-case basis to ensure overhead is kept to a minimum.\nTo avoid blowing up filesize, please use the svgColors option\n\n### Usage Examples\n\n#### Default Options\n\n```js\ngrunt.initConfig({\n  grunticon_pigment: {\n    options: {\n        // CSS filenames\n        datasvgcss: \"icons-data-svg.css\",\n        datapngcss: \"icons-data-png.css\",\n        urlpngcss: \"icons-fallback.css\",\n\n        // preview HTML filename\n        previewhtml: \"icons-preview.html\",\n\n        // grunticon loader code snippet filename\n        loadersnippet: \"grunticon-loader.js\",\n\n        // folder name (within cwd) for svg files\n        svgFolder: \"source\",\n        svgColorFolder: \"source-colourise\",\n\n        // folder name (within dest) for png output\n        pngfolder: \"png\",\n\n        // prefix for CSS classnames\n        cssprefix: \".i-\",\n\n        defaultWidth: \"32px\",\n        defaultHeight: \"32px\",\n\n        // colours for svg colourising\n        svgColors: [\"#ffffff\", \"#A6CC85\"],\n\n        // css file path prefix - this defaults to \"/\" and will be placed before the \"dest\" path when stylesheets are loaded.\n        // This allows root-relative referencing of the CSS. If you don't want a prefix path, set to to \"\"\n        cssbasepath: \"\",\n        customselectors: {\n            \"twitter\": [\".alternative-selector\"]\n        },\n\n        // templates for css output and preview page\n        template: \"template/default-css.hbs\",\n        previewTemplate:  \"template/preview-custom.hbs\"\n    },\n    files: [{\n        cwd: 'example/source',\n        dest: 'example/output'\n    }],\n  },\n});\n```\n\n\n\n\n\n## Browser testing results for icon output\n\nThe generated asynchronous CSS loader script delivers an appropriate icon stylesheet depending on a device/browser's capabilities. Grunticon is supported in cases where icon fonts fail.\n\nBrowsers that render the SVG data url stylesheet:\n- IE9\n- Chrome 14+ (maybe older too?)\n- Safari 4+ (maybe older too?)\n- Firefox 3.6+ (maybe older too?)\n- Opera 15+\n- iOS 3+ Safari and Chrome\n- Android 4.0 Chrome (caveat: SVG icons do not scale in vector, but do appear to draw in high-resolution)\n- Android 4.0 ICS Browser\n- BlackBerry Playbook\n\nBrowsers that receive the PNG data url stylesheet:\n- IE8\n- All versions of Opera, Opera Mini, and Opera Mobile before Chrome integration (v 15)\n- Android 2.3 Browser\n- Android 2.2 Browser\n- Android 2.1 Browser\n- Android 1.6 Browser\n- Android 1.5 Browser\n\nBrowsers that receive the fallback png request:\n- IE7\n- IE6\n- Non-JavaScript environments\n\nView the full support spreadsheet [here](https://docs.google.com/spreadsheet/ccc?key=0Ag5_yGvxpINRdHFYeUJPNnZMWUZKR2ItMEpRTXZPdUE#gid=0). Feel free to edit it if you find anything new.\n\nThe test page can be found [here](http://filamentgroup.com/examples/grunticon-icon-test/).\n\n## Tips\n\n### Serving compressed CSS\nOne of the great benefits to data uris is the ability to compress the images heavily via gzip compression. Be sure to enable gzip of CSS on your server, as it'll cut your icon transfer size greatly.\n\n### Creating SVG Artwork\n\nThe workflow we've been using so far involves creating a new Illustrator file with the artboard set to the desired size of the icon you want set in the CSS.\n\nExport the artwork by choosing File \u003e Save as...  In the dialog, choose \"SVG\" as the format and enter a name for the file (this wil be used as your class name later, so keep it free of any disallowed CSS class characters like `.`, `{`, `(`, `)`, etc.\n\nIn the Save SVG dialog that opens up, there are lots of options. SVG has a ton of formats, so here are a few tips we've learned.\n\n- SVG Profile: Seems like SVG 1.1 Tiny is really well supported across even older mobile platforms so if you have simple artwork that doesn't use gradients or opacity this will yield a smaller and more compatible graphic. If you want to use all the fancy effects, save artwork as SVG 1.1.\n- Type: Convert to outline before export.\n- Subsetting: None, I usually convert all text to outlines ahead of time\n- Images: Embed\n- Don't check \"Preserve Illustrator editing\" to reduce file size\n- Don't check \"Responsive\" unless you want the fallback pngs to get defaultWidth and defaultHeight.\n\n## Warnings\n* If your files have `#`, `.`, `\u003e`, or any other css selecting character in their names, they will likely be improperly processed.\n\n## Contributing\n\n```js\ngit clone git@github.com:springload/grunticon-pigment.git\ncd grunticon-pigment/\nnvm install\nnpm install\nnpm run test\n```\n\n## Release History\n\n* Version 1.0.0: Re-removed postinstall script.\n* Version 0.2.8: Reintroduced postinstall script.\n* Version 0.2.5: Upgraded npm dependencies and removed postinstall script.\n* Version 0.2.0: First stable release.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringload%2Fgrunticon-pigment","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspringload%2Fgrunticon-pigment","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringload%2Fgrunticon-pigment/lists"}