CSS Writing Rules

CSS Writing Rules

Web ComponentsプロジェクトにおけるCSS実装ガイドライン。monosusコーディングガイドラインとプロジェクト固有ルールを統合。

Quick Reference

Critical Rules（必須遵守）

1. !important禁止 - @layerで詳細度を管理
2. ::part()必須 - Shadow DOM内でクラスではなくpart属性を使用
3. Div Soup禁止 - 不要なwrapper div削除、最小限のDOM構造を維持
4. 変数マッピングは一度だけ - プロパティ定義は1箇所、状態変化は変数再代入
5. ネスト1階層 - @layer・疑似クラス・メディアクエリを除く
6. 状態はHTML属性 - .is-openではなく[open]、[aria-expanded="true"]
7. グローバルトークン必須 - #000000ではなくvar(--color-neutral-black)

Prohibited（絶対禁止）

/* NG: !important */
color: red !important;

/* NG: カラーキーワード */
color: black;  /* → var(--color-neutral-black) */

/* NG: ハードコード色値 */
--dads-button-color: #000000;  /* → var(--color-neutral-black) */

/* NG: html font-size 62.5% */
html { font-size: 62.5%; }

/* NG: Shadow DOM内でクラス */
<div class="accordion-summary">  /* → part="summary" */

/* NG: 状態クラス */
.is-open { }  /* → [open] { } */

<!-- NG: Div Soup（不要なwrapper div） -->
<div part="outer">
  <div part="wrapper">
    <div part="container">
      <slot></slot>
    </div>
  </div>
</div>

<!-- OK: フラット構造 -->
<blockquote part="blockquote">
  <slot name="lead" part="lead"></slot>
  <slot part="body"></slot>
</blockquote>

Decision Tree

Core Workflow

新規コンポーネントCSS作成

1. @layer配置を決定（通常はcomponents）
2. CSS変数構造を設計
   • セマンティックトークン → ローカルトークン → プロパティ
3. ベーススタイル定義
   • [part="base"]でプロパティ-変数マッピング
4. 状態バリエーション追加
   • 変数再代入のみ（プロパティ再定義禁止）
5. アクセシビリティ対応
   • prefers-reduced-motion
   • @media (any-hover: hover)
6. レスポンシブ対応

CSSレビュー時チェックリスト

• !importantが使用されていない
• @layerが適切に使用されている
• ネストが1階層以内
• 状態管理がHTML属性で行われている
• 変数命名が--category-unit/value形式
• プロパティ定義が1箇所のみ
• アクセシビリティ対応（motion、hover）
• カラーキーワード未使用（HEX/RGB/HSL）

Token Architecture

Primitive Tokens        Semantic Tokens         Local Tokens           Properties
--color-blue-900   →   --button-primary-bg  →  --dads-button-bg   →  background-color

正しいパターン

/* ベース: プロパティ-変数マッピング（一度だけ） */
[part="base"] {
  background-color: var(--dads-button-background);
  color: var(--dads-button-color);
}

/* 状態: 変数再代入のみ */
:host([variant="solid"]:hover) {
  --dads-button-background: var(--button-primary-bg-hover);
}

トークン定義（TypeScript）

// 文字列として定義
const tokenText = `
  :host {
    --button-primary-bg: var(--color-primitive-blue-900);
  }
`;

// 最後にcss関数で変換
export const tokens = css`${tokenText}`;

重要: CSSStyleSheetオブジェクトを文字列テンプレート内で展開しないこと

Style Application Order

styles: withReset([
  applyDADSTokens(),    // 1. グローバルトークン
  buttonTokens,          // 2. コンポーネントトークン
  buttonStyles,          // 3. スタイル定義
  applyDADSFocusStyles() // 4. フォーカススタイル
], 'minimal')

Reference Files

詳細なルールは以下のリファレンスを参照：

Relationship with Other Docs

このスキルは /docs/css-variable-pattern.md の内容を包含・拡張したものです。

変更時は両方を更新してください。

Sources

• monosus CSS Coding Guidelines
• monosus Naming Rules

Do / Don't

Do

• Use ::part() for Shadow DOM styling — Expose customization points via part attributes, not classes.

  my-component::part(base) { background: var(--dads-button-background); }
  

• Use @layer for specificity management — Organize styles into layers instead of increasing specificity.

  @layer base, variants, states;
  

• Use design tokens for all values — Reference var(--color-*), var(--spacing-*) instead of hardcoded values.

  padding: var(--spacing-4) var(--spacing-5);
  color: var(--color-neutral-black);
  

• Use HTML attributes for state — Style based on [open], [aria-expanded="true"], not .is-open.

  :host([disabled]) { opacity: 0.5; }
  

Don't

• Use !important — Manage specificity with @layer instead. !important breaks the cascade.

  /* NG */ color: red !important;
  /* OK */ @layer states { :host([error]) { --color: var(--color-error); } }
  

• Use CSS classes in Shadow DOM — Classes leak implementation details. Use part attributes.

  /* NG */ .accordion-header { ... }
  /* OK */ [part="header"] { ... }
  

• Hardcode color or spacing values — Always use token variables.

  /* NG */ padding: 16px; color: #333;
  /* OK */ padding: var(--spacing-4); color: var(--color-text-body);
  

• Create div soup wrappers — Minimize DOM depth. Use semantic elements with part attributes.

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