The design system is part of everyday shaping and shipping work. Product designers and engineers across R&D own it and contribute to it as part of their normal work, using their judgment about how best to use it and when to contribute back.
There's no central team that builds the design system or approves your changes. The upside is that you're not waiting on someone else's cycle. The trade-off is that the call is yours, with support from the people around you.
Two groups help hold the system together:
The ODS community is all R&D engineers and designers. It works async in #topic-design-system, where anyone at any level is welcome to weigh in. This is not a request queue, and nobody is on duty to answer. Read it when you can, and answer questions you're able to help with.
The leadership circle is a cross-functional group of design directors and key engineers who set the direction of the design system. They meet once a cycle in line with the shaping cadence. They're not a gate, and they don't need to approve your changes. Pull them in with @design-system-leaders when a decision feels high-impact.
Changes are announced in #feed-design-system.
For the full operating model, including how the leadership circle runs, see How we work: Design System in Confluence.
What counts as a contribution
Contributions fall into five types. Identifying which one you're making tells you how to proceed.
- Design tokens: creating, changing, updating, or deprecating a token
- Icons: creating, updating, or deprecating an icon
- Core components: creating a new component or variant, updating one, promoting a local component to core, or deprecating one
- UI patterns: adding, changing, or deprecating a pattern
- Documentation: adding, updating, or deprecating any documentation, excluding the Brand section
These are not contributions:
- Local components. Building a local, one-off component for your own screen isn't a contribution. As a rule of thumb, if the thing you're building could be used in three places right now, that's a strong signal to contribute it instead.
- Questions about a specific component. Check the usage guidelines in the component documentation, then ask in #topic-design-system.
- Feedback on how you're using the design system. Post in #topic-design-system for a review of your usage.
Getting started
These two steps apply to every contribution.
- Start a conversation. Post in #topic-design-system with the problem you're solving before you start work. This avoids doubling up and surfaces solutions you might not know about.
- Confirm feasibility during shaping. Your team owns this. During shaping, build confidence that the contribution solves the customer problem and is buildable. This isn't a design system gate, it's part of your team's normal way of working.
How much process you need
The rest depends on impact, not on how much work it is. A one-line change to the primary button color is trivial to make and very high impact.
|
Impact |
What to do |
|---|---|
|
Low |
Go ahead, self-directed. Communicate the change. Lean on peers if you want support. |
|
Medium |
Bring it to the community in #topic-design-system. Peer review is strongly recommended. Consider writing a proposal. |
|
High |
Raise it with @design-system-leaders. A proposal is strongly recommended. |
Roughly, by type:
|
Type |
Low |
Medium |
High |
|---|---|---|---|
|
Design tokens |
Fixing an incorrect value or a naming typo. Updating token documentation. |
Creating a new token or category. Renaming a token, which affects every component referencing it. Deprecating a token. Any breaking change for consuming components. |
Foundational rework of the token architecture, such as a new naming system or restructuring color. Changing the primary button color. |
|
Icons |
Creating an icon that follows existing naming and category conventions. Updating an icon's appearance. Fixing a rendering issue. |
Deprecating an icon other teams may be using. Changing naming conventions or categories. |
Replacing the icon system. |
|
Core components |
Fixing a defect in design, code, or documentation. Adding a state or variant that doesn't change the API or behavior. Design tweaks. Updating documentation. |
Adding functionality that changes behavior or the API, such as making an alert dismissible. Creating a new core component. Promoting a local component to core. Deprecating or replacing a component. Reworking structure, behavior, or interaction. Any breaking change. |
A new component category, or reworking a foundational component that touches most surfaces, such as navigation or layout. |
|
UI patterns |
Fixing errors or unclear language. Adding examples or clarifications to an existing pattern. |
Creating a new pattern. Changing the recommended approach in an existing pattern. Deprecating a pattern. |
Reworking a core interaction pattern that affects many teams and surfaces, such as forms, error handling, or onboarding. |
|
Documentation |
Fixing typos, broken links, or out-of-date information. Clarifying or expanding what's there. Documenting new or modified components. |
Creating new documentation sections. Establishing conventions or terminology other documentation will follow. |
Restructuring the documentation architecture or information model. |
A few things worth knowing when you read that table:
Tokens cascade. They're the foundational values that components are built on, so even small changes can ripple further than you expect. Post in #topic-design-system early when in doubt.
Components have the most variation. For new components and major reworks, write a proposal before bringing it to the community. The community's focus is system-level fit: where the component belongs, what to call it, and whether it overlaps with something that already exists. The community doesn't assess feasibility, which is your team's call, or design quality, which happens in design review.
UI patterns look like documentation but behave like architecture. They set conventions that affect consistency across the product. If a pattern change would shift how teams approach a common interaction, bring it to #topic-design-system.
Proposals
If impact is medium to high, write a proposal. Some examples to work from:
- TODO: link Proposal: Text Field Actions
- TODO: link Proposal: Renaming Layout Components
- TODO: link Decision: Client Side & Server Side Validation
- TODO: link Future of Material UI
Review
Use the level of review the contribution warrants. These happen in parallel, not in sequence.
- Design review checks quality and correctness: does it look right, behave correctly, and follow existing conventions? Request a peer review async in #team-design or in person at Design Lab.
- Engineering review follows your team's standard process. If you want input from other front-end experts, ask in #topic-frontend.
- #topic-design-system helps assess system-level fit: where this belongs, what it should be called, and whether it overlaps with something existing.
Release
You don't need to wait for a component to be built before publishing it in Figma or in the documentation. If we've decided that's where we're going, commit to it.
When you release, make sure you've covered:
- The component is published in the Figma Component Library
- Code Connect is set up, linking the Figma component to the code component
- The documentation covers usage, anatomy, variants, and dependencies
- The component status is set correctly
- Anything deprecated follows the Deprecation Guidelines
- You've announced the change in #feed-design-system, following the Communicating Changes guidelines
Code Connect and documentation are the two steps most likely to get skipped, and the two that cost other teams the most when they are. The next section explains why.
Working with AI
Most front-end work at Octopus now involves an AI assistant, which changes what the design system has to do.
Code Connect is what makes AI-generated front-end accurate. It tells the assistant that a given Figma layer is a specific component in our library, and what the code for it should be. Without it, an assistant pointed at a Figma file can only guess, and it usually guesses a local component. If you contribute a component and skip Code Connect, you've made the design system slightly worse at the thing people rely on it for.
Documentation is now read more by assistants than by people. Views of these docs are down since the start of the year, and most remaining traffic lands on the home page. People ask Claude what's in the design system rather than browsing. Thin or out-of-date docs produce wrong answers at scale.
AI prototypes don't use real components. They approximate them. That's fine for exploring a shape, but treat a prototype as a description of intent rather than something to translate literally. Before you build, work out which real components it was reaching for.
Generated code still needs someone who understands it. If you can't explain a front-end change in review, it isn't ready. If you're reviewing a large front-end PR, ask what the author was thinking. Slowing down to learn now is cheaper than owning pages nobody understands in a year.
If you want to build your front-end skills directly, see Learning Resources. TODO: link School of Frontend when it relaunches.
When you can't finish it this cycle
Sometimes the right contribution surfaces mid-cycle and there's no room for it. Don't drop it, and don't quietly ship a local component and move on.
- Write down what you found and what you'd do about it
- Raise it with your EM so it lands on your team's backlog and can be prioritized later
- If you shipped a local component in the meantime, say so in #topic-design-system, so the next person hitting the same problem finds your notes
Not everything gets fixed, and that's expected. Pages that haven't been touched in a long time cost more to uplift, so call that out during shaping and feasibility, while the cost is still visible.
What we're trying to avoid
This model exists to prevent a specific set of failure modes. If you hit one of these, say so in #topic-design-system:
- Feeling like you can't make small contributions autonomously
- Spending too long seeking approval, or seeking wider consensus than a change needs
- Being unable to start because the process is unclear or has too many hoops
- Being asked to get feedback in a particular sequence
- Having nowhere to escalate a concern or an idea