Infa Logo

Markdown as Universal Language for Design Systems

Why teams keep returning to markdown despite initial resistance, and how it enables future-proof, AI-ready documentation.

Event Context

Session: Craft Across: Documentation in Design Systems
Date: August 7, 2025
Key Contributors: Dustin Younse (Indeed), Kristen Singh (Intuit)

This insight emerged from a discussion about documentation format choices and why teams consistently return to markdown after trying various content management systems.

Core Insight

"We tried three different CMSs and always came back to markdown" - Dustin Younse

Despite initial resistance and the learning curve for non-technical contributors, markdown consistently proves to be the most sustainable choice for design system documentation.

Why Teams Return to Markdown

Universal Compatibility

  • ✓ Cross-platform support - Works across Storybook, Zero Height, and custom documentation sites
  • ✓ Tool independence - Not locked into specific vendor solutions
  • ✓ Future-proof format - Readable by humans and machines for decades

AI and Automation Ready

  • ✓ MCP compatibility - Built-in support for Model Context Protocols
  • ✓ Structured content - Easy for AI systems to parse and understand
  • ✓ Version control integration - Documentation versions with code changes

Single Source of Truth

  • ✓ Multi-platform distribution - Same content published to multiple destinations
  • ✓ Consistent formatting - Standardized presentation across tools
  • ✓ Centralized maintenance - Update once, deploy everywhere

Key Speaker Insights

Dustin Younse (Indeed): "We tried three different CMSs and always came back to markdown... It's the lowest common denominator that a lot of different tools can interact with."

Kristen Singh (Intuit): "We came to the realization that Markdown was super powerful... through many, many errors. We have to train designers who are writing content on how to write in markdown, which is not easy. But the payoff is significant."

When to Choose Markdown

  • Starting new documentation sites
  • Migrating from proprietary tools
  • Preparing for AI integration
  • Building multi-platform documentation
  • Teams prioritizing long-term sustainability

Alternative Approaches Considered

Custom CMS Solutions

  • Full control over features and presentation
  • "Maintenance burden is pretty immense" - requires ongoing technical investment

WYSIWYG Editors

  • Non-technical contributors love the familiar interface
  • Updates and migrations become difficult over time

Proprietary Tools

  • Rich features and polished interfaces
  • "Try opening a Sketch file 5 years later. Good luck." - vendor lock-in risks

Implementation Reality

The Learning Curve Challenge: Teams must train designers and content creators on markdown syntax, which creates initial resistance.

The Long-term Payoff: Once teams adopt markdown workflows, they gain unprecedented flexibility and future-proofing for their documentation.

Quick Example

# Button Component

## Usage

-   Use `variant="primary"` for main actions
-   Use `size="large"` for hero sections

## Code Example

```jsx
<Button variant="primary" size="large">
    Get Started
</Button>
```

Takeaway: Markdown isn't just a format—it's the foundation for future-proof, AI-ready design system documentation that scales across teams and tools. The initial learning curve pays dividends in long-term flexibility and sustainability.

Source: Craft Across: Documentation in Design Systems • August 7, 2025

Markdown as Universal Language for Design Systems - Infa