@mixinの目的は、小さな例で分かる。外枠のスタイルを一度定義し、二つのセレクタから適用する。

/* Draft syntax: definition and application */
@mixin --panel-frame() {
  border: 1px solid #777777;
  border-radius: 0.5rem;
  padding: 1.5rem;
}
 
.site-card {
  @apply --panel-frame();
}
 
.site-notice {
  @apply --panel-frame();
}

--panel-frameが名前で、@applyが適用位置だ。再利用するのは宣言のまとまりになる。@functionは値を一つ計算し、paddingなどのプロパティに渡す。

定義する場所と使う場所

定義規則では名前は--で始まり、一般のスタイル規則内にmixinを定義できない。この例はトップレベルに定義し、.site-cardと.site-noticeの中で適用している。@applyはスタイル規則か、その中の入れ子のグループ規則で使う。

引数がなければ@apply --panel-frame;と括弧を省ける。ここでは後で引数を加えやすいように残した。参照しているのはmixin名であり、既存classを渡しているわけではない。

最初の例は「ここへ規則のまとまりを入れる」と読めば、二つの要素で外枠を共有する仕組みが分かる。引数を加えたら、その値がどこから見えるかも追う必要がある。文字列の置換だけではスコープを説明できない。適用されたスタイルには引き続きcascadeが働き、出所、layer、詳細度、順序も有効だ。

二つの違いを呼び出す場所に残す

記事カードとバージョン通知は角丸を共有し、枠と見出しは同じ強調色を使う。通知だけ余白を狭くすると仮定する。後の例はこのHTMLを使う。

<article class="site-card">
  <h2 class="site-panel-title">Installation guide</h2>
  <p>Start with your project's first page.</p>
</article>
 
<aside class="site-notice">
  <h2 class="site-panel-title">Release notice</h2>
  <p>Read the changelog before upgrading.</p>
</aside>

最初のCSSを次に置き換える。引数は色と余白だけで、角丸は共通のままにする。

/* Draft syntax: parameters, defaults, and nested rules */
@mixin --panel-frame(
  --accent <color>: #777777,
  --space <length>: 1.5rem
) {
  border: 1px solid var(--accent);
  border-radius: 0.5rem;
  padding: var(--space);
 
  & > .site-panel-title {
    margin-block: 0 0.75rem;
    color: var(--accent);
  }
}
 
.site-card {
  @apply --panel-frame();
}
 
.site-notice {
  @apply --panel-frame(#45687d, 1rem);
}

カードは既定値を使い、通知は#45687dと1remを渡す。--accent <color>は色、--space <length>は長さを受け、コロンの後が既定値になる。百分率はこの<length>に含まれない。引数の構文

このmixinが共有するのは色と余白だけではない。.site-panel-titleを直接の子要素にするという構造も含む。カードの見出しを別の要素で包むと、見出しの規則は一致しなくなる。この時点で見出しと外枠のスタイルを分けたい。分けなければ、内部構造が増えるたびに単純な外枠まで修正することになる。

var()で読んでも、引数が普通の公開カスタムプロパティとして要素に追加されるわけではない。草案では私有プロパティとして外部の同名値を隠し、適用要素とその子孫にだけ値が見える。& + *のような兄弟セレクタへ変えた場合、渡した色が読めるとは限らない。引数とスコープ

@contentsで、呼び出し側の内容を受け取る

条件も再利用できる。二つの要素が同じviewportの幅でコンパクト表示へ入り、カードは配置を、通知は余白と側面の枠を変えるとする。前のCSSの後に次を足す。

/* Draft syntax: shared condition, caller-supplied content */
@mixin --compact-layout() {
  @media (width <= 40rem) {
    @contents;
  }
}
 
.site-card {
  @apply --compact-layout() {
    display: grid;
    gap: 0.75rem;
    padding: 1rem;
  }
}
 
.site-notice {
  @apply --compact-layout() {
    padding: 0.75rem;
    border-inline-start-width: 3px;
  }
}

@applyの後のブロックは呼び出し側が渡し、@contentsが挿入位置を決める。共有するのは40remという条件で、どう変えるかは各コンポーネントの近くに残る。@contentsの定義

別々のコンテナ幅に反応すべき要素なら、viewportの共通条件は合わない。40remはこの例の決定で、全サイトに通用する端末分類ではない。

@contentsには代替ブロックも書けるが、使われるのは呼び出し側が内容を渡さなかった場合だけだ。空ブロックは「空の内容を渡した」ことになる。この例には代替がないため、内容なしで--compact-layout()を呼んでも宣言は増えない。

複数のコンポーネントが条件を共有し、それぞれに異なる変更を持つ場合、この仕組みを使う理由が生まれる。今回の二つだけなら、一つの@mediaに両方の規則を書く方法で十分読みやすい。次は、現在使えるCSSで同じ結果を作る。

今この外枠を作るなら、通常のCSSを使う

同じHTMLはmixinを待たずに扱える。セレクタをまとめて宣言を共有し、カスタムプロパティで違いを与える。

:root {
  --panel-radius: 0.5rem;
}
 
.site-card,
.site-notice {
  border: 1px solid var(--panel-accent, #777777);
  border-radius: var(--panel-radius);
  padding: var(--panel-space, 1.5rem);
}
 
.site-card > .site-panel-title,
.site-notice > .site-panel-title {
  margin-block: 0 0.75rem;
  color: var(--panel-accent, #777777);
}
 
.site-notice {
  --panel-accent: #45687d;
  --panel-space: 1rem;
}

HTMLを変えられるなら、共通の.site-panelを二つの要素に付けてもよい。var()が置き換えるのは値で、宣言のまとまりではない。この例の宣言再利用はグループ化やclassで足りている。カスタムプロパティ仕様

将来、この規則を別々のコンポーネントスタイルで組み合わせる必要が出たら、mixinを再検討する。呼び出し側で引数を明示したい場合や、HTMLに共通classを付けにくい場合も候補になる。ただし呼び出しのたびに半分を上書きし、アイコン、背景、見出しサイズのスイッチまで増えるなら、ブロックの役割が広すぎる。引数を足す前に分割したい。

Sassを知っていても構文はそのまま移せない。Sassは$引数と@includeを使ってコンパイラからCSSを出す。ネイティブCSSの提案は--名、@apply、CSSの値の仕組みを使う。Sass mixin

2026年10月30日の確認時点でも、草案の評価章には新しい@privateモデルへ書き直すTODOと、古い@resultの例が残っている。このため上では5.1–5.4節に沿って公開構文を説明した。5.5節の内部展開の手順は、まだ確定した動作として扱えない。草案に残る作業

この例では、共有ブロックの役割を外枠までに留めたい。内容や個別の変化は各コンポーネントのスタイルで扱う。将来、通知がこの外枠を必要としなくなったら、適用を一つ外すだけで離れられる。mixinには、そのような組み合わせ方を期待している。