

Live code examples are the difference between documentation that tells developers what a component does and documentation that lets them try it. A static code snippet shows the syntax. A live, runnable example shows the behavior, the edges, and the answer to "what happens if I change this?"
For most design systems, the introduction of live code examples is the single largest improvement to developer experience the documentation goes through. The improvement isn't subtle. Developers validate that a component fits their use case in seconds rather than minutes, and the documentation team stops fielding the same trial-and-error questions over and over. Interactive design system documentation that runs the actual components is a different category of resource from a static reference.
This article covers what counts as a live code example, the three main shapes they take, the tools that produce them, where they earn their place, where they don't, and how to keep them from quietly drifting out of sync with your actual component library.
"Live code examples" is a loose term that covers three distinct patterns. The differences matter because they have different costs and serve different purposes.
Live component renders. A running instance of the component displayed alongside the documentation, no code visible. Storybook, custom component playgrounds, and most documentation tools handle this as a baseline. The reader sees what the component looks like and behaves like, but doesn't see the underlying code.
Static code with live preview. A code snippet shown on the page, with a live render next to it. The reader can read the code and see the output, but can't edit the code in place. Most modern design system documentation includes this, often produced by tools like Sandpack, zeroheight's preview blocks, or framework-specific MDX renderers.
Editable, forkable code. The full sandbox experience. The reader sees the code, edits it, can fork it into their own scratch project, and saves or shares their changes. Stackblitz and CodeSandbox are the dominant tools here. This is the most powerful pattern and the most expensive to maintain.
The three patterns aren't a hierarchy. A documentation site might use all three on the same page: a live render at the top, a code-with-preview for the common use cases, and an editable sandbox for the more complex examples that benefit from exploration.
The question isn't which one to use. It's which one to use where.
A few specific things change when documentation includes live code examples rather than static snippets.
Validation gets faster. A developer evaluating whether a component fits a particular case can try it in five seconds rather than copying the snippet into their codebase, wiring up the dependencies, and running the result. Five seconds of validation beats five minutes every time.
Live examples build confidence in the documentation itself. An example that runs is a guarantee it's at least syntactically correct. A static snippet can be wrong and still look right. The static example that says <Button onClick={handleClick}> but doesn't actually run is a class of bug that lives quietly in documentation for years.
Edges become discoverable. The third or fourth time a developer tries something the component doesn't quite support, the trade-off becomes visible without anyone having to write it down. Live examples are a kind of automatic edge-case documentation.
Feedback loops shorten when developers can fork and share. "Here's what I tried, here's what happened" with a Stackblitz link is more useful than a paragraph of description. The team supporting the design system gets reproduction cases instead of vague reports.
The cost of these benefits varies by tool, but the benefits are real. Most documentation that doesn't have live code examples eventually adds them. Teams rarely roll the addition back.
Live code examples aren't free, and the costs are worth knowing before committing.
Performance and load time matter. Embedded sandboxes are heavy. Stackblitz and CodeSandbox each spin up a full development environment, which can add seconds to page load. A documentation site with twenty embedded sandboxes on the same page becomes painful to navigate. Lazy-loading sandboxes (only initializing when scrolled into view) is usually a requirement for any docs site that uses them heavily.
Maintenance burden is the next big cost. A static code snippet is a string of text. A live example is a running project with dependencies, lockfiles, and breaking changes in the framework to track. When the underlying component library publishes a new version, every embedded sandbox needs to be checked. This isn't theoretical; it's the most common reason live examples go stale.
Tooling lock-in is a real consideration. Each tool has its own embed format, its own quirks, its own pricing. Once a documentation site is built around Stackblitz, switching to CodeSandbox is non-trivial. Choosing the tool is a more substantive decision than it looks.
Accessibility concerns deserve attention. Embedded sandboxes are notorious for accessibility issues: keyboard navigation traps, missing labels, focus that gets lost between the parent page and the embed. Most major tools have improved, but the situation is still uneven. Documentation that uses embedded sandboxes should be tested with assistive technology as part of the QA process.
Security implications round out the list. A live sandbox that runs arbitrary code is executing code in the reader's browser. For internal documentation behind authentication, this is usually fine. For public documentation, the surface area is worth thinking about.
None of these is disqualifying. Each shifts the calculus, though, and the decision to add live examples should account for the full ongoing cost rather than just the initial benefit.
The tools that produce live code examples fall into a few broad categories. The right one depends on what the documentation needs to do.
Stackblitz is the most full-featured for serious development. It runs a near-complete dev environment in the browser, supports most JavaScript frameworks (React, Vue, Angular, Next, Nuxt), and lets readers fork examples into their own accounts. The cost is heaviness. Stackblitz works best as a deep-dive tool: the example a reader opens when they want to really explore, not the example they see on every page.
CodeSandbox sits in the same category as Stackblitz with a similar feature set. It has historically been stronger for visual integrations and embedding into documentation; Stackblitz has been stronger for development-grade environments. The two have converged, and the choice often comes down to existing team familiarity or one-off feature comparisons.
Sandpack (by CodeSandbox) is a lighter-weight, embeddable component for inline live examples. It's what powers React's documentation and many modern docs sites. Sandpack is designed to be embedded alongside prose rather than as a standalone page. For documentation that needs live examples on every component page, this kind of lightweight design system code playground is usually the right call.
CodePen is the oldest of the live-code tools and the lightest-weight. It's strongest for vanilla HTML, CSS, and JavaScript. For design system documentation focused on framework components, CodePen has less to offer. For tokens, foundations, and pure-CSS components, it's still a reasonable option.
Custom embeds are technically an option. Some teams build their own. The benefit is full control. The cost is that you're now maintaining a code execution environment, which is more expensive than it looks. Most teams should not build their own.
The pattern that works for most design systems: a heavyweight tool (Stackblitz or CodeSandbox) for the deep-dive examples, and a lightweight one (Sandpack or the documentation platform's built-in live preview) for the inline ones.
Storybook deserves its own treatment because it sits in a category by itself.
Storybook is, at its core, a live component sandbox. Every component gets one or more "stories" that render it in a controlled state, often with knobs for adjusting props. A Storybook instance is a kind of documentation site built specifically around live components.
Where Storybook is strong: it's the canonical place where the actual component library renders, so the live examples are always running the real components. Storybook also handles framework integration cleanly. The same Storybook can serve React, Vue, Angular, or Svelte components without much fuss.
Where Storybook is weaker as documentation: the structure is component-centric, which fits component libraries but doesn't accommodate the broader documentation needs like foundations, patterns, content guidelines, or getting started. Storybook can hold long-form content through MDX, but the experience is generally less polished than purpose-built docs tools.
The pattern that works for most teams is to treat Storybook as a complement, not a replacement. Storybook holds the live component sandbox. The main documentation site holds the prose, the foundations, the patterns, and the structural content. Links between the two carry developers across.
Article 12 covers Storybook in more depth, including the integration patterns that connect it to design system documentation.
The most common failure mode for live code examples is drift. The example is committed at version 1.0 of the component library. The library moves to 2.0, then 3.0. The example still runs (the sandbox keeps an old dependency tree alive), but it's running against an old version of the component. Readers see behavior that doesn't match the current library, and trust in the documentation erodes.
The pattern that prevents drift is to pull live examples from the same source as the component library, not to maintain them separately.
For Storybook, this is automatic. Storybook reads the component library directly, so updates to the library appear immediately.
For Stackblitz and CodeSandbox, the pattern requires more work. The sandbox project should reference the component library as a versioned dependency (@your-system/react@latest, or pinned to a specific version with a deliberate update cadence). Sandboxes that hardcode component implementations directly are the ones that drift hardest.
For inline live previews (Sandpack-style), the framework should be configured to import from the live component library at build time. This ensures the example renders the current version of every component it references.
The maintenance overhead also wants automation. A CI check that catches broken sandboxes (a dependency tree that fails to resolve, an example that fails to render) catches drift the moment it happens. Without that check, drift is invisible until a reader complains.
Live code examples aren't always the right call.
For foundations (color, typography, spacing), static examples plus the underlying tokens are usually enough. A color swatch with its token name is more useful than a live React playground showing the same value.
For components with simple APIs, a static snippet and a static visual usually do the job. A page documenting a Divider component doesn't benefit much from a live sandbox.
For introductory pages, getting-started content, and overview material, live code adds load time without adding value. Readers in those sections aren't trying to validate behavior; they're trying to orient themselves.
For complex compositions involving multiple components, live examples are valuable but often overkill in the documentation itself. A link out to a Stackblitz collection of worked examples is lighter than embedding the same examples on the page.
The rule of thumb: live code earns its place on component pages where developers are evaluating behavior. It's optional or overkill almost everywhere else. The temptation to add live previews to every page is real but usually a mistake.
Live code examples are one of several developer-facing surfaces in design system documentation. The articles closest to this one in the guide:
Article 09 (Documenting design systems for developers) covers the full developer-facing layer, including the relationship between live examples, prop tables, and code documentation.
Article 12 (Storybook and design system documentation) covers Storybook specifically, including its role alongside live code examples in other tools.
Article 03 (How to document a design system component) covers the structure of a component page, including where live code sits on the page.
