Choosing Between Standard and Custom Design Tokens in Carbon Design System

Problem: Choosing Token Strategy in Carbon

When building a web app with Carbon Design System, you must decide whether to use the pre‑defined Standard tokens or create Custom tokens to match brand colors or spacing. The wrong choice leads to either a generic UI or fragile upgrades.

Takeaway: Use Standard tokens for the bulk of the interface; reserve Custom tokens only for high‑level brand values that have been accessibility‑tested.

Decision Constraints

• Upgrade frequency – how often you plan to move to a newer Carbon release.
• Brand requirements – whether corporate colors differ from the Carbon palette.
• Accessibility – need to meet WCAG contrast ratios for text and UI elements.
• Maintenance capacity – ability to audit token overrides after each library update.

Comparison of Options

Criteria	Standard Tokens	Custom Tokens
Maintenance	Low; values update automatically with Carbon releases.	High; requires manual review after each upgrade.
Consistency	Guaranteed across all Carbon components.	Risk of visual fragmentation if overrides diverge.
Accessibility	Pre‑validated for WCAG AA/AAA contrast.	Must be verified manually for each overridden color.
Implementation	Consume tokens directly from @carbon/styles.	Override Sass variables or set CSS custom properties before importing Carbon.

Trade‑offs

Standard tokens are version‑locked to the Carbon specification, so any spacing scale or color adjustment made by the Carbon team flows into your app without extra work. This reduces the chance of breaking layout in components like DataTable or Modal that rely on proportional spacing.

Custom tokens become necessary when a legal brand guideline mandates a hue that falls outside the Carbon palette, or when a specific contrast ratio cannot be achieved with the default colors. Overriding a token such as $interactive-01 changes the background of buttons, links, and form inputs everywhere it is used. If the new hue lacks sufficient light‑dark variance, hover and focus states may become indistinguishable, creating a usability issue.

Implementation: Overriding a Brand Color

Where to edit: Your main Sass entry point, e.g., styles.scss.

Permissions: Write access to the source repository and a Sass compiler configured for the project (Dart Sass or Node‑sass).

1. Define the brand color and test its contrast against the background.
2. Override the Carbon token before importing the library.
3. Import Carbon styles after the override.

// 1. Brand color (example: a corporate blue)
// Verify contrast with $background (usually #ffffff) using a contrast checker.
$brand-primary: #005eb8;

// 2. Override the interactive token used for buttons and links
$interactive-01: $brand-primary;

// 3. Import Carbon after the override
@use '@carbon/react';

Risk: If the custom color does not provide enough contrast variation, interactive states like :hover or :focus may lose visual distinction, leading to accessibility failures.

Validation

• CSS inspection: Open browser DevTools (F12), select a primary button, and confirm the computed background-color matches $brand-primary rather than the default Carbon blue.
• Contrast check: Use a tool such as Axe DevTools or the WebAIM contrast checker. Ensure the ratio between the overridden $interactive-01 and the background ($background) is at least 4.5:1 for normal text.
• Visual regression: Compare the rendered component against the Carbon Figma specification to verify that spacing or layout has not shifted unexpectedly.

Rollback Procedure

If validation shows contrast problems or visual regressions, remove the override lines from your Sass entry point and re‑compile the CSS. This instantly restores the Standard token values.