token-usage

スキル：IDS トークンの使用方法

目的

React コンポーネントと CSS で IDS デザイントークンを正しく使用できるよう、AI エージェントをガイドします。このスキルでは、各トークンカテゴリーのインポートパターン、よくある間違い、実用的な使用ルールを扱います。

使用するタイミング

• 色、余白、タイポグラフィ、角丸の値を必要とする React コンポーネントを生成するとき
• IDS ベースのアプリケーションでカスタム CSS またはインラインスタイルを記述するとき
• 既存のコードでデザイントークンの使用を確認または修正するとき
• コンポーネントのプロパティ、CSS 変数、cssVars JS オブジェクトのいずれを使うか選ぶとき
• 使用可能なトークンの値や命名規則について質問に回答するとき

ワークフロー

1. コンポーネントのプロパティで対応できるか確認します — ほとんどの IDS コンポーネントは IressCSSProps（例：p、m、gap、bg、color、textStyle）を受け付けます。トークンを直接使う前に、プロパティを使用してください。
2. トークンのカテゴリーを特定します — 色、余白、タイポグラフィ、角丸のどれでしょうか？
3. 適切なインポート方法を選びます — インラインスタイルには cssVars、スタイルシートには CSS 変数を使用します。以下のインポートパターンを参照してください。
4. 値を確認します — 特定の値を見つける必要がある場合は、利用可能なトークンの全一覧が記載された references/token-reference.md を参照してください。

クイックスタート

インストール

重要： IDS v6 は現在ベータ版です。@beta タグを付けてインストールしてください。

npm install @iress-oss/ids-tokens@beta
# IDS React コンポーネントも使用する場合：
npm install @iress-oss/ids-components@beta

前提条件（React のみ）

IDS React コンポーネントを使用する場合は、アプリケーションを IressProvider でラップし、CSS 変数のスタイルシートをインポートしてください。

注： IressProvider には IressModalProvider、IressSlideoutProvider、IressToasterProvider、IressPopoverProvider、IressIconProvider がすでに含まれているため、これらを個別に追加する必要はありません。IressShadow を使用する場合も、内部で IressProvider が含まれているため、追加のプロバイダーは必要ありません。

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

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

React 以外での使用： トークンパッケージは React がなくても動作します。CSS スタイルシートをインポートするか、JavaScript または CSS の任意の環境で cssVars／designTokens を直接使用してください。

CSP に関する注記： IressProvider は実行時に fonts.googleapis.com と fonts.gstatic.com からフォントを読み込みます。アプリでコンテンツセキュリティポリシーを適用している場合は、style-src と font-src でこれらのオリジンを許可リストに追加してください。IressShadow を使用していて、CSP によってインラインスタイルがブロックされる場合は、ノンスをサポートするために <meta name="csp-nonce" content="..."> を追加してください。詳細は、node_modules/@iress-oss/ids-components/.ai/guides/get-started-content-security-policy.md の CSP ガイドを参照してください（@iress-oss/ids-components のインストールが必要です）。

CSS 変数スタイルシート（CSS での使用を推奨）

CSS スタイルシートは、トークンを使用する最も簡単な方法です。一度インポートすれば、CSS のどこでも var() 参照を使用できます。

重要： @iress-oss/ids-tokens/build/css-vars.css で定義されている変数名（例：--colour-neutral-10）を使用してください。--iress-* 変数を直接参照 しないでください。これらはテーマファイルによって設定されるものであり、公開トークン API の一部ではありません。

/* Import the stylesheet once in your app root */
@import '@iress-oss/ids-tokens/build/css-vars.css';

/* Use variables anywhere in your CSS */
.card {
  background: var(--colour-neutral-10);
  padding: var(--spacing-4);
  border-radius: var(--radius-3);
  color: var(--colour-neutral-90);
}

cssVars オブジェクト（CSS-in-JS での使用を推奨）

インラインスタイルと CSS-in-JS では、cssVars エクスポートを使用してください。トークン構造を反映し、フォールバックを埋め込んだ var() 文字列を返します。完全な型安全性も備えています。

import { cssVars } from '@iress-oss/ids-tokens';

// Each leaf is a var() string with a fallback value
cssVars.colour.primary.fill; // 'var(--iress-colour-primary-fill, #003271)'
cssVars.spacing[4]; // 'var(--iress-spacing-4, calc(4 * var(--iress-spacing-100, .25rem)))'
cssVars.radius[1]; // 'var(--iress-radius-1, 0.25rem)'
cssVars.typography.heading[1]; // 'var(--iress-typography-heading-1, 500 calc(...) / 1.33 Ubuntu, ...)'

// Use in inline styles
<div
  style={{
    background: cssVars.colour.neutral[20],
    padding: cssVars.spacing[4],
  }}
>
  Themed content
</div>;

JavaScript スキーマ（メタデータ／ツール向け）

トークンのメタデータ（説明、型、拡張）を確認する場合、またはプログラムで反復処理する場合に限り、raw の designTokens スキーマを使用してください。スタイリングには、代わりに cssVars または CSS 変数を使用してください。

import { designTokens } from '@iress-oss/ids-tokens';

// Each token is an IressDesignToken object with $value, $type, $description, etc.
designTokens.colour.primary.fill.$value; // '#003271'
designTokens.spacing[4].$value; // 'calc(4 * {spacing.100 || .25rem})'
designTokens.radius[1].$value; // '0.25rem'
designTokens.typography.heading[1].$value; // { fontFamily, fontSize, fontWeight, lineHeight }

インポートパターン

CSS スタイリング用

/* In your app entry point */
@import '@iress-oss/ids-tokens/build/css-vars.css';

インポートすると、公開トークン変数（例：--colour-*、--spacing-*、--radius-*、--typography-*）をグローバルに使用できます。

CSS-in-JS／インラインスタイル用

import { cssVars } from '@iress-oss/ids-tokens';

// Type-safe var() references with fallbacks — use anywhere you need a style value
cssVars.colour.neutral[10]; // 'var(--iress-colour-neutral-10, #FFFFFF)'
cssVars.spacing[4]; // 'var(--iress-spacing-4, ...)'

トークンのメタデータ／ツール用

import { designTokens } from '@iress-oss/ids-tokens';

// Access raw token objects for metadata inspection
const { colour, spacing, radius, typography } = designTokens;

内部ヘルパー（テーマエディター専用）

注記： これらのヘルパーは、テーマエディター（Styler など）のような内部ツールを対象としています。利用者は代わりに cssVars または CSS 変数を使用してください。

// Convert token schema to a nested object of CSS variable references
import { mapTokensToCssVariables } from '@iress-oss/ids-tokens/mapTokensToCssVariables';

// Resolve `{colour.neutral.10}` token references to CSS vars
import { convertReferencesToVariables } from '@iress-oss/ids-tokens/convertReferencesToVariables';

カテゴリー別の使用ルール

色

色には必ず色トークンを使用してください — hex、rgb、hsl の値をハードコードしないでください。

用途	トークン	例
ページの背景	colour.neutral.10	bg="colour.neutral.10"
控えめな背景	colour.neutral.20	bg="colour.neutral.20"
デフォルトのテキスト	colour.neutral.80	color="colour.neutral.80"
セカンダリテキスト	colour.neutral.70	color="colour.neutral.70"
境界線	colour.neutral.30	コンポーネントのプロパティを使用
プライマリアクション	colour.primary.fill	Button mode="primary" を使用
成功インジケーター	colour.system.success.fill	Alert/Tag の status を使用
危険／エラー	colour.system.danger.fill	Alert/Tag の status を使用

// ✅ Correct
<IressText color="colour.neutral.80">Subtitle</IressText>
<IressStack bg="colour.neutral.20" p="spacing.4">...</IressStack>

// ❌ Wrong — hardcoded colours
<div style={{ color: '#384666' }}>Subtitle</div>
<div style={{ background: '#F5F6F8' }}>...</div>

余白

すべての余白にスペーシングトークンを使用してください — ギャップ、パディング、マージン。

基本単位：4px（0.25rem）。トークン値は基本単位の倍数です。

トークン	エイリアス	値	用途
0	none	0	余白なし
1	xs	4px	狭いインラインの余白
2	sm	8px	デフォルトの要素間の余白
3	—	12px	コンパクトなセクション間の余白
4	md	16px	標準的なセクション間の余白
5	—	20px	中程度のセクション間の余白
6	lg	24px	セクション間の区切り
7	—	28px	大きなセクション間の余白
8	—	32px	大きなグループ間の余白
10	xl	40px	ページレベルの余白

// ✅ Correct — use full token path
<IressStack gap="spacing.4" p="spacing.6">...</IressStack>
<IressInline gap="spacing.2">...</IressInline>

// ✅ Also correct — use token aliases
<IressStack gap="md" p="lg">...</IressStack>
<IressInline gap="sm">...</IressInline>

// ❌ Wrong — arbitrary values
<div style={{ gap: '15px', padding: '25px' }}>...</div>

注記： spacing[9] トークンはありません。有効なスペーシング値は spacing.0 から spacing.10（9を除く）、またはエイリアスの none、xs、sm、md、lg、xl です。

正の余白と負の余白： パディングプロパティ（p、px、py、pb、pl、pr、pt）では正のスペーシングトークンのみ使用できます。マージンプロパティ（m、mx、my、mb、ml、mr、mt）では、重なり合う要素に対して負の値（例：-spacing.2、-sm）も使用できます。

角丸

すべての角丸にラディウストークンを使用してください。

トークン	値	意味上の用途
radius.0	0	角張ったコーナー
radius.1	4px	ボタン、フォーム入力、タグ
radius.2	8px	汎用
radius.3	12px	カード、パネル、レイアウトコンテナー
radius.4	16px	ピル、バッジ

// ✅ Correct — IDS components already have correct radius
<IressButton>Submit</IressButton>  // radius.1 built in
<IressCard>...</IressCard>         // radius.3 built in

// Manual radius only when building custom layout
<IressStack borderRadius="radius.3">Custom panel</IressStack>

タイポグラフィ

すべてのテキスト描画には IressText を使用し、生の見出しや段落は使用しないでください。

要素	textStyle の値	フォント	サイズ	太さ
h1	typography.heading.1	Ubuntu	1.5rem (24px)	500
h2	typography.heading.2	Ubuntu	1.25rem (20px)	500
h3	typography.heading.3	Ubuntu	1.125rem (18px)	500
h4	typography.heading.4	Ubuntu	1rem (16px)	500
h5	typography.heading.5	Ubuntu	1rem (16px)	400
本文（デフォルト）	typography.body.md	Inter	0.875rem (14px)	400
本文の強調	typography.body.md.strong	Inter	0.875rem (14px)	600
小さいテキスト	typography.body.sm	Inter	0.75rem (12px)	400
小さいテキストの強調	typography.body.sm.strong	Inter	0.75rem (12px)	600
コード	typography.code	Space	1rem (16px)	400

すべての textStyle の値： typography.heading.1 – .5、typography.body.sm（＋ .regular、.medium、.strong、.em）、typography.body.md（＋ .regular、.medium、.strong、.em）、typography.code、inherit。

// ✅ Correct
<IressText element="h1">Page Title</IressText>
<IressText>Body paragraph text</IressText>
<IressText textStyle="typography.body.sm.strong">Small bold label</IressText>

// ❌ Wrong — raw HTML elements lose IDS typography
<h1>Page Title</h1>
<p style={{ fontFamily: 'Inter', fontSize: '14px' }}>Text</p>

カスタムスタイルでの CSS 変数

IDS コンポーネントの props で提供される機能を超えてカスタムスタイルを設定する場合は、この方法を推奨します。

Panda CSS を使用していますか？ プロジェクトで Panda CSS を使用している場合は、CSS 変数を手動で参照する代わりに、@iress-oss/ids-theme-preset パッケージを使用してください。このパッケージは、IDS トークンシステム全体を備えた Panda CSS プリセットを提供し、Panda の css() 関数、ユーティリティ、レシピを使って、型安全にトークンを使用できます。設定方法については、references/theme-preset.md を参照してください。

CSS / SCSS での使用

.custom-card {
  /* Colour tokens */
  background: var(--colour-neutral-10);
  border: 1px solid var(--colour-neutral-30);
  color: var(--colour-neutral-90);

  /* Spacing tokens */
  padding: var(--spacing-4);
  gap: var(--spacing-2);

  /* Radius tokens */
  border-radius: var(--radius-3);

  /* Typography tokens (composite shorthand) */
  font: var(--typography-body-md-regular);
}

CSS-in-JS / インラインスタイルでの使用

import { cssVars } from '@iress-oss/ids-tokens';

// cssVars gives you the same var() references, but type-safe in JS
<div
  style={{
    background: cssVars.colour.neutral[10],
    border: `1px solid ${cssVars.colour.neutral[30]}`,
    color: cssVars.colour.neutral[80],
    padding: cssVars.spacing[4],
    gap: cssVars.spacing[2],
    borderRadius: cssVars.radius[3],
  }}
>
  Custom card
</div>;

CSS 変数の命名規則

tokens/build/css-vars.css の変数は、次のパターンに従います。

--{category}-{path}

例：

• --colour-primary-fill
• --spacing-4
• --radius-1
• --typography-heading-1（省略形）
• --typography-heading-_1-fontSize（展開形。トークン名の前にアンダースコアが付きます）

注： テーマファイルでは、--iress-{category}-{path} というオーバーライド変数を定義しており、css-vars.css の公開変数内でフォールバックのデフォルト値として参照しています。独自の CSS では、--{category}-{path} の公開変数を使用してください。--iress-* のテーマオーバーライドを直接使用しないでください。

よくある間違い

1. トークンではなく値をハードコードする

// ❌ Wrong
<div style={{ background: '#F5F6F8', padding: '16px', borderRadius: '12px' }}>

// ✅ Correct
<IressStack bg="colour.neutral.20" p="spacing.4" borderRadius="radius.3">

2. 生の HTML 要素を使用する

// ❌ Wrong — loses IDS typography and theming
<h2>Section Title</h2>
<p>Body text</p>

// ✅ Correct — uses IDS tokens automatically
<IressText element="h2">Section Title</IressText>
<IressText>Body text</IressText>

3. コンポーネントのスタイルを再作成する

// ❌ Wrong — manually styling a button
<button style={{
  background: '#003271',
  color: '#FFFFFF',
  borderRadius: '4px',
  padding: '8px 16px'
}}>Submit</button>

// ✅ Correct — IDS handles all styling via mode
<IressButton mode="primary">Submit</IressButton>

4. 誤った色のセマンティックを使用する

// ❌ Wrong — using primary fill for background
<IressStack bg="colour.primary.fill">Content</IressStack>

// ✅ Correct — use surface variants for backgrounds
<IressStack bg="colour.primary.surface">Content</IressStack>

5. 存在しないトークン値を使用する

// ❌ Wrong — spacing 9 doesn't exist
<IressStack gap="spacing.9">...</IressStack>

// ✅ Correct — use 8 or 10
<IressStack gap="spacing.8">...</IressStack>

レスポンシブパターン

レイアウトコンポーネントでは、間隔 props にレスポンシブオブジェクトを指定できます。

// Responsive gap: 2 on mobile, 4 on tablet, 6 on desktop
<IressStack gap={{ base: 'spacing.2', md: 'spacing.4', lg: 'spacing.6' }}>
  ...
</IressStack>

// Or use aliases
<IressStack gap={{ base: 'sm', md: 'md', lg: 'lg' }}>
  ...
</IressStack>

// Hide on small screens
<IressStack hideBelow="md">Desktop only</IressStack>

決定表：コンポーネントの Props、CSS 変数、cssVars

状況	使用するもの
IDS レイアウトコンポーネントの間隔	Props：gap、p、m
IDS コンポーネントの色	Props：bg、color
カスタム CSS / SCSS	CSS 変数（var(--colour-*)、var(--spacing-*) など）
インラインスタイル / CSS-in-JS	cssVars オブジェクト（cssVars.colour.neutral[10]）
Panda CSS を使ったカスタム CSS	@iress-oss/ids-theme-preset プリセット
テーマ設定 / オーバーライド	カスタムプロパティの CSS 変数
内部テーマエディター	mapTokensToCssVariables() ヘルパー

一般的なルール： 利用可能な場合は、コンポーネントの Props を優先してください。カスタムスタイルには、スタイルシート内の CSS 変数、または JavaScript 内の cssVars を使用してください。mapTokensToCssVariables / convertReferencesToVariables は、テーマエディターなどの内部ツールでのみ使用してください。

避けるべきよくある間違い

よくあるアンチパターン（無効なボタン、冗長な textStyle、レガシーなスロット属性、生の HTML、ハードコードされた値）の全リストは、node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md にある「よくある間違い」ガイドを参照してください（@iress-oss/ids-components のインストールが必要です）。

トークンの完全なリファレンス

CSS 変数名とデフォルト値を含む、利用可能なすべての色、間隔、角丸、タイポグラフィのトークンについては、references/token-reference.md を参照してください。

テーマ設定

CSS 変数によるテーマのトークンのオーバーライド、スコープを限定したテーマ設定、AI エージェント向けのガイダンスについては、references/theming.md を参照してください。

関連ドキュメント

スタイル設定 Props のガイド、パッケージのリファレンス、コンポーネント単位のドキュメントへのリンクについては、references/cross-references.md を参照してください。これらの参照には @iress-oss/ids-components のインストールが必要です。