0
# Build System
1

2
Material Design Icons includes a Gulp-based build system for generating custom sprite sheets and optimizing assets. The build system processes individual icon files into optimized sprite formats.
3

4
## Capabilities
5

6
### Gulp Tasks
7

8
Pre-configured build tasks for generating various sprite formats and optimization files.
9

10
```javascript { .api }
11
/**
12
 * Available Gulp tasks for asset processing
13
 */
14
interface GulpTasks {
15
  "png-sprites": "Generate PNG sprite sheets with CSS for each category/color";
16
  "svg-sprites": "Generate SVG sprite sheets and symbol sprites for each category";  
17
  "iconjar": "Generate IconJar integration file (.ijmap format)";
18
  "default": "Run all sprite generation tasks (png-sprites, svg-sprites, iconjar)";
19
}
20

21
// Task execution
22
gulp.task(taskName: string, taskFunction: Function): void;
23
```
24

25
**Usage Examples:**
26

27
```bash
28
# Install dependencies
29
npm install
30

31
# Run individual tasks
32
npx gulp png-sprites    # Generate PNG sprites only
33
npx gulp svg-sprites    # Generate SVG sprites only  
34
npx gulp iconjar        # Generate IconJar file only
35

36
# Run all tasks
37
npx gulp                # or npx gulp default
38
```
39

40
### PNG Sprite Generation
41

42
Creates optimized PNG sprite sheets with accompanying CSS files for web usage.
43

44
```javascript { .api }
45
/**
46
 * PNG sprite generation configuration
47
 * Processes PNG icons into sprite sheets for each category/color combination
48
 */
49
interface PngSpriteConfig {
50
  src: string;           // Source pattern: `./{category}/1x_web/*_{color}_24dp.png`
51
  style: string;         // CSS filename: `sprite-{category}-{color}.css`
52
  name: string;          // Sprite name: `sprite-{category}-{color}`
53
  engine: "sprity-gm";   // Graphics processing engine
54
  orientation: "left-right"; // Sprite layout direction
55
}
56

57
const ICON_CATEGORIES: string[] = [
58
  "action", "alert", "av", "communication", "content", "device",
59
  "editor", "file", "hardware", "image", "maps", "navigation", 
60
  "notification", "places", "social", "toggle"
61
];
62

63
const PNG_COLORS: string[] = ["black", "white", "grey600"];
64
```
65

66
**Generated Files:**
67

68
```
69
sprites/css-sprite/
70
├── sprite-action-black.png      # PNG sprite image
71
├── sprite-action-black.css      # CSS positioning rules
72
├── sprite-action-white.png      
73
├── sprite-action-white.css
74
├── sprite-action-grey600.png    
75
├── sprite-action-grey600.css
76
├── sprite-alert-black.png
77
├── sprite-alert-black.css
78
└── ...                          # All category/color combinations
79
```
80

81
### SVG Sprite Generation
82

83
Generates SVG-based sprites in both traditional and symbol formats.
84

85
```javascript { .api }
86
/**
87
 * SVG sprite configuration
88
 * Creates both CSS-positioned sprites and symbol-based sprites
89
 */
90
interface SvgSpriteConfig {
91
  shape: {
92
    dimension: {
93
      maxWidth: 24;
94
      maxHeight: 24;
95
    };
96
  };
97
  mode: {
98
    css: {
99
      bust: false;
100
      dest: "./";
101
      sprite: `./svg-sprite-{category}.svg`;
102
      example: `./svg-sprite-{category}.html`;
103
      render: {
104
        css: {
105
          dest: `./svg-sprite-{category}.css`;
106
        };
107
      };
108
    };
109
    symbol: {
110
      bust: false; 
111
      dest: "./";
112
      sprite: `./svg-sprite-{category}-symbol.svg`;
113
      example: `./svg-sprite-{category}-symbol.html`;
114
    };
115
  };
116
}
117
```
118

119
**Generated Files:**
120

121
```
122
sprites/svg-sprite/
123
├── svg-sprite-action.svg              # SVG sprite sheet
124
├── svg-sprite-action.css              # CSS positioning
125
├── svg-sprite-action.html             # Usage example
126
├── svg-sprite-action-symbol.svg       # SVG symbol sprite
127
├── svg-sprite-action-symbol.html      # Symbol usage example
128
└── ...                                # All categories
129
```
130

131
### IconJar Integration
132

133
Generates metadata files for IconJar icon management application.
134

135
```javascript { .api }
136
/**
137
 * IconJar integration file generation
138
 * Converts codepoints to IconJar .ijmap format
139
 */
140
interface IconJarConfig {
141
  src: "./iconfont/codepoints";
142
  dest: "./iconfont/MaterialIcons-Regular.ijmap";
143
  format: "ijmap";
144
}
145

146
/**
147
 * Generated IconJar file structure
148
 */
149
interface IjmapFormat {
150
  icons: {
151
    [codepoint: string]: {
152
      name: string; // Human-readable icon name
153
    };
154
  };
155
}
156
```
157

158
**Usage Examples:**
159

160
```javascript
161
// Generated .ijmap file content (example)
162
{
163
  "icons": {
164
    "e84d": { "name": "3d Rotation" },
165
    "eb3b": { "name": "Ac Unit" },
166
    "e190": { "name": "Access Alarm" }
167
    // ... all 932 icons
168
  }
169
}
170
```
171

172
## Build Configuration
173

174
### Dependencies
175

176
Required development dependencies for the build system:
177

178
```json { .api }
179
{
180
  "devDependencies": {
181
    "babel-core": "^6.1.2",
182
    "babel-preset-es2015": "^6.1.2", 
183
    "gulp": "^3.9.0",
184
    "gulp-if": "^2.0.0",
185
    "gulp-svg-sprite": "^1.2.14",
186
    "lodash": "^3.10.1",
187
    "sprity": "^1.0.8",
188
    "sprity-gm": "^1.0.2",
189
    "through2": "^2.0.0",
190
    "underscore.string": "^3.2.2",
191
    "vinyl": "^1.1.0"
192
  }
193
}
194
```
195

196
### Build Functions
197

198
Core utility functions used by the build system:
199

200
```javascript { .api }
201
/**
202
 * Get SVG sprite configuration for a specific category
203
 * @param category - Icon category name
204
 * @returns Sprite configuration object
205
 */
206
function getSvgSpriteConfig(category: string): SvgSpriteConfig;
207

208
/**
209
 * Generate cartesian product of categories and colors
210
 * @returns Array of [category, color] pairs for sprite generation
211
 */
212
function getCategoryColorPairs(): Array<[string, string]>;
213

214
/**
215
 * Transform codepoints file to IconJar format
216
 * @param ijmapPath - Output path for .ijmap file
217
 * @returns Transform stream for processing codepoints
218
 */
219
function generateIjmap(ijmapPath: string): NodeJS.Transform;
220
```
221

222
## Custom Build Integration
223

224
### Extending the Build System
225

226
```javascript
227
// gulpfile.custom.js - Extend existing build system
228
const gulp = require("gulp");
229
const merge = require("merge-stream");
230
const sprity = require("sprity");
231

232
// Custom task: Generate sprites for specific icons only
233
gulp.task("custom-sprites", () => {
234
  const neededIcons = [
235
    "action/1x_web/ic_home_black_24dp.png",
236
    "action/1x_web/ic_search_black_24dp.png", 
237
    "navigation/1x_web/ic_menu_black_24dp.png"
238
  ];
239
  
240
  return sprity.src({
241
    src: neededIcons,
242
    style: "custom-sprite.css",
243
    name: "custom-sprite",
244
    engine: "sprity-gm"
245
  }).pipe(gulp.dest("./build/sprites/"));
246
});
247

248
// Custom task: Copy only needed SVG files
249
gulp.task("copy-needed-svgs", () => {
250
  const neededSvgs = [
251
    "action/svg/production/ic_home_24px.svg",
252
    "action/svg/production/ic_search_24px.svg"
253
  ];
254
  
255
  return gulp.src(neededSvgs, { base: "." })
256
    .pipe(gulp.dest("./build/icons/"));
257
});
258
```
259

260
### Webpack Integration
261

262
```javascript
263
// webpack.config.js - Process sprites at build time
264
const { STATIC_PATH } = require("material-design-icons");
265
const path = require("path");
266

267
module.exports = {
268
  resolve: {
269
    alias: {
270
      "material-icons-sprites": path.join(STATIC_PATH, "sprites")
271
    }
272
  },
273
  
274
  module: {
275
    rules: [
276
      {
277
        test: /\.svg$/,
278
        include: path.join(STATIC_PATH, "sprites"),
279
        use: [
280
          {
281
            loader: "file-loader",
282
            options: {
283
              name: "sprites/[name].[ext]"
284
            }
285
          }
286
        ]
287
      }
288
    ]
289
  }
290
};
291
```
292

293
### Node.js Build Scripts
294

295
```javascript
296
// build-custom-sprites.js - Node.js build integration
297
const { STATIC_PATH } = require("material-design-icons");
298
const fs = require("fs");
299
const path = require("path");
300
const { execSync } = require("child_process");
301

302
// Copy build files to project
303
const buildFiles = [
304
  "gulpfile.babel.js",
305
  ".babelrc",
306
  "package.json"
307
];
308

309
const buildDir = "./material-icons-build";
310
fs.mkdirSync(buildDir, { recursive: true });
311

312
// Copy source files
313
buildFiles.forEach(file => {
314
  const src = path.join(STATIC_PATH, file);
315
  const dest = path.join(buildDir, file);
316
  fs.copyFileSync(src, dest);
317
});
318

319
// Install dependencies and run build
320
process.chdir(buildDir);
321
execSync("npm install", { stdio: "inherit" });
322
execSync("npx gulp", { stdio: "inherit" });
323

324
console.log("Custom sprites generated in:", path.join(buildDir, "sprites"));
325
```
326

327
## Output Structure
328

329
The build system generates a comprehensive set of optimized assets:
330

331
```
332
sprites/
333
├── css-sprite/                    # PNG-based sprites
334
│   ├── sprite-{category}-{color}.png
335
│   └── sprite-{category}-{color}.css
336
├── svg-sprite/                    # SVG-based sprites  
337
│   ├── svg-sprite-{category}.svg
338
│   ├── svg-sprite-{category}.css
339
│   ├── svg-sprite-{category}.html
340
│   ├── svg-sprite-{category}-symbol.svg
341
│   └── svg-sprite-{category}-symbol.html
342
└── iconfont/
343
    └── MaterialIcons-Regular.ijmap # IconJar integration
344
```
345

346
All generated files are optimized for production use with minimal file sizes and maximum browser compatibility.