Headless Component Design

Headless Component Design

DADS準拠のヘッドレスWebComponentライブラリ設計ガイドライン。

Quick Reference

Core Principles

1. DADS First: デジタル庁公式をベースライン
2. Override Points: CSS変数（--dads-*）とpart属性で拡張可能
3. Accessible by Default: WCAG 2.2 AA準拠
4. Token-Based: 3層トークン構造

3層トークン構造

Primitive Tokens (DADS公式)
    ↓
Semantic Tokens (意味層)
    ↓
Local Tokens (--dads-* コンポーネントAPI)
    ↓
CSS Properties

角丸（DADS公式準拠）

重要: フォーム要素は 0.5rem (8px) を使用。0.25rem (4px) は間違い。

フォーカススタイル（DADS公式準拠）

/* 公式仕様 - border-radiusは変更しない */
outline: .25rem solid var(--dads-focus-outline-color);
outline-offset: .125rem;
box-shadow: 0 0 0 .125rem var(--dads-focus-ring-color);

Decision Tree

Core Workflow

新規コンポーネント設計

1. トークン設計

   • プリミティブ → セマンティック → ローカルの階層を定義
   • --dads-{component}-{property} 形式でAPI定義

2. フォーカススタイル適用

   • applyDADSFocusStyles() ミックスインを使用
   • border-radiusはフォーカス時に変更しない（公式準拠）

3. オーバーライドポイント設計

   • CSS変数で外部カスタマイズ可能に
   • ::part() で要素レベルのスタイリング可能に

4. アクセシビリティ確保

   • WCAG 2.2 AA準拠
   • キーボード操作対応
   • スクリーンリーダー対応

コンポーネントレビュー時チェックリスト

• 3層トークン構造に従っているか
• --dads-* プレフィックスでAPI定義されているか
• 角丸が公式準拠か（フォーム要素は8px/0.5rem）
• フォーカススタイルが公式準拠か（border-radius変更なし）
• オーバーライドポイントが明確か
• アクセシビリティ要件を満たしているか

Token API Pattern

正しいパターン

:host {
  /* セマンティック層 */
  --button-primary-bg: var(--color-primitive-blue-900);

  /* ローカル層（API） */
  --dads-button-background: var(--button-primary-bg);
}

/* プロパティ定義（一度だけ） */
[part="base"] {
  background-color: var(--dads-button-background);
}

/* 状態変化は変数再代入のみ */
:host(:hover) {
  --dads-button-background: var(--button-primary-bg-hover);
}

フォーカストークン

:host {
  /* セマンティック層 */
  --focus-outline-color: var(--color-neutral-black);
  --focus-ring-color: var(--color-primitive-yellow-300);

  /* ローカル層（API） */
  --dads-focus-outline-color: var(--focus-outline-color);
  --dads-focus-ring-color: var(--focus-ring-color);
}

Override Examples

CSS変数でカスタマイズ

<style>
  dads-button {
    --dads-button-background: var(--my-brand-color);
    --dads-focus-ring-color: var(--my-focus-color);
  }
</style>

::part()でスタイリング

<style>
  dads-textarea::part(textarea) {
    font-family: monospace;
  }
</style>

Sources

• デジタル庁デザインシステム
• GitHub: digital-go-jp/design-system-example-components
• Radix UI
• shadcn/ui

Related Docs

Do / Don't

Do

• Follow DADS baseline first — Start with DADS component specifications before adding customization.
• Expose override points via --dads-* CSS variables — Allow theming through CSS custom properties with the --dads- prefix.

  [part="base"] { background: var(--dads-button-background); }
  

• Use 3-layer token structure — Global → Component → Local token hierarchy for scalable theming.
• Implement WCAG 2.2 AA by default — All components must meet accessibility standards without additional configuration.
• Use ::part() for external customization — Expose specific elements for styling, not the entire Shadow DOM.

Don't

• Skip DADS compatibility check — Always verify component behavior against DADS specifications.
• Hardcode styles without token indirection — Every visual property should reference a token variable.

  /* NG */ background: #1a73e8;
  /* OK */ background: var(--dads-button-background, var(--color-primary));
  

• Mix token layers — Don't use global tokens directly in component styles; use component-level tokens that reference globals.
• Ignore focus style specifications — Focus indicators must follow DADS focus ring guidelines.
• Expose internal implementation details — Keep Shadow DOM internals private; only expose intentional part attributes.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.