# @sandlada/material-design-css ![Preview Image](https://raw.githubusercontent.com/sandlada/material-design-css/refs/heads/main/images/cover.png) ![NPM Downloads](https://img.shields.io/npm/d18m/@sandlada/material-design-css?label=NPM%20Downloads&labelColor=%2300531f&color=%23a3f5aa) ![NPM Version](https://img.shields.io/npm/v/%40sandlada%2Fmaterial-design-css?label=NPM%20Version&labelColor=%2300531f&color=%23a3f5aa) ![GitHub License](https://img.shields.io/github/license/sandlada/material-design-css?label=License&labelColor=%2300531f&color=%23a3f5aa) `@sandlada/material-design-css` is a CSS npm package for Material Design Tokens, styles include: - Color - Palette - Motion - Shape - Spacing - Typography - Prebuilt Colors - Prebuilt Palettes It also **supports TailwindCSS v4**. ## Documentation For more information on how to use, please visit [the project's official website](https://material-design-css.sandlada.com) ## Installation ```plaintext npm i @sandlada/material-design-css ``` ## Import ### For CSS ```typescript // TypeScript File // If you are using Vite or Webpack. // In CSS file, use @import instead. (You may need to adjust the path depending on your setup, e.g., `@import "../node_modules/@sandlada/material-design-css/preset.css";`) /** * Load preset before color or prebuilt-color utilities. * * :root:not([dark]) { * color-scheme: light; * } * * :root[dark] { * color-scheme: dark; * } */ import "@sandlada/material-design-css/preset.css" // text-on-surface & bg-surface import "@sandlada/material-design-css/color/utilities.css" // See more details on the /prebuilt-colors page. import "@sandlada/material-design-css/prebuilt-colors/tonal-spot/h0-2025.css" // text-primary-0 & bg-primary-100 import "@sandlada/material-design-css/palette/utilities.css" // Prebuilt Palettes. See more details on the /prebuilt-palettes page. import "@sandlada/material-design-css/prebuilt-palettes/tonal-spot/h0-2025.css" // display-large import "@sandlada/material-design-css/typography/utilities.css" import "@sandlada/material-design-css/typography/variables.css" // rounded-medium import "@sandlada/material-design-css/shape/utilities.css" import "@sandlada/material-design-css/shape/variables.css" // animation-easing-expressive-fast-spatial & transition-easing-expressive-fast-spatial import "@sandlada/material-design-css/motion/utilities.css" import "@sandlada/material-design-css/motion/variables.css" // spacing utilities import "@sandlada/material-design-css/spacing/utilities.css" import "@sandlada/material-design-css/spacing/variables.css" ``` ### For TailwindCSS v4 ```css @import "tailwindcss"; /** * Optional ready-made palette. * Replace the path with any file under prebuilt-colors/. */ @import "@sandlada/material-design-css/prebuilt-colors/tonal-spot/h0-2025.css"; @import "@sandlada/material-design-css/prebuilt-palettes/tonal-spot/h0-2025.css"; /** * bg-primary * text-on-primary */ @import "@sandlada/material-design-css/color/tw.css"; /** * bg-primary-90 * text-primary-10 */ @import "@sandlada/material-design-css/palette/tw.css"; /* rounded-medium */ @import "@sandlada/material-design-css/shape/tw.css"; /* spacing */ @import "@sandlada/material-design-css/spacing/tw.css"; /* * display-large * font-display-large * text-display-large * tracking-display-large * leading-display-large * font-weight-display-large */ @import "@sandlada/material-design-css/typography/tw.css"; /** * ease-emphasized * duration-[var(--duration-medium1)] */ @import "@sandlada/material-design-css/motion/tw.css"; ``` ## Naming Conventions - Color utilities use `bg-*` and `text-*`. - Prebuilt color files use the filenames from `prebuilt-colors/` as described above. - Prebuilt palette files are organized under `prebuilt-palettes/{variant}/`. Most variants use `h{hue}-{year}.css` / `h{hue}-{year}-minimal.css`; `content` and `fidelity` use `h{hue}c{chroma}t{tone}-{year}.css` / `h{hue}c{chroma}t{tone}-{year}-minimal.css`; `monochrome` uses `black-{year}.css` / `black-{year}-minimal.css`. - Shape utilities use `rounded-*` plus directional suffixes like `-t`, `-r`, `-b`, and `-l`. - Motion utilities use `animation-*` and `transition-*` with `duration-*` and `easing-*` tokens. - Spacing utilities use `space-*` and `gap-*`. - Typography utilities use `emphasized-*` for emphasized variants and the base type scale names for standard variants. ## Usage Copy this code into your configured project and you will see a button with color and rounded corners. ```html ``` ### Prebuilt Colors Prebuilt colors are ready-made color palettes generated by Material Design's color system. Each CSS file contains light/dark schemes and three contrast levels (default, low-contrast, high-contrast) built in. To use a prebuilt color, import `preset.css` first, then import the desired prebuilt color file, followed by the color utilities. ```typescript import '@sandlada/material-design-css/preset.css' import '@sandlada/material-design-css/prebuilt-colors/tonal-spot/h0-2025.css' import '@sandlada/material-design-css/color/text-utilities.css' import '@sandlada/material-design-css/color/bg-utilities.css' ``` Toggle the `dark` attribute on `:root` to switch between light and dark themes, or use `low-contrast` / `high-contrast` attributes to adjust contrast. #### Naming Conventions for Prebuilt Colors Prebuilt colors are organized into **9 variants** under `prebuilt-colors/`: | Variant | Directory | Description | | ----------- | -------------- | --------------------------------- | | Monochrome | `monochrome/` | Single-tone grayscale palette | | Neutral | `neutral/` | Neutral palette with a subtle hue | | Tonal Spot | `tonal-spot/` | Balanced tonal palette | | Vibrant | `vibrant/` | Highly saturated palette | | Expressive | `expressive/` | Expressive and dynamic palette | | Rainbow | `rainbow/` | Rainbow-inspired palette | | Fruit Salad | `fruit-salad/` | Diverse multi-hue palette | | Content | `content/` | Content-color aligned palette | | Fidelity | `fidelity/` | Fidelity-optimized palette | There are **two filename patterns** depending on the variant: **Pattern A — Hue + Year (`monochrome` is a special case)** Used by: `neutral`, `tonal-spot`, `vibrant`, `expressive`, `rainbow`, `fruit-salad` ``` h{hue}-{year}.css ``` - `{hue}`: Hue angle in degrees. Available values: `0`, `30`, `60`, `90`, `120`, `150`, `180`, `210`, `240`, `270`, `300`, `330`, `360` - `{year}`: Material Design spec version. Values: `2021` or `2025` Example filenames: - `prebuilt-colors/tonal-spot/h0-2025.css` - `prebuilt-colors/vibrant/h180-2021.css` > **Note:** Each file internally contains **three contrast modes**: default (`:root`), `low-contrast` (`:root[low-contrast]`), and `high-contrast` (`:root[high-contrast]`). **Special case — `monochrome`** ``` prebuilt-colors/monochrome/black.css ``` Only one file exists for monochrome. **Pattern B — Hue + Chroma + Tone + Year** Used by: `content`, `fidelity` ``` h{hue}c{chroma}t{tone}-{year}.css ``` - `{hue}`: Hue angle (`0`, `30`, `60`, `90`, `120`, `150`, `180`, `210`, `240`, `270`, `300`, `330`, `360`) - `{chroma}`: Chroma value in HCT color space. Values: `30`, `60`, `90` - `{tone}`: Tone value in HCT color space. Values: `20`, `50`, `80` - `{year}`: Material Design spec version. Values: `2021` or `2025` Example filenames: - `prebuilt-colors/content/h0c30t20-2025.css` - `prebuilt-colors/fidelity/h180c60t50-2021.css` Each file also contains three built-in contrast levels. ##### Examples by Variant **Monochrome** ```typescript import '@sandlada/material-design-css/preset.css' import '@sandlada/material-design-css/prebuilt-colors/monochrome/black.css' ``` **Neutral / Tonal Spot / Vibrant / Expressive / Rainbow / Fruit Salad** ```typescript import '@sandlada/material-design-css/preset.css' import '@sandlada/material-design-css/prebuilt-colors/neutral/h120-2025.css' import '@sandlada/material-design-css/prebuilt-colors/tonal-spot/h0-2025.css' import '@sandlada/material-design-css/prebuilt-colors/vibrant/h240-2025.css' ``` **Content / Fidelity** ```typescript import '@sandlada/material-design-css/preset.css' import '@sandlada/material-design-css/prebuilt-colors/content/h0c30t20-2025.css' import '@sandlada/material-design-css/prebuilt-colors/fidelity/h180c60t50-2025.css' ``` `preset.css` also defines the light and dark color-scheme contract used by the color utilities. Toggle the `dark` attribute on `:root` to switch themes. ### Prebuilt Palettes Prebuilt palettes provide raw reference tonal palettes generated by Material Design's color system. Unlike prebuilt colors, these are **not** semantic color schemes — they are low-level palette data you can use to build custom designs. Each file defines CSS custom properties for six reference palettes: ```css --md-ref-palette-primary-{tone}: #hex; --md-ref-palette-secondary-{tone}: #hex; --md-ref-palette-tertiary-{tone}: #hex; --md-ref-palette-error-{tone}: #hex; --md-ref-palette-neutral-{tone}: #hex; --md-ref-palette-neutral-variant-{tone}: #hex; ``` Where `{tone}` ranges from `0` to `100`. There are **9 variants**, organized into subdirectories under `prebuilt-palettes/`: | Variant | Directory | Filename Pattern | Description | | ----------- | -------------- | --------------------------------------------------------------------------------- | --------------------------------- | | Monochrome | `monochrome/` | `black-{year}.css` / `black-{year}-minimal.css` | Single-tone grayscale palette | | Neutral | `neutral/` | `h{hue}-{year}.css` / `h{hue}-{year}-minimal.css` | Neutral palette with a subtle hue | | Tonal Spot | `tonal-spot/` | `h{hue}-{year}.css` / `h{hue}-{year}-minimal.css` | Balanced tonal palette | | Vibrant | `vibrant/` | `h{hue}-{year}.css` / `h{hue}-{year}-minimal.css` | Highly saturated palette | | Expressive | `expressive/` | `h{hue}-{year}.css` / `h{hue}-{year}-minimal.css` | Expressive and dynamic palette | | Rainbow | `rainbow/` | `h{hue}-{year}.css` / `h{hue}-{year}-minimal.css` | Rainbow-inspired palette | | Fruit Salad | `fruit-salad/` | `h{hue}-{year}.css` / `h{hue}-{year}-minimal.css` | Diverse multi-hue palette | | Content | `content/` | `h{hue}c{chroma}t{tone}-{year}.css` / `h{hue}c{chroma}t{tone}-{year}-minimal.css` | Content-color aligned palette | | Fidelity | `fidelity/` | `h{hue}c{chroma}t{tone}-{year}.css` / `h{hue}c{chroma}t{tone}-{year}-minimal.css` | Fidelity-optimized palette | **Parameters:** - `{hue}`: Hue angle in degrees. Available values: `0`, `30`, `60`, `90`, `120`, `150`, `180`, `210`, `240`, `270`, `300`, `330`, `360` - `{chroma}`: Chroma value in HCT color space. Values: `30`, `60`, `90` (only for `content` and `fidelity`) - `{tone}`: Tone value in HCT color space. Values: `20`, `50`, `80` (only for `content` and `fidelity`) - `{year}`: Material Design spec version. Values: `2021` or `2025` **Versions:** | Version | Suffix | Tone values | | ------- | ---------- | ---------------------------------------------------------- | | Full | *(none)* | 0 ~ 100 (101 tones) | | Minimal | `-minimal` | 0–5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95–100 (21 tones) | Example filenames: - `prebuilt-palettes/tonal-spot/h0-2025.css` - `prebuilt-palettes/tonal-spot/h180-2025-minimal.css` - `prebuilt-palettes/content/h0c30t20-2025.css` - `prebuilt-palettes/fidelity/h180c60t50-2025-minimal.css` - `prebuilt-palettes/monochrome/black-2025.css` ```typescript import '@sandlada/material-design-css/prebuilt-palettes/tonal-spot/h0-2025.css' ``` Then use the palette tokens in your styles: ```css .my-element { background-color: var(--md-ref-palette-primary-40); color: var(--md-ref-palette-primary-90); } ```