Guide

Migrate an existing system

Preserve useful infrastructure, add the semantic and governance layers that are missing, and migrate deliberately instead of rebuilding by default.

1. Audit before replacing anything.

Inventory the existing colors, type styles, spacing, interactive patterns, recurring components, one-offs, and current kit dependencies. Reduce accidental variation before you codify it into a new semantic layer.

2. Choose the adoption model explicitly.

A third-party kit can remain part of the product. Under the B&Co Standard, the project still defines its own semantic layer and records how the kit is adopted rather than allowing vendor defaults to become the product model by accident.

3. Put the product semantic layer above the kit.

Treat the kit’s values/defaults as the underlying vocabulary and map product intent through semantic roles. Override semantics rather than repeatedly overriding individual components.

4. Tag component origin.

kit-native

Used without product modification.

kit-extended

Built on the kit with product modifications.

custom

No kit dependency.

These tags make upgrade blast radius visible.

5. Evaluate accessibility before committing.

Keyboard navigation, ARIA implementation, focus management, contrast, and touch behavior must meet the product’s structural accessibility requirements. A kit does not outsource that responsibility.

6. Let the product-local Catalog show the truth.

The Catalog should mount the real adopted/extended/custom implementation and connect it to the product spec and git. Building Blocks should not pretend an external kit is a Building Blocks implementation merely because the product uses both.