Understanding Carbon

Understanding-Carbon is a reusable agent skill for researching, auditing, designing, and implementing with IBM's Carbon Design System from public, traceable sources.

It was built to answer a practical problem: Carbon's public code and documentation are extensive, while the hosted Carbon MCP is authenticated and its indexed datasets are governed separately. This skill keeps the useful discipline—source discovery, framework separation, exact asset lookup, accessibility, and validation—without requiring an IBMid or private service.

What is included

• A complete research report covering Carbon's foundations, implementation model, local source inventory, MCP boundary, and licensing posture.
• A portable understanding-carbon skill for Codex and other Agent Skills-compatible tools.
• Dependency-free tools to inventory local Carbon clones, find exact public assets, and flag common implementation drift.
• A provenance-first policy that permits public Apache-2.0 Carbon code and assets, handles IBM Plex under OFL-1.1, and refuses untraceable illustrations or private datasets.

No IBM artwork, font files, package source, MCP dataset, or credentials are bundled.

Install the skill

Copy the directory at skill/understanding-carbon into the skill location used by your agent. For Codex, a personal installation commonly lives under:

~/.codex/skills/understanding-carbon

For a repository-scoped installation, use the skill directory supported by your coding agent.

Use it

Example requests:

• “Audit this React interface against current Carbon typography, grid, tokens, and accessibility guidance.”
• “Find a licensed Carbon icon and pictogram for this workflow. Verify the exact exports.”
• “Implement this flow with Carbon Web Components without mixing React APIs.”
• “Review this Carbon migration, including theme layers, telemetry, bundle cost, and reduced motion.”
• “Research Carbon MCP, but continue with public sources if authenticated access is unavailable.”

Tools

Run the tools with Node.js 18 or newer:

node skill/understanding-carbon/scripts/carbon-inventory.mjs \
  --carbon-repo /path/to/carbon \
  --icons-motion-repo /path/to/icons-motion

node skill/understanding-carbon/scripts/find-carbon-asset.mjs search \
  --kind icon \
  --carbon-repo /path/to/carbon

node skill/understanding-carbon/scripts/audit-carbon-project.mjs /path/to/project

The tools emit JSON so they can be used by people, scripts, and agents.

Research report

Read The Carbon Design System: public-source research and implementation report.

Independence and trademarks

This project is independent, is not an IBM product, and is not endorsed by IBM. “IBM,” “Carbon,” and “IBM Plex” may be trademarks of their respective owners. They are used here only to identify the systems and sources being discussed.

License

The original material in this repository is available under the MIT License. Third-party materials remain under their own licenses; see THIRD_PARTY_NOTICES.md.