ibm-carbon

IBM Carbon — design system operations

Research snapshot: 2026-07-30. This file records publicly documented operating practices and does not recommend a model for another system.

1. Governance

• Carbon is an open-source IBM design system with a core team and a broad community. Anyone can contribute code, design, or documentation; Carbon maintainers review code pull requests and perform the merge. A signed IBM Contributor License Agreement is required before code can be reviewed and merged. Getting started with contributing
• Carbon’s published governance has included a steering committee of Carbon practitioners that represents customer and business needs, provides oversight and direction, and supports consistency across IBM’s design and development community. Partners
• New components are multidisciplinary contributions. The Carbon team triages proposals, prioritizes larger work by business impact and reuse, and allocates Carbon resources during Delivery. Getting started with contributing, Product Development Lifecycle
• The IBM Figma Guild is not part of the Carbon team but is a governance partner: it maintains, tracks, and peer-reviews IBM Figma best practices used as design-kit requirements. Component checklist
• Carbon Labs is a separate, community-organized IBM incubation environment for unfinished design-system work, keeping explorations apart from stable production assets. Getting started with contributing

2. Component lifecycle

• Carbon’s Product Development Lifecycle uses Discovery → Delivery → Launch and scale. The component checklist maps public status to these phases: Draft (Discovery; partly complete and ready for validation), Preview candidate (Discovery; partly complete with measurable results, stakeholders, and business value), Preview (Delivery; mostly complete, usable in production, but still subject to change), and Stable (Launch and scale; complete across design spec, code, documentation, and design kit). Component checklist
• Carbon renamed its former “experimental” Delivery status to Preview to communicate more confidence and explicit production availability while still allowing breaking changes based on feedback. Product Development Lifecycle
• New components should enter Carbon Labs during Discovery. Delivery work must establish a Figma source of truth with robust specs and initial usage guidance, demonstrate business value, and be prioritized against other contribution work. Breaking code changes can be introduced behind a feature flag. Product Development Lifecycle
• Stable is gated by the full “definition of done” checklist across design specification, code, documentation, and design kit. The checklist includes tokenization, globalization, responsiveness, typed APIs, Storybook stories, tests, accessibility verification, migration support/codemods where needed, and long-form documentation. Component checklist
• Deprecation precedes removal, with long deprecation periods and migration support treated as API design requirements. Carbon publishes a deprecations page and migration guides for superseded packages and platform support. Component checklist, Deprecations

3. Contribution process

• Small contributions begin by selecting an issue labeled for community contribution or filing a proposal/bug through a GitHub template after searching the backlog. The Carbon team triages new ideas. Getting started with contributing
• Contributors iterate publicly in the GitHub issue and often work in small groups or attend office hours and guild sessions for feedback. Getting started with contributing
• Code is submitted by pull request and reviewed by maintainers; after revisions, a maintainer squash-merges the contribution. A signed CLA is mandatory. Design-only work is completed in coordination with the Carbon team. Getting started with contributing
• New components require the Product Development Lifecycle and full component checklist. Expected deliverables include rationale, research/business value, design spec, design-kit asset, usage/style/code/accessibility documentation, and supported-framework code. Getting started with contributing, Component checklist
• Component proposals start as GitHub issues describing rationale, intended behavior, whether the work is a variant or new asset, and optionally mockups and precedents. The issue is the staging area for community discussion and collaboration. Component contribution guidance

4. Versioning and release cadence

• Carbon publishes independently versioned packages and uses semantic major release lines. Its public release history maps Carbon system versions to corresponding package major versions and publishes migration guidance for major changes. Releases
• The main repository publishes frequent v11.x GitHub releases and release notes. Carbon repository and releases
• Major migrations are communicated through release pages, migration guides, codemods, deprecation dates, and replacement package instructions. Carbon’s deprecations page records end-of-support dates and supported alternatives. Releases, Deprecations
• Carbon’s public GitHub discussions include a pinned release-schedule announcement, while the repository release history shows a high-frequency stream. The cited public pages do not define one permanent cadence that applies to every package and asset. Carbon discussions, Carbon releases

5. Documentation structure and templates

• Component documentation is organized into Usage, Style, Code, and Accessibility tabs. Carbon publishes separate templates for single-variant and multiple-variant components, plus code and accessibility templates. Component contribution guidance, Component checklist
• Usage guidance explains when and how to use a component; style guidance covers structure, color, type, size, and other visual specifications; code guidance includes implementation, snippets, dependencies, and version changes; accessibility guidance is written with accessibility subject-matter experts. Component checklist
• Stable components require long-form documentation on both Storybook and a Carbon ecosystem website, plus default and playground Storybook stories. Component checklist
• A component contribution includes a rationale, interaction description, annotated design spec with color and type tokens, design-kit asset, usage documentation, working framework code, and code documentation. Component contribution guidance

6. Naming and token conventions

• Carbon token names communicate role rather than raw value. In v11, color tokens use the pattern [element]-[role]-[order]-[state]; most numeric suffixes were replaced by descriptive adjectives, while layer tokens retain ordering where it conveys stack depth. v11 design migration guide
• Sass tokens use a $ prefix, for example $text-secondary and $layer-01. Token values vary by theme while names and roles remain consistent. Color overview, Themes
• Token categories include color, spacing, typography, and global tokens, distributed through packages such as @carbon/themes, @carbon/layout, and @carbon/type. Themes, Carbon repository
• Component styles may not contain magic colors or numbers that should be tokenized. Figma components follow IBM’s component naming convention and file/component hierarchy guidance, reviewed by the Figma Guild. Component checklist

7. Accessibility criteria and enforcement

• Carbon components follow the IBM Accessibility Checklist, based on WCAG AA, Section 508, and European standards. Accessibility overview
• Stability requirements include accessibility verification tests, tokenized color, required contrast, keyboard behavior, screen-reader support, responsiveness, and documented accessibility guidance. For example, the component checklist requires 4.5:1 text contrast except for disabled states. Component checklist
• Automated Accessibility Verification Tests run for every proposed code change using the IBM Equal Access Accessibility Checker. Carbon also performs periodic manual testing, including screen-reader tests. Component accessibility status
• The public accessibility matrix reports testing separately for default state, advanced states, keyboard navigation, and screen readers with statuses including Tested, Partially tested, Manually tested, Not available, and Not tested. Preview/unstable components may defer testing; the matrix is published for stable @carbon/react components. Component accessibility status
• Accessibility guidance is a required documentation tab and is written with accessibility subject-matter experts. Component checklist

8. Audit and review cycle

• Carbon runs accessibility tests on all components for every latest release and publishes a current status matrix for stable components. Automated verification runs on each proposed code change, while manual screen-reader testing occurs periodically. Component accessibility status
• The definition-of-done checklist is both a readiness gate and a way to assess incomplete assets: teams can work backward from the stable requirements to locate a component in the lifecycle and prioritize missing work. Component checklist
• Launch and scale requires success criteria or learning objectives that continue to be monitored after launch. Product Development Lifecycle
• Deprecated packages and assets are maintained in a central public deprecations register with end-of-support state, replacement guidance, and migration resources. Deprecations
• Design-kit practices are maintained, tracked, and peer-reviewed by the IBM Figma Guild. Contribution work is also reviewed continuously through GitHub issues, office hours/guilds, and maintainer pull-request review. Component checklist, Getting started with contributing