migration-guide

name

migration-guide

description

Generate or update Norwegian-language migration guides for major version bumps of the Helsenorge design system packages (`@helsenorge/designsystem-react`, `@helsenorge/datepicker`, `@helsenorge/lightbox`) by comparing a feature branch against master. Use this skill whenever the user wants to create a migration guide, document breaking changes between branches, prepare migration notes for designsystem / Frankenstein major version upgrades, or translate git diffs and CHANGELOGs into wiki-ready migration documentation with both human summaries and agent-runnable prompts. Triggers on phrases like "make migration guide", "lag migreringsguide", "document breaking changes", "compare feature/v15 to master", "write migration notes for v15", or any context involving a major version bump of the design system packages.

Migration guide generator

This skill produces wiki-ready migration guides (in Norwegian) for major version bumps of the Helsenorge design system packages (@helsenorge/designsystem-react, @helsenorge/datepicker, @helsenorge/lightbox). The output is meant to be pasted into Confluence and to drive both human readers and coding agents working in downstream consumer codebases.

The defining design constraint: not every consumer uses every component, hook, or token. Each entry must include an applicability check so an agent can paste-and-go in any consumer repo and self-skip when the change is irrelevant.

When in doubt

If you trigger this skill but the user's actual request is something narrower (e.g. "summarize the changes in this branch" without wiki output), confirm before producing the full guide. The output is opinionated and Norwegian — make sure that's what they want.

Step 1: Gather inputs

You need:

• Feature branch name (e.g. feature/v15, feature/next, feature/supernova-tokens). Required.
• Existing migration guide path (optional). If the user is updating a partially-written guide, they should hand you the markdown file or paste the contents.
• Target output path (optional). Default: migration-guide-<sanitized-branch>.md in the current directory, where slashes in the branch name become hyphens.

If the feature branch isn't obvious from context, ask. If you see a partial guide in the conversation or as an attachment, treat that as the existing guide.

Step 2: Discover changes

Run in this order:

1. git fetch origin --quiet
2. git log --no-merges --oneline origin/master..origin/<branch> — commit overview.
3. git diff --name-only origin/master..origin/<branch> | grep -E "^npm/(designsystem|datepicker|lightbox|build-tools)/" | awk -F/ '{print $1"/"$2}' | sort -u — changed workspaces.

Note: npm/build-tools/ is private internal tooling — only mention it if a change leaks into a published package's behavior. Skip documentation-only changes in docs/ and utils/icons/ source assets unless they imply a public API change (e.g. removed icons).

For each changed package, gather signals in order of trustworthiness:

• Top-level CHANGELOG.md diff — primary source; this repo keeps a single root changelog generated by conventional-changelog-cli.
• <pkg>/package.json diff — version bump (major = breaking signal), peer-dep changes, and the exports map.
• exports field diff — @helsenorge/designsystem-react uses explicit sub-path exports (./components/Button, ./components/Chip/Chip, ./hooks/useLanguage, ./theme/*, ./scss/*, etc.). Each removed or renamed key is a removed public surface.
• Deleted files — git diff --diff-filter=D --name-only origin/master..origin/<branch> -- npm/<pkg>/src.
• Renamed components / hooks — folder renames under npm/designsystem/src/components/ and npm/designsystem/src/hooks/.
• Generated icon / illustration lists — diff npm/designsystem/src/components/Icons/ and Illustrations/ index for removed exports. These are auto-generated by __scripts__/generateIconNames.mjs and generateIllustrationNames.mjs, so a removed icon shows up as a removed file.
• Theme tokens — diff npm/designsystem/src/theme/ for removed or renamed colors, palette entries, spacing tokens, typography tokens. Renamed tokens are a common breaking change.
• SCSS public surface — diff npm/designsystem/src/scss/ (consumers import these directly via @helsenorge/designsystem-react/scss/*) and any *.module.scss whose class names are documented as part of a component's public anatomy.
• Component prop interfaces — diff the <Name>Props interface in npm/designsystem/src/components/<Name>/<Name>.tsx. Renamed, removed, or newly-required props are breaking.
• Resource keys — diff npm/designsystem/src/resources/Resources.ts for removed or renamed HN… resource interfaces (consumers pass these in via the resources prop).
• Commit messages — git log --no-merges --pretty=format:"%h %s%n%b" origin/master..origin/<branch> -- npm/<pkg> when CHANGELOG is thin.
• Targeted file diffs — only when you suspect a breaking change you can't otherwise confirm.

Be efficient. Don't load the full package diff. Follow signals.

Step 3: Classify each change

Each candidate fits one of:

• Removed export — component, hook, util, icon, illustration, or theme token deleted (usually with a replacement).
• Renamed export — same functionality, new name (component, hook, prop, theme token, icon).
• Changed API — modified prop name / type, hook signature, or function return type.
• Changed default — a prop or theme default flipped (e.g. a variant default, default size, default htmlMarkup).
• Required SCSS / asset change — consumer must touch their own index.html, root SCSS imports, or font loading because @helsenorge/designsystem-react/scss/* or /fonts/* paths changed.
• Resource-key change — a resources prop interface gained, lost, or renamed a key (consumers passing custom resources will break).
• Peer-dependency upgraded — major bump of react, react-dom, motion, classnames, normalize.css, or Node engine. Often informational, but mention it.
• Removed tooling — script, generator, or build step removed (e.g. generate:cssdefinitions flags changed).

Skip pure internal changes (refactors with no API change, lint fixes, test improvements, internal Storybook tweaks, generator-script internals). They don't belong in a migration guide.

Step 4: Reconcile with existing guide

If the user gave you an existing guide, read it and mark which changes are already documented. Verify every factual claim in every existing entry against your own diff analysis. Correct errors and outdated information — do not assume an existing guide is correct. Keep style and structure only where the facts check out. Merge in what's missing.

Step 5: Write each entry

Each entry has three parts.

h2 heading

Short, scannable, natural Norwegian. No BREAKING: prefix. Match the style of existing entries (e.g. "HelpBubble er fjernet", "Button bruker htmlMarkup i stedet for tag", "Supernova-tokens").

Human summary

2–5 sentences in Norwegian explaining what changed and why it matters. Include before/after code snippets when relevant — especially for imports (sub-path changes), prop renames, and SCSS imports. Link to external guides (React 19 upgrade notes, official TypeScript release notes, etc.) where natural. Internal links (Confluence, intranet HOW-TO-er, helsenorge.design) are acceptable in human summaries since a human reader can access them — but never include them in agent prompts.

Agent prompt

A copyable prompt for an agent working in a downstream consumer codebase. Wrap in a code block. The prompt must:

1. Start with an applicability check. Does this codebase use the affected component / hook / token / sub-path import? If not → skip and note it in the PR description. This is the most important part — it's what makes the prompt safe to paste into any consumer repo.
   • For sub-path import changes: the check must look for the specific import path (e.g. @helsenorge/designsystem-react/components/HelpBubble) — not just any @helsenorge/designsystem-react import.
   • For SCSS changes: search for the specific @helsenorge/designsystem-react/scss/<file> import or @import / @use reference.
   • For theme-token changes: search for the token name in both .ts/.tsx and .scss files (tokens are exposed in both layers).
2. Describe search patterns without naming specific tools — describe what to search for (string, file type, pattern) and let the executing agent choose its own search tool. Do not name tools like rg, ripgrep, grep, fd, or find. Example: instead of rg "HelpBubble" --type tsx, write "søk etter 'HelpBubble' i TypeScript/TSX-filer".
3. Search all usage sites, not just imports — JSX usage, prop spreads, resources overrides, SCSS @use / @import, and snapshot tests may all reference the affected API. Agent prompts must include search patterns for both import-based usage AND direct references in JSX, SCSS, and test snapshots.
4. Describe the transformation — what to replace, how props/types map. Tell the agent to read the component's TypeScript types (node_modules/@helsenorge/designsystem-react/lib/components/<Name>/<Name>.d.ts) when mapping isn't 1:1, not to guess.
5. Storybook / visual regression implications — if a component's default rendering changed, the prompt must include a step to regenerate Storybook snapshots and Chromatic / visual-regression baselines if the consumer uses them. Describe how to detect this (search for *.stories.tsx, chromatic.config.json, or similar).
6. Specify verification — tell the agent to read the scripts field in package.json and use whichever script runs type-checking, tests, and storybook build in that project. Do not hardcode npm run typecheck or npm test — these names vary across consumer codebases.
7. Only link to publicly accessible pages — agents cannot access Confluence, intranet HOW-TO-er, or other internal resources. Only reference public documentation (helsenorge.design Storybook is publicly hosted and OK; React / TypeScript release notes; MDN; etc.).
8. Specify what goes in the PR description — especially for skipped changes.

The prompt must be in Norwegian and self-contained — an agent should be able to act on it without reading the rest of the guide.

Example entry

## HelpBubble er fjernet

`HelpBubble` er slettet fra `@helsenorge/designsystem-react`. Bruk `Tooltip` som erstatning. Propsene er ikke 1:1 — sjekk komponentens
TypeScript-typer for å mappe riktig.

### Agent-prompt

```
Migrer fra HelpBubble til Tooltip.

1. Sjekk om kodebasen bruker HelpBubble:
   Søk etter 'HelpBubble' i TypeScript/TSX-filer og etter import-stien
   '@helsenorge/designsystem-react/components/HelpBubble'.
   Hvis ingen treff: hopp over dette steget og noter i PR-beskrivelsen at
   HelpBubble ikke er i bruk.

2. For hvert treff:
   - Endre import fra '@helsenorge/designsystem-react/components/HelpBubble'
     til '@helsenorge/designsystem-react/components/Tooltip'.
   - Bytt JSX-tagnavnet.
   - Mapp props ved å lese Tooltip sine TypeScript-typer i
     node_modules/@helsenorge/designsystem-react/lib/components/Tooltip/Tooltip.d.ts.
     Ikke gjett — verifiser.
   - Sjekk om noen av treffene er i *.stories.tsx eller snapshot-tester
     og oppdater disse også.

3. Verifiser:
   - Les scripts-feltet i package.json og finn riktig navn på typecheck-,
     test-, og evt. storybook-build-scriptene i dette prosjektet. Kjør dem.
   - Hvis prosjektet har visual regression (Chromatic e.l.), oppdater
     baselines.

4. I PR-beskrivelsen: lim inn liste over filer du endret, eller skriv
   "HelpBubble ikke i bruk" hvis ingen treff.
```

Step 6: Add the super-agent-prompt preamble

Immediately after the h1 title, insert a blockquote that serves as both a human explanation and a top-level instruction for any agent that receives the entire guide as input. The preamble must:

• Explain the structure of the guide for humans (human summaries + agent-prompts).
• Include a dependency-update step (steg 0) that the agent must complete before following any per-section prompts. See below.
• Instruct agents to work through all remaining sections in order, follow each agent-prompt, and start every section with the applicability check.

Dependency-update step in the preamble

The three published design system packages are versioned and released together from this monorepo:

• @helsenorge/designsystem-react
• @helsenorge/datepicker
• @helsenorge/lightbox

Derive the authoritative list at guide-generation time by running:

for d in npm/designsystem npm/datepicker npm/lightbox; do
  node -e "const p=require('./$d/package.json'); if(p.private!==true && p.name?.startsWith('@helsenorge/')) console.log(p.name+'@'+p.version)"
done

Consumers may also depend on other @helsenorge/* packages (e.g. @helsenorge/core-framework, @helsenorge/framework-utils, @helsenorge/eslint-config) that are outside the scope of this guide — they are released from a different monorepo (HN-CoreFrontend) and follow a separate version scheme. Agents must not bump those packages as part of a design system migration.

When the new major is not yet released as latest (only available under the beta dist-tag), the preamble must tell the agent to:

1. List all @helsenorge/designsystem-react, @helsenorge/datepicker, and @helsenorge/lightbox entries in package.json.
2. Use npm dist-tag ls @helsenorge/designsystem-react to find the current beta version. Use the same beta version line for all three packages (they are versioned together).
3. Present the full update plan to the user and wait for confirmation before touching package.json or running installs. Peer- dependency conflicts (especially against react@^19, motion, normalize.css, and other @helsenorge/* packages from CoreFrontend) can be hard to resolve automatically.
4. After confirmation: apply the version bumps and run npm install. Resolve any peer-dependency errors before proceeding.
5. Only continue with the per-section prompts once npm install succeeds.

Preamble template

Adapt version number and beta version based on what you found in the branch:

> Denne guiden beskriver endringer i v15 av Helsenorge designsystem-pakkene (`@helsenorge/designsystem-react`, `@helsenorge/datepicker`,
> `@helsenorge/lightbox`). Hver seksjon inneholder en menneskelig beskrivelse av hva som er endret, og en **agent-prompt** med konkrete
> instrukser for å utføre migreringen.
>
> **For agenter — steg 0, gjør dette før alt annet:**
>
> ```
> Oppdater designsystem-pakkene til riktig versjon.
>
> 1. List designsystem-pakkene i package.json:
>    Søk etter '@helsenorge/designsystem-react', '@helsenorge/datepicker', og
>    '@helsenorge/lightbox' i package.json (både dependencies og devDependencies).
>
> 2. Finn riktig beta-versjon:
>    npm dist-tag ls @helsenorge/designsystem-react
>    De tre pakkene er versjonert sammen — bruk samme beta-versjon
>    (f.eks. 15.0.0-beta.0) for alle tre.
>
> 3. Andre @helsenorge-pakker:
>    Pakker som @helsenorge/core-framework, @helsenorge/framework-utils,
>    @helsenorge/core-utils, @helsenorge/eslint-config m.fl. er IKKE en del
>    av denne migreringen — ikke endre versjonene deres.
>
> 4. Presenter oppdateringsplanen for brukeren og vent på godkjenning
>    før du endrer noe i package.json.
>
> 5. Etter godkjenning: oppdater versjonsnumre i package.json og kjør
>    npm install. Løs eventuelle peer dependency-konflikter (særlig mot
>    react@^19, motion, normalize.css, og andre @helsenorge-pakker).
>    Ikke gå videre til neste steg før npm install er vellykket.
> ```
>
> **Steg 1 og utover:** Gå gjennom alle seksjoner i rekkefølge. For hver seksjon: følg instruksene i agent-prompten nøyaktig. Start alltid
> med applicability-sjekken — hopp over seksjoner som ikke er relevante for dette prosjektet, og noter det i PR-beskrivelsen.

Step 7: Order the guide

Roughly: breaking API changes (removed/renamed components, hooks, props) → theme-token / SCSS changes → changed defaults → required config changes → peer-dependency / tooling changes (informational) at the end. If the existing guide has its own order, respect it.

Step 8: Write and summarize

Write the guide to the output path. Then summarize briefly in chat:

• Number of entries (new + carried over).
• Changes you found but were unsure how to classify — list them so the user can decide.
• Existing entries you preserved unchanged.
• Output file path.

Don't paste the full guide back into chat unless the user asks. They'll read the file.