Component checklist
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
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 |
|---|---|---|
| Discovery | Partially complete, ready for validation. |
| Discovery | Partially complete, with measurable results, stakeholders, and clear business value. |
| Delivery | Mostly complete, changes possible based on feedback, available to use in production. |
| 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 visuals 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 |
| 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 |
| 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 |
| Detailed structure and measurement specs allow developers to build assets quicker and ensure that designs are accurately represented in the code. |
| Interaction states |
| 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 |
| 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 |
| IBM products must meet WCAG AA accessibility standards. |
Code
In order for code to be stable, it must meet all of the following requirements. Experimental code should plan for these requirements, but does not need to meet them in the discovery or delivery phases.
| Requirement | Details | Why this matters |
|---|---|---|
| API guiding principles |
| Careful consideration of API design ensures that future changes to the system can be made in an iterative way that minimize disruption. Developer experience and productivity can be heavily influenced by confusing or 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 we 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 |
| Thorough implementation with intense attention to detail is pivotal to maintaining pervasive design excellence within the system. This high bar of quality is what sets our system apart and drives adoption, user satisfaction, and overall outcomes. |
| Tokens |
| Tokens are essential to the reusability and scalability of the system - they support a11y requirements and reduce the maintenance burden within the system. |
| Globalization |
| Ensures assets can be reused within products and offerings worldwide. |
| Responsiveness |
| Ensures assets work properly on small screens so that IBM products and offerings can be used on as many devices as possible. |
| Storybook |
| Ensures re-usable code and a demo are available. |
| Documentation |
| Usage examples in storybook do not answer all questions, cover all interactions, or provide pointed helpful information regarding the intended component usage and configuration. |
| Fully Typed/JSDoc |
| 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 |
| 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 |
| Validates and ensures that components work as they’re expected to and regressions are not introduced as changes are made. |
| Visual regression tests (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) |
| 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 |
| 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 |
|---|---|---|
| Usage docs |
| The usage documentation helps describe when to use a component and how it works. |
| Style docs |
| The style documentation helps describe how a component looks, including visual specifications such as color, typography, structure, and size. |
| Code docs |
| 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 |
| 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 being merged 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 doing a search. |
| 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 is what 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) All themes - Carbon Design System. | A published connected component ensures accurate use across products. It also allows for Figma analytic tracking. |