Icon Assets

Introduction

Icons are the files under icons/ of an app. They are not drawn or exported here: the folder holds a copy of the build output of Chassis Icons, which the build then copies to each platform.

The web output gets every file of the folder. iOS gets the SVG, PDF and PNG files, and Android gets the SVG files, each with the ic_ prefix. The build copies an icon as it is. With the --vector-drawables option it writes the SVG icons of Android as vector drawables.

Source layout

Icons live in source/<brand>/<app>/icons/, in the two folders that Chassis Icons writes: icons/ for the icon font, its stylesheets and the sprite, and svgs/ for one SVG file per icon.

source/default/docs/icons/
├── cx-sprite.svg                  -> a sprite of this repository, not of Chassis Icons
├── icons/
│   ├── chassis-icons.css
│   ├── chassis-icons.json
│   ├── chassis-icons.min.css
│   ├── chassis-icons.scss
│   ├── chassis-icons.svg          -> the sprite of every icon
│   ├── chassis-icons.woff
│   └── chassis-icons.woff2
└── svgs/
    ├── arrow-right-outline.svg
    ├── arrow-right-solid.svg
    └── ...

A brand with icons of its own has the same two folders under source/<brand>/<app>/icons/. A brand file replaces the default file of the same path, so a brand may also replace single icons under svgs/ and take the rest from the default brand.

Formats

Each platform keeps the formats it can use, and the build leaves the rest out.

The icon font and its stylesheets are for the web, so the apps get the SVG files only. An Android app draws an icon from a vector drawable: a build with --vector-drawables writes one per SVG file, and Vector Asset Studio of Android Studio makes one from a single file.

Naming

An icon is named after what it shows, followed by its style: arrow-right-solid.svg, arrow-right-outline.svg. The names are those of Chassis Icons, and a brand with icons of its own keeps them, so that an app refers to arrow-right-solid whichever brand it is built for.

The build renames each file for the platform. On Android it also adds the ic_ prefix to every file under icons/, unless the name starts with it already.

Adding files

The files of icons/icons/ and icons/svgs/ are the build output of another project. Change an icon in Chassis Icons, build it there, and copy the output here.

Refreshing the copy

The default brand of this repository holds the icons of the @chassis-ui/icons package, which ships the two folders as they are. Install the dependencies, replace the folders of each app with those of the package, and build:

pnpm install
for app in docs demo; do
  rm -rf source/default/$app/icons/icons source/default/$app/icons/svgs
  cp -r packages/site/node_modules/@chassis-ui/icons/icons source/default/$app/icons/icons
  cp -r packages/site/node_modules/@chassis-ui/icons/svgs source/default/$app/icons/svgs
done
pnpm assets

The icon font files are Git LFS files, so make the commit on a machine with Git LFS. Compare dist/ before and after: an icon that was under icons/svgs/ and is gone breaks an app that reads it by name.

Brand icons

A brand with another icon style builds its own set with Chassis Icons, under the same icon names, and copies the output to source/<brand>/<app>/icons/. The Chassis Icons docs describe how a set is drawn and built.

Integration

Chassis Icons owns the icons: the drawings, the icon font, the sprite and the class names of the stylesheets. Chassis Assets stores a copy of its output per brand and app, and gives each platform the files it can use under the names it expects.

The Chassis Icons docs show every icon with its name and describe how a page uses the font and the sprite.

Best practices

The icon files are a copy of the output of Chassis Icons. These practices keep the copy whole and the icon names stable across brands.

• Keep the icon names across brands: an app that shows arrow-right-solid gets the drawing of the brand it is built for. A brand that renames an icon needs a change in every app.
• Refresh both folders together: icons/icons/ and icons/svgs/ come from one build of Chassis Icons. A font from one version and SVG files from another disagree on the icons they hold.
• Refresh every app of the brand: docs and demo of the default brand each hold a copy.

Avoid the habits that undo this:

• Do not put other images under icons/: Android adds the ic_ prefix to every file of the folder, and the apps get only the formats of the table above. A logo or an illustration belongs under images/.

Platform output

The build copies each file to the icons/ folder of the job, in its subfolder, and renames it for the platform.

The web output of the configured web app keeps every file. The dot inside a name becomes a hyphen, so chassis-icons.min.css is chassis-icons-min.css:

dist/web/docs/chassis/icons/
├── cx-sprite.svg
├── icons/
│   ├── chassis-icons-min.css
│   ├── chassis-icons.css
│   ├── chassis-icons.json
│   ├── chassis-icons.scss
│   ├── chassis-icons.svg
│   ├── chassis-icons.woff
│   └── chassis-icons.woff2
└── svgs/
    ├── arrow-right-outline.svg
    ├── arrow-right-solid.svg
    └── ...

The iOS output of the configured app holds the sprite and the SVG file of each icon:

dist/ios/demo/chassis/icons/
├── icons/
│   └── chassis_icons.svg
└── svgs/
    ├── arrow_right_outline.svg
    ├── arrow_right_solid.svg
    └── ...

The Android output holds the same files with the prefix:

dist/android/demo/chassis/icons/
├── icons/
│   └── ic_chassis_icons.svg
└── svgs/
    ├── ic_arrow_right_outline.svg
    ├── ic_arrow_right_solid.svg
    └── ...

A build with pnpm assets --vector-drawables writes each of these SVG files as a vector drawable of the same name. The SVG file of the icon font has no shape to draw, so it stays, and the build warns about it:

dist/android/demo/chassis/icons/
├── icons/
│   └── ic_chassis_icons.svg
└── svgs/
    ├── ic_arrow_right_outline.xml
    ├── ic_arrow_right_solid.xml
    └── ...

See the web, iOS, and Android docs for how an app uses these files.