When I design and evolve a design system, I prioritize adoption over theoretical perfection.
A system that is partially imperfect but widely used creates more value than a refined system that teams avoid or bypass.
In real production environments, design systems compete with:
- delivery pressure,
- legacy constraints,
- and existing team habits.
Optimizing exclusively for conceptual purity often leads to:
- over-engineered abstractions,
- slow onboarding,
- and parallel solutions emerging outside the system.
Instead, I treat adoption as a primary success metric.
The system must be usable, approachable, and immediately helpful—even if that means accepting known limitations and planning to evolve them later.
Shipping usable components before ideal abstractions
Early system components are designed to solve concrete, recurring problems rather than to establish a perfectly generalized model.
Progressive refinement instead of upfront completeness
The system is allowed to grow iteratively as new needs emerged.
Accepting inconsistencies to enable onboarding
Some inconsistencies are tolerated temporarily to avoid breaking existing products or workflows.
If you are using React
<!--
In react options are not treated
with its standard attributes,
this breaks the component
-->
<MdsInputSelect>
<option value="1">Option 1</option>
<option value="2">Option 2</option>
<option value="3">Option 3</option>
</MdsInputSelect>
<!--
Use the web-component directly
even if it doesn't benefit from
the react wrapper
-->
<mds-input-select>
<option value="1">Option 1</option>
<option value="2">Option 2</option>
<option value="3">Option 3</option>
</mds-input-select>
Documentation optimized for first use, not completeness
Documentation is written to help teams succeed quickly rather than to describe the entire system exhaustively.
README.md
# mds-push-notification-item
to install the component:
'bash
npm install @maggioli-design-system/mds-push-notification-item
'
to use the component:
'html
<mds-push-notification-item></mds-push-notification-item>
'
<!-- Auto Generated Below -->
## Properties
| Property | Attribute | Description | Type | Default |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| 'dateFormat' | 'date-format' | Specifies if the notification date format shows time passed or displays date as a static string | 'string' | ''timeago'' |
| 'datetime' | 'datetime' | Specifies the notification date based on [standard ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). | 'string | undefined' | 'undefined' |
| 'deletable' | 'deletable' | Specifies if the component is dismissable or not, it should be set to true by default is used with it's parent component 'mds-push-notification-items' | 'boolean | undefined' | 'true' |
| 'icon' | 'icon' | Specifies the icon to be displayed | 'string | undefined' | 'undefined' |
| 'initials' | 'initials' | The user's inizials displayed if there's no image available, initials will override tone and variant senttings to keep user recognizable from others | 'string | undefined' | 'undefined' |
| 'message' | 'message' | Specifies the message of the component | 'string' | ''Nessun messaggio disponibile'' |
| 'preview' | 'preview' | Specifies if the 'src' attribute is used to show a the image as avatar or full image | '"avatar" | "image" | undefined' | ''image'' |
| 'src' | 'src' | Specifies the path to the image | 'string | undefined' | 'undefined' |
| 'subject' | 'subject' | Specifies the subject of the component | 'string | undefined' | 'undefined' |
| 'tone' | 'tone' | Specifies the color tone of the component | '"strong" | "weak" | undefined' | ''weak'' |
| 'variant' | 'variant' | Specifies the color variant of the component | '"amaranth" | "aqua" | "blue" | "error" | "green" | "info" | "lime" | "orange" | "orchid" | "primary" | "sky" | "success" | "violet" | "warning" | "yellow" | undefined' | 'undefined' |
----------------------------------------------
Built with love @ [Gruppo Maggioli](https://www.maggioli.com) from [R&D Department](https://www.maggioli.com/it-it/chi-siamo/ricerca-sviluppo)
Reducing contribution friction
Contribution processes were designed to encourage participation rather than enforce gatekeeping.
Issue and Merge Request Templates
.gitlab
- issue_templates
- Default.md
- Accessibility.md
- Bug.md
- Documentation.md
- Feature.md
- Performance.md
- Refactor.md
- Security.md
- Style.md
- Test.md
- merge_request_templates
- Default.md
- Accessibility.md
- Bug.md
- Documentation.md
- Feature.md
- Performance.md
- Refactor.md
- Security.md
- Style.md
- Test.md
...
Measuring success through usage, not elegance
System success was evaluated based on real adoption and impact.
Component adoption metrics
mds-button drive more value than elegant
but rarely-used components like mds-bibliography.
A design system does not fail because it is imperfect.
It fails when teams stop trusting it as a practical tool.
By prioritizing adoption over perfection:
- the system remains connected to real product work,
- teams feel supported rather than constrained,
- and improvement becomes continuous instead of theoretical.
Perfection is static.
Adoption creates momentum.