insolvia-design-system-bump
How to take a new @insolvia-ai/design-system or @insolvia-ai/tokens version into this repo — and the rule that the packages themselves are NOT here to edit. Use this whenever a task means changing a s
SKILL.md.claude/skills/insolvia-design-system-bump/SKILL.md
GitHubTaking a design-system or tokens version
First: the package is not in this repo
@insolvia-ai/design-system and @insolvia-ai/tokens live in
insolvia-ai/design-system.
There is no packages/insolvia_design_system here any more, and there must not
be one again — see
ADR 0010.
So a task that says "change the Button" is two pieces of work:
- Change and release it in the design-system repo (its own CI gates the version bump and publishes on merge).
- Bump the dependency here — that is what this skill covers.
Never short-circuit step 1 with a file: or link: path to a local
checkout, even temporarily, even uncommitted. The app used to read the
package's source through a workspace symlink; one package with two live states
is the exact failure ADR 0010 removed. To try an unpublished change, publish a
prerelease from that repo and depend on it by version.
The bump
Three surfaces consume the packages, and they do not share a lockfile — there are three of those too. Missing one is the usual way a bump half-lands, and the admin portal is the one most often forgotten because it arrived last.
| File | What to change |
|---|---|
package.json (root) |
devDependencies → @insolvia-ai/tokens — the brand tools resolve it from here |
apps/insolvia_app/package.json |
dependencies → @insolvia-ai/design-system, @insolvia-ai/tokens |
apps/insolvia_marketing/package.json |
devDependencies → @insolvia-ai/design-system (marketing does not use tokens) |
apps/insolvia_admin/package.json |
devDependencies → @insolvia-ai/design-system (nor does admin) |
package-lock.json |
regenerate with npm install from the repo root |
apps/insolvia_marketing/package-lock.json |
regenerate with npm install inside apps/insolvia_marketing — it is deliberately outside the workspace |
apps/insolvia_admin/package-lock.json |
regenerate with npm install inside apps/insolvia_admin — outside the workspace for the same reason |
Check what you actually got, rather than trusting the range — all three lockfiles must name the same version:
for p in . apps/insolvia_marketing apps/insolvia_admin; do node -e "const l=require('./$p/package-lock.json');for(const [k,v] of Object.entries(l.packages||{}))if(/@insolvia-ai\/(design-system|tokens)$/.test(k))console.log('$p',k,v.version)"; done
Installing needs a GitHub Packages token, even for public packages:
eval "$(./scripts/github-packages-auth.sh --export)"
Always regenerate the brand surfaces
npm run tokens
Commit whatever that writes. npm run tokens:check is a required PR check
(Cognito branding — the job kept its name, though Cognito's page left for
insolvia-services), and it fails on a bump that did not regenerate.
brand/colors.json is where Insolvia's colours live
(ADR 0020),
and it is the thing to understand before touching any of this. From tokens 0.5.0 the design system's
base theme is deliberately unbranded: monochrome chrome, square corners, no
display face, with primary/accent/brand all resolving to neutral-12. That
empty seam is the package's intent — a re-brand belongs to the consumer — so
Insolvia's navy and brass are overrides layered on top, not package
defaults.
npm run tokens renders that palette into the three surfaces that cannot read
the JSON themselves:
| Generated | Consumed by |
|---|---|
apps/insolvia_app/src/theme/brand-colors.ts |
the app — both themeFor() and the ThemeProvider that themes the package's .native leaves |
apps/insolvia_marketing/app/styles/brand.css |
marketing, imported after the package's theme.css |
apps/insolvia_admin/src/styles/brand.css |
the admin portal, same shape |
The sign-in page is not one of them any more. Cognito's managed-login style
(colours, logo, tab icon) moved to insolvia-services with the rest of auth on
2026-10-12 (ADR 0026), as checked-in files beside its infra/modules/auth. A
bump that changes a brand colour needs a matching change there; nothing here
checks it.
Never hand-edit one of those three — the next npm run tokens overwrites it
and the drift check fails in between. Change brand/colors.json and regenerate.
Two things that follow, and are easy to get wrong:
- The overrides are PARTIAL on purpose. Only roles Insolvia actually moves
are listed; the status colours,
dangerText, the overlay values and the neutral ramp stay the package's, so a tokens release that adds a role or re-measures a contrast reaches every surface without an edit here. Restating a package default inbrand/colors.jsonsilently opts out of that. - The hover/active states are native-only. Web derives them with
color-mix()over the base role, so the CSS deliberately omits them — emitting them would freeze a live derivation. React Native has no blend and needs them stated.tool/brand-palette.ts'sDERIVEDowns that split.
Skipping the regeneration leaves one app on a different palette from the rest, and nothing else in the tree would say so.
Then verify, locally
npm run ci
npm run build --workspace @insolvia-ai/app
The build matters more than usual for a design-system bump: the app renders the
package's .native leaves on every platform, web included, through a Metro
resolveRequest override in apps/insolvia_app/metro.config.js. If a release
reorganises the package's internals, that override is what breaks, and it breaks
silently — the bundle still builds, having resolved the .web leaves, whose
Tailwind classes reference CSS the app never compiles. A bundle that looks fine
and renders unstyled is the failure mode to watch for.
Marketing and the admin portal each have their own gate, and neither is covered
by the root npm run ci:
npm run typecheck --prefix apps/insolvia_marketing && npm run build --prefix apps/insolvia_marketing
npm run typecheck --prefix apps/insolvia_admin && npm run build --prefix apps/insolvia_admin
Build both, not just typecheck: each CI job greps its bundle for react-native,
which is how a platform-split regression shows up. And on a release that touches
theming, check the brand actually survived into the built CSS — the base theme's
own [data-theme='dark'] block is still in there, and ours only wins by landing
after it:
grep -o -- "--color-primary:[^;]*;" apps/insolvia_admin/dist/assets/*.css
Scope
A version bump is ordinary work and does not need its own PR — that rule
belonged to the package while it lived here. Bundle it with the change that
needs it. What still needs care is the list above moving together: a manifest
bumped without its lockfile fails npm ci in CI, and a marketing lockfile left
behind means the two surfaces silently render different versions of the same
component.