Carbon is an ecosystem of open-source projects. This design system is the result of community contributions of code, design, ideas, and guidance.

Roles and responsibilities

Users

Users are members of the community who are using Carbon guidelines, components, and tooling. Anyone can be a user, and we encourage users to participate in the community as much as possible.

Contributors

Contributors are members of the community who contribute to Carbon in a material way. Anyone can be a contributor. In addition to participating as a user, they also can contribute by:

  • Supporting new users and answering questions on Slack (IBM internal)
  • Reporting bugs or missing features through GitHub issues
  • Fixing bugs, adding features, and improving documentation through GitHub pull requests

Maintainers

Maintainers are members of the community who are committed to the success of individual Carbon projects. Each project has a team of maintainers, and each team has a lead. In addition to their participation as a contributor, maintainers have privileges to:

  • Label, close, and manage GitHub issues
  • Close and merge GitHub pull requests
  • Nominate and vote on new maintainers

Teams

Core team

Core team members are IBM employees responsible for the leadership and strategic direction of the Carbon Design System as a whole. The core team also directs how the IBM Design Language is reflected in digital products and experiences. Core team responsibilities include:

  • Actively engaging with users, contributors, and maintainers
  • Setting overall direction and vision
  • Setting priorities and release schedule
  • Focusing on broad, cross-cutting concerns
  • Spinning up or shutting down project teams

Project teams

Project teams are narrowly focused on specific areas of interest. Although not required, it’s recommended that project teams include at least one member of the core team to help ensure coherent project vision. Under the distributed model, project teams operate independently, though it’s recommended that they follow this governance structure to define roles, responsibilities, and decision-making protocols.

Each project team has a lead maintainer, responsible for:

  • Acting as a point of primary contact for the team
  • Participating in the technical steering committee
  • Deciding on the initial membership of project maintainers (in consultation with the core team)
  • Determining and publishing project team policies and mechanics, including the way maintainers join and leave the team (which should be based on team consensus)
  • Communicating core vision to the team
  • Ensuring that issues and pull requests progress at a reasonable rate
  • Making final decisions in cases where the team is unable to reach consensus (should be rare)

The way that project teams communicate internally and externally is left to each team, but:

  • Technical discussion should take place in the public domain as much as possible, ideally in GitHub issues and pull requests.
  • Each project should have a dedicated Slack channel (IBM internal).
  • Project teams should actively seek out discussion and input from stakeholders who are not members of the team.

Project team categories

Design

Design kits and designer tooling.

Elements

How the IBM Design Language is implemented.

Components

Component implementation, appearance, and behavior.

Website

Online presence.

Add-ons

See add-on guidance for custom components that follow the IBM Design Language.

Technical steering committee

Each project lead is expected to participate in the technical steering committee to foster collaboration among the core team and all project teams. This close communication on cross-cutting concerns greatly mitigates the risk of misalignment that can come from decentralized efforts.

Decision-making

Consensus

Project teams use consensus decision-making with the premise that a successful outcome is not where one side of a debate has “won,” but rather where concerns from all sides have been addressed in some way. This emphatically does not mean design by committee, nor compromised design. Rather, it’s a recognition that every design or implementation choice carries a trade-off and numerous costs. There is seldom a 100% right answer.

Breakthrough designs sometimes end up changing the playing field by eliminating tradeoffs altogether, but more often, difficult decisions have to be made. The key is to have a clear vision and set of values and priorities, which is the core team’s responsibility to set and communicate, and the project teams’ responsibility to act upon.

Whenever possible, seek to reach consensus through discussion and design iteration. Concretely, the steps are:

  • New GitHub issue or pull request is created with initial analysis of tradeoffs.
  • Comments reveal additional drawbacks, problems, or tradeoffs.
  • The issue or pull request is revised to address comments, often by improving the design or implementation.
  • Repeat above until “major objections” are fully addressed, or it’s clear that there is a fundamental choice to be made.

Consensus is reached when most people are left with only “minor” objections. While they might choose the tradeoffs slightly differently, they do not feel a strong need to actively block the issue or pull request from progressing.

One important question is: consensus among which people, exactly? Of course, the broader the consensus, the better. When a decision in a project team affects other teams (e.g. new/changed API), the team will be encouraged to invite people (e.g. leads) from affected teams. But at the very least, consensus within the members of the project team should be the norm for most decisions. If the core team has done its job of communicating the values and priorities, it should be possible to fit the debate about the issue into that framework and reach a fairly clear outcome.

Lack of consensus

In some cases, though, consensus cannot be reached. These cases tend to split into two very different camps:

  • “Trivial” reasons, e.g., there is not widespread agreement about naming, but there is consensus about the substance.
  • “Deep” reasons, e.g., the design fundamentally improves one set of concerns at the expense of another, and people on both sides feel strongly about it.

In either case, an alternative form of decision-making is needed.

  • For the “trivial” case, the project lead will make an executive decision or defer the decision to another maintainer on the team.
  • For the “deep” case, the project lead is empowered to make a final decision, but should consult with the core team before doing so.

Contribution process

Carbon Design System projects typically use a fork and pull request workflow for contributions. Specific instructions can be found in each project’s GitHub CONTRIBUTING.md file.

Contributor License Agreement

We require contributors outside of IBM to sign our Contributor License Agreement (CLA) before code contributions can be reviewed and merged. If you have questions, please contact the core team.

Support

Have questions? Found a bug? Learn where to go and what to do by visiting the Support page.