Managing and documenting custom components in Vaadin Flow

Flow
1

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:

  1. having a place to visually compare implemented components with designs (e.g. Figma)
  2. 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?

2

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?

1 Like