material-theme-builder 2.1.0

package/README.md

@@ -0,0 +1,249 @@
+[![npm version](https://img.shields.io/npm/v/material-theme-builder.svg)](https://www.npmjs.com/package/material-theme-builder)
+[![](https://img.shields.io/badge/chromatic-171c23.svg?logo=chromatic)](https://www.chromatic.com/library?appId=695eb517cb602e59b4cc045c&branch=main)
+[![](https://img.shields.io/badge/storybook-171c23.svg?logo=storybook)](https://main--695eb517cb602e59b4cc045c.chromatic.com)
+
+[Material Design colors](https://m3.material.io/styles/color/system/overview)
+for React.
+
+It injects `--md-sys-color-*` and `--md-ref-palette-*` CSS variables into the page (prefix is [configurable](#programmatic-api)).
+
+https://github.com/user-attachments/assets/5b67c961-d7a4-4b64-9356-4ada26bc9be4
+
+m3 references:
+
+| builder                                                                                                                                                                                                                             | roles                                                                                                                                                                                                           |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [<img width="2836" height="2266" alt="CleanShot 2026-01-14 at 08 58 40@2x" src="https://github.com/user-attachments/assets/e4b47c00-716f-4b08-b393-de306d5ce302" />](https://material-foundation.github.io/material-theme-builder/) | [<img width="2836" height="2266" alt="CleanShot 2026-01-14 at 09 01 23@2x" src="https://github.com/user-attachments/assets/826e502d-e173-43c4-807a-53d0ba075a88" />](https://m3.material.io/styles/color/roles) |
+
+Support for:
+
+Base (like in the Builder):
+
+- [x] light/dark mode
+- [x] source color
+- [x] scheme
+- [x] contrast
+- [x] core-colors overrides: primary, secondary, tertiary, error, neutral,
+      neutralVariant
+- [x] custom-colors (aka. "Extended colors")
+  - [x] Harmonization (aka. `blend`) -- with effective color: `source` or
+        `primary` if defined
+- [x] Shades (aka. "tonals")
+- [ ] colorMatch
+
+Extra:
+
+- [x] `contrastAllColors`: contrast also applies to custom-colors and shades
+      (not only the core-colors)
+- [x] `adaptiveShades`: shades adapt to the light/dark mode (instead of being
+      fixed)
+
+# Usage
+
+```tsx
+import { Mcu } from "material-theme-builder";
+
+<Mcu
+  source="#0e1216"
+  scheme="vibrant"
+  contrast={0.5}
+  customColors={[
+    { name: "myCustomColor1", hex: "#6C8A0C", blend: true },
+    { name: "myCustomColor2", hex: "#E126C6", blend: true },
+    { name: "myCustomColor3", hex: "#E126C6", blend: false },
+  ]}
+>
+  <p style={{
+    backgroundColor: "var(--md-sys-color-surface)",
+    color: "var(--md-sys-color-on-surface)",
+  }}>
+    Hello, MCU <span style={{
+      backgroundColor: "var(--md-sys-color-my-custom-color-1)",
+      color: "var(--md-sys-color-on-my-custom-color-1)",
+    }}>colors<span>!
+  </p>
+</Mcu>
+```
+
+> [!TIP]
+>
+> Typically wrapping `{children}` in a
+> [layout](https://nextjs.org/docs/app/getting-started/layouts-and-pages#creating-a-layout).
+
+> [!NOTE]
+>
+> CSS varnames are always kebab-cased, e.g. `myCustomColor1` →
+> `--md-sys-color-my-custom-color-1` / `--md-ref-palette-my-custom-color-1-<tone>`
+
+## `useMcu`
+
+A hook is also provided:
+
+```tsx
+import { useMcu } from "material-theme-builder";
+
+const { initials, setMcuConfig, getMcuColor } = useMcu();
+
+return (
+  <button onClick={() => setMcuConfig({ ...initials, source: "#FF5722" })}>
+    Change to {getMcuColor("primary", "light")}
+  </button>
+);
+```
+
+## Tailwind
+
+Compatible through [theme variables](https://tailwindcss.com/docs/theme):
+
+https://github.com/abernier/material-theme-builder/blob/688c789e322ed3858b51389b33eb7ea342bba81e/src/tailwind.css#L3-L186
+
+Or simply:
+
+```css
+@import "material-theme-builder/tailwind.css";
+```
+
+> [!IMPORTANT]
+>
+> Do not forget to manually add your custom colors, as in:
+> https://github.com/abernier/material-theme-builder/blob/688c789e322ed3858b51389b33eb7ea342bba81e/src/tailwind.css#L126-L185
+
+## shadcn
+
+Pre-requisites:
+
+- You should use
+  [`tailwind.cssVariables`](https://ui.shadcn.com/docs/theming#css-variables)
+
+Simply override/remap
+[shadcn's CSS variables](https://ui.shadcn.com/docs/theming#list-of-variables):
+
+```css
+:root {
+  /* ... */
+}
+.dark {
+  /* ... */
+}
+
+:root,
+.dark {
+  --background: var(--md-sys-color-surface);
+  --foreground: var(--md-sys-color-on-surface);
+  --card: var(--md-sys-color-surface-container-low);
+  --card-foreground: var(--md-sys-color-on-surface);
+  --popover: var(--md-sys-color-surface-container-high);
+  --popover-foreground: var(--md-sys-color-on-surface);
+  --primary: var(--md-sys-color-primary);
+  --primary-foreground: var(--md-sys-color-on-primary);
+  --secondary: var(--md-sys-color-secondary-container);
+  --secondary-foreground: var(--md-sys-color-on-secondary-container);
+  --muted: var(--md-sys-color-surface-container-highest);
+  --muted-foreground: var(--md-sys-color-on-surface-variant);
+  --accent: var(--md-sys-color-secondary-container);
+  --accent-foreground: var(--md-sys-color-on-secondary-container);
+  --destructive: var(--md-sys-color-error);
+  --border: var(--md-sys-color-outline-variant);
+  --input: var(--md-sys-color-outline);
+  --ring: var(--md-sys-color-primary);
+  --chart-1: var(--md-sys-color-primary-fixed);
+  --chart-2: var(--md-sys-color-secondary-fixed);
+  --chart-3: var(--md-sys-color-tertiary-fixed);
+  --chart-4: var(--md-sys-color-primary-fixed-dim);
+  --chart-5: var(--md-sys-color-secondary-fixed-dim);
+  --sidebar: var(--md-sys-color-surface-container-low);
+  --sidebar-foreground: var(--md-sys-color-on-surface);
+  --sidebar-primary: var(--md-sys-color-primary);
+  --sidebar-primary-foreground: var(--md-sys-color-on-primary);
+  --sidebar-accent: var(--md-sys-color-secondary-container);
+  --sidebar-accent-foreground: var(--md-sys-color-on-secondary-container);
+  --sidebar-border: var(--md-sys-color-outline-variant);
+  --sidebar-ring: var(--md-sys-color-primary);
+}
+```
+
+<details>
+  <summary>mapping details</summary>
+  see:
+  
+    - https://chatgpt.com/share/6899f20a-422c-8011-a072-62fb649589a0
+    - https://gemini.google.com/share/51e072b6f1d2
+</details>
+
+> [!IMPORTANT]
+>
+> Make sure `:root, .dark { ... }` comes AFTER `.root { ... } .dark { ... }` to
+> take precedence.
+
+## Programmatic API
+
+```ts
+import { builder } from "material-theme-builder";
+
+const theme = builder("#6750A4", {
+  scheme: "vibrant",
+  contrast: 0.5,
+  primary: "#FF0000",
+  secondary: "#00FF00",
+  customColors: [
+    { name: "brand", hex: "#FF5733", blend: true },
+    { name: "success", hex: "#28A745", blend: false },
+  ],
+  contrastAllColors: true,
+});
+
+theme.toJson();
+theme.toCss();
+```
+
+## CLI
+
+```sh
+$ npx material-theme-builder builder "#6750A4"
+```
+
+will generate a `material-theme` folder with: `Light.tokens.json` and `Dark.tokens.json` [design-tokens](https://www.designtokens.org/tr/2025.10/) files, you can (both) import into Figma.
+
+See `npx material-theme-builder builder --help` for all available options.
+
+# Dev
+
+## INSTALL
+
+Pre-requisites:
+
+- Install [nvm](https://github.com/nvm-sh/nvm), then:
+  ```sh
+  $ nvm install
+  $ nvm use
+  $ node -v # make sure your version satisfies package.json#engines.node
+  ```
+  nb: if you want this node version to be your default nvm's one:
+  `nvm alias default node`
+- Install pnpm, with:
+  ```sh
+  $ corepack enable
+  $ corepack prepare --activate # it reads "packageManager"
+  $ pnpm -v # make sure your version satisfies package.json#engines.pnpm
+  ```
+
+```sh
+$ pnpm i
+```
+
+## Validation
+
+```sh
+$ pnpm run lgtm
+```
+
+## CONTRIBUTING
+
+When submitting a pull request, please include a changeset to document your
+changes:
+
+```bash
+pnpm exec changeset
+```
+
+This helps us maintain the changelog and version the package appropriately.