This is a tracking issue for sub-issues related to improving support for AI agents working with the design system.
User Story: As a plugin author or Gutenberg contributor, I want to trust that the code produced by my AI agents follows best practices for user experience according to the WordPress Design System, so that I can have confidence that the generated code is high-quality to the standards of the users who use it, and the other collaborators who will review it.
Current State: AI agents will likely struggle to discover relevant documentation for using the design system effectively. Existing documentation and design system principles for the design system implementation are spread across our Storybook site and various package Markdown documents: READMEs (example), contribution guidelines (example), and other reference documents (example). As a client-rendered (single-page) application, Storybook is not easily accessible to machine scrapers like AI agents, and agents may struggle with discovering package documentation, particularly those which are excluded from the published package. The Storybook also includes a lot of unrelated and legacy component documentation, which is important for it to be an exhaustive resource, but its exhaustiveness may bloat agent context windows or mislead toward outdated conventions.
Anti-Goals:
- Avoid duplicated effort in maintaining documentation. Ideally we write the documentation once, and it's discoverable to multiple audiences (human or AI). In practice, this means limiting audience-specific documentation and reusing existing resources as much as possible.
This is a tracking issue for sub-issues related to improving support for AI agents working with the design system.
User Story: As a plugin author or Gutenberg contributor, I want to trust that the code produced by my AI agents follows best practices for user experience according to the WordPress Design System, so that I can have confidence that the generated code is high-quality to the standards of the users who use it, and the other collaborators who will review it.
Current State: AI agents will likely struggle to discover relevant documentation for using the design system effectively. Existing documentation and design system principles for the design system implementation are spread across our Storybook site and various package Markdown documents: READMEs (example), contribution guidelines (example), and other reference documents (example). As a client-rendered (single-page) application, Storybook is not easily accessible to machine scrapers like AI agents, and agents may struggle with discovering package documentation, particularly those which are excluded from the published package. The Storybook also includes a lot of unrelated and legacy component documentation, which is important for it to be an exhaustive resource, but its exhaustiveness may bloat agent context windows or mislead toward outdated conventions.
Anti-Goals: