Quick Start

Introduction

This guide takes you from a clone to a built output, adds a first file, and shows where a project picks the result up. The last section is for a team that adopts the repository for its own brands.

The README of the repository has the same setup, and lists every command with its options.

Prerequisites

The build needs Node.js and nothing else. The rest is for cloning and for the other commands.

• Node.js 22.12 or later, see engines in package.json. The repository pins its version in .nvmrc.
• pnpm, the version named by packageManager in package.json. Run corepack enable once and pnpm is used at that version.
• Git LFS, from git-lfs.com. Run git lfs install once on your machine before cloning. Fonts and raster images are Git LFS files.

Installation

Clone the repository to work on the assets:

git clone https://github.com/chassis-ui/assets.git chassis-assets
cd chassis-assets

To use the assets in a project of yours, add the repository to it as a Git submodule instead:

git submodule add https://github.com/chassis-ui/assets.git assets
cd assets

The build imports Node.js modules only, so it runs on a fresh clone with nothing installed. Install the dependencies to run the tests, the checks and the documentation site:

pnpm install

Build the output

Run the build from the repository root. It reads the brands and the apps of the chassis block of package.json, and writes one folder per job.

pnpm assets

Use the filters to build a part of it, and --dry-run to see the jobs without writing a file. Each filter takes one or more values.

pnpm assets --brand chassis          # one brand
pnpm assets --app docs               # one app
pnpm assets --platform ios android   # two platforms
pnpm assets --dry-run                # print the jobs, write nothing

The build writes the output to dist/<platform>/<app>/<brand>/. With the configuration of this repository:

dist/
├── web/
│   └── docs/
│       ├── chassis/      -> kebab-case names
│       │   ├── fonts/
│       │   ├── icons/
│       │   ├── images/
│       │   └── other/
│       └── sinefil/
├── ios/
│   └── demo/
│       ├── chassis/      -> snake_case names
│       └── sinefil/
└── android/
    └── demo/
        ├── chassis/      -> snake_case names, density folders, ic_ prefix
        └── sinefil/

dist/ is not committed. The build system page describes every command and option.

Add a file

A file added to source/ is in the output of the next build. No list or configuration names it.

1. Export the file from the design tool, named in lowercase with hyphens.
2. Put it in source/default/<app>/<type>/ when every brand gets it, or in source/<brand>/<app>/<type>/ when it belongs to one brand.
3. Run pnpm assets:lint:source to check the name, and pnpm assets to build.
4. Find the file in dist/, under the name of each platform.
5. Commit the file of source/ with a changeset from pnpm changeset.

source/
├── default/              -> the default brand, used by every brand
│   ├── docs/             -> an app
│   │   ├── fonts/
│   │   ├── images/
│   │   ├── icons/
│   │   └── other/        -> any other folder is a type too
│   └── demo/
└── sinefil/              -> a brand: only the files that differ
    ├── docs/
    └── demo/

A brand file replaces the default file of the same path. To give a brand a file of its own, add it to the folder of the brand under the same subfolder and name.

The design guidelines have the naming rules, and each type has a page: fonts, images, icons and other assets.

Use the output

A project reads the folder of one job. Copy it into the project, or point the project at it.

cp -R dist/web/docs/chassis/. /path/to/project/public/assets/

The page of each platform shows what the folder holds and how an app loads the files:

• Web applications
• iOS applications
• Android applications

Make it your own

Chassis Assets is meant to be owned by the team that adopts it. You change source/, the root package.json and chassis.checks.json. The build in packages/assets/build/ names no brand, app or file, so there is nothing to change in it.

Brands and apps

Name your brands and apps in the chassis block of package.json. Each app lists the platforms it is built for.

{
  "chassis": {
    "defaults": {
      "brandFolder": "default"
    },
    "build": {
      "brands": ["chassis", "sinefil"],
      "apps": {
        "docs": ["web"],
        "demo": ["ios", "android"]
      }
    }
  }
}

Then give source/ the same names: a folder per app under source/default/, and a folder per brand for the files that differ. See configuration.

Checks

What the checks verify is in chassis.checks.json, beside package.json: contracts, the files your consumers read by name, and lint.allow, the source files that break a naming rule on purpose. The lists of this repository are those of the Chassis sites. Replace them with yours, or delete the file. See checks file.

Package metadata

Change the name and the repository URL of the root package.json. The release archives take their name from it: acme-assets-workspace gives acme-assets-<platform>-<app>-<brand>-<version>.zip.

{
  "name": "acme-assets-workspace",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/acme-assets.git"
  }
}

The package that carries the version is packages/assets/package.json. It is private and never published, so its name can stay. When you rename it, rename it in the changesets of .changeset/ too.

Point the clone at your own repository:

git remote set-url origin https://github.com/your-org/acme-assets.git

Troubleshooting

Each entry gives the message or the symptom, then the cause and the fix.

Build fails on pointers

The build stops with <count> source file(s) are Git LFS pointers, not files. The clone was made without Git LFS, so the fonts and the images are pointer files of a few lines. Install Git LFS, run git lfs pull, and build again.

Unknown brand

The build stops with Unknown brand "<name>". Configured: <names>. A filter names a brand, an app or a platform that the chassis block of package.json does not have. Use one of the names the message lists.

Missing output file

The build passes and a file of source/ is not in the folder of a job. The platform does not keep the format: a TTF font is not copied to the web, and a WebP image is not copied to iOS. The page of the type has a table of the formats each platform gets.

Next steps

Continue with one of these pages:

• Design guidelines: the folders, the naming rules and the workflow of a designer.
• Build system: the commands, the configuration and the checks.
• Fonts, images and icons: the rules of each type.