Carbon Design System

When building components in the Carbon ecosystem, it’s essential that we align on a “definition of done” to ensure all components are being built with the same quality and assurance.

Definition of done
Design spec
Code
Documentation
Design kit

Definition of done

By aligning on the requirements of component stability, we can easily prioritize a backlog of work, share the status of assets with contributors and better differentiate when an asset is a component versus a pattern. We can also work backward from this strict list of requirements to inform where a component currently is in the Product Development Lifecycle (PDLC). With each phase, the component should progress in its completeness. Once it has reached stable and all items in the following checklists have been completed, then the component will be considered done.

Note: Although not all published assets currently meet these requirements, moving forward, we’d like all new assets to adhere to them.

Status	PDLC Phase	Description
Draft	Discovery	Partially complete, ready for validation.
Preview candidate	Discovery	Partially complete, with measurable results, stakeholders, and clear business value.
Preview	Delivery	Mostly complete, changes possible based on feedback, available to use in production.
Stable	Launch and scale	Complete across code, kit, docs, design, and ready for production use.

Design spec

The design specification (spec) is the blueprint used by developers to build the component in code and for designers making the component in Figma. It is referenced as the source of truth for the visual appearance and functionality of a component. Having an accurate and detailed design spec ensures the component will be built and represented consistently across experiences.

Requirement	Details	Why this matters
Color tokens	Design specs only use color tokens available in the system. Design specs only contain colors that are tokenized. Color token usage is correct according to our documentation and matches applications across the system.	Color tokens are essential to the reusability and scalability of the system; they support a11y requirements and reduce the maintenance burden. They also allow for consistent application of color across the system, and make color functionalities like theming possible.
Type tokens	Design specs only use type tokens available in the system. Design specs only contain type styles and sizes that are tokenized. Type token usage is correct and consistent with matching applications across the system.	Type tokens are essential to the reusability and scalability of the system and they reduce the maintenance burden. They also allow for consistent type use across the system.
Structure and measurements	Design specs only use spacing tokens available in the system. Clearly annotate spacing and alignment for all design elements. Design specs include all possible configurations such as sizes and content configurations.	Detailed structure and measurement specs allow developers to build assets quicker and ensure that designs are accurately represented in the code.
Interaction states	Designs include specs for states such as hover, focus, selected, disabled, read-only, error, warning, etc.	Each state of the component needs to be represented in the specification to ensure that accessibility requirements and quality of the designs are accurately represented in the code.
Behaviors	Designs include specs for behaviors such as responsiveness, content overflow or reflow, expansion, scrolling, etc.	Developers need to understand how the asset will behave when a user interacts with it. Detailed annotations and specs of the various behaviors will ensure that the designs are accurately represented in the code.
Accessibility	All text colors pass 4.5:1 color contrast with the exceptions of disabled states. All interactive non-text elements meet 3:1 contrast. Flow of focus is clearly documented.	IBM products must meet WCAG AA accessibility standards.

Code

In order for code to be stable, it must meet the requirements in the table below. Preview code should plan for these requirements, but does not need to meet them in the discovery or delivery phases. For additional guidance how we prefer to write code for the Carbon Design System, see the Carbon Style Guide.

Requirement	Details	Why this matters
API guiding principles	Prioritize end user: emphasize the consumer/dev experience above difficulty of implementation. Interoperability: support wide band coverage of multiple React versions, node LTS versions, etc. and favor framework/library agnostic approaches to component APIs and designs. Stability: always deprecate before removal, ensure long deprecation periods, consider the migration experience for developers. Composition: components should be broken down into logical pieces to support the many disparate configurations that are required by the business. Developer experience: consider how a developer will use this component; will they find it approachable or confusing?	Careful consideration of API design ensures that future changes to the system can be made in an iterative way that minimizes disruption. Developer experience and productivity can be heavily influenced by needlessly complex APIs. The business has a wide range of requirements and should meet as many of them as possible. Prioritize the user wherever possible — if you can make things easier for them by writing extra code, handling complexity internally, or taking care of a common concern, do so. It’s our job to contain chaos so that it’s easier and faster to build excellent software products.
Built to spec	Every interaction spec’d should be implemented. The design spec should match the implementation perfectly down to the pixel.	Thorough implementation with intense attention to detail is pivotal to maintaining pervasive design excellence within the system. This high bar of quality sets our system apart and drives adoption, user satisfaction, and overall outcomes.
Tokens	Component styles use tokens available in the system. Component styles do not contain magic numbers or colors that are not tokenized.	Tokens are essential to the reusability and scalability of the system — they support a11y requirements and reduce the maintenance burden within the system.
Globalization	All strings are configurable and parameterized (props) in a way that is agnostic and compatible with a wide range of g11n i18n solutions/libraries.	Ensures assets can be reused within products and offerings worldwide.
Responsiveness	Component layout, functionality, and ux works on all device sizes from very large to ~320px wide. Component styles use media queries where needed.	Ensures assets work properly on small screens so that IBM products and offerings can be used on as many devices as possible.
Storybook	A default and playground story exists in Storybook.	Ensures re-usable code and a demo are available.
Documentation	Long-form documentation is provided in both storybook and the carbon website.	Usage examples in the Storybook do not answer all questions, cover all interactions, or provide pointed helpful information regarding the intended component usage and configuration.
Fully Typed/JSDoc	Component has an interface with all props typed. Component interface is exported for use in consuming projects.	Ensures that components and assets are built using Typescript to attain the inherent benefits of strongly typed programming language, but also provides a best-in-class developer experience (particularly through intellisense), even for those not using TypeScript in their projects.
Codemods	If the component/change will require migration by consuming teams, an automated code migration script should be written and made available through @carbon/upgrade .	Ensure that consumers using a given component will have a graceful experience when breaking changes occur. Also holds a lot of weight as to the perception of the system’s ability to adapt and innovate while maintaining a laser focus on stability. Reduces the cost spent by a team to migrate — compounded across all the teams we support across IBM this can have a significant impact on IBM’s bottom line in cost/productivity.

Testing

A crucial aspect to ensure continued quality of production stable code is testing. The following testing requirements must be met before a component can be considered stable.

Requirement	Details	Why this matters
Unit testing	Component API and functionality should be thoroughly tested using jest and testing-library (therefore in a jsdom environment). Component unit test coverage should meet and exceed 80% of functions, lines, statements, etc.	Validates and ensures that components work as they’re expected to and regressions are not introduced as changes are made.
Visual regression tests (VRT)	Component has at least one test on the default story for VRT using Percy. Additional “problematic” or highly concerning component states, stories, viewport-widths can be covered by VRT.	Ensures that components do not visually regress as changes are made. This catches bugs early, avoids disruptive mistakes, and supports the overall stability of the system.
Accessibility verification tests (AVT)	Component has one test of it’s default state checked by the IBM Equal Access Accessibility Checker. Component has all additional “complex” states (open, closed, highlighted, expanded, focused, hovered, clicked, etc) checked by IBM Equal Access Accessibility Checker.	Ensures that components and assets are accessible. First and foremost this is a moral imperative; accessibility benefits everyone. It additionally supports the goal of IBM products and offerings being able to be sold and used in industries bound by law to have accessible experiences.
Screen reader/voiceover	Component has been manually tested to read appropriately in JAWS, VoiceOver, and NVDA.	Ensures that components and assets are able to be used by disabled users who utilize screenreaders. First and foremost this is a moral imperative; accessibility benefits everyone. It additionally supports the goal of IBM products and offerings being able to be sold and used in industries bound by law to have accessible experiences.

Documentation

All components and patterns require usage, style, code, and accessibility guidance published on a Carbon ecosystem website. Carbon provides documentation templates to help ensure visual and content expectations. Additional guidance on creating layouts and images for website documentation can be found in the image production guidelines.

Requirement	Details	Why this matters
xxUsage docs	Single variant template (last updated Q1 2024). Multiple variant template (last updated 2021).	The usage documentation helps describe when to use a component and how it works.
Style docs	Single variant template (last updated Q3 2024). Multiple variant template (last updated Q3 2024).	The style documentation helps describe how a component looks, including visual specifications such as color, typography, structure, and size.
Code docs	Code template (last updated 2022).	The code documentation helps developers implement the component. It includes code snippets, dependencies, and version changes. Although Carbon developers write more detailed documentation in Storybook, they still provide several standard pieces of information on the Carbon website.
Accessibility docs	Accessibility template (last updated 2023).	The published information, written by our A11y SMEs, helps users understand all the accessibility considerations that are baked into Carbon.

Design kit

Our IBM Figma best practices are maintained, tracked, and peer-reviewed by IBM’s Figma guild. Although the guild is not part of the Carbon team, they are crucial partners in our governance model.

Requirement	Details	Why this matters
IBM Figma Guidelines	Figma components follow the guidelines as defined in IBM Figma Best Practices. The guidance includes topics on component properties, auto layout, styles, icons, item and base components, content, construction, and file organization.	This checklist ensures components are built correctly before merging into the main Figma branch.
IBM Figma Naming Convention	Figma components follow the component naming convention documented in IBM Figma Best Practices.	The naming convention ensures that file architecture and component hierarchies are both standardized and intuitive for the user. With this method we are able to have hierarchy between the final components, their bases, and their pieces when we traverse through the assets/instance swapper panels while still being able to view the entire component name when searching.
Built to spec	The Figma component should match the design spec perfectly down to the pixel. Every interaction spec’d should be included in the Figma component.	Thorough implementation with intense attention to detail is pivotal to maintaining pervasive design excellence within the system. This high bar of quality sets our system apart and drives adoption, user satisfaction, and overall outcomes.
Published to a library	A Figma component must be published to the appropriate IBM Figma library. Components built in the Carbon repo are published in (V11) Carbon Design System.	A published connected component ensures accurate use across products. It also allows for Figma analytics to understand adoption and usage better.

Edit this page on GitHub

Contributing: Get started