Repository navigation
Creating an issue
Issues are the entry point for every contribution to Magma: they are the touchpoint between anyone who wants to contribute and the Design System community. Before writing code, opening a discussion, or proposing a component, you always start here.
This page explains when to open an issue, which type to choose, and how to write it so the core team can triage it quickly. If it is your first time, five minutes are enough.
📌 Golden rule: a well-written issue is triaged in a minute; a poorly written one sits for days waiting for clarifications. The time you invest here you save (many times over) later.
- Search the existing issues (including closed ones). If it already exists, add a 👍 or a comment instead of opening a new one: it helps us gauge how many people are affected.
- Is it a question? Usage questions do not belong in GitHub Issues but on the Stack Overflow channel.
- Is it a security vulnerability? Do not open it publicly: use the private security advisory channel.
- Pick the right type (see below). The template guides you with required fields - fill them all in.
The issue type maps directly to the contribution types and backlog types defined in the contribution model. Use this table to orient yourself:
| I want to… | Template | Notes |
|---|---|---|
| Report something that does not work | 🐞 Bug Report | Fixing a defect → usually semver: patch 🟢 |
| Suggest a feature without building it myself | 💡 Feature Request | Goes to the backlog; the core team reviews and prioritizes it |
| Propose a contribution I want to build myself | 🛠️ Contribution Proposal | Triggers the assignment of a core team mentor |
| Report a problem in the documentation | 📖 Documentation | Wrong page, missing example, typo |
| Request training or onboarding | 🎓 Training / Onboarding | For a person, a team, or a group |
In Magma's community-based model there is a precise difference:
- Feature Request = "the Design System should have X". You flag the need; the core team evaluates it and adds it to the backlog. You are not committing to build it.
- Contribution Proposal = "X is missing and I will take care of it". You commit to delivering the contribution (code and/or design). The core team pairs you with a mentor and plans the review path. This is the heart of the shift from core team to community.
If you are unsure which one to choose: open a Feature Request. If you later decide to implement it, the core team will convert it or ask you to open a proposal.
The template already sets a prefix ([Bug]:, [Feature]:, and so on).
Complete it with a short, specific sentence that makes sense out of context.
- ✅
[Bug]: mg-button loses focus after click on Safari - ✅
[Feature]: "ghost" variant for mg-button - ❌
[Bug]: it does not work - ❌
[Feature]: improve the buttons
A good title answers "what and where" straight from the issue list.
The templates ask you for the right fields; the principle is always the same:
- Context - which package, which version, which integration framework (vanilla, React, Angular, Vue…).
- Problem / need - what happens today or what is missing, and why it is a problem (the use case, not just the solution you have in mind).
- Expected behavior / proposed solution - what should happen.
- Reproduction or references - for a bug: steps or, even better, a minimal reproduction (the fastest way to get it fixed). For a feature: mockups, Figma links, examples.
💡 Focus on the problem before the solution. An issue that says "users cannot tell which button is primary" opens more paths than one that only says "make the buttons blue".
Every issue moves through a series of states, marked by the status:
labels:
-
status: triage- just opened. The core team reads and classifies it. -
status: needs-info- information is missing; the author must reply. -
status: accepted- validated against guidelines and quality standards, ready to be picked up. -
status: in-progress- someone is working on it (assigned). -
status: needs-review- waiting for review (dev, design, accessibility). -
Closed - resolved and merged, or
wontfix/duplicate.
An accepted issue that involves development then turns into a feature branch and follows the contribution flow (Dev → Doc → Release).
When an issue is picked up, the branch and the commits follow the project's
conventions. Commits are validated by commitlint (extending
@commitlint/config-conventional), so the commit type must be one of the
values below. Development branches use the same token, in the form
<type>/context-<name> (for example feat/context-button-ghost).
| Type | Used for | Semver impact |
|---|---|---|
build |
Build system or external dependencies | - |
change |
Breaking change to a component API | major 🔴 |
chore |
Repo maintenance and tooling (no src/test change) | - |
ci |
CI configuration and scripts | - |
docs |
Documentation only | - |
feat |
New feature or component | minor 🟡 |
fix |
Bug fix | patch 🟢 |
hotfix |
Urgent fix | patch 🟢 |
merge |
Merge commit | - |
perf |
Performance improvement | patch 🟢 |
refactor |
Code change that neither fixes a bug nor adds a feature | - |
revert |
Reverts a previous commit | depends |
style |
Formatting only (whitespace, no logic change) | - |
test |
Adding or fixing tests | - |
Versioning stays semantic: patch 🟢 for bug fixes, minor 🟡 for
backwards-compatible new functionality, major 🔴 for a breaking API change.
The semver column reflects the typical mapping - the authoritative bump is
whatever the project's conventional-changelog release setup produces.
ℹ️ commitlint also enforces the commit scope (
custom-scope-enum): it must be one of the project packages -design-tokens,icons,identity,lit,magma,magma-react,magma-angular,stencil,storybook,styles,svg-icons(plus each web component). Example:feat(magma): add ghost variant to mg-button.
- One issue = one problem. Do not bundle several requests together: they are triaged and closed separately.
- Add context; do not expect us to guess. Screenshots, logs, Figma links, or a reproduction are worth a thousand words.
-
Stay responsive. If an issue is in
status: needs-infoand no reply comes, it is eventually closed (it can always be reopened). - Be kind. This applies both to those who open and those who answer: the Code of Conduct is part of contributing.
- Label system - what each tag means and how it is used
- Contribution flow - from issue to release
- Contribution model - roles and dynamics
Magma Design System - Maggioli. This wiki is maintained by the community; spot something wrong? Open a Documentation issue.