MercuryAI

I've been working at Mercury on an agentic extension to our design system. It's been a huge partnership with engineering; we built a way for humans and agents to have one legible system that's deterministic for understanding any design component and the larger system around components.

It started with a documentation problem we could no longer ignore.

Four sources of truth was no source of truth

Mercury's design system documentation had become outdated and scattered across four or five places. Component behavior lived in code JSDocs. A defunct mercury.design/system site still depended on a stale Notion database. Figma documentation was sporadic and inconsistent. Meanwhile, a designer-led vibe-coding tool had created a divergent implementation of our components, complete with its own documentation system.

Each source was useful in isolation, but none could resolve the others. A designer, engineer, or agent asking the same question could get a different answer depending on where they looked. As AI tools became part of daily product work, the cost of that ambiguity increased: an agent could reproduce a stale pattern faster than a person could catch it.

A two-person undertaking

I got buy-in from our VP of Design and engineering leadership, then drove the project end to end with one engineer. It was just the two of us taking on a massive documentation and infrastructure problem across design, engineering, and AI tooling.

We pioneered a new system built on the Design System Documentation Specification. Instead of creating another destination, we created a manifest that could resolve what we already knew. A set of skills scaffolded the YAML structure, then mined insights from GitHub, Slack, and Notion to surface the decisions and context hidden across the company.

The repository gave the system a legible shape. The manifest was the shared contract; skills handled scaffolding and authoring; source material stayed close enough to inspect rather than disappearing into a black box.

design-system/
├── AGENTS.md
├── .agents/
│   └── skills/
│       ├── scaffold-manifest/
│       │   └── SKILL.md
│       ├── mine-system-context/
│       │   ├── SKILL.md
│       │   └── references/
│       │       ├── github.md
│       │       ├── slack.md
│       │       └── notion.md
│       └── author-documentation/
│           └── SKILL.md
└── manifest/
    ├── mercury.dsds.yaml
    ├── components/
    ├── foundations/
    └── patterns/

Structured for machines, written for people

The schema made design system knowledge portable without flattening it. Using the actual DSDS outputs, we could model guidelines, definitions, metadata, and references explicitly instead of burying them in page layouts. Each entry had a stable identity and type, while references and extensions could connect shared guidance or Mercury-specific context. The manifest could produce a concise human view and a more verbose agent view from the same resolved source.

schemaVersion: "0.20.1"
name: Mercury Design System

entries:
  - kind: component
    id: button
    name: Button
    description: Triggers an action.
    purpose: Gives users one consistent way to act.
    sections:
      - kind: guidelines
        for: all
        items:
          - level: should
            statement: Limit each surface to one primary button.
      - kind: definitions
        for: all
        title: Anatomy
        items:
          - term: Container
            definition: The interactive root element.
          - term: Label
            definition: The visible text of the button.

refs:
  - href: ./foundations/accessibility.dsds.yaml
    rel: file
    role: Shared accessibility guidelines

Human-authored prose still mattered. We combined it with JSDocs and resolved the result inside Storybook, with the Storybook manifest and Storybook MCP turned on. Engineers could keep documentation near code, designers could edit explanatory prose, and agents could read a structured version with the detail they needed.

Deterministic output in Cursor

I independently pioneered the Cursor plugin work, including its structured ds- slash commands and MCP integration. Instead of prompting an assistant to imitate Mercury from screenshots or memory, a designer or engineer could ask for deterministic design system output backed by the same manifest.

Following Cursor's plugin structure, I packaged commands, skills, and the MCP server behind a portable plugin manifest. This mock shows the shape of that interface:

mercury-design-system/
├── .cursor-plugin/
│   └── plugin.json
├── commands/
│   ├── ds-component.md
│   ├── ds-guidelines.md
│   └── ds-definition.md
├── skills/
│   └── mercury-design-system/
│       └── SKILL.md
└── mcp.json

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "mercury-design-system",
  "description": "Deterministic Mercury design system guidance",
  "version": "0.1.0",
  "author": { "name": "Mercury" }
}

That was the larger shift. The resolved system enabled every AI tool and agent to consume the same source, while giving us a path to build plugins for any future platform. We were not tying the design system to one model, editor, or vendor.

Outcome: turning on the future with what we had

The best outcome was what we did not need to build. There was no new third-party documentation site to maintain and no parallel publishing workflow to drift out of date. By enabling the manifest in Storybook and carving off a design-system-scoped Storybook host, we could give everyone a useful home immediately.

Redoing all of the documentation was still underway when I left, so I would not claim shipped adoption results. But our tests showed a massive difference in the specificity, determinism, and quality of agent output. The same prompts stopped producing vague approximations and started returning guidance anchored to Mercury's actual system.

One resolved system replaced a collection of destinations. People kept the context and prose they needed, while agents gained a structured, verbose source they could consume directly. Every future interface could start from the same Mercury design system instead of inventing another version of it.