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

GitHub

Taking 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:

  1. Change and release it in the design-system repo (its own CI gates the version bump and publishes on merge).
  2. 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 in brand/colors.json silently 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's DERIVED owns 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.