AI-Assisted Design
Documentation Platform

No shared source of truth

Every component handoff followed the same script: send a PDF export, a link to a Sketch library, and a Radar ticket written for an engineer who hadn’t sat in the design review. Nobody could run the spec. Nobody could resize it to test mobile. And by the time engineering asked the first follow-up question, the Sketch file had already changed.

The result was a fragmented documentation landscape. Each artifact lived in a different place, maintained by a different person, at a different level of freshness. Web developers discovered edge cases the PDF never addressed. Engineers had to interpret static annotations instead of inspecting working code. Designers spent their time answering questions a running prototype would have answered on its own.

“Specs felt like a wishlist.”

The fix wasn’t better annotations or more detailed tickets. It was a different format entirely — one that could run in a browser, adapt to dark mode, and answer follow-up questions before anyone had to ask them.

PDFs, Sketch links, and tickets — three artifacts, three owners, three versions

A platform architecture, not a document template

I chose to generate a running page at a URL rather than produce a better static document. The alternative was available and cheaper — more detailed annotations, longer tickets, a stricter PDF template — and I rejected it because none of those change the fundamental problem: a static artifact can only answer questions its author anticipated. A prototype answers the ones they didn’t.

The platform had to serve three audiences at once. Designers needed high-level specs. Engineers needed complete handoff detail. Web developers needed something they could open in devtools and inspect directly. A single static format can’t serve all three; a page that adapts can.

The method is a loop, not a pipeline

Each component followed the same path, and the middle step is the one that matters. First, decide the component from what actually needed building — for example, a modular reveal container that holds an image or icon, with optional items that can be toggled on or off depending on the page. Then design it in Sketch, in multiple views, to see the structure in visual terms before any code existed.

Then build it with AI and test the limits. This is where the design work happens. Not “does it render,” but what breaks it — what content lengths, what nesting, what viewport, what combination of optional elements. The generated component is a hypothesis; stress-testing is how it becomes a spec. Only once it held up did the documentation pass begin.

All of the code was written by AI assistance, directed by my prompts. I want to be precise about that, because it locates the contribution correctly: my work was deciding the architecture, defining the constraints, finding where the output was structurally wrong, and directing it toward something that scales. The generation was never the hard part.

The architecture I didn’t design

The documentation site itself almost didn’t come together.

I designed it the way a designer designs a page: screen by screen, solving what was in front of me. What I hadn’t designed was the system underneath — and it failed in three specific ways.

Hardcoded values instead of variables. As the site grew, colors went in as hex codes rather than tokens. Light and dark mode broke constantly, and every fix was local to one page.

Cache-busting wasn’t thought through. Updates shipped and didn’t appear. Stale files kept being served while the source had already changed — the same class of problem the platform existed to solve, reproduced in the platform itself.

Generated pages didn’t inherit anything. New articles were created on top of the site rather than from a shared foundation. Each one carried its own structure. Some were never linked into the navigation at all — real pages, reachable only if you knew the URL.

AI produces locally-correct output while having no model of the system that output belongs to.

None of these were AI errors in the narrow sense. Every page it generated was correct on its own terms. That’s precisely the failure mode. It optimizes the artifact in front of it, and left undirected it will default to literals over tokens, new files over shared foundations, and no global wiring — every single time.

The fix was information architecture, applied to a codebase instead of a navigation tree. One source of truth for tokens. Generated navigation instead of hand-linked pages. One foundation every article inherits. The site became a pseudo-CMS: create a spec article now and it wires itself into the navigation and renders through the correct template automatically, because the structure decides that — not the generation step.

That rethink is the actual design contribution in this project. Learning to direct AI toward scalable architecture is not a prompting trick — it’s the same systems judgment that makes a design system work, applied to a medium that will happily let you skip it.

Pages that inherit nothing drift apart and fall out of the nav — one foundation keeps them consistent and wires them in