@beyondwork/docx-react-component 1.0.53 → 1.0.54

package/src/ui-tailwind/theme/editor-theme.css

@@ -587,6 +587,14 @@
 .wre-scope-rail-stripe.wre-scope-rail-label-secondary { color: var(--color-secondary); }
 .wre-scope-rail-stripe.wre-scope-rail-label-danger { color: var(--color-danger); }
 
+/* §3.7 canonical scope families — stripe color */
+.wre-scope-rail-stripe.wre-scope-rail-tint-blocked   { background: var(--color-scope-tint-blocked); }
+.wre-scope-rail-stripe.wre-scope-rail-tint-in-scope  { background: var(--color-scope-tint-in-scope); }
+.wre-scope-rail-stripe.wre-scope-rail-tint-suggest   { background: var(--color-scope-tint-suggest); }
+.wre-scope-rail-stripe.wre-scope-rail-tint-comment   { background: var(--color-scope-tint-comment); }
+.wre-scope-rail-stripe.wre-scope-rail-tint-scheduled { background: var(--color-scope-tint-scheduled); }
+.wre-scope-rail-stripe.wre-scope-rail-tint-proposed  { background: var(--color-scope-tint-proposed); }
+
 /*
  * ─── Scope rail label pill ───
  *
@@ -652,6 +660,38 @@
   background: color-mix(in srgb, var(--color-danger) 8%, var(--color-canvas, #fff));
 }
 
+/* §3.7 canonical scope families — label pill */
+.wre-scope-rail-label-blocked {
+  color: var(--color-semantic-error);
+  border-color: color-mix(in srgb, var(--color-semantic-error) 40%, transparent);
+  background: color-mix(in srgb, var(--color-semantic-error) 8%, var(--color-canvas, #fff));
+}
+.wre-scope-rail-label-suggest {
+  color: var(--color-semantic-warning);
+  border-color: color-mix(in srgb, var(--color-semantic-warning) 42%, transparent);
+  background: color-mix(in srgb, var(--color-semantic-warning) 8%, var(--color-canvas, #fff));
+}
+.wre-scope-rail-label-scheduled {
+  color: var(--color-semantic-info);
+  border-color: color-mix(in srgb, var(--color-semantic-info) 40%, transparent);
+  background: color-mix(in srgb, var(--color-semantic-info) 8%, var(--color-canvas, #fff));
+}
+.wre-scope-rail-label-comment {
+  color: var(--color-accent-primary);
+  border-color: color-mix(in srgb, var(--color-accent-primary) 40%, transparent);
+  background: color-mix(in srgb, var(--color-accent-primary) 8%, var(--color-canvas, #fff));
+}
+.wre-scope-rail-label-in-scope {
+  color: var(--color-accent-primary);
+  border-color: color-mix(in srgb, var(--color-accent-primary) 40%, transparent);
+  background: color-mix(in srgb, var(--color-accent-primary) 8%, var(--color-canvas, #fff));
+}
+.wre-scope-rail-label-proposed {
+  color: var(--color-accent-primary);
+  border-color: color-mix(in srgb, var(--color-accent-primary) 40%, transparent);
+  background: color-mix(in srgb, var(--color-accent-primary) 8%, var(--color-canvas, #fff));
+}
+
 .wre-scope-rail-label-active {
   box-shadow: 0 0 0 1px color-mix(in srgb, currentColor 30%, transparent);
 }
@@ -784,10 +824,14 @@
  * — consumers pick whichever matches their payload shape.
  */
 .wre-rail-card {
+  --wre-rail-card-edge: var(--color-border-default);
+  --wre-rail-card-eyebrow: var(--color-text-tertiary);
   position: relative;
-  border-radius: var(--radius-card);
-  background: var(--color-surface);
-  border: 1px solid color-mix(in srgb, var(--color-border) 80%, transparent);
+  border-radius: var(--radius-lg);
+  background: var(--color-bg-elevated);
+  border: 1px solid var(--color-border-subtle);
+  border-left: 3px solid var(--wre-rail-card-edge);
+  box-shadow: var(--shadow-soft);
   padding: 14px 16px 16px;
   overflow: hidden;
   transition: background-color var(--motion-fast) ease-out,
@@ -812,34 +856,23 @@
 }
 
 .wre-rail-card[data-tone="inReview"] {
-  --wre-rail-card-edge: var(--color-accent);
-  --wre-rail-card-eyebrow: var(--color-accent);
-  --wre-rail-card-progress-fill: var(--color-accent);
+  --wre-rail-card-edge: var(--color-semantic-warning);
+  --wre-rail-card-eyebrow: var(--color-semantic-warning);
 }
 
 .wre-rail-card[data-tone="blocked"] {
-  --wre-rail-card-edge: var(--color-danger);
-  --wre-rail-card-eyebrow: var(--color-danger);
-  --wre-rail-card-progress-fill: var(--color-danger);
-  background: color-mix(in srgb, var(--color-danger-soft) 75%, var(--color-surface));
+  --wre-rail-card-edge: var(--color-semantic-error);
+  --wre-rail-card-eyebrow: var(--color-semantic-error);
 }
 
 .wre-rail-card[data-tone="scheduled"] {
-  --wre-rail-card-edge: var(--color-tertiary);
-  --wre-rail-card-eyebrow: var(--color-tertiary);
-  --wre-rail-card-progress-fill: var(--color-tertiary);
+  --wre-rail-card-edge: var(--color-semantic-info);
+  --wre-rail-card-eyebrow: var(--color-semantic-info);
 }
 
 .wre-rail-card[data-tone="resolved"] {
-  --wre-rail-card-edge: var(--color-success);
-  --wre-rail-card-eyebrow: var(--color-success);
-  --wre-rail-card-progress-fill: var(--color-success);
-}
-
-.wre-rail-card[data-tone="neutral"] {
-  --wre-rail-card-edge: var(--color-border-strong);
-  --wre-rail-card-eyebrow: var(--color-tertiary);
-  --wre-rail-card-progress-fill: var(--color-secondary);
+  --wre-rail-card-edge: var(--color-semantic-success);
+  --wre-rail-card-eyebrow: var(--color-semantic-success);
 }
 
 .wre-rail-card__eyebrow {
@@ -1009,3 +1042,197 @@
   color: var(--color-primary);
   background: color-mix(in srgb, var(--color-accent-soft) 80%, var(--color-subtle));
 }
+
+/*
+ * Lane 6d — Slice U1 (L8 Phase E): active H/F band chrome.
+ *
+ * Idle bands sit at 0.6 opacity so the header/footer content is
+ * visible but doesn't compete with the body; hover bumps to 0.85; the
+ * active band goes to full opacity and gains a 3 px accent ribbon
+ * across its top edge plus a floating "Header — Section N" label in
+ * the top-left corner so reviewers always know which band they are
+ * editing when a section break changes the chrome.
+ *
+ * When any H/F story is active the chrome layer's root carries
+ * `data-story-active="header|footer"` and the body PM surface dims to
+ * 0.65 so the active band reads as the focal surface.
+ */
+.wre-page-band {
+  opacity: 0.6;
+  transition: opacity var(--motion-fast, 120ms) ease-out;
+  pointer-events: auto;
+}
+
+.wre-page-band:hover {
+  opacity: 0.85;
+}
+
+.wre-page-band[data-active="true"] {
+  opacity: 1;
+}
+
+.wre-page-band[data-active="true"]::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 3px;
+  background: var(--color-accent);
+  border-radius: 0 0 var(--radius-pill) var(--radius-pill);
+  pointer-events: none;
+}
+
+.wre-page-band__label {
+  position: absolute;
+  top: 6px;
+  left: 10px;
+  font-size: 10px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--color-accent);
+  background: var(--color-surface);
+  padding: 2px 8px;
+  border-radius: var(--radius-pill);
+  box-shadow: var(--shadow-soft);
+  pointer-events: none;
+  z-index: 1;
+}
+
+[data-page-stack-chrome-layer][data-story-active="header"]
+  ~ [data-pm-body-slot],
+[data-page-stack-chrome-layer][data-story-active="footer"]
+  ~ [data-pm-body-slot] {
+  opacity: 0.65;
+  transition: opacity var(--motion-fast, 120ms) ease-out;
+}
+
+/*
+ * Lane 6d — Slice S2: print variant.
+ *
+ * At print time, collapse all editor chrome (toolbar, rails, overlays,
+ * page-break spacers, dock chrome) and let the browser paginate the
+ * paper cards one per physical sheet.  Intentionally no `@page` rule —
+ * the browser's print dialog owns paper size / margins so the host
+ * application doesn't need to fight it.
+ */
+@media print {
+  .wre-toolbar,
+  .wre-status-bar,
+  .wre-review-rail,
+  .wre-scope-rail-layer,
+  .wre-page-chrome-widget,
+  .wre-workspace-dock,
+  .wre-mode-dock,
+  [data-chrome-overlay],
+  [data-pin-surface] {
+    display: none !important;
+  }
+
+  [data-paper-frame] {
+    box-shadow: none !important;
+    border: none !important;
+    border-radius: 0 !important;
+    margin: 0 !important;
+    zoom: 1 !important;
+    page-break-after: always;
+  }
+
+  [data-paper-frame]:last-child {
+    page-break-after: auto;
+  }
+
+  .wre-page-surface {
+    color: #000;
+    background: #fff;
+  }
+}
+
+/*
+ * §6.23 — Scrollbar grammar (Lane 6c.S10)
+ * Thin track, thumb low-contrast until hover. Consistent across
+ * rail, long popovers, and the health panel.
+ * Scoped to the editor root class to avoid leaking into host chrome.
+ */
+.wre-editor ::-webkit-scrollbar,
+.wre-editor *::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+.wre-editor ::-webkit-scrollbar-track,
+.wre-editor *::-webkit-scrollbar-track {
+  background: transparent;
+}
+.wre-editor ::-webkit-scrollbar-thumb,
+.wre-editor *::-webkit-scrollbar-thumb {
+  background: var(--color-border-default);
+  border-radius: 9999px;
+}
+.wre-editor ::-webkit-scrollbar-thumb:hover,
+.wre-editor *::-webkit-scrollbar-thumb:hover {
+  background: var(--color-border-strong);
+}
+.wre-editor,
+.wre-editor * {
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-border-default) transparent;
+}
+
+/*
+ * §6.9 — Table grip hit area + affordance (Lane 6c.U8 / Commit C18)
+ *
+ * Visual stripe is 2 px; hit area is extended to 8 px via ::before pseudo-
+ * element (3 px pad each side). On coarse-pointer devices the ::before extends
+ * to 44 px total for WCAG 2.5.5 touch-target compliance.
+ *
+ * State cascade:
+ *   default  → transparent background (invisible, pointer affordance only)
+ *   hover    → --color-border-default  (subtle stripe appears)
+ *   active   → --color-accent-primary  (vivid stripe during drag)
+ */
+.wre-table-grip-col {
+  position: absolute;
+  width: 2px;
+  background: transparent;
+  cursor: col-resize;
+  transition: background 75ms ease;
+}
+.wre-table-grip-col::before {
+  content: "";
+  position: absolute;
+  inset: 0 -3px;
+}
+.wre-table-grip-col:hover {
+  background: var(--color-border-default);
+}
+.wre-table-grip-col[data-active="true"] {
+  background: var(--color-accent-primary);
+}
+
+.wre-table-grip-row {
+  position: absolute;
+  height: 2px;
+  background: transparent;
+  cursor: row-resize;
+  transition: background 75ms ease;
+}
+.wre-table-grip-row::before {
+  content: "";
+  position: absolute;
+  inset: -3px 0;
+}
+.wre-table-grip-row:hover {
+  background: var(--color-border-default);
+}
+.wre-table-grip-row[data-active="true"] {
+  background: var(--color-accent-primary);
+}
+
+@media (pointer: coarse) {
+  .wre-table-grip-col::before {
+    inset: 0 -21px; /* 44 px total touch hit area */
+  }
+  .wre-table-grip-row::before {
+    inset: -21px 0; /* 44 px total touch hit area */
+  }
+}

package/src/ui-tailwind/toolbar/tw-role-action-region.tsx

@@ -52,7 +52,20 @@ import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-edi
 import { ROLE_ACTION_SETS } from "../chrome/role-action-sets";
 import { TwScopePostureMenu } from "./tw-scope-posture-menu";
 
-export type MarkupDisplayMode = "clean" | "simple" | "all";
+/**
+ * Toolbar-local alias for the markup-display union.  L6d.N2 widens
+ * this to match the `MarkupDisplay` surface in
+ * `comment-decoration-model.ts`, which now accepts Word's 4-mode
+ * grammar plus the legacy triple.
+ */
+export type MarkupDisplayMode =
+  | "all-markup"
+  | "simple-markup"
+  | "no-markup"
+  | "original"
+  | "clean"
+  | "simple"
+  | "all";
 
 export interface WorkflowWorkItemSnapshot {
   workItemId: string;

package/src/ui-tailwind/toolbar/tw-shell-header.tsx

@@ -4,15 +4,20 @@ import * as Tabs from "@radix-ui/react-tabs";
 /**
  * TwShellHeader — the top "app chrome" bar above the document canvas.
  *
- * Anatomy matches the editorial reference mock:
+ * Designsystem §6.1 — three subregions on a single 48-px row:
  *   ┌─────────────────────────────────────────────────────────────────────┐
- *   │  [brand]        Edit | Review | Workflow | More          [⋯] [CTA] │
+ *   │ LEFT          │          CENTER           │               RIGHT     │
+ *   │ brand + slot  │ mode tabs (always-on)     │ icon actions + CTA      │
  *   └─────────────────────────────────────────────────────────────────────┘
  *
- * All three regions are optional slots — hosts opt in by supplying the
- * corresponding prop.  When nothing is supplied the header renders empty but
- * preserves layout height so the document canvas does not jump when a CTA
- * appears.
+ * Layout is CSS-grid `grid-cols-[1fr_auto_1fr]` so the center zone is
+ * always visually centred regardless of left / right slot width.  The
+ * 4-mode switcher (edit / review / workflow / more) renders
+ * unconditionally — Lane 6b §6b.S1 flips it from opt-in to always-on.
+ *
+ * All colors, shadows, radius, and motion bind to the Lane 6a token
+ * substrate (`var(--color-*)` / `var(--shadow-*)` / `var(--radius-*)` /
+ * `var(--motion-*)`) — no hex literals or legacy Tailwind palette names.
  */
 
 export type ShellHeaderMode = "edit" | "review" | "workflow" | "more";
@@ -40,6 +45,10 @@ export interface ShellHeaderIconAction {
 
 export interface TwShellHeaderProps {
   brand?: ReactNode;
+  /**
+   * Mode tab options.  When omitted, a default 4-mode set is rendered so
+   * the center subregion always has tabs per designsystem §6.1.
+   */
   modes?: readonly ShellHeaderModeOption[];
   activeMode?: ShellHeaderMode;
   onModeChange?: (mode: ShellHeaderMode) => void;
@@ -50,23 +59,33 @@ export interface TwShellHeaderProps {
   className?: string;
 }
 
-const focusRingClass =
-  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-canvas";
+/**
+ * Default 4-mode set — designsystem §6.1.  Exported so hosts can extend
+ * / relabel without reconstructing the whole list.
+ */
+export const DEFAULT_SHELL_HEADER_MODES: readonly ShellHeaderModeOption[] = [
+  { id: "edit", label: "Edit" },
+  { id: "review", label: "Review" },
+  { id: "workflow", label: "Workflow" },
+  { id: "more", label: "More" },
+];
 
-export function TwShellHeader(props: TwShellHeaderProps) {
-  const hasContent =
-    props.brand ||
-    (props.modes && props.modes.length > 0) ||
-    (props.iconActions && props.iconActions.length > 0) ||
-    props.primaryAction;
+const focusRingClass =
+  "focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]";
 
-  if (!hasContent) {
-    return null;
-  }
+export function TwShellHeader(props: TwShellHeaderProps): React.ReactElement {
+  const modes =
+    props.modes && props.modes.length > 0
+      ? props.modes
+      : DEFAULT_SHELL_HEADER_MODES;
+  const activeMode: ShellHeaderMode = props.activeMode ?? modes[0]!.id;
 
   const className = [
-    "flex h-12 shrink-0 items-center justify-between gap-4 px-4 bg-canvas/92 backdrop-blur-sm",
-    props.isScrolled ? "border-b border-border" : "border-b border-transparent",
+    "grid h-12 shrink-0 grid-cols-[1fr_auto_1fr] items-center gap-2 px-4",
+    "bg-[var(--color-bg-chrome)]/92 backdrop-blur-sm",
+    props.isScrolled
+      ? "border-b border-[var(--color-border-subtle)]"
+      : "border-b border-transparent",
     "transition-colors duration-[var(--motion-fast)]",
     props.className,
   ]
@@ -75,10 +94,15 @@ export function TwShellHeader(props: TwShellHeaderProps) {
 
   return (
     <header className={className} data-testid="tw-shell-header">
-      <div className="flex min-w-0 items-center gap-3">
+      {/* LEFT: brand + host-supplied slot */}
+      <div
+        className="flex min-w-0 items-center gap-3"
+        data-region="left"
+        data-testid="tw-shell-header__region-left"
+      >
         {props.brand ? (
           <div
-            className="font-[family-name:var(--font-legal-serif)] text-[15px] font-semibold text-primary truncate"
+            className="truncate font-[family-name:var(--font-legal-serif)] text-[15px] font-semibold text-[var(--color-text-primary)]"
             data-testid="tw-shell-header__brand"
           >
             {props.brand}
@@ -86,9 +110,14 @@ export function TwShellHeader(props: TwShellHeaderProps) {
         ) : null}
       </div>
 
-      {props.modes && props.modes.length > 0 && props.activeMode ? (
+      {/* CENTER: mode tabs (always on) */}
+      <div
+        className="flex items-center justify-center"
+        data-region="center"
+        data-testid="tw-shell-header__region-center"
+      >
         <Tabs.Root
-          value={props.activeMode}
+          value={activeMode}
           onValueChange={(v: string) =>
             props.onModeChange?.(v as ShellHeaderMode)
           }
@@ -97,7 +126,7 @@ export function TwShellHeader(props: TwShellHeaderProps) {
             aria-label="Workspace modes"
             className="flex items-center gap-1"
           >
-            {props.modes.map((mode) => (
+            {modes.map((mode) => (
               <Tabs.Trigger
                 key={mode.id}
                 value={mode.id}
@@ -110,17 +139,26 @@ export function TwShellHeader(props: TwShellHeaderProps) {
             ))}
           </Tabs.List>
         </Tabs.Root>
-      ) : (
-        <div aria-hidden="true" />
-      )}
+      </div>
 
-      <div className="flex items-center gap-1">
+      {/* RIGHT: icon actions + primary CTA */}
+      <div
+        className="flex items-center justify-end gap-1"
+        data-region="right"
+        data-testid="tw-shell-header__region-right"
+      >
         {props.iconActions?.map((action) => {
           const commonProps = {
             key: action.id,
             "aria-label": action.label,
             title: action.label,
-            className: `inline-flex h-8 w-8 items-center justify-center rounded-sm text-secondary transition-colors hover:bg-surface-hover hover:text-primary ${focusRingClass}`,
+            className: [
+              "inline-flex h-8 w-8 items-center justify-center rounded-[var(--radius-sm)]",
+              "text-[var(--color-text-secondary)]",
+              "transition-colors duration-[var(--motion-fast)]",
+              "hover:bg-[var(--color-bg-hover)] hover:text-[var(--color-text-primary)]",
+              focusRingClass,
+            ].join(" "),
           } as const;
 
           if (action.href) {
@@ -145,10 +183,13 @@ export function TwShellHeader(props: TwShellHeaderProps) {
             onClick={props.primaryAction.onClick}
             data-tone={props.primaryAction.tone ?? "accent"}
             className={[
-              "ml-2 inline-flex h-8 items-center rounded-sm px-3 text-xs font-semibold transition-colors disabled:opacity-40",
+              "ml-2 inline-flex h-8 items-center rounded-[var(--radius-sm)] px-3",
+              "text-xs font-semibold",
+              "transition-colors duration-[var(--motion-fast)]",
+              "disabled:opacity-40",
               props.primaryAction.tone === "neutral"
-                ? "bg-surface text-primary hover:bg-surface-hover"
-                : "bg-accent text-white hover:bg-[color-mix(in_srgb,var(--color-accent)_85%,#000)]",
+                ? "bg-[var(--color-bg-muted)] text-[var(--color-text-primary)] hover:bg-[var(--color-bg-hover)]"
+                : "bg-[var(--color-accent-primary)] text-[var(--color-text-on-accent)] hover:bg-[var(--color-accent-primary-hover)]",
               focusRingClass,
             ].join(" ")}
             data-testid="tw-shell-header__primary-action"

package/src/ui-tailwind/toolbar/tw-toolbar-icon-button.tsx

@@ -7,13 +7,31 @@ export interface TwToolbarIconButtonProps {
   icon: React.ComponentType<{ className?: string }>;
   label: string;
   disabled?: boolean;
+  /**
+   * Active / pressed state.  Designsystem §6.2 + Lane 6b §6b.S2: active
+   * buttons paint an accent-soft tint with an accent border ring — NOT a
+   * filled accent CTA.  The filled-CTA grammar is reserved for the shell
+   * header primary action only.
+   */
   active?: boolean;
+  /**
+   * Emphasis variant — used for "stand-out" toolbar items (e.g. a pinned
+   * AI action).  Paints the accent glyph color at rest; still tints on
+   * hover and on active.
+   */
   emphasis?: boolean;
+  /**
+   * Lane 6b §6b.U6 — optional keyboard-shortcut hint rendered as a small
+   * `<kbd>` chip to the right of the label inside the tooltip.  Use
+   * platform-agnostic symbols (⌘, ⇧, ⌥, ⌃) — callers format for macOS
+   * vs. Windows however they like.
+   */
+  shortcut?: string;
   onClick?: () => void;
 }
 
 const focusRingClass =
-  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
+  "focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]";
 
 export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
   return (
@@ -22,17 +40,22 @@ export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
         <button
           type="button"
           aria-label={props.label}
+          aria-pressed={props.active ?? undefined}
+          data-active={props.active ? "true" : undefined}
           disabled={props.disabled}
           onMouseDown={preserveEditorSelectionMouseDown}
           onClick={props.onClick}
           className={[
-            "inline-flex h-6 w-6 items-center justify-center rounded-md border border-transparent transition-colors outline-none",
+            "inline-flex h-6 w-6 items-center justify-center rounded-[var(--radius-sm)]",
+            "border border-transparent outline-none",
+            "transition-colors duration-[var(--motion-fast)]",
             "disabled:opacity-30 disabled:cursor-not-allowed",
-            props.emphasis
-              ? "text-accent hover:border-border/60 hover:bg-surface"
-              : props.active
-                ? "border-border/70 bg-surface text-accent shadow-[0_4px_12px_-10px_var(--color-shadow-strong)]"
-                : "text-secondary hover:border-border/60 hover:bg-surface hover:text-primary",
+            props.active
+              ? // Active = underline-tint grammar: accent-soft fill, accent-primary glyph, accent border ring.
+                "bg-[var(--color-accent-soft)] text-[var(--color-accent-primary)] border-[var(--color-border-accent)]"
+              : props.emphasis
+                ? "text-[var(--color-accent-primary)] hover:bg-[var(--color-bg-hover)] hover:border-[var(--color-border-subtle)]"
+                : "text-[var(--color-text-secondary)] hover:bg-[var(--color-bg-hover)] hover:text-[var(--color-text-primary)] hover:border-[var(--color-border-subtle)]",
             focusRingClass,
           ].join(" ")}
         >
@@ -41,10 +64,27 @@ export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
       </Tooltip.Trigger>
       <Tooltip.Portal>
         <Tooltip.Content
-          className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
+          className={[
+            "inline-flex items-center gap-2 rounded-[var(--radius-sm)] px-2 py-1 text-xs z-50",
+            "bg-[var(--color-text-primary)] text-[var(--color-text-inverse)]",
+            "shadow-[var(--shadow-soft)]",
+          ].join(" ")}
           sideOffset={6}
         >
-          {props.label}
+          <span>{props.label}</span>
+          {props.shortcut ? (
+            <kbd
+              className={[
+                "inline-flex items-center rounded-[var(--radius-sm)]",
+                "px-1 py-0.5 font-sans text-[10px] font-medium",
+                "border border-[var(--color-border-subtle)]/40",
+                "bg-[var(--color-bg-overlay)] text-[var(--color-text-inverse)]/80",
+              ].join(" ")}
+              data-testid="tw-toolbar-icon-button__shortcut"
+            >
+              {props.shortcut}
+            </kbd>
+          ) : null}
         </Tooltip.Content>
       </Tooltip.Portal>
     </Tooltip.Root>