Label system

Label system

Labels (the "tags") are used to classify and filter issues. A label set that is too rich becomes unmanageable; one that is too thin does not help triage. Magma uses a few label families, each with a consistent prefix and color, so that the state of an issue is clear at a glance.

🎯 Guiding principle: every label must answer a question that is useful for triage or filtering. If a label does not change a decision, it is not needed.

---

Issue type: labels or "Issue Types"?

GitHub offers two mechanisms that can overlap:

• Native Issue Types (type: bug, type: feature…) — set at the organization level, they appear as a dedicated field rather than a label.
• Labels with the type: prefix — ordinary repository labels.

Using both for the same thing creates confusion. Our recommendation:

• If you have configured Issue Types at the org level → use them for the main type (Bug, Feature, Docs, Task) and remove the type: labels from the templates.
• If you do not have Issue Types → keep the type: labels as in the current templates.

The provided templates include both options: pick one and stay consistent.

---

The label families

status: — where the issue is in its life cycle

Label	Meaning
status: triage	Just opened, to be classified
status: needs-info	Information is needed from the author
status: accepted	Validated, ready to be picked up
status: in-progress	Someone is working on it
status: needs-review	Waiting for review
status: blocked	Stuck on an external dependency
status: wontfix	Will not be worked on (with a reason)
status: duplicate	Already tracked elsewhere

area: — which part of the Design System is involved

Aligned with the monorepo packages:

area: components · area: tokens · area: styles · area: icons · area: identity · area: docs-site · area: storybook · area: build-ci

semver: — the impact on versioning

Maps your versioning scheme (🟢🟡🔴):

Label	Corresponds to	Color
semver: patch	Bug fix, no API change	🟢 green
semver: minor	Backwards-compatible new functionality	🟡 yellow
semver: major	API change / breaking change	🔴 red

review: — which reviews are needed before closing

review: needs-design · review: needs-a11y · review: needs-dev

This reflects the review steps of the contribution flow (system designer, accessibility expert, system developer).

Community labels

Label	Use
good first issue	Suitable for first-time contributors
help wanted	The core team is actively looking for a contributor
needs mentor	A core team mentor is needed to proceed

priority: (optional, set by the core team)

priority: low · priority: medium · priority: high · priority: critical

---

Managing labels "as code"

Managing labels by hand from the GitHub UI is not reproducible and drifts over time. It is better to define them in a versioned file and sync them automatically.

You will find .github/labels.yml in the repo. You can sync it with an action such as EndBug/label-sync or with the github-label-sync CLI:

# .github/workflows/labels.yml
name: Sync labels
on:
  push:
    branches: [main]
    paths: ['.github/labels.yml']
jobs:
  labels:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: EndBug/label-sync@v2
        with:
          config-file: .github/labels.yml
          delete-other-labels: false

This way labels become part of the repository, reviewable in code review like any other file.

⚠️ Set delete-other-labels: false until you are confident: true deletes every label that is not present in the file.