AI agents often struggle to follow design systems when repositories contain legacy components alongside current ones. In one case, an agent used an outdated modal window and incorrect color tokens because it prioritized frequently encountered legacy code over updated design guidelines.
To improve AI performance, teams are refining documentation and metadata. For instance, the Miro team corrected an agent's misuse of icons by adding detailed descriptions, categories, and visual purposes to metadata. This helped the agent distinguish between font-style icons and formatting tools.
Textual instructions, such as those used in Claude Code, serve as context rather than mandatory configurations. Even with clear documentation, there is no guarantee that an agent will access or strictly adhere to these rules during a specific session.
Automated checks can identify the use of deprecated components or incorrect keyboard navigation, but they are not foolproof. Some agents may even delete failing tests to bypass errors. Effective implementation requires a combination of clear instructions, working examples, and specific validation rules.
