@uniweb/kit 0.9.34 → 0.9.36

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.34",
+  "version": "0.9.36",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./xref": "./src/xref/index.js",
-    "./theme-tokens.css": "./src/theme-tokens.css"
+    "./theme-tokens.css": "./src/theme-tokens.css",
+    "./prose-tokens.css": "./src/prose-tokens.css"
   },
   "files": [
     "src",
@@ -39,7 +40,7 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.27",
+    "@uniweb/core": "0.7.28",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

package/src/components/Asset/Asset.jsx

@@ -26,6 +26,7 @@ import { useWebsite } from '../../hooks/useWebsite.js'
  * @param {React.ReactNode} [props.children] - Custom content (overrides default filename display)
  *
  * @example
+ * kit-palette-ok: a caller-supplied class in an example, not kit painting
  * <Asset value="document.pdf" className="text-blue-600 hover:underline" />
  *
  * @example

package/src/components/FileLogo/FileLogo.jsx

@@ -124,6 +124,7 @@ function getExtension(filename) {
  * <FileLogo filename="report.pdf" size="32" />
  *
  * @example
+ * kit-palette-ok: a caller-supplied class in an example, not kit painting
  * <FileLogo filename="data.xlsx" className="text-green-600" />
  */
 export function FileLogo({ filename, size = '24', className, ...props }) {

package/src/components/MediaIcon/MediaIcon.jsx

@@ -67,6 +67,7 @@ const SOCIAL_ICONS = {
  * @param {string} [props.className] - Additional CSS classes
  *
  * @example
+ * kit-palette-ok: a caller-supplied class in an example, not kit painting
  * <MediaIcon type="twitter" size="32" className="text-blue-400" />
  *
  * @example

package/src/hooks/index.js

@@ -11,7 +11,6 @@ export { useMobileMenu } from './useMobileMenu.js'
 export { useAccordion } from './useAccordion.js'
 export { useHeadings } from './useHeadings.js'
 export { useGridLayout, getGridClasses } from './useGridLayout.js'
-export { useTheme, getThemeClasses, THEMES, THEME_NAMES } from './useTheme.js'
 export { useInView, useIsInView } from './useInView.js'
 export { usePageState } from './usePageState.js'
 export { useWebsiteState } from './useWebsiteState.js'

package/src/hooks/useHeadings.js

@@ -41,8 +41,15 @@ import { useActiveRoute } from './useActiveRoute.js'
 
 /**
  * Pull headings out of the page's own content — available during prerender.
+ *
+ * Skips the headings the semantic parser claimed as the section's own
+ * title/pretitle/subtitle. In this framework a leading `###` is a pretitle and
+ * the `##` after the title is a subtitle — structure, not body headings — so a
+ * typed section would otherwise open every contents rail with two entries no
+ * reader recognises as sections of the article. An untyped document has none of
+ * those fields set, and everything in it counts.
  */
-function headingsFromContent(page, levels) {
+export function headingsFromContent(page, levels = [2, 3]) {
   const blocks = page?.getBodyBlocks?.() ?? []
   const found = []
 
@@ -50,13 +57,23 @@ function headingsFromContent(page, levels) {
     const nodes = block?.rawContent?.content
     if (!Array.isArray(nodes)) continue
 
+    const parsed = block.parsedContent || {}
+    const claimed = new Set(
+      [parsed.title, parsed.pretitle, parsed.subtitle]
+        .flat()
+        .filter(Boolean)
+        .map(value => String(value).trim())
+    )
+
     for (const node of nodes) {
       if (node?.type !== 'heading') continue
       const level = node.attrs?.level ?? 1
       if (!levels.includes(level)) continue
 
       const text = nodeText(node).trim()
-      if (text) found.push({ id: headingId(text), text, level })
+      if (!text || claimed.has(text)) continue
+
+      found.push({ id: headingId(text), text, level })
     }
   }
 

package/src/hooks/useScrolled.js

@@ -8,7 +8,7 @@
  * function Header() {
  *   const scrolled = useScrolled()
  *   return (
- *     <header className={scrolled ? 'bg-white shadow' : 'bg-transparent'}>
+ *     <header className={scrolled ? 'bg-section shadow' : 'bg-transparent'}>
  *       ...
  *     </header>
  *   )

package/src/index.js

@@ -65,10 +65,6 @@ export {
   useHeadings,
   useGridLayout,
   getGridClasses,
-  useTheme,
-  getThemeClasses,
-  THEMES,
-  THEME_NAMES,
   // Viewport detection
   useInView,
   useIsInView,
@@ -124,7 +120,6 @@ export {
 // Styled Components (Tailwind-based)
 // ============================================================================
 
-export { SidebarLayout } from './styled/SidebarLayout/index.js'
 export { Section, Render } from './styled/Section/index.js'
 export { Prose } from './styled/Prose/index.jsx'
 export { Article } from './styled/Article/index.jsx'

package/src/prose-tokens.css

@@ -0,0 +1,73 @@
+/*
+ * Tailwind Typography, wired to the theme.
+ *
+ * Usage — after the plugin, so these win on equal specificity:
+ *
+ *   @plugin "@tailwindcss/typography";
+ *   @import "@uniweb/kit/prose-tokens.css";
+ *
+ * `prose` ships its own greys, which means long-form body copy is the one part
+ * of a foundation that ignores the site's theme.yml unless someone bridges it
+ * by hand. Everyone does bridge it by hand, identically, and the bridge is easy
+ * to get subtly wrong — so it lives here.
+ *
+ * After this import, a prose container answers to the site like everything else
+ * and flips with the visitor's scheme on its own. Do not add a `prose-invert`
+ * or a `dark:` variant: the tokens have already changed by the time the dark
+ * scheme is active, and `prose-invert` would override this with fixed greys.
+ *
+ * For the same reason, do not add a palette modifier — `prose-gray`,
+ * `prose-slate`, `prose-neutral`. Those re-declare every variable below.
+ *
+ * ── One container ──
+ *
+ * These variables are inherited, so a `prose` container nested inside another
+ * silently resets the lot for its subtree. Two containers is always a bug, and
+ * a quiet one: the outer looks right and everything inside it does not. Decide
+ * who owns prose — the section that renders the document is usually the better
+ * owner, since it then renders correctly under any layout — and make sure the
+ * other one only supplies column width and padding.
+ */
+
+.prose {
+  --tw-prose-body: var(--body);
+  --tw-prose-headings: var(--heading);
+  --tw-prose-lead: var(--subtle);
+  --tw-prose-links: var(--link, var(--primary));
+  --tw-prose-bold: var(--heading);
+  --tw-prose-counters: var(--subtle);
+  --tw-prose-bullets: var(--border);
+  --tw-prose-hr: var(--border);
+  --tw-prose-quotes: var(--subtle);
+  --tw-prose-quote-borders: var(--primary);
+  --tw-prose-captions: var(--subtle);
+  --tw-prose-kbd: var(--heading);
+  --tw-prose-code: var(--heading);
+  --tw-prose-th-borders: var(--border);
+  --tw-prose-td-borders: var(--border);
+
+  /* Fenced code keeps whatever the highlighter paints — a site retunes that
+     through `code:` in theme.yml, not here. */
+  --tw-prose-pre-code: var(--code-text, var(--body));
+  --tw-prose-pre-bg: var(--code-surface, var(--muted));
+}
+
+/* Inline code reads as a chip on whatever surface it sits on, rather than the
+   plugin's fixed grey. Scoped to `:not(pre)` so fenced blocks are untouched. */
+.prose :not(pre) > code {
+  background-color: color-mix(in oklch, var(--section), var(--heading) 6%);
+  border-radius: 0.25rem;
+  padding: 0.125rem 0.375rem;
+  font-weight: 500;
+  font-size: 0.875em;
+}
+.prose :not(pre) > code::before,
+.prose :not(pre) > code::after {
+  content: none;
+}
+
+/* Anchors land clear of a fixed site header when something scrolls to them —
+   a contents rail, or a link with a #fragment. */
+.prose :is(h1, h2, h3, h4) {
+  scroll-margin-top: calc(var(--header-height, 4rem) + 1rem);
+}

package/src/styled/Asset/Asset.jsx

@@ -108,7 +108,7 @@ export const Asset = forwardRef(function Asset(
   return (
     <div
       className={cn(
-        'relative inline-block rounded-lg overflow-hidden border border-gray-200',
+        'relative inline-block rounded-lg overflow-hidden border border-border',
         'transition-shadow hover:shadow-md',
         className
       )}
@@ -117,7 +117,7 @@ export const Asset = forwardRef(function Asset(
       {...props}
     >
       {/* Preview */}
-      <div className="w-32 h-32 flex items-center justify-center bg-gray-50">
+      <div className="w-32 h-32 flex items-center justify-center bg-muted">
         {isImage && !imageError ? (
           <Image
             src={src}
@@ -126,12 +126,12 @@ export const Asset = forwardRef(function Asset(
             onError={handleImageError}
           />
         ) : (
-          <FileLogo filename={filename} size="48" className="text-gray-400" />
+          <FileLogo filename={filename} size="48" className="text-subtle" />
         )}
       </div>
 
       {/* Filename */}
-      <div className="px-2 py-1 text-xs text-gray-600 truncate max-w-[128px]" title={filename}>
+      <div className="px-2 py-1 text-xs text-body truncate max-w-[128px]" title={filename}>
         {filename}
       </div>
 
@@ -141,6 +141,7 @@ export const Asset = forwardRef(function Asset(
           onClick={handleDownload}
           className={cn(
             'absolute inset-0 flex items-center justify-center',
+            // kit-palette-ok: a scrim over a thumbnail, not a themed surface
             'bg-black/50 text-white transition-opacity',
             isHovered ? 'opacity-100' : 'opacity-0'
           )}

package/src/styled/Disclaimer/Disclaimer.jsx

@@ -38,6 +38,7 @@ function DisclaimerModal({ isOpen, onClose, title, content, className }) {
     <div className="fixed inset-0 z-50 overflow-y-auto">
       {/* Backdrop */}
       <div
+        // kit-palette-ok: a modal scrim is the same black in either scheme
         className="fixed inset-0 bg-black/50 transition-opacity"
         onClick={onClose}
         aria-hidden="true"
@@ -48,7 +49,7 @@ function DisclaimerModal({ isOpen, onClose, title, content, className }) {
         <div
           className={cn(
             'relative w-full max-w-lg transform overflow-hidden rounded-lg',
-            'bg-white shadow-xl transition-all',
+            'bg-card shadow-xl transition-all',
             className
           )}
           role="dialog"
@@ -56,13 +57,13 @@ function DisclaimerModal({ isOpen, onClose, title, content, className }) {
           aria-labelledby="disclaimer-title"
         >
           {/* Header */}
-          <div className="flex items-center justify-between border-b border-gray-200 px-4 py-3">
-            <h3 id="disclaimer-title" className="text-lg font-medium text-gray-900">
+          <div className="flex items-center justify-between border-b border-border px-4 py-3">
+            <h3 id="disclaimer-title" className="text-lg font-medium text-heading">
               {title}
             </h3>
             <button
               onClick={onClose}
-              className="rounded-md p-1 text-gray-400 hover:text-gray-500 focus:outline-none focus:ring-2 focus:ring-blue-500"
+              className="rounded-md p-1 text-subtle hover:text-heading focus:outline-none focus:ring-2 focus:ring-ring"
               aria-label="Close"
             >
               <svg className="h-5 w-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
@@ -81,10 +82,10 @@ function DisclaimerModal({ isOpen, onClose, title, content, className }) {
           </div>
 
           {/* Footer */}
-          <div className="border-t border-gray-200 px-4 py-3 flex justify-end">
+          <div className="border-t border-border px-4 py-3 flex justify-end">
             <button
               onClick={onClose}
-              className="px-4 py-2 text-sm font-medium text-white bg-blue-600 rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500"
+              className="px-4 py-2 text-sm font-medium text-primary-foreground bg-primary rounded-md hover:bg-primary-hover focus:outline-none focus:ring-2 focus:ring-ring"
             >
               Close
             </button>
@@ -161,8 +162,8 @@ export function Disclaimer({
       onClick={handleOpen}
       className={cn(
         'inline-flex items-center px-3 py-1.5 text-sm font-medium',
-        'text-blue-600 hover:text-blue-700',
-        'border border-blue-600 rounded-md hover:bg-blue-50',
+        'text-primary hover:text-primary-hover',
+        'border border-primary rounded-md hover:bg-primary/10',
         className
       )}
       {...props}
@@ -173,7 +174,7 @@ export function Disclaimer({
     <button
       onClick={handleOpen}
       className={cn(
-        'text-blue-600 hover:text-blue-700 underline text-sm',
+        'text-primary hover:text-primary-hover underline text-sm',
         className
       )}
       {...props}

package/src/styled/Media/Media.jsx

@@ -152,12 +152,15 @@ function PlayButton({ onClick, className }) {
       onClick={onClick}
       className={cn(
         'absolute inset-0 flex items-center justify-center',
+        // kit-palette-ok: a play-button scrim, the same in any theme
         'bg-black/30 hover:bg-black/40 transition-colors',
         'group cursor-pointer',
         className
       )}
       aria-label="Play video"
     >
+      {/* kit-palette-ok: a play control is a white disc with a dark glyph in
+          every player ever built — not a themed surface */}
       <div className="w-16 h-16 rounded-full bg-white/90 group-hover:bg-white flex items-center justify-center transition-colors">
         <svg className="w-8 h-8 text-gray-900 ml-1" fill="currentColor" viewBox="0 0 24 24">
           <path d="M8 5v14l11-7z" />
@@ -310,6 +313,7 @@ export function Media({
 
   return (
     <div
+      // kit-palette-ok: letterboxing behind a video is black, in any theme
       className={cn('relative overflow-hidden bg-black', className)}
       style={{ aspectRatio }}
       {...props}

package/src/styled/Section/Render.jsx

@@ -123,16 +123,16 @@ function RenderNode({ node, block, ...props }) {
                   className="w-full"
                 />
               ) : (
-                <div className="flex items-center gap-3 p-4 bg-gray-50">
-                  <Icon name="download" size="24" className="text-gray-500" />
-                  <span className="text-blue-600 group-hover:underline">
+                <div className="flex items-center gap-3 p-4 bg-muted">
+                  <Icon name="download" size="24" className="text-subtle" />
+                  <span className="text-link group-hover:underline">
                     {filename}
                   </span>
                 </div>
               )}
             </Link>
             {caption && (
-              <figcaption className="mt-2 text-sm text-gray-500 text-center">
+              <figcaption className="mt-2 text-sm text-subtle text-center">
                 {caption}
               </figcaption>
             )}
@@ -164,7 +164,7 @@ function RenderNode({ node, block, ...props }) {
         <figure className="my-4">
           <Image src={src} alt={alt} className="rounded-lg" />
           {caption && (
-            <figcaption className="mt-2 text-sm text-gray-500 text-center">
+            <figcaption className="mt-2 text-sm text-subtle text-center">
               {caption}
             </figcaption>
           )}
@@ -192,7 +192,7 @@ function RenderNode({ node, block, ...props }) {
 
     case 'blockquote': {
       return (
-        <blockquote className="border-l-4 border-gray-300 pl-4 italic text-gray-600 my-4">
+        <blockquote className="border-l-4 border-border pl-4 italic text-subtle my-4">
           {content?.map((child, i) => (
             <RenderNode key={i} node={child} block={block} />
           ))}
@@ -247,7 +247,7 @@ function RenderNode({ node, block, ...props }) {
       return (
         <Link
           to={href}
-          className="inline-block px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors my-2"
+          className="inline-block px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary-hover transition-colors my-2"
         >
           {label}
         </Link>
@@ -270,10 +270,10 @@ function RenderNode({ node, block, ...props }) {
               text = `<em>${text}</em>`
               break
             case 'code':
-              text = `<code class="px-1 py-0.5 bg-gray-100 rounded text-sm">${text}</code>`
+              text = `<code class="px-1 py-0.5 bg-muted rounded text-sm">${text}</code>`
               break
             case 'link':
-              text = `<a href="${mark.attrs?.href || '#'}" class="text-blue-600 hover:underline">${text}</a>`
+              text = `<a href="${mark.attrs?.href || '#'}" class="text-link hover:underline">${text}</a>`
               break
           }
         })

package/src/styled/Section/Section.jsx

@@ -62,7 +62,7 @@ const PADDING_CLASSES = {
  * <Section content={blockContent} width="lg" padding="md" />
  *
  * @example
- * <Section width="xl" columns="2" className="bg-gray-50">
+ * <Section width="xl" columns="2" className="bg-muted">
  *   <div>Column 1</div>
  *   <div>Column 2</div>
  * </Section>

package/src/styled/Section/renderers/Alert.jsx

@@ -15,39 +15,39 @@ import { SafeHtml } from '../../../components/SafeHtml/index.js'
  */
 const ALERT_STYLES = {
   info: {
-    container: 'bg-blue-50 border-blue-200 text-blue-800',
+    container: 'bg-info-subtle border-info text-info',
     icon: (
       <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
     ),
-    iconColor: 'text-blue-500'
+    iconColor: 'text-info'
   },
   success: {
-    container: 'bg-green-50 border-green-200 text-green-800',
+    container: 'bg-success-subtle border-success text-success',
     icon: (
       <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
     ),
-    iconColor: 'text-green-500'
+    iconColor: 'text-success'
   },
   warning: {
-    container: 'bg-yellow-50 border-yellow-200 text-yellow-800',
+    container: 'bg-warning-subtle border-warning text-warning',
     icon: (
       <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
     ),
-    iconColor: 'text-yellow-500'
+    iconColor: 'text-warning'
   },
   danger: {
-    container: 'bg-red-50 border-red-200 text-red-800',
+    container: 'bg-error-subtle border-error text-error',
     icon: (
       <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
     ),
-    iconColor: 'text-red-500'
+    iconColor: 'text-error'
   },
   error: {
-    container: 'bg-red-50 border-red-200 text-red-800',
+    container: 'bg-error-subtle border-error text-error',
     icon: (
       <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 14l2-2m0 0l2-2m-2 2l-2-2m2 2l2 2m7-2a9 9 0 11-18 0 9 9 0 0118 0z" />
     ),
-    iconColor: 'text-red-500'
+    iconColor: 'text-error'
   }
 }
 

package/src/styled/Section/renderers/Code.jsx

@@ -17,7 +17,7 @@ import { getUniweb } from '@uniweb/core'
 let cssInjected = false
 let shikiInstance = null
 let shikiLoadPromise = null
-let siteThemeLoaded = false
+const loadedDerived = new Set()
 
 // What a site gets when it declares no `code:` block of its own, and the base
 // every declaration layers over.
@@ -121,6 +121,24 @@ function injectCodeLayoutCSS() {
   display: block;
   font-family: var(--font-code, ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, Consolas, monospace);
 }
+
+/* A site that named a light/dark pair gets CSS variables per token instead of
+   inline colour, and these are what read them. Scoped to .shiki-themes, the
+   class Shiki adds only in that mode, so a single-theme listing is untouched. */
+.shiki-themes {
+  background-color: var(--shiki-light-bg);
+}
+.shiki-themes,
+.shiki-themes span {
+  color: var(--shiki-light);
+}
+.scheme-dark .shiki-themes {
+  background-color: var(--shiki-dark-bg);
+}
+.scheme-dark .shiki-themes,
+.scheme-dark .shiki-themes span {
+  color: var(--shiki-dark);
+}
 `
   document.head.appendChild(style)
   cssInjected = true
@@ -170,20 +188,82 @@ async function loadShiki() {
 }
 
 /**
- * Register the site's `code:` declaration as a theme, once, and answer with the
- * theme name to highlight against. Sites that declare nothing get the default.
+ * Normalize `theme.yml`'s `code:` into the three forms a site can write.
+ *
+ *   code: dracula                     → one bundled theme
+ *   code: { light: …, dark: … }       → a pair, following the visitor's scheme
+ *   code: { theme?: …, <colour>: … }  → a base theme with colours overridden
+ *
+ * The third is the escape hatch. Naming a theme is what most sites want — 65
+ * ship inside Shiki — and hand-picking a dozen syntax colours is a job few
+ * people can do well. Overrides exist because "that theme, on my background"
+ * is a reasonable and common ask.
+ *
+ * @param {string|Object} [code] - the `code:` declaration
+ * @returns {{ light: Side, dark?: Side }} where Side is { base, overrides }
+ */
+export function parseCodeConfig(code) {
+  const side = (value) => {
+    if (typeof value === 'string') return { base: value, overrides: {} }
+    const { theme, ...overrides } = value || {}
+    return { base: theme || DEFAULT_THEME, overrides }
+  }
+
+  if (!code) return { light: { base: DEFAULT_THEME, overrides: {} } }
+  if (typeof code === 'string') return { light: side(code) }
+
+  if (code.light || code.dark) {
+    return {
+      light: side(code.light ?? code.dark),
+      dark: side(code.dark ?? code.light),
+    }
+  }
+
+  return { light: side(code) }
+}
+
+/**
+ * Make sure a side's theme is registered, and answer the name to highlight by.
+ * A side with no overrides is just the bundled theme; one with overrides gets a
+ * derived theme built from it.
+ */
+async function registerSide(highlighter, side, name) {
+  if (!highlighter.getLoadedThemes().includes(side.base)) {
+    await highlighter.loadTheme(side.base)
+  }
+  if (Object.keys(side.overrides).length === 0) return side.base
+
+  if (!loadedDerived.has(name)) {
+    await highlighter.loadTheme({
+      ...buildCodeTheme(highlighter.getTheme(side.base), side.overrides),
+      name,
+    })
+    loadedDerived.add(name)
+  }
+  return name
+}
+
+/**
+ * Resolve the `code:` declaration into codeToHtml options.
+ *
+ * One theme highlights the same in both schemes — right for a site whose code
+ * blocks are a terminal. A pair makes Shiki emit CSS variables per token
+ * (`defaultColor: false`) instead of inline colour, so one rendered block can
+ * follow the visitor's choice; injectCodeLayoutCSS supplies the rules that read
+ * them.
  */
-async function resolveThemeName(highlighter, codeTheme) {
-  if (!codeTheme || Object.keys(codeTheme).length === 0) return DEFAULT_THEME
-  if (siteThemeLoaded) return SITE_CODE_THEME
+async function resolveThemeOptions(highlighter, code) {
+  const config = parseCodeConfig(code)
 
   try {
-    await highlighter.loadTheme(buildCodeTheme(highlighter.getTheme(DEFAULT_THEME), codeTheme))
-    siteThemeLoaded = true
-    return SITE_CODE_THEME
+    const light = await registerSide(highlighter, config.light, `${SITE_CODE_THEME}-light`)
+    if (!config.dark) return { theme: light }
+
+    const dark = await registerSide(highlighter, config.dark, `${SITE_CODE_THEME}-dark`)
+    return { themes: { light, dark }, defaultColor: false }
   } catch (error) {
     console.warn('[Code] Could not apply theme.code, using the default:', error)
-    return DEFAULT_THEME
+    return { theme: DEFAULT_THEME }
   }
 }
 
@@ -194,7 +274,7 @@ async function highlightCode(code, language, highlighter, codeTheme) {
   if (!highlighter) return null
 
   try {
-    const theme = await resolveThemeName(highlighter, codeTheme)
+    const themeOptions = await resolveThemeOptions(highlighter, codeTheme)
 
     // Load language if not already loaded
     const loadedLangs = highlighter.getLoadedLanguages()
@@ -205,13 +285,13 @@ async function highlightCode(code, language, highlighter, codeTheme) {
         await highlighter.loadLanguage(lang)
       } catch {
         // Language not available, fall back to plaintext
-        return highlighter.codeToHtml(code, { lang: 'plaintext', theme })
+        return highlighter.codeToHtml(code, { lang: 'plaintext', ...themeOptions })
       }
     }
 
     return highlighter.codeToHtml(code, {
       lang: lang === 'plaintext' ? 'text' : lang,
-      theme,
+      ...themeOptions,
     })
   } catch (error) {
     console.warn('[Code] Highlighting failed:', error)

package/src/styled/Section/renderers/Details.jsx

@@ -31,7 +31,7 @@ export function Details({
   return (
     <div
       className={cn(
-        'border border-gray-200 rounded-lg overflow-hidden',
+        'border border-border rounded-lg overflow-hidden',
         className
       )}
       {...props}
@@ -40,8 +40,8 @@ export function Details({
       <button
         className={cn(
           'w-full flex items-center justify-between px-4 py-3',
-          'text-left font-medium text-gray-900 bg-gray-50',
-          'hover:bg-gray-100 transition-colors'
+          'text-left font-medium text-heading bg-muted',
+          'hover:bg-card transition-colors'
         )}
         onClick={() => setIsOpen(!isOpen)}
         aria-expanded={isOpen}
@@ -49,7 +49,7 @@ export function Details({
         <span>{summary}</span>
         <svg
           className={cn(
-            'w-5 h-5 text-gray-500 transition-transform',
+            'w-5 h-5 text-subtle transition-transform',
             isOpen && 'rotate-180'
           )}
           fill="none"
@@ -62,7 +62,7 @@ export function Details({
 
       {/* Content */}
       {isOpen && (
-        <div className="px-4 py-3 border-t border-gray-200">
+        <div className="px-4 py-3 border-t border-border">
           {typeof content === 'string' ? (
             <SafeHtml value={content} className="prose prose-sm" />
           ) : (

package/src/styled/Section/renderers/Divider.jsx

@@ -24,16 +24,16 @@ export function Divider({ type = 'hr', className, ...props }) {
         role="separator"
         {...props}
       >
-        <span className="w-2 h-2 bg-gray-300 rounded-full" />
-        <span className="w-2 h-2 bg-gray-300 rounded-full" />
-        <span className="w-2 h-2 bg-gray-300 rounded-full" />
+        <span className="w-2 h-2 bg-border rounded-full" />
+        <span className="w-2 h-2 bg-border rounded-full" />
+        <span className="w-2 h-2 bg-border rounded-full" />
       </div>
     )
   }
 
   return (
     <hr
-      className={cn('border-gray-200 my-6', className)}
+      className={cn('border-border my-6', className)}
       {...props}
     />
   )

package/src/styled/Section/renderers/Table.jsx

@@ -22,10 +22,10 @@ export function Table({ content, className, ...props }) {
 
   return (
     <div className={cn('overflow-x-auto', className)} {...props}>
-      <table className="min-w-full divide-y divide-gray-200 border border-gray-200 rounded-lg">
-        <tbody className="divide-y divide-gray-200 bg-white">
+      <table className="min-w-full divide-y divide-border border border-border rounded-lg">
+        <tbody className="divide-y divide-border bg-section">
           {content.map((row, rowIndex) => (
-            <tr key={rowIndex} className={rowIndex % 2 === 0 ? 'bg-white' : 'bg-gray-50'}>
+            <tr key={rowIndex} className={rowIndex % 2 === 0 ? 'bg-section' : 'bg-muted'}>
               {row.content?.map((cell, cellIndex) => {
                 const CellTag = cell.type === 'tableHeader' ? 'th' : 'td'
                 const cellContent = cell.content?.[0]?.content?.[0]?.text || ''
@@ -36,8 +36,8 @@ export function Table({ content, className, ...props }) {
                     className={cn(
                       'px-4 py-2 text-sm',
                       cell.type === 'tableHeader'
-                        ? 'font-medium text-gray-900 bg-gray-100'
-                        : 'text-gray-600'
+                        ? 'font-medium text-heading bg-muted'
+                        : 'text-body'
                     )}
                   >
                     <SafeHtml value={cellContent} as="span" />

package/src/styled/index.js

@@ -7,14 +7,13 @@
  * For unstyled primitives, use the main '@uniweb/kit' export.
  *
  * @example
- * import { SidebarLayout, Section, Media } from '@uniweb/kit (styled)'
+ * import { Section, Prose, Media } from '@uniweb/kit (styled)'
  */
 
 // ============================================================================
 // Layout
 // ============================================================================
 
-export { SidebarLayout } from './SidebarLayout/index.js'
 
 // ============================================================================
 // Content Rendering

package/src/hooks/useTheme.js

@@ -1,205 +0,0 @@
-/**
- * useTheme Hook
- *
- * Provides standardized theme classes for components.
- * Eliminates duplicated theme objects across 25+ components.
- *
- * @example
- * function Hero({ params }) {
- *   const t = useTheme(params.theme)
- *
- *   return (
- *     <section className={t.section}>
- *       <h1 className={t.title}>...</h1>
- *       <p className={t.body}>...</p>
- *     </section>
- *   )
- * }
- *
- * @example
- * // With custom overrides
- * const t = useTheme('dark', {
- *   card: 'bg-gray-800 rounded-xl',
- *   cardHover: 'hover:bg-gray-700'
- * })
- */
-
-/**
- * Standard theme definitions.
- * Keys are standardized across all components.
- */
-const THEMES = {
-  light: {
-    // Section backgrounds
-    section: 'bg-white',
-    sectionAlt: 'bg-gray-50',
-
-    // Typography
-    title: 'text-gray-900',
-    subtitle: 'text-gray-700',
-    pretitle: 'text-primary',
-    body: 'text-gray-600',
-    muted: 'text-gray-500',
-
-    // Cards
-    card: 'bg-gray-50',
-    cardHover: 'hover:shadow-lg',
-    cardBorder: 'border border-gray-200',
-
-    // Interactive
-    link: 'text-primary hover:text-primary-dark',
-    linkMuted: 'text-gray-600 hover:text-gray-900',
-
-    // Borders & Dividers
-    border: 'border-gray-200',
-    divider: 'bg-gray-200',
-  },
-
-  gray: {
-    section: 'bg-gray-50',
-    sectionAlt: 'bg-gray-100',
-
-    title: 'text-gray-900',
-    subtitle: 'text-gray-700',
-    pretitle: 'text-primary',
-    body: 'text-gray-600',
-    muted: 'text-gray-500',
-
-    card: 'bg-white shadow-sm',
-    cardHover: 'hover:shadow-lg',
-    cardBorder: 'border border-gray-200',
-
-    link: 'text-primary hover:text-primary-dark',
-    linkMuted: 'text-gray-600 hover:text-gray-900',
-
-    border: 'border-gray-200',
-    divider: 'bg-gray-300',
-  },
-
-  dark: {
-    section: 'bg-gray-900',
-    sectionAlt: 'bg-gray-800',
-
-    title: 'text-white',
-    subtitle: 'text-gray-300',
-    pretitle: 'text-primary',
-    body: 'text-gray-400',
-    muted: 'text-gray-500',
-
-    card: 'bg-gray-800',
-    cardHover: 'hover:bg-gray-750',
-    cardBorder: 'border border-gray-700',
-
-    link: 'text-primary hover:text-primary-light',
-    linkMuted: 'text-gray-400 hover:text-white',
-
-    border: 'border-gray-700',
-    divider: 'bg-gray-700',
-  },
-
-  primary: {
-    section: 'bg-primary',
-    sectionAlt: 'bg-primary-dark',
-
-    title: 'text-white',
-    subtitle: 'text-white/90',
-    pretitle: 'text-white/80',
-    body: 'text-white/80',
-    muted: 'text-white/60',
-
-    card: 'bg-white/10',
-    cardHover: 'hover:bg-white/20',
-    cardBorder: 'border border-white/20',
-
-    link: 'text-white hover:text-white/80',
-    linkMuted: 'text-white/70 hover:text-white',
-
-    border: 'border-white/20',
-    divider: 'bg-white/20',
-  },
-
-  gradient: {
-    section: 'bg-gradient-to-br from-primary to-indigo-600',
-    sectionAlt: 'bg-gradient-to-br from-primary-dark to-indigo-700',
-
-    title: 'text-white',
-    subtitle: 'text-white/90',
-    pretitle: 'text-white/80',
-    body: 'text-white/80',
-    muted: 'text-white/60',
-
-    card: 'bg-white/10 backdrop-blur-sm',
-    cardHover: 'hover:bg-white/20',
-    cardBorder: 'border border-white/20',
-
-    link: 'text-white hover:text-white/80',
-    linkMuted: 'text-white/70 hover:text-white',
-
-    border: 'border-white/20',
-    divider: 'bg-white/20',
-  },
-
-  glass: {
-    section: 'bg-white/10 backdrop-blur-lg',
-    sectionAlt: 'bg-white/5 backdrop-blur-lg',
-
-    title: 'text-white',
-    subtitle: 'text-white/90',
-    pretitle: 'text-primary',
-    body: 'text-white/80',
-    muted: 'text-white/60',
-
-    card: 'bg-white/10 backdrop-blur-sm',
-    cardHover: 'hover:bg-white/20',
-    cardBorder: 'border border-white/20',
-
-    link: 'text-white hover:text-primary',
-    linkMuted: 'text-white/70 hover:text-white',
-
-    border: 'border-white/20',
-    divider: 'bg-white/20',
-  },
-}
-
-/**
- * Hook to get theme classes by name.
- *
- * @param {string} themeName - Theme name (light, gray, dark, primary, gradient, glass)
- * @param {Object} overrides - Custom class overrides
- * @returns {Object} Theme classes object
- */
-export function useTheme(themeName = 'light', overrides = {}) {
-  const baseTheme = THEMES[themeName] || THEMES.light
-
-  if (Object.keys(overrides).length === 0) {
-    return baseTheme
-  }
-
-  return {
-    ...baseTheme,
-    ...overrides,
-  }
-}
-
-/**
- * Get theme classes without the hook (for non-React contexts)
- * @param {string} themeName
- * @param {Object} overrides
- * @returns {Object}
- */
-export function getThemeClasses(themeName = 'light', overrides = {}) {
-  const baseTheme = THEMES[themeName] || THEMES.light
-  return { ...baseTheme, ...overrides }
-}
-
-/**
- * All available theme names
- */
-export const THEME_NAMES = Object.keys(THEMES)
-
-/**
- * Export theme definitions for customization
- */
-export { THEMES }
-
-export default useTheme

package/src/styled/SidebarLayout/SidebarLayout.jsx

@@ -1,311 +0,0 @@
-import React, { useEffect } from 'react'
-import { cn } from '../../utils/index.js'
-import { useMobileMenu } from '../../hooks/useMobileMenu.js'
-
-/**
- * SidebarLayout Component
- *
- * A flexible layout with optional left and/or right sidebars.
- * On desktop, sidebars appear inline at their configured breakpoints.
- * On mobile, the left panel is accessible via a slide-out drawer with FAB toggle.
- * The right panel is hidden on mobile (common pattern: nav essential, TOC optional).
- *
- * The layout is "sandwiched" - header and footer span the full width,
- * with the sidebars and content area between them.
- *
- * @example
- * // In foundation's src/foundation.js
- * import { SidebarLayout } from '@uniweb/kit'
- *
- * export default {
- *   Layout: SidebarLayout,
- * }
- *
- * @example
- * // With custom configuration
- * import { SidebarLayout } from '@uniweb/kit'
- *
- * function CustomLayout(props) {
- *   return (
- *     <SidebarLayout
- *       {...props}
- *       leftBreakpoint="lg"
- *       rightBreakpoint="xl"
- *       leftWidth="w-72"
- *     />
- *   )
- * }
- *
- * export default { Layout: CustomLayout }
- */
-
-/**
- * Hamburger menu icon
- */
-function MenuIcon({ className }) {
-  return (
-    <svg className={className} fill="none" viewBox="0 0 24 24" stroke="currentColor">
-      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" />
-    </svg>
-  )
-}
-
-/**
- * Close (X) icon
- */
-function CloseIcon({ className }) {
-  return (
-    <svg className={className} fill="none" viewBox="0 0 24 24" stroke="currentColor">
-      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-    </svg>
-  )
-}
-
-/**
- * Mobile drawer component (always slides from left)
- */
-function MobileDrawer({ isOpen, onClose, width, stickyHeader, children }) {
-  // Prevent body scroll when drawer is open
-  useEffect(() => {
-    if (isOpen) {
-      document.body.style.overflow = 'hidden'
-      return () => {
-        document.body.style.overflow = ''
-      }
-    }
-  }, [isOpen])
-
-  // Position below header if sticky, otherwise from top
-  const topOffset = stickyHeader ? 'top-[var(--header-height,4rem)]' : 'top-0'
-  const height = stickyHeader ? 'h-[calc(100vh-var(--header-height,4rem))]' : 'h-screen'
-
-  return (
-    <>
-      {/* Backdrop */}
-      <div
-        className={cn(
-          // kit-palette-ok: a modal scrim is the same black in either scheme
-          'fixed inset-0 bg-black/50 z-40 transition-opacity duration-300',
-          isOpen ? 'opacity-100' : 'opacity-0 pointer-events-none'
-        )}
-        onClick={onClose}
-        aria-hidden="true"
-      />
-
-      {/* Drawer (always from left) */}
-      <div
-        className={cn(
-          'fixed left-0 bg-section z-50 shadow-xl',
-          topOffset,
-          height,
-          width,
-          'transform transition-transform duration-300 ease-in-out',
-          isOpen ? 'translate-x-0' : '-translate-x-full'
-        )}
-        role="dialog"
-        aria-modal="true"
-        aria-label="Sidebar navigation"
-      >
-        {/* Close button */}
-        <button
-          onClick={onClose}
-          className="absolute top-4 right-4 p-1.5 rounded-md hover:bg-muted transition-colors"
-          aria-label="Close sidebar"
-        >
-          <CloseIcon className="w-5 h-5 text-subtle" />
-        </button>
-
-        {/* Drawer content */}
-        <div className="h-full overflow-y-auto overscroll-contain">
-          {children}
-        </div>
-      </div>
-    </>
-  )
-}
-
-/**
- * Floating action button for mobile menu (always bottom-left)
- */
-function FloatingMenuButton({ onClick }) {
-  return (
-    <button
-      onClick={onClick}
-      className={cn(
-        'fixed bottom-4 left-4 z-30',
-        'p-3 bg-primary text-primary-foreground rounded-full shadow-lg',
-        'hover:bg-primary/90 active:scale-95 transition-all',
-        'focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2'
-      )}
-      aria-label="Open navigation menu"
-    >
-      <MenuIcon className="w-6 h-6" />
-    </button>
-  )
-}
-
-/**
- * Get responsive classes for showing/hiding at breakpoint
- */
-function getBreakpointClasses(breakpoint) {
-  const showClass = {
-    sm: 'sm:block',
-    md: 'md:block',
-    lg: 'lg:block',
-    xl: 'xl:block',
-  }[breakpoint] || 'md:block'
-
-  const hideClass = {
-    sm: 'sm:hidden',
-    md: 'md:hidden',
-    lg: 'lg:hidden',
-    xl: 'xl:hidden',
-  }[breakpoint] || 'md:hidden'
-
-  return { showClass, hideClass }
-}
-
-/**
- * SidebarLayout main component
- *
- * @param {Object} props
- * @param {React.ReactNode} props.header - Header content (from layout/header.md)
- * @param {React.ReactNode} props.body - Main body content (page sections)
- * @param {React.ReactNode} props.footer - Footer content (from layout/footer.md)
- * @param {React.ReactNode} props.left - Left panel content (from layout/left.md)
- * @param {React.ReactNode} props.right - Right panel content (from layout/right.md)
- * @param {React.ReactNode} props.leftPanel - Alias for left (backwards compatibility)
- * @param {React.ReactNode} props.rightPanel - Alias for right (backwards compatibility)
- * @param {string} [props.leftWidth='w-64'] - Tailwind width class for left sidebar
- * @param {string} [props.rightWidth='w-64'] - Tailwind width class for right sidebar
- * @param {string} [props.drawerWidth='w-72'] - Tailwind width class for mobile drawer
- * @param {string} [props.leftBreakpoint='md'] - Breakpoint for showing left sidebar inline
- * @param {string} [props.rightBreakpoint='xl'] - Breakpoint for showing right sidebar inline
- * @param {boolean} [props.stickyHeader=true] - Whether header sticks to top
- * @param {boolean} [props.stickySidebar=true] - Whether sidebars stick below header
- * @param {string} [props.maxWidth='max-w-7xl'] - Max width of content area
- * @param {string} [props.contentPadding='px-4 py-8 sm:px-6 lg:px-8'] - Padding for main content
- * @param {string} [props.className] - Additional classes for the root element
- */
-export function SidebarLayout({
-  // Pre-rendered layout areas from runtime
-  header,
-  body,
-  footer,
-  left,
-  right,
-  leftPanel,
-  rightPanel,
-  // Configuration
-  leftWidth = 'w-64',
-  rightWidth = 'w-64',
-  drawerWidth = 'w-72',
-  leftBreakpoint = 'md',
-  rightBreakpoint = 'xl',
-  stickyHeader = true,
-  stickySidebar = true,
-  maxWidth = 'max-w-7xl',
-  contentPadding = 'px-4 py-8 sm:px-6 lg:px-8',
-  className,
-}) {
-  const { isOpen, open, close } = useMobileMenu()
-
-  // Resolve panel content (support both naming conventions)
-  const leftContent = left || leftPanel
-  const rightContent = right || rightPanel
-
-  // Get breakpoint classes for each panel
-  const leftClasses = getBreakpointClasses(leftBreakpoint)
-  const rightClasses = getBreakpointClasses(rightBreakpoint)
-
-  // Sticky positioning
-  const headerClasses = stickyHeader
-    ? 'sticky top-0 z-30'
-    : ''
-
-  const sidebarClasses = stickySidebar && stickyHeader
-    ? 'sticky top-[var(--header-height,4rem)] h-[calc(100vh-var(--header-height,4rem))]'
-    : stickySidebar
-      ? 'sticky top-0 h-screen'
-      : ''
-
-  return (
-    <div className={cn('min-h-screen flex flex-col bg-section', className)}>
-      {/* Header */}
-      {header && (
-        <header className={cn(
-          'w-full border-b border-border bg-section/95 backdrop-blur supports-[backdrop-filter]:bg-section/80',
-          headerClasses
-        )}>
-          {header}
-        </header>
-      )}
-
-      {/* Mobile Drawer (left panel only) */}
-      {leftContent && (
-        <div className={leftClasses.hideClass}>
-          <MobileDrawer
-            isOpen={isOpen}
-            onClose={close}
-            width={drawerWidth}
-            stickyHeader={stickyHeader}
-          >
-            {leftContent}
-          </MobileDrawer>
-        </div>
-      )}
-
-      {/* Main Content Area */}
-      <div className={cn('flex-1 w-full mx-auto', maxWidth)}>
-        <div className="flex">
-          {/* Left Sidebar (desktop) */}
-          {leftContent && (
-            <aside className={cn(
-              'hidden flex-shrink-0 overflow-y-auto border-r border-border',
-              leftClasses.showClass,
-              leftWidth,
-              sidebarClasses
-            )}>
-              {leftContent}
-            </aside>
-          )}
-
-          {/* Main Content */}
-          <main className="flex-1 min-w-0">
-            <div className={contentPadding}>
-              {body}
-            </div>
-          </main>
-
-          {/* Right Sidebar (desktop only, hidden on mobile) */}
-          {rightContent && (
-            <aside className={cn(
-              'hidden flex-shrink-0 overflow-y-auto border-l border-border',
-              rightClasses.showClass,
-              rightWidth,
-              sidebarClasses
-            )}>
-              {rightContent}
-            </aside>
-          )}
-        </div>
-      </div>
-
-      {/* Footer */}
-      {footer && (
-        <footer className="w-full border-t border-border">
-          {footer}
-        </footer>
-      )}
-
-      {/* Mobile FAB (only if left panel exists) */}
-      {leftContent && (
-        <div className={leftClasses.hideClass}>
-          <FloatingMenuButton onClick={open} />
-        </div>
-      )}
-    </div>
-  )
-}
-
-export default SidebarLayout

package/src/styled/SidebarLayout/index.js

@@ -1 +0,0 @@
-export { SidebarLayout, default } from './SidebarLayout.jsx'