メインコンテンツまでスキップ

コンポーネントスキン

コンポーネントスキンレベルは組み込みコンポーネントを再スタイリングします。特定のスタイリングスタックと安定したフックコントラクトの上に構築されます。

スタイリングスタック​

組み込み UI は 4 つのテクノロジーを一緒に使用します:

  • CSS Modules — コンポーネントスコープのスタイル用。ハッシュ化されたクラス名は明示的に公開コントラクトではありません。
  • CSS カスタムプロパティ — セマンティックトークン（--st-*）用。
  • カスケードレイヤー — 情報源の順序付け用。
  • コンテナクエリ — コンポーネント自身のコンテナに適応するレイアウト用。サイズは rem で表されます。

テーマは生成されたクラス名ではなく、フック属性をターゲットにします。

カスケードレイヤーの順序​

すべてのスタイルは固定のカスケードレイヤー順序で存在します:

@layer reset, tokens, base, components, plugin-base, theme, user;

後のレイヤーが先のレイヤーより勝つため、優先順位は次のとおりです:

  1. reset — ベースリセット。
  2. tokens — トークン定義。
  3. base — 要素レベルのデフォルト。
  4. components — 組み込みコンポーネントスタイル。
  5. plugin-base — プラグイン提供のベーススタイル用レイヤー。
  6. theme — アクティブなテーマのスキン。
  7. user — ユーザー自身のオーバーライド。最後に読み込まれます。

ユーザーオーバーライドスタイルシートは常に最後に読み込まれるため、壊れたテーマや独断的なテーマがユーザーのオーバーライドを妨げることは決してありません。!important の観点では: この構造は、ユーザー向けの a11y モードに属するアクセシビリティ設定レイヤーを除き、テーマ CSS で禁止されています。

フックコントラクト​

テーマは、ホストが公開し、SDK の他の部分と同様にバージョン管理される 4 つの属性を通じてコンポーネントをスタイリングします:

<div
  data-component="chat-message"
  data-part="container"
  data-role="assistant"
  data-state="streaming"
></div>
  • data-component — コンポーネントの種類。
  • data-part — コンポーネント内の構造的な部分。
  • data-role — メッセージロールなどのセマンティックロール。
  • data-state — open、closed、streaming などの状態。

テーマのスキン CSS は次のようになります:

@layer theme {
  [data-component='button'][data-variant='primary'] > [data-part='icon'] {
    color: var(--st-color-accent-text);
  }

  [data-component='action-bar'] [data-part='group'][data-role='secondary'] {
    color: var(--st-color-text-secondary);
  }
}

@neotavern/theme-sdk パッケージはこれらの属性オブジェクトを構築するための dataHook ヘルパーをエクスポートするため、コンポーネント作者とテーマ作者は同じ名前で合意できます。

コントラクトではないもの​

  • 生成された CSS モジュールのクラス名 — ハッシュ化され、不安定で、SDK の一部ではありません。それらをターゲットにするテーマは次のビルドで壊れます。
  • 内部 React 階層 — テーマは文書化されたフックを超えて、コンポーネント内部や DOM 順序に依存してはなりません。
  • 数値のレイアウト値 — 座標、グリッドスキーム、ブレークポイントはトークンコントラクトを通じてスタイリングできません。ビューポートのブレークポイントはレジストリにあり、コンテナクエリは rem で書かれなければなりません。

禁止された CSS​

テーマスタイルシートは読み込み前にスキャンされます。禁止構造はインストール時と検証時に拒否されます:

  • @import
  • javascript: URL と expression()。
  • -moz-binding と behavior:。
  • リモートまたはプロトコル相対 URL（url(http:、url(https:、url(//）。
  • data:text/html。
  • !important（a11y 設定レイヤーを除く）。

これによりテーマ CSS は純粋で、ローカルで、安全に保たれます。スキンが参照すべきトークンはデザイントークン を、スキンが再スタイリングできる名前付き領域はシェルコントラクト を参照してください。