webkit-ds-adoption

Skill: webkit-ds-adoption

Purpose

You rarely adopt a design system all at once — you adopt it one screen, one primitive at a time, without freezing feature work. This skill is the method for that migration: how to break an existing app's move onto @aziontech/webkit into small stories that each ship on their own, in an order where nothing depends on work that hasn't landed yet. The goal is not a rewrite; it is that every screen you touch comes out with more webkit and less hand-rolled UI than it went in with, and that the parts you replace stay replaced. The mechanics of how to import and token a component live in webkit-usage — this skill is about what to migrate, in what order, and how far.

How to use

• /webkit-ds-adoption — plan and execute the next migration story on the code in this conversation: pick the smallest shippable slice in dependency order and do it.
• /webkit-ds-adoption <screen-or-dir> — audit the target, produce its coverage scorecard (webkit vs custom), and propose the migration stories in order.

Check the catalog before you build anything

The default is compose webkit; writing a custom component is the exception, and it must be justified. Before you write UI — new or migrated — check whether the system already ships it:

• Ask the webkit MCP — suggest_component in plain words ("modal", "data table", "tag input").
• Or read node_modules/@aziontech/webkit/catalog.json — every key under imports is a real published subpath. If a subpath is not a key there, it does not exist.

If a component exists, use it — compose it, pass its props, fill its slots. A hand-rolled button, modal, or table when webkit ships one is not a migration; it is new debt.

Migrate in small stories, in dependency order

Never a big-bang rewrite. Decompose the migration into slices that each ship independently, bottom-up:

1. Wire the dependency + tokens. Add @aziontech/webkit / @aziontech/theme / @aziontech/icons and import theme + icons once at the app entry (see webkit-usage). Nothing renders differently yet — this is the foundation every later story stands on.
2. Replace primitives. Swap the leaf controls — button, input, modal, select, checkbox — for their webkit equivalents, one type at a time. Each swap is a small, reviewable, shippable PR.
3. Replace composite patterns. Once the primitives are webkit, migrate the assemblies built on them — a data table, a form section, a filter bar, an empty state — to the webkit composite (or compose it from its sub-components).
4. Remove dead custom CSS. After a pattern is on webkit, delete the legacy styles, class presets, and one-off components it replaced. The migration isn't done until the old code is gone — a half-migrated screen carries both systems.