@jackuait/blok 0.7.3-beta.4 → 0.7.3

package/src/components/modules/paste/handlers/blok-data-handler.ts

@@ -127,9 +127,19 @@ export class BlokDataHandler extends BasePasteHandler implements PasteHandler {
   }
 
   /**
-   * Insert Blok JSON blocks.
-   * After inserting all blocks, restores parent-child hierarchy using an ID mapping
-   * (pasted blocks receive new IDs, so original IDs are mapped to new block instances).
+   * Insert Blok JSON blocks using a two-pass approach:
+   *
+   * Pass 1 — child blocks (those whose parentId is within the pasted set) are
+   * inserted first.  They receive new IDs, which are recorded in a map.
+   *
+   * Pass 2 — root/container blocks (e.g. tables) are inserted with their data
+   * remapped so that any old child-block ID references are replaced by the new
+   * IDs from Pass 1.  This prevents container tools (TableCellBlocks) from
+   * resolving old IDs that still exist in the editor and stealing blocks from
+   * the original table.
+   *
+   * After both passes the parent-child hierarchy is re-established using the
+   * accumulated old→new ID mapping.
    */
   private insertBlokBlocks(
     blocks: BlokClipboardBlock[],
@@ -142,31 +152,70 @@ export class BlokDataHandler extends BasePasteHandler implements PasteHandler {
       this.config.sanitizer
     );
 
+    // Capture replace intent before any insertions move the current block pointer.
+    const shouldReplaceFirst =
+      canReplace &&
+      Boolean(BlockManager.currentBlock?.tool.isDefault) &&
+      Boolean(BlockManager.currentBlock?.isEmpty);
+
+    // Set of old IDs present in this paste, used to identify parent-child pairs.
+    const pastedOldIds = new Set(blocks.map(b => b.id));
+
+    type Entry = { sanitized: (typeof sanitizedBlocks)[number]; original: BlokClipboardBlock };
+    const children: Entry[] = [];
+    const roots: Entry[] = [];
+
+    sanitizedBlocks.forEach((sanitizedBlock, i) => {
+      const original = blocks[i];
+
+      if (original === undefined) {
+        return;
+      }
+
+      const isChild =
+        original.parentId !== undefined &&
+        original.parentId !== null &&
+        pastedOldIds.has(original.parentId);
+
+      (isChild ? children : roots).push({ sanitized: sanitizedBlock, original });
+    });
+
     /**
      * Map from original (old) block ID to the newly inserted Block instance.
-     * Used after insertion to re-establish parent-child relationships.
+     * Used to remap data and restore hierarchy after both passes.
      */
     const oldIdToEntry = new Map<string, { newBlock: Block; original: BlokClipboardBlock }>();
 
-    sanitizedBlocks.forEach((sanitizedBlock, i) => {
-      const { tool, data } = sanitizedBlock;
-      const needToReplaceCurrentBlock = i === 0 &&
-        canReplace &&
-        Boolean(BlockManager.currentBlock?.tool.isDefault) &&
-        Boolean(BlockManager.currentBlock?.isEmpty);
+    // Pass 1: insert children first so they exist with new IDs before the parent.
+    children.forEach(({ sanitized, original }) => {
+      const block = BlockManager.insert({ tool: sanitized.tool, data: sanitized.data });
 
-      const block = BlockManager.insert({
-        tool,
-        data,
-        replace: needToReplaceCurrentBlock,
-      });
+      oldIdToEntry.set(original.id, { newBlock: block, original });
+      Caret.setToBlock(block, Caret.positions.END);
+    });
 
-      const originalBlock = blocks[i];
+    // Build old→new string map for remapping ID references inside parent data.
+    const oldIdToNewId = new Map<string, string>();
 
-      if (originalBlock !== undefined) {
-        oldIdToEntry.set(originalBlock.id, { newBlock: block, original: originalBlock });
-      }
+    for (const [oldId, { newBlock }] of oldIdToEntry) {
+      oldIdToNewId.set(oldId, newBlock.id);
+    }
 
+    // Pass 2: insert root blocks with child IDs remapped in their data.
+    // Skip replace when children were pre-inserted to avoid replacing a
+    // just-inserted child paragraph rather than the original empty block.
+    roots.forEach(({ sanitized, original }, idx) => {
+      const remappedData = oldIdToNewId.size > 0
+        ? remapIds(sanitized.data, oldIdToNewId) as typeof sanitized.data
+        : sanitized.data;
+
+      const block = BlockManager.insert({
+        tool: sanitized.tool,
+        data: remappedData,
+        replace: idx === 0 && shouldReplaceFirst && children.length === 0,
+      });
+
+      oldIdToEntry.set(original.id, { newBlock: block, original });
       Caret.setToBlock(block, Caret.positions.END);
     });
 
@@ -193,3 +242,31 @@ export class BlokDataHandler extends BasePasteHandler implements PasteHandler {
     }
   }
 }
+
+/**
+ * Recursively walks `value` and replaces any string found as a key in `idMap`
+ * with its mapped value.  Used to remap old block IDs to new IDs within a
+ * tool's data object before insertion, so that container blocks (e.g. tables)
+ * reference the correct newly-inserted child block IDs.
+ */
+function remapIds(value: unknown, idMap: Map<string, string>): unknown {
+  if (typeof value === 'string') {
+    return idMap.get(value) ?? value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(item => remapIds(item, idMap));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const result: Record<string, unknown> = {};
+
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      result[k] = remapIds(v, idMap);
+    }
+
+    return result;
+  }
+
+  return value;
+}

package/src/components/modules/renderer.ts

@@ -10,6 +10,7 @@ import {
   shouldExpandToHierarchical,
   type DataFormatAnalysis,
 } from '../utils/data-model-transform';
+import { migrateMarkColors } from '../utils/color-migration';
 
 /**
  * Module that responsible for rendering Blocks on blok initialization
@@ -157,6 +158,7 @@ export class Renderer extends Module {
          * Insert batch of Blocks
          */
         BlockManager.insertMany(blocks);
+        migrateMarkColors(this.Blok.UI.nodes.redactor);
       }
 
       /**

package/src/components/modules/toolbar/blockSettings.ts

@@ -396,7 +396,7 @@ export class BlockSettings extends Module<BlockSettingsNodes> {
         title: this.Blok.I18n.t('popover.convertTo'),
         children: {
           items: convertToItems,
-          width: '200px',
+          minWidth: '200px',
         },
       });
       items.push({

package/src/components/modules/toolbar/index.ts

@@ -140,6 +140,7 @@ export class Toolbar extends Module<ToolbarNodes> {
       {
         getToolboxOpened: () => this.toolbox.opened ?? false,
         openToolbox: () => this.toolbox.open(),
+        openToolboxWithoutSlash: () => this.toolbox.openWithoutSlash(),
         closeToolbox: () => this.toolbox.close(),
         moveAndOpenToolbar: (block, target) => this.moveAndOpen(block, target),
       }
@@ -202,6 +203,7 @@ export class Toolbar extends Module<ToolbarNodes> {
     opened: boolean | undefined; // undefined is for the case when Toolbox is not initialized yet
     close: () => void;
     open: () => void;
+    openWithoutSlash: () => void;
     toggle: () => void;
     hasFocus: () => boolean | undefined;
     } {
@@ -210,6 +212,25 @@ export class Toolbar extends Module<ToolbarNodes> {
       close: () => {
         this.toolboxInstance?.close();
       },
+      openWithoutSlash: () => {
+        if (this.toolboxInstance === null) {
+          log('toolbox.openWithoutSlash() called before initialization is finished', 'warn');
+
+          return;
+        }
+
+        if (this.hoveredBlock && !this.hoveredBlockIsFromTableCell) {
+          const currentBlock = this.Blok.BlockManager.currentBlock;
+          const isCurrentBlockInsideTableCell = currentBlock !== undefined
+            && currentBlock.holder.closest('[data-blok-table-cell-blocks]') !== null;
+
+          if (!isCurrentBlockInsideTableCell) {
+            this.Blok.BlockManager.currentBlock = this.hoveredBlock;
+          }
+        }
+
+        this.toolboxInstance.open(false);
+      },
       open: () => {
         /**
          * If Toolbox is not initialized yet, do nothing

package/src/components/modules/toolbar/plus-button.ts

@@ -27,10 +27,15 @@ export class PlusButtonHandler {
   private getToolboxOpened: () => boolean;
 
   /**
-   * Callback to open the toolbox
+   * Callback to open the toolbox in slash-search mode
    */
   private openToolbox: () => void;
 
+  /**
+   * Callback to open the toolbox in no-slash mode (used when clicking the plus button)
+   */
+  private openToolboxWithoutSlash: () => void;
+
   /**
    * Callback to close the toolbox
    */
@@ -50,6 +55,7 @@ export class PlusButtonHandler {
     callbacks: {
       getToolboxOpened: () => boolean;
       openToolbox: () => void;
+      openToolboxWithoutSlash: () => void;
       closeToolbox: () => void;
       moveAndOpenToolbar: (block?: Block | null, target?: Element | null) => void;
     }
@@ -57,6 +63,7 @@ export class PlusButtonHandler {
     this.getBlok = getBlok;
     this.getToolboxOpened = callbacks.getToolboxOpened;
     this.openToolbox = callbacks.openToolbox;
+    this.openToolboxWithoutSlash = callbacks.openToolboxWithoutSlash;
     this.closeToolbox = callbacks.closeToolbox;
     this.moveAndOpenToolbar = callbacks.moveAndOpenToolbar;
   }
@@ -196,14 +203,17 @@ export class PlusButtonHandler {
       hoveredBlock?.holder.after(targetBlock.holder);
     }
 
-    // Insert "/" or position caret after existing one
+    // Position caret and open toolbox
     if (startsWithSlash) {
+      // Block already has "/" - keep slash-search mode, position after the slash
       Caret.setToBlock(targetBlock, Caret.positions.DEFAULT, 1);
+      this.moveAndOpenToolbar(targetBlock);
+      this.openToolbox();
     } else {
+      // New empty block - open toolbox directly without inserting "/"
       Caret.setToBlock(targetBlock, Caret.positions.START);
-      Caret.insertContentAtCaretPosition('/');
+      this.moveAndOpenToolbar(targetBlock);
+      this.openToolboxWithoutSlash();
     }
-    this.moveAndOpenToolbar(targetBlock);
-    this.openToolbox();
   }
 }

package/src/components/selection/fake-background/index.ts

@@ -119,18 +119,17 @@ export class FakeBackgroundManager {
    * Unwraps the highlight spans and restores the selection
    */
   removeFakeBackground(): void {
-    // Always clean up any orphaned fake background elements in the DOM
-    // This handles cleanup after undo/redo operations that may restore fake background elements
-    this.removeOrphanedFakeBackgroundElements();
-
-    if (!this.selectionUtils.isFakeBackgroundEnabled) {
-      return;
+    if (this.selectionUtils.isFakeBackgroundEnabled) {
+      // Remove highlight spans first while they still exist in the DOM,
+      // so that removeHighlightSpans() can reconstruct savedSelectionRange
+      // as a text-node-based range before the spans are gone.
+      this.removeHighlightSpans();
+      this.selectionUtils.isFakeBackgroundEnabled = false;
     }
 
-    // Remove the highlight spans
-    this.removeHighlightSpans();
-
-    this.selectionUtils.isFakeBackgroundEnabled = false;
+    // Clean up any remaining/orphaned fake background elements
+    // (handles undo/redo restoring spans, backwards compat, etc.)
+    this.removeOrphanedFakeBackgroundElements();
   }
 
   /**

package/src/components/shared/color-picker.ts

@@ -1,7 +1,26 @@
 import type { I18n } from '../../../types/api';
 import { parseColor } from '../utils/color-mapping';
+import { onHover } from '../utils/tooltip';
 import { twMerge } from '../utils/tw';
-import { COLOR_PRESETS } from './color-presets';
+import { COLOR_PRESETS, COLOR_PRESETS_DARK } from './color-presets';
+
+/**
+ * Returns the appropriate preset array for the current theme.
+ * Checks the data-blok-theme attribute first (explicit override),
+ * then falls back to the prefers-color-scheme media query.
+ */
+function getActivePresets(): typeof COLOR_PRESETS {
+  const theme = document.documentElement.getAttribute('data-blok-theme');
+
+  if (theme === 'dark') return COLOR_PRESETS_DARK;
+  if (theme === 'light') return COLOR_PRESETS;
+
+  if (typeof window !== 'undefined' && window.matchMedia?.('(prefers-color-scheme: dark)').matches) {
+    return COLOR_PRESETS_DARK;
+  }
+
+  return COLOR_PRESETS;
+}
 
 /**
  * Compare two CSS color strings for equality by their parsed RGB tuples.
@@ -23,7 +42,7 @@ function colorsEqual(a: string, b: string): boolean {
 }
 
 /**
- * Describes one tab in the color picker (e.g. "Text" or "Background")
+ * Describes one section in the color picker (e.g. "Text" or "Background")
  */
 export interface ColorPickerMode {
   key: string;
@@ -37,7 +56,6 @@ export interface ColorPickerMode {
 export interface ColorPickerOptions {
   i18n: I18n;
   modes: [ColorPickerMode, ColorPickerMode];
-  defaultModeIndex?: number;
   testIdPrefix: string;
   onColorSelect: (color: string | null, modeKey: string) => void;
 }
@@ -49,163 +67,158 @@ export interface ColorPickerHandle {
   element: HTMLDivElement;
   /**
    * Set the currently active color for visual indication on the matching swatch.
-   * Pass null to clear any active indicator.
+   * Pass null to clear any active indicator for that section.
    * @param color - CSS color value or null to clear
-   * @param modeKey - The mode key (e.g. 'color', 'background-color') to match the correct preset field
+   * @param modeKey - The mode key (e.g. 'color', 'background-color') to match the correct section
    */
   setActiveColor: (color: string | null, modeKey: string) => void;
   /**
-   * Reset the picker state (tab index) back to defaultModeIndex.
-   * Call this when the picker is reopened to ensure consistent initial state.
+   * Reset the picker state back to defaults (clear all active colors).
    */
   reset: () => void;
 }
 
 /**
- * Base Tailwind classes shared by tab buttons
- */
-const TAB_BASE_CLASSES = 'flex-1 py-1.5 text-xs text-center rounded-md cursor-pointer border-none outline-hidden transition-colors';
-
-/**
- * Neutral background for text-mode swatches so they render as visible buttons
+ * Neutral background for text-mode swatches so they render as visible buttons.
+ * Uses a CSS variable so it adapts to dark mode.
  */
-const SWATCH_NEUTRAL_BG = '#f7f7f5';
+const SWATCH_NEUTRAL_BG = 'var(--blok-swatch-neutral-bg)';
 
 /**
- * Creates a color picker element with two tabs (e.g. Text / Background),
- * a 5-column swatch grid, and a "Default" reset button.
+ * Creates a color picker element with two always-visible sections (e.g. Text / Background),
+ * each containing a 5-column swatch grid with a "Default" reset swatch at position 0.
  *
  * Shared between the marker inline tool and the table cell color popover.
  */
 export function createColorPicker(options: ColorPickerOptions): ColorPickerHandle {
   const { i18n, modes, testIdPrefix, onColorSelect } = options;
-  const defaultModeIndex = options.defaultModeIndex ?? 0;
-  const state = { modeIndex: defaultModeIndex, activeColor: null as string | null };
+  const state = {
+    activeColors: Object.fromEntries(modes.map((m) => [m.key, null])) as Record<string, string | null>,
+  };
 
   const wrapper = document.createElement('div');
 
   wrapper.setAttribute('data-blok-testid', `${testIdPrefix}-picker`);
-  wrapper.className = 'flex flex-col gap-2 p-2';
+  wrapper.className = 'flex flex-col gap-3 p-2';
 
   /**
-   * Tab row
+   * One grid element per section, stored so we can re-render independently.
    */
-  const tabRow = document.createElement('div');
+  const sectionGrids: HTMLDivElement[] = [];
 
-  tabRow.className = 'flex gap-0.5 mb-0.5';
+  /**
+   * Build sections once; re-render only the grids on state changes.
+   */
+  modes.forEach((mode) => {
+    const section = document.createElement('div');
 
-  const tabButtons: HTMLButtonElement[] = [];
+    section.setAttribute('data-blok-testid', `${testIdPrefix}-section-${mode.key}`);
+    section.className = 'flex flex-col gap-1';
 
-  modes.forEach((mode, modeIndex) => {
-    const tab = document.createElement('button');
+    const title = document.createElement('div');
 
-    tab.setAttribute('data-blok-testid', `${testIdPrefix}-tab-${mode.key}`);
-    tab.textContent = i18n.t(mode.labelKey);
-    tab.addEventListener('click', () => {
-      state.modeIndex = modeIndex;
-      updateTabs();
-      renderSwatches();
-    });
-    tabButtons.push(tab);
-    tabRow.appendChild(tab);
-  });
+    title.className = 'text-xs font-medium text-text-primary/60 px-0.5';
+    title.textContent = i18n.t(mode.labelKey);
 
-  const updateTabs = (): void => {
-    for (const [index, button] of tabButtons.entries()) {
-      button.className = twMerge(
-        TAB_BASE_CLASSES,
-        index === state.modeIndex ? 'bg-item-hover-bg font-medium' : 'bg-transparent hover:bg-item-hover-bg/50'
-      );
-    }
-  };
+    const grid = document.createElement('div');
+
+    grid.className = 'grid gap-1';
+    grid.style.gridTemplateColumns = 'repeat(5, 2.25rem)';
+    sectionGrids.push(grid);
+
+    section.appendChild(title);
+    section.appendChild(grid);
+    wrapper.appendChild(section);
+  });
 
   /**
-   * Color grid
+   * Render the swatches for one section.
    */
-  const grid = document.createElement('div');
-
-  grid.setAttribute('data-blok-testid', `${testIdPrefix}-grid`);
-  grid.className = 'grid grid-cols-5 gap-1.5';
+  const renderSection = (modeIndex: number): void => {
+    const grid = sectionGrids[modeIndex];
+    const mode = modes[modeIndex];
+    const presets = getActivePresets();
 
-  const renderSwatches = (): void => {
     grid.innerHTML = '';
 
-    const currentMode = modes[state.modeIndex];
+    const activeColorForSection = state.activeColors[mode.key];
+
+    // Default swatch (first position) — clears the active color for this section
+    const defaultSwatch = document.createElement('button');
+    const isDefaultActive = activeColorForSection === null;
+
+    defaultSwatch.setAttribute('data-blok-testid', `${testIdPrefix}-swatch-${mode.key}-default`);
+    defaultSwatch.className = twMerge(
+      'w-9 h-9 rounded-md cursor-pointer border-none outline-hidden',
+      'flex items-center justify-center text-sm font-semibold',
+      'transition-[box-shadow,transform] ring-inset hover:ring-2 hover:ring-swatch-ring-hover active:scale-90',
+      isDefaultActive && 'ring-2 ring-swatch-ring-hover'
+    );
+    defaultSwatch.textContent = mode.presetField === 'text' ? 'A' : '';
+
+    if (mode.presetField === 'text') {
+      defaultSwatch.style.color = 'var(--blok-text-primary)';
+      defaultSwatch.style.backgroundColor = SWATCH_NEUTRAL_BG;
+    } else {
+      defaultSwatch.style.backgroundColor = SWATCH_NEUTRAL_BG;
+    }
+    defaultSwatch.addEventListener('click', () => {
+      onColorSelect(null, mode.key);
+    });
+    onHover(defaultSwatch, `${i18n.t('tools.marker.default')} ${i18n.t(mode.labelKey).toLowerCase()}`, { placement: 'top' });
+    grid.appendChild(defaultSwatch);
 
-    for (const preset of COLOR_PRESETS) {
+    for (const preset of presets) {
       const swatch = document.createElement('button');
-      const swatchColor = currentMode.presetField === 'text' ? preset.text : preset.bg;
-      const isActive = state.activeColor !== null && colorsEqual(swatchColor, state.activeColor);
+      const swatchColor = mode.presetField === 'text' ? preset.text : preset.bg;
+      const isActive = activeColorForSection !== null && colorsEqual(swatchColor, activeColorForSection);
 
-      swatch.setAttribute('data-blok-testid', `${testIdPrefix}-swatch-${preset.name}`);
+      swatch.setAttribute('data-blok-testid', `${testIdPrefix}-swatch-${mode.key}-${preset.name}`);
       swatch.className = twMerge(
-        'w-8 h-8 rounded-md cursor-pointer border-none outline-hidden',
+        'w-9 h-9 rounded-md cursor-pointer border-none outline-hidden',
         'flex items-center justify-center text-sm font-semibold',
-        'transition-shadow ring-inset hover:ring-2 hover:ring-black/10',
-        isActive && 'ring-2 ring-black/30'
+        'transition-[box-shadow,transform] ring-inset hover:ring-2 hover:ring-swatch-ring-hover active:scale-90',
+        isActive && 'ring-2 ring-swatch-ring-hover'
       );
-      swatch.textContent = 'A';
+      swatch.textContent = mode.presetField === 'text' ? 'A' : '';
 
-      if (currentMode.presetField === 'text') {
+      if (mode.presetField === 'text') {
         swatch.style.color = preset.text;
         swatch.style.backgroundColor = SWATCH_NEUTRAL_BG;
       } else {
-        swatch.style.color = '';
+        swatch.style.color = presets === COLOR_PRESETS_DARK ? preset.text : '#37352f';
         swatch.style.backgroundColor = preset.bg;
       }
 
       swatch.addEventListener('click', () => {
-        onColorSelect(swatchColor, currentMode.key);
+        onColorSelect(swatchColor, mode.key);
       });
+      onHover(swatch, `${i18n.t('tools.colorPicker.color.' + preset.name)} ${i18n.t(mode.labelKey).toLowerCase()}`, { placement: 'top' });
       grid.appendChild(swatch);
     }
   };
 
-  /**
-   * Default button
-   */
-  const defaultBtn = document.createElement('button');
-
-  defaultBtn.setAttribute('data-blok-testid', `${testIdPrefix}-default-btn`);
-  defaultBtn.className = twMerge(
-    'w-full py-1.5 text-xs text-center rounded-md cursor-pointer',
-    'bg-transparent border-none outline-hidden hover:bg-item-hover-bg',
-    'mt-0.5 transition-colors'
-  );
-  defaultBtn.textContent = i18n.t('tools.marker.default');
-  defaultBtn.addEventListener('click', () => {
-    onColorSelect(null, modes[state.modeIndex].key);
-  });
-
-  /**
-   * Assemble
-   */
-  updateTabs();
-  renderSwatches();
+  const renderAll = (): void => {
+    modes.forEach((_, i) => renderSection(i));
+  };
 
-  wrapper.appendChild(tabRow);
-  wrapper.appendChild(grid);
-  wrapper.appendChild(defaultBtn);
+  renderAll();
 
   return {
     element: wrapper,
     setActiveColor: (color: string | null, modeKey: string) => {
-      state.activeColor = color;
-
       const matchingIndex = modes.findIndex((m) => m.key === modeKey);
 
       if (matchingIndex !== -1) {
-        state.modeIndex = matchingIndex;
-        updateTabs();
+        state.activeColors[modeKey] = color;
+        renderSection(matchingIndex);
       }
-
-      renderSwatches();
     },
     reset: () => {
-      state.modeIndex = defaultModeIndex;
-      state.activeColor = null;
-      updateTabs();
-      renderSwatches();
+      for (const mode of modes) {
+        state.activeColors[mode.key] = null;
+      }
+      renderAll();
     },
   };
 }

package/src/components/shared/color-presets.ts

@@ -8,7 +8,7 @@ export interface ColorPreset {
 }
 
 /**
- * Ten Notion-style color presets.
+ * Ten Notion-style color presets for light mode.
  * `text` is used for foreground (text-color mode), `bg` for background swatches.
  */
 export const COLOR_PRESETS: ColorPreset[] = [
@@ -17,9 +17,37 @@ export const COLOR_PRESETS: ColorPreset[] = [
   { name: 'orange', text: '#d9730d', bg: '#fbecdd' },
   { name: 'yellow', text: '#cb9b00', bg: '#fbf3db' },
   { name: 'green', text: '#448361', bg: '#edf3ec' },
-  { name: 'teal', text: '#2b9a8f', bg: '#e4f5f3' },
   { name: 'blue', text: '#337ea9', bg: '#e7f3f8' },
   { name: 'purple', text: '#9065b0', bg: '#f6f3f9' },
   { name: 'pink', text: '#c14c8a', bg: '#f9f0f5' },
   { name: 'red', text: '#d44c47', bg: '#fdebec' },
 ];
+
+/**
+ * Dark-mode adapted presets. Text colors are lightened for readability on dark
+ * swatch backgrounds; background colors are deep/muted to integrate with dark UI.
+ * All pairs achieve at least 3.8:1 WCAG contrast. Backgrounds are equalized at
+ * ~L19% HSL with increased saturation so each hue family is clearly identifiable.
+ */
+export const COLOR_PRESETS_DARK: ColorPreset[] = [
+  { name: 'gray',   text: '#9b9b9b', bg: '#2f2f2f' },
+  { name: 'brown',  text: '#c59177', bg: '#452a1c' },
+  { name: 'orange', text: '#dc8c47', bg: '#4d2f14' },
+  { name: 'yellow', text: '#d4ab49', bg: '#544012' },
+  { name: 'green',  text: '#5db184', bg: '#1e432f' },
+  { name: 'blue',   text: '#5c9fcc', bg: '#123a54' },
+  { name: 'purple', text: '#a67dca', bg: '#341d49' },
+  { name: 'pink',   text: '#d45e99', bg: '#4b1b33' },
+  { name: 'red',    text: '#dd5e5a', bg: '#4e1a18' },
+];
+
+/**
+ * Construct a CSS custom property reference for a named preset color.
+ *
+ * @param name - The color preset name (e.g. 'red', 'blue')
+ * @param mode - 'text' for foreground, 'bg' for background
+ * @returns CSS var reference, e.g. `var(--blok-color-red-text)`
+ */
+export function colorVarName(name: string, mode: 'text' | 'bg'): string {
+  return `var(--blok-color-${name}-${mode})`;
+}