How enforcing migration rules through tools beats writing them in documents

A development team managing a large design system migration found that written rules in documents were consistently ignored after the first week, prompting a shift in strategy. Instead of relying on developers to remember guidelines, the team embedded key restrictions directly into their build tools and component generators. When someone attempted to mix old and new design system files, the build would fail visibly; when a component was created inside an unmigrated screen, the generator would block the action and explain why. One rule — prohibiting new files in the legacy format — lacked a tool enforcement mechanism and was the only rule that was violated, with the legacy file count rising from 437 to 449 over several weeks. The team concluded that documents serve as a useful foundation, but rules only reliably hold when tools are built to refuse violations at the exact moment they occur.