design-system: Skill for Claude Code

Skill: IDS Token Usage

Purpose

Guide AI agents on correctly using IDS design tokens in React components and CSS. This skill covers import patterns, common mistakes, and practical usage rules for each token category.

When to Use

• Generating React components that need colours, spacing, typography, or border-radius values
• Writing custom CSS or inline styles for IDS-based applications
• Reviewing or fixing design token usage in existing code
• Choosing between component props, CSS variables, and the cssVars JS object
• Answering questions about available token values and naming conventions

Workflow

1. Check if a component prop handles it — Most IDS components accept IressCSSProps (e.g. p, m, gap, bg, color, textStyle). Use props before reaching for tokens directly.
2. Identify the token category — Is it colour, spacing, typography, or radius?
3. Choose the right import — Use cssVars for inline styles, CSS variables for stylesheets. See the import patterns below.
4. Look up the value — See references/token-reference.md for the full list of available tokens if you need to find a specific value.

Quick Start

Installation

Important: IDS v6 is currently in beta. Install with the @beta tag:

npm install @iress-oss/ids-tokens@beta
# If also using IDS React components:
npm install @iress-oss/ids-components@beta

Prerequisites (React only)

If you are using IDS React components, wrap your application in IressProvider and import the CSS variables stylesheet:

Note: IressProvider already includes IressModalProvider, IressSlideoutProvider, IressToasterProvider, IressPopoverProvider, and IressIconProvider — you do not need to add these separately. If using IressShadow, no additional providers are needed as it includes IressProvider internally.

import '@iress-oss/ids-tokens/build/css-vars.css';
import { IressProvider } from '@iress-oss/ids-components';

function App() {
  return <IressProvider>{/* your UI */}</IressProvider>;
}