How I turned a prose UX writing guide into a structured, machine-readable content system inside a product design system.
<aside>
🧭
At a glance
- Role: UX Writer
- Skills: Content engineering, object-oriented content modeling, design-system content, versioning and governance, information architecture
- Product: a self-custody crypto wallet
- Surface: the product's design system, in Notion
- Scope: sole editorial owner, working under the direction of the Head of Design
- Challenge: UX writing standards lived as a single prose guide — readable by people, invisible to the systems that increasingly depend on copy
- Impact: 60 structured, versioned Library entries plus canonical design-system pages · one source of truth, read by both people and machines
</aside>
The problem
The Product Content Guide was a comprehensive, well-written Notion document covering voice, tone, microcopy patterns, vocabulary, localization, and governance. It served writers well. But as a document, it had reached three limits:
- It was invisible to machines. Codegen, linters, and AI agents increasingly need copy rules in order to apply them automatically, and none of them can read prose.
- It invited double maintenance. As the design system grew, the same rules began to surface in two places, which guarantees drift over time.
- It flattened different kinds of knowledge. Lintable rules, reusable patterns, narrative voice, and rationale all lived as the same undifferentiated prose, so nothing could be addressed, reused, or enforced on its own.
The approach: content as infrastructure
Rather than copy the guide into the design system, I treated content as typed, addressable, version-controlled infrastructure. The core move was to split content by type.
- Codifiable rules and patterns become structured entries in a Content Library, each with a stable slug as its permanent ID, a status lifecycle, and a version. This is the machine-readable layer.
- Voice, narrative, and rationale, the parts that need human judgment, become canonical SFDS pages that people read and that reference the entries.
| Surface |
Role |
Consumer |
| Design system content pages |
Canonical, human-authored standards |
People |
| Content Library |
Codified mirror: the same rules and patterns as structured rows with stable slugs |
Machines (codegen, linters, agents) |
| Product Content Guide |
Frozen archive: the original prose, migrated section by section |
Historical reference |
One principle holds the system together: every piece of content has exactly one canonical home. Nothing is maintained in two places.
The process: a repeatable loop
I ran the migration as a single loop, applied to every section in turn.
- Audit. Inventory the Library first, including a duplicate-slug scan run before and after each change, so IDs always stay unique.
- Rehome. Move codifiable content into structured entries and narrative onto its canonical page.