@sandlada/material-design-css 2.4.0-20260426.a → 2.5.0-20260607.a

package/README.md

@@ -1,191 +1,240 @@
-# @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
-- Prebuilt Color
-- Motion
-- Shape
-- Typography
-
-It also **supports TailwindCSS v4**.
-
-## 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.
-import '@sandlada/material-design-css/preset.css'
-
-// text-on-surface
-import '@sandlada/material-design-css/color/text-utilities.css'
-
-// bg-surface
-import '@sandlada/material-design-css/color/bg-utilities.css'
-
-// text-primary-0
-import '@sandlada/material-design-css/palette/text-utilities.css'
-
-// bg-primary-100
-import '@sandlada/material-design-css/palette/bg-utilities.css'
-
-// display-large
-import '@sandlada/material-design-css/typography/typography-utilities.css'
-
-// rounded-medium
-import '@sandlada/material-design-css/shape/shape-utilities.css'
-
-// animation-easing-expressive-fast-spatial
-import '@sandlada/material-design-css/motion/animation-utilities.css'
-
-// transition-easing-expressive-fast-spatial
-import '@sandlada/material-design-css/motion/transition-utilities.css'
-```
-
-#### Prebuilt Color
-
-Use one file from `prebuild-color/` when you want a ready-made palette instead of generating one yourself.
-
-```typescript
-import '@sandlada/material-design-css/preset.css'
-
-import '@sandlada/material-design-css/prebuild-color/orange.css'
-import '@sandlada/material-design-css/color/text-utilities.css'
-import '@sandlada/material-design-css/color/bg-utilities.css'
-```
-
-Available presets:
-
-- `blue`
-- `cold-blue`
-- `cold-purple`
-- `green`
-- `light-green`
-- `monochrome`
-- `monochrome-high-contrast`
-- `monochrome-low-contrast`
-- `orange`
-- `pink`
-- `viridian`
-- `yellow`
-
-##### Tonal Spot (2025)
-
-Algorithmically-generated palettes in `prebuild-color/tonal-spot/`. Each color comes in three contrast variants: default, `-low-contrast`, and `-high-contrast`.
-
-```typescript
-import '@sandlada/material-design-css/preset.css'
-
-import '@sandlada/material-design-css/prebuild-color/tonal-spot/red-2025.css'
-import '@sandlada/material-design-css/color/text-utilities.css'
-import '@sandlada/material-design-css/color/bg-utilities.css'
-```
-
-Available tonal spot presets:
-
-- `blue-2025`
-- `brown-2025`
-- `cyan-2025`
-- `green-2025`
-- `navy-2025`
-- `orange-2025`
-- `pink-2025`
-- `purple-2025`
-- `red-2025`
-- `yellow-2025`
-
-`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.
-
-### For TailwindCSS v4
-
-```css
-@import "tailwindcss";
-
-/**
- * Optional ready-made palette.
- * Replace `orange` with any file under `prebuild-color/`.
- */
-@import "@sandlada/material-design-css/prebuild-color/orange.css";
-
-/**
- * bg-primary
- * text-on-primary
- */
-@import "@sandlada/material-design-css/color/tailwind-theme.css";
-
-/**
- * bg-primary-90
- * text-primary-10
- */
-@import "@sandlada/material-design-css/palette/tailwind-theme.css";
-
-/* rounded-medium */
-@import "@sandlada/material-design-css/shape/tailwind-theme.css";
-
-/*
- * font-display-large
- * text-display-large
- * tracking-display-large
- * leading-display-large
- * font-weight-display-large
- */
-@import "@sandlada/material-design-css/typography/tailwind-theme.css";
-
-/* display-large */
-@import "@sandlada/material-design-css/typography/tailwind-utilities.css";
-
-/**
- * ease-emphasized
- * duration-[var(--duration-medium1)]
- */
-@import "@sandlada/material-design-css/motion/tailwind-theme.css";
-
-@layer base {
-    :root:not([dark]) {
-        color-scheme: light;
-    }
-    :root[dark] {
-        color-scheme: dark;
-    }
-}
-```
-
-## Naming Conventions
-
-- Color utilities use `bg-*` and `text-*`.
-- Prebuilt color files use the filenames from `prebuild-color/`.
-- Shape utilities use `rounded-*` plus directional suffixes like `-t`, `-r`, `-b`, and `-l`.
-- Motion utilities use `animation-*` and `transition-*` with `duration-*` and `easing-*` tokens.
-- 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
-<button class="rounded-medium bg-primary text-on-primary px-4 py-2">
-    A rounded button
-</button>
-```
-
-## Documentation
-
-For more information on how to use, please visit [the project's official website](https://material-design-css.sandlada.com)
+# @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
+- Prebuilt Colors
+- Motion
+- Shape
+- Typography
+
+It also **supports TailwindCSS v4**.
+
+## 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.
+import '@sandlada/material-design-css/preset.css'
+
+// text-on-surface
+import '@sandlada/material-design-css/color/text-utilities.css'
+
+// bg-surface
+import '@sandlada/material-design-css/color/bg-utilities.css'
+
+// text-primary-0
+import '@sandlada/material-design-css/palette/text-utilities.css'
+
+// bg-primary-100
+import '@sandlada/material-design-css/palette/bg-utilities.css'
+
+// display-large
+import '@sandlada/material-design-css/typography/typography-utilities.css'
+
+// rounded-medium
+import '@sandlada/material-design-css/shape/shape-utilities.css'
+
+// animation-easing-expressive-fast-spatial
+import '@sandlada/material-design-css/motion/animation-utilities.css'
+
+// transition-easing-expressive-fast-spatial
+import '@sandlada/material-design-css/motion/transition-utilities.css'
+```
+
+#### 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.
+
+### 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";
+
+/**
+ * bg-primary
+ * text-on-primary
+ */
+@import "@sandlada/material-design-css/color/tailwind-theme.css";
+
+/**
+ * bg-primary-90
+ * text-primary-10
+ */
+@import "@sandlada/material-design-css/palette/tailwind-theme.css";
+
+/* rounded-medium */
+@import "@sandlada/material-design-css/shape/tailwind-theme.css";
+
+/*
+ * font-display-large
+ * text-display-large
+ * tracking-display-large
+ * leading-display-large
+ * font-weight-display-large
+ */
+@import "@sandlada/material-design-css/typography/tailwind-theme.css";
+
+/* display-large */
+@import "@sandlada/material-design-css/typography/tailwind-utilities.css";
+
+/**
+ * ease-emphasized
+ * duration-[var(--duration-medium1)]
+ */
+@import "@sandlada/material-design-css/motion/tailwind-theme.css";
+
+@layer base {
+    :root:not([dark]) {
+        color-scheme: light;
+    }
+    :root[dark] {
+        color-scheme: dark;
+    }
+}
+```
+
+## Naming Conventions
+
+- Color utilities use `bg-*` and `text-*`.
+- Prebuilt color files use the filenames from `prebuilt-colors/` as described above.
+- Shape utilities use `rounded-*` plus directional suffixes like `-t`, `-r`, `-b`, and `-l`.
+- Motion utilities use `animation-*` and `transition-*` with `duration-*` and `easing-*` tokens.
+- 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
+<button class="rounded-medium bg-primary text-on-primary px-4 py-2">
+    A rounded button
+</button>
+```
+
+## Documentation
+
+For more information on how to use, please visit [the project's official website](https://material-design-css.sandlada.com)

package/package.json

@@ -4,73 +4,23 @@
     "description": "A ready-made npm package for a collection of css styles in the material design style.",
     "exports": {
         "./*": "./*",
-        "./color/bg-utilities.css": "./color/bg-utilities.css",
-        "./color/tailwind-theme.css": "./color/tailwind-theme.css",
-        "./color/text-utilities.css": "./color/text-utilities.css",
-        "./motion/animation-utilities.css": "./motion/animation-utilities.css",
-        "./motion/tailwind-theme.css": "./motion/tailwind-theme.css",
-        "./motion/transition-utilities.css": "./motion/transition-utilities.css",
-        "./palette/bg-utilities.css": "./palette/bg-utilities.css",
-        "./palette/tailwind-theme.css": "./palette/tailwind-theme.css",
-        "./palette/text-utilities.css": "./palette/text-utilities.css",
-        "./prebuild-color/blue.css": "./prebuild-color/blue.css",
-        "./prebuild-color/cold-blue.css": "./prebuild-color/cold-blue.css",
-        "./prebuild-color/cold-purple.css": "./prebuild-color/cold-purple.css",
-        "./prebuild-color/green.css": "./prebuild-color/green.css",
-        "./prebuild-color/light-green.css": "./prebuild-color/light-green.css",
-        "./prebuild-color/monochrome-high-contrast.css": "./prebuild-color/monochrome-high-contrast.css",
-        "./prebuild-color/monochrome-low-contrast.css": "./prebuild-color/monochrome-low-contrast.css",
-        "./prebuild-color/monochrome.css": "./prebuild-color/monochrome.css",
-        "./prebuild-color/orange.css": "./prebuild-color/orange.css",
-        "./prebuild-color/pink.css": "./prebuild-color/pink.css",
-        "./prebuild-color/tonal-spot/blue-2025-high-contrast.css": "./prebuild-color/tonal-spot/blue-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/blue-2025-low-contrast.css": "./prebuild-color/tonal-spot/blue-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/blue-2025.css": "./prebuild-color/tonal-spot/blue-2025.css",
-        "./prebuild-color/tonal-spot/brown-2025-high-contrast.css": "./prebuild-color/tonal-spot/brown-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/brown-2025-low-contrast.css": "./prebuild-color/tonal-spot/brown-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/brown-2025.css": "./prebuild-color/tonal-spot/brown-2025.css",
-        "./prebuild-color/tonal-spot/cyan-2025-high-contrast.css": "./prebuild-color/tonal-spot/cyan-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/cyan-2025-low-contrast.css": "./prebuild-color/tonal-spot/cyan-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/cyan-2025.css": "./prebuild-color/tonal-spot/cyan-2025.css",
-        "./prebuild-color/tonal-spot/green-2025-high-contrast.css": "./prebuild-color/tonal-spot/green-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/green-2025-low-contrast.css": "./prebuild-color/tonal-spot/green-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/green-2025.css": "./prebuild-color/tonal-spot/green-2025.css",
-        "./prebuild-color/tonal-spot/navy-2025-high-contrast.css": "./prebuild-color/tonal-spot/navy-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/navy-2025-low-contrast.css": "./prebuild-color/tonal-spot/navy-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/navy-2025.css": "./prebuild-color/tonal-spot/navy-2025.css",
-        "./prebuild-color/tonal-spot/orange-2025-high-contrast.css": "./prebuild-color/tonal-spot/orange-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/orange-2025-low-contrast.css": "./prebuild-color/tonal-spot/orange-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/orange-2025.css": "./prebuild-color/tonal-spot/orange-2025.css",
-        "./prebuild-color/tonal-spot/pink-2025-high-contrast.css": "./prebuild-color/tonal-spot/pink-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/pink-2025-low-contrast.css": "./prebuild-color/tonal-spot/pink-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/pink-2025.css": "./prebuild-color/tonal-spot/pink-2025.css",
-        "./prebuild-color/tonal-spot/purple-2025-high-contrast.css": "./prebuild-color/tonal-spot/purple-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/purple-2025-low-contrast.css": "./prebuild-color/tonal-spot/purple-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/purple-2025.css": "./prebuild-color/tonal-spot/purple-2025.css",
-        "./prebuild-color/tonal-spot/red-2025-high-contrast.css": "./prebuild-color/tonal-spot/red-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/red-2025-low-contrast.css": "./prebuild-color/tonal-spot/red-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/red-2025.css": "./prebuild-color/tonal-spot/red-2025.css",
-        "./prebuild-color/tonal-spot/yellow-2025-high-contrast.css": "./prebuild-color/tonal-spot/yellow-2025-high-contrast.css",
-        "./prebuild-color/tonal-spot/yellow-2025-low-contrast.css": "./prebuild-color/tonal-spot/yellow-2025-low-contrast.css",
-        "./prebuild-color/tonal-spot/yellow-2025.css": "./prebuild-color/tonal-spot/yellow-2025.css",
-        "./prebuild-color/viridian.css": "./prebuild-color/viridian.css",
-        "./prebuild-color/yellow.css": "./prebuild-color/yellow.css",
-        "./preset.css": "./preset.css",
-        "./shape/shape-utilities.css": "./shape/shape-utilities.css",
-        "./shape/tailwind-theme.css": "./shape/tailwind-theme.css",
-        "./typography/tailwind-theme.css": "./typography/tailwind-theme.css",
-        "./typography/tailwind-utilities.css": "./typography/tailwind-utilities.css",
-        "./typography/typography-utilities.css": "./typography/typography-utilities.css"
+        "./color/*": "./color/*",
+        "./motion/*": "./motion/*",
+        "./palette/*": "./palette/*",
+        "./prebuilt-colors/*": "./prebuilt-colors/*",
+        "./prebuilt-colors/**/*": "./prebuilt-colors/**/*",
+        "./shape/*": "./shape/*",
+        "./typography/*": "./typography/*"
     },
     "files": [
-        "color/*",
-        "motion/*",
-        "palette/*",
-        "prebuild-color/*",
-        "prebuild-color/tonal-spot/*",
+        "LICENSE",
+        "color/**/*",
+        "motion/**/*",
+        "palette/**/*",
+        "prebuilt-colors/**/*",
         "preset.css",
-        "shape/*",
-        "typography/*"
+        "shape/**/*",
+        "typography/**/*"
     ],
     "homepage": "https://material-design-css.sandlada.com",
     "keywords": [
@@ -95,7 +45,10 @@
         "type": "git",
         "url": "https://github.com/sandlada/material-design-css.git"
     },
-    "style": "preset.css",
     "type": "module",
-    "version": "2.4.0-20260426.a"
+    "version": "2.5.0-20260607.a",
+    "devDependencies": {
+        "@material/material-color-utilities": "^0.4.0",
+        "@sandlada/material-theme-cli": "^1.0.0-20260525.a"
+    }
 }