In modern software development, design systems have evolved far beyond static style guides or PDF docs. The phrase “living design systems that travel with codebases” captures this shift — a dynamic, developer-friendly suite of assets, documentation, and workflows embedded directly in the repositories where products are built. But what does that actually mean in day-to-day practice? How does this approach impact engineering teams, designers, and product folks collaborating in fast-paced environments?
In this post, we'll unpack the concept by focusing on critical elements such as HTML artifacts as richer outputs, the importance of engagement and scannability in product documentation, why token cost is a minor concern compared to latency, and how reusable artifact templates powered by JSON data swaps enable agility and consistency across projects.
Living Design Systems: Beyond Static Docs
Traditional design systems often live in separate portals or isolated documentation—sometimes even outdated or disconnected from the actual product code. In contrast, living design systems are integrated directly into your code repositories. They travel with the code, evolving as the product evolves.
- Source of truth: The design system is the single source of truth within the repo. Up-to-date: Changes to components, styles, and guidelines immediately update the system. Accessible: Developers and designers see design documentation alongside the code they write.
Embedding living design systems in repos fosters cross-team collaboration by reducing communication friction. Everyone can refer to the same, real-time updated artifacts, reducing ambiguity or mismatched deliverables.
HTML Artifacts as a Rich Output Format for AI-Powered Workflows
One transformational choice when embedding design systems into repos is the use of HTML artifacts for documentation outputs, rather than static markdown or PDF files. HTML’s flexibility and rich semantic capabilities unlock powerful benefits, especially when combined with AI-driven workflows.
Why HTML?
- Rich formatting: Tables, lists, headings, section anchors, embedding media—HTML handles complex layouts effortlessly. Interactivity: HTML allows embedded scripts or components enabling interactive demos or live playgrounds. Accessibility: Proper HTML semantics support screen readers and keyboard navigation, improving inclusivity. Machine readability: Structured HTML artifacts can be parsed, annotated, or dynamically queried by AI tooling.
For example, AI-powered documentation assistants can scan HTML artifacts for relevant code snippets, produce live code suggestions, or highlight deprecated components inline, speeding up developer workflows.
Markdown vs. HTML
While Markdown is easy to write and integrates well with many repo hosting platforms (like GitHub or GitLab), its limitations become apparent as design systems grow complex:
- Limited layout control and poor handling of nested data tables or complex grids. Lack of native interactivity or embedded widgets. No semantic hooks beyond basic header and list structures.
Because living design systems need to be both human- and machine-readable, HTML artifacts offer the best https://stateofseo.com/can-live-artifacts-run-a-content-calendar-that-stays-updated/ of both worlds. Markdown can still serve as a source format, compiled into enriched HTML artifact outputs.
Engagement and Scannability Drive Better Product Work
Documentation is only useful if people actually use it. One key success factor of living design systems is their focus on making documentation highly engaging and scannable. This is not fluff; it’s foundational for moving fast without breaking stuff.
What does engagement mean here?
- Clear, concise headings: Allow quick navigation through different design patterns or component families. Visual hierarchy: Use size, color, and spacing intentionally to differentiate important concepts. Code examples and demos: In-line examples reduce context switching between docs and environments. Searchability: Well-structured HTML with metadata improves developer search experiences.
For example, Opus 4.7 pricing tokens if a developer is looking for how a button variant should behave, they should find it in a few seconds, with an example that can be copied and tested immediately.
Why is scannability so important?
- In high-velocity teams, people rarely read walls of text—they skim. Attention is limited; documentation must enable rapid orientation. Better scannability reduces errors due to misunderstandings or outdated approaches.
Adopting HTML artifacts enables precise control over document layout — think collapsible sections, anchored headers, and well-structured tables — supporting engagement and scannability natively.
Token Cost Is Minor; Latency Is The Real Friction
There is often concern about the “token cost” when using AI-assisted documentation or code generation. While token cost reflects actual computational expense and model context window limits, in practice this is a minor factor compared to latency — the delay between issuing a command and receiving a result.
Especially in integrated developer workflows or chat-based tools, even a one or two second delay feels disruptive. What slows engineers down is waiting on tooling, not the raw token count.
- Interactive developer tooling must prioritize responsive, low-latency experiences. Pre-generating rich HTML artifacts that AI agents parse locally can reduce repeated API calls, thus cutting latency. Incremental updates and JSON-driven templates allow partial refreshes, avoiding full regeneration.
It’s a simple but often overlooked tradeoff: optimizing for speed of interaction beats minimal token cost strategies every time.
Reusable Artifact Templates with JSON Data Swaps
Maintaining a living design system requires not only rich outputs but scalable ways to generate and update those outputs as product components evolve.
What is a reusable artifact template?
It’s a generic HTML structure that can be populated dynamically with JSON data representing design tokens, component props, usage guidelines, etc.
Component Template JSON Data Example Button label "className": "primary", "label": "Submit" Color Palette 
Using these templates means you can regenerate documentation for an entire component set simply by updating JSON data files, which may be auto-extracted from source code or design tokens.
Benefits of this approach:
- Consistency: Uniform layout and styling across all artifacts. Agility: One JSON update cascades through many related docs and previews. Automation-friendly: Easily integrated into CI/CD pipelines that rebuild artifacts on code changes. Customization: Different teams can swap out JSON to localize or adjust visual styles without breaking the overall system.
Putting It All Together: A Practical Workflow
Here’s a simplified overview of how living design systems that travel with codebases can come to life in a typical engineering environment:
Component development: New UI component created in the repo, along with code and style definitions. Metadata extraction: Build scripts extract design tokens, prop definitions, usage notes into structured JSON files. Template rendering: Predefined HTML templates consume JSON to generate artifacts including visual previews, code usage tables, and guidelines. Artifact deployment: Generated HTML artifacts are committed back in the repo (e.g., docs/ folder) or published to a static site. AI tooling integration: Interactive bots or assistants parse the HTML artifacts for real-time developer support. Continuous updates: As components change, steps 2-5 repeat automatically, keeping docs in sync.This process drastically reduces “documentation rot,” empowers developers and designers with timely, rich context, and accelerates product iteration cycles.
Conclusion: What’s the Carve-Out Where This Fails?
“Living design systems that travel with codebases” empower teams, but they are not a silver bullet. Some boundaries to consider:
- Legacy codebases: Retrofitting complex existing systems can be costly, especially if component definitions lack metadata. Scale vs. complexity: For tiny projects or teams, the overhead of generating rich HTML artifacts and maintaining templates might not pay off. Tooling alignment: Teams must maintain or adopt pipelines to keep JSON data extraction and artifact generation reliable. Human factors: Without buy-in from designers and engineers to embed design systems in workflows, artifacts risk becoming ignored PDFs in repos.
Still, these carve-outs do not negate the massive productivity and quality gains possible when implemented thoughtfully.
Final Thoughts
Living design systems that journey alongside your codebases represent a paradigm shift from isolated documentation to integrated, richly formatted, and continually updated knowledge assets. Leveraging HTML artifacts baked from reusable templates driven by JSON data empowers teams with engaging, scannable documentation that AI-powered tools can interact with seamlessly. Recognizing that latency trumps token cost helps designers of these workflows deliver smooth, responsive experiences for developers and product teams. When done right, these systems unlock new levels of collaboration and product velocity in a world where design and code must advance in tandem.