From 018e2b93b4655cdab8d645dbd829bc0d73a9ef8f Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Mon, 10 Aug 2026 19:37:32 +0200
Subject: [PATCH 1/2] feat(core): color a dock-bar entry's badge via a new
 badgeVariant field
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DockEntry's badge has always been a plain count with a fixed gray fill — no
way to distinguish, at a glance, "this count is provisional" from "this is
the settled value". json-render's own Tabs component already solved this one
level down (TabDescriptor.badgeVariant, with a real variant→color map); this
carries that same variant set up to the dock-bar entry itself.

badgeVariant is declared via the existing DevframeDockEntryRegistry
declaration-merge pattern this package already uses, staying optional so
every existing badge consumer keeps its current look unchanged. DockEntry.vue
falls back to its pre-existing bg-gray-6/text-white classes at 'default'/
unset, and only switches to an inline-styled fill (reusing Tabs.ts's own
colors map) for a non-default variant.
---
 .../components/dock/DockEntries.vue           |  1 +
 .../components/dock/DockEntry.stories.ts      |  7 +++++++
 .../components/dock/DockEntry.vue             | 19 +++++++++++++++++--
 packages/kit/src/types/docks.ts               | 14 ++++++++++++++
 .../@vitejs/devtools-kit/index.snapshot.d.ts  |  1 +
 5 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntries.vue b/packages/core/src/client/webcomponents/components/dock/DockEntries.vue
index 299d628e3..c67ccf1f4 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntries.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntries.vue
@@ -77,6 +77,7 @@ function toggleDockEntry(dock: DevToolsDockEntry) {
         :is-dimmed="dimInactive && selected ? (selected.id !== dock.id) : false"
         :is-vertical="isVertical"
         :badge="dock.badge"
+        :badge-variant="dock.badgeVariant"
         @click="toggleDockEntry(dock)"
       />
     </template>
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts b/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts
index 5eca60252..07642fc68 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts
@@ -12,6 +12,7 @@ interface EntryArgs {
   isVertical?: boolean
   isAction?: boolean
   badge?: string
+  badgeVariant?: 'default' | 'info' | 'success' | 'warning' | 'danger'
   tooltip?: boolean
 }
 
@@ -43,6 +44,7 @@ const meta = {
         isVertical: args.isVertical,
         isAction: args.isAction,
         badge: args.badge || undefined,
+        badgeVariant: args.badgeVariant,
         tooltip: args.tooltip,
       }))),
     ),
@@ -67,6 +69,9 @@ export const Action: Story = { args: { isAction: true } }
 /** A count badge in the corner (e.g. pending items). */
 export const WithBadge: Story = { args: { badge: '3' } }
 
+/** A colored badge — e.g. a staged-but-unapplied override count, warning-orange until it reloads. */
+export const WithBadgeVariant: Story = { args: { badge: '3', badgeVariant: 'warning' } }
+
 /** Rotated for a left/right edge dock. */
 export const Vertical: Story = { args: { isVertical: true } }
 
@@ -81,6 +86,8 @@ export const States: Story = {
         h(DockEntry, { context: ctx, dock: sample, isDimmed: true }),
         h(DockEntry, { context: ctx, dock: sample, isAction: true }),
         h(DockEntry, { context: ctx, dock: sample, badge: '9+' }),
+        h(DockEntry, { context: ctx, dock: sample, badge: '2', badgeVariant: 'warning' }),
+        h(DockEntry, { context: ctx, dock: sample, badge: '5', badgeVariant: 'success' }),
       ])),
     ),
   }),
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntry.vue b/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
index a94574bd6..9546a8031 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
@@ -1,8 +1,9 @@
 <script setup lang="ts">
-import type { DevToolsDockEntryBase } from '@vitejs/devtools-kit'
+import type { DevToolsDockBadgeVariant, DevToolsDockEntryBase } from '@vitejs/devtools-kit'
 import type { DocksContext } from '@vitejs/devtools-kit/client'
 import { useEventListener } from '@vueuse/core'
 import { computed, useTemplateRef } from 'vue'
+import { colors } from '../../json-render/components/tokens'
 import { setFloatingTooltip } from '../../state/floating-tooltip'
 import { accentTextStyle } from '../../utils/accent-color'
 import { openDockContextMenu } from './DockContextMenu'
@@ -17,6 +18,7 @@ const props = withDefaults(
     isDimmed?: boolean
     isVertical?: boolean
     badge?: string
+    badgeVariant?: DevToolsDockBadgeVariant
     tooltip?: boolean
     /** A `group` entry's optional `accentColor`, applied while selected/active. */
     accentColor?: string
@@ -29,6 +31,14 @@ const props = withDefaults(
 // Only kicks in while selected — an idle group button keeps its default look.
 const accentStyle = computed(() => (props.isSelected ? accentTextStyle(props.accentColor) : undefined))
 
+/** `undefined` (the existing `bg-gray-6 text-white` utility classes below) at `'default'`/unset — every pre-existing badge consumer keeps its current look, unchanged. */
+const badgeStyle = computed(() => {
+  if (!props.badgeVariant || props.badgeVariant === 'default')
+    return undefined
+  const { bg, fg } = colors[props.badgeVariant]
+  return { backgroundColor: bg, color: fg }
+})
+
 const button = useTemplateRef<HTMLButtonElement>('button')
 
 function updateTooltip() {
@@ -94,7 +104,12 @@ useEventListener('pointerdown', () => {
       class="flex items-center justify-center p1.5 hover:bg-[#8881] hover:scale-110 transition-all duration-300 relative outline-none"
     >
       <DockIcon :icon="dock.icon" class="w-5 h-5 select-none" />
-      <div v-if="badge" class="absolute top-0.5 right-0 bg-gray-6 text-white text-0.6em px-1 rounded-full shadow">
+      <div
+        v-if="badge"
+        class="absolute top-0.5 right-0 text-0.6em px-1 rounded-full shadow"
+        :class="badgeStyle ? '' : 'bg-gray-6 text-white'"
+        :style="badgeStyle"
+      >
         {{ badge }}
       </div>
     </button>
diff --git a/packages/kit/src/types/docks.ts b/packages/kit/src/types/docks.ts
index 98686dc83..4359d465d 100644
--- a/packages/kit/src/types/docks.ts
+++ b/packages/kit/src/types/docks.ts
@@ -43,8 +43,22 @@ declare module '@devframes/hub/types' {
   interface DevframeDockEntryRegistry {
     'json-render': DevToolsViewJsonRender
   }
+  interface DevframeDockEntryBase {
+    /**
+     * Colors {@link DevframeDockEntryBase.badge} on the dock bar itself — the same variant set
+     * json-render's own `Tabs` badge already uses ({@link DevToolsDockBadgeVariant}), applied one
+     * level up. Omitted (or `'default'`) leaves the badge at its existing neutral fill.
+     */
+    badgeVariant?: DevToolsDockBadgeVariant
+  }
 }
 
+/**
+ * Color for a dock-bar entry's badge — mirrors json-render's `TabDescriptor.badgeVariant`
+ * (`components/Tabs.ts`), so a dock can reuse the exact same variant→color mapping one level up.
+ */
+export type DevToolsDockBadgeVariant = 'default' | 'info' | 'success' | 'warning' | 'danger'
+
 /**
  * A selectable launch root offered by a launcher dock entry.
  *
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
index c05eb04dc..742f1344b 100644
--- a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
+++ b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
@@ -52,6 +52,7 @@ export interface ViteDevToolsNodeContext extends KitNodeContext {
 // #endregion
 
 // #region Types
+export type DevToolsDockBadgeVariant = 'default' | 'info' | 'success' | 'warning' | 'danger';
 export type DevToolsDockEntryCategory = DevframeDockEntryCategory;
 export type JsonRenderElement = UIElement;
 export type JsonRenderSpec = DevframeJsonRenderSpec;

From 81200685f0733dd17fc8de1a14ad074dfc2e39f1 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Mon, 10 Aug 2026 20:32:36 +0200
Subject: [PATCH 2/2] fix(core): boost badgeVariant contrast on the dock bar,
 trim doc comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The tab-badge fill (colors[variant].bg, alpha 0.15) read as too faint
reused on the dock bar — boosted via CSS relative-color syntax instead of
adding a second color table.
---
 .../components/dock/DockEntry.stories.ts              |  2 +-
 .../webcomponents/components/dock/DockEntry.vue       |  4 ++--
 packages/kit/src/types/docks.ts                       | 11 ++---------
 3 files changed, 5 insertions(+), 12 deletions(-)

diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts b/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts
index 07642fc68..0bfc60ace 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntry.stories.ts
@@ -69,7 +69,7 @@ export const Action: Story = { args: { isAction: true } }
 /** A count badge in the corner (e.g. pending items). */
 export const WithBadge: Story = { args: { badge: '3' } }
 
-/** A colored badge — e.g. a staged-but-unapplied override count, warning-orange until it reloads. */
+/** A colored badge, e.g. flagging a state that needs attention. */
 export const WithBadgeVariant: Story = { args: { badge: '3', badgeVariant: 'warning' } }
 
 /** Rotated for a left/right edge dock. */
diff --git a/packages/core/src/client/webcomponents/components/dock/DockEntry.vue b/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
index 9546a8031..e095b3986 100644
--- a/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
+++ b/packages/core/src/client/webcomponents/components/dock/DockEntry.vue
@@ -31,12 +31,12 @@ const props = withDefaults(
 // Only kicks in while selected — an idle group button keeps its default look.
 const accentStyle = computed(() => (props.isSelected ? accentTextStyle(props.accentColor) : undefined))
 
-/** `undefined` (the existing `bg-gray-6 text-white` utility classes below) at `'default'`/unset — every pre-existing badge consumer keeps its current look, unchanged. */
+/** `undefined` at `'default'`/unset keeps the existing `bg-gray-6 text-white` classes below. `colors[variant].bg`'s alpha is tuned for a tab badge, so it's boosted here for better contrast on the dock bar. */
 const badgeStyle = computed(() => {
   if (!props.badgeVariant || props.badgeVariant === 'default')
     return undefined
   const { bg, fg } = colors[props.badgeVariant]
-  return { backgroundColor: bg, color: fg }
+  return { backgroundColor: `rgba(from ${bg} r g b / 0.35)`, color: fg }
 })
 
 const button = useTemplateRef<HTMLButtonElement>('button')
diff --git a/packages/kit/src/types/docks.ts b/packages/kit/src/types/docks.ts
index 4359d465d..99d56d33d 100644
--- a/packages/kit/src/types/docks.ts
+++ b/packages/kit/src/types/docks.ts
@@ -44,19 +44,12 @@ declare module '@devframes/hub/types' {
     'json-render': DevToolsViewJsonRender
   }
   interface DevframeDockEntryBase {
-    /**
-     * Colors {@link DevframeDockEntryBase.badge} on the dock bar itself — the same variant set
-     * json-render's own `Tabs` badge already uses ({@link DevToolsDockBadgeVariant}), applied one
-     * level up. Omitted (or `'default'`) leaves the badge at its existing neutral fill.
-     */
+    /** Colors {@link DevframeDockEntryBase.badge}. Omitted (or `'default'`) keeps the existing neutral fill. */
     badgeVariant?: DevToolsDockBadgeVariant
   }
 }
 
-/**
- * Color for a dock-bar entry's badge — mirrors json-render's `TabDescriptor.badgeVariant`
- * (`components/Tabs.ts`), so a dock can reuse the exact same variant→color mapping one level up.
- */
+/** Color for a dock-bar entry's badge — mirrors json-render's `TabDescriptor.badgeVariant`. */
 export type DevToolsDockBadgeVariant = 'default' | 'info' | 'success' | 'warning' | 'danger'
 
 /**