Hi Penpot community!
I’m currently working on a complex button component system in Penpot and I’m struggling with organizing the assets in a way that makes them manageable and easy to navigate.
My button system includes:
Sizes: x-small, small, medium, large, x-large
Content types: text, icon, text + icon
Styles: fill, outline, ghost
Colors: basic, primary, success, warning, danger
Shapes: default, round
I’m using this naming pattern:
[Element: Button] / 01) [Property: Content ] text / 01) [Property: Size ] x small / 01) [Property: Style ] fill / 01) [Property: Shape ] default / 02) [Property: Color ] primary
This structure is technically accurate, but…
The issue:
The sidebar becomes overwhelming because of the deep nesting .
It’s visually hard to distinguish one property group from another.
The lack of hierarchy visualization or grouping makes it difficult to jump between variants.
Even with emojis and ordering numbers, I often get lost trying to manage or reuse a specific combination.
What I’m looking for:
Tips for organizing deeply nested component properties in Penpot
Best practices for naming and grouping that work well with Penpot’s asset panel
Any way to visually break up or label sections more clearly in the side panel
Interesting challenge.
As soon as component variants will be released in Penpot this will be easy and visually less complex. For now, I’m wondering if you can remove some complexity when outsourcing some styling options into Tokens or Libary Assets. For colors and styles this should be straight foreward.
I agree with @schnesen’s tips. Most of these properties will be variants (coming very soon) and that’ll simplify the organisation. And also that splitting some of these properties into design tokens would make a lot of sense.
If I’m reading correctly, you might not know that you can group components?
Some ways I organise components to help make the library really usable:
Keep the names short and consistent; the more text (and punctuation/emojis) you have, the harder components are to read and find. With libraries this big, you want to make it easy to use the search function to find components.
Group your components in a consistent order that works for you/your team. For a large library, I’ve found myself using a pattern of: type of component / component name / sub componentsub component variation / sub component which ends up as: action / star rating / stars solid / 1 star or utilities / icon / star / star outline
For your button example, this might be something like: inputs / button / buttondefault / defaultprimary / primarysmall
You would have to choose a hierarchy or order for your variations, which won’t be necessary when variants launch.
I like to repeat the group name in the following group. It might look a bit verbose when written out like this, but it makes the groups very readable and you can more easily understand the context of each group. Especially if you’re using the component swap menu in the Design panel.
I hope that makes sense! Let me know if you have any more questions
I don’t have better tips than those already shared by @schnesen and @LauraKalbag to improve the case. I just want to add a sneak peek and a small offer.
For style-related aspects (such as Size and Colors), design tokens enable efficient management across multiple dimensions like brands, devices or themes. Also, variants are coming soon to Penpot, making it easier to organize and visualize components in the library. Here’s a screenshot from a test file: a single main component contains all the options (variants) shown in the center, configured through properties like Variant, Icon, and State, as you can see at the right sidebar.
The offer: we’ll soon launch a beta test for Variants. We’d love to include people who are especially interested in design systems (like those participating in this conversation) and willing to give us feedback. Community ideas have been key in previous features (like Plugins and Grid Layout), and we believe they will be again this time. If you’re interested in joining the test, just write us to support@penpot.app and we’ll add you to the beta tester list.
I can’t wait for the component variants feature to be released that’s going to be a game-changer for managing this kind of complexity
Just to clarify my approach:
I’ve already set up the styling using design tokens (for colors, spacing, etc.).
Then I built the button components based on those tokens .
Finally, I saved each variant as a reusable component.
My goal is to make it so the UI team only interacts with the components, not the design tokens directly — to keep things simple and avoid inconsistencies.
I think the complexity might also be because of my background I’ve worked mostly with Sketch, and I’m still slowly adjusting to how Penpot structures things. So far I love the flexibility, just trying to find the right workflow for scalable systems like this.
I do use grouping, but with so many variants it becomes deeply nested and still hard to visually distinguish between property groups. Even with consistent naming, the sidebar gets overwhelming fast.
I’ve built my buttons using design tokens, then saved them as components so my UI team only uses the components, not the tokens.
Can’t wait for the variants feature that’s going to simplify everything!
] text / 01) [Property: Size 
] x small / 01) [Property: Style 
] fill / 01) [Property: Shape 
] default / 02) [Property: Color 
] primary
