@fibery/ui-kit 4.1.0 → 4.3.0

package/src/design-system/colors.ts

@@ -3,6 +3,7 @@ import {cssFromFilter, makeColorFilter} from "../color-filter";
 import {highlightColors} from "../highlight-colors";
 import type {ThemeMode} from "../theme-settings";
 import {alpha, opacity, transparent} from "./alpha";
+import {alphaCoefficients as A, type AlphaModeDef} from "./alpha-coefficients";
 import {getDarkenColor} from "./colors-js";
 import {Swatch, swatches} from "./colors-swatches";
 import {mapDef} from "./def";
@@ -12,13 +13,6 @@ import type {Def, DefMapper, Defs, ThemePalette} from "./types";
 /** @deprecated use swatches */
 export const cardTypeColors = swatches;
 
-type ThemeColorsDef = Record<
-  string,
-  | readonly [lightColor: string, darkColor: string]
-  | readonly [Record<string, string>, Record<string, string>]
-  | readonly ["light", "dark"]
->;
-
 const separator = (color: string) => `0.5px solid ${color}`;
 const border1 = (color: string) => `1px solid ${color}`;
 const border3 = (color: string) => `3px solid ${color}`;
@@ -32,6 +26,12 @@ const both =
   (map: (_: string) => string) =>
   ([light, dark]: Def): Def => [map(light), map(dark)];
 
+const alphaPair = (lightColor: string, darkColor: string, alphaValue: AlphaModeDef): Def => [
+  alpha(lightColor, alphaValue[0]),
+  alpha(darkColor, alphaValue[1]),
+];
+const alphaDef = (def: Def, alphaValue: AlphaModeDef): Def => alphaPair(def[0], def[1], alphaValue);
+
 export function defsFromPalette({
   key,
   whiteA,
@@ -59,19 +59,19 @@ export function defsFromPalette({
   enum: enumDefs,
 }: ThemePalette) {
   // whiteA = surface direction (white on light / black on dark) — blends INTO bg
-  const whiteA5: Def = [alpha(white, 0.05), alpha(black, 0.05)];
-  const whiteA10: Def = [alpha(white, 0.1), alpha(black, 0.1)];
-  const whiteA25: Def = [alpha(white, 0.25), alpha(black, 0.25)];
-  const whiteA40: Def = [alpha(white, 0.4), alpha(black, 0.4)];
+  const whiteA5: Def = alphaPair(white, black, A.direction.surface5);
+  const whiteA10: Def = alphaPair(white, black, A.direction.surface10);
+  const whiteA25: Def = alphaPair(white, black, A.direction.surface25);
+  const whiteA40: Def = alphaPair(white, black, A.direction.surface40);
   const whiteA100: Def = [white, black];
 
   // blackA = contrast direction (black on light / white on dark) — readable on bg
-  const blackA5: Def = [alpha(black, 0.05), alpha(white, 0.05)];
-  const blackA10: Def = [alpha(black, 0.1), alpha(white, 0.1)];
-  const blackA15: Def = [alpha(black, 0.15), alpha(white, 0.15)];
-  const blackA25: Def = [alpha(black, 0.25), alpha(white, 0.25)];
-  const blackA50: Def = [alpha(black, 0.5), alpha(white, 0.5)];
-  const blackA90: Def = [alpha(black, 0.9), alpha(white, 0.9)];
+  const blackA5: Def = alphaPair(black, white, A.direction.ink5);
+  const blackA10: Def = alphaPair(black, white, A.direction.ink10);
+  const blackA15: Def = alphaPair(black, white, A.direction.ink15);
+  const blackA25: Def = alphaPair(black, white, A.direction.ink25);
+  const blackA50: Def = alphaPair(black, white, A.direction.ink50);
+  const blackA90: Def = alphaPair(black, white, A.direction.ink90);
 
   const opacities = {
     subtle: same(opacity.opacity15.toString()),
@@ -107,8 +107,9 @@ export function defsFromPalette({
     level2_6: [base[2], baseDark[6]],
 
     // muted bg (code, form fields)
-    level3exotic: [base[3], blackish], // FIXME try blackA[3] | baseDark[3] to make it less exotic
+    level3: [base[3], baseDark[3]],
     level3_1: [base[3], baseDark[1]],
+    level3_2: [base[3], baseDark[2]],
     level3_4: [base[3], baseDark[4]],
     level3_6: [base[3], baseDark[6]],
     level3_7: [base[3], baseDark[7]],
@@ -167,124 +168,162 @@ export function defsFromPalette({
 
   // --- Input borders (stroke shadows) ---
   const inputStrokes = {
-    disabled: [stroke1(alpha(base[6], 0.2)), stroke1(alpha(baseDark[8], 0.2))],
-    default: [stroke1(alpha(base[6], 0.7)), stroke1(alpha(baseDark[8], 0.7))],
-    hover: [stroke1(base[7]), stroke1(baseDark[8])],
+    disabled: both(stroke1)(alphaPair(base[6], baseDark[8], A.inputStroke.disabled)),
+    default: both(stroke1)(alphaPair(base[6], baseDark[8], A.inputStroke.default)),
+    hover: [stroke1(base[7]), stroke1(baseDark[7])],
     focus: [stroke1(base[8]), stroke1(baseDark[9])],
     error: [stroke1(red[11]), stroke1(red[7])],
-    errorHover: [stroke1(alpha(red[11], 0.4)), stroke1(alpha(red[7], 0.4))],
-    errorFocus: [stroke1(alpha(red[11], 0.25)), stroke1(alpha(red[7], 0.25))],
-    errorFocusRing: [stroke3(alpha(red[11], 0.25)), stroke3(alpha(red[7], 0.25))],
+    errorHover: both(stroke1)(alphaPair(red[11], red[7], A.inputStroke.errorHover)),
+    errorFocus: both(stroke1)(alphaPair(red[11], red[7], A.inputStroke.errorFocus)),
+    errorFocusRing: both(stroke3)(alphaPair(red[11], red[7], A.inputStroke.errorFocus)),
     warning: [stroke1(yellow[9]), stroke1(yellowDark[8])],
   } satisfies Defs;
 
   // --- Floating surface shadows ---
   const floatingShadows = {
     popup: [
-      steps([glow2(alpha(base[11], 0.3)), elevationSM(alpha(base[11], 0.05)), elevationXL(alpha(base[11], 0.15))]),
-      steps([stroke1(baseDark[6]), elevationSM(alpha(baseDark[1], 0.05)), elevationXL(alpha(baseDark[1], 0.15))]),
+      steps([
+        glow2(alpha(base[11], A.shadow.popupGlowLight[0])),
+        elevationSM(alpha(base[11], A.shadow.hairline[0])),
+        elevationXL(alpha(base[11], A.shadow.medium[0])),
+      ]),
+      steps([
+        stroke1(baseDark[6]),
+        elevationSM(alpha(baseDark[1], A.shadow.hairline[1])),
+        elevationXL(alpha(baseDark[1], A.shadow.medium[1])),
+      ]),
     ],
     instrumentsMenu: [
-      steps([glow1(alpha(base[11], 0.2)), elevationSM(alpha(base[11], 0.05)), elevationSL(alpha(base[11], 0.1))]),
-      steps([glow1(baseDark[6]), elevationSM(alpha(baseDark[1], 0.05)), elevationSL(alpha(baseDark[1], 0.15))]),
+      steps([
+        glow1(alpha(base[11], A.shadow.high[0])),
+        elevationSM(alpha(base[11], A.shadow.hairline[0])),
+        elevationSL(alpha(base[11], A.shadow.low[0])),
+      ]),
+      steps([
+        glow1(baseDark[6]),
+        elevationSM(alpha(baseDark[1], A.shadow.hairline[1])),
+        elevationSL(alpha(baseDark[1], A.shadow.medium[1])),
+      ]),
+    ],
+  } satisfies Defs;
+
+  // --- Floating panel (inbox item hover, rich text format bar, batch actions toolbar) ---
+  const floatingPanel = {
+    bg: raised.level2,
+    shadow: [
+      steps([
+        stroke1(alpha(base[10], A.shadow.floatingPanelStrokeLight[0])),
+        elevationSL(alpha(base[11], A.shadow.floatingPanelDarkElevation[0])),
+      ]),
+      steps([stroke1(baseDark[6]), elevationSL(alpha(baseDark[1], A.shadow.floatingPanelDarkElevation[1]))]),
     ],
   } satisfies Defs;
 
   // --- Card/container shadows ---
   const cardShadows = {
     subtle: [
-      steps([stroke1(alpha(base[10], 0.1)), elevationS_shrinked(alpha(base[10], 0.2))]),
-      steps([stroke1(alpha(baseDark[2], 0.1)), elevationS_shrinked(alpha(baseDark[2], 0.2))]),
+      steps([stroke1(alpha(base[10], A.shadow.low[0])), elevationS_shrinked(alpha(base[10], A.shadow.high[0]))]),
+      steps([stroke1(alpha(baseDark[2], A.shadow.low[1])), elevationS_shrinked(alpha(baseDark[2], A.shadow.high[1]))]),
     ],
   } satisfies Defs;
 
   const entityBoxShadows = {
     stroke: {
       default: [stroke1(base[5]), stroke1(baseDark[5])],
-      focus: [stroke2(alpha(accent[9], 0.4)), stroke2(alpha(accentDark[9], 0.4))],
-      focusHover: [stroke2(alpha(accent[9], 0.6)), stroke2(alpha(accentDark[9], 0.6))],
+      focus: both(stroke2)(alphaPair(accent[9], accentDark[9], A.entityBox.focusStroke)),
+      focusHover: both(stroke2)(alphaPair(accent[9], accentDark[9], A.entityBox.focusHoverStroke)),
       selected: [
-        steps([stroke1(alpha(accent[9], 0.4)), stroke3(alpha(accent[9], 0.4))]),
-        steps([stroke1(accentDark[9]), stroke3(alpha(accentDark[9], 0.4))]),
+        steps([
+          stroke1(alpha(accent[9], A.entityBox.focusStroke[0])),
+          stroke3(alpha(accent[9], A.entityBox.focusStroke[0])),
+        ]),
+        steps([stroke1(accentDark[9]), stroke3(alpha(accentDark[9], A.entityBox.focusStroke[1]))]),
       ],
       selectedHover: [
-        steps([stroke1(alpha(accent[9], 0.6)), stroke3(alpha(accent[9], 0.4))]),
-        steps([stroke1(accentDark[9]), stroke3(alpha(accentDark[9], 0.4))]),
+        steps([
+          stroke1(alpha(accent[9], A.entityBox.focusHoverStroke[0])),
+          stroke3(alpha(accent[9], A.entityBox.focusStroke[0])),
+        ]),
+        steps([stroke1(accentDark[9]), stroke3(alpha(accentDark[9], A.entityBox.focusStroke[1]))]),
       ],
     } satisfies Defs,
     elevation: {
       // Progression: S → M → L (default → hover → drag)
-      default: [elevationS(alpha(base[12], 0.05)), elevationS(alpha(baseDark[1], 0.05))],
-      hover: [elevationM(alpha(base[12], 0.1)), elevationM(alpha(baseDark[1], 0.1))],
-      drag: [elevationL(alpha(base[12], 0.1)), elevationL(alpha(baseDark[1], 0.1))],
+      default: both(elevationS)(alphaPair(base[12], baseDark[1], A.entityBox.elevationDefault)),
+      hover: both(elevationM)(alphaPair(base[12], baseDark[1], A.entityBox.elevationRaised)),
+      drag: both(elevationL)(alphaPair(base[12], baseDark[1], A.entityBox.elevationRaised)),
     } satisfies Defs,
   };
 
-  // FIXME assymetric: light is composite (elevation100 + stroke05), dark is simple (stroke1 only)
+  // Asymmetric: light is composite (elevation100 + stroke05), dark is simple (stroke1 only).
   const shadowMenuHeaderAvatar = [
-    steps([elevation100(alpha(base[11], 0.1)), stroke05(alpha(base[5], 0.5))]),
-    stroke1(alpha(baseDark[9], 0.2)),
+    steps([
+      elevation100(alpha(base[11], A.shadow.low[0])),
+      stroke05(alpha(base[5], A.shadow.menuHeaderLightStroke[0])),
+    ]),
+    stroke1(alpha(baseDark[9], A.shadow.menuHeaderLightStroke[1])),
   ] as const;
 
   const edgeLeft = (color: string) => `-3px 0 10px 0 ${color}`;
 
-  const formHeaderShadow = [glow6(alpha(base[10], 0.1)), glow6(alpha(baseDark[1], 0.4))] as const;
+  const formHeaderShadow = [
+    glow6(alpha(base[10], A.shadow.formHeader[0])),
+    glow6(alpha(baseDark[1], A.shadow.formHeader[1])),
+  ] as const;
 
   const shadows = {
     // Elevations
-    surfaceElevationS: [elevationS(blackA[3]), elevationS(whiteA[3])],
+    // dark uses a subtle dark shadow (baseDark[1]) like entityBoxShadows — NOT a white glow
+    surfaceElevationS: [elevationS(blackA[3]), elevationS(alpha(baseDark[1], A.shadow.hairline[1]))],
     surfaceElevationM: [elevationM(blackA[5]), elevationM(whiteA[5])],
     surfaceElevationL: [elevationL(blackA[5]), elevationL(whiteA[5])],
 
     // Shadows and effects / Elevation
-    shadow50: [stroke1(alpha(base[12], 0.05)), stroke1(alpha(baseDark[12], 0.1))],
-    shadow100: [elevation100(alpha(base[12], 0.05)), elevation100(alpha(base[12], 0.1))],
-    shadow200: [elevation200(alpha(base[12], 0.05)), elevation200(alpha(base[12], 0.1))],
-    shadow300: same(steps([elevation250(alpha(base[12], 0.1)), elevation300(alpha(base[12], 0.15))])),
-    shadow400: same(steps([glow1(alpha(base[12], 0.2)), elevation400(alpha(base[12], 0.15))])),
-    shadow500: same(steps([glow1(alpha(base[12], 0.2)), elevation500(alpha(base[12], 0.15))])),
-    shadow600: same(steps([glow1(alpha(base[12], 0.2)), elevation600(alpha(base[12], 0.2))])),
+    shadow50: [stroke1(alpha(base[12], A.shadow.hairline[0])), stroke1(alpha(baseDark[12], A.shadow.low[1]))],
+    shadow100: [elevation100(alpha(base[12], A.shadow.hairline[0])), elevation100(alpha(base[12], A.shadow.low[1]))],
+    shadow200: [elevation200(alpha(base[12], A.shadow.hairline[0])), elevation200(alpha(base[12], A.shadow.low[1]))],
+    shadow300: same(
+      steps([elevation250(alpha(base[12], A.shadow.low[0])), elevation300(alpha(base[12], A.shadow.medium[0]))])
+    ),
+    shadow400: same(
+      steps([glow1(alpha(base[12], A.shadow.high[0])), elevation400(alpha(base[12], A.shadow.medium[0]))])
+    ),
+    shadow500: same(
+      steps([glow1(alpha(base[12], A.shadow.high[0])), elevation500(alpha(base[12], A.shadow.medium[0]))])
+    ),
+    shadow600: same(steps([glow1(alpha(base[12], A.shadow.high[0])), elevation600(alpha(base[12], A.shadow.high[0]))])),
 
     actionMenuShadow: floatingShadows.popup,
     shadowPopup: floatingShadows.popup,
-    shadowSidebar: [edgeLeft(alpha(base[10], 0.1)), edgeLeft(alpha(baseDark[1], 0.8))],
+    shadowSidebar: [
+      edgeLeft(alpha(base[10], A.shadow.sidebarEdge[0])),
+      edgeLeft(alpha(baseDark[1], A.shadow.sidebarEdge[1])),
+    ],
   } as const;
 
-  // names proposal: forbid color in keys (they all are colors) — restructure it better (separate shadows, borders etc)
-  // inspired by tailwind:
-  // bg-*	Sets the background color of an element
-  // text-*	Sets the text color of an element
-  // border-*	Sets the border color of an element
-  // shadow-*	Sets the color of box shadows
-  // fill-*	Sets the fill color of SVG elements
-  // stroke-*	Sets the stroke color of SVG elements
-  // TODO elevation = raised * shadow
-
   const transparentAlways = same(transparent);
   const whiteColor = same(white);
   const blackColor = same(black);
 
   const fg = {
     accent: [accent[11], accentDark[11]],
-    accentActive: [alpha(accent[11], 0.8), alpha(accentDark[11], 0.8)],
+    accentActive: alphaDef([accent[11], accentDark[11]], A.foreground.active),
 
     neutral: [base[11], baseDark[11]],
-    neutralActive: [alpha(base[11], 0.8), alpha(baseDark[11], 0.8)],
-    // FIXME uses base[12] while soft/ghost use base[11] — inconsistent?
-    neutralActive__TODO: [alpha(base[12], 0.8), alpha(baseDark[12], 0.8)],
+    neutralActive: alphaDef([base[11], baseDark[11]], A.foreground.active),
+    neutralStrongActive: alphaDef([base[12], baseDark[12]], A.foreground.active),
     muted: [base[9], baseDark[9]],
 
     destructive: [red[11], redDark[11]],
-    destructiveActive: [alpha(red[11], 0.8), alpha(redDark[11], 0.8)],
+    destructiveActive: alphaDef([red[11], redDark[11]], A.foreground.active),
 
     addition: [teal[9], tealDark[11]],
 
     success: [teal[11], tealDark[11]],
     warning: [yellow[11], yellowDark[11]],
 
-    icon: [alpha(base[12], 0.7), alpha(baseDark[12], 0.7)],
-    // TODO The 0.65 vs 0.7 dark alpha might be intentional (text slightly more muted than icons?) or drift.
-    secondary: [alpha(base[12], 0.7), alpha(baseDark[12], 0.65)],
+    icon: alphaDef([base[12], baseDark[12]], A.foreground.icon),
+    secondary: alphaDef([base[12], baseDark[12]], A.foreground.secondary),
 
     link: [blue_9_, blueDark_9_],
     ai: [purple_9_, purpleDark_9_],
@@ -317,15 +356,15 @@ export function defsFromPalette({
 
   const primary = {
     accent: [accent[9], accentDark[9]],
-    destructive_TODO: [red[9], redDark[9]],
-    destructive: [red[9], redDark[10]], // TODO 9_9?
+    destructiveBase: [red[9], redDark[9]],
+    destructive: [red[9], redDark[10]],
     success: [teal[9], tealDark[9]],
-    warning: [yellow[9], yellowDark[8]], // TODO 9_9 after correct adjusting palette?
+    warning: [yellow[9], yellowDark[8]],
   } satisfies Defs;
 
   const bgStatus = {
-    accent: [alpha(accent[5], 0.7), alpha(accentDark[4], 0.8)],
-    neutral: [alpha(base[5], 0.7), alpha(baseDark[4], 0.8)],
+    accent: alphaPair(accent[5], accentDark[4], A.badgeFill.accent),
+    neutral: alphaPair(base[5], baseDark[4], A.badgeFill.neutral),
     success: [teal[5], tealDark[5]],
     warning: [yellow[5], yellowDark[5]],
     error: [red[5], redDark[5]],
@@ -336,45 +375,45 @@ export function defsFromPalette({
   const borderDanger = [red[7], redDark[7]] as const;
   const borderNeutral = [base[8], baseDark[7]] as const;
 
-  // beg(TODO shake it)
-  const bgEntityCardOverlay = [alpha(base[2], 0.8), alpha(baseDark[6], 0.5)] as const;
-  const bgEntityCardDone = [alpha(base[4], 0.3), alpha(baseDark[5], 0.3)] as const;
+  const bgEntityCardOverlay = alphaPair(base[2], baseDark[6], A.entityCard.overlay);
+  const bgEntityCardDone = alphaPair(base[4], baseDark[5], A.entityCard.done);
   const base5_6 = [base[5], baseDark[6]] as const;
-  const base6_6_opacity30 = [alpha(base[6], 0.3), alpha(baseDark[6], 0.3)] as const;
+  const base6_6_opacity30 = alphaPair(base[6], baseDark[6], A.interactiveFill.disabledNeutral);
   const base8 = [base[8], baseDark[8]] as const;
   const fgAccentText = [base[10], baseDark[10]] as const;
   const fgMenuEtc = [base[12], baseDark[12]] as const;
 
   const bgTabFocus = [base[6], baseDark[6]] as const;
-  const bgTabHover = [alpha(base[11], 0.1), alpha(baseDark[11], 0.1)] as const;
+  const bgTabHover = alphaPair(base[11], baseDark[11], A.interactiveFill.tabHover);
 
   const viewHighlightBg = [accent[3], accentDark[3]] as const;
-  const notificationSelected = [accent[3], accentDark[4]] as const;
-  const bgCellGridDisabledOrHighlighted = [accent[4], accentDark[5]] as const;
-  const notificationSelectedHover = [accent[4], accentDark[6]] as const;
 
-  const fgSelection = [alpha(accent[9], 0.2), alpha(accentDark[9], 0.4)] as const;
+  const notificationSelected = [accent[3], accentDark[2]] as const;
+  const notificationSelectedHover = [accent[4], accentDark[3]] as const;
+  const bgCellGridDisabledOrHighlighted = [accent[4], accentDark[5]] as const;
 
-  const warningColor = [alpha(yellow[6], 0.6), alpha(yellowDark[9], 0.4)] as const;
-  const bgBtnGhostAccentHover = [alpha(accent[4], 0.8), alpha(accentDark[4], 0.8)] as const;
-  const bgBtnGhostNeutralHover = [alpha(base[7], 0.5), alpha(baseDark[6], 0.8)] as const;
+  const warningColor = alphaPair(yellow[6], yellowDark[9], A.interactiveFill.warningComment);
+  const bgBtnGhostAccentHover = alphaPair(accent[4], accentDark[4], A.interactiveFill.ghostAccentHover);
+  const bgBtnGhostNeutralHover = alphaPair(base[7], baseDark[6], A.interactiveFill.ghostNeutralHover);
   const bgBtnGhostDestructiveHover = [red[4], redDark[4]] as const;
   const bgBtnSoftAccentHover = [accent[5], accentDark[6]] as const;
   const bgBtnSoftNeutralDefault = [base[3], baseDark[3]] as const;
   const bgBtnSoftNeutralHover = [base[7], baseDark[7]] as const;
   const bgBtnSoftDestructiveHover = [red[6], redDark[6]] as const;
-  const borderFocusRingAccent = same(alpha(accent[9], 0.3));
-  const borderFocusRingNeutral = same(alpha(base[9], 0.3));
-  const borderFocusRingDestructive = same(alpha(red[9], 0.3));
-  const textWhiteboardSelectionLockedOrDisabled = [alpha(base[9], 0.5), alpha(baseDark[9], 0.5)] as const;
+  const bgBtnSoftAccentDefault = [accent[3], accentDark[4]] as const;
+
+  const borderFocusRingAccent = alphaDef(same(accent[9]), A.border.focusRing);
+  const borderFocusRingNeutral = alphaDef(same(base[9]), A.border.focusRing);
+  const borderFocusRingDestructive = alphaDef(same(red[9]), A.border.focusRing);
+  const textWhiteboardSelectionLockedOrDisabled = alphaPair(base[9], baseDark[9], A.whiteboard.lockedOrDisabled);
 
+  const fgSelection = alphaPair(accent[9], accentDark[9], A.interactiveFill.selection);
   const fgSelectedText = same(base[2]);
-  const fgSolidActiveText = same(alpha(white, 0.8));
+  const fgSolidActiveText = alphaDef(same(white), A.foreground.solidActiveText);
 
-  const codeOrErrorMessage = [red[9], red[8]] as const; // TODO check: lack of redDark scale usage
+  const codeOrErrorMessage = [red[9], red[8]] as const;
   const errorIndicatorColor = same(red[8]);
   const neutralStrong = same(base[11]);
-  // end(TODO shake it)
 
   const bgActionsMenu = raised.level1;
   const bgActionsMenuItemHover = surface.level4_5;
@@ -384,7 +423,7 @@ export function defsFromPalette({
 
   const iconFromFg = (fg: string): {fg: Def; bg: Def} => ({
     fg: deneutralize(same(fg)),
-    bg: deneutralize(same(alpha(fg, 0.2))),
+    bg: deneutralize(alphaDef(same(fg), A.interactiveFill.iconBackground)),
   });
 
   const iconMySpace = iconFromFg(Swatch.Grey);
@@ -395,6 +434,7 @@ export function defsFromPalette({
   const fns = createColorFns(deneutralizeFilterDef, {
     icon: fg.icon,
     adapt: surface.level0,
+    avatarPlaceholder: surface.level0,
     highlight: surface.level0,
     callout: surface.level0,
     enum: enumDefs,
@@ -405,49 +445,60 @@ export function defsFromPalette({
     ...highlightColors(highlight, surface.level0, deneutralizeFilterDef),
     colorPickerCssFilter: mapDef(deneutralizeFilterSpec, same(cssFromFilter)),
 
-    mode: ["light", "dark"],
-
     // Accent background tints (light → strong)
-    colorAccentBgSubtle: same(alpha(accent[9], 0.1)),
-    colorAccentBgMild: same(alpha(accent[9], 0.15)),
-    colorAccentBgMedium: same(alpha(accent[9], 0.2)),
-    colorAccentBgStrong: same(alpha(accent[9], 0.3)),
-    colorAccentBgBold: same(alpha(accent[9], 0.35)),
-    colorAccentBgVivid: same(alpha(accent[9], 0.6)),
+    colorAccentBgSubtle: alphaDef(same(accent[9]), A.interactiveFill.accentSubtle),
+    colorAccentBgMild: alphaDef(same(accent[9]), A.interactiveFill.accentMild),
+    colorAccentBgMedium: alphaDef(same(accent[9]), A.interactiveFill.accentMedium),
+    colorAccentBgStrong: alphaDef(same(accent[9]), A.interactiveFill.accentStrong),
+    colorAccentBgBold: alphaDef(same(accent[9]), A.interactiveFill.accentBold),
+    colorAccentBgVivid: alphaDef(same(accent[9]), A.interactiveFill.accentVivid),
 
     // Accent strokes
-    colorAccentStroke: same(alpha(accent[9], 0.25)),
-    colorAccentStrokeHover: same(alpha(accent[9], 0.4)),
-    colorAccentStrokeFocus: same(alpha(accent[9], 0.5)),
+    colorAccentStroke: alphaDef(same(accent[9]), A.interactiveFill.accentStroke),
+    colorAccentStrokeHover: alphaDef(same(accent[9]), A.interactiveFill.accentStrokeHover),
+    colorAccentStrokeFocus: alphaDef(same(accent[9]), A.interactiveFill.accentStrokeFocus),
 
     // Accent solid
-    colorAccentSolid: same(alpha(accent[9], 0.8)),
+    colorAccentSolid: alphaDef(same(accent[9]), A.interactiveFill.accentSolid),
 
     // Accent base
     colorAccent: primary.accent,
 
-    // Rubbish dump
-    /** @deprecated */
+    //to be sorted. these are still in use
     darkenPrimary: same(getDarkenColor(accent[9])),
     whiteColor,
     blackColor,
-    mainBg: surface.level3exotic,
+    mainBg: surface.level3,
     panelBg: surface.level0,
+    panelBorder: both(stroke1)(alphaPair(base[8], baseDark[8], A.border.panel)),
     panelContentBg: surface.level2_1,
-    colorBgRelationContainer: surface.level2_1,
+
+    //Database settings screens
+    dbSettingsSidebarBg: surface.level2,
+    dbSettingsSidebarItemHover: surface.level4,
+    dbSettingsSidebarIconBg: raised.level1,
+    dbSettingsSidebarIconBorder: shadowMenuHeaderAvatar,
+
+    dbSettingsCardBg: surface.level2,
+    dbSettingsCardBorder: both(stroke1)(alphaPair(base[6], baseDark[6], A.border.dbSettingsCard)),
+    colorBgRelationContainer: surface.level1_1,
 
     // AI colors
     colorAI: fg.ai,
-    colorBgAI: mapDef(fg.ai, (color) => alpha(color, 0.1)),
+    colorBgAI: mapDef(fg.ai, (color, side) => alpha(color, A.utility.aiBg[side])),
 
     colorBgAIFloatingLauncher: surface.level1_4,
     colorBgAIFloatingPanelContent: surface.level1_3,
     colorBgAISidebarContent: surface.level1,
 
+    // Floating panels (hover action toolbars, selection toolbar, rich-text format bar)
+    colorBgFloatingPanel: floatingPanel.bg,
+    shadowFloatingPanel: floatingPanel.shadow,
+
     // Other colors
     pageContentBg: surface.level0elevated,
-    colorBgPopup: raised.level2,
-    menuBg: surface.level3exotic,
+    colorBgPopup: [white, baseDark[3]],
+    menuBg: surface.level3,
     menuTextColor: fgMenuEtc,
     menuItemHoverColor: base5_6,
     menuSelectedTextColor: fgSelectedText,
@@ -462,9 +513,9 @@ export function defsFromPalette({
     inversedTextColor: surface.level3_6,
     colorTextSecondary: fg.secondary,
     linkColor: fg.link,
-    linkBorder: mapDef(fg.link, (color) => separator(alpha(color, 0.4))),
+    linkBorder: mapDef(fg.link, (color, side) => separator(alpha(color, A.border.link[side]))),
     linkHoverColor: fg.link,
-    linkBorderHover: mapDef(fg.link, (color) => separator(alpha(color, 0.75))),
+    linkBorderHover: mapDef(fg.link, (color, side) => separator(alpha(color, A.border.linkHover[side]))),
     codeColor: codeOrErrorMessage,
     codeBgColor: surface.level3_4,
     codeBlockBgColor: surface.level3_4,
@@ -473,16 +524,16 @@ export function defsFromPalette({
 
     // Entity
     entityNodeColor: [baseDark[3], base[8]],
-    entityNodeBorder: [separator(alpha(baseDark[3], 0.3)), separator(alpha(base[8], 0.4))],
+    entityNodeBorder: both(separator)(alphaPair(baseDark[3], base[8], A.border.entityNode)),
     entityNodeHoverColor: [baseDark[7], base[7]],
-    entityNodeBorderHover: [separator(alpha(base[11], 0.8)), separator(alpha(base[7], 0.8))],
+    entityNodeBorderHover: both(separator)(alphaPair(base[11], base[7], A.border.entityNodeHover)),
     entityNodeBgColor: surface.level2_3,
     shortcutTextColor: [base[9], baseDark[11]],
-    shortcutBorder: [border1(alpha(base[8], 0.5)), border1(alpha(baseDark[10], 0.2))],
-    shortcutBorderColor: [alpha(base[8], 0.5), alpha(baseDark[10], 0.2)],
+    shortcutBorder: both(border1)(alphaPair(base[8], baseDark[10], A.border.shortcut)),
+    shortcutBorderColor: alphaPair(base[8], baseDark[10], A.border.shortcut),
 
     // Input
-    inputBgColor: surface.level0elevated,
+    inputBgColor: [white, baseDark[1]],
     inputDisabledBgColor: base6_6_opacity30,
     inputDisabledBorderColor: inputStrokes.disabled,
     inputCopyBgColor: surface.level3_4,
@@ -496,6 +547,7 @@ export function defsFromPalette({
     inputErrorBorderFocusColor: inputStrokes.errorFocus,
     inputErrorBorderFocusShadow: inputStrokes.errorFocusRing,
     inputBorderWarningColor: inputStrokes.warning,
+    //buttons and checkboxes and blockquote (why?)
     buttonPrimaryColor: primary.accent,
     buttonColor: fgAccentText,
     buttonPrimaryTextColor: [base[2], base[6]],
@@ -506,17 +558,17 @@ export function defsFromPalette({
     colorBgActionsMenu: bgActionsMenu,
     colorBgActionsMenuItemHover: bgActionsMenuItemHover,
     colorBgActionsMenuItemSelected: bgBtnGhostAccentHover,
-    colorBgActionsMenuItemSelectedHover: [alpha(accent[5], 0.8), alpha(accentDark[6], 0.8)],
-    colorBgActionsMenuItemDangerHover: [alpha(red[9], 0.1), alpha(redDark[10], 0.1)],
-    colorBgActionsMenuItemDangerActive: [alpha(red[9], 0.8), alpha(redDark[10], 0.8)],
+    colorBgActionsMenuItemSelectedHover: alphaPair(accent[5], accentDark[6], A.actionMenu.selectedHover),
+    colorBgActionsMenuItemDangerHover: alphaPair(red[9], redDark[10], A.actionMenu.dangerHover),
+    colorBgActionsMenuItemDangerActive: alphaPair(red[9], redDark[10], A.actionMenu.dangerActive),
     actionMenuBg: bgActionsMenu,
     actionMenuInnerBg: raised.level2,
     actionMenuHover: bgActionsMenuItemHover,
-    actionMenuInnerHover: [base[4], alpha(baseDark[6], 0.5)],
+    actionMenuInnerHover: [base[4], alpha(baseDark[6], A.actionMenu.innerHoverDark[1])],
     actionMenuButtonColor: surface.level0elevated,
     actionMenuButtonHoverColor: surface.level1_3,
     actionMenuButtonShadow: cardShadows.subtle,
-    actionMenuSeparatorColor: [alpha(black, 0.1), alpha(white, 0.15)],
+    actionMenuSeparatorColor: alphaPair(black, white, A.actionMenu.separator),
     separatorColor: blackA10,
     separatorColorDimmed: blackA5,
     separatorBreadcrumbsColor: base8,
@@ -552,9 +604,10 @@ export function defsFromPalette({
     shadowCardInset: [`inset ${inputStrokes.default[0]}`, `inset ${inputStrokes.default[1]}`],
 
     iconColor: fg.icon,
-    appIconColor: [alpha(base[2], 0.9), alpha(base[2], 0.7)],
-    appIconBgColor: [alpha(base[1], 0.9), alpha(base[2], 0.5)],
-    mentionBgColor: [alpha(base[7], 0.3), alpha(baseDark[7], 0.4)],
+    colorIconDestructive: fg.destructive,
+    appIconColor: alphaPair(base[2], base[2], A.iconAndMention.appIconFg),
+    appIconBgColor: alphaPair(base[1], base[2], A.iconAndMention.appIconBg),
+    mentionBgColor: alphaPair(base[7], baseDark[7], A.iconAndMention.mentionBg),
     colorBgSelectMenu: surface.level1_3,
     shadowSelectMenu: floatingShadows.popup,
     colorBgListItemGeneral: transparentAlways,
@@ -570,7 +623,8 @@ export function defsFromPalette({
 
     // Search
     colorSearchSubtitle: fg.muted,
-    colorBgSearchRowHover: bgActionsMenuItemHover,
+    colorBgSearchPanel: [white, baseDark[2]],
+    colorBgSearchRowHover: [base[4], baseDark[3]],
     colorBgSearchRowCreateHover: [accent[4], accentDark[4]],
     opacitySearchItemDone: opacities.drag,
 
@@ -618,7 +672,7 @@ export function defsFromPalette({
     entityCardDoneColor: bgEntityCardDone,
     entityCardShadow: cardShadows.subtle,
     entityCardShadowHover: cardShadows.subtle,
-    colorBgSegmentedControl: [alpha(base[5], 0.8), alpha(baseDark[3], 0.8)],
+    colorBgSegmentedControl: alphaPair(base[5], baseDark[2], A.segmentedControl.track),
     colorBgMenuHeaderAvatar: surface.level0elevated,
     shadowMenuHeaderAvatar: shadowMenuHeaderAvatar,
 
@@ -627,16 +681,16 @@ export function defsFromPalette({
     opacityMenuItemDragged: opacities.drag,
     colorBgMenuItemSelectedDragged: [accent[6], accentDark[6]],
     // Default
-    colorTextMenuItem: [alpha(base[12], 0.9), alpha(baseDark[12], 0.9)],
+    colorTextMenuItem: alphaDef([base[12], baseDark[12]], A.foreground.menuItem),
     colorBgMenuItem: transparentAlways,
     // :hover
-    colorBgMenuItemHover: [base[5], baseDark[2]],
+    colorBgMenuItemHover: [base[5], baseDark[5]],
     // :focus
-    colorBgMenuItemFocus: [base[6], baseDark[5]],
+    colorBgMenuItemFocus: [base[6], baseDark[6]],
     // Selected
-    colorBgMenuItemSelected: [alpha(accent[5], 0.8), accentDark[3]],
+    colorBgMenuItemSelected: [alpha(accent[5], A.menu.selected[0]), accentDark[3]],
     // :hover
-    colorBgMenuItemSelectedHover: [alpha(accent[6], 0.7), accentDark[5]],
+    colorBgMenuItemSelectedHover: [alpha(accent[6], A.menu.selectedHover[0]), accentDark[5]],
     // :focus, :focus:hover
     colorBgPinnedFieldsLabel: fg.neutral,
     colorBgObjectEditorSeparator: fgMenuEtc,
@@ -673,24 +727,24 @@ export function defsFromPalette({
 
     tooltipBgColor: [baseDark[5], baseDark[6]],
     todayMarkerColor: [red[8], redDark[6]],
-    viewBgOverlayColor: [alpha(base[8], 0.2), alpha(baseDark[1], 0.6)],
+    viewBgOverlayColor: alphaPair(base[8], baseDark[1], A.overlay.view),
     floatEditorMenuBg: surface.level1_6,
     floatEditorActiveColor: fg.accent,
     commentColor: warningColor,
     cellBackgroundColor: surface.level2,
     cellBackgroundHoverColor: base6_6_opacity30,
-    cellBorderColor: [alpha(base[8], 0.5), alpha(baseDark[9], 0.5)],
-    cellPinnedBorderColor: [alpha(base[8], 0.7), alpha(baseDark[9], 0.7)],
+    cellBorderColor: alphaPair(base[8], baseDark[9], A.border.cell),
+    cellPinnedBorderColor: alphaPair(base[8], baseDark[9], A.border.cellPinned),
     tableRowWarningColor: warningColor,
-    errorBgColor: [alpha(red[9], 0.2), alpha(redDark[9], 0.6)],
+    errorBgColor: alphaPair(red[9], redDark[9], A.statusFill.error),
     errorTextColor: [red[11], red[7]],
     errorButtonColor: primary.destructive,
-    warningBgColor: [alpha(yellow[6], 0.6), alpha(yellowDark[8], 0.6)],
+    warningBgColor: alphaPair(yellow[6], yellowDark[8], A.statusFill.warning),
     warningButtonColor: fg.warning,
-    infoBox: [alpha(yellow[4], 0.5), alpha(yellowDark[9], 0.2)],
+    infoBox: alphaPair(yellow[4], yellowDark[9], A.statusFill.infoBox),
     appCardBgColor: surface.level0elevated,
-    appCardHoverColor: [alpha(base[1], 0.95), baseDark[2]],
-    modalBg: [alpha(base[11], 0.2), alpha(baseDark[2], 0.5)],
+    appCardHoverColor: [alpha(base[1], A.statusFill.appCardHover[0]), baseDark[2]],
+    modalBg: alphaPair(base[11], baseDark[2], A.overlay.modal),
     modalContentBg: bgActionsMenu,
     progressIconBg: [blackA[7], whiteA[7]],
     progressIconFill: [blackA[11], whiteA[11]],
@@ -700,7 +754,7 @@ export function defsFromPalette({
     filterGroup1Bg: surface.level2_6,
     filterGroup2Bg: surface.level3_7,
     filterGroupBorder: [blackA[3], whiteA[3]],
-    colorBgNotificationHover: surface.level3_4,
+    colorBgNotificationHover: surface.level3_2,
     colorBgNotificationSelected: notificationSelected,
     colorBgNotificationSelectedHover: notificationSelectedHover,
     disabledInversedTextColor: blackA25,
@@ -711,13 +765,13 @@ export function defsFromPalette({
     cardBg: raised.level4,
     selectedImageBorder: [blackA[8], whiteA[11]],
     transparent: transparentAlways,
-    progressBg: same(base[4]), // TODO check if that could be surface.level4?
+    progressBg: same(base[4]),
     progressText: neutralStrong,
     progressFillBg: neutralStrong,
     progressFillText: whiteColor,
-    progressBarFillNeutral: [alpha(base[9], 0.2), alpha(baseDark[9], 0.2)],
+    progressBarFillNeutral: alphaPair(base[9], baseDark[9], A.progress.neutralFill),
     progressBarFill: [accent[9], accentDark[10]],
-    progressBarBg: [alpha(accent[9], 0.25), alpha(accentDark[10], 0.25)],
+    progressBarBg: alphaPair(accent[9], accentDark[10], A.progress.track),
     colorPickerSwatchBorder: same(blackA[7]),
     colorBorderRichTextMedia: same(blackA[7]),
     richTextTableBorder: [blackA[5], whiteA[7]],
@@ -727,12 +781,15 @@ export function defsFromPalette({
 
     // Views
     viewBg: surface.level1,
+    colorBgViewMetaItem: surface.level0elevated,
+    collectionViewBg: surface.level1_1,
+    collectionViewBorder: inputStrokes.disabled,
     viewSecondaryBg: surface.level2,
     viewHighlightBg: viewHighlightBg,
 
     // Board
     boardBg: surface.level1,
-    boardBgWithOpacity80: [alpha(base[1], 0.8), alpha(baseDark[1], 0.8)],
+    boardBgWithOpacity80: alphaPair(base[1], baseDark[1], A.utility.boardBg),
     boardAxisBgHover: surface.level4,
 
     // Grid
@@ -752,25 +809,25 @@ export function defsFromPalette({
     //timeline
     timelineEntityHandleColor: borderAccentOrMedium,
     timelineDependencyHoverBgColor: borderAccentOrMediumAccent,
-    timelineDependencyOverlapBgColor: primary.destructive_TODO,
+    timelineDependencyOverlapBgColor: primary.destructiveBase,
     timelineDependencyOverlapHoverBgColor: fg.destructive,
     timelineCellBgColor: surface.level1,
     timelineCellWeekendBgColor: surface.level2,
     timelineCellTodayBgColor: [accent[4], accentDark[2]],
-    timelineCreateEntityPlaceholderBgColor: [alpha(base[11], 0.2), baseDark[7]],
+    timelineCreateEntityPlaceholderBgColor: [alpha(base[11], A.utility.timelinePlaceholder[0]), baseDark[7]],
 
     // #region buttons
     // solid
     colorBgButtonSolidAccentDefault: primary.accent,
     colorBgButtonSolidAccentHover: [accent[11], accentDark[10]],
     colorBgButtonSolidNeutralDefault: fgMenuEtc,
-    colorBgButtonSolidNeutralHover: [alpha(base[12], 0.85), white],
-    colorBgButtonSolidDestructiveDefault: primary.destructive_TODO,
+    colorBgButtonSolidNeutralHover: [alpha(base[12], A.button.solidNeutralHover[0]), white],
+    colorBgButtonSolidDestructiveDefault: primary.destructiveBase,
     colorBgButtonSolidDestructiveHover: [red[11], redDark[10]],
     colorTextButtonSolidAccent: whiteColor,
     colorTextButtonSolidAccentActive: fgSolidActiveText,
     colorTextButtonSolidNeutral: [white, baseDark[2]],
-    colorTextButtonSolidNeutralActive: [white, alpha(baseDark[2], 0.8)],
+    colorTextButtonSolidNeutralActive: [white, alpha(baseDark[2], A.button.solidNeutralActiveText[1])],
     colorTextButtonSolidDestructive: whiteColor,
     colorTextButtonSolidDestructiveActive: fgSolidActiveText,
     colorIconButtonSolidAccent: whiteColor,
@@ -789,14 +846,14 @@ export function defsFromPalette({
     colorTextButtonOutlineAccent: fg.accent,
     colorTextButtonOutlineAccentActive: fg.accentActive,
     colorTextButtonOutlineNeutral: fg.neutral,
-    colorTextButtonOutlineNeutralActive: fg.neutralActive__TODO,
+    colorTextButtonOutlineNeutralActive: fg.neutralStrongActive,
     colorTextButtonOutlineDestructive: fg.destructive,
     colorTextButtonOutlineDestructiveActive: fg.destructiveActive,
     colorIconButtonOutlineAccent: fg.accent,
     colorIconButtonOutlineNeutral: fg.neutral,
     colorIconButtonOutlineDestructive: fg.destructive,
     // soft
-    colorBgButtonSoftAccentDefault: notificationSelected,
+    colorBgButtonSoftAccentDefault: bgBtnSoftAccentDefault,
     colorBgButtonSoftAccentHover: bgBtnSoftAccentHover,
     colorBgButtonSoftNeutralDefault: bgBtnSoftNeutralDefault,
     colorBgButtonSoftNeutralHover: bgBtnSoftNeutralHover,
@@ -838,10 +895,50 @@ export function defsFromPalette({
     colorBorderReactionsHover: [base[8], baseDark[9]],
     colorBgReactionsSelectedDefault: [accent[3], accentDark[8]],
     colorBorderReactionsSelectedDefault: borderAccentOrMediumAccent,
-    // FIXME: lack of accentDark scale usage
+    // Existing dark hover uses the light accent scale.
     colorBgReactionsSelectedHover: [accent[2], accent[10]],
     colorBorderReactionsSelectedHover: [accent[9], accent[10]],
     colorTextReactionsSelected: [accent[10], baseDark[12]],
+
+    // ToggleButton (reactions, pinned filters)
+    colorBgToggleButtonUnselectedNormal: surface.level0elevated,
+    colorBgToggleButtonUnselectedHover: surface.level3_6,
+    colorBgToggleButtonSelectedNormal: [accent[3], accentDark[8]],
+    colorBgToggleButtonSelectedHover: [accent[2], accent[10]],
+    colorBorderToggleButtonUnselectedNormal: [base[8], baseDark[9]],
+    colorBorderToggleButtonUnselectedHover: [base[8], baseDark[9]],
+    colorBorderToggleButtonSelectedNormal: borderAccentOrMediumAccent,
+    colorBorderToggleButtonSelectedHover: [accent[9], accent[10]],
+    colorTextToggleButtonUnselectedNormal: fg.neutral,
+    colorTextToggleButtonUnselectedHover: fg.neutral,
+    colorTextToggleButtonSelectedNormal: [accent[10], baseDark[12]],
+    colorTextToggleButtonSelectedHover: [accent[10], baseDark[12]],
+    colorIconToggleButtonUnselectedNormal: fg.neutral,
+    colorIconToggleButtonUnselectedHover: fg.neutral,
+    colorIconToggleButtonSelectedNormal: fg.accent,
+    colorIconToggleButtonSelectedHover: fg.accent,
+
+    // RoundToggleButton (capability indicators)
+    colorBgRoundToggleButtonUnselectedNormal: surface.level0elevated,
+    colorBgRoundToggleButtonUnselectedHover: surface.level3_6,
+    colorBgRoundToggleButtonSelectedNormal: [accent[4], accentDark[8]],
+    colorBgRoundToggleButtonSelectedHover: [accent[3], accent[10]],
+
+    colorBorderRoundToggleButtonUnselectedNormal: [base[8], baseDark[9]],
+    colorBorderRoundToggleButtonUnselectedHover: [base[8], baseDark[9]],
+    colorBorderRoundToggleButtonSelectedNormal: borderAccentOrMediumAccent,
+    colorBorderRoundToggleButtonSelectedHover: [accent[9], accent[10]],
+
+    colorTextRoundToggleButtonUnselectedNormal: fg.neutral,
+    colorTextRoundToggleButtonUnselectedHover: fg.neutral,
+    colorTextRoundToggleButtonSelectedNormal: [accent[10], baseDark[12]],
+    colorTextRoundToggleButtonSelectedHover: [accent[10], baseDark[12]],
+
+    colorIconRoundToggleButtonUnselectedNormal: fg.neutral,
+    colorIconRoundToggleButtonUnselectedHover: fg.neutral,
+    colorIconRoundToggleButtonSelectedNormal: fg.accent,
+    colorIconRoundToggleButtonSelectedHover: fg.accent,
+
     colorBgToastDefault: surface.level1,
     colorBgDbTabHover: surface.level3_4,
     colorBgDbTabFocus: bgTabFocus,
@@ -856,7 +953,10 @@ export function defsFromPalette({
     colorTextEntityAvatarHover: primary.accent,
     colorBgMessageHighlighted: surface.level0elevated,
 
-    // Text editor
+    // Comment/message row hover (subtle lift over panel, stays darker than the floating actions toolbar in dark theme)
+    colorBgCommentHover: surface.level2,
+
+    colorBgCodeEditor: raised.level1,
     colorBgEditorImageZoomed: surface.level3_6,
     colorMermaidPrimaryColor: [base[2], baseDark[8]],
     colorMermaidPrimaryBorderColor: fg.muted,
@@ -869,34 +969,31 @@ export function defsFromPalette({
     colorHighlightWhiteboardSelection: borderAccentOrMediumAccent,
     colorHighlightWhiteboardSelectionLocked: textWhiteboardSelectionLockedOrDisabled,
     colorSelectionWhiteboardBorderDisabled: textWhiteboardSelectionLockedOrDisabled,
-    colorPlaceholderWhiteboardDefault: [alpha(accent[8], 0.2), alpha(accentDark[8], 0.2)],
+    colorPlaceholderWhiteboardDefault: alphaPair(accent[8], accentDark[8], A.whiteboard.placeholder),
     colorLinkPointWhiteboardDefault: borderAccentOrMediumAccent,
     colorLinkPointWhiteboardFillDefault: [white, blackish],
-    colorMapWhiteboardPreviewDefault: [alpha(accent[8], 0.4), alpha(accentDark[8], 0.4)],
-    colorCardWhiteboardShadowDefault: [alpha(base[11], 0.05), alpha(baseDark[11], 0.05)],
+    colorMapWhiteboardPreviewDefault: alphaPair(accent[8], accentDark[8], A.whiteboard.mapPreview),
+    colorCardWhiteboardShadowDefault: alphaPair(base[11], baseDark[11], A.whiteboard.cardShadow),
     colorCardWhiteboardBgDefault: raised.level3,
-    colorCardWhiteboardBorderDefault: [alpha(base[12], 0.2), alpha(baseDark[12], 0.2)],
-    colorUnitHeaderWhiteboardDefault: [alpha(base[12], 0.6), alpha(baseDark[12], 0.6)],
+    colorCardWhiteboardBorderDefault: alphaPair(base[12], baseDark[12], A.whiteboard.cardBorder),
+    colorUnitHeaderWhiteboardDefault: alphaPair(base[12], baseDark[12], A.whiteboard.unitHeader),
     colorUnitWhiteboardBgDefault: surface.level3_6,
-    colorUnitWhiteboardBorderDefault: [alpha(base[12], 0.2), alpha(baseDark[12], 0.25)],
+    colorUnitWhiteboardBorderDefault: alphaPair(base[12], baseDark[12], A.whiteboard.unitBorder),
     colorSectionWhiteboardBgInactive: surface.level2,
     colorSectionWhiteboardBorderInactive: bgTabFocus,
-    colorEmbedWhiteboardEditBorder: [alpha(teal[8], 0.9), alpha(tealDark[8], 0.9)],
+    colorUploadPreviewBg: alphaPair(base[11], baseDark[2], A.whiteboard.uploadPreview),
+    colorEmbedWhiteboardEditBorder: alphaPair(teal[8], tealDark[8], A.whiteboard.embedEditBorder),
     colorTextWhiteboardDefault: fgMenuEtc,
     colorTextWhiteboardDisabled: fg.muted,
-    // FIXME bug?
-    //  Dark uses baseDark[1] (near-black at 60% opacity) as "accent text" on a dark background.
-    //  This reads as near-invisible dark text on dark bg.
-    //  Compare with colorUnitHeaderWhiteboardDefault (L772) which correctly uses baseDark[12] for dark.
-    //  Likely should be baseDark[12] too.
-    colorTextWhiteboardAccent: [alpha(base[12], 0.6), alpha(baseDark[1], 0.6)],
+    // Existing dark accent blends into the whiteboard surface.
+    colorTextWhiteboardAccent: alphaPair(base[12], baseDark[1], A.whiteboard.accentText),
     colorTextWhiteboardInversedDefault: whiteColor,
     instrumentsMenuBg: raised.level2,
     instrumentsMenuShadow: floatingShadows.instrumentsMenu,
     commentBubbleBg: raised.level4,
     commentsPanelShadow: floatingShadows.instrumentsMenu,
     searchFiltersBg: surface.level1_1,
-    selectedColorBorder: same(alpha(base[6], 0.25)),
+    selectedColorBorder: alphaDef(same(base[6]), A.border.selectedColor),
 
     // SegmentedControl
     colorBgSegmentedControlDefault: surface.level3_1,
@@ -906,12 +1003,12 @@ export function defsFromPalette({
 
     // Banner
     colorBgBannerNeutral: bg.neutral3,
-    colorBgBannerPrimary: bg.accent3,
+    colorBgBannerAccent: bg.accent3,
     colorBgBannerWarning: bg.warning,
     colorBgBannerError: bg.error,
     colorBgBannerSuccess: bg.success,
 
-    colorIconBannerNeutral: icon.primary,
+    colorIconBannerNeutral: icon.neutral,
     colorIconBannerAccent: icon.accent,
     colorIconBannerWarning: icon.warning,
     colorIconBannerError: icon.error,
@@ -932,8 +1029,8 @@ export function defsFromPalette({
 
     // Logo/illustration specific colors
     colorBorderLogoGrid: surface.level4,
-    colorBorderLogoGridSubtle: [alpha(base[4], 0.2), baseDark[4]],
-    colorBorderLogoGridMedium: [alpha(base[4], 0.4), baseDark[4]],
+    colorBorderLogoGridSubtle: [alpha(base[4], A.utility.logoGridSubtle[0]), baseDark[4]],
+    colorBorderLogoGridMedium: [alpha(base[4], A.utility.logoGridMedium[0]), baseDark[4]],
     colorStrokeLogoDashed: [base[6], baseDark[8]],
     colorBgLogoCardTransparent: surface.level0elevated,
     colorBgLogoCardDark: base8,
@@ -951,7 +1048,7 @@ export function defsFromPalette({
 
     // Elevation shadows (ink direction)
     colorShadowElevation: blackA10,
-    colorShadowOutline: [alpha(black, 0.2), alpha(white, 0.2)],
+    colorShadowOutline: alphaPair(black, white, A.utility.shadowOutline),
 
     // Placeholder/fallback
     colorPlaceholder: whiteA40,
@@ -986,17 +1083,17 @@ export function defsFromPalette({
     whiteA100,
 
     // File hover overlay (always dark scrim for white text readability)
-    colorBgFileOverlay: same(alpha(black, 0.6)),
+    colorBgFileOverlay: alphaDef(same(black), A.overlay.file),
 
     // Scroll fade edges
-    colorBgScrollFade: [alpha(white, 0.15), alpha(black, 0.15)],
+    colorBgScrollFade: alphaPair(white, black, A.utility.scrollFade),
 
     // Date picker selected outline
-    colorStrokeSelectedOutline: [alpha(black, 0.75), alpha(white, 0.75)],
+    colorStrokeSelectedOutline: alphaPair(black, white, A.utility.selectedOutline),
 
     // Preloader / chrome
-    scrollbar: [alpha(base[9], 0.5), alpha(baseDark[7], 0.5)],
-  } as const satisfies ThemeColorsDef;
+    scrollbar: alphaPair(base[9], baseDark[7], A.utility.scrollbar),
+  } as const satisfies Record<string, Def>;
 
   return {key, colors, fns} as const;
 }