From 8503bef24b35de4325e403f4b11c53996b3fe159 Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Thu, 17 Oct 2024 11:06:44 +0700
Subject: [PATCH] add runtime theme docs

---
 .../pigment-css/pigment-css.md                | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/data/material/experimental-api/pigment-css/pigment-css.md b/docs/data/material/experimental-api/pigment-css/pigment-css.md
index 07fed588a07523..9b90d8cbf907bf 100644
--- a/docs/data/material/experimental-api/pigment-css/pigment-css.md
+++ b/docs/data/material/experimental-api/pigment-css/pigment-css.md
@@ -341,3 +341,35 @@ declare global {
   }
 }
 ```
+
+### Runtime theme
+
+:::info
+
+**Caveat**
+
+- Avoid using the runtime theme unless you have a compelling reason.
+- The runtime theme contains [**only serializable values**](https://developer.mozilla.org/en-US/docs/Glossary/Serializable_object) (some functions still exist in `breakpoints` and `transitions` for internal logic inside components but may be removed in the future).
+- The runtime theme will not change between modes (light and dark) because it is pre-compiled at build time. To render something based on the theme structure and its values, use `theme.vars.*` to refer to CSS variables instead.
+
+:::
+
+To access the runtime theme, use the `useTheme` hook:
+
+```js
+import { useTheme } from '@mui/material-pigment-css';
+
+function MyComponent() {
+  const theme = useTheme();
+
+  return (
+    <div>
+      {Object.entries(theme.vars.palette.primary).map(([key, value]) => (
+        <div key={key} style={{ width: 40, height: 40, background: value }}>
+          {key}: {value}
+        </div>
+      ))}
+    </div>
+  );
+}
+```