From 7c1f6cc6339ed40494d73bb9a81ad157fa93e8c0 Mon Sep 17 00:00:00 2001
From: Gabriel Dugny <gabriel.dugny@believe.com>
Date: Thu, 8 Jan 2026 12:05:40 +0100
Subject: [PATCH] feat: support surfaces

Signed-off-by: Gabriel Dugny <gabriel.dugny@believe.com>
---
 docs-ui/src/content/toggle-button.props.ts    |  6 ++
 packages/ui/report.api.md                     |  1 +
 .../ToggleButton/ToggleButton.module.css      | 64 +++++++++++++++----
 .../components/ToggleButton/ToggleButton.tsx  |  7 +-
 .../ui/src/components/ToggleButton/types.ts   |  3 +
 5 files changed, 69 insertions(+), 12 deletions(-)

diff --git a/docs-ui/src/content/toggle-button.props.ts b/docs-ui/src/content/toggle-button.props.ts
index 71625e7e6f..31acd558c7 100644
--- a/docs-ui/src/content/toggle-button.props.ts
+++ b/docs-ui/src/content/toggle-button.props.ts
@@ -17,6 +17,12 @@ export const toggleButtonPropDefs: Record<string, PropDef> = {
     default: 'small',
     responsive: true,
   },
+  onSurface: {
+    type: 'enum',
+    values: ['0', '1', '2', '3', 'danger', 'warning', 'success', 'auto'],
+    description: 'Surface level this toggle is placed on',
+    responsive: true,
+  },
   iconStart: { type: 'enum', values: ['ReactNode'] },
   iconEnd: { type: 'enum', values: ['ReactNode'] },
   isSelected: { type: 'boolean' },
diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md
index bc339b4026..56b716ea94 100644
--- a/packages/ui/report.api.md
+++ b/packages/ui/report.api.md
@@ -1865,6 +1865,7 @@ export interface ToggleButtonProps extends ToggleButtonProps_2 {
   iconEnd?: ReactElement;
   // (undocumented)
   iconStart?: ReactElement;
+  onSurface?: Responsive<Surface>;
   // (undocumented)
   size?: 'small' | 'medium' | Partial<Record<Breakpoint, 'small' | 'medium'>>;
   // (undocumented)
diff --git a/packages/ui/src/components/ToggleButton/ToggleButton.module.css b/packages/ui/src/components/ToggleButton/ToggleButton.module.css
index ad3b173f04..f11c8bac45 100644
--- a/packages/ui/src/components/ToggleButton/ToggleButton.module.css
+++ b/packages/ui/src/components/ToggleButton/ToggleButton.module.css
@@ -36,9 +36,57 @@
   }
 
   .bui-ToggleButton[data-variant='secondary'] {
-    background: transparent;
+    background-color: var(--bui-bg-neutral-on-surface-0);
     color: var(--bui-fg-primary);
-    box-shadow: inset 0 0 0 1px var(--bui-border);
+    box-shadow: none;
+
+    &[data-hovered]:not([data-disabled]) {
+      background-color: var(--bui-bg-neutral-on-surface-0-hover);
+    }
+
+    &[data-pressed]:not([data-disabled]),
+    &[data-selected]:not([data-disabled]) {
+      background-color: var(--bui-bg-neutral-on-surface-0-pressed);
+    }
+
+    &[data-on-surface='1'] {
+      background-color: var(--bui-bg-neutral-on-surface-1);
+
+      &[data-hovered]:not([data-disabled]) {
+        background-color: var(--bui-bg-neutral-on-surface-1-hover);
+      }
+
+      &[data-pressed]:not([data-disabled]),
+      &[data-selected]:not([data-disabled]) {
+        background-color: var(--bui-bg-neutral-on-surface-1-pressed);
+      }
+    }
+
+    &[data-on-surface='2'] {
+      background-color: var(--bui-bg-neutral-on-surface-2);
+
+      &[data-hovered]:not([data-disabled]) {
+        background-color: var(--bui-bg-neutral-on-surface-2-hover);
+      }
+
+      &[data-pressed]:not([data-disabled]),
+      &[data-selected]:not([data-disabled]) {
+        background-color: var(--bui-bg-neutral-on-surface-2-pressed);
+      }
+    }
+
+    &[data-on-surface='3'] {
+      background-color: var(--bui-bg-neutral-on-surface-3);
+
+      &[data-hovered]:not([data-disabled]) {
+        background-color: var(--bui-bg-neutral-on-surface-3-hover);
+      }
+
+      &[data-pressed]:not([data-disabled]),
+      &[data-selected]:not([data-disabled]) {
+        background-color: var(--bui-bg-neutral-on-surface-3-pressed);
+      }
+    }
   }
 
   .bui-ToggleButton[data-variant='primary'][data-selected],
@@ -51,21 +99,15 @@
     background: var(--bui-bg-surface-2);
   }
 
-  .bui-ToggleButton[data-variant='secondary'][data-selected],
-  .bui-ToggleButton[data-variant='secondary'][data-pressed] {
-    background: var(--bui-bg-surface-2);
-    box-shadow: inset 0 0 0 1px var(--bui-border-hover);
-  }
-
   .bui-ToggleButton[data-focus-visible] {
-    outline: 2px solid var(--bui-ring);
-    outline-offset: 2px;
+    outline: none;
+    box-shadow: inset 0 0 0 2px var(--bui-ring);
   }
 
   .bui-ToggleButton[data-disabled] {
     cursor: not-allowed;
     color: var(--bui-fg-disabled);
-    background: var(--bui-bg-disabled);
+    background: var(--bui-bg-neutral-on-surface-0-disabled);
     box-shadow: inset 0 0 0 1px var(--bui-border-disabled);
   }
 
diff --git a/packages/ui/src/components/ToggleButton/ToggleButton.tsx b/packages/ui/src/components/ToggleButton/ToggleButton.tsx
index e688b29c96..211ff03b6d 100644
--- a/packages/ui/src/components/ToggleButton/ToggleButton.tsx
+++ b/packages/ui/src/components/ToggleButton/ToggleButton.tsx
@@ -21,6 +21,7 @@ import type { ToggleButtonProps } from './types';
 import { useStyles } from '../../hooks/useStyles';
 import { ToggleButtonDefinition } from './definition';
 import styles from './ToggleButton.module.css';
+import { useSurface } from '../../hooks/useSurface';
 
 /** @public */
 export const ToggleButton = forwardRef(
@@ -34,13 +35,17 @@ export const ToggleButton = forwardRef(
       },
     );
 
-    const { children, className, iconStart, iconEnd, ...rest } = cleanedProps;
+    const { children, className, iconStart, iconEnd, onSurface, ...rest } =
+      cleanedProps;
+
+    const { surface } = useSurface({ onSurface });
 
     return (
       <AriaToggleButton
         className={clsx(classNames.root, styles[classNames.root], className)}
         ref={ref}
         {...dataAttributes}
+        {...(typeof surface === 'string' ? { 'data-on-surface': surface } : {})}
         {...rest}
       >
         <span
diff --git a/packages/ui/src/components/ToggleButton/types.ts b/packages/ui/src/components/ToggleButton/types.ts
index 9bffb72c83..bf6c08f521 100644
--- a/packages/ui/src/components/ToggleButton/types.ts
+++ b/packages/ui/src/components/ToggleButton/types.ts
@@ -17,6 +17,7 @@
 import type { Breakpoint } from '../..';
 import type { ReactElement, ReactNode } from 'react';
 import type { ToggleButtonProps as AriaToggleButtonProps } from 'react-aria-components';
+import type { Responsive, Surface } from '../../types';
 
 /**
  * Properties for {@link ToggleButton}
@@ -32,4 +33,6 @@ export interface ToggleButtonProps extends AriaToggleButtonProps {
   iconStart?: ReactElement;
   iconEnd?: ReactElement;
   children?: ReactNode;
+  /** Surface the toggle button is placed on. Defaults to context surface if available */
+  onSurface?: Responsive<Surface>;
 }