ub-css

UB CSS

概要

予測可能なカスケード制御、トークン主導のスタイリング、プログレッシブエンハンスメントによって、最新の CSS プラットフォーム機能を活用します。デザイントークンをシステムの契約として扱い、セレクターと詳細度を保守しやすい状態に保ち、従来の Sass 時代の回避策よりネイティブ CSS 機能を優先します。

必要に応じてリファレンスを読み込む

• ルーティングのガイダンスやスキルをまたぐ記述規約を調整する場合は、../ub-authoring/references/authoring-conventions.md を読みます。
• すぐに使えるパターンやフレームワークとの連携（Vue/Nuxt/Quasar/Tailwind）については、references/modern-css-source.md を読みます。
• フォールバック方針や機能の有効化条件を決める場合は、references/browser-support-baseline.md を読みます。

使用しない場合

• Tailwind のユーティリティワークフロー、Tailwind のセットアップ、または Tailwind の移行が主な変更対象の場合は、このスキルを使用しないでください。CSS アーキテクチャも主要な関心事であるかどうかに応じて、ub-tailwind を併用するか、そちらに委ねてください。
• 主な問題が Nuxt のランタイム動作、アプリ構造、または Nitro/サーバーに関する場合は、このスキルを使用しないでください。その場合は ub-nuxt に委ねてください。
• CSS よりもコンポーネントアーキテクチャが重視される一般的な Vue コンポーネントのロジックには、このスキルを使用しないでください。

基本的なワークフロー

1. トークンの信頼できる唯一の情報源を確認します（DTCG JSON または既存のトークンレジストリ）。
2. トークンをランタイム CSS カスタムプロパティとセマンティックエイリアスにマッピングします。
3. @layer でカスケード順序を定義し、ベンダー CSS をベンダーレイヤーに分離します。
4. ネイティブのネスト、最新のセレクター、コンテナクエリを使ってコンポーネントのスタイルを実装します。
5. 流動的なサイズ指定、論理プロパティ、最新の色指定・テーマ設定プリミティブを追加します。
6. 一部の環境でしかサポートされない機能は、@supports と明示的なフォールバック動作で制御します。
7. アクセシビリティ、動きの設定、パフォーマンスを考慮した CSS 機能を確認します。

最新の CSS のルール

1. デザイントークンを信頼できる唯一の情報源として使う（DTCG 優先）

• 正式なトークンデータ（$value、$type、$description、エイリアス参照）には、DTCG トークン形式を優先します。
• 正式なトークンを、グローバルスコープとセマンティックスコープの CSS カスタムプロパティにマッピングします。
• セマンティックトークン名は安定させ、その背後では値を変更できるようにします。
• 意図的な一時的な値であり、文書化されている場合を除き、コンポーネント内での値のハードコードは避けます。

{
  "color": {
    "brand": {
      "primary": { "$type": "color", "$value": "oklch(62% 0.2 256)" }
    },
    "surface": {
      "default": { "$type": "color", "$value": "#ffffff" }
    }
  }
}

:root {
    --color-brand-primary   : oklch(62% 0.2 256);
    --color-surface-default : #ffffff;
    --space-4               : 1rem;
    --radius-md             : 0.5rem;
}

2. トークンをフレームワークの CSS パイプラインに連携する

• Vue/Nuxt/Quasar：SFC のスタイルブロックで CSS 変数を直接使用します。v-bind() はコンポーネントに反応する値にのみ使います。
• Tailwind（最新の安定版）：トークンを @theme に置き、ユーティリティと生の CSS が同じ値を参照できるよう、CSS 変数と命名を揃えます。
• トークンマッピングを決定論的に保ち、デザイン、アプリの CSS、ユーティリティクラスを同期させます。

@theme {
    --color-brand-primary : oklch(62% 0.2 256);
    --spacing-4           : 1rem;
    --radius-md           : 0.5rem;
}

3. @layer でカスケードを予測可能な形で制御する

• グローバルなレイヤー順序は一度だけ宣言します。
• サードパーティの CSS は専用のベンダーレイヤーにインポートします。
• 詳細度の過剰な引き上げを避けるためにレイヤーを使います。

@layer reset, vendor, tokens, base, components, utilities, overrides;
@import url("vendor.css") layer(vendor);

4. ネイティブのネストを使い、深くしすぎない

• 状態セレクター、ローカルな子孫要素、同じ場所に配置するクエリには、ネイティブのネストを使います。
• ネストの深さは <= 3 レベルに保ちます。
• DOM 構造に強く依存する深いセレクターは避けます。

5. コンポーネントのレスポンシブ対応にはコンテナクエリを使う

• コンポーネントの境界で container: <name> / inline-size（または container-type と container-name）を設定します。
• コンポーネント内部にはコンテナクエリを優先し、ビューポートのメディアクエリはページシェルのレイアウトに使います。
• サイズをコンテナの幅や高さに連動させる場合は、コンテナクエリ単位（cqw、cqh、cqi、cqmin、cqmax）を使います。

6. 最新のセレクターを意図的に使う

• マークアップや JS を簡潔にできる場合は、親要素や状態に応じたスタイル設定に :has() を使います。
• 通常の詳細度でセレクターのバリエーションをまとめるには、:is() を使います。
• 詳細度ゼロのデフォルトには、:where() を使います。
• :focus-visible を使って、キーボード操作時にアクセス可能なフォーカス状態を必ず含めます。

7. 最新のレイアウト、サイズ指定、国際化のプリミティブを優先する

• マージンによる間隔調整のハックではなく、gap を使った Grid／Flex を使用します。
• 流動的なサイズ指定には clamp()、min()、max()、calc() を使用します。
• 物理的な左右のプロパティより、論理プロパティ（padding-inline、border-inline-start、inset-block）を優先します。
• padding-box の比率調整ハックではなく、aspect-ratio を使用します。

8. 最新の色指定とテーマ設定のプリミティブを使用する

• トークン値には、知覚的な色空間（oklch）を優先します。
• パレットを手作業で複製するのではなく、color-mix() でバリエーションを導出します。
• 2つのテーマに対応する必要がある場合は、color-scheme と light-dark() を使用します。
• accent-color は機能強化として扱い、正確なスタイル指定に不可欠なものとしては扱いません。

9. モーション、インタラクション、パフォーマンスを意図的に扱う

• ユーザー設定（prefers-reduced-motion、必要に応じてコントラストモードや強制カラーモード）を尊重します。
• 機能強化のパターンとして、@starting-style、transition-behavior: allow-discrete、ポップオーバーフックを使用します。
• 長いリストや画面外の負荷が大きいコンテンツには、content-visibility とコンテインメントを使用します。
• スクロールバーの表示時に発生するレイアウトシフトを軽減するには、scrollbar-gutter: stable を使用します。

プログレッシブエンハンスメントポリシー（段階的なモダン優先）

• 安全なデフォルト：幅広くサポートされている最新機能をデフォルトで使用します。
• 機能強化段階：@supports によるガードと、許容できるフォールバック動作を必須とします。
• 限定的／実験的段階：明確な理由があり、簡単に取り消せる場合に限り使用します。

ドキュメント、構成、フォーマット

構成

• コードベースの規模に応じて、役割ごとにスタイルを分割します。
  • styles/tokens.css
  • styles/base.css
  • styles/components/*.css
  • styles/utilities.css
• 実用上可能な場合は、コンポーネントのスタイルをそのコンポーネントの近くに配置します。
• グローバルトークンの定義を一元化し、差異の拡大を防ぎます。

ドキュメント

• 意図が明白でない箇所、フォールバックの根拠、互換性の制約には、簡潔なコメントを追加します。
• 部分的にしかサポートされていない機能を使用する理由を記載します。
• コメントは「何を」ではなく「なぜ」に焦点を当てます。

フォーマット

• プロパティの順序に一貫性を持たせます。
  1. レイアウト（display、position、grid／flex、z-index）
  2. ボックスモデル（inline-size/block-size、margin、padding、border）
  3. タイポグラフィ（font-*、line-height、text-*）
  4. ビジュアル（background、color、box-shadow、opacity、filter）
  5. モーション（transform、transition、animation）
• 間隔と配置に一貫性を持たせます。
• 小さく、単一の目的に絞ったセレクターブロックを優先します。

完了チェックリスト

• トークンモデルが定義され、CSS カスタムプロパティに明確に対応付けられています。
• ハードコードされた値を最小限に抑え、使用する場合はその理由を明確にしています。
• レイヤーの順序が明示され、ベンダー CSS が分離されています。
• ネストは浅く、読みやすく保たれています。
• コードを簡潔にできる箇所では、コンテナークエリと最新のセレクターを使用しています。
• アクセシビリティの状態に :focus-visible が含まれ、モーションに関する設定が尊重されています。
• 機能強化と限定的な機能には、フォールバックを用意しています。
• コメントは簡潔で、意図に焦点を当てています。

バージョンと調査に関するポリシー

• CSS 機能を推奨または使用条件の判定対象にする前に、ウェブ検索で最新のブラウザーサポート状況を確認します。
• プロジェクト固有のバージョンポリシーやツール設定については、ホストリポジトリに AGENTS.md または同等の指示がある場合、その内容を確認します。そこにこのカタログのデフォルトが記載されているとは限りません。
• 生成するガイダンスに特定の時点の日付やバージョン番号をハードコードせず、推奨事項を最新の状態に保てるようにします。

出力要件

CSS のガイダンスを生成またはレビューする際は、次の内容を含めます。

1. トークンに関する注記：トークンの信頼できる情報源と、実行時の CSS への対応付け方法。
2. カスケードに関する注記：レイヤーの順序とセレクターの詳細度に関する方針。
3. 機能強化に関する注記：標準機能と @supports で使用を制御する機能の区別。
4. アクセシビリティに関する注記：フォーカス、モーション、コントラスト、強制カラーモードに関する考慮事項。
5. 検証に関する注記：実際に行った lint、ビルド、ブラウザーサポート確認、または手動検証の手順。