Repository navigation
Steps reference
This page describes every step and checkpoint in the Magma contribution process, once. The per-type pages (Bug fix, Small enhancement, Large enhancement, New feature, New feature across components, Major initiative) don't repeat these descriptions — they just list the ordered path through them. If you want to know what a step means or how to do it, this is the place.
How to read it. The process is organised in phases — Propose → Design → Code → Submit → Doc → Release — and moderated by the core team at three checkpoints. Not every step applies to every contribution; your contribution type tells you which ones you follow.
Under the moderated model you interact with the core team, not with a wider community. The core team acts as the gate at three points.
Right after you open the proposal. The core team decides whether the contribution moves forward, confirms its type, and assigns labels and a milestone — or asks for more detail, or declines with a rationale. This replaces the old "review by system team" and "present to community" steps.
Before any code is written. The core team reviews the design (UI, tokens, accessibility, feasibility for implementation) and either approves it or requests changes. Only an approved design proceeds to code. This replaces the old "present to assigned developer / system team / design community" and the separate designer / developer / accessibility / content-strategy reviews.
On the pull request. The core team reviews the code (standards, quality,
accessibility, design consistency) and merges it into dev, or requests changes.
The phase where you state why the change is worth making. It's the direct link between you and the core team, and the tool the team uses to decide whether the work enters the flow, is redirected, or is dropped.
Before proposing, make sure there isn't already an issue about this work. Search the issues and the project board — it's good practice to check before opening a new one.
Open the matching issue template. It captures your proposal and queues it for the core team. Answer the basics: what? why? for whom / how many? by when?
Sketch the requirements needed to build the work. For simple UI components a list of Must / Should / Could / Won't is often enough. A complex proposal (say a grid layout with rows, columns, offsets, breakpoints) may run to pages and include proposed values and code demos. These details drive feature prioritisation during the checkpoints.
Once the triage checkpoint accepts the proposal and its scope is set, plan how to deliver it: for larger work, a parent (tracking) issue plus independently shippable sub-issues, with internal steps kept as checklists. Everything is tracked on GitHub — issues, sub-issues and the project board.
When the work needs it, produce the design that shows the core team how the result will look and behave (UI and UX). If you're not confident designing, ask a colleague or a system designer for help.
Create your file from the shared Magma libraries so you inherit the existing styles and components. Pick the file that matches what you're changing: Components, Design Tokens, SVG Icons, Typography, Identity.
If the work extends something that already exists, build on it — add new views that cover the new behaviour rather than starting from scratch.
Represent the features clearly, so they give developers a concrete reference to build from.
Keep the design aligned with the shared Design Tokens
(and the design-tokens package) so components stay consistent.
Add notes that help anyone viewing the design understand what each part is and how it behaves.
Verify the design meets Magma's accessibility standards (contrast, states, focus order) and that the UX patterns you've used are current. Automated accessibility checks come later, in Storybook, during Code.
After this, the design goes to the design-validation checkpoint.
Make sure the visuals and annotations are complete, the tokens are integrated, and the details are expanded before handing off to implementation.
The implementation phase and the flows around it.
Create a branch for the work. Branch and commit naming follow the type enum in
commitlint.config.js
— note the custom change type, used for breaking API changes.
Set up the file structure needed to introduce the feature, fix or change.
Before committing and pushing, get the code to a point where it's functional and runnable.
Design an API that follows Magma's standards.
Write the HTML, CSS, JavaScript/TypeScript and any other required formats. For web components, the project provides a Stencil scaffolding command that helps you create them.
Add a Storybook view for the component. Storybook is where visual testing happens; its accessibility (a11y) addon also covers accessibility checks — there's no separate manual/automated accessibility step anymore.
Add documentation explaining how the API you implemented behaves.
Update the affected package.json dependencies for the components involved in
the change.
Add unit tests. The web-component environment provides a dedicated set of testing utilities.
Test on the browsers and devices Magma supports. The support matrix is the
.browserslistrc
in the repo — that file is the source of truth, so check it rather than relying
on a copy here.
Visual regression testing is not part of the flow at the moment. The old manual suite was too costly to maintain and has been removed; visual regression will be reintroduced through Storybook when feasible. You don't need to do it today.
Add functional tests to confirm the API actually works at runtime.
Record the changes you made in the changelog. Breaking changes must be called out clearly.
Open a merge request from your branch to dev, linked to its issue, so the code
can be added to the main codebase. For smaller contributions the documentation
can travel in the same PR; for larger ones it's a separate step (see below).
This is where the review & merge checkpoint happens.
The final development phase: the information that becomes public for everyone who uses the Design System.
Publishing target is deferred. The documentation site is being rebuilt and is out of scope for now. Write and review the documentation as described here; the "package for publishing" destination will be defined when the site is ready.
Write the documentation for your work following the existing template.
Reuse existing documentation and images where you can.
Write an introduction to the component and what it's for.
If you only need to update existing documentation — for example adding a colour to an existing set — extend the current page instead of writing a new one.
Add usage examples that help people understand how to use it.
Show how it can be used at the design level and how to combine it with other elements.
The do's and don'ts for avoiding accessibility problems.
How to write the content that goes inside the element.
Update the Figma files where the change or feature was applied.
Prepare static images that represent the component and its main features.
Finalize the written documentation and make sure everything is in order.
The core team releases the merged work, following the Contribution model. The release impact (patch / minor / major) depends on the contribution type — see each type's page for the typical outcome.
Questions about any of this? Ask on the Stack Overflow channel.
Magma Design System - Maggioli. This wiki is maintained by the community; spot something wrong? Open a Documentation issue.