carbide 0.5.0

An unofficial Flutter port of the IBM Carbon Design System, built strictly on Flutter's base widgets (no Material, no Cupertino).

Carbide

An unofficial Flutter port of the IBM Carbon Design System.

Carbide brings the IBM Carbon Design System to Flutter, built on Flutter's base widgets and SDK rendering libraries — no Material, no Cupertino in library code. Tokens and component behavior are ported from Carbon's pinned reference sources.

▶ Explore the live gallery — cataloged families and compositions in four themes, with live controls and compiled clipboard examples.

The checked catalog contains 67 routes. The public barrel exposes 279 declarations, including 170 widget classes across 63 source families. These counts include composition and inherited-scope types, not separate independent controls. The API-to-gallery policy records live references and reasoned composition/nonvisual exemptions.

Install

flutter pub add carbide

Carbide bundles the IBM Plex fonts, so no extra font setup is required.

Quick start

Carbide has no app-level widget of its own: drop a CarbonTheme above your widget tree and build with Carbon* components. Components read the active theme's tokens through CarbonTheme.of(context).

import 'package:carbide/carbide.dart';
import 'package:flutter/widgets.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return CarbonTheme(
      data: CarbonThemeData.white,
      child: WidgetsApp(
        color: CarbonColors.blue60,
        builder: (context, _) => const Home(),
      ),
    );
  }
}

class Home extends StatelessWidget {
  const Home({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = CarbonTheme.of(context);
    return ColoredBox(
      color: theme.background,
      child: Center(
        child: CarbonButton(
          label: 'Submit',
          onPressed: () {},
        ),
      ),
    );
  }
}

You can equally place CarbonTheme inside an existing MaterialApp or WidgetsApp — it is just an InheritedWidget.

Theming

Carbon ships four themes — White, Gray 10 (light) and Gray 90, Gray 100 (dark) — each mapping the same set of semantic tokens onto the palette. Select one with a named constructor on CarbonThemeData:

CarbonTheme(data: CarbonThemeData.white,   child: ...);
CarbonTheme(data: CarbonThemeData.gray10,  child: ...);
CarbonTheme(data: CarbonThemeData.gray90,  child: ...);
CarbonTheme(data: CarbonThemeData.gray100, child: ...);

Use AnimatedCarbonTheme to crossfade tokens when the theme changes, exactly like Flutter's implicit animations:

AnimatedCarbonTheme(
  data: isDark ? CarbonThemeData.gray100 : CarbonThemeData.white,
  duration: const Duration(milliseconds: 150),
  child: ...,
);

CarbonLayer implements Carbon's contextual layering model: wrapping a subtree steps its layer, field, and border tokens up one level so nested surfaces (cards on cards, modals over content) stay distinguishable.

CarbonLayer(
  child: MyCard(), // its descendants now read the next layer's tokens
);

See the theming & layers guide for the full token set and the layering rules.

Component catalog

The checked Carbon parity matrix distinguishes present, consolidated, partial, deferred and platform-specific APIs, with a fidelity tier and explicit boundaries. React Fluid* names map to the existing picker/field APIs and CarbonFluidForm; React providers and CSS subgrid are separate platform/architecture decisions. The matrix does not promise full variant parity.

Gallery category	Pages	Public widget declarations mapped
Foundations	Color tokens, Typography, Fluid typography, Spacing, Icons, Pictograms, Motion	5
Foundational	Button, Copy button, Code snippet, Icon button, Indicators, Aspect ratio, Grid, Skeletons, Tag, Link, Tile, Loading, Progress bar, List, Stack, Heading	61
Forms	Text input, Text area, Number input, Select, Search, Checkbox, Radio button, Toggle, Slider	13
Composite	AI label, Chat button, Contained list, Context menu, Pagination nav, Dropdown, Combo box, Multi-select, Tooltip, Toggletip, Overflow menu, Tabs, Accordion, Content switcher, Breadcrumb, Pagination, Modal, Dialog, Notification, Progress indicator, Structured list	42
Complex & data	Data table, Date picker, Time picker, File uploader, Tree view, Page header	12
Compositions	Form, Button set, Menu, Popover, Table toolbar, UI shell, Layers and breakpoints, Fluid pickers	41

A widget can map to several categories; these per-category counts are not additive. Mappings include composed variants rather than implying a dedicated page for each declaration. Component pages provide clipboard copy/expand controls and source-derived functional examples; CI compiles their actual displayed code and reviewed Button configurations.

Accessibility & testing

The checked platform support matrix distinguishes platform targets, PR gates, scheduled host/browser canaries and native-device evidence, including fonts, golden authority, input, target sizes, contrast and localization boundaries.

See the semantics policy for static tags, nested lists, code snippets and application-supplied context.

• Accessible by construction. Components expose Carbon's semantics — roles, labels, focus order, and a custom-painted focus ring — and target WCAG AA contrast.
• Platform preferences. Decorative motion follows reduced motion, and increased contrast strengthens boundaries, focus indicators and inactive labels centrally.
• Checked contracts. State, focus, semantics, lifetime and scaling tests accompany component changes. Public API documentation, inventories and generated artifacts are checked in CI.

33 curated default stories compare selected families with committed upstream Carbon Storybook images. Their 24×24 luminance-grid scores, control dimensions, token colors and state contracts detect reviewed drift; they do not establish pixel identity or all-variant coverage. Other family specimens use Linux golden regression baselines and behavior/accessibility tests. The parity matrix records these distinct tiers and implementation boundaries.

Principles

1. No Material or Cupertino. No package:flutter/material.dart or package:flutter/cupertino.dart in lib/. Theming, state, and styling are built from scratch on the widgets layer.
2. Token-driven. Components consume design tokens (color, type, layout, motion) resolved per theme — White, Gray 10, Gray 90, Gray 100 — exactly as Carbon defines them.
3. Tested to a high bar. See above.
4. Strict Dart. The analyzer is configured to fail on a large set of lints (see analysis_options.yaml). No shortcuts.

Documentation

• 0.5.0 adoption and migration — prepared changes from the published 0.4.2 API, ownership, defaults and opt-in features.

• Getting started

• Theming & layers

• Architecture

• Patterns: Forms · Page headers · Progress indicators · Loading · Notifications · Status indicators

• Contributing

Licensing

Carbide is licensed under the Apache License, Version 2.0 — the same license as the IBM Carbon Design System. You may use it freely in open-source and proprietary applications under those terms.

Design tokens are derived from Carbon and the project bundles the SIL OFL 1.1 licensed IBM Plex fonts; see NOTICE for attribution.

Trademark

Carbide is not affiliated with, endorsed by, or sponsored by IBM. "IBM", "Carbon", and "IBM Plex" are trademarks of International Business Machines Corporation, used here only to identify the upstream design system.