Components are key building blocks of the design system
Components are one of the key building blocks of the Carbon Design System. Each component has been designed and coded to solve a specific UI problem, such as presenting a list of options, enabling submission of a form, or providing feedback to the user. All components in Carbon have been designed to work harmoniously together as parts of a greater whole. Systematic reuse of components helps create visual and functional consistency across products.
Community-maintained components available separately
Additional components maintained by the Carbon community are available in the Community assets component index, separate from the main Carbon Design System components.
Refining an issue before starting code work
Before starting to code, refine the issue by creating a rough task list and posting it in the issue comments. Consider these questions: Are you clear on the scope of the work? Is the task list feasible for you to do? Should a designer get involved to do initial research or create a design spec? Do you need to collaborate with anyone else?
Getting feedback on Carbon code contributions
Most contributors work in groups of 2–3 and either set up weekly sessions or join meetups such as Data Viz Guild or Carbon Developer office hours. Share work in progress and ask questions in these sessions. Update your GitHub issue as you make progress. Code will be reviewed in a pull request where maintainers will review your work, ask questions, and suggest changes. When you need to make a change, commit and push to your branch normally. Once all revisions are complete, a maintainer will squash and merge your commits.
Submitting new ideas or bug reports to Carbon
Before submitting a new idea or bug report, search through the issue backlog on GitHub to ensure it is novel. Then file your proposal using the issue templates on GitHub. If you are willing to work on the idea yourself, mention this in your issue. Your idea will then go through a triage process by the Carbon team.
How to volunteer for existing Carbon issues
The best way to volunteer for work is to look through existing GitHub issues labeled with 'needs: community contribution' or 'needs: code contribution'. To volunteer, put a comment in the issue saying you would like to help. If an issue is already assigned to someone or has a specific milestone, discuss with the assignee or the Carbon team to coordinate.
Good first issue label for new contributors
Issues labeled 'good first issue' are great candidates to pick up if you are working with the code for the first time. The Carbon team is happy to help new contributors. You can join Carbon Developer office hours or contact the team directly for assistance.
Community code contributions process overview
Code contributions to Carbon can include anything from squashing bugs to adding feature requests. New issues submitted by the community are initially triaged by Carbon team members. Any issue that the Carbon team accepts but cannot fit in their roadmap is open for community contribution.
Carbon repositories for code contributions
Code contributions are typically made to one of these repositories: Carbon website (carbon-website), Carbon monorepo (carbon), Carbon Angular (carbon-components-angular), Carbon Vue (carbon-components-vue), or Carbon charts (carbon-charts). Setup instructions are available in the CONTRIBUTING.md file in the Carbon monorepo.
Discovery phase evaluation and advancement
Only the Carbon team can move an asset from discovery to delivery in core Carbon or Carbon for IBM Products. Not all proposals in the discovery phase will move on in the lifecycle; some explorations may not gain traction or may be deprioritized by other efforts. Carbon does not take on ownership and maintenance of certain types of assets like full applications, third party tooling, and shared services.
Delivery phase collaboration
In the delivery phase, the Carbon team usually collaborates with a workgroup or discovery team to begin to codify and implement their asset for preview in the Carbon library.
Delivery phase milestones
Delivery phase milestones include: Carbon team collaborates with subject matter experts and establishes a feasible quarterly roadmap (3-in-a-box perspective), a strong source of truth is established in Figma including robust design specs and initial usage docs, 5–8 stakeholder teams are identified for early usage and feedback, backlog work begins on kit, docs, and code per definition of done, and any breaking changes are integrated into the Carbon library behind a feature flag.
Delivery phase prioritization criteria
Once a contribution enters the delivery phase, it must be prioritized against other contributions and work streams. The most important factor in determining prioritization in the contribution pipeline is business impact. The greater the case for reuse or support for a high-impact team, the more likely a proposal is to move up in the pipeline and garner more Carbon resources.
Launch and scale phase completion requirements
In the launch and scale phase, all requirements from the delivery phase for a component or pattern to become stable must be met. This includes full peer-review completed requirements, with reviews requested early and often on various deliverables.
Launch and scale phase asset status - Stable
All components in the launch and scale phase are stable. This means all requirements in the asset's definition of done are complete and the asset is ready to use in production.
Launch and scale final steps
Once an asset is complete there should be a communication plan in place to raise awareness of the new work across multiple channels. PMs should also begin to track the usage (product insertions) of the new asset via Figma's API and the IBM Telemetry service.
Asset status definitions - Draft
Draft status is used in the Discovery phase. An asset with draft status is partially complete and ready for validation.
Asset status definitions - Preview candidate
Preview candidate status is used in the Discovery phase. An asset with preview candidate status is partially complete, with measurable results, stakeholders, and clear business value.
Asset status definitions - Preview
Preview status is used in the Delivery phase. An asset with preview status is mostly complete, changes are possible based on feedback, and it is available to use in production.
Asset status definitions - Stable
Stable status is used in the Launch and scale phase. An asset with stable status is complete across code, kit, docs, and design, and is ready for production use.
Component asset type definition
A component is an asset that has been designed and coded, that can be imported into a UI. Components have their own definition of done that must be completed before an asset can be considered done.
Pattern asset type definition
Patterns are something that can be accomplished in multiple ways utilizing a combination of component(s) with additional design considerations. Because of the many ways patterns can be implemented, it is not possible to provide code for every scenario, but some patterns do have example code. Patterns have their own definition of done that must be completed before an asset can be considered done.
GitHub pull request review channel
A pull request can be opened in the appropriate Carbon GitHub repo for a final review of a completed contribution. If seeking feedback on a proof-of-concept, a draft pull request should be opened instead.
GitHub issue review channel
A feature request or enhancement issue can be opened in the Carbon GitHub outlining the gap that needs to be resolved. The issue should include all supporting materials and evidence gathered in the discovery phase, which can include competitive research, potential solutions, or prototypes.
Delivery phase asset status - Preview
All assets in the delivery phase are considered in preview status. Breaking changes are still possible based on feedback from use in products. Preview status indicates that an asset is mostly complete and available to use in production, but is not yet stable.
Product Development Lifecycle (PDLC) three phases
The PDLC is organized into three phases: discovery, delivery, and launch & scale. Once a product is in market, agile product teams do all these types of work concurrently, in parallel work streams, with feedback from in-market learnings shaping the priorities of both discovery and delivery.
Discovery phase purpose
The purpose of the discovery phase is to address any major value, usability, feasibility, and viability risks ahead of delivering product-quality code in order to arrive at a successful product faster and at a lower cost.
Delivery phase purpose
The delivery phase emphasizes the disciplined execution of determining how we will realize user value and maximize the efficiency of building it. This includes the functional and non-functional requirements, and the user experience required for customers to adopt product features within a production setting.
Launch and scale phase purpose
Launch and scale involves having clearly defined success criteria or learning objectives that are monitored after launch. In this phase, an asset will become stable and achieve Carbon's definition of done.
Discovery phase innovation requirements
For an enhancement or net new asset to warrant resourcing a discovery phase, proposals need to show that the component or pattern would be useful to many teams and unique to the system. Key considerations include: whether it replicates anything in the system already or if there is truly a gap, evidence that the proposed solution is better if it replicates an existing asset, whether there is already an existing issue or proposal in Carbon or Carbon for IBM Products GitHub, evidence that the new asset or enhancement would be useful for many teams or services, and the ratio of feasibility to impact to help prioritize (consulting developers and accessibility SMEs).
Discovery phase asset statuses
All assets in the discovery phase start as drafts. As the asset progresses in its completeness and validation, it can graduate from draft to preview candidate, meaning it is ready to be reviewed and seriously considered for inclusion as a maintained asset in the system.
Carbon Labs purpose
Carbon Labs is a dedicated environment for discovery, separate from stable design system assets. The purpose of Carbon Labs is to highlight innovation work that is being done in the ecosystem but has not yet met the definition of done (stable) criteria. Both draft and preview candidate design or code assets are welcomed in Labs.
Apply text styles from Carbon Type Sets
To apply a text style, select a text layer, then in the properties panel, choose a text style from the (v11) Carbon Type Sets library. Use color styles to change the color of a text style.
Carbon Figma kit includes four themes
The (v11) Carbon Design System library includes all four Carbon themes: two light themes (White and Gray 10) and two dark themes (Gray 90 and Gray 100).
Internal users access Carbon libraries via IBM SSO
Internal IBM users should sign into Figma using IBM SSO and will be automatically added to the IBM Figma organization. No need to join or request access to specific teams to access the libraries.
Enable Carbon Design System library in Figma
To enable the (v11) Carbon Design System library, navigate to the Main menu panel in the top left of the toolbar, select Libraries from the list, find the (v11) Carbon Design System library in the modal, and select the 'Add to file' button.
Optional IBM Design Language libraries for internal users
Internal users can optionally enable the following IBM Design Language libraries: (v11) Carbon Type Sets - IBM Design Language, IBM® Color Library - IBM Design Language, IBM® UI Icon Library - IBM Design Language, and IBM® Pictogram Library - IBM Design Language.
External users access Carbon via Figma Community
External users should sign into Figma, navigate to the Community icon in the header, search for Carbon Design System, and duplicate the (v11) Carbon Design System library file to their workspace, then publish it as a library.
External users can access additional IBM Design Language libraries
External users can access supplementary IBM Design Language libraries including (v11) Carbon Type Sets, IBM® Color Library, IBM® UI Icon Library, and IBM® Pictogram Library through the Figma Community.
Insert components from Asset panel in Figma
To insert a Carbon component, go to the Asset panel in Figma and find the component you want to use. Drag it from the asset panel onto the canvas. Component variants can be configured using fields and controls in the right sidebar.
Screens asset includes grid configurations
The Screens asset included in the Carbon Figma library provides a canvas configurable at the five 2x grid breakpoints. It includes the 16 column grid both with and without a left panel grid influencer.
TypeScript must resolve JSON modules for importing data
To import JSON files as modules in Angular with TypeScript, the tsconfig.app.json file must include 'resolveJsonModule': true in the compilerOptions. This allows the pattern 'import * as data from ../info.json' to work in component files.
Carbon Angular Tutorial Step 4 overview
Step 4 of the Carbon Angular tutorial focuses on creating custom components using Carbon assets. The tutorial walks through building two reusable components called InfoSection and InfoCard by combining Carbon icons and tokens. The components are designed with considerations for accessibility and responsiveness.
InfoSection and InfoCard component structure
The tutorial builds an informational section with a heading and three subheadings, each with accompanying copy and a pictogram. The parent component is called InfoSection and contains three InfoCard child components. InfoSection displays the title 'The Principles' and passes content from info.json to each InfoCard instance.
InfoSection component styling uses Carbon tokens
The InfoSection component uses @include type-style('heading-01') with @include font-weight('semibold') for the heading. The section has padding-top and padding-bottom of $spacing-09, and uses $ui-01 for background-color. A pseudo-element ::before extends the background using left and right values of -$spacing-05.
InfoCard component layout and typography
The InfoCard component uses flex display with flex-direction column. The heading applies type-style('productive-heading-03'). The body has margin-top of $spacing-06, flex-grow of 1, and type-style('body-long-01'). The body has a max-width of 75% at breakpoints between 321px and md. Icons have margin-top of $spacing-09.
InfoCard uses ng-content for icon injection
The InfoCard component uses <ng-content></ng-content> within a div with class 'info-card__icon' to allow parent components to inject icon elements as children. This pattern enables the InfoSection component to pass different Carbon icon components into each InfoCard instance.
InfoCard heading split for bold styling
The InfoCard component uses a createArrayFromPhrase function to separate the last word from each heading phrase. The template displays the first words normally and wraps the last word in a <strong> tag to make it bold. The function splits on spaces, removes the last word with pop(), and rejoins the remaining words.
InfoSection borders use breakpoint-specific styling
At breakpoints down to md, InfoCard elements that are not the second child have a top border of 1px solid $ui-03 with padding-top of $spacing-09. At md breakpoint, odd-numbered InfoCard children have a left border of 1px solid $ui-03. At lg breakpoint, all InfoCard children have a left border of 1px solid $ui-03 with margin-top set to 0.
Carbon Angular icons imported as separate modules
Carbon icons are imported as individual modules for each icon and size. The tutorial imports PersonFavorite32Module, Globe32Module, and Application32Module from '@carbon/icons-angular/lib/[icon-name]/32'. These modules are then imported into the InfoModule's imports array and used with selector tags like <ibm-icon-person-favorite32></ibm-icon-person-favorite32>.
InfoSection and InfoCard components export from InfoModule
The InfoModule must export InfoSectionComponent and InfoCardComponent so they can be used in other modules like HomeModule. The exports array in the module decorator includes these components, allowing them to be used in parent component templates.
Official framework support
The Carbon Design System is built React first with official support for Web Components. Core parts of the system are also officially supported in Angular, vanilla JS, Vue, and Svelte.
Community framework support
Community support exists for other frameworks including Svelte, Lightning Web Components, and vanilla JavaScript. Developers can build components using the Carbon styles by following the guidelines for these frameworks.
Building components with just Carbon styles
Developers wanting to build in different ways can follow the instructions for the Vanilla JS library to access the styles and build out their own components.
Wrapping Carbon components pattern
When using Carbon components in frameworks with dynamic DOM creation, the best approach is to define a wrapping component using the framework's lifecycle callbacks. The wrapping component should instantiate the Carbon component when the DOM element is created (connectedCallback) and release it when destroyed (disconnectedCallback) to prevent zombie event handlers.
Web Components Custom Elements lifecycle example
The following example demonstrates wrapping a Carbon component using Web Components Custom Elements v1 spec: A class extending HTMLElement defines connectedCallback() to instantiate a Carbon component via CarbonComponents.Loading.create() and disconnectedCallback() to call this.loading.release(). The class is registered using customElements.define('bx-loading', BXLoading).
Requirements for adding framework support to Carbon
For the Carbon Design System to incorporate additional frameworks into core offering, the frameworks must have clear, guaranteed, ongoing resources to maintain and support that option. One-off implementations built for specific products without planned external support cannot become core parts of Carbon.
v11 developer benefits
Carbon v11 offers developers: CSS grid for easier layout implementation with sub-grid support; CSS custom properties for theming (light mode and dark mode); significant reduction in compile times with updated Sass architecture; consistent component API across all components; improved Sass structure for getting started and productive use; and new accessibility component primitives.
v11 customer benefits
Carbon v11 benefits end users through: light and dark mode support; faster feature development time; new components that reduce custom development; accessibility primitives enabling accessible experiences earlier in development; faster load times due to smaller bundle sizes.
Disabled state definition
A disabled state is applied to a component when the user is not allowed to interact with the component due to either permissions, dependencies, or prerequisites. Disabled states completely remove the interactive function of a component.