Skip to main content
Machine-Readable Documentation

Machine-Readable Documentation

Make your design system documentation structured and parseable so AI tools can understand and apply it correctly. Human-readable docs are great for people but AI needs explicit structure, relationships, and constraints to generate system-compliant work.

How to

  1. Audit current documentation

    Review your guidance for structure. Identify where information is implicit, scattered, or narrative-only.

  2. Add structured metadata

    Include machine-readable fields in your documentation: component API schemas, token relationships, usage constraints, accessibility requirements, and valid combinations.

    • For example: "component": "Button", "props": [{"name": "variant", "type": "enum", "values": ["primary", "secondary"], "required": true}]

  3. Create relationship maps

    Document how tokens relate to components, which components depend on others, and where customisation is/isn't allowed. Make these relationships explicit and queryable.

  4. Publish in structured formats

    Offer JSON schemas, OpenAPI specs, or structured markdown alongside human docs. AI tools should be able to import and parse your system programmatically.

  5. Validate with AI

    Test by asking AI to use your documentation. Identify where it misunderstands or makes wrong assumptions, then improve structure.

  6. Keep in sync

    Update structured docs whenever you update human guidance. Treat them as equal parts of your documentation strategy.