The purpose of @mixin is visible in a small example: define a frame once, then let two selectors apply it.

/* 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 names the mixin; @apply marks where to use it. The reusable unit is a group of declarations. A @function, by comparison, produces a value for a property such as padding.

Definition and application belong in different places

Under the definition rules, names start with --, and a mixin definition cannot appear inside an ordinary style rule. This example defines it at the top level and applies it within .site-card and .site-notice. Application is allowed in style rules or their nested group rules.

Without arguments, parentheses can be omitted: @apply --panel-frame;. I keep them here to make adding parameters straightforward. The reference is a mixin name, not an existing class passed to @apply.

Reading the first example as “put this group of rules here” explains how the two components share a frame. Once parameters enter the picture, we also need to track where their values are visible. Text substitution alone cannot explain that scope. The resulting styles still follow the cascade, including origins, layers, specificity, and order.

Leave two differences at the call site

Suppose the article card and version notice share a radius, and each frame and heading should use the same accent color. The notice needs tighter padding. The remaining examples use this 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>

Replace the initial CSS with the following. Parameters cover color and spacing only; the radius remains shared:

/* 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);
}

The card uses defaults; the notice passes #45687d and 1rem. --accent <color> accepts a color, --space <length> a length, and the value after the colon is the default. Percentages do not belong to this <length> type. Parameter syntax

The mixin shares more than color and spacing: it also requires .site-panel-title to be a direct child. Wrap a card's heading in another element and the heading rule stops matching. I would separate heading styles from frame styles at that point. Otherwise, every new internal structure makes the simple frame responsible for another selector.

Reading parameters through var() does not create ordinary public custom properties on the element. The draft treats them as private properties, shadowing external values of the same name and visible only to the applying element and its descendants. A sibling selected by something like & + * cannot be assumed to see the passed color. Parameters and scope

@contents leaves a place for the caller's styles

Conditions offer another reusable unit. Suppose both components use the same viewport threshold for a compact layout, but the card changes arrangement while the notice tightens padding and strengthens its side border. Append this to the previous 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;
  }
}

The caller supplies the block after @apply; @contents specifies where it goes. The shared part is the 40rem condition. Each component keeps its own changes nearby. @contents definition

If the components should instead respond to separate containers, a shared viewport threshold is the wrong rule. The example's 40rem is a design choice, not a device category suitable for every site.

@contents can have fallback content, used only when the caller supplies no block. An empty block still counts as supplied content, with no declarations. This example has no fallback, so calling --compact-layout() without a block adds no styles.

The mechanism earns its place when several components share a condition but each needs its own changes. With only the two components here, a single @media containing both rules is already easy to follow. The next example implements the same result in CSS available today.

Today, I would build this frame with ordinary CSS

The HTML need not wait for mixins. Group selectors to share declarations and use custom properties for differences:

: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;
}

If the HTML can change, a shared .site-panel class can replace the grouped selectors. var() substitutes values, not whole groups of declarations; the class or grouping already supplies that reuse here. Custom-property specification

I would reconsider a mixin if these rules later needed composition across component styles, if callers needed explicit parameters, or if the HTML could not conveniently share a class. I would also inspect the calls: overriding half the settings and adding switches for icons, backgrounds, and heading sizes suggests the block already does too much. Split it before adding more parameters.

Sass familiarity does not make the syntax interchangeable. Sass uses $ parameters and @include, with a compiler producing CSS. The native proposal uses -- names, @apply, and CSS's value system. Sass mixins

As of October 30, 2026, the draft's evaluation section still has a TODO to adopt the newer @private model, alongside older @result examples. The explanation above therefore follows sections 5.1–5.4 for public syntax. Section 5.5's internal expansion steps should not yet be treated as settled behavior. Outstanding work in the draft

For this example, I would stop the shared block at the frame. Each component's styles would still handle its content and variations. If the notice later no longer needs that frame, removing one application should let it leave. That is the kind of composition I want a mixin to support.