Add a Carbon Design System Button to React: Incremental Adoption Guide

Problem: You need a consistent, accessible button without redesigning your entire UI

If your React app requires a reliable button component but a full design system migration is too risky, Carbon's Button from @carbon/react can replace one custom button safely.

Prerequisites

• React project using a bundler that supports CSS/SCSS imports (Webpack, Vite, etc.)
• Node.js 14+ and npm/yarn available
• Peer-dependency awareness: Carbon requires react and react-dom as peer dependencies

Install Carbon React Package

Run in your project root. Pin to a major version to avoid breaking changes:

npm install @carbon/react@^10.0.0 --save
# or with yarn
yarn add @carbon/react@^10.0.0

Expected check: No peer-dependency warnings. If warnings appear, align React versions first.

Import Carbon Styles

Carbon components require their stylesheet. Add one of these to your entry file (e.g., src/index.js or src/App.jsx):

// For modern builds with CSS modules or PostCSS
import '@carbon/themes/css/g10.css';

// Or use SCSS for theme customization
@import '@carbon/themes/scss/g10';

Risk: Omitting this results in unstyled components with raw HTML.

Replace Your Button with Carbon Button

Find the custom button file and replace it:

// Before: custom button
function MyButton({onClick, children}) {
  return (
    <button className="btn" onClick={onClick}>
      {children}
    </button>
  );
}

// After: Carbon Button
import { Button } from '@carbon/react';

function MyButton({onClick, children}) {
  return (
    <Button onClick={onClick}>
      {children}
    </Button>
  );
}

Expected Checks

1. Visual: Button renders with Carbon styling (rounded corners, primary/secondary variants via theme prop)
2. Accessibility: Focus ring visible on Tab key; aria-label works if needed
3. DOM inspection: Element contains bx--btn class name

Verify Build and Tests

Run your build and test suite:

npm run build
npm test -- --testPathPattern=Button

If SSR is used, ensure styles are injected on server to prevent flash of unstyled content (FOUC).

Recovery Options (If Issues Occur)

1. Uninstall Carbon: npm uninstall @carbon/react
2. Remove style imports from entry file
3. Restore original button implementation from version control

Limitations and Next Steps

This guide assumes React 17+; older versions may need react-dom/client adjustments. Carbon's Button supports disabled, icon, and link props—refer to the @carbon/react docs for full API. For incremental adoption, consider adding Carbon's Toggle or Dropdown next, one component at a time.