Skip to content

feat(tokens): updated greyscale surface tokens #326

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
geoquant merged 5 commits into from
Mar 30, 2026
Merged

feat(tokens): updated greyscale surface tokens #326

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0540025
feat(tokens): updated greyscale surface tokens
najlaskr Mar 27, 2026
10ffe90
fix(tabs): ring opacity in dark mode
najlaskr Mar 27, 2026
3e38481
fix(sidebarNav): updated hover state
najlaskr Mar 27, 2026
672eded
Merge branch 'main' into greyscale-tokens
najlaskr Mar 27, 2026
4c8682b
Merge branch 'main' into greyscale-tokens
najlaskr Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .changeset/color-surface-token-refresh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
"@cloudflare/kumo": minor
---

Refresh semantic surface color tokens and component surface usage.

- Add and adopt `kumo-canvas` as the page-level surface token in theme output and docs usage.
- Rebalance neutral token values in `kumo-binding.css` and generated theme variables for improved light/dark surface hierarchy.
- Update surface-related component styling (`LayerCard`, `MenuBar`, `Tabs`) to align with the refreshed `canvas`/`elevated`/`recessed` layering model.
- Update token usage guidance in `ai/USAGE.md` to reflect page vs component background roles.
2 changes: 1 addition & 1 deletion packages/kumo-docs-astro/src/components/Header.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ const kumoVersion =
---

<header
class="sticky top-0 z-10 h-12 border-b border-kumo-line bg-kumo-elevated hidden md:flex"
class="sticky top-0 z-10 h-12 border-b border-kumo-line bg-kumo-canvas hidden md:flex"
>
<div
class="flex min-w-0 flex-1 items-center justify-end border-r border-kumo-line px-4"
Expand Down
8 changes: 4 additions & 4 deletions packages/kumo-docs-astro/src/components/SidebarNav.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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",
)}
Expand Down Expand Up @@ -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 ated md:block",
"border-r border-kumo-line",
)}
>
Expand Down Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions packages/kumo-docs-astro/src/components/demos/HomeGrid.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
),
Expand Down Expand Up @@ -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 ? (
Expand Down
2 changes: 1 addition & 1 deletion packages/kumo-docs-astro/src/components/docs/ComponentPreview.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ const { class: className, ...rest } = Astro.props;

<div
class:list={[
"flex min-h-[120px] items-center justify-center rounded-t-lg border border-kumo-line bg-kumo-surface p-6",
"flex min-h-[120px] items-center justify-center rounded-t-lg border border-kumo-line bg-kumo-canvas p-6",
className,
]}
{...rest}
Expand Down
2 changes: 1 addition & 1 deletion packages/kumo-docs-astro/src/layouts/BaseLayout.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ const buildDate = typeof __BUILD_DATE__ !== "undefined" ? __BUILD_DATE__ : new D
---

<!doctype html>
<html class="bg-kumo-elevated" lang="en">
<html class="bg-kumo-canvas" lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
Expand Down
4 changes: 2 additions & 2 deletions packages/kumo-docs-astro/src/styles/global.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ html {
--tw-prose-kbd-shadows: transparent;
--tw-prose-code: var(--color-kumo-default);
--tw-prose-pre-code: var(--color-kumo-default);
--tw-prose-pre-bg: var(--color-kumo-recessed);
--tw-prose-pre-bg: var(--color-kumo-canvas);
--tw-prose-th-borders: var(--color-kumo-line);
--tw-prose-td-borders: var(--color-kumo-line);

Expand All @@ -65,7 +65,7 @@ html {
--tw-prose-invert-kbd-shadows: transparent;
--tw-prose-invert-code: var(--color-kumo-default);
--tw-prose-invert-pre-code: var(--color-kumo-default);
--tw-prose-invert-pre-bg: var(--color-kumo-recessed);
--tw-prose-invert-pre-bg: var(--color-kumo-canvas);
--tw-prose-invert-th-borders: var(--color-kumo-line);
--tw-prose-invert-td-borders: var(--color-kumo-line);
}
Expand Down
4 changes: 3 additions & 1 deletion packages/kumo/ai/USAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,10 @@ import { Button, Input, Dialog } from "@cloudflare/kumo";
### Background Colors
| Token | Purpose |
|-------|---------|
| `bg-kumo-base` | Page/card background |
| `bg-kumo-surface` | Page background |
| `bg-kumo-base` | Component background |
| `bg-kumo-elevated` | Slightly elevated surface |
| `bg-kumo-recessed` | Recessed surface with a darker colour |
| `bg-kumo-overlay` | Overlay/hover background |
| `bg-kumo-contrast` | High-contrast background (inverted) |
| `bg-kumo-control` | Form control background |
Expand Down
42 changes: 19 additions & 23 deletions packages/kumo/scripts/theme-generator/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,25 +222,34 @@ export const THEME_CONFIG: ThemeConfig = {
* CSS variable: --color-{token}
*/
color: {
"kumo-surface": {
"kumo-canvas": {
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-25, oklch(98.75% 0 0))",
dark: "var(--color-kumo-neutral-1000, oklch(10% 0 0))",
},
fedramp: {
light: "#5b697c",
dark: "#5b697c",
},
},
},
"kumo-elevated": {
newName: "",
theme: {
kumo: {
light: "var(--color-kumo-neutral-75, oklch(98% 0 0))",
dark: "var(--color-kumo-neutral-975, oklch(12% 0 0))",
},
},
},
"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-kumo-neutral-125, oklch(96% 0 0))",
dark: "var(--color-kumo-neutral-950, oklch(12% 0 0))",
},
},
},
Expand All @@ -249,7 +258,7 @@ 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",
Expand All @@ -261,7 +270,7 @@ export const THEME_CONFIG: ThemeConfig = {
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))",
},
},
Expand All @@ -271,20 +280,7 @@ export const THEME_CONFIG: ThemeConfig = {
theme: {
kumo: {
light: "var(--color-kumo-neutral-975, oklch(8.5% 0 0))",
dark: "var(--color-kumo-neutral-25, oklch(99% 0 0))",
},
},
},
/**
* TO DEPRECIATE
* In an effort to reduce the amount of greyscale tokens used in Kumo & Stratus, these tokens will be replaced and depreciated
*/
"kumo-elevated": {
newName: "",
theme: {
kumo: {
light: "var(--color-kumo-neutral-25, oklch(98.5% 0 0))",
dark: "var(--color-neutral-950, oklch(14.5% 0 0))",
dark: "var(--color-kumo-neutral-25, oklch(98.5% 0 0))",
},
},
},
Expand Down Expand Up @@ -328,8 +324,8 @@ export const THEME_CONFIG: ThemeConfig = {
newName: "",
theme: {
kumo: {
light: "var(--color-neutral-200, oklch(92.2% 0 0))",
dark: "var(--color-neutral-700, oklch(37.1% 0 0))",
light: "var(--color-kumo-neutral-125, oklch(96.5% 0 0))",
dark: "var(--color-neutral-800, oklch(37.1% 0 0))",
},
},
},
Expand Down
2 changes: 1 addition & 1 deletion packages/kumo/src/components/layer-card/layer-card.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ function LayerCardSecondary({ children, className }: LayerCardProps) {
return (
<div
className={cn(
"flex items-center gap-2 p-4 text-base font-medium text-kumo-strong -my-2 bg-kumo-recessed",
"flex items-center gap-2 p-4 text-base font-medium text-kumo-strong -my-2 bg-kumo-elevated",
className,
)}
>
Expand Down
6 changes: 3 additions & 3 deletions packages/kumo/src/components/menubar/menubar.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ export interface KumoMenuBarVariantsProps {}
export function menuBarVariants(_props: KumoMenuBarVariantsProps = {}) {
return cn(
// Base styles
"flex rounded-lg border border-kumo-fill bg-kumo-fill pl-px shadow-xs transition-colors",
"flex rounded-lg border border-kumo-recessed bg-kumo-recessed pl-px shadow-xs transition-colors",
);
}

Expand Down Expand Up @@ -46,7 +46,7 @@ const MenuOption = ({
<Tooltip content={tooltip} asChild>
<button
className={cn(
"focus:inset-ring-focus relative -ml-px flex h-full w-11 cursor-pointer items-center justify-center rounded-md border-none bg-kumo-fill first:rounded-l-lg last:rounded-r-lg transition-colors focus:z-1 focus:outline-none focus-visible:z-1 focus-visible:inset-ring-[0.5]",
"focus:inset-ring-focus relative -ml-px flex h-full w-11 cursor-pointer items-center justify-center rounded-md border-none bg-kumo-recessed first:rounded-l-lg last:rounded-r-lg transition-colors focus:z-1 focus:outline-none focus-visible:z-1 focus-visible:inset-ring-[0.5]",
{
"z-2 bg-kumo-base shadow-xs transition-colors": isActive === id,
},
Expand Down Expand Up @@ -118,7 +118,7 @@ export const MenuBar = ({
return (
<nav
className={cn(
"isolate flex rounded-lg border border-kumo-fill bg-kumo-fill pl-px shadow-xs transition-colors",
"isolate flex rounded-lg border border-kumo-fill bg-kumo-recessed pl-px shadow-xs transition-colors",
className,
)}
ref={menuRef}
Expand Down
4 changes: 2 additions & 2 deletions packages/kumo/src/components/tabs/tabs.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,13 +151,13 @@ export function Tabs({
>
{/* Background element for segmented variant */}
{isSegmented && (
<div className="absolute inset-x-0 top-1/2 z-0 h-9 -translate-y-1/2 rounded-lg bg-kumo-surface" />
<div className="absolute inset-x-0 top-1/2 z-0 h-9 -translate-y-1/2 rounded-lg bg-kumo-recessed" />
)}
<TabsPrimitive.List
activateOnFocus={activateOnFocus}
className={cn(
"scrollbar-hide relative flex min-w-0 shrink items-stretch",
isSegmented && "h-9 rounded-lg bg-kumo-recessed px-0.5",
isSegmented && "h-9 rounded-lg bg-kumo-recessed px-0.5 ring ring-kumo-line/70",
isUnderline && "h-7 gap-4 border-b border-kumo-ring pb-2",
listClassName,
)}
Expand Down
17 changes: 9 additions & 8 deletions packages/kumo/src/styles/kumo-binding.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,15 @@
--color-blue-400: oklch(70.7% 0.165 254.624);
--color-blue-800: oklch(42.4% 0.199 265.638);

--color-kumo-neutral-25: oklch(99% 0 0);
--color-kumo-neutral-50: oklch(96.5% 0 0);
--color-kumo-neutral-75: oklch(95.7% 0 0);
--color-kumo-neutral-150: oklch(93.5% 0 0);
--color-kumo-neutral-450: oklch(86% 0 0);
--color-kumo-neutral-850: oklch(22.4% 0 0);
--color-kumo-neutral-925: oklch(18% 0 0);
--color-kumo-neutral-975: oklch(8.5% 0 0);
--color-kumo-neutral-50: oklch(98.75% 0 0);
--color-kumo-neutral-75: oklch(98% 0 0);
--color-kumo-neutral-125: oklch(96.5% 0 0);
--color-kumo-neutral-450: oklch(89% 0 0);
--color-kumo-neutral-850: oklch(24% 0 0);
--color-kumo-neutral-925: oklch(17% 0 0);
--color-kumo-neutral-950: oklch(15% 0 0);
--color-kumo-neutral-975: oklch(12% 0 0);
--color-kumo-neutral-1000: oklch(10% 0 0);
}

/* Typography is now generated in theme-kumo.css via codegen:themes */
Expand Down
6 changes: 3 additions & 3 deletions packages/kumo/src/styles/theme-fedramp.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@

@layer base {
[data-theme="fedramp"] {
--color-kumo-surface: light-dark(
--color-kumo-canvas: light-dark(
#5b697c,
#5b697c
);
Expand All @@ -26,13 +26,13 @@

@layer base {
[data-theme="fedramp"] {
--color-kumo-surface: #5b697c;
--color-kumo-canvas: #5b697c;
--color-kumo-base: #5b697c;
--color-kumo-ring: #c8d4e5;
}

[data-mode="dark"] [data-theme="fedramp"], [data-theme="fedramp"][data-mode="dark"], [data-theme="fedramp"] [data-mode="dark"] {
--color-kumo-surface: #5b697c;
--color-kumo-canvas: #5b697c;
--color-kumo-base: #5b697c;
--color-kumo-ring: #c8d4e5;
}
Expand Down
Loading
Loading