feat(tokens): updated greyscale tokens

.changeset/surface-tokens-update.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/kumo": minor
+---
+
+Adjust semantic color tokens and generated theme output for Kumo surfaces and neutrals with base scales instead of semantic naming. Tokens are determined by their elevation level relative to the base component.
+
+Specific token updates:
+- `bg-kumo-recessed` is updated to `bg-kumo-base-neg-1` and `bg-kumo-base-neg-2`
+- `bg-kumo-elevated` is updated to `bg-kumo-base-1` and `bg-kumo-base-2`

packages/kumo-docs-astro/src/components/SidebarNav.tsx

@@ -100,8 +100,8 @@ declare const __BUILD_COMMIT__: string;
 declare const __BUILD_DATE__: string;
 
 const LI_STYLE =
-  "block rounded-lg text-kumo-strong hover:text-kumo-default hover:bg-kumo-tint p-2 my-[.05rem] cursor-pointer transition-colors no-underline relative z-10";
-const LI_ACTIVE_STYLE = "font-semibold text-kumo-default bg-kumo-tint";
+  "block rounded-lg text-kumo-strong hover:text-kumo-default hover:bg-kumo-base-1 p-2 my-[.05rem] cursor-pointer transition-colors no-underline relative z-10";
+const LI_ACTIVE_STYLE = "font-semibold text-kumo-default bg-kumo-base-1";
 
 interface SidebarNavProps {
   currentPath: string;
@@ -259,7 +259,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       <div className="mb-4">
         <button
           type="button"
-          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint"
+          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-base-1"
           onClick={() => setChartsOpen(!chartsOpen)}
         >
           <span>Charts</span>
@@ -298,7 +298,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
         {/* Blocks Section */}
         <button
           type="button"
-          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-tint"
+          className="flex w-full cursor-pointer items-center justify-between rounded-lg px-2 py-2 text-sm font-medium text-kumo-default transition-colors hover:bg-kumo-base-1"
           onClick={() => setBlocksOpen(!blocksOpen)}
         >
           <span>Blocks</span>
@@ -341,7 +341,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       {/* Mobile header bar with hamburger */}
       <div
         className={cn(
-          "fixed inset-x-0 top-0 z-50 flex h-12 items-center justify-between border-b border-kumo-line bg-kumo-elevated px-3 md:hidden",
+          "fixed inset-x-0 top-0 z-50 flex h-12 items-center justify-between border-b border-kumo-line bg-kumo-canvas px-3 md:hidden",
         )}
       >
         <Button
@@ -359,7 +359,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       {/* Mobile slide-out drawer */}
       <aside
         className={cn(
-          "fixed inset-y-0 left-0 z-50 flex w-72 flex-col border-r border-kumo-line bg-kumo-elevated md:hidden",
+          "fixed inset-y-0 left-0 z-50 flex w-72 flex-col border-r border-kumo-line bg-kumo-canvas md:hidden",
           "transition-transform duration-300 will-change-transform",
           mobileMenuOpen ? "translate-x-0" : "-translate-x-full",
         )}
@@ -388,7 +388,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       {/* Desktop: Left rail that always stays put */}
       <div
         className={cn(
-          "fixed inset-y-0 left-0 z-50 hidden w-12 bg-kumo-elevated md:block",
+          "fixed inset-y-0 left-0 z-50 hidden w-12 bg-kumo-canvas md:block",
           "border-r border-kumo-line",
         )}
       >
@@ -416,7 +416,7 @@ export function SidebarNav({ currentPath }: SidebarNavProps) {
       <aside
         data-sidebar-open={sidebarOpen}
         className={cn(
-          "fixed inset-y-0 left-12 z-40 hidden w-64 flex-col bg-kumo-elevated md:flex",
+          "fixed inset-y-0 left-12 z-40 hidden w-64 flex-col bg-kumo-canvas md:flex",
           "transition-transform duration-300 ease-out will-change-transform",
           sidebarOpen
             ? "translate-x-0 border-r border-kumo-line"

packages/kumo-docs-astro/src/components/demos/HomeGrid.tsx

@@ -325,7 +325,7 @@ export function HomeGrid() {
       name: "Surface",
       id: "surface",
       Component: (
-        <Surface className="flex h-24 w-40 items-center justify-center rounded-lg bg-kumo-base text-sm text-kumo-subtle">
+        <Surface className="flex h-24 w-40 items-center justify-center rounded-lg bg-kumo-canvas text-sm text-kumo-subtle">
           <em>To put things over.</em>
         </Surface>
       ),
@@ -629,7 +629,7 @@ export function HomeGrid() {
         const route = componentRoutes[c.id] || null;
         return (
           <li
-            className="relative flex aspect-square items-center justify-center bg-kumo-surface"
+            className="relative flex aspect-square items-center justify-center bg-kumo-canvas"
             key={c.name}
           >
             {route ? (

packages/kumo-docs-astro/src/components/docs/ComponentPreview.astro

@@ -3,7 +3,7 @@
 ---
 
 <div
-  class="flex min-h-[120px] items-center justify-center rounded-t-lg border border-kumo-line bg-kumo-surface p-6"
+  class="flex min-h-[120px] items-center justify-center rounded-t-lg border border-kumo-line bg-kumo-canvas p-6"
 >
   <slot />
 </div>

packages/kumo/ai/USAGE.md

@@ -26,9 +26,10 @@ import { Button, Input, Dialog } from "@cloudflare/kumo";
 ## Critical Rules
 
 1. **Semantic tokens only** — use `bg-kumo-base`, `text-kumo-default`, etc. Never use raw Tailwind colors (`bg-blue-500`).
-2. **No `dark:` variant** — light/dark mode is handled automatically via CSS `light-dark()`. Never add `dark:` prefixes.
-3. **Merge classes with `cn()`** — import from `@cloudflare/kumo` and use it to combine class names.
-4. **Compound components** — many components use a dot-notation API: `<Dialog.Root>`, `<Dialog.Trigger>`, etc.
+2. **Merge classes with `cn()`** — import from `@cloudflare/kumo` and use it to combine class names.
+3. **Compound components** — many components use a dot-notation API: `<Dialog.Root>`, `<Dialog.Trigger>`, etc.
+
+`dark:` variants are supported in a few components that require different elevation levels between light and dark modes, however using the same variant is highly recommended.
 
 ## Component Quick Reference
 
@@ -87,17 +88,20 @@ import { Button, Input, Dialog } from "@cloudflare/kumo";
 | `text-kumo-brand` | Brand-colored text |
 
 ### Background Colors
+Background colors are determined by elevation levels in relative to the base surface.
+
 | Token | Purpose |
 |-------|---------|
-| `bg-kumo-base` | Page/card background |
-| `bg-kumo-elevated` | Slightly elevated surface |
-| `bg-kumo-overlay` | Overlay/hover background |
+| `bg-kumo-canvas` | Page background |
+| `bg-kumo-base` | Component background |
+| `bg-kumo-elevated` | Slightly elevated surface (legacy; to be replaced with `bg-kumo-base-1` or `bg-kumo-base-2`) |
+| `bg-kumo-overlay` | Overlay background (i.e. for `Combobox` or `Dialog`) |
 | `bg-kumo-contrast` | High-contrast background (inverted) |
-| `bg-kumo-control` | Form control background |
-| `bg-kumo-fill` | Muted fill (borders, badges) |
-| `bg-kumo-fill-hover` | Hover state for fills |
-| `bg-kumo-tint` | Subtle tinted background |
-| `bg-kumo-interact` | Interactive element background |
+| `bg-kumo-ring` | Ring colour |
+| `bg-kumo-control` | Form control background (legacy; to be replaced with `bg-kumo-base`) |
+| `bg-kumo-fill` | Muted fill (borders, badges) (legacy; to be replaced with `bg-kumo-base`) |
+| `bg-kumo-fill-hover` | Hover state for fills (legacy; to be replaced with `bg-kumo-base-1`) |
+| `bg-kumo-tint` | Subtle tinted background (legacy; to be replaced with `bg-kumo-base-1`) ||
 | `bg-kumo-brand` | Brand primary background |
 | `bg-kumo-brand-hover` | Brand hover background |
 | `bg-kumo-danger` | Error/destructive background |

packages/kumo/scripts/theme-generator/config.ts

@@ -53,7 +53,7 @@ export const THEME_CONFIG: ThemeConfig = {
       theme: {
         kumo: {
           light: "var(--color-neutral-500, oklch(55.6% 0 0))",
-          dark: "var(--color-kumo-neutral-50, oklch(97.5% 0 0))",
+          dark: "var(--color-kumo-neutral-75, oklch(97.5% 0 0))",
         },
       },
     },
@@ -128,25 +128,58 @@ export const THEME_CONFIG: ThemeConfig = {
    * CSS variable: --color-{token}
    */
   color: {
+    "kumo-canvas": {
+      newName: "",
+      theme: {
+        kumo: {
+          light: "var(--color-kumo-neutral-25, oklch(98.5% 0 0))",
+          dark: "var(--color-kumo-neutral-1000, oklch(10% 0 0))",
+        },
+        fedramp: {
+          light: "#5b697c",
+          dark: "#5b697c",
+        },
+      },
+    },
+    // to be replaced with kumo-canvas
     "kumo-surface": {
       newName: "",
       theme: {
         kumo: {
-          light: "var(--color-kumo-neutral-25, oklch(99% 0 0))",
-          dark: "var(--color-kumo-neutral-975, oklch(8.5% 0 0))",
+          light: "var(--color-kumo-neutral-50, oklch(98.5% 0 0))",
+          dark: "var(--color-kumo-neutral-950, oklch(10% 0 0))",
         },
         fedramp: {
           light: "#5b697c",
           dark: "#5b697c",
         },
       },
     },
+    "kumo-base-neg-2": {
+      newName: "",
+      theme: {
+        kumo: {
+          light: "var(--color-neutral-125, oklch(96.5% 0 0))",
+          dark: "var(--color-kumo-neutral-975, oklch(12% 0 0))",
+        },
+      },
+    },
+    // to be replaced with kumo-base--2
     "kumo-recessed": {
       newName: "",
       theme: {
         kumo: {
-          light: "var(--color-kumo-neutral-50, oklch(96.5% 0 0))",
-          dark: "var(--color-kumo-neutral-925, oklch(18% 0 0))",
+          light: "var(--color-neutral-50, oklch(97% 0 0))",
+          dark: "var(--color-kumo-neutral-950, oklch(10% 0 0))",
+        },
+      },
+    },
+    "kumo-base-neg-1": {
+      newName: "",
+      theme: {
+        kumo: {
+          light: "var(--color-neutral-50, oklch(98.5% 0 0))",
+          dark: "var(--color-kumo-neutral-950, oklch(15% 0 0))",
         },
       },
     },
@@ -155,23 +188,51 @@ export const THEME_CONFIG: ThemeConfig = {
       theme: {
         kumo: {
           light: "var(--color-white, #fff)",
-          dark: "var(--color-kumo-neutral-850, oklch(22.4% 0 0))",
+          dark: "var(--color-kumo-neutral-925, oklch(17% 0 0))",
         },
         fedramp: {
           light: "#5b697c",
           dark: "#5b697c",
         },
       },
     },
+    // to be replaced with kumo-base-1
     "kumo-tint": {
       newName: "",
       theme: {
         kumo: {
-          light: "var(--color-kumo-neutral-75, oklch(96.7% 0 0))",
+          light: "var(--color-neutral-100, oklch(97% 0 0))",
           dark: "var(--color-kumo-neutral-800, oklch(26.9% 0 0))",
         },
       },
     },
+    "kumo-base-1": {
+      newName: "",
+      theme: {
+        kumo: {
+          light: "var(--color-neutral-100, oklch(97% 0 0))",
+          dark: "var(--color-kumo-neutral-850, oklch(24% 0 0))",
+        },
+      },
+    },
+    "kumo-base-2": {
+      newName: "",
+      theme: {
+        kumo: {
+          light: "var(--color-kumo-neutral-125, oklch(95% 0 0))",
+          dark: "var(--color-neutral-700, oklch(37.1% 0 0))",
+        },
+      },
+    },
+    "kumo-overlay": {
+      newName: "",
+      theme: {
+        kumo: {
+          light: "var(--color-kumo-neutral-450, oklch(89% 0 0))",
+          dark: "var(--color-neutral-700, oklch(37.1% 0 0))",
+        },
+      },
+    },
     "kumo-contrast": {
       newName: "",
       theme: {
@@ -194,15 +255,6 @@ export const THEME_CONFIG: ThemeConfig = {
         },
       },
     },
-    "kumo-overlay": {
-      newName: "",
-      theme: {
-        kumo: {
-          light: "var(--color-kumo-neutral-50, oklch(97.5% 0 0))",
-          dark: "var(--color-neutral-800, oklch(26.9% 0 0))",
-        },
-      },
-    },
     "kumo-control": {
       newName: "",
       theme: {
@@ -270,7 +322,7 @@ export const THEME_CONFIG: ThemeConfig = {
       newName: "",
       theme: {
         kumo: {
-          light: "var(--color-kumo-neutral-150, oklch(93.5% 0 0))",
+          light: "var(--color-kumo-neutral-150, oklch(95% 0 0))",
           dark: "var(--color-neutral-700, oklch(37.1% 0 0))",
         },
         fedramp: {

packages/kumo/src/components/combobox/combobox.tsx

@@ -344,7 +344,7 @@ function Item({ children, ...props }: ComboboxBase.Item.Props) {
   return (
     <ComboboxBase.Item
       {...props}
-      className="group mx-1.5 grid cursor-pointer grid-cols-[1fr_16px] gap-2 rounded px-2 py-1.5 text-base data-highlighted:bg-kumo-tint"
+      className="group mx-1.5 grid cursor-pointer grid-cols-[1fr_16px] gap-2 rounded px-2 py-1.5 text-base data-highlighted:bg-kumo-base-1"
     >
       <div className="col-start-1">{children}</div>
       <ComboboxBase.ItemIndicator className="col-start-2 flex items-center">
@@ -423,14 +423,14 @@ function Chip(props: ComboboxBase.Chip.Props) {
         "flex items-center gap-2.5", // Layout
         "h-6 pl-2 pr-[3px]", // Dimensions
         "rounded-sm ring-1 ring-kumo-line", // Border
-        "bg-kumo-overlay", // Background
+        "bg-kumo-base", // Background
         "text-sm", // Typography
       )}
     >
       {props.children}
       <ComboboxBase.ChipRemove
         className={cn(
-          "cursor-pointer rounded-md p-1 hover:bg-kumo-fill-hover",
+          "cursor-pointer rounded-md p-1 hover:bg-kumo-base-1",
           "bg-transparent flex",
         )}
       >

packages/kumo/src/components/command-palette/command-palette.tsx

@@ -336,7 +336,7 @@ function Item<T>({
       onClick={onClick}
       className={cn(
         "group flex w-full items-center gap-3 px-2 py-1.5 text-left text-base transition-colors",
-        "cursor-pointer data-[highlighted]:bg-kumo-overlay",
+        "cursor-pointer data-[highlighted]:bg-kumo-base-1",
         "rounded-lg",
         disabled && "cursor-default opacity-50",
         className,
@@ -383,7 +383,7 @@ function Loading({ children }: CommandPaletteLoadingProps) {
  */
 function Footer({ children }: CommandPaletteFooterProps) {
   return (
-    <div className="flex items-center justify-between rounded-b-lg bg-kumo-elevated px-4 py-3 text-xs text-kumo-strong">
+    <div className="flex items-center justify-between rounded-b-lg bg-kumo-base-1 px-4 py-3 text-xs text-kumo-strong">
       {children}
     </div>
   );
@@ -479,7 +479,7 @@ function ResultItem<T>({
         "group flex w-full items-center gap-3 rounded-lg px-2 py-1.5 text-left transition-colors",
         nonInteractive
           ? "cursor-default"
-          : "cursor-pointer data-[highlighted]:bg-kumo-overlay",
+          : "cursor-pointer data-[highlighted]:bg-kumo-base-1",
       )}
     >
       {icon && (
@@ -540,7 +540,7 @@ function Container({
   return (
     <div
       className={cn(
-        "flex max-h-[60vh] flex-col overflow-hidden rounded-lg bg-kumo-elevated",
+        "flex max-h-[60vh] flex-col overflow-hidden rounded-lg bg-kumo-base-neg-1",
         className,
       )}
     >