Appearance
Mixins
Sass mixins: media queries, grid, spacing, theme and export of CSS variables.
37 documented in src/mixins.scss.
corners-cut($values, $symmetry: null)
Mixin to cut corners of an element using a clip-path polygon. This mixin allows you to cut corners of an element in a polygonal shape.
| Parameter | Type | Description |
|---|---|---|
$values | map | A map containing the corner values (top-left, top-right, bottom-right, bottom-left). |
$symmetry | string|null | Optional parameter to define the symmetry of the corners (e.g., horizontal, vertical). |
Throws {Error} If an invalid symmetry is provided.
elevation($elevation: 0, $color: null)
Mixin to add elevation (box-shadow) to an element. This mixin applies a box-shadow based on the given elevation level and color.
| Parameter | Type | Description |
|---|---|---|
$elevation | number | The elevation level (0 or higher). |
$color | color|null | The shadow color. Default: the color of the level in $elevations. |
media-queries($key: null, $range: min)
Wraps what follows in the media query of a width class. Mobile first: the default is min-width, so the rules apply from the class up and only redefine what changes. base is the base, below the first class: its rules are written as they are, with no query.
| Parameter | Type | Description |
|---|---|---|
$key | string|null | The width class, or base. null writes the content for each class. |
$range | string | min (from the class up), max (up to the class) or both (this class only). |
Throws Error if the class does not exist, or the range is not min, max or both.
media-queries-height($key)
Wraps what follows in the media query of a height class, for the wide but short screens (a phone in landscape). Mobile first like media-queries(): from the height up.
| Parameter | Type | Description |
|---|---|---|
$key | string | The height class (medium, expanded), or base. |
Throws Error if the class does not exist.
shape($shape, $cornerOrSide: null, $symmetry: null)
Mixin to apply a specific shape to an element using border-radius. This mixin allows you to apply different shapes (e.g., circle, rounded) to elements.
| Parameter | Type | Description |
|---|---|---|
$shape | string | The shape name (e.g., medium, full) or a raw px value. |
$cornerOrSide | string|null | A specific corner or side to apply the shape (optional). |
$symmetry | string|null | Mirror the radius across an axis: horizontal, vertical, or diagonal (optional). |
Throws {Error} If an invalid corner, side, or symmetry type is provided.
triangle($direction, $size, $color: currentColor)
Mixin to create a triangle using borders. This mixin creates a triangle shape using CSS borders and can be used for indicators, pointers, etc.
| Parameter | Type | Description |
|---|---|---|
$direction | string | The triangle direction (e.g., up, right, down, left, top-right, bottom-right, bottom-left, top-left. |
$size | number | The size of the triangle in pixels. |
$color | color | The triangle color (default: currentColor). |
Throws {Error} If an invalid direction is provided.
grid($columns: MithrilConfig.$default-grid-columns, $gap: null)
Mixin to create a responsive grid layout. This mixin generates a grid with customizable columns and gaps, suitable for responsive designs.
| Parameter | Type | Description |
|---|---|---|
$columns | number | Number of columns (default is $default-grid-columns). |
$gap | string|number|null | Gap size. Default: the gap of the base grid in $grids. |
padding($spacings)
Mixin to add padding to an element. This mixin sets padding values based on a provided map for each side (top, right, bottom, left).
| Parameter | Type | Description |
|---|---|---|
$spacings | map | Map with padding values for each side (top, right, bottom, left). |
generate-spacing-utilities($key, $value, $placeholder, $property)
Mixin to generate utility classes for padding and margin based on a given property and value. This mixin creates responsive utility classes for different sides of an element (top, right, bottom, left).
| Parameter | Type | Description |
|---|---|---|
$key | string | The key for the spacing (e.g., small, medium, large). |
$value | string|number | The value for the spacing (in pixels, rem, etc.). |
$placeholder | string | The CSS property for spacing (e.g., p, m). |
$property | string | The CSS property for spacing (e.g., padding, margin). |
color-token($name, $value)
Writes a CSS custom property, and its -rgb twin when the value is a color. The twin holds the channels (--primary-rgb: 69 90 100), so that the color can take an opacity: rgb(var(--primary-rgb) / 0.5).
| Parameter | Type | Description |
|---|---|---|
$name | string | The name of the custom property, without the leading dashes. |
$value | any | The value. A color of any format also gets the -rgb twin. |
generate-theme($overrides: (), $mode: light)
Writes the semantic theme tokens as CSS custom properties, each color with its -rgb twin: --primary, --primary-rgb, --on-primary, --secondary, --surface, etc. Call it once, in :root. Pass a partial map to override only some of the tokens.
Default tokens (all map to Material palette values): primary, primary-variant, on-primary, secondary, secondary-variant, on-secondary, surface, on-surface, background, on-background, error, on-error
Reference the tokens in SCSS with fn.theme(), and use the -rgb twin to give a color an opacity.
It also writes the roles of Material 3 that come from these colors (primary-container, surface-container-*, outline, inverse-surface...), with the tone of the mode: see $theme-roles and color-tone().
| Parameter | Type | Description |
|---|---|---|
$overrides | map | Partial map of token and color to override the defaults (optional). |
$mode | string | light (default) or dark: the tones of the roles. |
scss
:root { @include mx.generate-theme(); }
:root { @include mx.generate-theme((primary: #ff5722, on-primary: #fff)); }
.button {
background: fn.theme("primary"); // var(--primary)
box-shadow: 0 0 0 4px rgb(var(--primary-rgb) / 0.3);
}export-css-variables($data: null)
Exports the design tokens that the stylesheets use as CSS custom properties on :root.
| Parameter | Type | Description |
|---|---|---|
$data | map|null | Extra tokens to export, as a map of name and value (optional). |
export-if-used($var-name, $value, $used-vars)
Writes a CSS custom property only when the token is in use.
| Parameter | Type | Description |
|---|---|---|
$var-name | string | The name of the token, without the leading dashes. |
$value | any | The value to write. |
$used-vars | list | The tokens in use, from get-used-variables(). |
export-breakpoints($used-vars)
Writes the breakpoints, in rem, for the tokens in use only. Called by export-css-variables().
Names: breakpoint-<class> for the width, breakpoint-height-<class> for the height.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-containers($used-vars)
Writes the container widths, in rem, for the tokens in use only. Called by export-css-variables().
Names: container-<class>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-grid($used-vars)
Writes the number of columns, the gaps and the margins of the grid, for the tokens in use only. Called by export-css-variables().
Names: grid-cols-<n> and grid-<class>-<cols|gap|margin>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-spacings($used-vars)
Writes the spacing scale, in rem, for the tokens in use only. Called by export-css-variables().
Names: spacing-<key>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-opacity($used-vars)
Writes the opacity levels, for the tokens in use only. Called by export-css-variables().
Names: opacity-<key>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-typography($used-vars)
Writes the font families, weights, sizes, line heights, letter spacings, fluid sizes and headings, for the tokens in use only. Called by export-css-variables().
Names: typo-<ff|fw|fs|lh|ls>-<key>, font-size-fluid-<key> and h<level>-<property>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-type-scale($used-vars)
Writes the styles of the type scale, for the tokens in use only. Called by export-css-variables().
Names: type-<style>-font|size|line-height|tracking|weight|emphasized-weight.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-shapes($used-vars)
Writes the shape radii, in rem, for the tokens in use only. Called by export-css-variables().
Names: shape-<key>, and shape-<key>-top|end|bottom|start for the corners of one side.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-elevations($used-vars)
Writes the elevations, as a box-shadow value, for the tokens in use only. Called by export-css-variables().
Names: elevation-<level>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-states($used-vars)
Writes the state opacities, for the tokens in use only. Called by export-css-variables().
Names: <key>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-colors($used-vars)
Writes the colors of the palette, each with its -rgb twin, for the tokens in use only. Called by export-css-variables().
Names: <family> and <family>-<shade>.
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
export-data($used-vars, $data)
Writes the tokens of the application that are in use, each color with its -rgb twin. Called by export-css-variables().
| Parameter | Type | Description |
|---|---|---|
$used-vars | list | The tokens in use, from get-used-variables(). |
$data | map | The tokens of the application, as a map of name and value. |
p($key, $direction: null)
Mixin to add padding to an element.
respond-to($key: null, $range: min)
Short name of media-queries().
| Parameter | Type | Description |
|---|---|---|
$key | string|null | The width class (optional). |
$range | string | min, max or both. Default: min. |
container($key)
Mixin to constrain an element to the container width of a width class.
| Parameter | Type | Description |
|---|---|---|
$key | string | The width class (medium, expanded...). |
heading($level)
Mixin to apply all heading styles for a given level (1-6). Outputs margin, padding, line-height, font-weight, and letter-spacing. Font size is NOT included - pair with mx.text-fluid('h1') if needed.
| Parameter | Type | Description |
|---|---|---|
$level | number | The heading level (1 to 6). |
Throws {Error} If the heading level does not exist.
type($role, $emphasized: false)
Mixin to apply a style of the Material 3 type scale: font, size, line height, tracking and weight, in rem so they follow the base font size.
| Parameter | Type | Description |
|---|---|---|
$role | string | The style (display-large, body-medium, label-small...). |
$emphasized | boolean | The emphasized style of the role: heavier, for the selected, the |
Throws {Error} If the style does not exist.
font-size($key)
Mixin to apply a font-size from the $font-size map.
| Parameter | Type | Description |
|---|---|---|
$key | string|number | The font-size key (e.g., 'base', 16, 24). |
Throws {Error} If the key does not exist.
text-fluid($key)
Mixin to apply a fluid font-size using clamp() from the $font-size-fluid map.
| Parameter | Type | Description |
|---|---|---|
$key | string | The fluid font-size key (e.g., 'base', 'h1', 'lg'). |
Throws {Error} If the key does not exist.
line-height($key)
Mixin to apply a line-height from the $line-height map. Unitless ratio values (e.g., 1.2) are applied as-is; px values are converted to rem.
| Parameter | Type | Description |
|---|---|---|
$key | string|number | The line-height key (e.g., 'base', 5, 'large'). |
Throws {Error} If the key does not exist.
state-layer($state: 'hover')
Mixin to apply a Material Design state layer via a ::before pseudo-element. Sets position: relative on the host and overlays a currentColor pseudo-element at the appropriate opacity for the given interaction state.
| Parameter | Type | Description |
|---|---|---|
$state | string | The interaction state: 'hover', 'focus', or 'pressed'. Default: 'hover'. |
Throws {Error} If the state is not valid.
ripple($color: currentcolor, $press: null, $release: null)
The ripple of a press, in CSS only: a soft circle fades in under the finger or the pointer and out when it is released, with the opacity of the pressed state of Material 3 and the gradient of the md-ripple of Material Web. It is centered; set --ripple-x and --ripple-y (in %) on the element to make it start where the press happened.
It needs no JavaScript, and it is not written for the readers who ask for less motion or use forced colors.
| Parameter | Type | Description |
|---|---|---|
$color | color | The color of the ripple. Default: the color of the text. |
$press | number|null | How long it takes to show on the press. Default: from $motion. |
$release | number|null | How long it takes to fade out. Default: from $motion. |
state-disabled()
Mixin to apply a disabled state to an element. Sets the Material Design disabled opacity and blocks pointer interactions.
m($key, $direction: null)
Mixin to add padding to an element.