@@ -146,6 +146,22 @@ export async function writePageTocPreview(site: SiteConfig) {
   </TabPane>
 </Tabs>
 
+## From site config
+
+The table of contents the doc layout renders takes its tone, variant and extra classes from the `pageToc` section of `siteConfig.json`. A page can still override the tone with `layout.tocTone` in its frontmatter.
+
+```json
+{
+  "pageToc": {
+    "tone": "neutral",
+    "variant": "surfaceAlt",
+    "class": "spotlight-from-top-right"
+  }
+}
+```
+
+The panel keeps its own rounded corners whatever the variant, and drops its border when it collapses to a rail.
+
 ## Behavior and accessibility
 
 The default doc template already renders the page TOC; do not add a second copy to a normal guide. A sole h1 outline root is omitted so the list starts at its children. The template renders top-level entries and one nested level. Panel controls belong to the standard doc layout.
@@ -161,6 +177,8 @@ The default doc template already renders the page TOC; do not add a second copy
   <a href="#page-toc-prop-items">items</a>
   <a href="#page-toc-prop-title">title</a>
   <a href="#page-toc-prop-tone">tone</a>
+  <a href="#page-toc-prop-variant">variant</a>
+  <a href="#page-toc-prop-variantMode">variantMode</a>
 </nav>
 
 <ApiProperty anchor="page-toc-prop-items" name="items" valueType="PageOutlineItem[]" defaultValue="context.outline">
@@ -171,10 +189,18 @@ The default doc template already renders the page TOC; do not add a second copy
   <p>Trimmed visible panel title. Empty text uses the default.</p>
 </ApiProperty>
 
-<ApiProperty anchor="page-toc-prop-tone" name="tone" valueType="SemanticTone" defaultValue="inherited">
+<ApiProperty anchor="page-toc-prop-tone" name="tone" valueType="RefOrValue&lt;SemanticTone&gt;" defaultValue="inherited">
   <p>Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.</p>
 </ApiProperty>
 
+<ApiProperty anchor="page-toc-prop-variant" name="variant" valueType="RefOrValue&lt;ComponentVariant&gt;" defaultValue="flat">
+  <p>Visual treatment of the panel. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none. The panel keeps its own rounded corners whatever the variant.</p>
+</ApiProperty>
+
+<ApiProperty anchor="page-toc-prop-variantMode" name="variantMode" valueType="RefOrValue&lt;ComponentVariantMode&gt;" defaultValue="stateless">
+  <p>Use stateless for the contents panel; stateful enables the treatment’s hover and active styles on the whole panel. Links keep their own hover and active styles either way.</p>
+</ApiProperty>
+
 ### Composition
 
 <div class="api-contract">
 
@@ -43,6 +43,10 @@ export interface DocLayoutConfig {
 export interface PageTocConfig {
   enabled: boolean
   tone: SemanticTone
+  /** Treatment of the table of contents panel, such as flat, surfaceAlt or glass. */
+  variant?: string
+  /** Extra classes for the table of contents panel. */
+  class?: string
 }
 
 export interface AuthConfig {
 
@@ -0,0 +1,47 @@
+import { ensureDomGlobals } from '@purestack/ts-minidom'
+import { renderApp } from '@purestack/ts-render'
+import { getSvgIcon } from '@purestack/ts-svg-icons'
+import { describe, expect, it } from 'vitest'
+import { createTestContext } from '../../test/testContext'
+import { defineButtonComponents } from '../btn/btn'
+import { defineIconComponents } from '../icon/icon'
+import { definePageTocComponents } from './pageToc'
+
+function renderPageToc(template: string) {
+  const cleanup = ensureDomGlobals()
+  const html = renderApp(template, {
+    components: {
+      ...defineButtonComponents(),
+      ...defineIconComponents(getSvgIcon),
+      ...definePageTocComponents(),
+    },
+    context: createTestContext({
+      outline: [{ id: 'intro', title: 'Intro', depth: 2 }],
+    }),
+  })
+  cleanup()
+  return html.match(/<nav class="([^"]*)"/)?.[1].split(' ') ?? []
+}
+
+describe('PageToc rendering', () => {
+  it('renders a stateless flat panel by default', () => {
+    const classes = renderPageToc(`<PageToc/>`)
+
+    expect(classes).toContain('page-toc')
+    expect(classes).toContain('tone-fill-flat')
+    expect(classes).toContain('tone-border-surface')
+    expect(classes).not.toContain('tone-fill-flat-hover')
+  })
+
+  it('accepts tone, variant, variant mode and extra classes', () => {
+    const classes = renderPageToc(
+      `<PageToc tone="accent" variant="glass" variantMode="stateful" class="spotlight-from-top-right"/>`,
+    )
+
+    expect(classes).toContain('tone-fill-glass')
+    expect(classes).toContain('tone-fill-glass-hover')
+    expect(classes).toContain('tone--accent')
+    expect(classes).toContain('spotlight-from-top-right')
+    expect(classes).not.toContain('tone-fill-flat')
+  })
+})
@@ -1,23 +1,39 @@
 import type { PageOutlineItem, TsSsgContext } from '@purestack/ts-common'
 import { resolveTsSsgContext } from '@purestack/ts-common'
-import { getSemanticToneClass, type SemanticTone } from '@purestack/ts-style'
-import { type ComputedRef, computed, defineComponent, html } from 'regor'
+import type { SemanticTone } from '@purestack/ts-style'
+import {
+  type ComputedRef,
+  computed,
+  defineComponent,
+  html,
+  type RefOrValue,
+} from 'regor'
+import {
+  type ComponentVariant,
+  type ComponentVariantMode,
+  resolveComponentClasses,
+} from '../componentVariant'
 
 export interface PageToc {
   items?: PageOutlineItem[]
   title?: string
-  tone?: SemanticTone
-  toneClass?: ComputedRef<string>
+  tone?: RefOrValue<SemanticTone>
+  variant?: RefOrValue<ComponentVariant>
+  variantMode?: RefOrValue<ComponentVariantMode>
+  classes?: ComputedRef<string>
 }
 
+const DEFAULT_PAGE_TOC_VARIANT: ComponentVariant = 'flat'
+const DEFAULT_PAGE_TOC_VARIANT_MODE: ComponentVariantMode = 'stateless'
+
 export interface PageTocItem extends PageOutlineItem {
   href: string
   children?: PageTocItem[]
 }
 
 const pageTocTemplate = html`<nav
-  class="page-toc tone-fill-flat tone-border-surface tone-text-surface"
-  :class="toneClass"
+  class="page-toc"
+  :class="classes"
   aria-label="On this page"
 >
   <button
@@ -115,13 +131,17 @@ function resolveTitle(props: PageToc) {
 
 function definePageTocComponent() {
   return defineComponent<PageToc>(pageTocTemplate, {
-    props: ['items', 'title', 'tone'],
+    props: ['items', 'title', 'tone', 'variant', 'variantMode'],
     context: (head) => {
       const context = resolveTsSsgContext(head)
-      const tone = head.props.tone
       return {
         title: resolveTitle(head.props),
-        toneClass: computed(() => getSemanticToneClass(tone)),
+        classes: computed(() =>
+          resolveComponentClasses(head.props, {
+            defaultVariant: DEFAULT_PAGE_TOC_VARIANT,
+            defaultVariantMode: DEFAULT_PAGE_TOC_VARIANT_MODE,
+          }),
+        ),
         items: resolveItems(head.props, context),
       }
     },
 
@@ -28,7 +28,7 @@ export function registerPageTocShellStyles(
     .display('block')
     .marginLeft(docLayoutVar('activeShellPaddingInlineEnd'))
     .padding('1em')
-    .borderRadius(palette.radii.lg)
+    .borderRadius(`${palette.radii.lg} !important`)
     .border('1px solid transparent')
     .apply(palette.applyFont(palette.font.size.body))
     .maxHeight(`calc(100vh - ${docLayoutVar('sidebarTop')} - 1.5625rem)`)
@@ -276,7 +276,7 @@ function registerPageTocMobileOverlayStyles(
     )
     .media(mediaMax(BREAKPOINTS.toc))
     .background('transparent')
-    .border('none')
+    .border('none !important')
     .boxShadow('none')
 
   styleBuilder
@@ -349,7 +349,7 @@ function registerPageTocDesktopCollapsedStyles(theme: ThemeMode) {
     .select('.page-toc', theme)
     .media(mediaBelow(BREAKPOINTS.md))
     .marginInlineStart('0')
-    .borderRadius('0')
+    .borderRadius('0 !important')
   styleBuilder
     .select(
       '.template-doc--toc-collapsed .doc-toc:not(.doc-toc--open) .page-toc__header, .template-doc--toc-collapsed .doc-toc:not(.doc-toc--open) .page-toc__restore-toggle, .template-doc--toc-collapsed .doc-toc:not(.doc-toc--open) .page-toc__list, .template-doc--toc-collapsed .doc-toc:not(.doc-toc--open) .page-toc__empty',
@@ -366,7 +366,7 @@ function registerPageTocDesktopCollapsedStyles(theme: ThemeMode) {
     .marginLeft('0')
     .padding('0')
     .background('transparent')
-    .border('none')
-    .borderRadius('0')
+    .border('none !important')
+    .borderRadius('0 !important')
     .overflow('visible')
 }
@@ -438,6 +438,35 @@
           ],
           "description": "Page table-of-contents semantic tone.",
           "default": "neutral"
+        },
+        "variant": {
+          "type": "string",
+          "enum": [
+            "solid",
+            "surface",
+            "surfaceAlt",
+            "spotlight",
+            "glass",
+            "flat",
+            "flatAlt",
+            "flatSolid",
+            "outlineFill",
+            "outline",
+            "subtle",
+            "subtleBtn",
+            "link",
+            "sheen",
+            "underline",
+            "rail",
+            "bracket",
+            "none"
+          ],
+          "description": "Page table-of-contents treatment. The panel keeps its own rounded corners whatever the variant.",
+          "default": "flat"
+        },
+        "class": {
+          "type": "string",
+          "description": "Extra classes for the page table of contents, such as spotlight-from-top-right."
         }
       }
     },
 
@@ -370,6 +370,41 @@ describe('renderPage consent integration', () => {
     expect(html).toContain('<nav-menu tone="neutral">')
   })
 
+  it('passes the configured page toc variant and class to the page toc', async () => {
+    const site = resolveSiteConfig({
+      rootDir: process.cwd(),
+      pageToc: { variant: ' surfaceAlt ', class: 'spotlight-from-top-right' },
+    })
+    const html = await renderPage({
+      bodyHtml: '<h2 id="intro">Intro</h2>',
+      pageInfo: {
+        relPath: 'index.md',
+        urlPath: '/',
+        frontmatter: normalizeFrontmatter({ layout: { showToc: true } }),
+      },
+      outline: [{ id: 'intro', title: 'Intro', depth: 2 }],
+      site,
+    })
+    expect(html).toContain(
+      '<page-toc tone="neutral" variant="surfaceAlt" class="spotlight-from-top-right">',
+    )
+  })
+
+  it('leaves the page toc on its own variant when none is configured', async () => {
+    const site = resolveSiteConfig({ rootDir: process.cwd() })
+    const html = await renderPage({
+      bodyHtml: '<h2 id="intro">Intro</h2>',
+      pageInfo: {
+        relPath: 'index.md',
+        urlPath: '/',
+        frontmatter: normalizeFrontmatter({ layout: { showToc: true } }),
+      },
+      outline: [{ id: 'intro', title: 'Intro', depth: 2 }],
+      site,
+    })
+    expect(html).toContain('<page-toc tone="neutral">')
+  })
+
   it('does not render navigation shell when showNav is false', async () => {
     const site = resolveSiteConfig({ rootDir: process.cwd() })
     const html = await renderPage({
 
@@ -171,9 +171,16 @@ function resolvePageTocConfig(
   input?: DeepPartial<PageTocConfig>,
   file?: DeepPartial<PageTocConfig>,
 ): PageTocConfig {
+  const variant =
+    resolveOptionalString(input?.variant) ??
+    resolveOptionalString(file?.variant)
+  const className =
+    resolveOptionalString(input?.class) ?? resolveOptionalString(file?.class)
   return {
     enabled: pickBoolean(input?.enabled, file?.enabled, true),
     tone: pickSemanticTone(input?.tone, file?.tone) ?? 'neutral',
+    ...(variant ? { variant } : {}),
+    ...(className ? { class: className } : {}),
   }
 }
 
 
@@ -95,6 +95,12 @@ function renderDocTemplate({
                       .push(
                         h('page-toc').attr({
                           tone: frontmatter.layout.tocTone ?? site.pageToc.tone,
+                          ...(site.pageToc.variant
+                            ? { variant: site.pageToc.variant }
+                            : {}),
+                          ...(site.pageToc.class
+                            ? { class: site.pageToc.class }
+                            : {}),
                         }),
                       ),
                   ]