docs: add ui kit tokens section (#4862)

* docs: add ui kit tokens section

Author: plagoa

apps/docs/src/components/ThemeSwitcher.tsx

@@ -16,6 +16,7 @@ const allowedPaths = [
   "/charts",
   "/examples",
   "/docs/color-tokens",
+  "/docs/theme-tokens",
 ];
 
 export const ThemeSwitcher = () => {

apps/docs/src/components/tokens/BreakpointTokens.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import { HvTypography, useTheme } from "@hitachivantara/uikit-react-core";
+import { HvBreakpoints } from "@hitachivantara/uikit-styles";
+
+import { DocsProvider } from "../code/DocsProvider";
+
+export const BreakpointTokens = () => {
+  return (
+    <DocsProvider className="bg-transparent space-y-10">
+      <BreakpointTokensInternal />
+    </DocsProvider>
+  );
+};
+export const BreakpointTokensInternal = () => {
+  const { activeTheme } = useTheme();
+  if (!activeTheme) return null;
+
+  return (
+    <section className="flex flex-col gap-sm w-100% mt-sm">
+      {Object.entries(activeTheme.breakpoints.values).map(([categoryKey]) => {
+        if (categoryKey === "circle") return null;
+
+        const breakpointValue =
+          activeTheme.breakpoints.values[categoryKey as HvBreakpoints];
+
+        const barWidth =
+          categoryKey === "xs" ? 3 : (breakpointValue * 80) / 1920;
+
+        return (
+          <div
+            className="flex w-100% flex items-center gap-xs"
+            key={categoryKey}
+          >
+            <div
+              className="h-20px border-1 border-dashed border-borderStrong bg-bgContainer"
+              style={{ width: `${barWidth}%` }}
+            >
+              <HvTypography component="code">{categoryKey}</HvTypography>
+            </div>
+
+            <HvTypography variant="caption1">{breakpointValue}px</HvTypography>
+          </div>
+        );
+      })}
+    </section>
+  );
+};

apps/docs/src/components/color/ColorTokens.tsx renamed to apps/docs/src/components/tokens/ColorTokens.tsx

@@ -3,12 +3,12 @@
 import { HvTypography, useTheme } from "@hitachivantara/uikit-react-core";
 
 import { DocsProvider } from "../code/DocsProvider";
-import { descriptions } from "./descriptions";
+import { descriptions } from "../color/descriptions";
 import {
   colorTokensSpec,
   compatMap,
   groupColorTokensByCategory,
-} from "./utils";
+} from "../color/utils";
 
 export const ColorTokens = () => {
   return (

apps/docs/src/components/tokens/RadiiTokens.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { HvTypography, useTheme } from "@hitachivantara/uikit-react-core";
+
+import { DocsProvider } from "../code/DocsProvider";
+
+export const RadiiTokens = () => {
+  return (
+    <DocsProvider className="bg-transparent space-y-10">
+      <RadiiTokensInternal />
+    </DocsProvider>
+  );
+};
+
+export const RadiiTokensInternal = () => {
+  const { activeTheme } = useTheme();
+  if (!activeTheme) return null;
+
+  return (
+    <section className="flex gap-sm  w-100% justify-center mt-sm">
+      {Object.entries(activeTheme.radii).map(([categoryKey]) => {
+        if (categoryKey === "circle") return null;
+
+        return (
+          <div className="flex flex-col items-center" key={categoryKey}>
+            <div
+              style={{ borderRadius: activeTheme.radii[categoryKey] }}
+              className="p-md border-dashed border-1 border-borderStrong bg-bgContainer w-100px h-100px"
+            />
+            <HvTypography component="code">{categoryKey}</HvTypography>
+            <HvTypography variant="caption1">
+              {activeTheme.radii[categoryKey]}
+            </HvTypography>
+          </div>
+        );
+      })}
+    </section>
+  );
+};

apps/docs/src/components/tokens/SpaceTokens.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { HvTypography, useTheme } from "@hitachivantara/uikit-react-core";
+
+import { DocsProvider } from "../code/DocsProvider";
+
+export const SpaceTokens = () => {
+  return (
+    <DocsProvider className="bg-transparent space-y-10">
+      <SpaceTokensInternal />
+    </DocsProvider>
+  );
+};
+
+export const SpaceTokensInternal = () => {
+  const { activeTheme } = useTheme();
+  if (!activeTheme) return null;
+
+  return (
+    <section className="flex flex-wrap gap-xl gap-row-sm w-100% justify-center mt-sm">
+      {Object.entries(activeTheme.space).map(([categoryKey]) => {
+        return (
+          <div className="flex flex-col items-center" key={categoryKey}>
+            <div
+              className="flex"
+              style={{ gap: activeTheme.space[categoryKey] }}
+            >
+              <div className="p-md border-dashed border-1 border-borderStrong bg-bgContainer w-50px h-50px" />
+              <div className="p-md border-dashed border-1 border-borderStrong bg-bgContainer w-50px h-50px" />
+            </div>
+            <HvTypography component="code">{categoryKey}</HvTypography>
+            <HvTypography variant="caption1">
+              {activeTheme.space[categoryKey]}
+            </HvTypography>
+          </div>
+        );
+      })}
+    </section>
+  );
+};

apps/docs/src/components/tokens/TypographyTokens.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { HvTypography, useTheme } from "@hitachivantara/uikit-react-core";
+
+import { DocsProvider } from "../code/DocsProvider";
+
+export const TypographyTokens = () => {
+  return (
+    <DocsProvider className="bg-transparent space-y-10">
+      <TypographyTokensInternal />
+    </DocsProvider>
+  );
+};
+
+const sections = {
+  fontFamily: "fontFamily",
+  fontSizes: "fontSize",
+  fontWeights: "fontWeight",
+  lineHeights: "lineHeight",
+} as const;
+
+export const TypographyTokensInternal = () => {
+  const { activeTheme } = useTheme();
+  if (!activeTheme) return null;
+
+  return (
+    <section className="flex flex-col gap-sm w-100% justify-center mt-sm">
+      {(Object.keys(sections) as Array<keyof typeof sections>).map(
+        (section) => (
+          <section
+            key={section}
+            className="flex flex-col gap-sm w-100% justify-center mt-sm"
+          >
+            <HvTypography variant="title4" className="font-semibold">
+              {section}
+            </HvTypography>
+            <div className="flex gap-lg justify-center w-100% flex-wrap">
+              {Object.entries(activeTheme[section]).map(([categoryKey]) => {
+                const sectionKey = sections[section];
+                return (
+                  <div className="flex gap-md" key={categoryKey}>
+                    <div className="flex flex-col text-align-center">
+                      <span
+                        style={{
+                          [sectionKey]: activeTheme[section][categoryKey],
+                        }}
+                      >
+                        UI Kit
+                      </span>
+                      <code>{categoryKey}</code>
+                      <HvTypography variant="caption1">
+                        {activeTheme[section][categoryKey]}
+                      </HvTypography>
+                    </div>
+                  </div>
+                );
+              })}
+            </div>
+          </section>
+        ),
+      )}
+    </section>
+  );
+};

apps/docs/src/components/tokens/ZIndexTokens.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { HvTypography, useTheme } from "@hitachivantara/uikit-react-core";
+
+import { DocsProvider } from "../code/DocsProvider";
+
+export const ZIndexTokens = () => {
+  return (
+    <DocsProvider className="bg-transparent space-y-10">
+      <ZIndexTokensInternal />
+    </DocsProvider>
+  );
+};
+
+export const ZIndexTokensInternal = () => {
+  const { activeTheme } = useTheme();
+  if (!activeTheme) return null;
+
+  let left = 0;
+  let top = 0;
+
+  return (
+    <section className="flex gap-sm w-100% justify-center mt-sm relative h-420px">
+      {Object.entries(activeTheme.zIndices).map(([categoryKey]) => {
+        left += 10;
+        top += 30;
+
+        return (
+          <div
+            className="absolute border-1 border-dashed border-borderStrong bg-bgContainer w-300px h-50px "
+            style={{ left, top }}
+            key={categoryKey}
+          >
+            <div className="absolute flex top-5px w-100% h-[100%] gap-md justify-center color-text">
+              <HvTypography component="code">{categoryKey}</HvTypography>
+              <HvTypography variant="caption1">
+                {activeTheme.zIndices[categoryKey]}
+              </HvTypography>
+            </div>
+          </div>
+        );
+      })}
+    </section>
+  );
+};

apps/docs/src/content/docs/_meta.ts

@@ -19,11 +19,15 @@ export default {
     type: "separator",
     title: "Foundation",
   },
-  theming: "Theming",
+  "theme-tokens": {
+    title: "Theme Tokens",
+    theme: { layout: "full", toc: false },
+  },
   "color-tokens": {
     title: "Color Tokens",
     theme: { layout: "full", toc: false },
   },
+  theming: "Theming",
   "color-palette": {
     title: "Color Palette",
     theme: { layout: "full", toc: false },

apps/docs/src/content/docs/color-tokens.mdx

@@ -1,16 +1,7 @@
-import { ColorTokens } from "../../components/color/ColorTokens";
+import { ColorTokens } from "../../components/tokens/ColorTokens";
 
 # Color Tokens
 
-Color tokens are the **semantic layer** of the **UI Kit** color system, providing **consistent**, and **themeable** values for UI development.
-They ensure design integrity, maintainability, and seamless alignment between design and implementation.
-
-> [!NOTE]
->
-> Think of color tokens as the handshake between design and development. They
-> keep everyone on the same page — so always use them to ensure things stay
-> consistent and clean.
-
 Color tokens can be accessed through the `theme.colors` object:
 
 ```tsx

apps/docs/src/content/docs/theme-tokens.mdx

@@ -0,0 +1,70 @@
+import { BreakpointTokens } from "../../components/tokens/BreakpointTokens";
+import { RadiiTokens } from "../../components/tokens/RadiiTokens";
+import { SpaceTokens } from "../../components/tokens/SpaceTokens";
+import { TypographyTokens } from "../../components/tokens/TypographyTokens";
+import { ZIndexTokens } from "../../components/tokens/ZIndexTokens";
+
+# UI Kit tokens
+
+UI Kit tokens are the **semantic layer** of the **UI Kit** system, providing **consistent**, and **themeable** values for UI development.
+They ensure design integrity, maintainability, and seamless alignment between design and implementation.
+
+> [!NOTE]
+>
+> Think of UI Kit tokens as the handshake between design and development. They
+> keep everyone on the same page - so always use them to ensure things stay
+> consistent and clean.
+
+UI Kit tokens can be accessed through the `theme` object:
+
+```tsx
+import { theme } from "@hitachivantara/uikit-react-core";
+
+const MyComponent = () => (
+  <div style={{ color: theme.colors.primary }}>
+    This text uses the semantic primary color.
+  </div>
+);
+```
+
+These tokens are categorized into several groups, each serving a specific purpose in the UI Kit design system and can be
+accessed through the `theme` object.
+
+When creating a new theme, you can extend any of the supported themes by overriding these tokens (or adding new ones).
+This allows you to customize the UI Kit to fit your brand or application needs while maintaining the core design principles.
+
+> [!NOTE]
+>
+> Check the [Color tokens page](/docs/color-tokens) for more information on how to use color tokens in your components.
+
+Below is a summary of the available token categories:
+
+## Radii
+
+Accessible through the `theme.radii` object, these tokens define the border radius values used across the UI Kit components.
+
+<RadiiTokens />
+
+## Spacing
+
+Accessible through the `theme.spacing` object, these tokens define the spacing values used for margins, paddings, and gaps in the UI Kit components.
+
+<SpaceTokens />
+
+## ZIndex
+
+Accessible through the `theme.zIndex` object, these tokens define the stacking order of UI Kit components.
+
+<ZIndexTokens />
+
+## Typography
+
+These tokens define the typography styles used in the UI Kit components.
+
+<TypographyTokens />
+
+## Breakpoints
+
+Accessible through the `theme.breakpoints` object, these tokens define the responsive breakpoints used in the UI Kit components.
+
+<BreakpointTokens />