I’m trying to improve how we manage and document custom components in a Vaadin Flow project and would like to hear how others approach this.
Our setup is relatively simple:
mostly overrides of the default theme
a few custom-built components
Even so, it’s already getting hard to keep track of what exists.
What we’re missing is some kind of internal “component gallery”:
1. overview of all available components 2. visual examples of usage and states 3. clear mapping to code (names, locations)
The main goal is to avoid duplication. Before creating a new component, developers should be able to quickly check if something similar already exists.
Another important aspect is collaboration with designers:
having a place to visually compare implemented components with designs (e.g. Figma)
ensuring consistency between design and implementation
So the question is:
How do you handle this in Vaadin Flow projects?
Do you build something like a simplified Storybook, or use any tools/patterns to document and showcase components?
Or do you rely on a different approach to keep this overview accessible to the team?
Hey, thanks for the good explanation of the problem and your use-cases – very useful!
One of the things we’re working on right now is a more customizable component palette in Copilot, so that you can make a project specific palette with exactly the components you have and use in your project. Customizable Palette in Copilot #7503
The intent is precisely to provide a shared component library so for discoverability and consistency. The longer term vision is to expand this, so it’s a convenient part of your design system that both developers and AI can reference, with docs and examples.
(And it should probably also be renamed, as “palette” is not the best way to describe this).
Separately – part of the same story but (maybe) not exactly for palette – we have been discussing the need to get an overview of components for various purposes like theming, and the use-cases you mention fit in. For this we do not have any concrete plan yet, it’s unclear where and how this should show up to be most useful. Any input very useful!
What do you think, is this directionally right? Would Copilot (inside the application running in devmode) fit your use-cases?
And for your case, is project-specific good, or is something organization-wide needed?
Thanks — but Copilot probably isn’t really what I’m after here. I want something closer to a small standalone “preview” app: I point it at all my custom components, and it generates a minimalistic gallery for me automatically — one entry per component, rendered live, with its name and source path.
The key word is automatically. Hand-registering every component in a @Route("dev/components") view works, but it’s exactly the maintenance burden I’m trying to avoid — it drifts and nobody keeps it up to date. What I’d love is to drop my components in (or have it scan the classpath) and get the preview generated, no per-component boilerplate. Or maybe add some annotation?
So my real question is: has anyone built (or seen) something like that for Flow?
A tiny generator that:
discovers components (classpath scan, or an annotation like @Preview / a marker interface),
instantiates each one with sensible defaults,
and lays them out in a minimal gallery with name + class + file path.
That’s the sweet spot for me — minimal, generated, always in sync with the code. Storybook-style but native to Flow and zero manual story-writing. Curious if that exists or if people just accept the manual gallery.
Yesterday I saw this: Dev pages, so something like that it’s enough for me right now.
We used to have a solution that is somewhat similar to what you describe, called Vaadin Design System Publisher (or DSP for short) – it’s the toolkit we use to generate the Vaadin documentation | Comprehensive guide for developers sub-site.
We still use it internally for our docs, but it was sunset as a product. One of the reasons it didn’t really work out very well for third party use is that it is very much not lightweight – it really only made sense if you have a lot of custom components for which you want to write extensive documentation.
DSP doesn’t have any kind of automated sample UI generation, and, to be honest, I’m a bit skeptical of the idea in general: while it can work just fine for some components, in most cases you need to configure the sample in various ways (e.g. adding content to a container component, adding text etc to simpler components, and providing renderings of its various variants, etc). You did mention instantiating them with “sensible defaults”, but those defaults need to be defined by someone, and by far the easiest way to do that is to simply implement the sample.
So my suggestion would be to accept that you need to implement the samples manually, but somehow automate how they are collected, rendered, routed, etc, e.g. using annotations.
So, essentially a Flow-based sampler application.
If you want to embed Figma designs in it, you should be able to do so with IFrames.