Development setup
The repository contains both the icon production pipeline and the documentation site. A local build lets you verify source changes in the same generated formats used by the npm package and the published website.
Requirements and installation
Continuous integration runs on Node.js 24. Use the same major version locally to reduce
differences in dependency and build behaviour. Install the locked dependency tree with
npm ci; this keeps local output aligned with CI.
npm ciKnow the source boundaries
| Path | What it holds |
|---|---|
| src/ | Authoring SVGs, grouped by their public icon category. |
| meta/ | Aliases, search tags and generated release history for each identifier. |
| tmpl/ and assets/ | Twig content, JavaScript and Sass used to build the documentation site. |
| dist/ and _site/ | Generated package and website output. Rebuild these from their sources. |
Build icon assets
The icon build optimizes the source SVGs and produces individual files, category sprites, stylesheets, Sass variables and the JSON data consumed by the site. Run it after changing an SVG or icon metadata that affects generated output.
npm run icons-buildBuild and preview the site
The site build renders the Twig templates and copies the icon distribution and Soul Design
System into _site/. Serve that directory locally to test navigation, responsive
layout, code examples and icon previews as a reader will encounter them.
npm run site-build
npm run site-serve
For an active editing session, npm run dev builds the icon set and site once, then
watches SVG, Sass and Twig sources for changes.
npm run devRun the relevant checks
CI installs from the lockfile, runs Stylelint and rebuilds the icons. Match those checks before submitting a pull request. Documentation changes should also receive a complete site build so broken templates and navigation data are caught locally.
npm run stylelint
npm run icons-build
npm run site-buildCommit message convention
Prefix each commit with the type that best describes its effect. The release tooling uses these prefixes to organize changelog entries, so choose the user-visible outcome rather than the file type you happened to edit.
[FEATURE]for new functionality or new public assets.[BUGFIX]for corrections to shipped behaviour or assets.[TASK]for maintenance, refactoring and dependency work.[DOCS]for documentation-only changes.[!!!]or[BREAKING]for incompatible changes.