If you’re building front ends with Umbraco, you’re already working in a component-driven way—especially if you’re using Web Components alongside the Block List editor.
In a previous article, we looked at how Web Components map naturally to Umbraco blocks and how structuring them using an adapted atomic design helps keep things scalable.
This article builds on that, and focuses on what makes that approach actually work in practice.
Umbraco and Storybook
Umbraco itself uses Storybook internally for its backoffice UI—and makes it available for developers to explore.
It reflects a broader shift toward:
Component-driven development
Isolated UI testing
Living documentation
If you’ve browsed Umbraco’s UI library, you’ve likely already seen this approach:
Components organised in a sidebar
Variants grouped together
Properties editable in real time
This is exactly what Storybook brings to your own projects.
What stories give you (and why they matter)
A story is simply an isolated version of a component in a defined state. But the impact goes far beyond that.
A faster development workflow
Without stories, front-end work often depends on the CMS: create content, navigate to a page, refresh, adjust, repeat
With stories, that loop disappears.
Confidence in your components
Stories make behaviour visible. You can see:
How a component behaves with missing data
How it handles long content
How different configurations affect layout
Instead of guessing how a block will render in Umbraco, you already know.
A shared understanding across the team
Stories create a single place where:
Developers understand implementation
Designers review variations
QA validates behaviour
That alignment is hard to achieve when everything lives inside the CMS.
A natural foundation for testing
Because stories isolate components, they become ideal for:
Visual checks
Interaction testing
Accessibility validation
Instead of building separate test setups, you reuse what you already have.
Where this fits in an Umbraco project
If you’re using Web Components with Umbraco, stories sit naturally in the workflow:
Web Component → Story → Umbraco → Page
Instead of building UI directly inside the CMS, components are developed and validated in isolation first. Stories define how each component should look and behave—covering default states, variations, and edge cases—before it’s integrated into a Block List item.
This creates a clear separation: Umbraco handles content and structure, while components handle UI and behaviour. In practice, this reduces the need to debug inside Razor, speeds up development, and makes your front end far more predictable as the number of blocks grows.
What it looks like in practice
At a high level, writing a story is straightforward:
The important part isn't the syntax, it is the intent.
Why this approach works (from experience)
In Umbraco projects, complexity doesn’t come from a single component—it comes from how many of them you have. Stories help you manage that complexity.
They reduce CMS dependency during development
You don’t need to constantly create or adjust content just to test UI.
They make behaviour predictable
When a component is used in a block, there are no surprises—because you’ve already seen every relevant state.
They improve long-term maintainability
New developers don’t need to reverse-engineer components from Razor views or CMS data. They can open Storybook and understand everything immediately.
They support scalable front-end architecture
As your system grows—from a handful of blocks to dozens—stories become the structure that keeps everything understandable.
A note on “how much” to document
One common mistake is trying to cover every possible variation.
In practice, we focus on:
The default state
A few meaningful variants
One or two edge cases
That’s enough to document intent without adding noise.
In some cases, it is also interesting to include stories showcasing all different style variants for a specific components. It can give developes a quick visual guide on how to use the component.
Final thoughts
If you’re building Web Components for Umbraco, stories aren’t an extra layer, they’re part of the foundation.
They give you:
A faster development workflow
Better visibility into your components
More confidence when shipping changes
And most importantly, they turn your component library into something the whole team can understand and use.
We’ve applied this approach across Umbraco projects to build component-driven front ends that are easier to scale and maintain. If you’re working with Block List and want more predictability in your UI layer, it’s a pattern worth adopting early.