From 3139bfce572ae8a13ec7ac4f536925736412a2bf Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Mon, 2 Mar 2026 19:05:27 -0600
Subject: [PATCH 01/47] feat(tokens,css,link,text,breadcrumbs,input-group):
 NO-JIRA tokens, CSS foundation, deprecations, tooling, scratch page

Dark theme tokens, radius-350, CSS :where() specificity softening, import
ordering, watch tooling, inverted deprecations (link, text, breadcrumbs,
keyboard-shortcut), input-group deprecation, deprecated badge in API table,
scratch page.
---
 .claude/rules/css-specificity.md              |  96 ++
 .../theme/assets/less/dialtone-docs.less      |  40 +-
 .../theme/assets/less/dialtone-syntax.less    |  21 +-
 .../theme/components/SidebarItem.vue          |   2 +-
 .../.vuepress/theme/components/TocItem.vue    |   2 +-
 .../docs/.vuepress/views/Overview.vue         |  46 +-
 .../docs/_data/site-nav.json                  |   8 +-
 .../docs/components/input-group.md            |   2 +-
 .../docs/components/link.md                   |  57 +-
 .../docs/components/mode-island.md            |  54 +-
 .../docs/components/stack.md                  |   2 +-
 .../docs/components/table.md                  | 136 ++-
 .../docs/components/text.md                   |  53 +-
 .../docs/guides/contributing/index.md         |   6 +
 apps/dialtone-documentation/docs/scratch.md   | 873 ++++++++++++++++++
 .../docs/utilities/borders/radius.md          |   5 +-
 apps/dialtone-documentation/project.json      |   5 +-
 packages/dialtone-css/.github/CONTRIBUTING.md |  79 ++
 packages/dialtone-css/gulpfile.cjs            |   5 +-
 .../lib/build/less/components/card.less       |   1 +
 .../lib/build/less/components/selects.less    |   2 +-
 .../lib/build/less/components/table.less      |  27 +-
 .../dialtone-css/lib/build/less/dialtone.less |  32 +-
 packages/dialtone-css/postcss/constants.cjs   |   1 +
 packages/dialtone-css/project.json            |  14 +
 .../dialtone-tokens/tokens/theme/dp/dark.json |  20 +-
 .../breadcrumbs/breadcrumb_item.stories.js    |   3 +
 .../breadcrumbs/breadcrumbs.stories.js        |   3 +
 .../breadcrumbs_variants.story.vue            |   7 -
 .../components/card/card_default.story.vue    |  22 +-
 .../filter_pill/filter_pill.stories.js        |   2 +-
 .../components/hovercard/hovercard.stories.js |  15 +-
 .../components/icon/icon_variants.story.vue   |  27 +-
 .../input_group/input_group.stories.js        |   7 +
 .../input_group_variants.story.vue            |  10 +-
 .../kitchen_sink/kitchen_sink_view.vue        |   3 +
 .../components/link/link.stories.js           |   3 +-
 .../dialtone-vue/components/link/link.vue     |   1 +
 .../components/link/link_default.story.vue    |   1 +
 .../components/link/link_variants.story.vue   |  35 +-
 .../presence/presence_variants.story.vue      |  51 +-
 .../components/root_layout/root_layout.vue    |   9 +-
 .../scroller/scroller_default.story.vue       |   2 +-
 .../scroller/scroller_dynamic.story.vue       |   2 +-
 .../components/text/text_variants.story.vue   |  20 +-
 .../feed_item_row_variants.story.vue          |   2 +-
 46 files changed, 1460 insertions(+), 354 deletions(-)
 create mode 100644 .claude/rules/css-specificity.md

diff --git a/.claude/rules/css-specificity.md b/.claude/rules/css-specificity.md
new file mode 100644
index 0000000000..b646b5a016
--- /dev/null
+++ b/.claude/rules/css-specificity.md
@@ -0,0 +1,96 @@
+---
+paths:
+  - "packages/dialtone-css/**"
+---
+
+# CSS Specificity Rules
+
+## Target: (0,1,0) Per Selector
+
+Every component selector should aim for a specificity of (0,1,0) — one class. BEM naturally achieves this:
+
+```less
+.d-banner {}           // (0,1,0) — block
+.d-banner__dialog {}   // (0,1,0) — element
+.d-banner--success {}  // (0,1,0) — modifier
+```
+
+Modifier overrides should use CSS custom properties, not higher specificity:
+
+```less
+// CORRECT — modifier overrides a variable, same specificity
+.d-banner { --banner-color: var(--dt-color-surface-primary); }
+.d-banner--success { --banner-color: var(--dt-color-surface-success); }
+
+// AVOID — parent modifier targets child, inflates to (0,2,0)
+.d-banner--success .d-banner__icon { color: green; }
+```
+
+## Element-Type Descendants: Always Wrap in `:where()`
+
+When a component must style bare HTML elements (`th`, `td`, `a`, `button`, `option`, `li`, etc.), wrap them in `:where()` to zero out the element's specificity contribution:
+
+```less
+// CORRECT — (0,1,0)
+.d-table {
+  :where(th) { color: var(--table-th-color-text); }
+  :where(td) { color: var(--table-td-color-text); }
+}
+
+// WRONG — (0,1,1), harder to override
+.d-table {
+  th { color: var(--table-th-color-text); }
+}
+```
+
+## Structural Pseudo-Classes on Elements: Wrap the Full Descendant
+
+When using `:first-child`, `:last-of-type`, `:nth-child()`, etc. on element selectors inside a component, wrap everything in `:where()`:
+
+```less
+// CORRECT — (0,1,0)
+.d-table {
+  :where(tbody tr:last-of-type) {
+    :where(td, th) { border-block-end-width: 0; }
+  }
+}
+
+// WRONG — (0,2,3)
+.d-table {
+  tbody tr:last-of-type {
+    td, th { border-block-end-width: 0; }
+  }
+}
+```
+
+## Do NOT Wrap These
+
+- **The host component class** — `.d-table` must retain its (0,1,0) as the anchor selector
+- **BEM modifier classes** — `.d-table--striped` needs its specificity to override base styles
+- **State pseudo-classes** — `:hover`, `:disabled`, `:focus-visible`, `:active`, `:checked` where specificity ordering is functional (e.g., `:not(:disabled):hover` must beat `:disabled`)
+- **`:not()` / `:has()` containing class selectors** — the specificity reflects semantic complexity, not accidental inflation
+
+## Nesting Depth
+
+- **1 class** (0,1,0): Default. Covers most rules.
+- **2 classes** (0,2,0): Acceptable when a parent modifier must affect children (e.g., `.d-tablist--inverted .d-tab`). Prefer CSS custom property overrides when possible.
+- **3+ classes**: Avoid. Refactor to use CSS custom properties or restructure the component.
+
+## `@layer` Context
+
+All component styles are inside `@layer dialtone.components`. This means:
+
+- Unlayered consumer CSS always wins regardless of specificity
+- Within the layer, lower specificity = easier to extend and override
+- Keeping selectors flat benefits consumers who style within the same layer
+
+## Anti-Patterns
+
+- No `#id` selectors
+- No bare element selectors without `:where()` wrapping
+- No `!important` in component styles (reserved for utility classes)
+- No qualifying element selectors on classes (e.g., `div.d-banner` — just use `.d-banner`)
+
+## Reference
+
+Use [Specificity Calculator](https://specificity.keegan.st/) to verify selector specificity values. It supports CSS Selectors Level 4 including `:where()`, `:is()`, and `:has()`.
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less
index c395af47a9..9a1a243609 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less
@@ -176,7 +176,7 @@ html body {
     color: var(--dt-color-foreground-secondary);
     font-size: var(--dt-font-size-300);
 
-    strong {
+    :where(strong) {
       color: var(--dt-color-foreground-primary);
     }
   }
@@ -189,19 +189,19 @@ html body {
     padding-block-end: var(--dt-size-400);
   }
 
-  .DocSearch-Hits mark {
+  .DocSearch-Hits :where(mark) {
     padding: var(--dt-size-200);
     color: var(--dt-color-foreground-primary);
     background: var(--dt-color-surface-warning);
   }
 
-  .DocSearch-Hit a {
+  .DocSearch-Hit :where(a) {
     padding-inline: var(--dt-size-450) var(--dt-size-450);
     border-radius: var(--dt-size-radius-300);
   }
 
-  .DocSearch-Hit-action svg,
-  .DocSearch-Hit-icon svg {
+  .DocSearch-Hit-action :where(svg),
+  .DocSearch-Hit-icon :where(svg) {
     inline-size: var(--dt-icon-size-200);
     block-size: var(--dt-icon-size-200);
   }
@@ -216,7 +216,7 @@ html body {
     // no overrides
   }
 
-  .DocSearch-Hit[aria-selected="true"] mark {
+  .DocSearch-Hit[aria-selected="true"] :where(mark) {
     color: var(--dt-color-foreground-primary) !important;
     text-decoration: none;
   }
@@ -242,8 +242,8 @@ html body {
     // no overrides
   }
 
-  .DocSearch-Logo svg {
-    filter: saturate(0) contrast(0.25);
+  .DocSearch-Logo :where(svg) {
+    filter: saturate(0) contrast(.25);
   }
 
   .DocSearch-Commands {
@@ -273,7 +273,7 @@ html body {
     color: var(--dt-color-link-primary);
   }
 
-  .DocSearch-NoResults-Prefill-List li {
+  .DocSearch-NoResults-Prefill-List :where(li) {
     list-style-type: none;
   }
 }
@@ -293,15 +293,15 @@ html body {
   background-color: var(--dt-shell-color-surface-default);
   view-transition-name: dialtone-header;
 
-  > :first-child {
+  > :where(:first-child) {
     justify-self: start;
   }
 
-  > :nth-child(2) {
+  > :where(:nth-child(2)) {
     justify-self: center;
   }
 
-  > :last-child {
+  > :where(:last-child) {
     justify-self: end;
   }
 
@@ -417,7 +417,7 @@ a.header-anchor {
 
 .d-docsite--header-2,
 .d-docsite--header-3 {
-  &:hover a.header-anchor {
+  &:hover :where(a).header-anchor {
     opacity: 1;
   }
 }
@@ -457,7 +457,7 @@ a.header-anchor {
   }
 }
 
-code {
+:where(code) {
   .d-docsite--paragraph &,
   .d-docsite--unordered-list &,
   .d-docsite--ordered-list &,
@@ -563,7 +563,7 @@ code {
   .d-popover {
     block-size: 100%;
 
-    > div {
+    > :where(div) {
       block-size: 100%;
     }
   }
@@ -633,7 +633,7 @@ code {
   block-size: var(--dt-size-650);
   margin-block-end: var(--dt-size-300);
 
-  svg {
+  :where(svg) {
     inline-size: 100%;
     block-size: auto;
   }
@@ -642,7 +642,7 @@ code {
 .dialtone-icon-card__icon--autosize {
   margin-block-end: var(--dt-size-300);
 
-  svg {
+  :where(svg) {
     inline-size: 100%;
     block-size: auto;
   }
@@ -882,17 +882,17 @@ code {
 //  ----------------------------------------------------------------------------
 
 .dialtone-definition {
-  > dt {
+  > :where(dt) {
     margin-block-start: var(--dt-size-500);
     font-weight: var(--dt-font-weight-bold);
   }
 
-  > dd {
+  > :where(dd) {
     max-inline-size: 72ch;
     margin: 0;
   }
 
-  code {
+  :where(code) {
     font-weight: var(--dt-font-weight-normal);
   }
 }
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
index c8373ea8e6..0ef0d400e3 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
@@ -9,12 +9,12 @@ div[class*="language-"] {
 	background-color: var(--dt-color-surface-secondary);
 	border-radius: var(--dt-size-500);
 
-	& pre {
+	& :where(pre) {
 		margin: 0;
 		padding: var(--dt-size-450);
     padding-block-start: var(--dt-size-550);
 
-		& code {
+		& :where(code) {
 			padding: 0;
 			color: var(--dt-color-foreground-secondary);
 			background-color: unset;
@@ -59,6 +59,11 @@ pre[class*="language-"] {
 	user-select: initial;
 }
 
+div[class*=language-] pre {
+	font: var(--dt-text-code-sm);
+	line-height: var(--dt-font-line-height-400);
+}
+
 @media print {
 	code[class*="language-"],
 	pre[class*="language-"] {
@@ -156,7 +161,7 @@ pre[class*="language-"].line-numbers {
 	counter-reset: linenumber;
 }
 
-pre[class*="language-"].line-numbers > code {
+pre[class*="language-"].line-numbers > :where(code) {
 	position: relative;
 	white-space: inherit;
 }
@@ -173,7 +178,7 @@ pre[class*="language-"].line-numbers > code {
 	pointer-events: none;
 }
 
-.line-numbers-rows > span {
+.line-numbers-rows > :where(span) {
   display: block;
   counter-increment: linenumber;
 
@@ -197,22 +202,22 @@ pre[class*="language-"].line-numbers > code {
 	pointer-events: none;
 }
 
-.command-line-prompt > span::before {
+.command-line-prompt > :where(span)::before {
 	display: block;
 	padding-inline-end: var(--dt-size-400);
 	color: var(--dt-color-black-600);
 	content: ' ';
 }
 
-.command-line-prompt > span[data-user]::before {
+.command-line-prompt > :where(span[data-user])::before {
 	content: "[" attr(data-user) "@" attr(data-host) "] $";
 }
 
-.command-line-prompt > span[data-user="root"]::before {
+.command-line-prompt > :where(span[data-user="root"])::before {
 	content: "[" attr(data-user) "@" attr(data-host) "] #";
 }
 
-.command-line-prompt > span[data-prompt]::before {
+.command-line-prompt > :where(span[data-prompt])::before {
 	content: attr(data-prompt);
 }
 
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue
index e6c4f53a2e..8ee9e0122e 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue
@@ -99,7 +99,7 @@
                 kind="muted"
                 label-class="d-jc-flex-start d-ta-left d-fw-normal"
                 :class="[
-                  'dialtone-shell-btn d-w100p',
+                  'dialtone-shell-btn d-w100p d-tw-pretty',
                   { 'd-pl48': depth === 0 },
                   { 'd-pl64': depth === 1 },
                 ]"
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
index bc9959c99b..f1139a72a2 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
@@ -1,7 +1,7 @@
 <template>
   <RouterLink
     :class="[
-      'd-btn d-btn--sm d-btn--muted d-w100p d-jc-flex-start d-fw-normal',
+      'd-btn d-btn--sm d-btn--muted d-w100p d-jc-flex-start d-fw-normal d-tw-pretty',
       { 'd-btn--active': active },
     ]"
     :to="to"
diff --git a/apps/dialtone-documentation/docs/.vuepress/views/Overview.vue b/apps/dialtone-documentation/docs/.vuepress/views/Overview.vue
index 8ed2400f92..ec2043a32c 100644
--- a/apps/dialtone-documentation/docs/.vuepress/views/Overview.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/views/Overview.vue
@@ -1,30 +1,32 @@
 <template>
   <div class="dialtone-wall">
     <template v-for="page in pages" :key="page.title">
-      <component
-        :is="cardElType(page)"
-        :to="page.link"
-        class="dialtone-wall__item"
-      >
-        <div v-if="page.thumb" class="dialtone-wall__image">
-          <svg-loader class="dialtone-wall__thumb" :name="page.fileName" />
-        </div>
-        <div class="dialtone-wall__details">
-          <div class="dialtone-wall__title">
-            <span class="dialtone-wall__title-text">{{ pageTitle(page) }}</span>
-            <span
-              v-if="page.status"
-              class="d-badge d-tt-capitalize"
-              :class="badgeKindClass(page.status)"
-            >
-              {{ page.status }}
-            </span>
+      <template v-if="page.status !== 'deprecated'">
+        <component
+          :is="cardElType(page)"
+          :to="page.link"
+          class="dialtone-wall__item"
+        >
+          <div v-if="page.thumb" class="dialtone-wall__image">
+            <svg-loader class="dialtone-wall__thumb" :name="page.fileName" />
           </div>
-          <div class="dialtone-wall__description">
-            {{ page.description }}
+          <div class="dialtone-wall__details">
+            <div class="dialtone-wall__title">
+              <span class="dialtone-wall__title-text">{{ pageTitle(page) }}</span>
+              <span
+                v-if="page.status"
+                class="d-badge d-tt-capitalize"
+                :class="badgeKindClass(page.status)"
+              >
+                {{ page.status }}
+              </span>
+            </div>
+            <div class="dialtone-wall__description">
+              {{ page.description }}
+            </div>
           </div>
-        </div>
-      </component>
+        </component>
+      </template>
     </template>
   </div>
 </template>
diff --git a/apps/dialtone-documentation/docs/_data/site-nav.json b/apps/dialtone-documentation/docs/_data/site-nav.json
index ea6c9c2bd1..a8d5d809f1 100644
--- a/apps/dialtone-documentation/docs/_data/site-nav.json
+++ b/apps/dialtone-documentation/docs/_data/site-nav.json
@@ -341,10 +341,6 @@
                 "text": "Input",
                 "link": "/components/input.html"
               },
-              {
-                "text": "Input Group",
-                "link": "/components/input-group.html"
-              },
               {
                 "text": "Item Layout",
                 "link": "/components/item-layout.html"
@@ -826,6 +822,10 @@
                     "text": "Text Transform",
                     "link": "/utilities/typography/text-transform.html"
                   },
+                  {
+                    "text": "Text Wrap",
+                    "link": "/utilities/typography/text-wrap.html"
+                  },
                   {
                     "text": "Vertical Alignment",
                     "link": "/utilities/typography/vertical-align.html"
diff --git a/apps/dialtone-documentation/docs/components/input-group.md b/apps/dialtone-documentation/docs/components/input-group.md
index ca11991ed4..bbba1ceed8 100644
--- a/apps/dialtone-documentation/docs/components/input-group.md
+++ b/apps/dialtone-documentation/docs/components/input-group.md
@@ -1,7 +1,7 @@
 ---
 title: Input Group
 description: Input Groups are convenience components for a grouping of related inputs. While each input within the group could be independent, the v-model on the group provides a convenient interface for determining the current state of the group.
-status: ready
+status: deprecated
 thumb: true
 image: assets/images/components/input.png
 storybook: https://dialtone.dialpad.com/vue/?path=/story/components-input-group--default
diff --git a/apps/dialtone-documentation/docs/components/link.md b/apps/dialtone-documentation/docs/components/link.md
index bdab17695c..1eded95f84 100644
--- a/apps/dialtone-documentation/docs/components/link.md
+++ b/apps/dialtone-documentation/docs/components/link.md
@@ -71,45 +71,54 @@ vueCode='
 '
 showHtmlWarning />
 
-### Inverted
+### No underline
 
-<code-well-header bgclass="d-bgc-contrast">
-  <DtStack gap="400" ref="linkExample2">
-    <dt-link href="#link" inverted>Inverted base link</dt-link>
-    <dt-link href="#link" kind="danger" inverted>Inverted danger link</dt-link>
-    <dt-link href="#link" kind="success" inverted>Inverted success link</dt-link>
-    <dt-link href="#link" kind="warning" inverted>Inverted warning link</dt-link>
-    <dt-link href="#link" kind="muted" inverted>Inverted muted link</dt-link>
-    <dt-link href="#link" kind="mention" inverted>Inverted mention link</dt-link>
-  </DtStack>
+This inverts the underline behavior. With `underline="false"`, the link will not have an underline by default, but will show one on hover.
+
+<code-well-header>
+  <dt-link href="#link" :underline="false">No underline link</dt-link>
 </code-well-header>
 
 <code-example-tabs
-:htmlCode='() => $refs.linkExample2'
+htmlCode='
+<a href="#link" class="d-link d-link--no-underline">No underline link</a>
+'
 vueCode='
-<dt-link :href="#link" inverted>Inverted link</dt-link>
-<dt-link :href="#link" kind="danger" inverted>Inverted danger link</dt-link>
-<dt-link :href="#link" kind="success" inverted>Inverted success link</dt-link>
-<dt-link :href="#link" kind="warning" inverted>Inverted warning link</dt-link>
-<dt-link :href="#link" kind="muted" inverted>Inverted muted link</dt-link>
-<dt-link :href="#link" kind="mention" inverted>Inverted mention link</dt-link>
+<dt-link href="#link" :underline="false">No underline link</dt-link>
 '
 showHtmlWarning />
 
-### No underline
+### Inverted
 
-This inverts the underline behavior. With `underline="false"`, the link will not have an underline by default, but will show one on hover.
+<dt-notice
+  title="Deprecated"
+  kind="error"
+  class="d-wmx100p d-my16"
+>
+  The <code>inverted</code> prop has been deprecated in favor of using <router-link to="mode-island.html"> <DtLink>DtModeIsland</DtLink> </router-link> as a wrapper.
+</dt-notice>
+
+In place of the <code>inverted</code> prop, use the <router-link to="mode-island.html"> <DtLink>DtModeIsland</DtLink> </router-link> component as a wrapper.
 
 <code-well-header>
-  <dt-link href="#link" :underline="false">No underline link</dt-link>
+  <dt-mode-island class="d-p16 d-bar8">
+    <DtStack gap="400" ref="linkInvertedExample">
+      <dt-link href="#link">Base link</dt-link>
+      <dt-link href="#link" kind="danger">Danger link</dt-link>
+      <dt-link href="#link" kind="success">Success link</dt-link>
+      <dt-link href="#link" kind="warning">Warning link</dt-link>
+      <dt-link href="#link" kind="muted">Muted link</dt-link>
+      <dt-link href="#link" kind="mention">Mention link</dt-link>
+    </DtStack>
+  </dt-mode-island>
 </code-well-header>
 
 <code-example-tabs
-htmlCode='
-<a href="#link" class="d-link d-link--no-underline">No underline link</a>
-'
+:htmlCode='() => $refs.linkInvertedExample'
 vueCode='
-<dt-link href="#link" :underline="false">No underline link</dt-link>
+<dt-mode-island>
+  <dt-link {props}>Link</dt-link>
+</dt-mode-island>
 '
 showHtmlWarning />
 
diff --git a/apps/dialtone-documentation/docs/components/mode-island.md b/apps/dialtone-documentation/docs/components/mode-island.md
index 595f8874b7..f4d3d5ed30 100644
--- a/apps/dialtone-documentation/docs/components/mode-island.md
+++ b/apps/dialtone-documentation/docs/components/mode-island.md
@@ -273,7 +273,7 @@ vueCode='
 '
 showHtmlWarning />
 
-## Custom element
+## Render as
 
 Polymorphic rendering via `as` prop—controls which HTML element wraps content. Ensures proper document structure and semantic markup. Example values: `section` for thematic grouping, `article` for self-contained content. Defaults to `div` where semantics aren't a concern.
 
@@ -325,12 +325,60 @@ vueCode='
 '
 />
 
+## Custom background
+
+The background surface of a Mode Island defaults to the root surface color. To override, use a CSS Utility class.
+
+<code-well-header>
+  <dt-mode-island class="d-p16 d-bar8 d-w100p d-bgc-transparent" ref="customBackgroundExample">
+    <dt-stack gap="400">
+      <dt-text as="p" kind="code" size="xs" tone="tertiary">Transparent background, inverted mode island</dt-text>
+      <div>
+        <dt-button>Button</dt-button>
+      </div>
+    </dt-stack>
+  </dt-mode-island>
+  <dt-mode-island class="d-p16 d-bar8 d-w100p">
+    <dt-stack gap="400">
+      <dt-text as="p" kind="code" size="xs" tone="tertiary">Default background, inverted mode island</dt-text>
+      <div>
+        <dt-button>Button</dt-button>
+      </div>
+    </dt-stack>
+  </dt-mode-island>
+  <dt-mode-island mode="dark" class="d-p16 d-bar8 d-w100p d-bgc-warning">
+    <dt-stack gap="400">
+      <dt-text as="p" kind="code" size="xs" tone="tertiary">warning background, dark mode island</dt-text>
+      <div>
+        <dt-button>Button</dt-button>
+      </div>
+    </dt-stack>
+  </dt-mode-island>
+  <dt-mode-island mode="light" class="d-p16 d-bar8 d-w100p d-bgc-warning">
+    <dt-stack gap="400">
+      <dt-text as="p" kind="code" size="xs" tone="tertiary">warning background, light mode island</dt-text>
+      <div>
+        <dt-button>Button</dt-button>
+      </div>
+    </dt-stack>
+  </dt-mode-island>
+</code-well-header>
+
+<code-example-tabs
+:htmlCode='() => $refs.customBackgroundExample'
+vueCode='
+<dt-mode-island class="d-bgc-transparent">
+  <dt-button>Button</dt-button>
+</dt-mode-island>
+'
+showHtmlWarning />
+
 ## Examples
 
 ### Callbar
 
 <code-well-header>
-  <dt-mode-island ref="callbarExample" class="d-ba d-bc-subtle d-p8 d-py4 d-bar32 d-bs-md d-w100p">
+  <dt-mode-island ref="callbarExample" class="d-ba d-bc-subtle d-p8 d-py4 d-bar8 d-bs-md d-w100p">
     <dt-stack direction="row" gap="600">
       <dt-stack gap="400" direction="row">
         <dt-avatar
@@ -382,7 +430,7 @@ vueCode='
 <code-example-tabs
 :htmlCode='() => $refs.callbarExample'
 vueCode='
-<dt-mode-island class="d-ba d-bc-subtle d-p8 d-py4 d-bar32 d-bs-md d-w100p">
+<dt-mode-island class="d-ba d-bc-subtle d-p8 d-py4 d-bar8 d-bs-md d-w100p">
   <dt-stack direction="row" gap="600">
     <dt-stack gap="400" direction="row">
       <dt-avatar full-name="TA" seed="ted-anderson" size="lg" />
diff --git a/apps/dialtone-documentation/docs/components/stack.md b/apps/dialtone-documentation/docs/components/stack.md
index 1c7c90991f..d18dd6ba19 100644
--- a/apps/dialtone-documentation/docs/components/stack.md
+++ b/apps/dialtone-documentation/docs/components/stack.md
@@ -185,7 +185,7 @@ vueCode='
 '
 />
 
-## As
+## Render as
 
 The `as` prop controls which HTML element the Stack component renders as. Defaults to `<div>`, but can be declared as any valid HTML element to ensure semantic and accessible markup.
 
diff --git a/apps/dialtone-documentation/docs/components/table.md b/apps/dialtone-documentation/docs/components/table.md
index 5864e0a339..05cd81058c 100644
--- a/apps/dialtone-documentation/docs/components/table.md
+++ b/apps/dialtone-documentation/docs/components/table.md
@@ -82,50 +82,40 @@ keywords: ["data table", "grid", "rows", "d-table", "DtTable", "dt-table", "data
 
 ### Inverted Style
 
-Used when you want to display a data table on a darker background.
-
-<code-well-header bgclass="d-bgc-contrast">
-  <table class="d-table dialtone-doc-table d-table--inverted">
-    <caption class="d-table__caption">Office List</caption>
-    <thead>
-      <tr>
-        <th scope="col">Office</th>
-        <th scope="col">Country</th>
-        <th scope="col" width="10%">Employees</th>
-        <th scope="col">Contact</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr v-for="i in examples">
-        <th scope="row">{{ i.office }}</th>
-        <td>{{ i.country }}</td>
-        <td>{{ i.size }}</td>
-        <td>{{ i.contact }}</td>
-      </tr>
-    </tbody>
-  </table>
+<dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
+  The <code>d-table--inverted</code> modifier has been deprecated in favor of using <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> as a wrapper.
+</dt-notice>
+
+In place of the <code>d-table--inverted</code> modifier, wrap the table in the <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> component.
+
+<code-well-header>
+  <dt-mode-island class="d-p16 d-bar8">
+    <table class="d-table dialtone-doc-table">
+      <caption class="d-table__caption">Office List</caption>
+      <thead>
+        <tr>
+          <th scope="col">Office</th>
+          <th scope="col">Country</th>
+          <th scope="col" width="10%">Employees</th>
+          <th scope="col">Contact</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="i in examples">
+          <th scope="row">{{ i.office }}</th>
+          <td>{{ i.country }}</td>
+          <td>{{ i.size }}</td>
+          <td>{{ i.contact }}</td>
+        </tr>
+      </tbody>
+    </table>
+  </dt-mode-island>
 </code-well-header>
 
 ```html
-<table class="d-table d-table--inverted">
-  <caption class="d-table__caption">...</caption>
-  <thead>
-    <tr>
-      <th scope="col">...</th>
-      <th scope="col">...</th>
-      <th scope="col">...</th>
-      <th scope="col">...</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th scope="row">...</th>
-      <td>...</td>
-      <td>...</td>
-      <td>...</td>
-    </tr>
-  </tbody>
-</table>
+<dt-mode-island>
+  <table class="d-table">...</table>
+</dt-mode-island>
 ```
 
 ### Striped
@@ -174,48 +164,34 @@ Used when you want to display a data table on a darker background.
 </table>
 ```
 
-<code-well-header bgclass="d-bgc-contrast">
-  <table class="d-table dialtone-doc-table d-table--inverted d-table--striped">
-    <caption class="d-table__caption">Office List</caption>
-    <thead>
-      <tr>
-        <th scope="col">Office</th>
-        <th scope="col">Country</th>
-        <th scope="col" width="10%">Employees</th>
-        <th scope="col">Contact</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr v-for="i in examples">
-        <th scope="row">{{ i.office }}</th>
-        <td>{{ i.country }}</td>
-        <td>{{ i.size }}</td>
-        <td>{{ i.contact }}</td>
-      </tr>
-    </tbody>
-  </table>
+<code-well-header>
+  <dt-mode-island class="d-p16 d-bar8">
+    <table class="d-table dialtone-doc-table d-table--striped">
+      <caption class="d-table__caption">Office List</caption>
+      <thead>
+        <tr>
+          <th scope="col">Office</th>
+          <th scope="col">Country</th>
+          <th scope="col" width="10%">Employees</th>
+          <th scope="col">Contact</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="i in examples">
+          <th scope="row">{{ i.office }}</th>
+          <td>{{ i.country }}</td>
+          <td>{{ i.size }}</td>
+          <td>{{ i.contact }}</td>
+        </tr>
+      </tbody>
+    </table>
+  </dt-mode-island>
 </code-well-header>
 
 ```html
-<table class="d-table d-table--inverted d-table--striped">
-  <caption class="d-table__caption">...</caption>
-  <thead>
-    <tr>
-      <th scope="col">...</th>
-      <th scope="col">...</th>
-      <th scope="col">...</th>
-      <th scope="col">...</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th scope="row">...</th>
-      <td>...</td>
-      <td>...</td>
-      <td>...</td>
-    </tr>
-  </tbody>
-</table>
+<dt-mode-island>
+  <table class="d-table d-table--striped">...</table>
+</dt-mode-island>
 ```
 
 ## Classes
diff --git a/apps/dialtone-documentation/docs/components/text.md b/apps/dialtone-documentation/docs/components/text.md
index 459bf043da..9f0e849332 100644
--- a/apps/dialtone-documentation/docs/components/text.md
+++ b/apps/dialtone-documentation/docs/components/text.md
@@ -278,42 +278,37 @@ vueCode='
 Use `tone` to declare the text's tone, which will map to a foreground color. By default, the tone is inherited from its parent.
 
 <code-well-header>
-  <dt-stack gap="500" direction="row">
-    <dt-stack gap="300" class="d-py8 d-px16 d-bgc-primary d-bar4">
-      <dt-text>primary</dt-text>
-      <dt-text tone="secondary">secondary</dt-text>
-      <dt-text tone="tertiary">tertiary</dt-text>
-      <dt-text tone="muted">muted</dt-text>
-      <dt-text tone="disabled">disabled</dt-text>
-      <dt-text tone="placeholder">placeholder</dt-text>
-      <dt-text tone="success">success</dt-text>
-      <dt-text tone="success-strong">success-strong</dt-text>
-      <dt-text tone="warning">warning</dt-text>
-      <dt-text tone="critical">critical</dt-text>
-      <dt-text tone="critical-strong">critical-strong</dt-text>
-    </dt-stack>
-    <dt-stack gap="300" class="d-py8 d-px16 d-bgc-primary-inverted d-bar4">
-      <dt-text tone="primary-inverted">primary-inverted</dt-text>
-      <dt-text tone="secondary-inverted">secondary-inverted</dt-text>
-      <dt-text tone="tertiary-inverted">tertiary-inverted</dt-text>
-      <dt-text tone="muted-inverted">muted-inverted</dt-text>
-      <dt-text tone="disabled-inverted">disabled-inverted</dt-text>
-      <dt-text tone="placeholder-inverted">placeholder-inverted</dt-text>
-      <dt-text tone="success-inverted">success-inverted</dt-text>
-      <dt-text tone="success-strong-inverted">success-strong-inverted</dt-text>
-      <dt-text tone="warning-inverted">warning-inverted</dt-text>
-      <dt-text tone="critical-inverted">critical-inverted</dt-text>
-      <dt-text tone="critical-strong-inverted">critical-strong-inverted</dt-text>
-    </dt-stack>
+  <dt-stack gap="300" class="d-py8 d-px16 d-bar4">
+    <dt-text>primary</dt-text>
+    <dt-text tone="secondary">secondary</dt-text>
+    <dt-text tone="tertiary">tertiary</dt-text>
+    <dt-text tone="muted">muted</dt-text>
+    <dt-text tone="disabled">disabled</dt-text>
+    <dt-text tone="placeholder">placeholder</dt-text>
+    <dt-text tone="success">success</dt-text>
+    <dt-text tone="success-strong">success-strong</dt-text>
+    <dt-text tone="warning">warning</dt-text>
+    <dt-text tone="critical">critical</dt-text>
+    <dt-text tone="critical-strong">critical-strong</dt-text>
   </dt-stack>
 </code-well-header>
 
 <code-example-tabs
 vueCode='
-<dt-text tone="{{tone}}">...</dt-text>
+<dt-text>primary</dt-text>
+<dt-text tone="secondary">secondary</dt-text>
+<dt-text tone="tertiary">tertiary</dt-text>
+<dt-text tone="muted">muted</dt-text>
+<dt-text tone="disabled">disabled</dt-text>
+<dt-text tone="placeholder">placeholder</dt-text>
+<dt-text tone="success">success</dt-text>
+<dt-text tone="success-strong">success-strong</dt-text>
+<dt-text tone="warning">warning</dt-text>
+<dt-text tone="critical">critical</dt-text>
+<dt-text tone="critical-strong">critical-strong</dt-text>
 '/>
 
-## As
+## Render as
 
 Use `as` to declare the underlying HTML tag that the component should render, independent of the visual styling. Defaults to `span`.
 
diff --git a/apps/dialtone-documentation/docs/guides/contributing/index.md b/apps/dialtone-documentation/docs/guides/contributing/index.md
index 97559f7972..aebfca11cf 100644
--- a/apps/dialtone-documentation/docs/guides/contributing/index.md
+++ b/apps/dialtone-documentation/docs/guides/contributing/index.md
@@ -18,8 +18,14 @@ in our Dialtone repository.
 
 ### CSS Architecture
 
+#### Cascade Layers
+
 Dialtone uses [CSS Cascade Layers](../css-layers/) to organize styles into a predictable hierarchy. When contributing CSS, all styles must be wrapped in the appropriate `@layer` block. Read the [CSS Layers Guide](../css-layers/) to understand where to place your styles.
 
+#### Selector Specificity
+
+All component selectors should target a specificity of `(0,1,0)` — a single class. BEM naming naturally achieves this. Use CSS custom properties for modifier overrides instead of increasing selector depth, and wrap bare element descendants (e.g., `th`, `td`, `a`) in `:where()` to keep specificity flat. See the [dialtone-css CONTRIBUTING guide](https://github.com/dialpad/dialtone/blob/staging/packages/dialtone-css/.github/CONTRIBUTING.md) for full details and examples.
+
 ## Adding Icons and Illustrations
 
 If you need to add an icon into Dialtone, here’s how you would go about doing that.
diff --git a/apps/dialtone-documentation/docs/scratch.md b/apps/dialtone-documentation/docs/scratch.md
index fc4649ab36..61feaaf7d7 100644
--- a/apps/dialtone-documentation/docs/scratch.md
+++ b/apps/dialtone-documentation/docs/scratch.md
@@ -3,3 +3,876 @@ layout: Blank
 ---
 
 <!-- Just an empty utilitarian page to explore some in a completely blank context -->
+
+<script setup>
+import { ref, computed } from 'vue';
+import { useThemeManager } from '@composables/useThemeManager';
+
+const {
+  currentMode,
+  currentContrast,
+  currentModeIconName,
+  setMode,
+  setContrast,
+} = useThemeManager();
+
+const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);
+
+const borderless = ref(false);
+const outlined = ref(false);
+const muted = ref(false);
+const showIcon = ref(false);
+const showTabEndIcon = ref(false);
+const showLeading = ref(false);
+const showTrailing = ref(false);
+const size = ref('md');
+const selectOnFocus = ref(false);
+const isDisabled = ref(false);
+const labelSizeSelection = ref('default');
+const resolvedLabelSize = computed(() => labelSizeSelection.value === 'default' ? undefined : labelSizeSelection.value);
+const labelStrengthSelection = ref('default');
+const resolvedLabelStrength = computed(() => labelStrengthSelection.value === 'default' ? undefined : labelStrengthSelection.value);
+const showLabelClass = ref(false);
+const resolvedLabelClass = computed(() => showLabelClass.value ? 'd-bgc-warning' : undefined);
+const checkRadioLabelSize = ref('default');
+const resolvedCheckRadioLabelSize = computed(() => checkRadioLabelSize.value === 'default' ? undefined : checkRadioLabelSize.value);
+const checkRadioLabelStrength = ref('default');
+const resolvedCheckRadioLabelStrength = computed(() => checkRadioLabelStrength.value === 'default' ? undefined : checkRadioLabelStrength.value);
+const showBtnLeading = ref(false);
+const showBtnTrailing = ref(false);
+const showBtnStartIcon = ref(false);
+const showBtnEndIcon = ref(false);
+const removeBtnSlotClass = ref(false);
+const highlightBtnSlotClass = ref(false);
+const showBtnLabelClass = ref(false);
+const resolvedBtnLabelClass = computed(() => showBtnLabelClass.value ? 'd-bgc-warning' : undefined);
+const showTabLabelClass = ref(false);
+const resolvedTabLabelClass = computed(() => showTabLabelClass.value ? 'd-bgc-warning' : undefined);
+const showInputDescription = ref(false);
+const showInputMessages = ref(false);
+const inputMessages = computed(() => showInputMessages.value ? [{ message: 'Error validation message', type: 'error' }] : []);
+const showInputMessagesClass = ref(false);
+const resolvedInputMessagesClass = computed(() => showInputMessagesClass.value ? 'd-bgc-critical' : undefined);
+const showInputDescriptionClass = ref(false);
+const resolvedInputDescriptionClass = computed(() => showInputDescriptionClass.value ? 'd-bgc-success' : undefined);
+const showDescription = ref(false);
+const showCheckRadioMessages = ref(false);
+const checkRadioMessages = computed(() => showCheckRadioMessages.value ? [{ message: 'Error validation message', type: 'error' }] : []);
+const showCheckRadioMessagesClass = ref(false);
+const resolvedCheckRadioMessagesClass = computed(() => showCheckRadioMessagesClass.value ? 'd-bgc-critical' : undefined);
+const showCheckRadioDescriptionClass = ref(false);
+const resolvedCheckRadioDescriptionClass = computed(() => showCheckRadioDescriptionClass.value ? 'd-bgc-success' : undefined);
+const checkRadioDisabled = ref(false);
+</script>
+
+<dt-stack class="d-p32" gap="600">
+  <dt-stack direction="row" gap="400">
+    <dt-text as="h1" kind="headline" size="2xl">
+      Scratchpad
+    </dt-text>
+    <dt-dropdown navigation-type="arrow-keys" placement="bottom-start">
+      <template #anchor>
+        <dt-button
+          v-dt-tooltip:bottom="`Mode: ${capitalize(currentMode)}`"
+          importance="outlined"
+          size="sm"
+          kind="muted"
+          icon-position="right"
+          class="dialtone-shell-btn"
+        >
+          <template #startIcon="{ iconSize }">
+            <dt-icon :name="currentModeIconName" :size="iconSize" />
+          </template>
+        </dt-button>
+      </template>
+      <template #list>
+        <dt-list-item-group
+          heading-class="d-py4 d-px8 d-c-default d-fc-tertiary d-label--sm"
+          heading="Mode"
+        >
+          <dt-list-item
+            role="menuitem"
+            navigation-type="arrow-keys"
+            @click="setMode('system')"
+          >
+            System
+            <template #right>
+              <dt-icon :class="{ 'd-o0': currentMode !== 'system' }" name="check" size="200" />
+            </template>
+          </dt-list-item>
+          <dt-list-item
+            role="menuitem"
+            navigation-type="arrow-keys"
+            @click="setMode('light')"
+          >
+            Light
+            <template #right>
+              <dt-icon :class="{ 'd-o0': currentMode !== 'light' }" name="check" size="200" />
+            </template>
+          </dt-list-item>
+          <dt-list-item
+            role="menuitem"
+            navigation-type="arrow-keys"
+            @click="setMode('dark')"
+          >
+            Dark
+            <template #right>
+              <dt-icon :class="{ 'd-o0': currentMode !== 'dark' }" name="check" size="200" />
+            </template>
+          </dt-list-item>
+        </dt-list-item-group>
+        <dt-dropdown-separator />
+        <dt-list-item-group
+          heading-class="d-py4 d-px8 d-c-default d-fc-tertiary d-label--sm"
+          heading="Contrast"
+        >
+          <dt-list-item
+            role="menuitem"
+            navigation-type="arrow-keys"
+            @click="setContrast('default')"
+          >
+            Default
+            <template #right>
+              <dt-icon :class="{ 'd-o0': currentContrast !== 'default' }" name="check" size="200" />
+            </template>
+          </dt-list-item>
+          <dt-list-item
+            role="menuitem"
+            navigation-type="arrow-keys"
+            @click="setContrast('high')"
+          >
+            High
+            <template #right>
+              <dt-icon :class="{ 'd-o0': currentContrast !== 'high' }" name="check" size="200" />
+            </template>
+          </dt-list-item>
+        </dt-list-item-group>
+      </template>
+    </dt-dropdown>
+  </dt-stack>
+  <dt-stack gap="500">
+    <dt-text as="h1" kind="headline" size="xl">
+      Disabled Button
+    </dt-text>
+    <dt-text as="p" kind="body" size="lg">
+      Not just a matter of applying opacity to whole button, but w/ combination of `color-mix()` and tweaking existing DtButton css variables via `oklch()` of specific properties – separate opacity and saturation for border, bgc, fc, etc.
+    </dt-text>
+    <dt-stack class="d-bgc-moderate-opaque d-p12 d-bar8">
+      <span>
+        <dt-checkbox v-model="isDisabled">Disabled</dt-checkbox>
+      </span>
+    </dt-stack>
+    <dt-stack gap="400" ref="disabledAll">
+      <dt-stack gap="400" :direction="{ 'default': 'column', 'md': 'row' }">
+        <dt-button :disabled="isDisabled"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+        <dt-button :disabled="isDisabled" importance="outlined"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+        <dt-button :disabled="isDisabled" importance="clear"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+      </dt-stack>
+      <dt-stack gap="400" :direction="{ 'default': 'column', 'md': 'row' }">
+        <dt-button :disabled="isDisabled" kind="danger"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+        <dt-button :disabled="isDisabled" kind="danger" importance="outlined"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+        <dt-button :disabled="isDisabled" kind="danger" importance="clear"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+      </dt-stack>
+      <dt-stack gap="400" :direction="{ 'default': 'column', 'md': 'row' }">
+        <dt-button :disabled="isDisabled" kind="positive">Place Call<template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+        <dt-button :disabled="isDisabled" kind="positive" importance="outlined">Place Call<template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+        <dt-button :disabled="isDisabled" kind="positive" importance="clear">Place Call<template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+      </dt-stack>
+      <dt-stack gap="400" :direction="{ 'default': 'column', 'md': 'row' }">
+        <dt-button :disabled="isDisabled" kind="muted" importance="clear"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+        <dt-button :disabled="isDisabled" kind="muted" importance="outlined"> Place Call <template #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template></dt-button>
+      </dt-stack>
+    </dt-stack>
+  </dt-stack>
+  <dt-stack gap="500">
+    <dt-text as="h1" kind="headline" size="xl">
+      Button: Leading/Trailing
+    </dt-text>
+    <dt-text as="p" kind="body" size="lg">
+      Freeform elements that are rendered before/after the button content.
+    </dt-text>
+    <dt-stack gap="500" direction="row" align="baseline" class="d-bgc-moderate-opaque d-p12 d-bar8">
+      <dt-checkbox v-model="showBtnLeading">
+        Leading
+      </dt-checkbox>
+      <dt-checkbox v-model="showBtnTrailing">
+        Trailing
+      </dt-checkbox>
+      <dt-checkbox v-model="showBtnStartIcon">
+        Start Icon
+      </dt-checkbox>
+      <dt-checkbox v-model="showBtnEndIcon">
+        End Icon
+      </dt-checkbox>
+      <dt-checkbox v-model="showBtnLabelClass">
+        `labelClass`
+      </dt-checkbox>
+      <dt-checkbox v-model="removeBtnSlotClass">
+        Remove leading/trailing class
+      </dt-checkbox>
+      <dt-checkbox v-model="highlightBtnSlotClass">
+        Highlight leading/trailing
+      </dt-checkbox>
+    </dt-stack>
+    <dt-stack gap="400" direction="row">
+      <dt-button kind="muted" importance="outlined" size="xs" :leading-class="[removeBtnSlotClass ? undefined : 'd-pl2', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :trailing-class="[removeBtnSlotClass ? undefined : 'd-pr1', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :label-class="resolvedBtnLabelClass">
+        Place Call
+        <template v-if="showBtnLeading" #leading>
+          <dt-badge kind="count" text="1" />
+        </template>
+        <template v-if="showBtnTrailing" #trailing>
+          <dt-badge text="Label" />
+        </template>
+        <template v-if="showBtnStartIcon" #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+        <template v-if="showBtnEndIcon" #endIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+      </dt-button>
+      <dt-button kind="muted" importance="outlined" size="sm" :leading-class="[removeBtnSlotClass ? undefined : 'd-pl2', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :trailing-class="[removeBtnSlotClass ? undefined : 'd-pr4', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :label-class="resolvedBtnLabelClass">
+        Place Call
+        <template v-if="showBtnLeading" #leading>
+          <dt-badge kind="count" text="1" />
+        </template>
+        <template v-if="showBtnTrailing" #trailing>
+          <dt-badge text="Label" />
+        </template>
+        <template v-if="showBtnStartIcon" #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+        <template v-if="showBtnEndIcon" #endIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+      </dt-button>
+      <dt-button kind="muted" importance="outlined" size="md" :leading-class="[removeBtnSlotClass ? undefined : 'd-pl4', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :trailing-class="[removeBtnSlotClass ? undefined : 'd-pr8', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :label-class="resolvedBtnLabelClass">
+        Place Call
+        <template v-if="showBtnLeading" #leading>
+          <dt-badge kind="count" text="1" />
+        </template>
+        <template v-if="showBtnTrailing" #trailing>
+          <dt-badge text="Label" />
+        </template>
+        <template v-if="showBtnStartIcon" #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+        <template v-if="showBtnEndIcon" #endIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+      </dt-button>
+      <dt-button kind="muted" importance="outlined" size="lg" :leading-class="[removeBtnSlotClass ? undefined : 'd-pl8', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :trailing-class="[removeBtnSlotClass ? undefined : 'd-pr10', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :label-class="resolvedBtnLabelClass">
+        Place Call
+        <template v-if="showBtnLeading" #leading>
+          <dt-badge kind="count" text="1" />
+        </template>
+        <template v-if="showBtnTrailing" #trailing>
+          <dt-badge text="Label" />
+        </template>
+        <template v-if="showBtnStartIcon" #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+        <template v-if="showBtnEndIcon" #endIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+      </dt-button>
+      <dt-button kind="muted" importance="outlined" size="xl" :leading-class="[removeBtnSlotClass ? undefined : 'd-pl8', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :trailing-class="[removeBtnSlotClass ? undefined : 'd-pr12', highlightBtnSlotClass ? 'd-bgc-warning' : undefined]" :label-class="resolvedBtnLabelClass">
+        Place Call
+        <template v-if="showBtnLeading" #leading>
+          <dt-badge kind="count" text="1" />
+        </template>
+        <template v-if="showBtnTrailing" #trailing>
+          <dt-badge text="Label" />
+        </template>
+        <template v-if="showBtnStartIcon" #startIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+        <template v-if="showBtnEndIcon" #endIcon="{ iconSize }"> <dt-icon name="box-select" :size="iconSize" /> </template>
+      </dt-button>
+    </dt-stack>
+  </dt-stack>
+  <dt-stack gap="500">
+    <dt-text as="h1" kind="headline" size="xl">
+      Sizing update: Button/Input/Select
+    </dt-text>
+    <dt-stack direction="row">
+      <dt-select-menu
+        size="xs"
+        :options="[
+              { value: ``, label: `Please select one` },
+              { value: `1`, label: `Option 1` },
+              { value: `2`, label: `Option 2` },
+              { value: `3`, label: `Option 3` },
+            ]"
+        :model-value="modelValue"
+        @input="onInput"
+        @change="onChange"
+      />
+      <dt-input type="text" placeholder="Placeholder" size="xs" />
+      <dt-button
+        icon-position="left"
+        kind="default"
+        importance="primary"
+        size="xs"
+      >
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="box-select" :size="iconSize" />
+        </template>
+        Button
+      </dt-button>
+    </dt-stack>
+    <dt-stack direction="row">
+      <dt-select-menu
+        size="sm"
+        :options="[
+              { value: ``, label: `Please select one` },
+              { value: `1`, label: `Option 1` },
+              { value: `2`, label: `Option 2` },
+              { value: `3`, label: `Option 3` },
+            ]"
+        :model-value="modelValue"
+        @input="onInput"
+        @change="onChange"
+      />
+      <dt-input type="text" placeholder="Placeholder" size="sm" />
+      <dt-button
+        icon-position="left"
+        kind="default"
+        importance="primary"
+        size="sm"
+      >
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="box-select" :size="iconSize" />
+        </template>
+        Button
+      </dt-button>
+    </dt-stack>
+    <dt-stack direction="row">
+      <dt-select-menu
+        size="md"
+        :options="[
+              { value: ``, label: `Please select one` },
+              { value: `1`, label: `Option 1` },
+              { value: `2`, label: `Option 2` },
+              { value: `3`, label: `Option 3` },
+            ]"
+        :model-value="modelValue"
+        @input="onInput"
+        @change="onChange"
+      />
+      <dt-input type="text" placeholder="Placeholder" size="md" />
+      <dt-button
+        icon-position="left"
+        kind="default"
+        importance="primary"
+        size="md"
+      >
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="box-select" :size="iconSize" />
+        </template>
+        Button
+      </dt-button>
+    </dt-stack>
+    <dt-stack direction="row">
+      <dt-select-menu
+        size="lg"
+        :options="[
+              { value: ``, label: `Please select one` },
+              { value: `1`, label: `Option 1` },
+              { value: `2`, label: `Option 2` },
+              { value: `3`, label: `Option 3` },
+            ]"
+        :model-value="modelValue"
+        @input="onInput"
+        @change="onChange"
+      />
+      <dt-input type="text" placeholder="Placeholder" size="lg" />
+      <dt-button
+        icon-position="left"
+        kind="default"
+        importance="primary"
+        size="lg"
+      >
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="box-select" :size="iconSize" />
+        </template>
+        Button
+      </dt-button>
+    </dt-stack>
+    <dt-stack direction="row">
+      <dt-select-menu
+        size="xl"
+        :options="[
+              { value: ``, label: `Please select one` },
+              { value: `1`, label: `Option 1` },
+              { value: `2`, label: `Option 2` },
+              { value: `3`, label: `Option 3` },
+            ]"
+        :model-value="modelValue"
+        @input="onInput"
+        @change="onChange"
+      />
+      <dt-input type="text" placeholder="Placeholder" size="xl" />
+      <dt-button
+        icon-position="left"
+        kind="default"
+        importance="primary"
+        size="xl"
+      >
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="box-select" :size="iconSize" />
+        </template>
+        Button
+      </dt-button>
+    </dt-stack>
+  </dt-stack>
+  <dt-stack gap="500">
+    <dt-text as="h1" kind="headline" size="xl">
+      Input / Select
+    </dt-text>
+    <dt-stack gap="500" direction="row" class="d-bgc-moderate-opaque d-p12 d-bar8">
+      <dt-select-menu
+        label="Label Size"
+        :label-visible="false"
+        :options="[
+          { value: 'default', label: 'Default' },
+          { value: 'xs', label: 'xs' },
+          { value: 'sm', label: 'sm' },
+          { value: 'md', label: 'md' },
+          { value: 'lg', label: 'lg' },
+        ]"
+        :model-value="labelSizeSelection"
+        @change="labelSizeSelection = $event"
+      />
+      <dt-select-menu
+        label="Label Strength"
+        :label-visible="false"
+        :options="[
+          { value: 'default', label: 'Default' },
+          { value: 'bold', label: 'bold' },
+          { value: 'semibold', label: 'semibold' },
+          { value: 'medium', label: 'medium' },
+          { value: 'normal', label: 'normal' },
+        ]"
+        :model-value="labelStrengthSelection"
+        @change="labelStrengthSelection = $event"
+      />
+      <dt-checkbox v-model="showLabelClass">`labelClass`</dt-checkbox>
+      <dt-checkbox v-model="showInputDescription">Description</dt-checkbox>
+      <dt-checkbox v-model="showInputMessages">Messages</dt-checkbox>
+      <dt-checkbox v-model="showInputMessagesClass">`messagesClass`</dt-checkbox>
+      <dt-checkbox v-model="showInputDescriptionClass">`descriptionClass`</dt-checkbox>
+    </dt-stack>
+    <dt-stack direction="row" gap="600">
+      <dt-stack gap="400" class="d-fl1">
+        <dt-input label="Extra Small" type="text" placeholder="Placeholder" size="xs" :label-size="resolvedLabelSize" :label-strength="resolvedLabelStrength" :label-class="resolvedLabelClass" :description="showInputDescription ? 'Description text' : undefined" :messages="inputMessages" :messages-class="resolvedInputMessagesClass" :description-class="resolvedInputDescriptionClass" />
+        <dt-input label="Small" type="text" placeholder="Placeholder" size="sm" :label-size="resolvedLabelSize" :label-strength="resolvedLabelStrength" :label-class="resolvedLabelClass" :description="showInputDescription ? 'Description text' : undefined" :messages="inputMessages" :messages-class="resolvedInputMessagesClass" :description-class="resolvedInputDescriptionClass" />
+        <dt-input label="Medium" type="text" placeholder="Placeholder" size="md" :label-size="resolvedLabelSize" :label-strength="resolvedLabelStrength" :label-class="resolvedLabelClass" :description="showInputDescription ? 'Description text' : undefined" :messages="inputMessages" :messages-class="resolvedInputMessagesClass" :description-class="resolvedInputDescriptionClass" />
+        <dt-input label="Large" type="text" placeholder="Placeholder" size="lg" :label-size="resolvedLabelSize" :label-strength="resolvedLabelStrength" :label-class="resolvedLabelClass" :description="showInputDescription ? 'Description text' : undefined" :messages="inputMessages" :messages-class="resolvedInputMessagesClass" :description-class="resolvedInputDescriptionClass" />
+        <dt-input label="Extra large" type="text" placeholder="Placeholder" size="xl" :label-size="resolvedLabelSize" :label-strength="resolvedLabelStrength" :label-class="resolvedLabelClass" :description="showInputDescription ? 'Description text' : undefined" :messages="inputMessages" :messages-class="resolvedInputMessagesClass" :description-class="resolvedInputDescriptionClass" />
+      </dt-stack>
+      <dt-stack gap="400" class="d-fl1">
+        <!-- IMPORTANT NOTE: Change model-value to just value in Vue 2 -->
+        <dt-select-menu
+          :options="[
+            { value: ``, label: `Please select one` },
+            { value: `1`, label: `Option 1` },
+            { value: `2`, label: `Option 2` },
+            { value: `3`, label: `Option 3` },
+          ]"
+          label="Label"
+          size="xs"
+          :label-size="resolvedLabelSize"
+          :label-strength="resolvedLabelStrength"
+          :label-class="resolvedLabelClass"
+          :description="showInputDescription ? 'Description text' : undefined"
+          :messages="inputMessages"
+          :messages-class="resolvedInputMessagesClass"
+          :description-class="resolvedInputDescriptionClass"
+          :model-value="modelValue"
+          @input="onInput"
+          @change="onChange"
+        />
+        <dt-select-menu
+          :options="[
+            { value: ``, label: `Please select one` },
+            { value: `1`, label: `Option 1` },
+            { value: `2`, label: `Option 2` },
+            { value: `3`, label: `Option 3` },
+          ]"
+          label="Label"
+          size="sm"
+          :label-size="resolvedLabelSize"
+          :label-strength="resolvedLabelStrength"
+          :label-class="resolvedLabelClass"
+          :description="showInputDescription ? 'Description text' : undefined"
+          :messages="inputMessages"
+          :messages-class="resolvedInputMessagesClass"
+          :description-class="resolvedInputDescriptionClass"
+          :model-value="modelValue"
+          @input="onInput"
+          @change="onChange"
+        />
+        <dt-select-menu
+          :options="[
+            { value: ``, label: `Please select one` },
+            { value: `1`, label: `Option 1` },
+            { value: `2`, label: `Option 2` },
+            { value: `3`, label: `Option 3` },
+          ]"
+          label="Label"
+          size="md"
+          :label-size="resolvedLabelSize"
+          :label-strength="resolvedLabelStrength"
+          :label-class="resolvedLabelClass"
+          :description="showInputDescription ? 'Description text' : undefined"
+          :messages="inputMessages"
+          :messages-class="resolvedInputMessagesClass"
+          :description-class="resolvedInputDescriptionClass"
+          :model-value="modelValue"
+          @input="onInput"
+          @change="onChange"
+        />
+        <dt-select-menu
+          :options="[
+            { value: ``, label: `Please select one` },
+            { value: `1`, label: `Option 1` },
+            { value: `2`, label: `Option 2` },
+            { value: `3`, label: `Option 3` },
+          ]"
+          label="Label"
+          size="lg"
+          :label-size="resolvedLabelSize"
+          :label-strength="resolvedLabelStrength"
+          :label-class="resolvedLabelClass"
+          :description="showInputDescription ? 'Description text' : undefined"
+          :messages="inputMessages"
+          :messages-class="resolvedInputMessagesClass"
+          :description-class="resolvedInputDescriptionClass"
+          :model-value="modelValue"
+          @input="onInput"
+          @change="onChange"
+        />
+        <dt-select-menu
+          :options="[
+            { value: ``, label: `Please select one` },
+            { value: `1`, label: `Option 1` },
+            { value: `2`, label: `Option 2` },
+            { value: `3`, label: `Option 3` },
+          ]"
+          label="Label"
+          size="xl"
+          :label-size="resolvedLabelSize"
+          :label-strength="resolvedLabelStrength"
+          :label-class="resolvedLabelClass"
+          :description="showInputDescription ? 'Description text' : undefined"
+          :messages="inputMessages"
+          :messages-class="resolvedInputMessagesClass"
+          :description-class="resolvedInputDescriptionClass"
+          :model-value="modelValue"
+          @input="onInput"
+          @change="onChange"
+        />
+      </dt-stack>
+    </dt-stack>
+  </dt-stack>
+  <dt-stack gap="500">
+    <dt-text as="h1" kind="headline" size="xl">
+      Tabs
+    </dt-text>
+    <dt-text as="p" kind="body" size="lg">
+      Just straight up refactor to use DtButton instead of custom markup/style. Use mix of DtButton variants depending on `active`. Uses all DtButton sizes (currently at least).
+    </dt-text>
+    <dt-stack gap="500" direction="row" align="baseline" class="d-bgc-moderate-opaque d-p12 d-bar8">
+      <dt-checkbox v-model="borderless">
+        Borderless
+      </dt-checkbox>
+      <dt-checkbox v-model="outlined">
+        Outlined
+      </dt-checkbox>
+      <dt-checkbox v-model="muted">
+        Muted
+      </dt-checkbox>
+      <dt-checkbox v-model="showIcon">
+        Start Icon
+      </dt-checkbox>
+      <dt-checkbox v-model="showTabEndIcon">
+        End Icon
+      </dt-checkbox>
+      <dt-checkbox v-model="showLeading">
+        Leading
+      </dt-checkbox>
+      <dt-checkbox v-model="showTrailing">
+        Trailing
+      </dt-checkbox>
+      <dt-checkbox v-model="selectOnFocus">
+        Select on focus
+      </dt-checkbox>
+      <dt-checkbox v-model="showTabLabelClass">
+        `labelClass`
+      </dt-checkbox>
+      <dt-select-menu
+        :options="[
+          { value: 'xs', label: 'xs' },
+          { value: 'sm', label: 'sm' },
+          { value: 'md', label: 'md (default)' },
+          { value: 'lg', label: 'lg' },
+          { value: 'xl', label: 'xl' },
+        ]"
+        :model-value="size"
+        @change="size = $event"
+      />
+    </dt-stack>
+    <dt-tab-group :borderless="borderless" :kind="muted ? 'muted' : 'default'" :outlined="outlined" :size="size" :activation-mode="selectOnFocus ? 'auto' : 'manual'">
+      <template #tabs>
+        <dt-tab id="1" panel-id="2" selected leading-class="d-pl8" trailing-class="d-pr8" :label-class="resolvedTabLabelClass">
+          <template v-if="showIcon" #startIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          <template v-if="showTabEndIcon" #endIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          Argentina
+          <template v-if="showLeading" #leading>
+            <dt-badge kind="count" text="1" />
+          </template>
+          <template v-if="showTrailing" #trailing>
+            <dt-badge kind="count" text="1" />
+          </template>
+        </dt-tab>
+        <dt-tab id="3" panel-id="4" leading-class="d-pl8" trailing-class="d-pr8" :label-class="resolvedTabLabelClass">
+          <template v-if="showIcon" #startIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          <template v-if="showTabEndIcon" #endIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          United States
+          <template v-if="showLeading" #leading>
+            <dt-badge kind="count" text="1" />
+          </template>
+          <template v-if="showTrailing" #trailing>
+            <dt-badge kind="count" text="1" />
+          </template>
+        </dt-tab>
+        <dt-tab id="5" panel-id="6" :label-class="resolvedTabLabelClass">
+          <template v-if="showIcon" #startIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          <template v-if="showTabEndIcon" #endIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          United Kingdom
+        </dt-tab>
+        <dt-tab id="7" panel-id="8" :label-class="resolvedTabLabelClass">
+          <template v-if="showIcon" #startIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          <template v-if="showTabEndIcon" #endIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          India
+        </dt-tab>
+        <dt-tab id="9" panel-id="10" disabled :label-class="resolvedTabLabelClass">
+          <template v-if="showIcon" #startIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          <template v-if="showTabEndIcon" #endIcon="{ iconSize }">
+            <dt-icon name="box-select" :size="iconSize" />
+          </template>
+          Canada
+        </dt-tab>
+      </template>
+      <div class="d-py8">
+        <dt-tab-panel id="2" tab-id="1">
+          <dt-stack gap="400">
+            <dt-text as="p" kind="body" size="md">Argentina stretches from subtropical forests in the north to glacial landscapes in the south, encompassing the towering Andes mountains and the vast Pampas grasslands in between.</dt-text>
+            <dt-text as="p" kind="body" size="md">Its cities blend European architectural influences with a vibrant local character, while rural traditions of horsemanship and cattle ranching continue to shape the national identity.</dt-text>
+            <dt-text as="p" kind="body" size="md">The country is celebrated for its contributions to tango, wine production, and a culinary culture built around shared meals and regional flavors.</dt-text>
+          </dt-stack>
+        </dt-tab-panel>
+        <dt-tab-panel id="4" tab-id="3">
+          <dt-stack gap="400">
+            <dt-text as="p" kind="body" size="md">The United States spans a broad continental range, from Atlantic coastlines and Appalachian ridges to Great Plains, Rocky Mountain summits, and Pacific shores beyond.</dt-text>
+            <dt-text as="p" kind="body" size="md">Major metropolitan areas serve as centers for finance, technology, and the arts, while smaller communities maintain distinct regional customs, dialects, and culinary traditions.</dt-text>
+            <dt-text as="p" kind="body" size="md">The nation's history of immigration has produced a diverse cultural fabric, with influences from virtually every corner of the globe woven into daily life.</dt-text>
+          </dt-stack>
+        </dt-tab-panel>
+        <dt-tab-panel id="6" tab-id="5">
+          <dt-stack gap="400">
+            <dt-text as="p" kind="body" size="md">The United Kingdom comprises England, Scotland, Wales, and Northern Ireland, each with distinct landscapes ranging from chalk cliffs and moors to highland lochs and green valleys.</dt-text>
+            <dt-text as="p" kind="body" size="md">Its cities layer centuries of history alongside modern architecture, with institutions in education, finance, and governance that have influenced systems around the world.</dt-text>
+            <dt-text as="p" kind="body" size="md">A strong tradition in literature, theater, and music continues to thrive, supported by public institutions and a widespread culture of creative expression.</dt-text>
+          </dt-stack>
+        </dt-tab-panel>
+        <dt-tab-panel id="8" tab-id="7">
+          <dt-stack gap="400">
+            <dt-text as="p" kind="body" size="md">India extends from the Himalayan ranges in the north through fertile river plains to tropical coastlines in the south, supporting an extraordinary range of ecosystems and climates.</dt-text>
+            <dt-text as="p" kind="body" size="md">Hundreds of languages and traditions coexist across its states and territories, producing one of the most culturally varied societies on earth with deep historical roots.</dt-text>
+            <dt-text as="p" kind="body" size="md">A growing technology sector and expanding urban centers complement longstanding agricultural and artisan economies that continue to sustain millions of people.</dt-text>
+          </dt-stack>
+        </dt-tab-panel>
+        <dt-tab-panel id="10" tab-id="9">
+          <dt-stack gap="400">
+            <dt-text as="p" kind="body" size="md">Canada stretches from the Atlantic to the Pacific and northward into the Arctic, encompassing boreal forests, prairies, mountain ranges, and thousands of lakes and waterways.</dt-text>
+            <dt-text as="p" kind="body" size="md">Its cities are known for cultural diversity and livability, while vast rural and wilderness areas support forestry, mining, and agriculture across multiple climate zones.</dt-text>
+            <dt-text as="p" kind="body" size="md">Official bilingualism in English and French reflects a history shaped by Indigenous peoples, European settlement, and ongoing immigration from around the world.</dt-text>
+          </dt-stack>
+        </dt-tab-panel>
+      </div>
+    </dt-tab-group>
+  </dt-stack>
+  <dt-stack gap="500">
+    <dt-text as="h1" kind="headline" size="xl">
+      Notice / Banner / Toast
+    </dt-text>
+    <dt-text as="p" kind="body" size="lg">
+      Updated typography sizing and intelligent icon alignment. Icon margin adjusts based on content layout: title-only, message-only, or title+message.
+    </dt-text>
+    <dt-stack gap="500">
+      <dt-text as="h2" kind="headline" size="lg">
+        Notice
+      </dt-text>
+      <div class="d-d-grid d-g32 d-g-cols2">
+        <dt-stack gap="400">
+          <dt-text as="h3" kind="headline" size="md">Default</dt-text>
+          <dt-notice kind="success" title="Success" hide-action>
+            Action completed successfully.
+          </dt-notice>
+          <dt-notice kind="warning" title="Warning" hide-action>
+            Please review before proceeding.
+          </dt-notice>
+          <dt-notice kind="error" title="Error" hide-action>
+            Something went wrong. Please try again.
+          </dt-notice>
+          <dt-notice kind="base" title="Base" hide-action>
+            A neutral notice for general information.
+          </dt-notice>
+        </dt-stack>
+        <dt-stack gap="400">
+          <dt-text as="h3" kind="headline" size="md">Important</dt-text>
+          <dt-notice kind="info" title="Important info" :important="true" hide-action>
+            Visually prominent variant with filled background.
+          </dt-notice>
+          <dt-notice kind="success" title="Important success" :important="true" hide-action>
+            Visually prominent variant with filled background.
+          </dt-notice>
+          <dt-notice kind="warning" title="Important warning" :important="true" hide-action>
+            Visually prominent variant with filled background.
+          </dt-notice>
+          <dt-notice kind="error" title="Important error" :important="true" hide-action>
+            Visually prominent variant with filled background.
+          </dt-notice>
+        </dt-stack>
+        <dt-stack gap="400">
+          <dt-text as="h3" kind="headline" size="md">Alignment per internal parts</dt-text>
+          <dt-notice kind="info" title="Title only" hide-action />
+          <dt-notice kind="info" hide-action>
+            Message only — icon aligns to center when there is a single line of content.
+          </dt-notice>
+          <dt-notice kind="info" title="Title and message" hide-action>
+            When both title and message are present, the icon aligns to the top of the content stack.
+          </dt-notice>
+        </dt-stack>
+      </div>
+    </dt-stack>
+    <dt-stack gap="500">
+      <dt-text as="h2" kind="headline" size="lg">
+        Banner
+      </dt-text>
+      <dt-stack gap="400">
+        <dt-banner kind="info" title="Info banner" class="d-ps-relative d-zi-base">
+          Banners are more prominent than notices.
+        </dt-banner>
+        <dt-banner kind="success" title="Success banner" class="d-ps-relative d-zi-base">
+          Action completed successfully.
+        </dt-banner>
+        <dt-banner kind="warning" title="Warning banner" class="d-ps-relative d-zi-base">
+          Please review before proceeding.
+        </dt-banner>
+        <dt-banner kind="error" title="Error banner" class="d-ps-relative d-zi-base">
+          Something went wrong.
+        </dt-banner>
+      </dt-stack>
+      <dt-stack gap="400">
+        <dt-text as="h3" kind="headline" size="md">Important</dt-text>
+        <dt-banner kind="info" title="Info banner" :important="true" class="d-ps-relative d-zi-base">
+          Banners are more prominent than notices.
+        </dt-banner>
+        <dt-banner kind="success" title="Success banner" :important="true" class="d-ps-relative d-zi-base">
+          Action completed successfully.
+        </dt-banner>
+        <dt-banner kind="warning" title="Warning banner" :important="true" class="d-ps-relative d-zi-base">
+          Please review before proceeding.
+        </dt-banner>
+        <dt-banner kind="error" title="Error banner" :important="true" class="d-ps-relative d-zi-base">
+          Something went wrong.
+        </dt-banner>
+      </dt-stack>
+    </dt-stack>
+    <dt-stack gap="500">
+      <dt-text as="h2" kind="headline" size="lg">
+        Toast
+      </dt-text>
+      <div class="d-d-grid d-g32 d-g-cols2">
+        <dt-stack gap="400">
+          <dt-text as="h3" kind="headline" size="md">Default</dt-text>
+          <dt-toast :show="true" kind="info" title="Info toast" message="Informational message." :duration="null" />
+          <dt-toast :show="true" kind="success" title="Success toast" message="Action completed." :duration="null" />
+          <dt-toast :show="true" kind="warning" title="Warning toast" message="Review before proceeding." :duration="null" />
+          <dt-toast :show="true" kind="error" title="Error toast" message="Something went wrong." :duration="null" />
+          <dt-toast :show="true" kind="base" title="Base toast" message="Neutral notification." :duration="null" />
+        </dt-stack>
+        <dt-stack gap="400">
+          <dt-text as="h3" kind="headline" size="md">Important</dt-text>
+          <dt-toast :show="true" kind="info" title="Info toast" message="Informational message." :important="true" :duration="null" />
+          <dt-toast :show="true" kind="success" title="Success toast" message="Action completed." :important="true" :duration="null" />
+          <dt-toast :show="true" kind="warning" title="Warning toast" message="Review before proceeding." :important="true" :duration="null" />
+          <dt-toast :show="true" kind="error" title="Error toast" message="Something went wrong." :important="true" :duration="null" />
+          <dt-toast :show="true" kind="base" title="Base toast" message="Neutral notification." :important="true" :duration="null" />
+        </dt-stack>
+        <dt-stack gap="400">
+          <dt-text as="h3" kind="headline" size="md">Alignment per internal parts</dt-text>
+          <dt-toast :show="true" kind="info" title="Title only" :duration="null" />
+          <dt-toast :show="true" kind="info" message="Action completed." :duration="null" />
+          <dt-toast :show="true" kind="info" title="Title and message" message="Review before proceeding." :duration="null" />
+        </dt-stack>
+      </div>
+    </dt-stack>
+  </dt-stack>
+  <dt-stack gap="500">
+    <dt-text as="h1" kind="headline" size="xl">
+      Radio / Checkbox
+    </dt-text>
+    <dt-stack gap="500" direction="row" class="d-bgc-moderate-opaque d-p12 d-bar8">
+      <dt-select-menu
+        label="Label Size"
+        :label-visible="false"
+        :options="[
+          { value: 'default', label: 'Default' },
+          { value: 'xs', label: 'xs' },
+          { value: 'sm', label: 'sm' },
+          { value: 'md', label: 'md' },
+          { value: 'lg', label: 'lg' },
+        ]"
+        :model-value="checkRadioLabelSize"
+        @change="checkRadioLabelSize = $event"
+      />
+      <dt-select-menu
+        label="Label Strength"
+        :label-visible="false"
+        :options="[
+          { value: 'default', label: 'Default' },
+          { value: 'bold', label: 'bold' },
+          { value: 'semibold', label: 'semibold' },
+          { value: 'medium', label: 'medium' },
+          { value: 'normal', label: 'normal' },
+        ]"
+        :model-value="checkRadioLabelStrength"
+        @change="checkRadioLabelStrength = $event"
+      />
+      <dt-checkbox v-model="showDescription">Description</dt-checkbox>
+      <dt-checkbox v-model="checkRadioDisabled">Disabled</dt-checkbox>
+      <dt-checkbox v-model="showLabelClass">`labelClass`</dt-checkbox>
+      <dt-checkbox v-model="showCheckRadioMessages">Messages</dt-checkbox>
+      <dt-checkbox v-model="showCheckRadioMessagesClass">`messagesClass`</dt-checkbox>
+      <dt-checkbox v-model="showCheckRadioDescriptionClass">`descriptionClass`</dt-checkbox>
+    </dt-stack>
+    <dt-stack gap="500" direction="row">
+      <dt-stack gap="400" class="d-fl1">
+        <dt-text as="h2" kind="headline" size="lg">Checkbox</dt-text>
+        <dt-checkbox label="Checkbox label" :label-size="resolvedCheckRadioLabelSize" :label-strength="resolvedCheckRadioLabelStrength" :label-class="resolvedLabelClass" :disabled="checkRadioDisabled" :description="showDescription ? 'Description text for this checkbox' : undefined" :messages="checkRadioMessages" :messages-class="resolvedCheckRadioMessagesClass" :description-class="resolvedCheckRadioDescriptionClass" />
+        <dt-checkbox label="Checkbox label" :label-size="resolvedCheckRadioLabelSize" :label-strength="resolvedCheckRadioLabelStrength" :label-class="resolvedLabelClass" :disabled="checkRadioDisabled" :description="showDescription ? 'Description text for this checkbox' : undefined" :messages="checkRadioMessages" :messages-class="resolvedCheckRadioMessagesClass" :description-class="resolvedCheckRadioDescriptionClass" />
+        <dt-checkbox label="Checkbox label" :label-size="resolvedCheckRadioLabelSize" :label-strength="resolvedCheckRadioLabelStrength" :label-class="resolvedLabelClass" :disabled="checkRadioDisabled" :description="showDescription ? 'Description text for this checkbox' : undefined" :messages="checkRadioMessages" :messages-class="resolvedCheckRadioMessagesClass" :description-class="resolvedCheckRadioDescriptionClass" />
+      </dt-stack>
+      <dt-stack gap="400" class="d-fl1">
+        <dt-text as="h2" kind="headline" size="lg">Radio</dt-text>
+        <dt-radio label="Radio label" value="1" :label-size="resolvedCheckRadioLabelSize" :label-strength="resolvedCheckRadioLabelStrength" :label-class="resolvedLabelClass" :disabled="checkRadioDisabled" :description="showDescription ? 'Description text for this radio' : undefined" :messages="checkRadioMessages" :messages-class="resolvedCheckRadioMessagesClass" :description-class="resolvedCheckRadioDescriptionClass" />
+        <dt-radio label="Radio label" value="2" :label-size="resolvedCheckRadioLabelSize" :label-strength="resolvedCheckRadioLabelStrength" :label-class="resolvedLabelClass" :disabled="checkRadioDisabled" :description="showDescription ? 'Description text for this radio' : undefined" :messages="checkRadioMessages" :messages-class="resolvedCheckRadioMessagesClass" :description-class="resolvedCheckRadioDescriptionClass" />
+        <dt-radio label="Radio label" value="3" :label-size="resolvedCheckRadioLabelSize" :label-strength="resolvedCheckRadioLabelStrength" :label-class="resolvedLabelClass" :disabled="checkRadioDisabled" :description="showDescription ? 'Description text for this radio' : undefined" :messages="checkRadioMessages" :messages-class="resolvedCheckRadioMessagesClass" :description-class="resolvedCheckRadioDescriptionClass" />
+      </dt-stack>
+    </dt-stack>
+  </dt-stack>
+</dt-stack>
+<div class="d-h768"></div>
diff --git a/apps/dialtone-documentation/docs/utilities/borders/radius.md b/apps/dialtone-documentation/docs/utilities/borders/radius.md
index 06d331fb90..20bd9468ee 100644
--- a/apps/dialtone-documentation/docs/utilities/borders/radius.md
+++ b/apps/dialtone-documentation/docs/utilities/borders/radius.md
@@ -14,7 +14,7 @@ Use `d-bar{n}` to change the border radius on all corners of your element.
     :direction="{ 'default': 'column', 'md': 'row' }"
   >
     <div
-      v-for="r in [0, 1, 2, 4, 8, 12, 16, 24, 32]"
+      v-for="r in [0, 1, 2, 4, 6, 8, 12, 16, 24, 32]"
       class="d-p16 d-ba d-baw2 d-bgc-primary d-ws-nowrap"
       :class="`d-bar${r}`"
     >
@@ -28,6 +28,7 @@ Use `d-bar{n}` to change the border radius on all corners of your element.
 <div class="d-bar1">...</div>
 <div class="d-bar2">...</div>
 <div class="d-bar4">...</div>
+<div class="d-bar6">...</div>
 <div class="d-bar8">...</div>
 <div class="d-bar12">...</div>
 <div class="d-bar16">...</div>
@@ -110,7 +111,7 @@ Use `d-b{a|t|r|b|l}r-circle` to change the border radius of your element to a ci
       </tr>
     </tbody>
     <tbody v-for="i in ['a', 't', 'r', 'b', 'l']">
-      <tr v-for="(val, token) in {'--dt-size-radius-0': '0', '--dt-size-radius-100': '1', '--dt-size-radius-200': '2', '--dt-size-radius-300': '4', '--dt-size-radius-400': '8', '--dt-size-radius-450': '12', '--dt-size-radius-500': '16', '--dt-size-550': '24', '--dt-size-radius-600': '32', '--dt-size-radius-circle': '-circle', '--dt-size-radius-pill': '-pill'}">
+      <tr v-for="(val, token) in {'--dt-size-radius-0': '0', '--dt-size-radius-100': '1', '--dt-size-radius-200': '2', '--dt-size-radius-300': '4', '--dt-size-radius-350': '6', '--dt-size-radius-400': '8', '--dt-size-radius-450': '12', '--dt-size-radius-500': '16', '--dt-size-550': '24', '--dt-size-radius-600': '32', '--dt-size-radius-circle': '-circle', '--dt-size-radius-pill': '-pill'}">
         <th scope="row" class="d-code--sm d-docsite-code">.d-b{{ i }}r{{ val }}</th>
         <td>
           <dt-stack direction="row" justify="between" align="center">
diff --git a/apps/dialtone-documentation/project.json b/apps/dialtone-documentation/project.json
index 6faca841ce..4589e9c1cb 100644
--- a/apps/dialtone-documentation/project.json
+++ b/apps/dialtone-documentation/project.json
@@ -40,7 +40,10 @@
         "cwd": "{projectRoot}",
         "commands": [
           {
-            "command": "nx watch --projects=dialtone-css,dialtone-tokens,dialtone-vue -- nx run \\$NX_PROJECT_NAME:build"
+            "command": "nx run dialtone-css:startWatch"
+          },
+          {
+            "command": "nx watch --projects=dialtone-tokens,dialtone-vue -- nx run \\$NX_PROJECT_NAME:build"
           },
           {
             "command": "node scripts/generate-raw-markdown.mjs && vuepress dev docs"
diff --git a/packages/dialtone-css/.github/CONTRIBUTING.md b/packages/dialtone-css/.github/CONTRIBUTING.md
index ac8a81cdf0..46b9a91b49 100644
--- a/packages/dialtone-css/.github/CONTRIBUTING.md
+++ b/packages/dialtone-css/.github/CONTRIBUTING.md
@@ -33,6 +33,85 @@ Component class names use the [Block Element Modifier (BEM)](http://getbem.com/n
 .d-banner--success {} // Modifier
 ```
 
+### Selector specificity
+
+Keeping selector specificity low and predictable is critical for a design system. Consumers need to be able to override component styles without resorting to specificity escalation or `!important`.
+
+#### Why BEM keeps specificity flat
+
+Every BEM selector — block, element, or modifier — is a single class, which means a specificity of `(0,1,0)`. This is the target for all component selectors. When every rule has the same specificity, the cascade is determined by source order alone, which is predictable and easy to reason about.
+
+#### Use CSS custom properties for modifier overrides
+
+When a modifier needs to change a property, prefer overriding a CSS custom property rather than targeting a child with a higher-specificity selector:
+
+```less
+// Preferred — both selectors are (0,1,0)
+.d-banner {
+  --banner-color-background: var(--dt-color-surface-primary);
+  background-color: var(--banner-color-background);
+}
+
+.d-banner--success {
+  --banner-color-background: var(--dt-color-surface-success);
+}
+
+// Avoid — inflates to (0,2,0)
+.d-banner--success .d-banner__icon {
+  color: green;
+}
+```
+
+#### Element-type descendants: wrap in `:where()`
+
+Some components must style bare HTML elements (e.g., `th`, `td`, `a`, `button`, `option` inside a table, toast, or select). These add specificity that makes overrides harder. Wrap them in `:where()` to zero out their specificity contribution:
+
+```less
+// Correct — specificity stays at (0,1,0)
+.d-table {
+  :where(th, td) {
+    padding: var(--dt-size-500);
+  }
+}
+
+// Avoid — specificity is (0,1,1), harder to override
+.d-table {
+  th, td {
+    padding: var(--dt-size-500);
+  }
+}
+```
+
+The same applies to structural pseudo-classes on element selectors:
+
+```less
+// Correct — (0,1,0)
+.d-table :where(tbody tr:last-of-type) :where(td, th) {
+  border-block-end-width: 0;
+}
+
+// Avoid — (0,2,3)
+.d-table tbody tr:last-of-type td, th {
+  border-block-end-width: 0;
+}
+```
+
+Do **not** wrap the component class itself, BEM modifiers, or state pseudo-classes (`:hover`, `:disabled`, `:focus-visible`) in `:where()` — their specificity is intentional.
+
+#### Quick reference
+
+| Selector | Specificity | Verdict |
+|----------|-------------|---------|
+| `.d-banner` | (0,1,0) | Ideal |
+| `.d-banner__dialog` | (0,1,0) | Ideal |
+| `.d-banner--success` | (0,1,0) | Ideal |
+| `.d-table :where(th)` | (0,1,0) | Correct — element wrapped |
+| `.d-table th` | (0,1,1) | Avoid — bare element inflates specificity |
+| `.d-tablist--inverted .d-tab` | (0,2,0) | Acceptable — parent modifier affecting child |
+| `.d-notice.d-notice--truncate .d-notice__content .d-notice__title` | (0,4,0) | Avoid — refactor to use CSS custom properties |
+
+Use the [Specificity Calculator](https://specificity.keegan.st/) to verify selector specificity values when in doubt. It supports CSS Selectors Level 4 including `:where()`, `:is()`, and `:has()`.
+
 ### Immutable utility classes
 
 All of our utility classes are set to `!important`. This is because they are designed to be immutable, and `!important` is the best way we have of achieving immutability in CSS. Utility classes should only be applied at the application level and not within Dialtone Vue components.
diff --git a/packages/dialtone-css/gulpfile.cjs b/packages/dialtone-css/gulpfile.cjs
index 1f969ee676..aec2a39841 100644
--- a/packages/dialtone-css/gulpfile.cjs
+++ b/packages/dialtone-css/gulpfile.cjs
@@ -35,7 +35,7 @@ const path = require('path');
 //  @@ STYLES
 const postCSS = settings.styles ? require('gulp-postcss') : null;
 // crawls .less dependencies for incremental building
-const postCSSNano = settings.styles ? require('cssnano') : null;
+const postCSSNano = settings.styles ? require('cssnano')({ preset: ['default', { calc: false }] }) : null;
 const less = settings.styles ? require('gulp-less') : null;
 const postCSSDialtoneGenerator = settings.styles ? require('./postcss/dialtone-generators.cjs') : null;
 const sourcemaps = settings.styles ? require('gulp-sourcemaps') : null;
@@ -419,6 +419,9 @@ exports.watch = series(
   watchFiles,
 );
 
+// start watching without a prior clean or full build (assumes build already ran).
+exports.startWatch = series(watchFiles);
+
 //  --  CONVERT WEBFONTS
 exports.fonts = series(
   webfonts,
diff --git a/packages/dialtone-css/lib/build/less/components/card.less b/packages/dialtone-css/lib/build/less/components/card.less
index c55d13d357..ae01cfc2e6 100644
--- a/packages/dialtone-css/lib/build/less/components/card.less
+++ b/packages/dialtone-css/lib/build/less/components/card.less
@@ -53,6 +53,7 @@
 //  ----------------------------------------------------------------------------
 .d-card__footer {
   display: flex;
+  gap: var(--dt-size-400);
   align-items: center;
   padding: 0 var(--dt-size-500) var(--dt-size-500);
 }
diff --git a/packages/dialtone-css/lib/build/less/components/selects.less b/packages/dialtone-css/lib/build/less/components/selects.less
index 834f50066f..600f23c817 100644
--- a/packages/dialtone-css/lib/build/less/components/selects.less
+++ b/packages/dialtone-css/lib/build/less/components/selects.less
@@ -54,7 +54,7 @@
   ._input();
 
   // select options can be styled on windows
-  & option {
+  & :where(option) {
     color: var(--dt-color-foreground-secondary);
     background-color: var(--dt-color-surface-secondary);
   }
diff --git a/packages/dialtone-css/lib/build/less/components/table.less b/packages/dialtone-css/lib/build/less/components/table.less
index bdca4c3d57..51694b940d 100644
--- a/packages/dialtone-css/lib/build/less/components/table.less
+++ b/packages/dialtone-css/lib/build/less/components/table.less
@@ -34,7 +34,7 @@
     border-spacing: 0;
 
     // Caption styles
-    .d-table__caption {
+    &__caption {
       margin-block-end: var(--dt-size-400); // 8
       color: var(--table-th-color-text);
       font-weight: var(--dt-font-weight-bold);
@@ -43,11 +43,11 @@
     }
 
     // Table Head Styles
-    thead {
+    :where(thead) {
         border-block-end: var(--dt-size-200) solid var(--table-color-border);
 
         // Column Header Styles
-        th {
+        :where(th) {
             font-size: var(--table-th-font-size);
             line-height: var(--dt-font-line-height-100);
             text-transform: uppercase;
@@ -55,38 +55,35 @@
     }
 
     // Header Styles
-    th {
+    :where(th) {
         color: var(--table-th-color-text);
         font-weight: var(--dt-font-weight-bold);
     }
 
     // Cell Styles
-    td {
+    :where(td) {
         color: var(--table-td-color-text);
     }
 
     // Header & Cell Styles
-    th,
-    td {
+    :where(th, td) {
         padding: var(--dt-size-500); // 16
         text-align: start;
         border-block-end: var(--dt-size-100) solid var(--table-color-border);
     }
 
     // Nested Table Body, First Row Styles, used internally on the Dialtone site
-    tbody + tbody tr:first-of-type {
+    :where(tbody + tbody tr:first-of-type) {
         // Header & Cell Styles
-        td,
-        th {
+        :where(td, th) {
             border-block-start: var(--dt-size-200) solid var(--table-color-border);
         }
     }
 
     // Last Table Row Styles
-    tbody tr:last-of-type {
+    :where(tbody tr:last-of-type) {
         // Header & Cell Styles
-        td,
-        th {
+        :where(td, th) {
             border-block-end-width: 0;
         }
     }
@@ -106,13 +103,13 @@
 //  ----------------------------------------------------------------------------
 .d-table--striped {
     // Row Styles
-    tr:nth-child(even) {
+    :where(tr:nth-child(even)) {
         background-color: var(--dt-color-surface-secondary-opaque);
     }
 
     &.d-table--inverted {
         // Row Styles
-        tr:nth-child(even) {
+        :where(tr:nth-child(even)) {
             background-color: oklch(from var(--dt-color-surface-primary) l c h / 0.1);
         }
     }
diff --git a/packages/dialtone-css/lib/build/less/dialtone.less b/packages/dialtone-css/lib/build/less/dialtone.less
index 31b1750b9b..0dd77691ed 100644
--- a/packages/dialtone-css/lib/build/less/dialtone.less
+++ b/packages/dialtone-css/lib/build/less/dialtone.less
@@ -17,13 +17,20 @@
 @import 'components/root-layout';
 @import 'components/stack';
 @import 'components/text';
+@import 'components/link';
 @import 'components/item-layout';
 @import 'components/avatar';
-@import 'components/badge';
-@import 'components/breadcrumbs';
 @import 'components/button';
-@import 'components/card';
+@import 'components/badge';
 @import 'components/chip';
+@import 'components/keyboard-shortcut';
+@import 'components/mode-island';
+@import 'components/table';
+@import 'components/toggle';
+@import 'components/presence';
+@import 'components/icon';
+@import 'components/emoji';
+@import 'components/emoji-text-wrapper';
 @import 'components/codeblock';
 @import 'components/collapsible';
 @import 'components/combobox';
@@ -31,16 +38,17 @@
 @import 'components/dropdown';
 @import 'components/description-list';
 @import 'components/empty-state';
-@import 'components/forms';
-@import 'components/image-viewer';
 @import 'components/input';
-@import 'components/keyboard-shortcut';
-@import 'components/link';
+@import 'components/selects';
+@import 'components/image-viewer';
+@import 'components/forms';
+@import 'components/tooltip';
+@import 'components/card';
+@import 'components/breadcrumbs';
 @import 'components/list-group'; // Dialtone 5 shim
 @import 'components/list-item-group';
 @import 'components/list-item';
 @import 'components/loader';
-@import 'components/mode-island';
 @import 'components/modal';
 @import 'components/notice';
 @import 'components/toast';
@@ -50,17 +58,9 @@
 @import 'components/radio-checkbox';
 @import 'components/rich-text-editor';
 @import 'components/scroller';
-@import 'components/selects';
 @import 'components/skeleton';
-@import 'components/table';
 @import 'components/tabs';
-@import 'components/tooltip';
-@import 'components/toggle';
-@import 'components/presence';
-@import 'components/icon';
 @import 'components/scrollbar';
-@import 'components/emoji';
-@import 'components/emoji-text-wrapper';
 @import 'components/emoji-picker';
 @import 'components/filter-pill';
 
diff --git a/packages/dialtone-css/postcss/constants.cjs b/packages/dialtone-css/postcss/constants.cjs
index 28ca9696b3..90ec181fbe 100644
--- a/packages/dialtone-css/postcss/constants.cjs
+++ b/packages/dialtone-css/postcss/constants.cjs
@@ -27,6 +27,7 @@ module.exports = {
     1: 'radius-100',
     2: 'radius-200',
     4: 'radius-300',
+    6: 'radius-350',
     8: 'radius-400',
     12: 'radius-450',
     16: 'radius-500',
diff --git a/packages/dialtone-css/project.json b/packages/dialtone-css/project.json
index b5362e6ac2..66d9202fab 100644
--- a/packages/dialtone-css/project.json
+++ b/packages/dialtone-css/project.json
@@ -33,6 +33,20 @@
         "parallel": false
       }
     },
+    "buildWatch": {
+      "executor": "nx:run-commands",
+      "options": {
+        "cwd": "{projectRoot}",
+        "command": "gulp buildWatch"
+      }
+    },
+    "startWatch": {
+      "executor": "nx:run-commands",
+      "options": {
+        "cwd": "{projectRoot}",
+        "command": "gulp startWatch"
+      }
+    },
     "watch": {
       "executor": "nx:run-commands",
       "dependsOn": [
diff --git a/packages/dialtone-tokens/tokens/theme/dp/dark.json b/packages/dialtone-tokens/tokens/theme/dp/dark.json
index ff4762235b..7d41643bdf 100644
--- a/packages/dialtone-tokens/tokens/theme/dp/dark.json
+++ b/packages/dialtone-tokens/tokens/theme/dp/dark.json
@@ -31,7 +31,7 @@
         "type": "color"
       },
       "success": {
-        "value": "{color.green.700}",
+        "value": "{color.green.600}",
         "type": "color"
       },
       "critical-strong": {
@@ -39,7 +39,7 @@
         "type": "color"
       },
       "success-strong": {
-        "value": "{color.green.900}",
+        "value": "{color.green.800}",
         "type": "color"
       },
       "primary-inverted": {
@@ -174,11 +174,11 @@
         "type": "color"
       },
       "warning-strong": {
-        "value": "{color.gold.800}",
+        "value": "{color.gold.700}",
         "type": "color"
       },
       "success-strong": {
-        "value": "{color.green.700}",
+        "value": "{color.green.600}",
         "type": "color"
       },
       "info-strong": {
@@ -570,7 +570,7 @@
         "type": "color"
       },
       "success": {
-        "value": "{color.green.800}",
+        "value": "{color.green.600}",
         "type": "color"
       },
       "brand": {
@@ -598,7 +598,7 @@
         "type": "color"
       },
       "success-strong": {
-        "value": "{color.green.700}",
+        "value": "{color.green.800}",
         "type": "color"
       },
       "warning-strong": {
@@ -1091,6 +1091,14 @@
         },
         "positive": {
           "primary": {
+            "default": {
+              "value": "{color.green.600}",
+              "type": "color"
+            },
+            "hover": {
+              "value": "{color.green.700}",
+              "type": "color"
+            },
             "active": {
               "value": "{action.color.background.positive.primary.default}",
               "type": "color"
diff --git a/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.stories.js b/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.stories.js
index 2b00e324a6..dc2d542e02 100644
--- a/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.stories.js
+++ b/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.stories.js
@@ -22,6 +22,9 @@ export const argTypesData = {
     },
     control: 'text',
   },
+  inverted: {
+    table: { disable: true },
+  },
 };
 
 // Story Collection
diff --git a/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.stories.js b/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.stories.js
index 0b34ec71c2..755eb66dff 100644
--- a/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.stories.js
+++ b/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.stories.js
@@ -51,6 +51,9 @@ export const argTypesData = {
       },
     },
   },
+  inverted: {
+    table: { disable: true },
+  },
 };
 
 // Story Collection
diff --git a/packages/dialtone-vue/components/breadcrumbs/breadcrumbs_variants.story.vue b/packages/dialtone-vue/components/breadcrumbs/breadcrumbs_variants.story.vue
index 2ec3d93b3e..a53902bd2a 100644
--- a/packages/dialtone-vue/components/breadcrumbs/breadcrumbs_variants.story.vue
+++ b/packages/dialtone-vue/components/breadcrumbs/breadcrumbs_variants.story.vue
@@ -4,13 +4,6 @@
       class="d-py16 d-px12"
       :breadcrumbs="$attrs.breadcrumbs"
     />
-    <div class="d-bgc-contrast d-py16 d-px12">
-      <dt-breadcrumbs
-        inverted
-        :breadcrumbs="$attrs.breadcrumbs"
-      />
-    </div>
-
     <dt-breadcrumbs
       class="d-py16 d-px12"
     >
diff --git a/packages/dialtone-vue/components/card/card_default.story.vue b/packages/dialtone-vue/components/card/card_default.story.vue
index c49dbd80b0..a8e6e9f219 100644
--- a/packages/dialtone-vue/components/card/card_default.story.vue
+++ b/packages/dialtone-vue/components/card/card_default.story.vue
@@ -11,10 +11,17 @@
       v-if="showHeader && variants"
       #header
     >
-      <p>Header</p>
+      <dt-text
+        kind="headline"
+        size="md"
+        as="h3"
+      >
+        Header
+      </dt-text>
       <dt-button
         size="xs"
         importance="clear"
+        kind="muted"
         aria-label="Menu button"
       >
         <template #startIcon>
@@ -39,13 +46,8 @@
         v-else
         tabindex="0"
       >
-        <p class="d-fs-200 d-fw-bold">
-          Lorem ipsum
-        </p>
-        <p class="d-fs-100">
-          Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-          Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-        </p>
+        Default content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
       </div>
     </template>
     <template
@@ -55,7 +57,7 @@
       <dt-button>
         Button 1
       </dt-button>
-      <dt-button class="d-ml8">
+      <dt-button>
         Button 2
       </dt-button>
     </template>
@@ -72,6 +74,7 @@
 import DtCard from './card.vue';
 import { DtIcon } from '@/components/icon';
 import { DtButton } from '@/components/button';
+import { DtText } from '@/components/text';
 
 export default {
   name: 'DtCardDefault',
@@ -79,6 +82,7 @@ export default {
     DtCard,
     DtButton,
     DtIcon,
+    DtText,
   },
 
   props: {
diff --git a/packages/dialtone-vue/components/filter_pill/filter_pill.stories.js b/packages/dialtone-vue/components/filter_pill/filter_pill.stories.js
index debd40a820..2864cc4ad0 100644
--- a/packages/dialtone-vue/components/filter_pill/filter_pill.stories.js
+++ b/packages/dialtone-vue/components/filter_pill/filter_pill.stories.js
@@ -113,7 +113,7 @@ export const Default = {
   render: DefaultTemplate,
   decorators: [
     () => ({
-      template: `<div class="d-p64"><story /></div>`,
+      template: `<div><story /></div>`,
     }),
   ],
 };
diff --git a/packages/dialtone-vue/components/hovercard/hovercard.stories.js b/packages/dialtone-vue/components/hovercard/hovercard.stories.js
index e321f030bc..d8ff0c8d35 100644
--- a/packages/dialtone-vue/components/hovercard/hovercard.stories.js
+++ b/packages/dialtone-vue/components/hovercard/hovercard.stories.js
@@ -172,11 +172,7 @@ const DefaultTemplate = (args, { argTypes }) => createTemplateFromVueFile(
 export const Default = {
   render: DefaultTemplate,
   decorators: [() => ({
-    template: `<dt-stack direction="row" justify="center" align="center" class="d-h464">
-      <div class="d-w164">
-        <story />
-      </div>
-    </dt-stack>`,
+    template: `<div> <story /> </div>`,
   })],
 
   args: {},
@@ -190,8 +186,7 @@ const ManyTemplate = (args, { argTypes }) => createTemplateFromVueFile(
 export const Many = {
   render: ManyTemplate,
   decorators: [() => ({
-    template: `<div class="d-wmx464"><story />
-    </div>`,
+    template: `<div><story /></div>`,
   })],
   args: { ...Default.args, offset: [0, 5] },
 };
@@ -204,11 +199,7 @@ const InputTemplate = (args, { argTypes }) => createTemplateFromVueFile(
 export const WithInput = {
   render: InputTemplate,
   decorators: [() => ({
-    template: `<dt-stack direction="row" justify="center" align="center" class="d-h464">
-      <div class="d-w164">
-        <story />
-      </div>
-    </dt-stack>`,
+    template: `<div><story /></div>`,
   })],
   args: { ...Default.args, offset: [0, 5] },
 };
diff --git a/packages/dialtone-vue/components/icon/icon_variants.story.vue b/packages/dialtone-vue/components/icon/icon_variants.story.vue
index 361caad445..c5bd30176a 100644
--- a/packages/dialtone-vue/components/icon/icon_variants.story.vue
+++ b/packages/dialtone-vue/components/icon/icon_variants.story.vue
@@ -5,15 +5,25 @@
       :key="category"
     >
       <h2
-        class="d-tt-capitalize d-my8"
+        class="d-tt-capitalize d-my16"
         v-text="category"
       />
-      <dt-icon
-        v-for="icon in Object.keys(icons).slice(0, $attrs.limit)"
-        :key="`${category}-${icon}`"
-        :name="icon"
-        class="d-m8"
-      />
+      <dt-stack
+        direction="row"
+        class="d-fw-wrap"
+        gap="500"
+      >
+        <dt-stack
+          v-for="icon in Object.keys(icons).slice(0, $attrs.limit)"
+          :key="`${category}-${icon}`"
+          :title="icon"
+        >
+          <dt-icon
+            :name="icon"
+            size="300"
+          />
+        </dt-stack>
+      </dt-stack>
     </template>
   </div>
 </template>
@@ -21,10 +31,11 @@
 <script>
 import { DtIcon } from './';
 import { categories } from '@dialpad/dialtone-icons/keywords-icons.json';
+import { DtStack } from '../stack';
 
 export default {
   name: 'IconDefault',
-  components: { DtIcon },
+  components: { DtIcon, DtStack },
   data () {
     return {
       categories,
diff --git a/packages/dialtone-vue/components/input_group/input_group.stories.js b/packages/dialtone-vue/components/input_group/input_group.stories.js
index 96bb20d1ae..66be65e0e3 100644
--- a/packages/dialtone-vue/components/input_group/input_group.stories.js
+++ b/packages/dialtone-vue/components/input_group/input_group.stories.js
@@ -71,6 +71,12 @@ export const argTypesData = {
       },
     },
   },
+  legendClass: {
+    control: 'text',
+  },
+  messagesClass: {
+    control: 'text',
+  },
 
   // Directives
   'v-model': {
@@ -100,6 +106,7 @@ export const argTypesData = {
 export default {
   title: 'Components/Input Group',
   component: DtInputGroup,
+  tags: ['!dev', '!autodocs'],
   args: argsData,
   argTypes: argTypesData,
   excludeStories: /.*Data$/,
diff --git a/packages/dialtone-vue/components/input_group/input_group_variants.story.vue b/packages/dialtone-vue/components/input_group/input_group_variants.story.vue
index c81d20ab5a..846f646663 100644
--- a/packages/dialtone-vue/components/input_group/input_group_variants.story.vue
+++ b/packages/dialtone-vue/components/input_group/input_group_variants.story.vue
@@ -1,5 +1,8 @@
 <template>
-  <div id="components-input-group--variants-container">
+  <dt-stack
+    id="components-input-group--variants-container"
+    gap="400"
+  >
     <!-- Default -->
     <dt-input-group
       name="input-group-default"
@@ -87,18 +90,19 @@
       <inputs-decorator />
     </dt-input-group>
     <!-- With Error Messages Hidden -->
-  </div>
+  </dt-stack>
 </template>
 
 <script>
 import { VALIDATION_MESSAGE_TYPES } from '@/common/constants';
 import InputsDecorator from './decorators/inputs.vue';
 import DtInputGroup from './input_group.vue';
+import DtStack from '../stack/stack.vue';
 
 export default {
   name: 'InputGroupVariants',
 
-  components: { InputsDecorator, DtInputGroup },
+  components: { InputsDecorator, DtInputGroup, DtStack },
 
   created () {
     this.VALIDATION_MESSAGE_TYPES = VALIDATION_MESSAGE_TYPES;
diff --git a/packages/dialtone-vue/components/kitchen_sink/kitchen_sink_view.vue b/packages/dialtone-vue/components/kitchen_sink/kitchen_sink_view.vue
index bb070bf140..b0bdf0f93b 100644
--- a/packages/dialtone-vue/components/kitchen_sink/kitchen_sink_view.vue
+++ b/packages/dialtone-vue/components/kitchen_sink/kitchen_sink_view.vue
@@ -256,4 +256,7 @@ onMounted(async () => {
 .kitchen-sink__section {
   scroll-margin-top: var(--dt-size-750);
 }
+[outline] {
+  outline: 2px solid orangered;
+}
 </style>
diff --git a/packages/dialtone-vue/components/link/link.stories.js b/packages/dialtone-vue/components/link/link.stories.js
index 783b663648..2a08ab4706 100644
--- a/packages/dialtone-vue/components/link/link.stories.js
+++ b/packages/dialtone-vue/components/link/link.stories.js
@@ -12,7 +12,6 @@ export const argsData = {
   href: '#',
   to: null,
   replace: false,
-  inverted: false,
   kind: '',
   rel: undefined,
   onClick: action('click'),
@@ -40,7 +39,7 @@ export const argTypesData = {
     },
   },
   inverted: {
-    control: 'boolean',
+    table: { disable: true },
   },
   href: {
     description: 'URL for anchor link navigation. Renders as a native <a> element.',
diff --git a/packages/dialtone-vue/components/link/link.vue b/packages/dialtone-vue/components/link/link.vue
index 266691c472..8ee5c05a7a 100644
--- a/packages/dialtone-vue/components/link/link.vue
+++ b/packages/dialtone-vue/components/link/link.vue
@@ -40,6 +40,7 @@ export default {
      * Determines whether the link should have inverted styling
      * default is false.
      * @values true, false
+     * @ignore
      */
     inverted: {
       type: Boolean,
diff --git a/packages/dialtone-vue/components/link/link_default.story.vue b/packages/dialtone-vue/components/link/link_default.story.vue
index a933934f6b..013981decc 100644
--- a/packages/dialtone-vue/components/link/link_default.story.vue
+++ b/packages/dialtone-vue/components/link/link_default.story.vue
@@ -6,6 +6,7 @@
       :replace="$attrs.replace"
       :kind="$attrs.kind"
       :inverted="$attrs.inverted"
+      :underline="$attrs.underline"
       :rel="$attrs.rel"
       @click="$attrs.onClick"
       @focusin="$attrs.onFocusIn"
diff --git a/packages/dialtone-vue/components/link/link_variants.story.vue b/packages/dialtone-vue/components/link/link_variants.story.vue
index ff1216212d..046b4537eb 100644
--- a/packages/dialtone-vue/components/link/link_variants.story.vue
+++ b/packages/dialtone-vue/components/link/link_variants.story.vue
@@ -2,35 +2,36 @@
   <div>
     <dt-stack
       gap="400"
-      direction="row"
-      class="d-p8"
     >
-      <dt-link
-        v-for="kind in LINK_VARIANTS"
-        :key="kind"
-        href="#"
-        :kind="kind"
-      >
-        {{ kind }} link
-      </dt-link>
-    </dt-stack>
-    <div class="d-bgc-contrast">
       <dt-stack
-        gap="400"
+        class="d-fw-wrap"
         direction="row"
-        class="d-p8"
+        gap="400"
+        align="baseline"
       >
         <dt-link
           v-for="kind in LINK_VARIANTS"
           :key="kind"
-          inverted
           href="#"
           :kind="kind"
         >
-          {{ kind }} inverted
+          {{ kind }} link
+        </dt-link>
+      </dt-stack>
+      <dt-stack
+        class="d-fw-wrap"
+        direction="row"
+        gap="400"
+        align="baseline"
+      >
+        <dt-link
+          href="#"
+          :underline="false"
+        >
+          No underline {{ kind }} link
         </dt-link>
       </dt-stack>
-    </div>
+    </dt-stack>
   </div>
 </template>
 
diff --git a/packages/dialtone-vue/components/presence/presence_variants.story.vue b/packages/dialtone-vue/components/presence/presence_variants.story.vue
index a575c0095b..b6a7b41dab 100644
--- a/packages/dialtone-vue/components/presence/presence_variants.story.vue
+++ b/packages/dialtone-vue/components/presence/presence_variants.story.vue
@@ -1,65 +1,48 @@
 <template>
   <div>
-    <dt-stack
-      direction="row"
-      align="center"
-      class="d-p8"
-    >
-      <h1 class="d-fs-200 d-mx4">
+    <div>
+      <h2>
         Active
-      </h1>
+      </h2>
       <dt-presence
         presence="active"
       />
-    </dt-stack>
+    </div>
 
-    <dt-stack
-      direction="row"
-      align="center"
-      class="d-p8"
-    >
-      <h1 class="d-fs-200 d-mx4">
+    <div>
+      <h2>
         Away
-      </h1>
+      </h2>
       <dt-presence
         presence="away"
       />
-    </dt-stack>
+    </div>
 
-    <dt-stack
-      direction="row"
-      align="center"
-      class="d-p8"
-    >
-      <h1 class="d-fs-200 d-mx4">
+    <div>
+      <h2>
         Busy
-      </h1>
+      </h2>
       <dt-presence
         presence="busy"
       />
-    </dt-stack>
+    </div>
 
-    <dt-stack
-      direction="row"
-      align="center"
-      class="d-p8"
-    >
-      <h1 class="d-fs-200 d-mx4">
+    <div>
+      <h2>
         Offline
-      </h1>
+      </h2>
       <dt-presence
         presence="offline"
       />
-    </dt-stack>
+    </div>
   </div>
 </template>
 
 <script>
 import DtPresence from './presence.vue';
-import { DtStack } from '@/components/stack';
 
 export default {
   name: 'DtPresenceVariantsStory',
-  components: { DtPresence, DtStack },
+  components: { DtPresence },
 };
 </script>
diff --git a/packages/dialtone-vue/components/root_layout/root_layout.vue b/packages/dialtone-vue/components/root_layout/root_layout.vue
index a224093b4c..aac04f0a86 100644
--- a/packages/dialtone-vue/components/root_layout/root_layout.vue
+++ b/packages/dialtone-vue/components/root_layout/root_layout.vue
@@ -78,7 +78,8 @@ export default {
     },
 
     /**
-     * DEPRECATED: set the height of the inner element instead.
+     * Set the height of the inner element instead.
+     * @deprecated
      */
     headerHeight: {
       type: String,
@@ -119,7 +120,8 @@ export default {
     },
 
     /**
-     * DEPRECATED: set the width of the inner element instead.
+     * Set the width of the inner element instead.
+     * @deprecated
      */
     sidebarWidth: {
       type: String,
@@ -145,7 +147,8 @@ export default {
     },
 
     /**
-     * DEPRECATED: set the height of the inner element instead.
+     * Set the height of the inner element instead.
+     * @deprecated
      */
     footerHeight: {
       type: String,
diff --git a/packages/dialtone-vue/components/scroller/scroller_default.story.vue b/packages/dialtone-vue/components/scroller/scroller_default.story.vue
index c0f2d5f385..86497beb93 100644
--- a/packages/dialtone-vue/components/scroller/scroller_default.story.vue
+++ b/packages/dialtone-vue/components/scroller/scroller_default.story.vue
@@ -129,7 +129,7 @@ function switchAutoScrolling () {
 .autoscrolling{
   display: flex;
   align-items: center;
-  div {
+  :where(div) {
     background-color: red;
     inline-size: 5px;
     block-size: 5px;
diff --git a/packages/dialtone-vue/components/scroller/scroller_dynamic.story.vue b/packages/dialtone-vue/components/scroller/scroller_dynamic.story.vue
index 50f9d22572..983e126ec6 100644
--- a/packages/dialtone-vue/components/scroller/scroller_dynamic.story.vue
+++ b/packages/dialtone-vue/components/scroller/scroller_dynamic.story.vue
@@ -126,7 +126,7 @@ function replaceItems () {
 .autoscrolling{
   display: flex;
   align-items: center;
-  div {
+  :where(div) {
     background-color: red;
     inline-size: 5px;
     block-size: 5px;
diff --git a/packages/dialtone-vue/components/text/text_variants.story.vue b/packages/dialtone-vue/components/text/text_variants.story.vue
index 13fa9b653b..7d93b79ac2 100644
--- a/packages/dialtone-vue/components/text/text_variants.story.vue
+++ b/packages/dialtone-vue/components/text/text_variants.story.vue
@@ -228,24 +228,6 @@
               </dt-stack>
             </div>
           </div>
-
-          <div>
-            <div class="d-ba d-bc-default d-p16 d-bar8 d-bgc-primary-inverted">
-              <dt-stack
-                direction="row"
-                gap="400"
-                class="d-fw-wrap"
-              >
-                <dt-text
-                  v-for="tone in invertedToneExamples"
-                  :key="tone"
-                  :tone="tone"
-                >
-                  {{ tone }}
-                </dt-text>
-              </dt-stack>
-            </div>
-          </div>
         </dt-stack>
       </section>
 
@@ -400,7 +382,7 @@
             >
               {{ item.wrap.charAt(0).toUpperCase() + item.wrap.slice(1) }}
             </dt-text>
-            <div class="d-ba d-bc-default d-of-hidden d-p16 d-bar8 d-w192">
+            <div class="d-ba d-bc-default d-of-hidden d-p16 d-bar8">
               <dt-text
                 kind="headline"
                 size="md"
diff --git a/packages/dialtone-vue/recipes/conversation_view/feed_item_row/feed_item_row_variants.story.vue b/packages/dialtone-vue/recipes/conversation_view/feed_item_row/feed_item_row_variants.story.vue
index de090f57a1..c33fcead6d 100644
--- a/packages/dialtone-vue/recipes/conversation_view/feed_item_row/feed_item_row_variants.story.vue
+++ b/packages/dialtone-vue/recipes/conversation_view/feed_item_row/feed_item_row_variants.story.vue
@@ -308,7 +308,7 @@ const { mockReactions } = useMockReactions();
 <style lang="less" scoped>
   .feed-item-row {
     &__default-story {
-      p {
+      :where(p) {
         color: var(--dt-color-foreground-primary);
         font-size: 15px;
         font-style: normal;

From 3d1d595a6f86687d8cca83a5de6c069d94a9b3f1 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 09:12:17 -0600
Subject: [PATCH 02/47] migrate to dt-text component

---
 .../baseComponents/ComponentVueApiTable.vue   | 33 +++++++++----------
 .../theme/assets/less/dialtone-syntax.less    |  6 ++--
 2 files changed, 19 insertions(+), 20 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentVueApiTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentVueApiTable.vue
index 4379af6ba4..03c5997947 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentVueApiTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentVueApiTable.vue
@@ -46,17 +46,16 @@
           >
             <th scope="row">
               <dt-stack gap="300">
-                <span>
-                  <code class="d-code--sm d-docsite-code">
-                    {{ item.name }}
-                  </code>
-                </span>
-                <div
+                <dt-text as="code" kind="code" size="xs" class="d-docsite-code">
+                  {{ item.name }}
+                </dt-text>
+                <dt-text
                   v-if="item.required"
-                  class="d-fc-critical d-fw-normal"
+                  tone="critical"
+                  strength="normal"
                 >
                   required
-                </div>
+                </dt-text>
                 <span v-if="item.deprecated">
                   <dt-badge
                     type="critical"
@@ -68,9 +67,9 @@
             </th>
 
             <td v-if="withDefault">
-              <code v-if="item.defaultValue" class="d-code--sm d-docsite-code">
+              <dt-text v-if="item.defaultValue" as="code" kind="code" size="xs" class="d-docsite-code">
                 {{ item.defaultValue }}
-              </code>
+              </dt-text>
             </td>
 
             <td class="vue-api-table">
@@ -89,14 +88,14 @@
                     <dt-text v-if="index > 0" tone="muted" as="span" kind="body" size="xs">
                       |
                     </dt-text>
-                    <code class="d-code--sm d-docsite-code">"{{ value }}"</code>
+                    <dt-text as="code" kind="code" size="xs" class="d-docsite-code">
+                      "{{ value }}"
+                    </dt-text>
                   </template>
                 </dt-stack>
-                <span v-else-if="item.type">
-                  <code class="d-code--sm d-docsite-code">
-                    {{ item.type }}
-                  </code>
-                </span>
+                <dt-text v-else-if="item.type" as="code" kind="code" size="xs" class="d-docsite-code">
+                  {{ item.type }}
+                </dt-text>
                 <dt-text
                   v-if="item.description"
                   as="p"
@@ -113,7 +112,7 @@
                   as="p"
                   kind="body"
                   size="sm"
-                  class="d-fc-critical"
+                  tone="critical"
                 >
                   {{ item.deprecatedMessage }}
                 </dt-text>
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
index 0ef0d400e3..ba92c13819 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
@@ -33,11 +33,11 @@ div[class*="language-"] {
   }
 }
 
-code:not(.d-code--md, .d-code--sm) {
+:where(.d-docsite--paragraph > code) {
 	padding: var(--dt-size-200) var(--dt-size-300);
 	color: var(--dt-color-blue-800);
-	background-color: var(--dt-color-surface-info);
-	border-radius: var(--dt-size-100);
+	border-radius: var(--dt-size-200);
+	border: 1px solid var(--dt-color-border-subtle);
 	user-select: all;
 }
 

From a97556271ec7769d7ab3bbf320ec6a0186c86de1 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 09:39:06 -0600
Subject: [PATCH 03/47] migrate ComponentAccessibleTable and
 ComponentClassTable to dt-text component

---
 .../ComponentAccessibleTable.vue              | 41 +++++++++++++------
 .../baseComponents/ComponentClassTable.vue    | 37 ++++++++++++-----
 2 files changed, 54 insertions(+), 24 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentAccessibleTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentAccessibleTable.vue
index 732a81bbb7..f1e0642f05 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentAccessibleTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentAccessibleTable.vue
@@ -35,19 +35,34 @@
             v-for="({ item, applies, description }) in accessible"
             :key="item"
           >
-            <th
-              scope="row"
-              class="d-code--sm d-docsite-code"
-              v-text="item"
-            />
-            <td
-              class="d-code--sm"
-              v-text="applies"
-            />
-            <td
-              class="d-fs-100"
-              v-html="description"
-            />
+            <th scope="row">
+              <dt-text
+                as="span"
+                kind="code"
+                size="xs"
+                class="d-docsite-code"
+              >
+                {{ item }}
+              </dt-text>
+            </th>
+            <td>
+              <dt-text
+                as="code"
+                kind="code"
+                size="xs"
+                class="code-example--inline"
+              >
+                {{ applies }}
+              </dt-text>
+            </td>
+            <td>
+              <dt-text
+                kind="body"
+                size="xs"
+              >
+                {{ description }}
+              </dt-text>
+            </td>
           </tr>
         </tbody>
       </table>
diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentClassTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentClassTable.vue
index 11c66169bf..998d569cad 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentClassTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentClassTable.vue
@@ -37,19 +37,34 @@
           >
             <th
               scope="row"
-              class="d-code--sm d-docsite-code"
-              v-text="className.startsWith('data-') ? className : `.${className}`"
-            />
-            <td class="d-code--sm">
-              <span
+            >
+              <dt-text
+                as="span"
+                kind="code"
+                size="xs"
+                class="d-docsite-code"
+              >
+                {{ className.startsWith('data-') ? className : `.${className}` }}
+              </dt-text>
+            </th>
+            <td>
+              <dt-text
+                as="code"
+                kind="code"
+                size="xs"
                 class="code-example--inline"
-                v-text="applies"
-              />
+              >
+                {{ applies }}
+              </dt-text>
+            </td>
+            <td>
+              <dt-text
+                kind="body"
+                size="xs"
+              >
+                {{ description }}
+              </dt-text>
             </td>
-            <td
-              class="d-fs-100 d-lh-300"
-              v-text="description"
-            />
           </tr>
         </tbody>
       </table>

From a95ff17954b0248f17aafff9ecb0337a1d94f2cb Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 10:08:58 -0600
Subject: [PATCH 04/47] migrate DesignColorTable, NewUtilityClassTable,
 ThemeColorTable, TokenValue, and Page to dt-text component

---
 .../baseComponents/DesignColorTable.vue       | 16 +++++++--
 .../baseComponents/NewUtilityClassTable.vue   | 18 +++++-----
 .../baseComponents/ThemeColorTable.vue        | 33 +++++++++++++++----
 .../baseComponents/tokens/TokenValue.vue      |  8 ++---
 .../docs/.vuepress/theme/components/Page.vue  | 13 +++++---
 5 files changed, 60 insertions(+), 28 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/DesignColorTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/DesignColorTable.vue
index cd001a4263..848a85a21c 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/DesignColorTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/DesignColorTable.vue
@@ -93,10 +93,20 @@ const colors = processColorsDocs(props.excludedColors, props.classPrefix);
             </th>
             <th class="d-lh-300" scope="row">
               <span class="d-tt-capitalize" v-text="color.name" />
-              <span v-if="color.description" class="d-d-block d-fw-normal d-fs-100" v-text="color.description" />
+              <dt-text v-if="color.description" as="span" kind="body" size="xs" strength="normal" class="d-d-block">
+                {{ color.description }}
+              </dt-text>
             </th>
-            <td class="d-code--sm d-docsite-code" v-text="color.tokenName ? `var(${color.tokenName})` : '-'" />
-            <td class="d-code--sm d-docsite-code" v-text="color.utilityClass" />
+            <td>
+              <dt-text as="span" kind="code" size="xs" class="d-docsite-code">
+                {{ color.tokenName ? `var(${color.tokenName})` : '-' }}
+              </dt-text>
+            </td>
+            <td>
+              <dt-text as="span" kind="code" size="xs" class="d-docsite-code">
+                {{ color.utilityClass }}
+              </dt-text>
+            </td>
           </tr>
         </tbody>
       </table>
diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/NewUtilityClassTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/NewUtilityClassTable.vue
index 091b59021f..8854256564 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/NewUtilityClassTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/NewUtilityClassTable.vue
@@ -21,16 +21,16 @@
             v-for="(value, className) in classes"
             :key="className"
           >
-            <th
-              scope="row"
-              class="d-code--sm d-docsite-code"
-              v-text="className"
-            />
-            <td
-              class="d-code--sm d-ws-break-spaces"
-            >
+            <th scope="row">
+              <dt-text as="span" kind="code" size="xs" class="d-docsite-code">
+                {{ className }}
+              </dt-text>
+            </th>
+            <td class="d-ws-break-spaces">
               <dt-stack direction="row" justify="between" align="center" gap="500">
-                <span class="d-fl-grow1 d-code--sm" v-text="value" />
+                <dt-text as="span" kind="code" size="xs" class="d-fl-grow1">
+                  {{ value }}
+                </dt-text>
                 <slot name="example" :class-name="className" />
               </dt-stack>
             </td>
diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ThemeColorTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ThemeColorTable.vue
index e3a505633d..a42853fe4c 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ThemeColorTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ThemeColorTable.vue
@@ -73,13 +73,16 @@
                   class="d-w42 d-h42 d-bar-circle d-ba d-bc-subtle"
                 />
               </dt-stack>
-              <div
+              <dt-text
                 v-else-if="color.property === 'color'"
+                as="p"
                 :style="{ color: `var(${color.variable})` }"
-                class="d-fs-300 d-p6 d-ta-center d-fw-medium"
+                kind="body"
+                size="lg"
+                class="d-p6 d-ta-center d-fw-medium"
               >
                 Ag
-              </div>
+              </dt-text>
               <div
                 v-else-if="color.property === 'border-color'"
                 :class="['d-d-inline-flex d-p4 d-bar-pill', { 'd-bgc-contrast': color.variable.includes('inverted') }]"
@@ -90,10 +93,26 @@
                 />
               </div>
             </td>
-            <th scope="row" class="d-ws-nowrap d-tt-capitalize" v-text="color.section" />
-            <td class="d-tt-capitalize" v-text="color.states" />
-            <td class="d-code--sm d-docsite-code" v-text="color.property" />
-            <td class="d-code--sm d-docsite-code" v-text="color.variable" />
+            <th scope="row">
+              <dt-text as="span" kind="body" size="xs" class="d-tt-capitalize">
+                {{ color.section }}
+              </dt-text>
+            </th>
+            <td>
+              <dt-text as="span" kind="body" size="xs" class="d-tt-capitalize">
+                {{ color.states }}
+              </dt-text>
+            </td>
+            <td>
+              <dt-text as="span" kind="code" size="xs" class="d-docsite-code">
+                {{ color.property }}
+              </dt-text>
+            </td>
+            <td>
+              <dt-text as="span" kind="code" size="xs" class="d-docsite-code">
+                {{ color.variable }}
+              </dt-text>
+            </td>
           </tr>
         </tbody>
       </table>
diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue
index d908acc137..a9e4a99e4b 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue
@@ -1,19 +1,19 @@
 <template>
-  <div class="d-code--sm d-docsite-code">
+  <dt-text as="div" kind="code" size="xs" class="d-docsite-code">
     <div v-if="isCompositionToken(tokenValue)">
       <span v-for="value in tokenValue" :key="value">
         <span
           v-dt-tooltip="getTooltipValue(value)"
-          :class="{ 'd-d-block h:d-fc-secondary d-c-default': getTooltipValue(value) }"
+          :class="{ 'd-d-block h:d-fc-primary d-c-default': getTooltipValue(value) }"
         >
           {{ value }}&nbsp;
         </span>
       </span>
     </div>
     <div v-else>
-      {{ tokenValue }}
+      {{ tokenValue }}s
     </div>
-  </div>
+  </dt-text>
 </template>
 
 <script setup>
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/Page.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/Page.vue
index 3db077f0cf..3a9b166d53 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/Page.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/Page.vue
@@ -27,8 +27,10 @@
           <template #startIcon>
             <dt-icon name="arrow-left" />
           </template>
-          <dt-stack as="span" class="d-ta-left d-p8">
-            <span class="d-body--md-compact d-fc-muted">Previous</span>
+          <dt-stack as="span" class="d-p8">
+            <dt-text as="span" kind="body" size="md" tone="muted">
+              Previous
+            </dt-text>
             <span>{{ prev.text }}</span>
           </dt-stack>
         </dt-button>
@@ -37,7 +39,6 @@
           :to="next.link"
           class="d-wmn40p"
           label-class="d-jc-space-between"
-          icon-position="right"
           importance="outlined"
           kind="muted"
           size="lg"
@@ -45,8 +46,10 @@
           <template #endIcon>
             <dt-icon name="arrow-right" />
           </template>
-          <dt-stack as="span" class="d-ta-left d-p8">
-            <span class="d-body--md-compact d-fc-muted">Next</span>
+          <dt-stack as="span" class="d-p8">
+            <dt-text as="span" kind="body" size="md" tone="muted">
+              Next
+            </dt-text>
             <span>{{ next.text }}</span>
           </dt-stack>
         </dt-button>

From b6838cfbaa60a1618c2ce1fcb3a14000fa4be902 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 10:27:20 -0600
Subject: [PATCH 05/47] mgigrate to dt-text component

---
 .../.vuepress/baseComponents/GradientHero.vue | 10 +++--
 .../.vuepress/baseComponents/IconPopover.vue  | 14 +++---
 .../baseComponents/tokens/TokenTable.vue      | 15 +++----
 .../docs/.vuepress/theme/components/Home.vue  | 44 +++++++++----------
 4 files changed, 42 insertions(+), 41 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/GradientHero.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/GradientHero.vue
index cc28906364..91aa86d8ca 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/GradientHero.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/GradientHero.vue
@@ -1,8 +1,12 @@
 <template>
   <div class="gradient-overlay" style="--overlay-opacity: 0; --text-opacity: .6;">
     <div class="gradient-overlay__overlay" />
-    <h1
-      class="d-headline--xxl d-h100p d-w100p d-d-grid d-plc-center d-ta-center d-fw-medium d-wmx1024 d-m-auto d-p32"
+    <dt-text
+      as="h1"
+      kind="headline"
+      size="2xl"
+      strength="medium"
+      class="d-h100p d-w100p d-d-grid d-plc-center d-ta-center d-wmx1024 d-m-auto d-p32"
       style="
         font-size: 64px;
         font-family: var(--dt-font-family-expressive);
@@ -21,7 +25,7 @@
       >
         Making every business, a better business through design.
       </div>
-    </h1>
+    </dt-text>
   </div>
 </template>
 
diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/IconPopover.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/IconPopover.vue
index 766809f51b..dd8212dd33 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/IconPopover.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/IconPopover.vue
@@ -24,18 +24,16 @@
             size="600"
           />
         </template>
-        <span
-          class="dialtone-icon-card__subtitle d-tt-capitalize d-fc-tertiary"
-          v-text="name"
-        />
+        <dt-text as="span" tone="tertiary" class="dialtone-icon-card__subtitle d-tt-capitalize">
+          {{ name }}
+        </dt-text>
       </dt-button>
     </template>
     <template #headerContent>
       <dt-stack direction="row" align="center" class="d-plc-space-between">
-        <span
-          class="d-tt-capitalize d-fc-primary"
-          v-text="name"
-        />
+        <dt-text as="span" tone="primary" class="d-tt-capitalize">
+          {{ name }}
+        </dt-text>
         <copy-button
           class="d-ml8"
           :text="shareIcon"
diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue
index ab5a9c8a2a..8f29605fb2 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue
@@ -88,16 +88,15 @@
                 :tokens="tokens"
               />
             </th>
-            <td v-if="!isSmallDevice && showValue" class="d-text-code--md d-fc-blue-800 d-ta-right d-wmx164">
-              <token-value :token-value="valueToString(tokenValue)" :tokens="tokens" />
+            <td v-if="!isSmallDevice && showValue" class="d-ta-right d-wmx164">
+              <dt-text as="span" kind="code" size="md" class="d-fc-blue-800">
+                <token-value :token-value="valueToString(tokenValue)" :tokens="tokens" />
+              </dt-text>
             </td>
-            <td
-              v-if="!!tokenList"
-              class="d-text-code--md d-docsite-code"
-            >
-              <div class="d-wmx264">
+            <td v-if="!!tokenList">
+              <dt-text as="div" kind="code" size="md" class="d-docsite-code d-wmx264">
                 {{ remToPixels(tokenValue) }}
-              </div>
+              </dt-text>
             </td>
           </tr>
         </tbody>
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/Home.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/Home.vue
index 41eefa2bf3..0c1d6c0e5c 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/Home.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/Home.vue
@@ -8,13 +8,13 @@
       class="hero__inner-wrapper d-mx-auto d-wmx1340 d-pl24 d-pr32"
     >
       <dt-stack justify="center" class="hero__content">
-        <h1 class="d-headline--xxl d-mb12 d-ff-marketing">
+        <dt-text as="h1" kind="headline" size="2xl" class="d-mb12 d-ff-marketing">
           Improve your UI's reception with Dialtone
-        </h1>
-        <p class="d-fs-300 d-lh-400 d-mb16 d-fc-secondary">
+        </dt-text>
+        <dt-text as="p" kind="body" size="md" density="400" tone="secondary" class="d-mb16">
           Documented styles, components, and utility classes to help you quickly design and build unified experiences
           across Dialpad experiences.
-        </p>
+        </dt-text>
         <dt-stack direction="row" justify="start" class="d-mb32">
           <a
             class="d-td-unset d-d-inline-flex"
@@ -54,14 +54,14 @@
         <router-link class="d-fc-primary h:d-td-underline d-td-none d-bar8 d-pt4" to="/design/">
           <dt-stack gap="600">
             <svg-loader class="d-h96" name="home-design-language" />
-            <h2 class="d-headline--xl d-ff-marketing">
+            <dt-text as="h2" kind="headline" size="xl" class="d-ff-marketing">
               Design Language
-            </h2>
+            </dt-text>
           </dt-stack>
         </router-link>
-        <p class="d-body--md-compact d-fc-secondary">
+        <dt-text as="p" kind="body" size="md" density="200" tone="secondary">
           Foundational color, iconography, and spacing guidelines
-        </p>
+        </dt-text>
         <dt-stack gap="300">
           <dt-link to="/design/">
             Browse Design Guidelines
@@ -72,14 +72,14 @@
         <router-link class="d-fc-primary h:d-td-underline d-td-none d-bar8 d-pt4" to="/components/">
           <dt-stack gap="600">
             <svg-loader class="d-h96" name="home-components" />
-            <h2 class="d-headline--xl d-ff-marketing">
+            <dt-text as="h2" kind="headline" size="xl" class="d-ff-marketing">
               Components
-            </h2>
+            </dt-text>
           </dt-stack>
         </router-link>
-        <p class="d-body--md-compact d-fc-secondary">
+        <dt-text as="p" kind="body" size="md" density="200" tone="secondary">
           Presentational UI components offered in CSS and Vue
-        </p>
+        </dt-text>
         <dt-stack gap="300">
           <dt-link to="/components/">
             Browse CSS Components
@@ -93,14 +93,14 @@
         <router-link class="d-fc-primary h:d-td-underline d-td-none d-bar8 d-pt4" to="/utilities/">
           <dt-stack gap="600">
             <svg-loader class="d-h96" name="home-utilities" />
-            <h2 class="d-headline--xl d-ff-marketing">
+            <dt-text as="h2" kind="headline" size="xl" class="d-ff-marketing">
               Utilities
-            </h2>
+            </dt-text>
           </dt-stack>
         </router-link>
-        <p class="d-body--md-compact d-fc-secondary">
+        <dt-text as="p" kind="body" size="md" density="200" tone="secondary">
           A utility-first CSS framework for building user interfaces.
-        </p>
+        </dt-text>
         <dt-stack gap="300">
           <dt-link to="/utilities/">
             Browse Utility Classes
@@ -111,14 +111,14 @@
         <router-link class="d-fc-primary h:d-td-underline d-td-none d-bar8 d-pt4" to="/guides/">
           <dt-stack gap="600">
             <svg-loader class="d-h96" name="home-guides" />
-            <h2 class="d-headline--xl d-ff-marketing">
+            <dt-text as="h2" kind="headline" size="xl" class="d-ff-marketing">
               Guides
-            </h2>
+            </dt-text>
           </dt-stack>
         </router-link>
-        <p class="d-body--md-compact d-fc-secondary">
+        <dt-text as="p" kind="body" size="md" density="200" tone="secondary">
           Reference guidelines for Accessibility, Writing, and more
-        </p>
+        </dt-text>
         <dt-stack gap="300">
           <dt-link to="/guides/getting-started/">
             Getting Started
@@ -135,9 +135,9 @@
   </section>
   <section class="d-py64 d-ta-center">
     <dt-stack direction="row" gap="500" align="center" class="d-fc-secondary d-px48 d-mx-auto d-d-inline-flex">
-      <h2 class="d-headline--lg d-fw-semibold">
+      <dt-text as="h2" kind="headline" size="lg" strength="semibold">
         Don't see something? Want to contribute?
-      </h2>
+      </dt-text>
       <dt-button
         href="https://dialpad.atlassian.net/servicedesk/customer/portal/123/create/465"
         target="_blank"

From 74b14b6260a67ff2f8656d3ff0408f5cfa34a385 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 10:44:21 -0600
Subject: [PATCH 06/47] migrate to dt-link component with new router-link
 support

---
 .../baseComponents/ComponentHealthStatusTable.vue          | 7 ++-----
 .../docs/.vuepress/baseComponents/FontUtilitiesNotice.vue  | 4 ++--
 .../docs/.vuepress/theme/components/MobileNavbar.vue       | 6 +++---
 apps/dialtone-documentation/docs/components/breadcrumbs.md | 4 ++--
 apps/dialtone-documentation/docs/components/button.md      | 6 +++---
 .../docs/components/keyboard-shortcut.md                   | 4 ++--
 apps/dialtone-documentation/docs/components/link.md        | 4 ++--
 apps/dialtone-documentation/docs/components/table.md       | 4 ++--
 apps/dialtone-documentation/docs/components/tabs.md        | 4 ++--
 9 files changed, 20 insertions(+), 23 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentHealthStatusTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentHealthStatusTable.vue
index c7d446c7ed..477b789aa5 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentHealthStatusTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentHealthStatusTable.vue
@@ -64,12 +64,9 @@
         :key="component.name"
       >
         <th scope="row">
-          <router-link
-            class="d-link"
-            :to="component.url"
-          >
+          <dt-link :to="component.url">
             {{ component.name }}
-          </router-link>
+          </dt-link>
         </th>
         <td
           tabindex="0"
diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue
index 7473a3cf45..a51dfdf341 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue
@@ -7,9 +7,9 @@
   >
     <template #default>
       Reach for the
-      <router-link class="d-fw-semibold d-link d-link--muted" to="/components/text">
+      <dt-link kind="muted" to="/components/text">
         DtText
-      </router-link>
+      </dt-link>
       component before considering any typography utility.
     </template>
   </dt-notice>
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/MobileNavbar.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/MobileNavbar.vue
index 3280bb0dab..1144ce50de 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/MobileNavbar.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/MobileNavbar.vue
@@ -55,16 +55,16 @@
         "
       :class="{ 'd-o0 d-d-none': !isMenuOpen }"
     >
-      <router-link
+      <dt-link
         v-for="link in items"
         :key="link"
         :to="link.link"
-        class="d-link d-mb12"
+        class="d-mb12"
         :class="{ 'router-link-active': isActiveLink(link.text) }"
         @click="toggleNavbar"
       >
         {{ link.text }}
-      </router-link>
+      </dt-link>
     </dt-stack>
   </dt-stack>
 </template>
diff --git a/apps/dialtone-documentation/docs/components/breadcrumbs.md b/apps/dialtone-documentation/docs/components/breadcrumbs.md
index 0a09ca4717..e9182cbb9a 100644
--- a/apps/dialtone-documentation/docs/components/breadcrumbs.md
+++ b/apps/dialtone-documentation/docs/components/breadcrumbs.md
@@ -72,10 +72,10 @@ showHtmlWarning />
 ### Inverted
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>inverted</code> prop has been deprecated in favor of using <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
 
 <code-well-header>
   <dt-mode-island class="d-p16 d-bar8">
diff --git a/apps/dialtone-documentation/docs/components/button.md b/apps/dialtone-documentation/docs/components/button.md
index d32b081c93..a5b818f7a9 100644
--- a/apps/dialtone-documentation/docs/components/button.md
+++ b/apps/dialtone-documentation/docs/components/button.md
@@ -437,10 +437,10 @@ vueCode='
   kind="error"
   class="d-wmx100p d-my16"
 >
-  <code>kind="inverted"</code> has been deprecated in favor of using <router-link to="mode-island.html"> <DtLink>DtModeIsland</DtLink> </router-link> as a wrapper.
+  <code>kind="inverted"</code> has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
 </dt-notice>
 
-In place of <code>kind="inverted"</code>, use the <router-link to="mode-island.html"> <DtLink>DtModeIsland</DtLink> </router-link> component as a wrapper.
+In place of <code>kind="inverted"</code>, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
 
 <code-well-header>
   <dt-split-button
@@ -1319,7 +1319,7 @@ showHtmlWarning />
   kind="info"
   class="d-wmx100p d-my16"
 >
-  <router-link to="split-button.html"> <DtLink>DtSplitButton</DtLink> </router-link> is its own component containing multiple DtButtons.
+  <dt-link to="split-button.html">DtSplitButton</dt-link> is its own component containing multiple DtButtons.
 </dt-notice>
 
 <code-well-header>
diff --git a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
index f4c181d5d9..48390c23e8 100644
--- a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
+++ b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
@@ -40,10 +40,10 @@ vueCode='
 ### Inverted
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>inverted</code> prop has been deprecated in favor of using <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
 
 <code-well-header>
   <dt-mode-island class="d-p16 d-bar8">
diff --git a/apps/dialtone-documentation/docs/components/link.md b/apps/dialtone-documentation/docs/components/link.md
index 1eded95f84..62541cd094 100644
--- a/apps/dialtone-documentation/docs/components/link.md
+++ b/apps/dialtone-documentation/docs/components/link.md
@@ -95,10 +95,10 @@ showHtmlWarning />
   kind="error"
   class="d-wmx100p d-my16"
 >
-  The <code>inverted</code> prop has been deprecated in favor of using <router-link to="mode-island.html"> <DtLink>DtModeIsland</DtLink> </router-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <router-link to="mode-island.html"> <DtLink>DtModeIsland</DtLink> </router-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
 
 <code-well-header>
   <dt-mode-island class="d-p16 d-bar8">
diff --git a/apps/dialtone-documentation/docs/components/table.md b/apps/dialtone-documentation/docs/components/table.md
index 05cd81058c..3a19cfa337 100644
--- a/apps/dialtone-documentation/docs/components/table.md
+++ b/apps/dialtone-documentation/docs/components/table.md
@@ -83,10 +83,10 @@ keywords: ["data table", "grid", "rows", "d-table", "DtTable", "dt-table", "data
 ### Inverted Style
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>d-table--inverted</code> modifier has been deprecated in favor of using <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> as a wrapper.
+  The <code>d-table--inverted</code> modifier has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
 </dt-notice>
 
-In place of the <code>d-table--inverted</code> modifier, wrap the table in the <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> component.
+In place of the <code>d-table--inverted</code> modifier, wrap the table in the <dt-link to="mode-island.html">DtModeIsland</dt-link> component.
 
 <code-well-header>
   <dt-mode-island class="d-p16 d-bar8">
diff --git a/apps/dialtone-documentation/docs/components/tabs.md b/apps/dialtone-documentation/docs/components/tabs.md
index c0e1fd24cc..2b7fd6cb93 100644
--- a/apps/dialtone-documentation/docs/components/tabs.md
+++ b/apps/dialtone-documentation/docs/components/tabs.md
@@ -176,10 +176,10 @@ showHtmlWarning />
 ### Inverted
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>inverted</code> prop has been deprecated in favor of using <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <router-link to="mode-island.html"><DtLink>DtModeIsland</DtLink></router-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
 
 <code-well-header>
   <dt-mode-island class="d-p16 d-bar8">

From fd48e9184acb70aad6d0fce53cde15a6f59bac9c Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 10:54:34 -0600
Subject: [PATCH 07/47] remove unnecessary anchor wrapper around external link
 button

---
 .../theme/components/SidebarItem.vue          | 44 +++++++++----------
 1 file changed, 20 insertions(+), 24 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue
index 30b66aec50..ecd5073bac 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/SidebarItem.vue
@@ -87,35 +87,31 @@
                 </dt-badge>
               </dt-stack>
             </div>
-            <a
+            <dt-button
               v-else-if="isExternalLink(subItem.link)"
               :href="subItem.link"
               target="_blank"
               rel="noopener noreferrer"
-              class="d-td-none"
+              importance="clear"
+              kind="muted"
+              label-class="d-jc-flex-start d-ta-left d-fw-normal"
+              :class="[
+                'dialtone-shell-btn d-w100p d-tw-pretty',
+                { 'd-pl48': depth === 0 },
+                { 'd-pl64': depth === 1 },
+              ]"
             >
-              <dt-button
-                importance="clear"
-                kind="muted"
-                label-class="d-jc-flex-start d-ta-left d-fw-normal"
-                :class="[
-                  'dialtone-shell-btn d-w100p d-tw-pretty',
-                  { 'd-pl48': depth === 0 },
-                  { 'd-pl64': depth === 1 },
-                ]"
-              >
-                <dt-stack as="span" direction="row" justify="space-between" class="d-w100p">
-                  {{ subItem.text }}
-                  <dt-badge
-                    v-if="subItem.status === 'beta'"
-                    class="d-fw-normal d-ml4"
-                    type="info"
-                  >
-                    Beta
-                  </dt-badge>
-                </dt-stack>
-              </dt-button>
-            </a>
+              <dt-stack as="span" direction="row" justify="space-between" class="d-w100p">
+                {{ subItem.text }}
+                <dt-badge
+                  v-if="subItem.status === 'beta'"
+                  class="d-fw-normal d-ml4"
+                  type="info"
+                >
+                  Beta
+                </dt-badge>
+              </dt-stack>
+            </dt-button>
             <dt-button
               v-else
               :to="subItem.link"

From a4e6b6fcd3776f9226743bca73a6e0c255234f3c Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 10:59:31 -0600
Subject: [PATCH 08/47] migrate TocItem and index page to dt-button component
 with router-link support

---
 .../.vuepress/theme/components/TocItem.vue    | 14 ++++---
 apps/dialtone-documentation/docs/index.md     | 42 ++++++++-----------
 2 files changed, 26 insertions(+), 30 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
index f1139a72a2..875a0fd81c 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
@@ -1,13 +1,15 @@
 <template>
-  <RouterLink
-    :class="[
-      'd-btn d-btn--sm d-btn--muted d-w100p d-jc-flex-start d-fw-normal d-tw-pretty',
-      { 'd-btn--active': active },
-    ]"
+  <dt-button
     :to="to"
+    :active="active"
+    importance="clear"
+    kind="muted"
+    size="sm"
+    label-class="d-jc-flex-start d-fw-normal d-tw-pretty"
+    class="d-w100p"
   >
     {{ text }}
-  </RouterLink>
+  </dt-button>
 </template>
 
 <script setup>
diff --git a/apps/dialtone-documentation/docs/index.md b/apps/dialtone-documentation/docs/index.md
index 3e8f6ae594..b3b7d7d6cf 100644
--- a/apps/dialtone-documentation/docs/index.md
+++ b/apps/dialtone-documentation/docs/index.md
@@ -41,14 +41,12 @@ pageClass: dialpad-design-home
       <h2 class="d-headline--xxl d-ff-expressive" style="font-size: 48px;font-family:var(--dt-font-family-expressive); text-wrap: balance; max-width: 1400px; font-weight: var(--dt-font-weight-regular);">Foundations</h2>
       <p class="d-ta-center d-docsite--paragraph d-m0 d-wmx764" style="text-wrap: balance; font-size: 24px; font-family:var(--dt-font-family-expressive);">The building blocks of Dialtone... Color, Type, Icons, and more.</p>
       <p class="d-ta-center d-docsite--paragraph d-m0 d-wmx764">
-        <router-link to="./foundations/">
-          <dt-button size="lg" @click="navigate">
-            View Foundations
-            <template #endIcon>
-              <dt-icon name="arrow-right" size="300" />
-            </template>
-          </dt-button>
-        </router-link>
+        <dt-button size="lg" to="./foundations/">
+          View Foundations
+          <template #endIcon>
+            <dt-icon name="arrow-right" size="300" />
+          </template>
+        </dt-button>
       </p>
     </dt-stack>
   </dt-stack>
@@ -71,14 +69,12 @@ pageClass: dialpad-design-home
       <h2 class="d-headline--xxl d-ff-expressive" style="font-size: 48px;font-family:var(--dt-font-family-expressive); text-wrap: balance; max-width: 1400px; font-weight: var(--dt-font-weight-regular);">Design System</h2>
       <p class="d-ta-center d-docsite--paragraph d-m0 d-wmx764" style="text-wrap: balance;  font-size: 24px; font-family:var(--dt-font-family-expressive)">Build with Dialtone Components, Design Tokens, CSS Utilities, and more.</p>
       <p class="d-ta-center d-docsite--paragraph d-m0 d-wmx764">
-        <router-link to="./dialtone/">
-          <dt-button size="lg">
-            View all Documentation
-            <template #endIcon>
-              <dt-icon name="arrow-right" size="300" />
-            </template>
-          </dt-button>
-        </router-link>
+        <dt-button size="lg" to="./dialtone/">
+          View all Documentation
+          <template #endIcon>
+            <dt-icon name="arrow-right" size="300" />
+          </template>
+        </dt-button>
       </p>
     </dt-stack>
   </dt-stack>
@@ -87,14 +83,12 @@ pageClass: dialpad-design-home
       <h2 class="d-headline--xxl d-ff-expressive" style="font-size: 48px;font-family:var(--dt-font-family-expressive); text-wrap: balance; max-width: 1400px; font-weight: var(--dt-font-weight-regular);">What's New</h2>
       <p class="d-ta-center d-docsite--paragraph d-m0 d-wmx764" style="text-wrap: balance; font-size: 24px; font-family:var(--dt-font-family-expressive)">The latest from Dialpad Design.</p>
       <p class="d-ta-center d-docsite--paragraph d-m0 d-wmx764">
-        <router-link to="./dialtone/whats-new/">
-          <dt-button size="lg">
-            View all
-            <template #endIcon>
-              <dt-icon name="arrow-right" size="300" />
-            </template>
-          </dt-button>
-        </router-link>
+        <dt-button size="lg" to="./dialtone/whats-new/">
+          View all
+          <template #endIcon>
+            <dt-icon name="arrow-right" size="300" />
+          </template>
+        </dt-button>
       </p>
     </dt-stack>
     <dt-stack

From 9e7e9073bf41d92cf63af65452d0a1ffe7a9769a Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 12:38:56 -0600
Subject: [PATCH 09/47] dt-split-button accepts to and href props from
 dt-button

---
 .../docs/components/split-button.md           | 65 ++++++++++++++++++
 .../split_button/split_button-alpha.vue       | 45 ++++++++++++
 .../split_button/split_button.stories.js      | 54 +++++++++++++++
 .../split_button/split_button.test.js         | 68 +++++++++++++++++++
 .../components/split_button/split_button.vue  | 51 ++++++++++++++
 .../split_button_default.story.vue            |  5 ++
 6 files changed, 288 insertions(+)

diff --git a/apps/dialtone-documentation/docs/components/split-button.md b/apps/dialtone-documentation/docs/components/split-button.md
index 22d256f1bf..b3ec521b0a 100644
--- a/apps/dialtone-documentation/docs/components/split-button.md
+++ b/apps/dialtone-documentation/docs/components/split-button.md
@@ -455,6 +455,71 @@ vueCode='
 '
 showHtmlWarning />
 
+## Navigation
+
+The start button supports navigation via `start-href` (renders as `<a>`) or `start-to` (renders as `<router-link>`). Navigation only applies to the start button — the end button is a dropdown trigger.
+
+### External Link
+
+<code-well-header>
+  <dt-split-button
+    start-href="https://dialpad.com"
+    start-target="_blank"
+    start-rel="noopener noreferrer"
+    end-tooltip-text="More options"
+  >
+    Visit Dialpad
+    <template #dropdownList>
+      <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 1 </dt-list-item>
+      <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 2 </dt-list-item>
+    </template>
+  </dt-split-button>
+</code-well-header>
+
+<code-example-tabs
+htmlCode='
+<span class="d-split-btn">
+  <a class="base-button__button d-btn d-btn--primary d-split-btn__alpha d-split-btn__alpha--md" href="https://dialpad.com" target="_blank" rel="noopener noreferrer">
+    <span class="d-btn__label base-button__label"> Visit Dialpad </span>
+  </a>
+  <button class="base-button__button d-btn d-btn--primary d-btn--icon-only d-split-btn__omega d-split-btn__omega--md" type="button">
+    <span class="base-button__icon d-btn__icon d-btn__icon--left">...</span>
+  </button>
+</span>
+'
+vueCode='
+<dt-split-button
+  start-href="https://dialpad.com"
+  start-target="_blank"
+  start-rel="noopener noreferrer"
+  end-tooltip-text="More options"
+>
+  Visit Dialpad
+  <template #dropdownList>
+    <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 1 </dt-list-item>
+    <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 2 </dt-list-item>
+  </template>
+</dt-split-button>
+'
+showHtmlWarning />
+
+### Router Link
+
+<code-example-tabs
+vueCode='
+<dt-split-button
+  start-to="/components/button"
+  end-tooltip-text="More options"
+>
+  Go to Button docs
+  <template #dropdownList>
+    <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 1 </dt-list-item>
+    <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 2 </dt-list-item>
+  </template>
+</dt-split-button>
+'
+/>
+
 ## Icon Support
 
 ### Icon and Label
diff --git a/packages/dialtone-vue/components/split_button/split_button-alpha.vue b/packages/dialtone-vue/components/split_button/split_button-alpha.vue
index a7f8033e6c..c4ab757e63 100644
--- a/packages/dialtone-vue/components/split_button/split_button-alpha.vue
+++ b/packages/dialtone-vue/components/split_button/split_button-alpha.vue
@@ -15,6 +15,11 @@
     :trailing-class="trailingClass"
     :loading="loading"
     :size="size"
+    :to="to"
+    :replace="replace"
+    :href="href"
+    :target="target"
+    :rel="rel"
   >
     <template
       v-if="$slots.startIcon"
@@ -175,6 +180,46 @@ export default {
       type: String,
       default: 'md',
     },
+
+    /**
+     * Vue router `to` prop. When set, renders as a `<router-link>`.
+     */
+    to: {
+      type: [String, Object],
+      default: null,
+    },
+
+    /**
+     * Whether to use `router.replace()` instead of `router.push()`.
+     */
+    replace: {
+      type: Boolean,
+      default: false,
+    },
+
+    /**
+     * HTML href. When set, renders as an `<a>` element.
+     */
+    href: {
+      type: String,
+      default: null,
+    },
+
+    /**
+     * HTML target attribute for the link.
+     */
+    target: {
+      type: String,
+      default: null,
+    },
+
+    /**
+     * HTML rel attribute for the link.
+     */
+    rel: {
+      type: String,
+      default: null,
+    },
   },
 
   data () {
diff --git a/packages/dialtone-vue/components/split_button/split_button.stories.js b/packages/dialtone-vue/components/split_button/split_button.stories.js
index 97c95b80c2..6f1032b32d 100644
--- a/packages/dialtone-vue/components/split_button/split_button.stories.js
+++ b/packages/dialtone-vue/components/split_button/split_button.stories.js
@@ -125,6 +125,26 @@ export const argTypesData = {
     control: 'boolean',
   },
 
+  startTo: {
+    control: 'text',
+  },
+
+  startHref: {
+    control: 'text',
+  },
+
+  startTarget: {
+    control: 'text',
+  },
+
+  startRel: {
+    control: 'text',
+  },
+
+  startReplace: {
+    control: 'boolean',
+  },
+
   dropdownPlacement: {
     options: POPOVER_DIRECTIONS,
     control: {
@@ -209,6 +229,40 @@ export const Default = {
   ],
 };
 
+export const WithLink = {
+  render: DefaultTemplate,
+
+  args: {
+    ...argsData,
+    startHref: 'https://dialpad.com',
+    startTarget: '_blank',
+    startRel: 'noopener noreferrer',
+    default: 'Visit Dialpad',
+  },
+
+  decorators: [
+    () => ({
+      template: `<dt-stack direction="row" justify="center" align="center" class="d-h164"><story /></dt-stack>`,
+    }),
+  ],
+};
+
+export const WithRouterLink = {
+  render: DefaultTemplate,
+
+  args: {
+    ...argsData,
+    startTo: '/components/button',
+    default: 'Go to Button',
+  },
+
+  decorators: [
+    () => ({
+      template: `<dt-stack direction="row" justify="center" align="center" class="d-h164"><story /></dt-stack>`,
+    }),
+  ],
+};
+
 export const Variants = {
   render: VariantsTemplate,
 
diff --git a/packages/dialtone-vue/components/split_button/split_button.test.js b/packages/dialtone-vue/components/split_button/split_button.test.js
index dd66ef1890..03fa2962e6 100644
--- a/packages/dialtone-vue/components/split_button/split_button.test.js
+++ b/packages/dialtone-vue/components/split_button/split_button.test.js
@@ -556,6 +556,74 @@ describe('DtSplitButton Tests', function () {
     });
   });
 
+  describe('Navigation Tests', () => {
+    describe('When startTo is provided', () => {
+      it('Should forward to prop to the alpha DtButton', () => {
+        mockProps = { startTo: '/some-route' };
+
+        updateWrapper();
+
+        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+
+        expect(alphaComponent.props('to')).toBe('/some-route');
+      });
+    });
+
+    describe('When startTo is an object', () => {
+      it('Should forward the route object to the alpha DtButton', () => {
+        const route = { name: 'home', params: { id: 1 } };
+        mockProps = { startTo: route };
+
+        updateWrapper();
+
+        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+
+        expect(alphaComponent.props('to')).toEqual(route);
+      });
+    });
+
+    describe('When startHref is provided', () => {
+      it('Should forward href prop to the alpha DtButton', () => {
+        mockProps = { startHref: 'https://example.com' };
+
+        updateWrapper();
+
+        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+
+        expect(alphaComponent.props('href')).toBe('https://example.com');
+      });
+    });
+
+    describe('When startTarget and startRel are provided', () => {
+      it('Should forward target and rel props to the alpha DtButton', () => {
+        mockProps = {
+          startHref: 'https://example.com',
+          startTarget: '_blank',
+          startRel: 'noopener noreferrer',
+        };
+
+        updateWrapper();
+
+        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+
+        expect(alphaComponent.props('target')).toBe('_blank');
+        expect(alphaComponent.props('rel')).toBe('noopener noreferrer');
+      });
+    });
+
+    describe('When startReplace is provided', () => {
+      it('Should forward replace prop to the alpha DtButton', () => {
+        mockProps = { startTo: '/some-route', startReplace: true };
+
+        updateWrapper();
+
+        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+
+        expect(alphaComponent.props('replace')).toBe(true);
+      });
+    });
+  });
+
   describe('Extendability Tests', () => {
     describe('When a rootClass is provided', () => {
       it('should include the root class', () => {
diff --git a/packages/dialtone-vue/components/split_button/split_button.vue b/packages/dialtone-vue/components/split_button/split_button.vue
index 94a262057e..4255aebfb8 100644
--- a/packages/dialtone-vue/components/split_button/split_button.vue
+++ b/packages/dialtone-vue/components/split_button/split_button.vue
@@ -498,6 +498,52 @@ export default {
       type: [String, Object, Array],
       default: '',
     },
+
+    /**
+     * Vue router `to` prop for the start button.
+     * When set, renders the start button as a `<router-link>`.
+     */
+    startTo: {
+      type: [String, Object],
+      default: null,
+    },
+
+    /**
+     * Whether to use `router.replace()` instead of `router.push()`
+     * when navigating via `startTo`.
+     * @values true, false
+     */
+    startReplace: {
+      type: Boolean,
+      default: false,
+    },
+
+    /**
+     * HTML href for the start button.
+     * When set, renders the start button as an `<a>` element.
+     */
+    startHref: {
+      type: String,
+      default: null,
+    },
+
+    /**
+     * HTML target attribute for the start button link.
+     * Only applies when `startHref` is set.
+     */
+    startTarget: {
+      type: String,
+      default: null,
+    },
+
+    /**
+     * HTML rel attribute for the start button link.
+     * Only applies when `startHref` is set.
+     */
+    startRel: {
+      type: String,
+      default: null,
+    },
   },
 
   emits: [
@@ -550,6 +596,11 @@ export default {
         kind: this.kind,
         size: this.size,
         tooltipText: this.alphaTooltipText ?? this.startTooltipText,
+        to: this.startTo,
+        replace: this.startReplace,
+        href: this.startHref,
+        target: this.startTarget,
+        rel: this.startRel,
         class: this.$attrs.class,
         style: this.$attrs.style,
       };
diff --git a/packages/dialtone-vue/components/split_button/split_button_default.story.vue b/packages/dialtone-vue/components/split_button/split_button_default.story.vue
index 43528ba8fc..4c477d0973 100644
--- a/packages/dialtone-vue/components/split_button/split_button_default.story.vue
+++ b/packages/dialtone-vue/components/split_button/split_button_default.story.vue
@@ -17,6 +17,11 @@
     :end-tooltip-text="$attrs.endTooltipText"
     :root-class="$attrs.rootClass"
     :size="$attrs.size"
+    :start-to="$attrs.startTo"
+    :start-replace="$attrs.startReplace"
+    :start-href="$attrs.startHref"
+    :start-target="$attrs.startTarget"
+    :start-rel="$attrs.startRel"
     :width="$attrs.width"
     @start-clicked="$attrs.onStartClicked"
     @end-clicked="$attrs.onEndClicked"

From 22ab64fbef7c835ed2851a72edcdc9bdd9da3f8a Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 13:34:51 -0600
Subject: [PATCH 10/47] inline code styles

---
 .../theme/assets/less/dialtone-docs.less       | 18 ++++++++----------
 .../theme/assets/less/dialtone-syntax.less     | 17 ++++-------------
 2 files changed, 12 insertions(+), 23 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less
index 992ce24f41..092d11e874 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less
@@ -457,16 +457,6 @@ a.header-anchor {
   }
 }
 
-:where(code) {
-  .d-docsite--paragraph &,
-  .d-docsite--unordered-list &,
-  .d-docsite--ordered-list &,
-  .d-docsite--list-element &,
-  .d-docsite--preview-header & {
-    font-size: 95%;
-  }
-}
-
 .d-docsite--unordered-list,
 .d-docsite--list-element,
 .d-docsite--ordered-list {
@@ -490,6 +480,14 @@ a.header-anchor {
   }
 }
 
+:where(:is(.d-docsite--paragraph, .d-docsite--unordered-list, .d-docsite--ordered-list, .d-docsite--list-element, .d-docsite--preview-header) > code) {
+	padding: var(--dt-size-200) var(--dt-size-300);
+	color: var(--dt-color-blue-800);
+	border-radius: var(--dt-size-200);
+	border: 1px solid var(--dt-color-border-subtle);
+	user-select: all;
+}
+
 .d-docsite--preview-header {
   margin-block: var(--dt-size-600) var(--dt-size-300);
 }
diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
index ba92c13819..bbbce8b258 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
@@ -33,18 +33,10 @@ div[class*="language-"] {
   }
 }
 
-:where(.d-docsite--paragraph > code) {
-	padding: var(--dt-size-200) var(--dt-size-300);
-	color: var(--dt-color-blue-800);
-	border-radius: var(--dt-size-200);
-	border: 1px solid var(--dt-color-border-subtle);
-	user-select: all;
-}
-
 code[class*="language-"],
 pre[class*="language-"] {
 	margin: 0;
-	color: var(--dt-color-black-1000);
+	color: var(--dt-color-foreground-secondary);
 	font: var(--dt-text-code-sm);
 	line-height: var(--dt-font-line-height-400);
 	white-space: pre;
@@ -87,7 +79,8 @@ pre[class*="language-"] {
 .token.prolog,
 .token.doctype,
 .token.cdata {
-	color: var(--dt-color-foreground-tertiary);
+	color: var(--dt-color-foreground-muted);
+	font-style: italic;
 }
 
 .token.punctuation {
@@ -221,8 +214,6 @@ pre[class*="language-"].line-numbers > :where(code) {
 	content: attr(data-prompt);
 }
 
-code,
-kbd,
-samp {
+:is(pre, code, kbd, samp) {
   font-family: var(--dt-font-family-mono);
 }

From f120e14b07929b36f89a7885fc42c92491f1acbb Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 13:35:13 -0600
Subject: [PATCH 11/47] doc site housekeeping

---
 .../docs/.vuepress/theme/components/TocItem.vue  |  2 +-
 .../docs/components/badge.md                     |  2 +-
 .../docs/components/button.md                    |  2 ++
 .../docs/utilities/backgrounds/gradients.md      |  2 +-
 .../docs/utilities/grid/place-content.md         |  4 ++--
 .../docs/utilities/grid/place-items.md           |  4 ++--
 .../docs/utilities/grid/place-self.md            |  6 +++---
 .../docs/utilities/layout/coordinates.md         | 16 ++++++++--------
 8 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue b/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
index 875a0fd81c..311422e678 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/components/TocItem.vue
@@ -4,7 +4,7 @@
     :active="active"
     importance="clear"
     kind="muted"
-    size="sm"
+    size="xs"
     label-class="d-jc-flex-start d-fw-normal d-tw-pretty"
     class="d-w100p"
   >
diff --git a/apps/dialtone-documentation/docs/components/badge.md b/apps/dialtone-documentation/docs/components/badge.md
index 6a18244934..912199083e 100644
--- a/apps/dialtone-documentation/docs/components/badge.md
+++ b/apps/dialtone-documentation/docs/components/badge.md
@@ -150,7 +150,7 @@ showHtmlWarning />
       <td>
         <dt-badge type="ai" text="Label" kind="label"></dt-badge>
       </td>
-      <td><abbr class="d-fc-black-400 d-td-none d-fs-100" title="Not applicable">N/A</abbr></td>
+      <td><abbr class="d-fc-muted d-td-none d-fs-100" title="Not applicable">N/A</abbr></td>
       <td>To call out Dialpad Ai features.</td>
     </tr>
   </tbody>
diff --git a/apps/dialtone-documentation/docs/components/button.md b/apps/dialtone-documentation/docs/components/button.md
index a5b818f7a9..a4cf2c9e77 100644
--- a/apps/dialtone-documentation/docs/components/button.md
+++ b/apps/dialtone-documentation/docs/components/button.md
@@ -70,6 +70,7 @@ Dialtone provides five options for `kind`, with three levels of `importance`.
 The base button should be the go-to button for most of your needs. When in doubt, use this style. To help provide clarity to users, it is generally recommended to use only one primary button style within a section or page.
 
 <code-well-header>
+  <!-- asdfasdf -->
   <dt-stack direction="row" gap="400" ref="defaultExample">
       <dt-button> Place Call </dt-button>
       <dt-button importance="outlined"> Place Call </dt-button>
@@ -80,6 +81,7 @@ The base button should be the go-to button for most of your needs. When in doubt
 <code-example-tabs
 :htmlCode='() => $refs.defaultExample'
 vueCode='
+<!-- asdfasdf -->
 <dt-button> Place Call </dt-button>
 <dt-button importance="outlined"> Place Call </dt-button>
 <dt-button importance="clear"> Place Call </dt-button>
diff --git a/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md b/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md
index e991716e35..4b7cc8ff34 100644
--- a/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md
+++ b/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md
@@ -117,7 +117,7 @@ The starting stop (`d-bgg-from-{color}`) should be declared. Optionally an endin
 
 <utility-class-table>
 <template #content>
-       <div v-for="direction in ['from', 'to']" style="display: contents">
+       <template v-for="direction in ['from', 'to']">
          <tbody v-for="{ color, stops } in baseColors">
              <tr v-for="{ stop } in stops">
                  <th scope="row" class="d-code--sm d-docsite-code">.d-bgg-{{ direction }}-{{ color }}-{{ stop }}</th>
diff --git a/apps/dialtone-documentation/docs/utilities/grid/place-content.md b/apps/dialtone-documentation/docs/utilities/grid/place-content.md
index 8e461955ff..512cf96f64 100644
--- a/apps/dialtone-documentation/docs/utilities/grid/place-content.md
+++ b/apps/dialtone-documentation/docs/utilities/grid/place-content.md
@@ -167,7 +167,7 @@ Use `d-plc-space-between{-n}` to distribute grid items along the block axis so t
 <utility-class-table>
   <template #content>
     <tbody>
-      <div v-for="c in alignments" style="display: contents">
+      <template v-for="c in alignments">
         <tr v-for="i in alignments">
           <th scope="row" class="d-code--sm d-docsite-code">
             <span v-if="i !== c">.d-plc-{{ c }}-{{ i }}</span>
@@ -178,7 +178,7 @@ Use `d-plc-space-between{-n}` to distribute grid items along the block axis so t
             <span v-else>place-content: {{ c }} !important</span>
           </td>
         </tr>
-      </div>
+      </template>
     </tbody>
   </template>
 </utility-class-table>
diff --git a/apps/dialtone-documentation/docs/utilities/grid/place-items.md b/apps/dialtone-documentation/docs/utilities/grid/place-items.md
index bb54cf357b..7a96f488ed 100644
--- a/apps/dialtone-documentation/docs/utilities/grid/place-items.md
+++ b/apps/dialtone-documentation/docs/utilities/grid/place-items.md
@@ -101,7 +101,7 @@ Use `d-pli-center{-n}` to align grid items along the center of their block and/o
 <utility-class-table>
   <template #content>
     <tbody>
-      <div v-for="c in alignments" style="display: contents">
+      <template v-for="c in alignments">
         <tr v-for="i in alignments">
           <th scope="row" class="d-code--sm d-docsite-code">
             <span v-if="i !== c">.d-pli-{{ c }}-{{ i }}</span>
@@ -112,7 +112,7 @@ Use `d-pli-center{-n}` to align grid items along the center of their block and/o
             <span v-else>place-items: {{ c }} !important;</span>
           </td>
         </tr>
-      </div>
+      </template>
     </tbody>
   </template>
 </utility-class-table>
diff --git a/apps/dialtone-documentation/docs/utilities/grid/place-self.md b/apps/dialtone-documentation/docs/utilities/grid/place-self.md
index 80c01a5a67..4391311adb 100644
--- a/apps/dialtone-documentation/docs/utilities/grid/place-self.md
+++ b/apps/dialtone-documentation/docs/utilities/grid/place-self.md
@@ -101,18 +101,18 @@ Use `d-pls-center{-n}` to align a grid item along the center of their block and/
 <utility-class-table>
   <template #content>
     <tbody>
-      <div v-for="c in alignments" style="display: contents">
+      <template v-for="c in alignments">
         <tr v-for="i in alignments">
           <th scope="row" class="d-code--sm d-docsite-code">
             <span v-if="i !== c">.d-pls-{{ c }}-{{ i }}</span>
             <span v-else>.d-pls-{{ c }}</span>
           </th>
-          <td class="d-code--sm">
+          <td class="d-code--sm" outline>
             <span v-if="i !== c">place-self: {{ c }} {{ i }} !important;</span>
             <span v-else>place-self: {{ c }} !important;</span>
           </td>
         </tr>
-      </div>
+      </template>
     </tbody>
   </template>
 </utility-class-table>
diff --git a/apps/dialtone-documentation/docs/utilities/layout/coordinates.md b/apps/dialtone-documentation/docs/utilities/layout/coordinates.md
index 31109fcc68..34ff33f444 100644
--- a/apps/dialtone-documentation/docs/utilities/layout/coordinates.md
+++ b/apps/dialtone-documentation/docs/utilities/layout/coordinates.md
@@ -91,15 +91,15 @@ Use the `top|right|bottom|left|x|y|all` utility classes to absolutely position e
       <tbody>
         <tr v-for="{coordinate, suffix, combo, value } in coordinates">
           <th scope="row">{{ value }}</th>
-          <div v-for="{direction: dir, prefix: pre, percent} in coordinateDirections" style="display: contents">
-            <td v-if="percent === 'no' && combo === 'no'" class="d-o50 d-bgc-black-200 d-fc-black-400 d-fs-100 d-ta-center">
-              <em>N/A</em>
+          <template v-for="{direction: dir, prefix: pre, percent} in coordinateDirections">
+            <td v-if="percent === 'no' && combo === 'no'" class="d-fc-muted d-fs-100 d-ta-center">
+              N/A
             </td>
             <td v-else class="d-code--sm d-docsite-code">
               <span v-if="suffix === '-calc'">.d-{{ pre }}{{ coordinate }}{{ suffix }}</span>
               <span v-else>.d-{{ pre }}{{ coordinate }}</span>
             </td>
-          </div>
+          </template>
         </tr>
       </tbody>
     </table>
@@ -191,15 +191,15 @@ Use the `top|right|bottom|left|x|y|all` utility classes to absolutely position e
       <tbody>
         <tr v-for="{coordinate, suffix, combo, negative, value } in coordinates">
           <th v-if="negative === 'yes'" scope="row">{{ value }}</th>
-          <div v-if="negative === 'yes'" v-for="{direction: dir, prefix: pre, percent} in coordinateDirections" style="display: contents">
-            <td v-if="percent === 'no' && combo === 'no'" class="d-o50 d-bgc-black-200 d-fc-black-400 d-fs-100 d-ta-center">
-              <em>N/A</em>
+          <template v-if="negative === 'yes'" v-for="{direction: dir, prefix: pre, percent} in coordinateDirections">
+            <td v-if="percent === 'no' && combo === 'no'" class="d-fc-muted d-fs-100 d-ta-center">
+              N/A
             </td>
             <td v-else class="d-code--sm d-docsite-code">
               <span v-if="suffix === '-calc'">.d-{{ pre }}n{{ coordinate }}{{ suffix }}</span>
               <span v-else>.d-{{ pre }}n{{ coordinate }}</span>
             </td>
-          </div>
+          </template>
         </tr>
       </tbody>
     </table>

From f610be9db3566d05b875ba4767602fb410717d1d Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 13:56:33 -0600
Subject: [PATCH 12/47] remove unused constants

---
 .../empty_state/empty_state_constants.js           | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/packages/dialtone-vue/components/empty_state/empty_state_constants.js b/packages/dialtone-vue/components/empty_state/empty_state_constants.js
index b8e0f1ce9f..b0e9199a18 100644
--- a/packages/dialtone-vue/components/empty_state/empty_state_constants.js
+++ b/packages/dialtone-vue/components/empty_state/empty_state_constants.js
@@ -10,12 +10,6 @@ export const EMPTY_STATE_CONTENT_SIZE_MODIFIERS = {
   lg: 'd-empty-state__content--lg',
 };
 
-export const EMPTY_STATE_HEADLINE_SIZE_MODIFIERS = {
-  sm: 'd-text-headline--md d-lh-200',
-  md: 'd-text-headline--xl d-lh-200',
-  lg: 'd-text-headline--2xl',
-};
-
 export const EMPTY_STATE_HEADLINE_SIZES = {
   sm: 'md',
   md: 'xl',
@@ -28,12 +22,6 @@ export const EMPTY_STATE_HEADLINE_DENSITIES = {
   lg: undefined,
 };
 
-export const EMPTY_STATE_BODY_SIZE_MODIFIERS = {
-  sm: 'd-text-body--sm',
-  md: 'd-text-body--md d-lh-300',
-  lg: 'd-text-body--lg d-lh-300',
-};
-
 export const EMPTY_STATE_BODY_SIZES = {
   sm: 'sm',
   md: 'md',
@@ -49,10 +37,8 @@ export const EMPTY_STATE_BODY_DENSITIES = {
 export default {
   EMPTY_STATE_SIZE_MODIFIERS,
   EMPTY_STATE_CONTENT_SIZE_MODIFIERS,
-  EMPTY_STATE_HEADLINE_SIZE_MODIFIERS,
   EMPTY_STATE_HEADLINE_SIZES,
   EMPTY_STATE_HEADLINE_DENSITIES,
-  EMPTY_STATE_BODY_SIZE_MODIFIERS,
   EMPTY_STATE_BODY_SIZES,
   EMPTY_STATE_BODY_DENSITIES,
 };

From 87f53e1257dba8c752820726972a43e403ed3035 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 14:04:24 -0600
Subject: [PATCH 13/47] doc rule for code examples using refs in
 code-well-header

---
 .claude/rules/documentation-writing.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/.claude/rules/documentation-writing.md b/.claude/rules/documentation-writing.md
index 93c59d1192..da286734bc 100644
--- a/.claude/rules/documentation-writing.md
+++ b/.claude/rules/documentation-writing.md
@@ -8,19 +8,44 @@ paths:
 # Documentation Writing Rules
 
 ## Use Exact Names — Never Generic Terms
+
 - Package names: `@dialpad/dialtone-vue`, `dialtone-css`, `dialtone-tokens` — never "our library" or "the package"
 - Component names: `DtButton`, `DtModal`, `DtInput` — never "the button component"
 - Tool names: VuePress, pnpm, Nx, vue-docgen-api, Vitest — never "our build tool" or "the test framework"
 - File paths: `packages/dialtone-vue/components/` — never "the components folder"
 
 ## Code Examples Must Be Complete
+
 - Include imports, setup, and realistic variable names
 - Show runnable code, not pseudo-code
 - Add language identifier to all fenced code blocks
 
 ## No Placeholder Content
+
 - Never write TODO, TBD, "Coming soon", or empty sections
 - If content isn't ready, omit the section entirely
 
+## HTML Code Examples Must Use Refs
+
+In `<code-example-tabs>`, always use the ref-based pattern for `htmlCode`:
+
+```html
+<code-well-header>
+  <dt-notice ref="baseExample" kind="base" title="Base title" />
+</code-well-header>
+
+<code-example-tabs
+  :htmlCode='() => $refs.baseExample'
+  vueCode='<dt-notice kind="base" title="Base title" />'
+  showHtmlWarning />
+```
+
+- Add `ref="descriptiveName"` to the outermost rendered element inside `<code-well-header>`
+- Bind `:htmlCode='() => $refs.refName'` — never use static inline HTML strings (`htmlCode='<div>...'`)
+- Always include `showHtmlWarning` when using the ref pattern
+- If a `<dt-stack>` or other wrapper surrounds multiple items, put the `ref` on the wrapper
+- If there is no `<code-well-header>` (code-only snippet), omit `htmlCode` entirely
+
 ## Component Doc Pages (VuePress)
+
 Required sections in order: overview, usage example, variants, props table, events table, slots table, accessibility notes. See `rules/documentation-site.md` for frontmatter and sidebar conventions.

From 377a50d4b4530e8eca505ddbbbd09725e34233bc Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 15:07:58 -0600
Subject: [PATCH 14/47] add missing storybook docs

---
 .../future/split-button-anchor-support.md     | 115 ------------------
 .../scrollbar_directive/scrollbar.mdx         |  58 +++++++++
 .../scrollbar_directive/scrollbar.stories.js  |  28 +++++
 .../scrollbar_directive_default.story.vue     |  72 +++++++++++
 4 files changed, 158 insertions(+), 115 deletions(-)
 delete mode 100644 docs/plans/future/split-button-anchor-support.md
 create mode 100644 packages/dialtone-vue/directives/scrollbar_directive/scrollbar.mdx
 create mode 100644 packages/dialtone-vue/directives/scrollbar_directive/scrollbar.stories.js
 create mode 100644 packages/dialtone-vue/directives/scrollbar_directive/scrollbar_directive_default.story.vue

diff --git a/docs/plans/future/split-button-anchor-support.md b/docs/plans/future/split-button-anchor-support.md
deleted file mode 100644
index d039c1e576..0000000000
--- a/docs/plans/future/split-button-anchor-support.md
+++ /dev/null
@@ -1,115 +0,0 @@
-# DtSplitButton Anchor and Router Link Forwarding
-
-## Overview
-
-**Status:** Future
-**Created:** 2026-02-15
-**Depends on:** [DtButton Anchor Support](../active/dt-button-anchor-support.md)
-
-Forward DtButton's `href` and `to` navigation props through the SplitButton alpha button so the primary action can navigate.
-
-## Problem
-
-With DtButton now supporting `href` and `to` props, SplitButton's alpha button cannot take advantage of this because `split_button.vue` and `split_button-alpha.vue` don't forward the navigation props. Consumers who need a navigating split button (e.g., "Join Room" as the main CTA with a dropdown for options) have no clean path.
-
-## Why alpha only
-
-The alpha (left) button is the primary action — navigation is a natural use case (e.g., "Join Room" as the main CTA, with a dropdown for "Join with video", "Join audio only"). The omega (right) button is a dropdown trigger; it opens a menu, not navigates. If a custom navigating omega is ever needed, the `#omega` slot already provides full override capability.
-
-## Naming convention
-
-Follows SplitButton's existing pattern: `alphaDisabled`, `alphaActive`, `alphaAriaLabel`, `alphaLoading`, `alphaTooltipText`, etc. The navigation props become `alphaTo`, `alphaHref`, `alphaTarget`, `alphaRel`, `alphaReplace`.
-
-## Props
-
-New props on `DtSplitButton`:
-
-| Prop            | Type           | Default | Description                                                  |
-| --------------- | -------------- | ------- | ------------------------------------------------------------ |
-| `alphaHref`     | String         | null    | Renders alpha button as `<a>` for external navigation        |
-| `alphaTo`       | String, Object | null    | Renders alpha button as `<router-link>` for SPA navigation   |
-| `alphaTarget`   | String         | null    | HTML anchor target. Only applied when using `alphaHref`      |
-| `alphaRel`      | String         | null    | HTML anchor rel. Only applied when using `alphaHref`         |
-| `alphaReplace`  | Boolean        | false   | vue-router replace. Only applied when using `alphaTo`        |
-
-New props on `SplitButtonAlpha` (internal):
-
-| Prop      | Type           | Default | Forwards to          |
-| --------- | -------------- | ------- | -------------------- |
-| `to`      | String, Object | null    | `<dt-button :to>`    |
-| `href`    | String         | null    | `<dt-button :href>`  |
-| `target`  | String         | null    | `<dt-button :target>`|
-| `rel`     | String         | null    | `<dt-button :rel>`   |
-| `replace` | Boolean        | false   | `<dt-button :replace>`|
-
-No changes to `SplitButtonOmega`.
-
-## Example usage
-
-```vue
-<!-- Alpha navigates externally, omega opens dropdown -->
-<dt-split-button
-  alpha-href="https://example.com"
-  alpha-target="_blank"
-  alpha-rel="noopener noreferrer"
-  omega-tooltip-text="More options"
->
-  Visit Site
-  <template #dropdownList>
-    <dt-list-item role="menuitem">Copy link</dt-list-item>
-    <dt-list-item role="menuitem">Open in new tab</dt-list-item>
-  </template>
-</dt-split-button>
-
-<!-- Alpha navigates via router, omega opens dropdown -->
-<dt-split-button
-  :alpha-to="roomPath"
-  omega-tooltip-text="More calling options"
->
-  Join Room
-  <template #dropdownList>
-    <dt-list-item role="menuitem">Join with video</dt-list-item>
-    <dt-list-item role="menuitem">Join audio only</dt-list-item>
-  </template>
-</dt-split-button>
-```
-
-## Prerequisites
-
-The [DtButton Anchor Support](../active/dt-button-anchor-support.md) plan must be **merged and stable** before this work begins. The first milestone below evaluates the final merged API to confirm the design here still holds — prop names, types, defaults, and behavior may have evolved during review.
-
-## Implementation
-
-### Milestones
-
-#### Milestone 0: Evaluate merged DtButton API
-
-- [ ] Confirm DtButton anchor support PR is merged to `staging`
-- [ ] Review the final `button.vue` props (`to`, `href`, `target`, `rel`, `replace`) — verify names, types, and defaults match what this plan assumes
-- [ ] Review any API changes that emerged during DtButton PR review
-- [ ] Update this plan's prop tables and examples if anything diverged
-
-#### Milestone 1: Prop forwarding
-
-- [ ] Add `alphaTo`, `alphaHref`, `alphaTarget`, `alphaRel`, `alphaReplace` props to `split_button.vue`
-- [ ] Forward via `alphaButtonProps` computed
-- [ ] Add `to`, `href`, `target`, `rel`, `replace` props to `split_button-alpha.vue` and pass through to `<dt-button>`
-
-#### Milestone 2: Tests and stories
-
-- [ ] Unit tests for prop forwarding
-- [ ] Storybook: navigation variant in `split_button_variants.story.vue`
-- [ ] Storybook controls for new props
-
-### Files to modify
-
-- `packages/dialtone-vue/components/split_button/split_button.vue` — add `alpha*` props; forward in `alphaButtonProps`
-- `packages/dialtone-vue/components/split_button/split_button-alpha.vue` — add navigation props; pass through to `<dt-button>`
-- `packages/dialtone-vue/components/split_button/split_button.test.js` — tests for prop forwarding
-- `packages/dialtone-vue/components/split_button/split_button.stories.js` — Storybook controls
-- `packages/dialtone-vue/components/split_button/split_button_variants.story.vue` — navigation variant
-
-### Files not modified
-
-- `packages/dialtone-vue/components/split_button/split_button-omega.vue` — omega is a dropdown trigger, not a navigation element
-- `packages/dialtone-vue/components/split_button/split_button_constants.js` — no new validators needed
diff --git a/packages/dialtone-vue/directives/scrollbar_directive/scrollbar.mdx b/packages/dialtone-vue/directives/scrollbar_directive/scrollbar.mdx
new file mode 100644
index 0000000000..a6607a366c
--- /dev/null
+++ b/packages/dialtone-vue/directives/scrollbar_directive/scrollbar.mdx
@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import * as ScrollbarDirectiveStories from './scrollbar.stories.js';
+
+<Meta of={ScrollbarDirectiveStories}/>
+
+# Scrollbar directive
+
+A custom scrollbar directive that wraps [OverlayScrollbars](https://kingsora.github.io/OverlayScrollbars/)
+to provide styled, cross-browser-consistent scrollbars.
+
+## Usage
+
+Import the directive from dialtone-vue
+
+```js
+import { DtScrollbarDirective } from "@dialpad/dialtone-vue";
+```
+
+Install the directive into vue instance
+
+```js
+Vue.use(DtScrollbarDirective);
+```
+
+### Default
+
+Default scrollbar uses `leave` auto-hide behavior — the scrollbar hides when the pointer leaves the element.
+
+```html
+<div v-dt-scrollbar>
+  <div>Scrollable content</div>
+</div>
+```
+
+### Auto-hide modes
+
+Control when the scrollbar hides using directive arguments:
+
+**Never auto-hide** — scrollbar is always visible
+
+```html
+<div v-dt-scrollbar:never>
+  <div>Scrollable content</div>
+</div>
+```
+
+**Hide on scroll** — scrollbar hides after scrolling stops (1300ms delay)
+
+```html
+<div v-dt-scrollbar:scroll>
+  <div>Scrollable content</div>
+</div>
+```
+
+### Important
+
+The directive expects the scrollable content to be wrapped in a single child element,
+which becomes the OverlayScrollbars viewport.
diff --git a/packages/dialtone-vue/directives/scrollbar_directive/scrollbar.stories.js b/packages/dialtone-vue/directives/scrollbar_directive/scrollbar.stories.js
new file mode 100644
index 0000000000..bc4e180ad0
--- /dev/null
+++ b/packages/dialtone-vue/directives/scrollbar_directive/scrollbar.stories.js
@@ -0,0 +1,28 @@
+import { createTemplateFromVueFile } from '@/common/storybook_utils.js';
+import ScrollbarDirectiveDefaultTemplate from './scrollbar_directive_default.story.vue';
+
+export const argsData = {};
+
+export const argTypesData = {};
+
+// Story Collection
+export default {
+  title: 'Directives/Scrollbar',
+  component: ScrollbarDirectiveDefaultTemplate,
+  args: argsData,
+  argTypes: argTypesData,
+  excludeStories: /.*Data$/,
+};
+
+// Templates
+const DefaultTemplate = (args, { argTypes }) =>
+  createTemplateFromVueFile(args, argTypes, ScrollbarDirectiveDefaultTemplate);
+
+// Stories
+export const Default = {
+  render: DefaultTemplate,
+  parameters: {
+    options: { showPanel: false },
+    controls: { disable: true },
+  },
+};
diff --git a/packages/dialtone-vue/directives/scrollbar_directive/scrollbar_directive_default.story.vue b/packages/dialtone-vue/directives/scrollbar_directive/scrollbar_directive_default.story.vue
new file mode 100644
index 0000000000..3866e8d703
--- /dev/null
+++ b/packages/dialtone-vue/directives/scrollbar_directive/scrollbar_directive_default.story.vue
@@ -0,0 +1,72 @@
+<template>
+  <dt-stack
+    gap="600"
+    class="d-m64"
+  >
+    <div>
+      <p class="d-label--md-compact d-mb8">
+        Default (auto-hide on leave)
+      </p>
+      <div
+        v-dt-scrollbar
+        class="d-h164 d-w264 d-bar8 d-bc-default d-ba"
+      >
+        <div class="d-p16">
+          <p
+            v-for="i in 20"
+            :key="i"
+            class="d-body--md"
+          >
+            Scrollable content line {{ i }}
+          </p>
+        </div>
+      </div>
+    </div>
+    <div>
+      <p class="d-label--md-compact d-mb8">
+        Never auto-hide
+      </p>
+      <div
+        v-dt-scrollbar:never
+        class="d-h164 d-w264 d-bar8 d-bc-default d-ba"
+      >
+        <div class="d-p16">
+          <p
+            v-for="i in 20"
+            :key="i"
+            class="d-body--md"
+          >
+            Scrollable content line {{ i }}
+          </p>
+        </div>
+      </div>
+    </div>
+    <div>
+      <p class="d-label--md-compact d-mb8">
+        Auto-hide on scroll
+      </p>
+      <div
+        v-dt-scrollbar:scroll
+        class="d-h164 d-w264 d-bar8 d-bc-default d-ba"
+      >
+        <div class="d-p16">
+          <p
+            v-for="i in 20"
+            :key="i"
+            class="d-body--md"
+          >
+            Scrollable content line {{ i }}
+          </p>
+        </div>
+      </div>
+    </div>
+  </dt-stack>
+</template>
+
+<script>
+import DtStack from '@/components/stack/stack.vue';
+export default {
+  name: 'DtScrollbarDirectiveDefault',
+  components: { DtStack },
+};
+</script>

From b06c80147182e0ecdb8650b3cb82c9a92cd41df0 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 16:02:59 -0600
Subject: [PATCH 15/47] fix closing tag

---
 .../docs/utilities/backgrounds/gradients.md                     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md b/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md
index 4b7cc8ff34..7e74795c0e 100644
--- a/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md
+++ b/apps/dialtone-documentation/docs/utilities/backgrounds/gradients.md
@@ -143,7 +143,7 @@ The starting stop (`d-bgg-from-{color}`) should be declared. Optionally an endin
                  </td>
              </tr>
          </tbody>
-       </div>
+       </template>
    </template>
  </utility-class-table>
 

From 6e9ac56d5fef80bc9a3969fce7173dd452e5c467 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 16:31:05 -0600
Subject: [PATCH 16/47] rename split button subcomponents from alpha/omega to
 start/end

---
 .../lib/build/less/components/button.less     | 113 +++++++------
 ..._button-omega.vue => split_button-end.vue} |   6 +-
 ...utton-alpha.vue => split_button-start.vue} |   6 +-
 .../split_button/split_button.test.js         | 160 +++++++++---------
 .../components/split_button/split_button.vue  |  40 ++---
 5 files changed, 171 insertions(+), 154 deletions(-)
 rename packages/dialtone-vue/components/split_button/{split_button-omega.vue => split_button-end.vue} (94%)
 rename packages/dialtone-vue/components/split_button/{split_button-alpha.vue => split_button-start.vue} (97%)

diff --git a/packages/dialtone-css/lib/build/less/components/button.less b/packages/dialtone-css/lib/build/less/components/button.less
index 908b68f705..9738e703b3 100644
--- a/packages/dialtone-css/lib/build/less/components/button.less
+++ b/packages/dialtone-css/lib/build/less/components/button.less
@@ -719,12 +719,15 @@
 
   .d-popover,
   .d-popover div,
-  .d-popover &__omega {
+  .d-popover &__omega,
+  .d-popover &__end {
     block-size: 100%;
   }
 
   &__alpha,
-  &__omega {
+  &__omega,
+  &__start,
+  &__end {
     position: relative;
 
     &:focus-visible {
@@ -732,12 +735,27 @@
     }
   }
 
-  &__alpha {
+  &__alpha,
+  &__start {
     flex-grow: 1;
     padding-inline-end: calc(var(--button-padding-x) + var(--dt-size-200));
+
+    &:not(.d-btn--outlined) {
+      border-inline-end: 0;
+    }
+
+    &:disabled:not(.d-btn--outlined),
+    &:disabled:not(.d-btn--primary),
+    &.d-btn--primary,
+    &.d-btn--outlined {
+      border-inline-end: 0;
+      border-start-end-radius: 0;
+      border-end-end-radius: 0;
+    }
   }
 
-  &__omega {
+  &__omega,
+  &__end {
     // vertical divider between the two buttons
     &::before {
       position: absolute;
@@ -751,20 +769,27 @@
       opacity: var(--dt-opacity-600); // soften it
       content: "";
 
-       // soften divider for muted outlined
-      .d-split-btn:has(.d-btn--outlined.d-btn--muted, .d-btn--outlined.d-btn--inverted) & {
+      // soften divider for muted outlined
+      .d-split-btn:has(.d-btn--outlined.d-btn--muted,
+      .d-btn--outlined.d-btn--inverted) & {
         opacity: var(--dt-opacity-300);
       }
 
       // hide divider line when hovering or focusing any button within the split button
-      .d-split-btn:has(:focus-visible, :hover, .d-btn--active) & {
+      .d-split-btn:has(:focus-visible,
+      :hover,
+      .d-btn--active) & {
         opacity: 0;
       }
 
       // DO NOT hide divider line for primary, outlined, or disabled buttons
       .d-split-btn:has(:disabled) &,
-      .d-split-btn:has(.d-btn--outlined:focus-visible, .d-btn--outlined:hover, .d-btn--outlined.d-btn--active) &,
-      .d-split-btn:has(.d-btn--primary:focus-visible, .d-btn--primary:hover, .d-btn--primary.d-btn--active) & {
+      .d-split-btn:has(.d-btn--outlined:focus-visible,
+      .d-btn--outlined:hover,
+      .d-btn--outlined.d-btn--active) &,
+      .d-split-btn:has(.d-btn--primary:focus-visible,
+      .d-btn--primary:hover,
+      .d-btn--primary.d-btn--active) & {
         opacity: var(--dt-opacity-600);
       }
     }
@@ -779,59 +804,51 @@
     &.d-btn--outlined::before {
       inset-block: var(--dt-size-50-negative);
     }
-  }
-
-  &__alpha:disabled:not(.d-btn--outlined),
-  &__alpha:disabled:not(.d-btn--primary),
-  &__alpha.d-btn--primary,
-  &__alpha.d-btn--outlined {
-    border-inline-end: 0;
-    border-start-end-radius: 0;
-    border-end-end-radius: 0;
-  }
 
-  &__alpha:not(.d-btn--outlined) {
-    border-inline-end: 0;
-  }
-
-  &__omega:not(.d-btn--outlined) {
-    border-inline-start: 0;
-  }
+    &:not(.d-btn--outlined) {
+      border-inline-start: 0;
+    }
 
-  &__omega:not(.d-btn--outlined, .d-btn--primary) > * {
-    // yes, I'm pushing a half-pixel over just for this variant
-    // to ensure icon is centered
-    transform: translateX(var(--dt-size-50));
-  }
+    &:not(.d-btn--outlined, .d-btn--primary) > * {
+      // yes, I'm pushing a half-pixel over just for this variant
+      // to ensure icon is centered
+      transform: translateX(var(--dt-size-50));
+    }
 
-  &__omega:disabled:not(.d-btn--outlined),
-  &__omega:disabled:not(.d-btn--primary),
-  &__omega.d-btn--primary,
-  &__omega.d-btn--outlined {
-    border-inline-start: 0;
-    border-start-start-radius: 0;
-    border-end-start-radius: 0;
+    &:disabled:not(.d-btn--outlined),
+    &:disabled:not(.d-btn--primary),
+    &.d-btn--primary,
+    &.d-btn--outlined {
+      border-inline-start: 0;
+      border-start-start-radius: 0;
+      border-end-start-radius: 0;
+    }
   }
 
   // adjust x-padding for icon-only button at each size
-  &__omega--xs.d-btn--icon-only {
-    --button-padding-x: var(--dt-size-300);
+  &__omega--xs,
+  &__end--xs {
+    &.d-btn--icon-only { --button-padding-x: var(--dt-size-300); }
   }
 
-  &__omega--sm.d-btn--icon-only {
-    --button-padding-x: var(--dt-size-300);
+  &__omega--sm,
+  &__end--sm {
+    &.d-btn--icon-only { --button-padding-x: var(--dt-size-300); }
   }
 
-  &__omega--md.d-btn--icon-only {
-    --button-padding-x: var(--dt-size-350);
+  &__omega--md,
+  &__end--md {
+    &.d-btn--icon-only { --button-padding-x: var(--dt-size-350); }
   }
 
-  &__omega--lg.d-btn--icon-only {
-    --button-padding-x: var(--dt-size-400);
+  &__omega--lg,
+  &__end--lg {
+    &.d-btn--icon-only { --button-padding-x: var(--dt-size-400); }
   }
 
-  &__omega--xl.d-btn--icon-only {
-    --button-padding-x: var(--dt-size-450);
+  &__omega--xl,
+  &__end--xl {
+    &.d-btn--icon-only { --button-padding-x: var(--dt-size-450); }
   }
 }
 
diff --git a/packages/dialtone-vue/components/split_button/split_button-omega.vue b/packages/dialtone-vue/components/split_button/split_button-end.vue
similarity index 94%
rename from packages/dialtone-vue/components/split_button/split_button-omega.vue
rename to packages/dialtone-vue/components/split_button/split_button-end.vue
index fa9bea8079..ec59357cdd 100644
--- a/packages/dialtone-vue/components/split_button/split_button-omega.vue
+++ b/packages/dialtone-vue/components/split_button/split_button-end.vue
@@ -2,10 +2,10 @@
   <dt-button
     :id="id"
     v-dt-tooltip="{ message: tooltipText, inverted: kind === 'inverted' }"
-    data-qa="dt-split-button-omega"
+    data-qa="dt-split-button-end"
     :active="active"
     :aria-label="ariaLabel"
-    :class="`d-split-btn__omega d-split-btn__omega--${size}`"
+    :class="`d-split-btn__end d-split-btn__end--${size}`"
     :disabled="disabled"
     :importance="importance"
     :kind="kind"
@@ -30,7 +30,7 @@ import { getUniqueString } from '@/common/utils';
 
 export default {
   compatConfig: { MODE: 3 },
-  name: 'SplitButtonOmega',
+  name: 'SplitButtonEnd',
   components: {
     DtButton,
     DtIconChevronDown,
diff --git a/packages/dialtone-vue/components/split_button/split_button-alpha.vue b/packages/dialtone-vue/components/split_button/split_button-start.vue
similarity index 97%
rename from packages/dialtone-vue/components/split_button/split_button-alpha.vue
rename to packages/dialtone-vue/components/split_button/split_button-start.vue
index c4ab757e63..eecc0528a1 100644
--- a/packages/dialtone-vue/components/split_button/split_button-alpha.vue
+++ b/packages/dialtone-vue/components/split_button/split_button-start.vue
@@ -1,11 +1,11 @@
 <template>
   <dt-button
     v-dt-tooltip="tooltipConfig"
-    data-qa="dt-split-button-alpha"
+    data-qa="dt-split-button-start"
     :active="active"
     :aria-label="ariaLabel"
     :assertive-on-focus="assertiveOnFocus"
-    :class="`d-split-btn__alpha d-split-btn__alpha--${size}`"
+    :class="`d-split-btn__start d-split-btn__start--${size}`"
     :disabled="disabled"
     :icon-position="iconPosition"
     :importance="importance"
@@ -69,7 +69,7 @@ import { BUTTON_ICON_SIZES, DtButton } from '@/components/button';
 
 export default {
   compatConfig: { MODE: 3 },
-  name: 'SplitButtonAlpha',
+  name: 'SplitButtonStart',
 
   components: {
     DtButton,
diff --git a/packages/dialtone-vue/components/split_button/split_button.test.js b/packages/dialtone-vue/components/split_button/split_button.test.js
index 03fa2962e6..f1f23a03e8 100644
--- a/packages/dialtone-vue/components/split_button/split_button.test.js
+++ b/packages/dialtone-vue/components/split_button/split_button.test.js
@@ -1,7 +1,7 @@
 import { flushPromises, mount } from '@vue/test-utils';
 import DtSplitButton from './split_button.vue';
-import SplitButtonAlpha from './split_button-alpha.vue';
-import SplitButtonOmega from './split_button-omega.vue';
+import SplitButtonStart from './split_button-start.vue';
+import SplitButtonEnd from './split_button-end.vue';
 import { DtIconSend } from '@dialpad/dialtone-icons/vue3';
 import { DtTooltipDirective } from '@/directives/tooltip_directive';
 
@@ -25,10 +25,10 @@ let mockAttrs = {};
 
 describe('DtSplitButton Tests', function () {
   let wrapper;
-  let alphaButton;
-  let omegaButton;
-  let alphaIconSlot;
-  let omegaIconSlot;
+  let startButton;
+  let endButton;
+  let startIconSlot;
+  let endIconSlot;
 
   const updateWrapper = () => {
     wrapper = mount(DtSplitButton, {
@@ -40,8 +40,8 @@ describe('DtSplitButton Tests', function () {
         },
         plugins: [DtTooltipDirective],
         components: {
-          SplitButtonAlpha,
-          SplitButtonOmega,
+          SplitButtonStart,
+          SplitButtonEnd,
           DtIconSend,
         },
       },
@@ -49,10 +49,10 @@ describe('DtSplitButton Tests', function () {
       attachTo: document.body,
     });
 
-    alphaButton = wrapper.find('[data-qa="dt-split-button-alpha"]');
-    alphaIconSlot = alphaButton.find('[data-qa="dt-button-icon"]');
-    omegaButton = wrapper.find('[data-qa="dt-split-button-omega"]');
-    omegaIconSlot = omegaButton.find('[data-qa="dt-button-icon"]');
+    startButton = wrapper.find('[data-qa="dt-split-button-start"]');
+    startIconSlot = startButton.find('[data-qa="dt-button-icon"]');
+    endButton = wrapper.find('[data-qa="dt-split-button-end"]');
+    endIconSlot = endButton.find('[data-qa="dt-button-icon"]');
   };
 
   beforeAll(() => {
@@ -83,15 +83,15 @@ describe('DtSplitButton Tests', function () {
     describe('When rendered with default props', () => {
       it('Should render the component', () => {
         expect(wrapper.exists()).toBe(true);
-        expect(alphaButton.exists()).toBe(true);
-        expect(omegaButton.exists()).toBe(true);
-        expect(omegaIconSlot.exists()).toBe(true);
+        expect(startButton.exists()).toBe(true);
+        expect(endButton.exists()).toBe(true);
+        expect(endIconSlot.exists()).toBe(true);
       });
 
       it('Should render primary by default', async () => {
         // Default (no props) button should be d-btn--primary
-        expect(alphaButton.classes().includes('d-btn--primary')).toBe(true);
-        expect(omegaButton.classes().includes('d-btn--primary')).toBe(true);
+        expect(startButton.classes().includes('d-btn--primary')).toBe(true);
+        expect(endButton.classes().includes('d-btn--primary')).toBe(true);
       });
     });
 
@@ -101,8 +101,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.classes().includes('d-btn--danger')).toBe(true);
-        expect(omegaButton.classes().includes('d-btn--danger')).toBe(true);
+        expect(startButton.classes().includes('d-btn--danger')).toBe(true);
+        expect(endButton.classes().includes('d-btn--danger')).toBe(true);
       });
     });
 
@@ -112,8 +112,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.classes().includes('d-btn--outlined')).toBe(true);
-        expect(omegaButton.classes().includes('d-btn--outlined')).toBe(true);
+        expect(startButton.classes().includes('d-btn--outlined')).toBe(true);
+        expect(endButton.classes().includes('d-btn--outlined')).toBe(true);
       });
     });
 
@@ -123,7 +123,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.classes().includes('d-btn--loading')).toBe(true);
+        expect(startButton.classes().includes('d-btn--loading')).toBe(true);
       });
     });
 
@@ -133,8 +133,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.attributes('disabled')).toBeDefined();
-        expect(omegaButton.attributes('disabled')).toBeUndefined();
+        expect(startButton.attributes('disabled')).toBeDefined();
+        expect(endButton.attributes('disabled')).toBeUndefined();
       });
     });
 
@@ -144,8 +144,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.attributes('disabled')).toBeUndefined();
-        expect(omegaButton.attributes('disabled')).toBeDefined();
+        expect(startButton.attributes('disabled')).toBeUndefined();
+        expect(endButton.attributes('disabled')).toBeDefined();
       });
     });
 
@@ -155,8 +155,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.attributes('disabled')).toBeDefined();
-        expect(omegaButton.attributes('disabled')).toBeDefined();
+        expect(startButton.attributes('disabled')).toBeDefined();
+        expect(endButton.attributes('disabled')).toBeDefined();
       });
     });
 
@@ -166,7 +166,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.classes().includes('d-btn--active')).toBe(true);
+        expect(startButton.classes().includes('d-btn--active')).toBe(true);
       });
     });
 
@@ -176,7 +176,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(omegaButton.classes().includes('d-btn--active')).toBe(true);
+        expect(endButton.classes().includes('d-btn--active')).toBe(true);
       });
     });
 
@@ -186,8 +186,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.classes().includes('d-btn--xl')).toBe(true);
-        expect(omegaButton.classes().includes('d-btn--xl')).toBe(true);
+        expect(startButton.classes().includes('d-btn--xl')).toBe(true);
+        expect(endButton.classes().includes('d-btn--xl')).toBe(true);
       });
     });
 
@@ -199,11 +199,11 @@ describe('DtSplitButton Tests', function () {
       });
 
       it('Should render the custom icon', () => {
-        expect(alphaIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
+        expect(startIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
       });
 
       it('Should render left by default', () => {
-        expect(alphaIconSlot.classes().includes('d-btn__icon--left')).toBe(true);
+        expect(startIconSlot.classes().includes('d-btn__icon--left')).toBe(true);
       });
 
       describe('When startIconPosition is set to right', () => {
@@ -212,7 +212,7 @@ describe('DtSplitButton Tests', function () {
 
           updateWrapper();
 
-          expect(alphaIconSlot.classes().includes('d-btn__icon--right')).toBe(true);
+          expect(startIconSlot.classes().includes('d-btn__icon--right')).toBe(true);
         });
       });
     });
@@ -225,14 +225,14 @@ describe('DtSplitButton Tests', function () {
       });
 
       it('Should render start icon in the alpha button at start position', () => {
-        const startIconSlot = alphaButton.find('[data-qa="dt-button-start-icon"]');
+        const startIconSlot = startButton.find('[data-qa="dt-button-start-icon"]');
 
         expect(startIconSlot.exists()).toBe(true);
         expect(startIconSlot.findComponent(DtIconSend).exists()).toBe(true);
       });
 
       it('Should render end icon in the alpha button at end position', () => {
-        const endIconSlot = alphaButton.find('[data-qa="dt-button-end-icon"]');
+        const endIconSlot = startButton.find('[data-qa="dt-button-end-icon"]');
 
         expect(endIconSlot.exists()).toBe(true);
         expect(endIconSlot.findComponent(DtIconSend).exists()).toBe(true);
@@ -247,7 +247,7 @@ describe('DtSplitButton Tests', function () {
       });
 
       it('should render the custom icon', () => {
-        expect(omegaIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
+        expect(endIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
       });
     });
 
@@ -256,7 +256,7 @@ describe('DtSplitButton Tests', function () {
         mockProps = { startTooltipText: MOCK_START_TOOLTIP_TEXT };
         await updateWrapper();
         await flushPromises();
-        await alphaButton.trigger('mouseenter');
+        await startButton.trigger('mouseenter');
 
         const tooltip = document.body.querySelector('[data-qa="dt-tooltip"]');
 
@@ -269,7 +269,7 @@ describe('DtSplitButton Tests', function () {
         mockProps = { endTooltipText: MOCK_END_TOOLTIP_TEXT };
         await updateWrapper();
         await flushPromises();
-        await omegaButton.trigger('mouseenter');
+        await endButton.trigger('mouseenter');
 
         const tooltip = document.body.querySelector('[data-qa="dt-tooltip"]');
 
@@ -285,7 +285,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        await alphaButton.trigger('click');
+        await startButton.trigger('click');
       });
 
       it('Should call listener', async () => {
@@ -307,7 +307,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        await omegaButton.trigger('click');
+        await endButton.trigger('click');
       });
 
       it('Should call listener', async () => {
@@ -331,7 +331,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.classes().includes('d-btn--active')).toBe(true);
+        expect(startButton.classes().includes('d-btn--active')).toBe(true);
       });
     });
 
@@ -341,7 +341,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(omegaButton.classes().includes('d-btn--active')).toBe(true);
+        expect(endButton.classes().includes('d-btn--active')).toBe(true);
       });
     });
 
@@ -351,7 +351,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.classes().includes('d-btn--loading')).toBe(true);
+        expect(startButton.classes().includes('d-btn--loading')).toBe(true);
       });
     });
 
@@ -361,8 +361,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.attributes('disabled')).toBeDefined();
-        expect(omegaButton.attributes('disabled')).toBeUndefined();
+        expect(startButton.attributes('disabled')).toBeDefined();
+        expect(endButton.attributes('disabled')).toBeUndefined();
       });
     });
 
@@ -372,8 +372,8 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.attributes('disabled')).toBeUndefined();
-        expect(omegaButton.attributes('disabled')).toBeDefined();
+        expect(startButton.attributes('disabled')).toBeUndefined();
+        expect(endButton.attributes('disabled')).toBeDefined();
       });
     });
 
@@ -383,7 +383,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
+        expect(startIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
       });
     });
 
@@ -393,7 +393,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(omegaIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
+        expect(endIconSlot.findComponent(DtIconSend).classes().includes('d-icon--send')).toBe(true);
       });
     });
 
@@ -403,9 +403,9 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+        const startComponent = wrapper.findComponent(SplitButtonStart);
 
-        expect(alphaComponent.props('tooltipText')).toBe(MOCK_START_TOOLTIP_TEXT);
+        expect(startComponent.props('tooltipText')).toBe(MOCK_START_TOOLTIP_TEXT);
       });
     });
 
@@ -415,9 +415,9 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const omegaComponent = wrapper.findComponent(SplitButtonOmega);
+        const endComponent = wrapper.findComponent(SplitButtonEnd);
 
-        expect(omegaComponent.props('tooltipText')).toBe(MOCK_END_TOOLTIP_TEXT);
+        expect(endComponent.props('tooltipText')).toBe(MOCK_END_TOOLTIP_TEXT);
       });
     });
 
@@ -427,7 +427,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.attributes('aria-label')).toBe('Call action');
+        expect(startButton.attributes('aria-label')).toBe('Call action');
       });
     });
 
@@ -437,7 +437,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(omegaButton.attributes('aria-label')).toBe('More options');
+        expect(endButton.attributes('aria-label')).toBe('More options');
       });
     });
 
@@ -448,7 +448,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaIconSlot.classes().includes('d-btn__icon--right')).toBe(true);
+        expect(startIconSlot.classes().includes('d-btn__icon--right')).toBe(true);
       });
     });
 
@@ -458,7 +458,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const labelEl = alphaButton.find('[data-qa="dt-button-label"]');
+        const labelEl = startButton.find('[data-qa="dt-button-label"]');
 
         expect(labelEl.classes().includes('custom-label-class')).toBe(true);
       });
@@ -473,7 +473,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaIconSlot.findComponent(DtIconSend).exists()).toBe(true);
+        expect(startIconSlot.findComponent(DtIconSend).exists()).toBe(true);
         expect(wrapper.find('[data-qa="old-alpha-icon"]').exists()).toBe(false);
       });
     });
@@ -487,7 +487,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(omegaIconSlot.findComponent(DtIconSend).exists()).toBe(true);
+        expect(endIconSlot.findComponent(DtIconSend).exists()).toBe(true);
         expect(wrapper.find('[data-qa="old-omega-icon"]').exists()).toBe(false);
       });
     });
@@ -505,7 +505,7 @@ describe('DtSplitButton Tests', function () {
           global: {
             stubs: { transition: false },
             plugins: [DtTooltipDirective],
-            components: { SplitButtonAlpha, SplitButtonOmega, DtIconSend },
+            components: { SplitButtonStart, SplitButtonEnd, DtIconSend },
           },
           attrs: { ...baseAttrs, ...mockAttrs },
           attachTo: document.body,
@@ -526,7 +526,7 @@ describe('DtSplitButton Tests', function () {
           global: {
             stubs: { transition: false },
             plugins: [DtTooltipDirective],
-            components: { SplitButtonAlpha, SplitButtonOmega, DtIconSend },
+            components: { SplitButtonStart, SplitButtonEnd, DtIconSend },
           },
           attrs: { ...baseAttrs, ...mockAttrs },
           attachTo: document.body,
@@ -541,7 +541,7 @@ describe('DtSplitButton Tests', function () {
 
     describe('When start button is clicked', () => {
       it('Should emit deprecated alpha-clicked event', async () => {
-        await alphaButton.trigger('click');
+        await startButton.trigger('click');
 
         expect(wrapper.emitted()).toHaveProperty('alpha-clicked');
       });
@@ -549,7 +549,7 @@ describe('DtSplitButton Tests', function () {
 
     describe('When end button is clicked', () => {
       it('Should emit deprecated omega-clicked event', async () => {
-        await omegaButton.trigger('click');
+        await endButton.trigger('click');
 
         expect(wrapper.emitted()).toHaveProperty('omega-clicked');
       });
@@ -563,9 +563,9 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+        const startComponent = wrapper.findComponent(SplitButtonStart);
 
-        expect(alphaComponent.props('to')).toBe('/some-route');
+        expect(startComponent.props('to')).toBe('/some-route');
       });
     });
 
@@ -576,9 +576,9 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+        const startComponent = wrapper.findComponent(SplitButtonStart);
 
-        expect(alphaComponent.props('to')).toEqual(route);
+        expect(startComponent.props('to')).toEqual(route);
       });
     });
 
@@ -588,9 +588,9 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+        const startComponent = wrapper.findComponent(SplitButtonStart);
 
-        expect(alphaComponent.props('href')).toBe('https://example.com');
+        expect(startComponent.props('href')).toBe('https://example.com');
       });
     });
 
@@ -604,10 +604,10 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+        const startComponent = wrapper.findComponent(SplitButtonStart);
 
-        expect(alphaComponent.props('target')).toBe('_blank');
-        expect(alphaComponent.props('rel')).toBe('noopener noreferrer');
+        expect(startComponent.props('target')).toBe('_blank');
+        expect(startComponent.props('rel')).toBe('noopener noreferrer');
       });
     });
 
@@ -617,9 +617,9 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const alphaComponent = wrapper.findComponent(SplitButtonAlpha);
+        const startComponent = wrapper.findComponent(SplitButtonStart);
 
-        expect(alphaComponent.props('replace')).toBe(true);
+        expect(startComponent.props('replace')).toBe(true);
       });
     });
   });
@@ -642,7 +642,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const leading = alphaButton.find('.d-btn__leading');
+        const leading = startButton.find('.d-btn__leading');
 
         expect(leading.exists()).toBe(true);
         expect(leading.classes()).toContain('custom-leading');
@@ -656,7 +656,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        const trailing = alphaButton.find('.d-btn__trailing');
+        const trailing = startButton.find('.d-btn__trailing');
 
         expect(trailing.exists()).toBe(true);
         expect(trailing.classes()).toContain('custom-trailing');
@@ -669,7 +669,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.find('[data-qa="test-leading"]').exists()).toBe(true);
+        expect(startButton.find('[data-qa="test-leading"]').exists()).toBe(true);
       });
     });
 
@@ -679,7 +679,7 @@ describe('DtSplitButton Tests', function () {
 
         updateWrapper();
 
-        expect(alphaButton.find('[data-qa="test-trailing"]').exists()).toBe(true);
+        expect(startButton.find('[data-qa="test-trailing"]').exists()).toBe(true);
       });
     });
   });
diff --git a/packages/dialtone-vue/components/split_button/split_button.vue b/packages/dialtone-vue/components/split_button/split_button.vue
index 4255aebfb8..5905ecd261 100644
--- a/packages/dialtone-vue/components/split_button/split_button.vue
+++ b/packages/dialtone-vue/components/split_button/split_button.vue
@@ -4,9 +4,9 @@
     :class="[rootClass, 'd-split-btn']"
     :style="{ width }"
   >
-    <split-button-alpha
-      v-bind="alphaButtonProps"
-      ref="alphaButton"
+    <split-button-start
+      v-bind="startButtonProps"
+      ref="startButton"
       @click="onStartClick"
     >
       <!-- Dual-icon path: when startEndIcon is provided, use DtButton's startIcon/endIcon -->
@@ -71,7 +71,7 @@
       </template>
       <!-- @slot Default content slot -->
       <slot name="default" />
-    </split-button-alpha>
+    </split-button-start>
     <!-- @slot End (right) content slot, overrides end button styling and functionality completely -->
     <template v-if="$slots.end">
       <slot name="end" />
@@ -88,8 +88,8 @@
         @opened="open => isDropdownOpen = open"
       >
         <template #anchor="attrs">
-          <split-button-omega
-            v-bind="{ ...attrs, ...omegaButtonProps }"
+          <split-button-end
+            v-bind="{ ...attrs, ...endButtonProps }"
             :active="isDropdownOpen"
             @click="onEndClick"
           >
@@ -107,7 +107,7 @@
                 :size="iconSize"
               />
             </template>
-          </split-button-omega>
+          </split-button-end>
         </template>
         <template #list="{ close }">
           <!-- @slot Built-in dropdown content slot, use of dt-list-item is highly recommended here. -->
@@ -118,9 +118,9 @@
         </template>
       </dt-dropdown>
 
-      <split-button-omega
+      <split-button-end
         v-else
-        v-bind="omegaButtonProps"
+        v-bind="endButtonProps"
         @click="onEndClick"
       >
         <template #icon="{ size: iconSize }">
@@ -137,7 +137,7 @@
             :size="iconSize"
           />
         </template>
-      </split-button-omega>
+      </split-button-end>
     </template>
   </span>
 </template>
@@ -149,8 +149,8 @@ import {
   BUTTON_SIZE_MODIFIERS,
   ICON_POSITION_MODIFIERS,
 } from '@/components/button';
-import SplitButtonAlpha from './split_button-alpha.vue';
-import SplitButtonOmega from './split_button-omega.vue';
+import SplitButtonStart from './split_button-start.vue';
+import SplitButtonEnd from './split_button-end.vue';
 import { DtDropdown } from '@/components/dropdown';
 import { hasSlotContent, warnIfUnmounted, returnFirstEl } from '@/common/utils';
 
@@ -159,9 +159,9 @@ export default {
   name: 'DtSplitButton',
 
   components: {
-    SplitButtonOmega,
+    SplitButtonEnd,
     DtDropdown,
-    SplitButtonAlpha,
+    SplitButtonStart,
   },
 
   inheritAttrs: false,
@@ -581,7 +581,7 @@ export default {
   },
 
   computed: {
-    alphaButtonProps () {
+    startButtonProps () {
       return {
         active: this.alphaActive ?? this.startActive,
         ariaLabel: this.alphaAriaLabel ?? this.startAriaLabel,
@@ -606,7 +606,7 @@ export default {
       };
     },
 
-    omegaButtonProps () {
+    endButtonProps () {
       return {
         id: this.omegaId ?? this.endId,
         active: this.omegaActive ?? this.endActive,
@@ -646,11 +646,11 @@ export default {
     },
 
     validateProps () {
-      this.validateAlphaButtonProps();
-      this.validateOmegaButtonProps();
+      this.validateStartButtonProps();
+      this.validateEndButtonProps();
     },
 
-    validateAlphaButtonProps () {
+    validateStartButtonProps () {
       if (hasSlotContent(this.$slots.default)) return;
 
       if ((hasSlotContent(this.$slots.startIcon) || hasSlotContent(this.$slots.alphaIcon)) &&
@@ -659,7 +659,7 @@ export default {
       }
     },
 
-    validateOmegaButtonProps () {
+    validateEndButtonProps () {
       if (hasSlotContent(this.$slots.end) || hasSlotContent(this.$slots.omega)) return;
 
       if (!(this.omegaTooltipText ?? this.endTooltipText)) {

From a15ad42f7b3f6dac8a2a1648714de3b391f7e428 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 16:50:47 -0600
Subject: [PATCH 17/47] update test descriptions to use 'start' instead of
 'alpha' terminology

---
 .../split_button/split_button.test.js          | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/dialtone-vue/components/split_button/split_button.test.js b/packages/dialtone-vue/components/split_button/split_button.test.js
index f1f23a03e8..a5a4b3b60d 100644
--- a/packages/dialtone-vue/components/split_button/split_button.test.js
+++ b/packages/dialtone-vue/components/split_button/split_button.test.js
@@ -224,14 +224,14 @@ describe('DtSplitButton Tests', function () {
         updateWrapper();
       });
 
-      it('Should render start icon in the alpha button at start position', () => {
+      it('Should render start icon in the start button at start position', () => {
         const startIconSlot = startButton.find('[data-qa="dt-button-start-icon"]');
 
         expect(startIconSlot.exists()).toBe(true);
         expect(startIconSlot.findComponent(DtIconSend).exists()).toBe(true);
       });
 
-      it('Should render end icon in the alpha button at end position', () => {
+      it('Should render end icon in the start button at end position', () => {
         const endIconSlot = startButton.find('[data-qa="dt-button-end-icon"]');
 
         expect(endIconSlot.exists()).toBe(true);
@@ -558,7 +558,7 @@ describe('DtSplitButton Tests', function () {
 
   describe('Navigation Tests', () => {
     describe('When startTo is provided', () => {
-      it('Should forward to prop to the alpha DtButton', () => {
+      it('Should forward to prop to the start DtButton', () => {
         mockProps = { startTo: '/some-route' };
 
         updateWrapper();
@@ -570,7 +570,7 @@ describe('DtSplitButton Tests', function () {
     });
 
     describe('When startTo is an object', () => {
-      it('Should forward the route object to the alpha DtButton', () => {
+      it('Should forward the route object to the start DtButton', () => {
         const route = { name: 'home', params: { id: 1 } };
         mockProps = { startTo: route };
 
@@ -583,7 +583,7 @@ describe('DtSplitButton Tests', function () {
     });
 
     describe('When startHref is provided', () => {
-      it('Should forward href prop to the alpha DtButton', () => {
+      it('Should forward href prop to the start DtButton', () => {
         mockProps = { startHref: 'https://example.com' };
 
         updateWrapper();
@@ -595,7 +595,7 @@ describe('DtSplitButton Tests', function () {
     });
 
     describe('When startTarget and startRel are provided', () => {
-      it('Should forward target and rel props to the alpha DtButton', () => {
+      it('Should forward target and rel props to the start DtButton', () => {
         mockProps = {
           startHref: 'https://example.com',
           startTarget: '_blank',
@@ -612,7 +612,7 @@ describe('DtSplitButton Tests', function () {
     });
 
     describe('When startReplace is provided', () => {
-      it('Should forward replace prop to the alpha DtButton', () => {
+      it('Should forward replace prop to the start DtButton', () => {
         mockProps = { startTo: '/some-route', startReplace: true };
 
         updateWrapper();
@@ -664,7 +664,7 @@ describe('DtSplitButton Tests', function () {
     });
 
     describe('When leading slot is provided', () => {
-      it('should render leading content through to alpha button', () => {
+      it('should render leading content through to start button', () => {
         mockSlots = { leading: '<span data-qa="test-leading">L</span>' };
 
         updateWrapper();
@@ -674,7 +674,7 @@ describe('DtSplitButton Tests', function () {
     });
 
     describe('When trailing slot is provided', () => {
-      it('should render trailing content through to alpha button', () => {
+      it('should render trailing content through to start button', () => {
         mockSlots = { trailing: '<span data-qa="test-trailing">T</span>' };
 
         updateWrapper();

From eccff2030ccb71b2896f17f08c926d63db1fc20a Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 21:52:26 -0600
Subject: [PATCH 18/47] init mode directive

---
 .../docs/components/mode-island.md            | 350 +++++++++++-------
 .../docs/guides/theme-and-mode/index.md       |  15 +-
 .../build/less/components/mode-island.less    |   5 +-
 .../directives/mode_directive/index.js        |   1 +
 .../directives/mode_directive/mode.js         | 117 ++++++
 .../directives/mode_directive/mode.mdx        |  43 +++
 .../directives/mode_directive/mode.stories.js |  28 ++
 .../directives/mode_directive/mode.test.js    | 256 +++++++++++++
 .../mode_directive_default.story.vue          | 186 ++++++++++
 packages/dialtone-vue/index.js                |   1 +
 10 files changed, 873 insertions(+), 129 deletions(-)
 create mode 100644 packages/dialtone-vue/directives/mode_directive/index.js
 create mode 100644 packages/dialtone-vue/directives/mode_directive/mode.js
 create mode 100644 packages/dialtone-vue/directives/mode_directive/mode.mdx
 create mode 100644 packages/dialtone-vue/directives/mode_directive/mode.stories.js
 create mode 100644 packages/dialtone-vue/directives/mode_directive/mode.test.js
 create mode 100644 packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue

diff --git a/apps/dialtone-documentation/docs/components/mode-island.md b/apps/dialtone-documentation/docs/components/mode-island.md
index 595f8874b7..4f7551a864 100644
--- a/apps/dialtone-documentation/docs/components/mode-island.md
+++ b/apps/dialtone-documentation/docs/components/mode-island.md
@@ -1,8 +1,8 @@
 ---
 title: Mode Island
-description: Create independent sections with their own color modes.
+description: Apply light, dark, or inverted color mode to any element or region.
 status: beta
-keywords: ["theme island","mode override","d-mode-island","DtModeIsland","dt-mode-island"]
+keywords: ["theme island","mode override","v-dt-mode","directive","light","dark","inverted"]
 ---
 
 <code-well-header>
@@ -17,17 +17,30 @@ keywords: ["theme island","mode override","d-mode-island","DtModeIsland","dt-mod
           <dt-button
             importance="outlined"
             kind="muted"
+            size="sm"
           >
             <dt-stack gap="400" direction="row">
-              <dt-text><dt-text strength="strong">Mode:</dt-text> {{ currentMode.charAt(0).toUpperCase() + currentMode.slice(1) }}</dt-text>
-              <dt-text><dt-text strength="strong">Contrast:</dt-text> {{ currentContrast.charAt(0).toUpperCase() + currentContrast.slice(1) }}</dt-text>
+              <span>
+                <dt-text strength="bold">Mode:</dt-text>
+                <dt-text tone="tertiary">{{ currentMode.charAt(0).toUpperCase() + currentMode.slice(1) }}</dt-text>
+              </span>
+              <span>
+                <dt-text strength="bold">Contrast:</dt-text>
+                <dt-text tone="tertiary">{{ currentContrast.charAt(0).toUpperCase() + currentContrast.slice(1) }}</dt-text>
+              </span>
             </dt-stack>
-            <template #startIcon>
+            <template #startIcon="{ iconSize }">
               <dt-icon
-                size="300"
+                :size="iconSize"
                 :name="currentModeIconName"
               />
             </template>
+            <template #endIcon="{ iconSize }">
+              <dt-icon
+                :size="iconSize"
+                name="chevron-down"
+              />
+            </template>
           </dt-button>
         </template>
         <template #list>
@@ -96,7 +109,7 @@ keywords: ["theme island","mode override","d-mode-island","DtModeIsland","dt-mod
       </dt-dropdown>
     </dt-stack>
     <dt-stack :direction="{ 'default': 'column', 'md': 'row' }" gap="500" class="d-w100p">
-      <dt-mode-island class="d-p16 d-bar8 d-ba d-fl1">
+      <section v-dt-mode class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default d-fl1">
         <dt-stack gap="400">
           <dt-stack direction="row" gap="400" class="d-jc-space-between">
             <dt-text as="h3" kind="headline" size="md" density="200">Inverted <dt-text strength="normal">(auto)</dt-text></dt-text>
@@ -115,8 +128,8 @@ keywords: ["theme island","mode override","d-mode-island","DtModeIsland","dt-mod
             <dt-button class="d-fl1" kind="danger">Button</dt-button>
           </dt-stack>
         </dt-stack>
-      </dt-mode-island>
-      <dt-mode-island mode="light" class="d-p16 d-bar8 d-ba d-fl1">
+      </section>
+      <section v-dt-mode:light class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default d-fl1">
         <dt-stack gap="400">
           <dt-stack direction="row" gap="400" class="d-jc-space-between">
             <dt-text as="h3" kind="headline" size="md" density="200">Explicit light</dt-text>
@@ -135,8 +148,8 @@ keywords: ["theme island","mode override","d-mode-island","DtModeIsland","dt-mod
             <dt-button class="d-fl1" kind="danger">Button</dt-button>
           </dt-stack>
         </dt-stack>
-      </dt-mode-island>
-      <dt-mode-island mode="dark" class="d-p16 d-bar8 d-ba d-fl1">
+      </section>
+      <section v-dt-mode:dark class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default d-fl1">
         <dt-stack gap="400">
           <dt-stack direction="row" gap="400" class="d-jc-space-between">
             <dt-text as="h3" kind="headline" size="md" density="200">Explicit dark</dt-text>
@@ -155,31 +168,99 @@ keywords: ["theme island","mode override","d-mode-island","DtModeIsland","dt-mod
             <dt-button class="d-fl1" kind="danger">Button</dt-button>
           </dt-stack>
         </dt-stack>
-      </dt-mode-island>
+      </section>
     </dt-stack>
   </dt-stack>
 </code-well-header>
 
 ## Usage
 
-Mode islands create isolated regions that may display in a different color mode, `light`, `dark`, or `inverted`. Useful for forcing a region to a controlled mode for a unique UI purpose.
+Use the `v-dt-mode` directive to control the color mode of a region, component, or element. It creates an scoped region with the specified mode. Descendant elements retain their original styling but are rendered with the specified mode.
+
+<code-well-header>
+  <dt-text v-dt-mode:dark tone="success"> Dark content </dt-text>
+  <dt-text v-dt-mode:light tone="success"> Light content </dt-text>
+  <dt-text v-dt-mode:invert tone="success"> Inverted — opposite of parent or root </dt-text>
+</code-well-header>
+<code-example-tabs
+vueCode='
+<dt-text v-dt-mode:dark tone="success"> Dark content </dt-text>
+<dt-text v-dt-mode:light tone="success"> Light content </dt-text>
+<dt-text v-dt-mode:invert tone="success"> Inverted — opposite of parent or root </dt-text>
+'
+/>
+
+### Inverting
 
-### Structure
+This effectively removes the need for `inverted` props or variants on elements or components.
+
+For example, instead of using `inverted` on a DtButton, use `v-dt-mode:invert`
 
 <code-example-tabs
 vueCode='
-<dt-mode-island>
-  Inverted
-</dt-mode-island>
-<dt-mode-island mode="light">
-  Light
-</dt-mode-island>
-<dt-mode-island mode="dark">
-  Dark
-</dt-mode-island>
+<dt-button>Button</dt-button>
+<dt-button v-dt-mode:invert>Button</dt-button>
 '
 />
 
+<code-well-header>
+  <dt-stack gap="400" direction="row">
+    <dt-button>Button</dt-button>
+    <dt-button v-dt-mode:invert>Button</dt-button>
+  </dt-stack>
+</code-well-header>
+
+### Dynamic mode
+
+Bind a reactive variable as the directive arg to switch modes at runtime.
+
+<code-well-header>
+  <dt-stack gap="500">
+    <dt-stack gap="400" direction="row">
+      <dt-button
+        kind="muted"
+        importance="outlined"
+        :active="dynamicMode === 'invert'"
+        @click="dynamicMode = 'invert'"
+      >
+        Invert
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="circle-half-filled" :size="iconSize" />
+        </template>
+      </dt-button>
+      <dt-button
+        kind="muted"
+        importance="outlined"
+        :active="dynamicMode === 'light'"
+        @click="dynamicMode = 'light'"
+      >
+        Light
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="sun" :size="iconSize" />
+        </template>
+      </dt-button>
+      <dt-button
+        kind="muted"
+        importance="outlined"
+        :active="dynamicMode === 'dark'"
+        @click="dynamicMode = 'dark'"
+      >
+        Dark
+        <template #startIcon="{ iconSize }">
+          <dt-icon name="moon" :size="iconSize" />
+        </template>
+      </dt-button>
+    </dt-stack>
+    <dt-text v-dt-mode:[dynamicMode] align="center" tone="success"> {{ dynamicMode }} mode </dt-text>
+  </dt-stack>
+</code-well-header>
+
+<code-example-tabs
+vueCode='
+<dt-text v-dt-mode:[dynamicMode] align="center" tone="success"> {{ dynamicMode }} mode content </dt-text>
+'
+showHtmlWarning />
+
 ### Guidance
 
 <dialtone-usage>
@@ -195,43 +276,39 @@ vueCode='
 <template #dont>
 
 - Do not overuse mode islands, respect user theme preference
-- Do not use purely for decoration. Ensure Mode Island use serves a functional and unique purpose
+- Do not use purely for decoration. Ensure mode island use serves a functional and unique purpose
 - Avoid nesting deeply. Keep hierarchy shallow for maintainability
 
 </template>
 
 </dialtone-usage>
 
-### Reactive Mode Updates
-
-Inverted islands reactively track parent/root mode changes. User switches light ↔ dark → inverted islands flip automatically. Even directly modifying the `mode` attribute will also work.
+### How it works
 
-### Brand Theme Protection
-
-`data-dt-brand` (aka "Theme", e.g. "tmo", "sunflower", etc) can not be set on Mode Islands. Brand theme can only be set at root level and are inherited
-
-### Contrast Inheritance
-
-Contrast is not an option to set to a Mode Island. Contrast theme setting is inherited from the root element, i.e. `<html>`.
+- CSS tokens activate via `[data-dt-mode="light"]` and `[data-dt-mode="dark"]` attribute selectors
+- High-contrast tokens layer via `[data-dt-mode][data-dt-contrast="high"]`
+- Contrast is inherited from the root `<html>` element and kept in sync via MutationObserver
+- For `invert` mode, the directive reads the nearest ancestor's `data-dt-mode`, computes the opposite, and reacts when it changes
+- `data-dt-brand` (theme) cannot be set on mode islands — brand is root-level only
 
 ## Variants
 
 ### Inverted
 
-The default mode, inverts the container relative to the parent or root's mode. When `mode` attribute is omitted, it defaults to `inverted`.
+The default mode — inverts relative to the nearest parent mode boundary or the root. When no arg is provided, `v-dt-mode` defaults to invert.
 
 <code-well-header>
-  <dt-mode-island ref="invertedExample" class="d-p16 d-bar8">
-    <dt-text as="p">Inverted mode (opposite of parent)</dt-text>
-  </dt-mode-island>
+  <section ref="invertedExample" v-dt-mode class="d-p16 d-bar8">
+    <dt-text as="p" tone="success">Inverted mode (opposite of parent)</dt-text>
+  </section>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.invertedExample'
 vueCode='
-<dt-mode-island class="d-p16 d-bar8">
-  <dt-text as="p">Inverted mode (opposite of parent)</dt-text>
-</dt-mode-island>
+<section v-dt-mode class="d-p16 d-bar8">
+  <dt-text as="p" tone="success">Inverted mode (opposite of parent)</dt-text>
+</section>
 '
 showHtmlWarning />
 
@@ -240,17 +317,17 @@ showHtmlWarning />
 Explicitly set to light mode regardless of parent or root mode.
 
 <code-well-header>
-  <dt-mode-island ref="lightExample" mode="light" class="d-p16 d-bar8">
-    <dt-text as="p">Always light mode</dt-text>
-  </dt-mode-island>
+  <section ref="lightExample" v-dt-mode:light class="d-p16 d-bar8">
+    <dt-text as="p" tone="success">Always light mode</dt-text>
+  </section>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.lightExample'
 vueCode='
-<dt-mode-island mode="light" class="d-p16 d-bar8">
-  <dt-text as="p">Always light mode</dt-text>
-</dt-mode-island>
+<section v-dt-mode:light class="d-p16 d-bar8">
+  <dt-text as="p" tone="success">Always light mode</dt-text>
+</section>
 '
 showHtmlWarning />
 
@@ -259,69 +336,48 @@ showHtmlWarning />
 Explicitly set to dark mode regardless of parent or root mode.
 
 <code-well-header>
-  <dt-mode-island ref="darkExample" mode="dark" class="d-p16 d-bar8">
-    <dt-text as="p">Always dark mode</dt-text>
-  </dt-mode-island>
+  <section ref="darkExample" v-dt-mode:dark class="d-p16 d-bar8">
+    <dt-text as="p" tone="success">Always dark mode</dt-text>
+  </section>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.darkExample'
 vueCode='
-<dt-mode-island mode="dark" class="d-p16 d-bar8">
+<section v-dt-mode:dark class="d-p16 d-bar8">
   <dt-text as="p">Always dark mode</dt-text>
-</dt-mode-island>
+</section>
 '
 showHtmlWarning />
 
-## Custom element
-
-Polymorphic rendering via `as` prop—controls which HTML element wraps content. Ensures proper document structure and semantic markup. Example values: `section` for thematic grouping, `article` for self-contained content. Defaults to `div` where semantics aren't a concern.
-
-<code-well-header>
-  <dt-mode-island ref="sectionExample" as="section" mode="dark" class="d-p16 d-bar8">
-    <dt-text as="p">Rendered as section element</dt-text>
-  </dt-mode-island>
-</code-well-header>
-
-<code-example-tabs
-:htmlCode='() => $refs.sectionExample'
-vueCode='
-<dt-mode-island as="section" mode="dark" class="d-p16 d-bar8">
-  <dt-text as="p">Rendered as section element</dt-text>
-</dt-mode-island>
-'
-showHtmlWarning />
-
-**Common values:** `div` (default), `section`, `article`, `nav`, `aside`, `header`, `footer`, `main`
-
 ## Nesting
 
-Mode islands may be nested, though should rarely occur.
+Mode boundaries can be nested. Each `v-dt-mode:invert` reads the nearest parent boundary and flips. In this example the first level is explicitly set to light mode, the second level inverts against that, and the third level inverts again.
 
 <code-well-header>
-  <dt-mode-island ref="nestingExample" mode="light" class="d-p16 d-bar8">
-    <dt-text as="p">Light island</dt-text>
-    <dt-mode-island class="d-p16 d-bar8">
-      <dt-text as="p">Inverted → Dark island</dt-text>
-      <dt-mode-island class="d-p16 d-bar4">
-        <dt-text as="p">Inverted again → Light island</dt-text>
-      </dt-mode-island>
-    </dt-mode-island>
-  </dt-mode-island>
+  <dt-stack gap="400" ref="nestingExample" v-dt-mode:light class="d-p16 d-bar8 d-bgc-secondary d-ba">
+    <dt-text as="p" tone="success">Light</dt-text>
+    <dt-stack v-dt-mode gap="400" class="d-p16 d-bar8 d-bgc-secondary">
+      <dt-text as="p" tone="success">Inverted (Dark)</dt-text>
+      <dt-stack v-dt-mode gap="400" class="d-p16 d-bar4 d-bgc-secondary">
+        <dt-text as="p" tone="success">Inverted again (Light)</dt-text>
+      </dt-stack>
+    </dt-stack>
+  </dt-stack>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.nestingExample'
 vueCode='
-<dt-mode-island mode="light" class="d-p16 d-bar8">
-  <dt-text as="p">Light island</dt-text>
-  <dt-mode-island class="d-p16 d-bar8">
-    <dt-text as="p">Inverted → Dark island</dt-text>
-    <dt-mode-island class="d-p16 d-bar4">
-      <dt-text as="p">Inverted again → Light island</dt-text>
-    </dt-mode-island>
-  </dt-mode-island>
-</dt-mode-island>
+<dt-stack gap="400" v-dt-mode:light class="d-p16 d-bar8 d-bgc-secondary d-ba">
+  <dt-text as="p" tone="success">Light</dt-text>
+  <dt-stack v-dt-mode gap="400" class="d-p16 d-bar8 d-bgc-secondary">
+    <dt-text as="p" tone="success">Inverted (Dark)</dt-text>
+    <dt-stack v-dt-mode gap="400" class="d-p16 d-bar4 d-bgc-secondary">
+      <dt-text as="p" tone="success">Inverted again (Light)</dt-text>
+    </dt-stack>
+  </dt-stack>
+</dt-stack>
 '
 />
 
@@ -329,8 +385,10 @@ vueCode='
 
 ### Callbar
 
+A real-world pattern: the callbar container already exists as a semantic element. The directive applies mode theming directly — no wrapper needed.
+
 <code-well-header>
-  <dt-mode-island ref="callbarExample" class="d-ba d-bc-subtle d-p8 d-py4 d-bar32 d-bs-md d-w100p">
+  <nav ref="callbarExample" v-dt-mode class="d-ba d-bc-subtle d-bgc-secondary d-p8 d-py4 d-bar12 d-bs-md d-w100p">
     <dt-stack direction="row" gap="600">
       <dt-stack gap="400" direction="row">
         <dt-avatar
@@ -375,23 +433,23 @@ vueCode='
         </dt-button>
       </dt-stack>
     </dt-stack>
-  </dt-mode-island>
+  </nav>
   <dt-text as="p" tone="muted" class="d-mt8">* Not real, still just an example</dt-text>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.callbarExample'
 vueCode='
-<dt-mode-island class="d-ba d-bc-subtle d-p8 d-py4 d-bar32 d-bs-md d-w100p">
+<nav v-dt-mode class="d-ba d-bc-subtle d-p8 d-py4 d-bar32 d-bs-md d-w100p">
   <dt-stack direction="row" gap="600">
     <dt-stack gap="400" direction="row">
       <dt-avatar full-name="TA" seed="ted-anderson" size="lg" />
       <dt-stack gap="200">
         <dt-text kind="label" size="md" density="200">Ted Anderson</dt-text>
         <dt-stack direction="row" gap="300" align="baseline">
-          <dt-text kind="helper" size="sm" tone="tertiary" wrap="nowrap" numeric>(913) 555-6745</dt-text>
-          <dt-text kind="helper" size="sm" tone="muted">&bull;</dt-text>
-          <dt-text kind="helper" size="sm" tone="tertiary" numeric>21:18</dt-text>
+          <dt-text kind="body" size="xs" tone="tertiary" wrap="nowrap" numeric>(913) 555-6745</dt-text>
+          <dt-text kind="body" size="xs" tone="muted">&bull;</dt-text>
+          <dt-text kind="body" size="xs" tone="tertiary" numeric>21:18</dt-text>
         </dt-stack>
       </dt-stack>
     </dt-stack>
@@ -408,13 +466,13 @@ vueCode='
       </dt-button>
     </dt-stack>
   </dt-stack>
-</dt-mode-island>
+</nav>
 '
 showHtmlWarning />
 
 ### Positioned Components
 
-[Popovers](/components/popover.html), [Dropdowns](/components/dropdown.html), and [Hovercards](/components/hovercard.html) are typically rendered at the root element of the DOM tree, and thus inherit the page's mode by default. They can be forced to a specific mode by assigning a Mode Island to its content slot.
+[Popovers](/components/popover.html), [Dropdowns](/components/dropdown.html), and [Hovercards](/components/hovercard.html) render at the root of the DOM tree and inherit the page's mode. Use `v-dt-mode` on the slot content's container to override.
 
 <code-well-header>
   <dt-stack gap="500">
@@ -436,9 +494,9 @@ showHtmlWarning />
             <dt-button size="sm" kind="muted" importance="outlined">Inverted </dt-button>
           </template>
           <template #content>
-            <dt-mode-island class="d-p16 d-bgc-secondary">
+            <div v-dt-mode class="d-p16 d-bgc-secondary">
               <ExampleProfileCard />
-            </dt-mode-island>
+            </div>
           </template>
         </dt-hovercard>
         <dt-hovercard padding="none" placement="top-start">
@@ -446,9 +504,9 @@ showHtmlWarning />
             <dt-button size="sm" kind="muted" importance="outlined">Light </dt-button>
           </template>
           <template #content>
-            <dt-mode-island mode="light" class="d-p16 d-bgc-secondary">
+            <div v-dt-mode:light class="d-p16 d-bgc-secondary">
               <ExampleProfileCard />
-            </dt-mode-island>
+            </div>
           </template>
         </dt-hovercard>
         <dt-hovercard padding="none" placement="top-start">
@@ -456,9 +514,9 @@ showHtmlWarning />
             <dt-button size="sm" kind="muted" importance="outlined">Dark </dt-button>
           </template>
           <template #content>
-            <dt-mode-island mode="dark" class="d-p16 d-bgc-secondary">
+            <div v-dt-mode:dark class="d-p16 d-bgc-secondary">
               <ExampleProfileCard />
-            </dt-mode-island>
+            </div>
           </template>
         </dt-hovercard>
       </dt-stack>
@@ -481,9 +539,9 @@ showHtmlWarning />
             <dt-button size="sm" kind="muted" importance="outlined"> Inverted </dt-button>
           </template>
           <template #content="{ close }">
-            <dt-mode-island mode="inverted" class="d-p16 d-bgc-secondary">
+            <div v-dt-mode class="d-p16 d-bgc-secondary">
               <dt-text as="p">This Popover's content is in the <dt-text strength="strong">inverted</dt-text> mode.</dt-text>
-            </dt-mode-island>
+            </div>
           </template>
         </dt-popover>
         <dt-popover padding="none" placement="top-start" dialogClass="d-w216">
@@ -491,9 +549,9 @@ showHtmlWarning />
             <dt-button size="sm" kind="muted" importance="outlined"> Light </dt-button>
           </template>
           <template #content="{ close }">
-            <dt-mode-island mode="light" class="d-p16 d-bgc-secondary">
+            <div v-dt-mode:light class="d-p16 d-bgc-secondary">
               <dt-text as="p">This Popover's content is in explicit <dt-text strength="strong">light</dt-text> mode.</dt-text>
-            </dt-mode-island>
+            </div>
           </template>
         </dt-popover>
         <dt-popover padding="none" placement="top-start" dialogClass="d-w216">
@@ -501,9 +559,9 @@ showHtmlWarning />
             <dt-button size="sm" kind="muted" importance="outlined"> Dark </dt-button>
           </template>
           <template #content="{ close }">
-            <dt-mode-island mode="dark" class="d-p16 d-bgc-secondary">
+            <div v-dt-mode:dark class="d-p16 d-bgc-secondary">
               <dt-text as="p">This Popover's content is in explicit <dt-text strength="strong">dark</dt-text> mode.</dt-text>
-            </dt-mode-island>
+            </div>
           </template>
         </dt-popover>
       </dt-stack>
@@ -542,7 +600,7 @@ showHtmlWarning />
             </dt-button>
           </template>
           <template #list="{ close }">
-            <dt-mode-island class="d-bgc-secondary d-p4">
+            <div v-dt-mode class="d-bgc-secondary d-p4">
               <dt-list-item
                 v-for="item in items"
                 :key="item.id"
@@ -552,7 +610,7 @@ showHtmlWarning />
               >
                 {{ item.name }}
               </dt-list-item>
-            </dt-mode-island>
+            </div>
           </template>
         </dt-dropdown>
         <dt-dropdown navigation-type="arrow-keys" placement="bottom-start" listClass="d-m0" padding="small">
@@ -565,7 +623,7 @@ showHtmlWarning />
             </dt-button>
           </template>
           <template #list="{ close }">
-            <dt-mode-island mode="light" class="d-bgc-secondary d-p4">
+            <div v-dt-mode:light class="d-bgc-secondary d-p4">
               <dt-list-item
                 v-for="item in items"
                 :key="item.id"
@@ -575,7 +633,7 @@ showHtmlWarning />
               >
                 {{ item.name }}
               </dt-list-item>
-            </dt-mode-island>
+            </div>
           </template>
         </dt-dropdown>
         <dt-dropdown navigation-type="arrow-keys" placement="bottom-start" listClass="d-m0" padding="small">
@@ -588,7 +646,7 @@ showHtmlWarning />
             </dt-button>
           </template>
           <template #list="{ close }">
-            <dt-mode-island mode="dark" class="d-bgc-secondary d-p4">
+            <div v-dt-mode:dark class="d-bgc-secondary d-p4">
               <dt-list-item
                 v-for="item in items"
                 :key="item.id"
@@ -598,7 +656,7 @@ showHtmlWarning />
               >
                 {{ item.name }}
               </dt-list-item>
-            </dt-mode-island>
+            </div>
           </template>
         </dt-dropdown>
       </dt-stack>
@@ -614,9 +672,9 @@ vueCode='
     <dt-button size="sm" kind="muted" importance="outlined">Inverted</dt-button>
   </template>
   <template #content>
-    <dt-mode-island class="d-p16 d-bgc-secondary">
+    <div v-dt-mode class="d-p16 d-bgc-secondary">
       <ExampleProfileCard />
-    </dt-mode-island>
+    </div>
   </template>
 </dt-hovercard>
 <!-- Popover -->
@@ -625,9 +683,9 @@ vueCode='
     <dt-button size="sm" kind="muted" importance="outlined">Inverted</dt-button>
   </template>
   <template #content="{ close }">
-    <dt-mode-island mode="inverted" class="d-p16 d-bgc-secondary">
+    <div v-dt-mode class="d-p16 d-bgc-secondary">
       <dt-text as="p">This Popover content is in the <dt-text strength="strong">inverted</dt-text> mode.</dt-text>
-    </dt-mode-island>
+    </div>
   </template>
 </dt-popover>
 <!-- Dropdown -->
@@ -641,7 +699,7 @@ vueCode='
     </dt-button>
   </template>
   <template #list="{ close }">
-    <dt-mode-island class="d-bgc-secondary d-p4">
+    <div v-dt-mode class="d-bgc-secondary d-p4">
       <dt-list-item
         v-for="item in items"
         :key="item.id"
@@ -650,14 +708,56 @@ vueCode='
       >
         {{ item.name }}
       </dt-list-item>
-    </dt-mode-island>
+    </div>
   </template>
 </dt-dropdown>
 '
 />
 
+## Component
+
+The `<dt-mode-island>` component is the underlying abstraction that the directive builds on. It creates a wrapper element, sets `data-dt-mode` and `data-dt-contrast`, and applies the `d-mode-island` CSS class (which sets `color` and `background-color` from tokens).
+
+Use the component when no container element exists and you need one created for you.
+
+<code-example-tabs
+vueCode='
+<dt-mode-island>
+  Inverted (default)
+</dt-mode-island>
+<dt-mode-island mode="light">
+  Light
+</dt-mode-island>
+<dt-mode-island mode="dark">
+  Dark
+</dt-mode-island>
+<dt-mode-island as="section" mode="dark">
+  Rendered as a section element
+</dt-mode-island>
+'
+/>
+
+### When to use which
+
+| Scenario | Use |
+|----------|-----|
+| You already have a container element (`section`, `nav`, `div`, etc.) | `v-dt-mode` directive |
+| No container exists, you need a wrapper created | `<dt-mode-island>` component |
+| Inside slot content (popovers, dropdowns) | Either — directive preferred if a container element exists |
+
+Both set `data-dt-mode` on their element and are fully interoperable when nested.
+
 ## Vue API
 
+### Directive
+
+```js
+import { DtModeDirective } from '@dialpad/dialtone-vue';
+app.use(DtModeDirective);
+```
+
+### Component
+
 <component-vue-api component-name="modeisland" />
 
 ## Accessibility
@@ -678,6 +778,8 @@ const {
   setContrast,
 } = useThemeManager({ includeThemes: false });
 
+const dynamicMode = ref('invert');
+
 const items = ref([
   { id: '1', name: 'Option 1' },
   { id: '2', name: 'Option 2' },
diff --git a/apps/dialtone-documentation/docs/guides/theme-and-mode/index.md b/apps/dialtone-documentation/docs/guides/theme-and-mode/index.md
index 5e0f1f24b3..558493191b 100644
--- a/apps/dialtone-documentation/docs/guides/theme-and-mode/index.md
+++ b/apps/dialtone-documentation/docs/guides/theme-and-mode/index.md
@@ -179,11 +179,18 @@ Switch themes by changing the brand CSS import and updating the `data-dt-brand`
 
 ### Mode Sections
 
-You can create sections with different modes using the [Mode Island component](/components/mode-island.html). This is useful for:
+Use the `v-dt-mode` directive to create sections with different modes within a page.
+Apply it to any existing element — no wrapper needed:
 
-- Dark mode previews within light mode pages
-- Code examples showing both modes
-- Mixed-mode UI sections
+```html
+<section v-dt-mode:dark>
+  Dark mode content
+</section>
+```
+
+When no container element exists, the [Mode Island component](/components/mode-island.html)
+creates one for you. See the [Mode Island page](/components/mode-island.html) for full
+documentation on both approaches.
 
 ### Micro-frontends (Separate Bundles)
 
diff --git a/packages/dialtone-css/lib/build/less/components/mode-island.less b/packages/dialtone-css/lib/build/less/components/mode-island.less
index 7db98777c9..162f50d2b4 100644
--- a/packages/dialtone-css/lib/build/less/components/mode-island.less
+++ b/packages/dialtone-css/lib/build/less/components/mode-island.less
@@ -1,6 +1,9 @@
 @layer dialtone.components {
-.d-mode-island {
+[data-dt-mode] {
   color: var(--dt-color-foreground-primary);
+}
+
+.d-mode-island {
   background-color: var(--dt-color-surface-primary);
 }
 }
diff --git a/packages/dialtone-vue/directives/mode_directive/index.js b/packages/dialtone-vue/directives/mode_directive/index.js
new file mode 100644
index 0000000000..b3260306cb
--- /dev/null
+++ b/packages/dialtone-vue/directives/mode_directive/index.js
@@ -0,0 +1 @@
+export { default as DtModeDirective } from './mode.js';
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.js b/packages/dialtone-vue/directives/mode_directive/mode.js
new file mode 100644
index 0000000000..4350af269b
--- /dev/null
+++ b/packages/dialtone-vue/directives/mode_directive/mode.js
@@ -0,0 +1,117 @@
+import {
+  getOppositeMode,
+  getRootContrast,
+  findParentMode,
+} from '@/components/mode_island/utils';
+
+const VALID_MODES = ['light', 'dark', 'invert'];
+
+export const DtModeDirective = {
+  name: 'dt-mode-directive',
+  install (app) {
+    const instances = new WeakMap();
+
+    app.directive('dt-mode', {
+      mounted (el, binding) {
+        const mode = resolveArg(binding.arg);
+        const state = applyMode(el, mode);
+        instances.set(el, state);
+      },
+
+      updated (el, binding) {
+        if (binding.arg !== binding.oldArg) {
+          cleanup(instances.get(el));
+          const mode = resolveArg(binding.arg);
+          const state = applyMode(el, mode);
+          instances.set(el, state);
+        }
+      },
+
+      unmounted (el) {
+        cleanup(instances.get(el));
+        instances.delete(el);
+      },
+    });
+
+    function resolveArg (arg) {
+      if (!arg) return 'invert';
+      if (VALID_MODES.includes(arg)) return arg;
+      console.warn(
+        `[DtModeDirective] Invalid mode "${arg}". Valid modes: ${VALID_MODES.join(', ')}. Falling back to "invert".`,
+      );
+      return 'invert';
+    }
+
+    function applyMode (el, mode) {
+      const state = {
+        contrastObserver: null,
+        modeObserver: null,
+      };
+
+      // Set contrast from root
+      el.setAttribute('data-dt-contrast', getRootContrast());
+
+      // Watch for contrast changes on root
+      state.contrastObserver = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          if (mutation.type === 'attributes' && mutation.attributeName === 'data-dt-contrast') {
+            el.setAttribute('data-dt-contrast', getRootContrast());
+          }
+        }
+      });
+      state.contrastObserver.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ['data-dt-contrast'],
+      });
+
+      if (mode === 'light' || mode === 'dark') {
+        el.setAttribute('data-dt-mode', mode);
+      } else {
+        // invert mode
+        const parentMode = findParentMode(el);
+        el.setAttribute('data-dt-mode', getOppositeMode(parentMode));
+
+        // Watch for mode changes on root and ancestors
+        const config = {
+          attributes: true,
+          attributeFilter: ['data-dt-mode'],
+          subtree: false,
+        };
+
+        state.modeObserver = new MutationObserver(() => {
+          const currentParentMode = findParentMode(el);
+          el.setAttribute('data-dt-mode', getOppositeMode(currentParentMode));
+        });
+
+        // Observe root element
+        state.modeObserver.observe(document.documentElement, config);
+
+        // Observe all ancestor elements for data-dt-mode changes.
+        // This includes ancestors that don't yet have the attribute,
+        // because a sibling directive may set it after this one mounts
+        // (Vue 3 fires child mounted before parent mounted).
+        let parent = el.parentElement;
+        while (parent && parent !== document.documentElement) {
+          state.modeObserver.observe(parent, config);
+          parent = parent.parentElement;
+        }
+      }
+
+      return state;
+    }
+
+    function cleanup (state) {
+      if (!state) return;
+      if (state.contrastObserver) {
+        state.contrastObserver.disconnect();
+        state.contrastObserver = null;
+      }
+      if (state.modeObserver) {
+        state.modeObserver.disconnect();
+        state.modeObserver = null;
+      }
+    }
+  },
+};
+
+export default DtModeDirective;
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.mdx b/packages/dialtone-vue/directives/mode_directive/mode.mdx
new file mode 100644
index 0000000000..340bbdd49a
--- /dev/null
+++ b/packages/dialtone-vue/directives/mode_directive/mode.mdx
@@ -0,0 +1,43 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import * as ModeDirectiveStories from './mode.stories.js';
+
+<Meta of={ModeDirectiveStories}/>
+
+# Mode directive
+
+Apply light, dark, or inverted color mode to any element without a wrapper component.
+For full documentation, see the [Mode Island page](/components/mode-island.html).
+
+## Usage
+
+Import the directive from dialtone-vue
+
+```js
+import { DtModeDirective } from "@dialpad/dialtone-vue";
+```
+
+Install the directive into vue instance
+
+```js
+Vue.use(DtModeDirective);
+```
+
+### Explicit modes
+
+```html
+<section v-dt-mode:dark>Dark mode content</section>
+<section v-dt-mode:light>Light mode content</section>
+```
+
+### Invert (default)
+
+```html
+<section v-dt-mode>Inverted from parent or root</section>
+<section v-dt-mode:invert>Same as above, explicit</section>
+```
+
+### Dynamic arg
+
+```html
+<section v-dt-mode:[dynamicMode]>Reactive mode</section>
+```
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.stories.js b/packages/dialtone-vue/directives/mode_directive/mode.stories.js
new file mode 100644
index 0000000000..05267f6a1b
--- /dev/null
+++ b/packages/dialtone-vue/directives/mode_directive/mode.stories.js
@@ -0,0 +1,28 @@
+import { createTemplateFromVueFile } from '@/common/storybook_utils.js';
+import ModeDirectiveDefaultTemplate from './mode_directive_default.story.vue';
+
+export const argsData = {};
+
+export const argTypesData = {};
+
+// Story Collection
+export default {
+  title: 'Directives/Mode',
+  component: ModeDirectiveDefaultTemplate,
+  args: argsData,
+  argTypes: argTypesData,
+  excludeStories: /.*Data$/,
+};
+
+// Templates
+const DefaultTemplate = (args, { argTypes }) =>
+  createTemplateFromVueFile(args, argTypes, ModeDirectiveDefaultTemplate);
+
+// Stories
+export const Default = {
+  render: DefaultTemplate,
+  parameters: {
+    options: { showPanel: false },
+    controls: { disable: true },
+  },
+};
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.test.js b/packages/dialtone-vue/directives/mode_directive/mode.test.js
new file mode 100644
index 0000000000..e636770b21
--- /dev/null
+++ b/packages/dialtone-vue/directives/mode_directive/mode.test.js
@@ -0,0 +1,256 @@
+import { mount } from '@vue/test-utils';
+import { DtModeDirective } from './mode.js';
+import DtModeIsland from '@/components/mode_island/mode_island.vue';
+
+describe('DtModeDirective Tests', () => {
+  let wrapper;
+
+  afterEach(() => {
+    wrapper?.unmount();
+  });
+
+  beforeEach(() => {
+    document.documentElement.setAttribute('data-dt-mode', 'light');
+    document.documentElement.setAttribute('data-dt-contrast', 'default');
+  });
+
+  afterEach(() => {
+    document.documentElement.removeAttribute('data-dt-mode');
+    document.documentElement.removeAttribute('data-dt-contrast');
+  });
+
+  describe('Explicit Mode Tests', () => {
+    it('should set data-dt-mode to light with v-dt-mode:light', () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:light data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('light');
+    });
+
+    it('should set data-dt-mode to dark with v-dt-mode:dark', () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:dark data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+    });
+  });
+
+  describe('Invert Mode Tests', () => {
+    it('should invert root mode when no arg is provided (default)', () => {
+      wrapper = mount({
+        template: '<section v-dt-mode data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      // Root is light, so invert should be dark
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+    });
+
+    it('should invert root mode with explicit :invert arg', () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:invert data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+    });
+
+    it('should invert dark root mode', () => {
+      document.documentElement.setAttribute('data-dt-mode', 'dark');
+
+      wrapper = mount({
+        template: '<section v-dt-mode data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('light');
+    });
+
+    it('should invert nearest parent with data-dt-mode', () => {
+      wrapper = mount({
+        template: `
+          <div data-dt-mode="dark">
+            <section v-dt-mode:invert data-qa="target">Content</section>
+          </div>
+        `,
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('light');
+    });
+  });
+
+  describe('Contrast Tests', () => {
+    it('should set data-dt-contrast from root', () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:dark data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-contrast')).toBe('default');
+    });
+
+    it('should update data-dt-contrast when root changes', async () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:dark data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      document.documentElement.setAttribute('data-dt-contrast', 'high');
+      // Wait for MutationObserver callback
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-contrast')).toBe('high');
+    });
+  });
+
+  describe('Reactive Tests', () => {
+    it('should re-invert when root mode changes', async () => {
+      wrapper = mount({
+        template: '<section v-dt-mode data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+
+      document.documentElement.setAttribute('data-dt-mode', 'dark');
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('light');
+    });
+
+    it('should re-initialize when dynamic arg changes', async () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:[mode] data-qa="target">Content</section>',
+        data () {
+          return { mode: 'dark' };
+        },
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+
+      await wrapper.setData({ mode: 'light' });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('light');
+    });
+  });
+
+  describe('Nesting Tests', () => {
+    it('should read parent mode from DtModeIsland correctly', () => {
+      wrapper = mount({
+        template: `
+          <dt-mode-island mode="dark" data-qa="parent">
+            <section v-dt-mode:invert data-qa="child">Content</section>
+          </dt-mode-island>
+        `,
+        components: { DtModeIsland },
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="parent"]').attributes('data-dt-mode')).toBe('dark');
+      expect(wrapper.find('[data-qa="child"]').attributes('data-dt-mode')).toBe('light');
+    });
+
+    it('should nest directive inside directive correctly', async () => {
+      wrapper = mount({
+        template: `
+          <div v-dt-mode:dark data-qa="outer">
+            <section v-dt-mode:invert data-qa="inner">Content</section>
+          </div>
+        `,
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      // Wait for MutationObserver to propagate (child mounted fires before parent)
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      expect(wrapper.find('[data-qa="outer"]').attributes('data-dt-mode')).toBe('dark');
+      expect(wrapper.find('[data-qa="inner"]').attributes('data-dt-mode')).toBe('light');
+    });
+
+    it('should alternate correctly with triple nesting', async () => {
+      wrapper = mount({
+        template: `
+          <div v-dt-mode:light data-qa="level1">
+            <div v-dt-mode:invert data-qa="level2">
+              <div v-dt-mode:invert data-qa="level3">Content</div>
+            </div>
+          </div>
+        `,
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      // Wait for MutationObserver to propagate through nesting levels
+      await new Promise(resolve => setTimeout(resolve, 10));
+
+      expect(wrapper.find('[data-qa="level1"]').attributes('data-dt-mode')).toBe('light');
+      expect(wrapper.find('[data-qa="level2"]').attributes('data-dt-mode')).toBe('dark');
+      expect(wrapper.find('[data-qa="level3"]').attributes('data-dt-mode')).toBe('light');
+    });
+  });
+
+  describe('Cleanup Tests', () => {
+    it('should disconnect MutationObservers on unmount', () => {
+      const disconnectSpy = vi.spyOn(MutationObserver.prototype, 'disconnect');
+
+      wrapper = mount({
+        template: '<section v-dt-mode data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      wrapper.unmount();
+      expect(disconnectSpy).toHaveBeenCalled();
+      disconnectSpy.mockRestore();
+    });
+  });
+
+  describe('Validation Tests', () => {
+    it('should warn and fall back to invert on invalid arg', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      wrapper = mount({
+        template: '<section v-dt-mode:invalid data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Invalid mode "invalid"'),
+      );
+      // Falls back to invert — root is light, so should be dark
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+      warnSpy.mockRestore();
+    });
+  });
+
+  describe('Class Tests', () => {
+    it('should NOT auto-add d-mode-island class', () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:dark data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').classes()).not.toContain('d-mode-island');
+    });
+  });
+});
diff --git a/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue b/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
new file mode 100644
index 0000000000..d6d30dba01
--- /dev/null
+++ b/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
@@ -0,0 +1,186 @@
+<template>
+  <dt-stack
+    gap="600"
+    class="d-m64"
+  >
+    <dt-text
+      as="h3"
+      kind="headline"
+      size="sm"
+    >
+      Explicit modes
+    </dt-text>
+    <dt-stack
+      gap="400"
+      direction="row"
+    >
+      <section
+        v-dt-mode:light
+        class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+      >
+        <dt-stack gap="400">
+          <dt-text
+            kind="body"
+            tone="primary"
+          >
+            Light mode (v-dt-mode:light)
+          </dt-text>
+          <dt-stack
+            gap="400"
+            direction="row"
+          >
+            <span class="d-fc-primary">Primary</span>
+            <span class="d-fc-tertiary">Tertiary</span>
+            <span class="d-fc-success">Success</span>
+            <span class="d-fc-critical">Critical</span>
+          </dt-stack>
+        </dt-stack>
+      </section>
+      <section
+        v-dt-mode:dark
+        class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+      >
+        <dt-stack gap="400">
+          <dt-text
+            kind="body"
+            tone="primary"
+          >
+            Dark mode (v-dt-mode:dark)
+          </dt-text>
+          <dt-stack
+            gap="400"
+            direction="row"
+          >
+            <span class="d-fc-primary">Primary</span>
+            <span class="d-fc-tertiary">Tertiary</span>
+            <span class="d-fc-success">Success</span>
+            <span class="d-fc-critical">Critical</span>
+          </dt-stack>
+        </dt-stack>
+      </section>
+    </dt-stack>
+
+    <dt-text
+      as="h3"
+      kind="headline"
+      size="sm"
+    >
+      Invert mode (default)
+    </dt-text>
+    <section
+      v-dt-mode
+      class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+    >
+      <dt-text
+        kind="body"
+        tone="primary"
+      >
+        Inverted from root (v-dt-mode)
+      </dt-text>
+    </section>
+
+    <dt-text
+      as="h3"
+      kind="headline"
+      size="sm"
+    >
+      Nested directives
+    </dt-text>
+    <div
+      v-dt-mode:dark
+      class="d-p16 d-ba d-bc-subtle d-bar8"
+    >
+      <dt-stack gap="400">
+        <dt-text
+          kind="body"
+          tone="primary"
+        >
+          Dark (outer)
+        </dt-text>
+        <div
+          v-dt-mode:invert
+          class="d-p16 d-ba d-bc-subtle d-bar8"
+        >
+          <dt-stack gap="400">
+            <dt-text
+              kind="body"
+              tone="primary"
+            >
+              Light — inverted from dark (inner)
+            </dt-text>
+            <div
+              v-dt-mode:invert
+              class="d-p16 d-ba d-bc-subtle d-bar8"
+            >
+              <dt-text
+                kind="body"
+                tone="primary"
+              >
+                Dark — inverted again (deepest)
+              </dt-text>
+            </div>
+          </dt-stack>
+        </div>
+      </dt-stack>
+    </div>
+
+    <dt-text
+      as="h3"
+      kind="headline"
+      size="sm"
+    >
+      Dynamic arg
+    </dt-text>
+    <dt-stack
+      gap="400"
+      direction="row"
+      class="d-ai-center"
+    >
+      <label
+        for="mode-select"
+        class="d-label"
+      >Mode</label>
+      <select
+        id="mode-select"
+        v-model="dynamicMode"
+        class="d-select d-w128"
+      >
+        <option value="light">
+          light
+        </option>
+        <option value="dark">
+          dark
+        </option>
+        <option value="invert">
+          invert
+        </option>
+      </select>
+      <section
+        v-dt-mode:[dynamicMode]
+        class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+      >
+        <dt-text
+          kind="body"
+          tone="primary"
+        >
+          v-dt-mode:{{ dynamicMode }}
+        </dt-text>
+      </section>
+    </dt-stack>
+  </dt-stack>
+</template>
+
+<script>
+import DtStack from '@/components/stack/stack.vue';
+import DtText from '@/components/text/text.vue';
+
+export default {
+  name: 'DtModeDirectiveDefault',
+  components: { DtStack, DtText },
+  data () {
+    return {
+      dynamicMode: 'invert',
+    };
+  },
+};
+</script>
diff --git a/packages/dialtone-vue/index.js b/packages/dialtone-vue/index.js
index f635be3983..9b21a9ee44 100644
--- a/packages/dialtone-vue/index.js
+++ b/packages/dialtone-vue/index.js
@@ -67,6 +67,7 @@ export * from './components/validation_messages';
 // Directives
 export * from './directives/tooltip_directive';
 export * from './directives/scrollbar_directive';
+export * from './directives/mode_directive';
 
 /// Recipes
 export * from './recipes/buttons/callbar_button';

From 5ce421b2e8a16e8862eb933ca79fc9c165ecfb3a Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 22:01:55 -0600
Subject: [PATCH 19/47] simplify contrast observer mutation handler

---
 packages/dialtone-vue/directives/mode_directive/mode.js | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode.js b/packages/dialtone-vue/directives/mode_directive/mode.js
index 4350af269b..93593dd9c4 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.js
@@ -52,12 +52,8 @@ export const DtModeDirective = {
       el.setAttribute('data-dt-contrast', getRootContrast());
 
       // Watch for contrast changes on root
-      state.contrastObserver = new MutationObserver((mutations) => {
-        for (const mutation of mutations) {
-          if (mutation.type === 'attributes' && mutation.attributeName === 'data-dt-contrast') {
-            el.setAttribute('data-dt-contrast', getRootContrast());
-          }
-        }
+      state.contrastObserver = new MutationObserver(() => {
+        el.setAttribute('data-dt-contrast', getRootContrast());
       });
       state.contrastObserver.observe(document.documentElement, {
         attributes: true,

From c664485835d6755fb187d664edab3763bc88b190 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 22:02:12 -0600
Subject: [PATCH 20/47] consolidate afterEach hooks in mode directive tests

---
 packages/dialtone-vue/directives/mode_directive/mode.test.js | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode.test.js b/packages/dialtone-vue/directives/mode_directive/mode.test.js
index e636770b21..da487beb6a 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.test.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.test.js
@@ -5,16 +5,13 @@ import DtModeIsland from '@/components/mode_island/mode_island.vue';
 describe('DtModeDirective Tests', () => {
   let wrapper;
 
-  afterEach(() => {
-    wrapper?.unmount();
-  });
-
   beforeEach(() => {
     document.documentElement.setAttribute('data-dt-mode', 'light');
     document.documentElement.setAttribute('data-dt-contrast', 'default');
   });
 
   afterEach(() => {
+    wrapper?.unmount();
     document.documentElement.removeAttribute('data-dt-mode');
     document.documentElement.removeAttribute('data-dt-contrast');
   });

From 1be8f3d3e7214d5bef93ff02bc71a4ab93272d58 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 22:27:33 -0600
Subject: [PATCH 21/47] update mode directive story with visual polish and
 select menu

---
 packages/dialtone-vue/.storybook/preview.jsx  |  2 +
 .../components/mode_island/mode_island.mdx    |  9 ---
 .../directives/mode_directive/mode.mdx        | 38 +----------
 .../mode_directive_default.story.vue          | 68 ++++++++-----------
 4 files changed, 33 insertions(+), 84 deletions(-)
 delete mode 100644 packages/dialtone-vue/components/mode_island/mode_island.mdx

diff --git a/packages/dialtone-vue/.storybook/preview.jsx b/packages/dialtone-vue/.storybook/preview.jsx
index c499eaf7b8..f98a46cd26 100644
--- a/packages/dialtone-vue/.storybook/preview.jsx
+++ b/packages/dialtone-vue/.storybook/preview.jsx
@@ -48,6 +48,7 @@ import { dialtoneDarkTheme, dialtoneLightTheme } from './dialtone-themes.js';
 import { DialtoneDocsPage } from './DialtoneDocsPage.jsx';
 import { DtTooltipDirective } from '@/directives/tooltip_directive';
 import { DtScrollbarDirective } from '@/directives/scrollbar_directive';
+import { DtModeDirective } from '@/directives/mode_directive';
 import { DtStack } from '@/components/stack';
 import { faker } from '@faker-js/faker';
 
@@ -133,6 +134,7 @@ setup((app) => {
   app.use(fixDefaultSlot);
   app.use(DtTooltipDirective);
   app.use(DtScrollbarDirective);
+  app.use(DtModeDirective);
   app.component('DtStack', DtStack);
   // global seed, to make sure results are reproducible on percy and don't change on every reload too.
   faker.seed(6687422389464139);
diff --git a/packages/dialtone-vue/components/mode_island/mode_island.mdx b/packages/dialtone-vue/components/mode_island/mode_island.mdx
deleted file mode 100644
index 04d3edda6e..0000000000
--- a/packages/dialtone-vue/components/mode_island/mode_island.mdx
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Meta } from '@storybook/addon-docs/blocks';
-import * as ModeIslandStories from './mode_island.stories';
-import RedirectToDocs from "@/common/snippets/redirect-to-docs.mdx"
-
-<Meta of={ModeIslandStories}/>
-
-# Mode Island
-
-<RedirectToDocs name="mode-island" />
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.mdx b/packages/dialtone-vue/directives/mode_directive/mode.mdx
index 340bbdd49a..2f9490b17c 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.mdx
+++ b/packages/dialtone-vue/directives/mode_directive/mode.mdx
@@ -1,43 +1,9 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 import * as ModeDirectiveStories from './mode.stories.js';
+import RedirectToDocs from "@/common/snippets/redirect-to-docs.mdx"
 
 <Meta of={ModeDirectiveStories}/>
 
 # Mode directive
 
-Apply light, dark, or inverted color mode to any element without a wrapper component.
-For full documentation, see the [Mode Island page](/components/mode-island.html).
-
-## Usage
-
-Import the directive from dialtone-vue
-
-```js
-import { DtModeDirective } from "@dialpad/dialtone-vue";
-```
-
-Install the directive into vue instance
-
-```js
-Vue.use(DtModeDirective);
-```
-
-### Explicit modes
-
-```html
-<section v-dt-mode:dark>Dark mode content</section>
-<section v-dt-mode:light>Light mode content</section>
-```
-
-### Invert (default)
-
-```html
-<section v-dt-mode>Inverted from parent or root</section>
-<section v-dt-mode:invert>Same as above, explicit</section>
-```
-
-### Dynamic arg
-
-```html
-<section v-dt-mode:[dynamicMode]>Reactive mode</section>
-```
+<RedirectToDocs name="mode-island" />
diff --git a/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue b/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
index d6d30dba01..533b67afcf 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
+++ b/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
@@ -1,22 +1,22 @@
 <template>
   <dt-stack
-    gap="600"
-    class="d-m64"
+    gap="500"
+    class="d-p8"
   >
     <dt-text
       as="h3"
       kind="headline"
-      size="sm"
+      size="lg"
     >
       Explicit modes
     </dt-text>
     <dt-stack
-      gap="400"
+      gap="500"
       direction="row"
     >
       <section
         v-dt-mode:light
-        class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+        class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8 d-fl1"
       >
         <dt-stack gap="400">
           <dt-text
@@ -38,7 +38,7 @@
       </section>
       <section
         v-dt-mode:dark
-        class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+        class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8 d-fl1"
       >
         <dt-stack gap="400">
           <dt-text
@@ -63,13 +63,13 @@
     <dt-text
       as="h3"
       kind="headline"
-      size="sm"
+      size="lg"
     >
       Invert mode (default)
     </dt-text>
     <section
       v-dt-mode
-      class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+      class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8 d-w264"
     >
       <dt-text
         kind="body"
@@ -82,13 +82,13 @@
     <dt-text
       as="h3"
       kind="headline"
-      size="sm"
+      size="lg"
     >
       Nested directives
     </dt-text>
     <div
       v-dt-mode:dark
-      class="d-p16 d-ba d-bc-subtle d-bar8"
+      class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8"
     >
       <dt-stack gap="400">
         <dt-text
@@ -99,7 +99,7 @@
         </dt-text>
         <div
           v-dt-mode:invert
-          class="d-p16 d-ba d-bc-subtle d-bar8"
+          class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8"
         >
           <dt-stack gap="400">
             <dt-text
@@ -110,7 +110,7 @@
             </dt-text>
             <div
               v-dt-mode:invert
-              class="d-p16 d-ba d-bc-subtle d-bar8"
+              class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8"
             >
               <dt-text
                 kind="body"
@@ -127,37 +127,21 @@
     <dt-text
       as="h3"
       kind="headline"
-      size="sm"
+      size="lg"
     >
       Dynamic arg
     </dt-text>
-    <dt-stack
-      gap="400"
-      direction="row"
-      class="d-ai-center"
-    >
-      <label
-        for="mode-select"
-        class="d-label"
-      >Mode</label>
-      <select
-        id="mode-select"
-        v-model="dynamicMode"
-        class="d-select d-w128"
-      >
-        <option value="light">
-          light
-        </option>
-        <option value="dark">
-          dark
-        </option>
-        <option value="invert">
-          invert
-        </option>
-      </select>
+    <dt-stack gap="400">
+      <span class="d-w128">
+        <dt-select-menu
+          v-model="dynamicMode"
+          label="Mode"
+          :options="modeOptions"
+        />
+      </span>
       <section
         v-dt-mode:[dynamicMode]
-        class="d-p16 d-ba d-bc-subtle d-bar8 d-w264"
+        class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8 d-w264"
       >
         <dt-text
           kind="body"
@@ -173,13 +157,19 @@
 <script>
 import DtStack from '@/components/stack/stack.vue';
 import DtText from '@/components/text/text.vue';
+import DtSelectMenu from '@/components/select_menu/select_menu.vue';
 
 export default {
   name: 'DtModeDirectiveDefault',
-  components: { DtStack, DtText },
+  components: { DtStack, DtText, DtSelectMenu },
   data () {
     return {
       dynamicMode: 'invert',
+      modeOptions: [
+        { value: 'invert', label: 'invert' },
+        { value: 'light', label: 'light' },
+        { value: 'dark', label: 'dark' },
+      ],
     };
   },
 };

From 4f823c5db9f45563514fa576f98c1894a0f35f2e Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 22:30:59 -0600
Subject: [PATCH 22/47] expand mode directive documentation with usage examples
 and api reference

---
 .../directives/mode_directive/mode.mdx        | 86 ++++++++++++++++++-
 1 file changed, 84 insertions(+), 2 deletions(-)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode.mdx b/packages/dialtone-vue/directives/mode_directive/mode.mdx
index 2f9490b17c..78c7adaf78 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.mdx
+++ b/packages/dialtone-vue/directives/mode_directive/mode.mdx
@@ -1,9 +1,91 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 import * as ModeDirectiveStories from './mode.stories.js';
-import RedirectToDocs from "@/common/snippets/redirect-to-docs.mdx"
 
 <Meta of={ModeDirectiveStories}/>
 
 # Mode directive
 
-<RedirectToDocs name="mode-island" />
+Apply light, dark, or inverted color mode to any element. Sets `data-dt-mode` and
+`data-dt-contrast` on the bound element, scoping descendant token-based styles
+(`d-fc-primary`, `d-bgc-secondary`, etc.) to the specified mode.
+
+For full documentation, see the [Mode Island page](https://dialtone.dialpad.com/components/mode-island.html).
+
+## Usage
+
+Import the directive from dialtone-vue
+
+```js
+import { DtModeDirective } from "@dialpad/dialtone-vue";
+```
+
+Install the directive into vue instance
+
+```js
+app.use(DtModeDirective);
+```
+
+### Explicit modes
+
+```html
+<section v-dt-mode:dark>Dark mode content</section>
+<section v-dt-mode:light>Light mode content</section>
+```
+
+### Invert (default)
+
+When no arg is provided, the directive inverts the nearest parent mode boundary (or the root).
+
+```html
+<section v-dt-mode>Inverted from parent or root</section>
+<section v-dt-mode:invert>Same as above, explicit</section>
+```
+
+### Dynamic arg
+
+Bind a reactive variable to switch modes at runtime.
+
+```html
+<section v-dt-mode:[dynamicMode]>Reactive mode</section>
+```
+
+## Args
+
+<table>
+  <thead>
+    <tr>
+      <th>Arg</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>dark</code></td>
+      <td>Explicitly set dark mode</td>
+    </tr>
+    <tr>
+      <td><code>light</code></td>
+      <td>Explicitly set light mode</td>
+    </tr>
+    <tr>
+      <td><code>invert</code></td>
+      <td>Invert the nearest parent or root mode</td>
+    </tr>
+    <tr>
+      <td><em>(none)</em></td>
+      <td>Default — same as <code>invert</code></td>
+    </tr>
+    <tr>
+      <td><code>[dynamic]</code></td>
+      <td>Reactive — re-evaluates when the bound value changes</td>
+    </tr>
+  </tbody>
+</table>
+
+## Behavior
+
+- Sets `data-dt-mode` (`light` or `dark`) on the element
+- Sets `data-dt-contrast` inherited from root `<html>` element
+- For `invert`, watches ancestor mode changes via MutationObserver and reacts automatically
+- Does **not** add the `d-mode-island` CSS class or set `background-color`
+- Interoperable with `<dt-mode-island>` — nesting either inside the other works naturally

From e42e920a13a9cfd3c721f85619899e87c7b4841f Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 22:58:58 -0600
Subject: [PATCH 23/47] .

---
 apps/dialtone-documentation/docs/components/mode-island.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/dialtone-documentation/docs/components/mode-island.md b/apps/dialtone-documentation/docs/components/mode-island.md
index 4f7551a864..2ae759f6b7 100644
--- a/apps/dialtone-documentation/docs/components/mode-island.md
+++ b/apps/dialtone-documentation/docs/components/mode-island.md
@@ -219,6 +219,7 @@ Bind a reactive variable as the directive arg to switch modes at runtime.
     <dt-stack gap="400" direction="row">
       <dt-button
         kind="muted"
+        size="sm"
         importance="outlined"
         :active="dynamicMode === 'invert'"
         @click="dynamicMode = 'invert'"
@@ -230,6 +231,7 @@ Bind a reactive variable as the directive arg to switch modes at runtime.
       </dt-button>
       <dt-button
         kind="muted"
+        size="sm"
         importance="outlined"
         :active="dynamicMode === 'light'"
         @click="dynamicMode = 'light'"
@@ -241,6 +243,7 @@ Bind a reactive variable as the directive arg to switch modes at runtime.
       </dt-button>
       <dt-button
         kind="muted"
+        size="sm"
         importance="outlined"
         :active="dynamicMode === 'dark'"
         @click="dynamicMode = 'dark'"

From aac35946fbd301b822cd0aa3c27b52062338934a Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 23:58:47 -0600
Subject: [PATCH 24/47] update inverted prop deprecation notices to recommend
 v-dt-mode directive over DtModeIsland

---
 .../docs/components/breadcrumbs.md            |  19 ++-
 .../docs/components/button.md                 | 159 +++---------------
 .../docs/components/keyboard-shortcut.md      |  17 +-
 .../docs/components/link.md                   |  29 ++--
 .../docs/components/table.md                  |  14 +-
 .../docs/components/tabs.md                   |  26 +--
 .../docs/components/tooltip.md                |   4 +
 .../docs/utilities/backgrounds/color.md       |   4 +
 .../docs/utilities/borders/color.md           |   4 +
 .../docs/utilities/typography/font-color.md   |   4 +
 10 files changed, 93 insertions(+), 187 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/breadcrumbs.md b/apps/dialtone-documentation/docs/components/breadcrumbs.md
index e9182cbb9a..29b1884bbc 100644
--- a/apps/dialtone-documentation/docs/components/breadcrumbs.md
+++ b/apps/dialtone-documentation/docs/components/breadcrumbs.md
@@ -72,30 +72,35 @@ showHtmlWarning />
 ### Inverted
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated. Use the
+  <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
+  instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
+  when no natural container element exists.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> on the component element.
 
 <code-well-header>
-  <dt-mode-island class="d-p16 d-bar8">
+  <div class="d-bgc-contrast">
     <dt-breadcrumbs
+      v-dt-mode:invert
       ref="invertedBreadcrumbsExample"
+      class="d-p16 d-bar8"
       :breadcrumbs="[
         { href: '#', label: 'Root' },
         { href: '#', label: 'Section' },
         { href: '#', label: 'Current Page', selected: true },
       ]"
     />
-  </dt-mode-island>
+  </div>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.invertedBreadcrumbsExample'
 vueCode='
-<dt-mode-island>
-  <dt-breadcrumbs :breadcrumbs="breadcrumbs" />
-</dt-mode-island>
+<div class="d-bgc-contrast">
+  <dt-breadcrumbs v-dt-mode:invert :breadcrumbs="breadcrumbs" />
+</div>
 '
 showHtmlWarning />
 
diff --git a/apps/dialtone-documentation/docs/components/button.md b/apps/dialtone-documentation/docs/components/button.md
index a4cf2c9e77..760474f2c8 100644
--- a/apps/dialtone-documentation/docs/components/button.md
+++ b/apps/dialtone-documentation/docs/components/button.md
@@ -231,7 +231,6 @@ Buttons can be set to active state using the `active` prop or `.d-btn--active` D
     <dt-button active>Place Call</dt-button>
     <dt-button kind="danger" importance="clear" active>Place Call</dt-button>
     <dt-button kind="positive" importance="clear" active>Place Call</dt-button>
-    <dt-button kind="inverted" active>Place Call</dt-button>
     <dt-button kind="muted" active>Place Call</dt-button>
   </dt-stack>
 </code-well-header>
@@ -243,7 +242,6 @@ vueCode='
 <dt-button active>Place Call</dt-button>
 <dt-button kind="danger" importance="clear" active>Place Call</dt-button>
 <dt-button kind="positive" importance="clear" active>Place Call</dt-button>
-<dt-button kind="inverted" active>Place Call</dt-button>
 <dt-button kind="muted" active>Place Call</dt-button>
 '
 showHtmlWarning />
@@ -317,6 +315,29 @@ vueCode='
 '
 showHtmlWarning />
 
+### Inverted
+
+<dt-notice
+  title="Deprecated"
+  kind="error"
+  class="d-wmx100p d-my16"
+>
+  <code>kind="inverted"</code> has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link> when no natural container element exists.
+</dt-notice>
+
+In place of <code>kind="inverted"</code>, use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> on the component element.
+
+<code-well-header>
+  <dt-button v-dt-mode:invert>Place Call</dt-button>
+</code-well-header>
+
+<code-example-tabs
+:htmlCode='() => $refs.modeIslandExample'
+vueCode='
+<dt-button v-dt-mode:invert {props}>Place Call</dt-button>
+'
+showHtmlWarning />
+
 ## Navigation
 
 DtButton can render as an `<a>` or `<router-link>` for cases where you need button styling with navigation behavior.
@@ -432,40 +453,6 @@ vueCode='
 '
 />
 
-### Inverted
-
-<dt-notice
-  title="Deprecated"
-  kind="error"
-  class="d-wmx100p d-my16"
->
-  <code>kind="inverted"</code> has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
-</dt-notice>
-
-In place of <code>kind="inverted"</code>, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
-
-<code-well-header>
-  <dt-split-button
-    end-tooltip-text="More calling options"
-  >
-    Place call
-    <template #dropdownList>
-      <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 1 </dt-list-item>
-      <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 2 </dt-list-item>
-      <dt-list-item role="menuitem" navigation-type="arrow-keys"> Option 3 </dt-list-item>
-    </template>
-  </dt-split-button>
-</code-well-header>
-
-<code-example-tabs
-:htmlCode='() => $refs.modeIslandExample'
-vueCode='
-<dt-mode-island>
-  <dt-button {props}>Place Call</dt-button>
-</dt-mode-island>
-'
-showHtmlWarning />
-
 ## Sizes
 
 The default button size is `md`, but does not need to be explicitly specified.
@@ -744,32 +731,6 @@ Icon-only buttons are commonly used for toggling actions, navigation, or closing
         </template>
       </dt-button>
     </dt-stack>
-    <dt-stack direction="row" gap="400" class="d-bgc-contrast d-p8">
-      <dt-button v-dt-tooltip="`Tooltip`" kind="inverted" importance="clear">
-        <template #startIcon="{ iconSize }">
-          <dt-icon
-            name="phone"
-            :size="iconSize"
-          />
-        </template>
-      </dt-button>
-      <dt-button v-dt-tooltip="`Tooltip`" kind="inverted" importance="outlined">
-        <template #startIcon="{ iconSize }">
-          <dt-icon
-            name="phone"
-            :size="iconSize"
-          />
-        </template>
-      </dt-button>
-      <dt-button v-dt-tooltip="`Tooltip`" kind="inverted">
-        <template #startIcon="{ iconSize }">
-          <dt-icon
-            name="phone"
-            :size="iconSize"
-          />
-        </template>
-      </dt-button>
-    </dt-stack>
   </dt-stack>
 </code-well-header>
 
@@ -864,30 +825,6 @@ vueCode='
     />
   </template>
 </dt-button>
-<dt-button v-dt-tooltip="`Tooltip`" kind="inverted" importance="clear">
-  <template #startIcon="{ iconSize }">
-    <dt-icon
-      name="phone"
-      :size="iconSize"
-    />
-  </template>
-</dt-button>
-<dt-button v-dt-tooltip="`Tooltip`" kind="inverted" importance="outlined">
-  <template #startIcon="{ iconSize }">
-    <dt-icon
-      name="phone"
-      :size="iconSize"
-    />
-  </template>
-</dt-button>
-<dt-button v-dt-tooltip="`Tooltip`" kind="inverted">
-  <template #startIcon="{ iconSize }">
-    <dt-icon
-      name="phone"
-      :size="iconSize"
-    />
-  </template>
-</dt-button>
 '
 showHtmlWarning />
 
@@ -971,32 +908,6 @@ The following styles are available as a circle shape.
         </template>
       </dt-button>
     </dt-stack>
-    <dt-stack direction="row" gap="400" class="d-bgc-contrast d-p8">
-      <dt-button v-dt-tooltip="`Tooltip`" circle kind="inverted" importance="clear">
-        <template #startIcon="{ iconSize }">
-          <dt-icon
-            name="phone"
-            :size="iconSize"
-          />
-        </template>
-      </dt-button>
-      <dt-button v-dt-tooltip="`Tooltip`" circle kind="inverted" importance="outlined">
-        <template #startIcon="{ iconSize }">
-          <dt-icon
-            name="phone"
-            :size="iconSize"
-          />
-        </template>
-      </dt-button>
-      <dt-button v-dt-tooltip="`Tooltip`" circle kind="inverted">
-        <template #startIcon="{ iconSize }">
-          <dt-icon
-            name="phone"
-            :size="iconSize"
-          />
-        </template>
-      </dt-button>
-    </dt-stack>
   </dt-stack>
 </code-well-header>
 
@@ -1067,30 +978,6 @@ vueCode='
     />
   </template>
 </dt-button>
-<dt-button v-dt-tooltip="`Tooltip`" circle kind="inverted" importance="clear">
-  <template #startIcon="{ iconSize }">
-    <dt-icon
-      name="phone"
-      :size="iconSize"
-    />
-  </template>
-</dt-button>
-<dt-button v-dt-tooltip="`Tooltip`" circle kind="inverted" importance="outlined">
-  <template #startIcon="{ iconSize }">
-    <dt-icon
-      name="phone"
-      :size="iconSize"
-    />
-  </template>
-</dt-button>
-<dt-button v-dt-tooltip="`Tooltip`" circle kind="inverted">
-  <template #startIcon="{ iconSize }">
-    <dt-icon
-      name="phone"
-      :size="iconSize"
-    />
-  </template>
-</dt-button>
 '
 showHtmlWarning />
 
diff --git a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
index 48390c23e8..ad100b8fab 100644
--- a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
+++ b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
@@ -40,23 +40,24 @@ vueCode='
 ### Inverted
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated. Use the
+  <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
+  instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
+  when no natural container element exists.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> on the component element.
 
 <code-well-header>
-  <dt-mode-island class="d-p16 d-bar8">
-    <dt-keyboard-shortcut ref="invertedExample" shortcut="{cmd}+Ctrl+X" />
-  </dt-mode-island>
+  <div class="d-bgc-contrast d-p16">
+    <dt-keyboard-shortcut v-dt-mode:invert ref="invertedExample" shortcut="{cmd}+Ctrl+X" />
+  </div>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.invertedExample'
 vueCode='
-<dt-mode-island>
-  <dt-keyboard-shortcut shortcut="{cmd}+Ctrl+X" />
-</dt-mode-island>
+<dt-keyboard-shortcut v-dt-mode:invert shortcut="{cmd}+Ctrl+X" />
 '
 showHtmlWarning />
 
diff --git a/apps/dialtone-documentation/docs/components/link.md b/apps/dialtone-documentation/docs/components/link.md
index 62541cd094..65a86ec494 100644
--- a/apps/dialtone-documentation/docs/components/link.md
+++ b/apps/dialtone-documentation/docs/components/link.md
@@ -95,30 +95,29 @@ showHtmlWarning />
   kind="error"
   class="d-wmx100p d-my16"
 >
-  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated. Use the
+  <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
+  instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
+  when no natural container element exists.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> on the component element.
 
 <code-well-header>
-  <dt-mode-island class="d-p16 d-bar8">
-    <DtStack gap="400" ref="linkInvertedExample">
-      <dt-link href="#link">Base link</dt-link>
-      <dt-link href="#link" kind="danger">Danger link</dt-link>
-      <dt-link href="#link" kind="success">Success link</dt-link>
-      <dt-link href="#link" kind="warning">Warning link</dt-link>
-      <dt-link href="#link" kind="muted">Muted link</dt-link>
-      <dt-link href="#link" kind="mention">Mention link</dt-link>
-    </DtStack>
-  </dt-mode-island>
+  <DtStack gap="400" ref="linkInvertedExample" class="d-bgc-contrast d-p8">
+    <dt-link v-dt-mode:invert href="#link">Base link</dt-link>
+    <dt-link v-dt-mode:invert href="#link" kind="danger">Danger link</dt-link>
+    <dt-link v-dt-mode:invert href="#link" kind="success">Success link</dt-link>
+    <dt-link v-dt-mode:invert href="#link" kind="warning">Warning link</dt-link>
+    <dt-link v-dt-mode:invert href="#link" kind="muted">Muted link</dt-link>
+    <dt-link v-dt-mode:invert href="#link" kind="mention">Mention link</dt-link>
+  </DtStack>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.linkInvertedExample'
 vueCode='
-<dt-mode-island>
-  <dt-link {props}>Link</dt-link>
-</dt-mode-island>
+<dt-link v-dt-mode:invert {props}>Link</dt-link>
 '
 showHtmlWarning />
 
diff --git a/apps/dialtone-documentation/docs/components/table.md b/apps/dialtone-documentation/docs/components/table.md
index 3a19cfa337..742f52aba4 100644
--- a/apps/dialtone-documentation/docs/components/table.md
+++ b/apps/dialtone-documentation/docs/components/table.md
@@ -83,14 +83,14 @@ keywords: ["data table", "grid", "rows", "d-table", "DtTable", "dt-table", "data
 ### Inverted Style
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>d-table--inverted</code> modifier has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
+  The <code>d-table--inverted</code> modifier has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link> when no natural container element exists.
 </dt-notice>
 
-In place of the <code>d-table--inverted</code> modifier, wrap the table in the <dt-link to="mode-island.html">DtModeIsland</dt-link> component.
+In place of the <code>d-table--inverted</code> modifier, use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> on the table element.
 
 <code-well-header>
-  <dt-mode-island class="d-p16 d-bar8">
-    <table class="d-table dialtone-doc-table">
+  <div class="d-p8 d-bgc-contrast">
+    <table v-dt-mode:invert class="d-table dialtone-doc-table d-p16 d-bar8">
       <caption class="d-table__caption">Office List</caption>
       <thead>
         <tr>
@@ -109,13 +109,11 @@ In place of the <code>d-table--inverted</code> modifier, wrap the table in the <
         </tr>
       </tbody>
     </table>
-  </dt-mode-island>
+  </div>
 </code-well-header>
 
 ```html
-<dt-mode-island>
-  <table class="d-table">...</table>
-</dt-mode-island>
+<table v-dt-mode:invert class="d-table">...</table>
 ```
 
 ### Striped
diff --git a/apps/dialtone-documentation/docs/components/tabs.md b/apps/dialtone-documentation/docs/components/tabs.md
index 2b7fd6cb93..129fdc93c1 100644
--- a/apps/dialtone-documentation/docs/components/tabs.md
+++ b/apps/dialtone-documentation/docs/components/tabs.md
@@ -176,28 +176,28 @@ showHtmlWarning />
 ### Inverted
 
 <dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
-  The <code>inverted</code> prop has been deprecated in favor of using <dt-link to="mode-island.html">DtModeIsland</dt-link> as a wrapper.
+  The <code>inverted</code> prop has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link> when no natural container element exists.
 </dt-notice>
 
-In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html">DtModeIsland</dt-link> component as a wrapper.
+In place of the <code>inverted</code> prop, use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> on the component element.
 
 <code-well-header>
-  <dt-mode-island class="d-p16 d-bar8">
-    <example-tabs ref="invertedTabsExample" />
-  </dt-mode-island>
+  <div class="d-p8 d-bgc-contrast d-w100p">
+    <div v-dt-mode:invert class="d-p16 d-bar8">
+      <example-tabs ref="invertedTabsExample" />
+    </div>
+  </div>
 </code-well-header>
 
 <code-example-tabs
 :htmlCode='() => $refs.invertedTabsExample'
 vueCode='
-<dt-mode-island>
-  <dt-tab-group>
-    <template #tabs>
-      <dt-tab id="1" panel-id="2" selected>First</dt-tab>
-      <dt-tab id="3" panel-id="4">Second</dt-tab>
-    </template>
-  </dt-tab-group>
-</dt-mode-island>
+<dt-tab-group v-dt-mode:invert>
+  <template #tabs>
+    <dt-tab id="1" panel-id="2" selected>First</dt-tab>
+    <dt-tab id="3" panel-id="4">Second</dt-tab>
+  </template>
+</dt-tab-group>
 '
 showHtmlWarning />
 
diff --git a/apps/dialtone-documentation/docs/components/tooltip.md b/apps/dialtone-documentation/docs/components/tooltip.md
index d8d041ac40..d6b1d947c2 100644
--- a/apps/dialtone-documentation/docs/components/tooltip.md
+++ b/apps/dialtone-documentation/docs/components/tooltip.md
@@ -135,6 +135,10 @@ showHtmlWarning />
 
 ### Inverted
 
+<dt-notice title="Note" kind="warning" class="d-wmx100p d-my16">
+  The <code>inverted</code> prop is still required for DtTooltip because the tooltip renders outside the normal DOM tree (via Tippy.js). The <code>v-dt-mode</code> directive cannot reach the tooltip shell. See <dt-link href="https://dialpad.atlassian.net/browse/DLT-3077">DLT-3077</dt-link> for follow-up.
+</dt-notice>
+
 <code-well-header bgclass="d-bgc-contrast" class="d-hmn164">
   <dt-tooltip inverted message="tooltip">
     <template #anchor>
diff --git a/apps/dialtone-documentation/docs/utilities/backgrounds/color.md b/apps/dialtone-documentation/docs/utilities/backgrounds/color.md
index c937f41209..e85bc2e42d 100644
--- a/apps/dialtone-documentation/docs/utilities/backgrounds/color.md
+++ b/apps/dialtone-documentation/docs/utilities/backgrounds/color.md
@@ -111,6 +111,10 @@ Use `d-bgo{stop}` to change an element's background color opacity. You can also
 <p class="d-bgc-critical d-bgo0">...</p>
 ```
 
+<dt-notice title="Tip" kind="info" class="d-wmx100p d-my16">
+  Prefer using the <dt-link to="/components/mode-island.html#inverting">v-dt-mode directive</dt-link> with base utility classes instead of <code>-inverted</code> variants. For example, use <code>&lt;div v-dt-mode:invert class="d-bgc-critical"&gt;</code> instead of <code>&lt;div class="d-bgc-critical-inverted"&gt;</code>.
+</dt-notice>
+
 ## Classes
 
 <new-utility-class-table :classes="backgroundColors">
diff --git a/apps/dialtone-documentation/docs/utilities/borders/color.md b/apps/dialtone-documentation/docs/utilities/borders/color.md
index 9532f36c46..04e9b9dac7 100644
--- a/apps/dialtone-documentation/docs/utilities/borders/color.md
+++ b/apps/dialtone-documentation/docs/utilities/borders/color.md
@@ -168,6 +168,10 @@ You can also change the border color opacity value on `:hover`
 </dt-button>
 ```
 
+<dt-notice title="Tip" kind="info" class="d-wmx100p d-my16">
+  Prefer using the <dt-link to="/components/mode-island.html#inverting">v-dt-mode directive</dt-link> with base utility classes instead of <code>-inverted</code> variants. For example, use <code>&lt;div v-dt-mode:invert class="d-bc-critical"&gt;</code> instead of <code>&lt;div class="d-bc-critical-inverted"&gt;</code>.
+</dt-notice>
+
 ## Classes
 
 <new-utility-class-table :classes="borderColors">
diff --git a/apps/dialtone-documentation/docs/utilities/typography/font-color.md b/apps/dialtone-documentation/docs/utilities/typography/font-color.md
index 3d37a3c466..6d183437cc 100644
--- a/apps/dialtone-documentation/docs/utilities/typography/font-color.md
+++ b/apps/dialtone-documentation/docs/utilities/typography/font-color.md
@@ -126,6 +126,10 @@ Use `d-fco{n}` to change an element's text color opacity. You can also change fo
 <p class="d-fc-critical d-fco0">...</p>
 ```
 
+<dt-notice title="Tip" kind="info" class="d-wmx100p d-my16">
+  Prefer using the <dt-link to="/components/mode-island.html#inverting">v-dt-mode directive</dt-link> with base utility classes instead of <code>-inverted</code> variants. For example, use <code>&lt;dt-text v-dt-mode:invert tone="critical"&gt;</code> instead of <code>&lt;dt-text tone="critical-inverted"&gt;</code>.
+</dt-notice>
+
 ## Classes
 
 <new-utility-class-table :classes="fontColors">

From e6cf8daf3285b5b1d880557bf8e35d835b1030ff Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sat, 7 Mar 2026 23:59:01 -0600
Subject: [PATCH 25/47] move mode island styles from components to base layer

---
 .../dialtone-css/lib/build/less/components/mode-island.less    | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/dialtone-css/lib/build/less/components/mode-island.less b/packages/dialtone-css/lib/build/less/components/mode-island.less
index 162f50d2b4..f1f927be83 100644
--- a/packages/dialtone-css/lib/build/less/components/mode-island.less
+++ b/packages/dialtone-css/lib/build/less/components/mode-island.less
@@ -1,4 +1,5 @@
-@layer dialtone.components {
+@layer dialtone.base {
+// intentionally on base layer
 [data-dt-mode] {
   color: var(--dt-color-foreground-primary);
 }

From 82c9c5879a35bfa2ec1b2f1617989b84b61cd07c Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sun, 8 Mar 2026 00:00:05 -0600
Subject: [PATCH 26/47] update inverted prop deprecation notices across
 components to recommend v-dt-mode directive

---
 .../dialtone-vue/components/breadcrumbs/breadcrumb_item.vue     | 2 +-
 packages/dialtone-vue/components/breadcrumbs/breadcrumbs.vue    | 2 +-
 packages/dialtone-vue/components/button/button.vue              | 1 +
 .../components/keyboard_shortcut/keyboard_shortcut.vue          | 2 +-
 packages/dialtone-vue/components/link/link.vue                  | 2 +-
 packages/dialtone-vue/components/tab/tab_group.vue              | 2 +-
 6 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.vue b/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.vue
index 89e7d0402a..fd918fce3b 100644
--- a/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.vue
+++ b/packages/dialtone-vue/components/breadcrumbs/breadcrumb_item.vue
@@ -41,8 +41,8 @@ export default {
 
   props: {
     /**
-     * @ignore
      * Passed through to link. If true, applies inverted styles to the link.
+     * @deprecated Use v-dt-mode directive instead.
      */
     inverted: {
       type: Boolean,
diff --git a/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.vue b/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.vue
index fb4277a0e4..b440f7faf2 100644
--- a/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.vue
+++ b/packages/dialtone-vue/components/breadcrumbs/breadcrumbs.vue
@@ -55,9 +55,9 @@ export default {
     },
 
     /**
-     * @ignore
      * Passed through to link. If true, applies inverted styles to the link.
      * @values true, false
+     * @deprecated Use v-dt-mode directive instead.
      */
     inverted: {
       type: Boolean,
diff --git a/packages/dialtone-vue/components/button/button.vue b/packages/dialtone-vue/components/button/button.vue
index ccbf4d7950..0b36f1d6ad 100644
--- a/packages/dialtone-vue/components/button/button.vue
+++ b/packages/dialtone-vue/components/button/button.vue
@@ -306,6 +306,7 @@ export default {
 
     /**
      * The color of the button.
+     * The inverted value is deprecated — use v-dt-mode directive instead.
      * @values default, unstyled, muted, danger, positive
      */
     kind: {
diff --git a/packages/dialtone-vue/components/keyboard_shortcut/keyboard_shortcut.vue b/packages/dialtone-vue/components/keyboard_shortcut/keyboard_shortcut.vue
index a2ae496ed5..d0fa904df3 100644
--- a/packages/dialtone-vue/components/keyboard_shortcut/keyboard_shortcut.vue
+++ b/packages/dialtone-vue/components/keyboard_shortcut/keyboard_shortcut.vue
@@ -113,9 +113,9 @@ export default {
 
   props: {
     /**
-     * @ignore
      * If true, applies inverted styles.
      * @values true, false
+     * @deprecated Use v-dt-mode directive instead.
      */
     inverted: {
       type: Boolean,
diff --git a/packages/dialtone-vue/components/link/link.vue b/packages/dialtone-vue/components/link/link.vue
index 8ee5c05a7a..ef592c8240 100644
--- a/packages/dialtone-vue/components/link/link.vue
+++ b/packages/dialtone-vue/components/link/link.vue
@@ -40,7 +40,7 @@ export default {
      * Determines whether the link should have inverted styling
      * default is false.
      * @values true, false
-     * @ignore
+     * @deprecated Use v-dt-mode directive instead.
      */
     inverted: {
       type: Boolean,
diff --git a/packages/dialtone-vue/components/tab/tab_group.vue b/packages/dialtone-vue/components/tab/tab_group.vue
index 1f721446ae..19497996cc 100644
--- a/packages/dialtone-vue/components/tab/tab_group.vue
+++ b/packages/dialtone-vue/components/tab/tab_group.vue
@@ -88,7 +88,7 @@ export default {
 
     /**
      * If true, applies inverted styles to the tab group
-     * @deprecated
+     * @deprecated Use v-dt-mode directive instead.
      * @values true, false
      */
     inverted: {

From c575976002c6ac843598bc1b1e4ea2f667415720 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sun, 8 Mar 2026 07:00:53 -0500
Subject: [PATCH 27/47] refine mode island demo layout and add code syntax
 color variables

---
 .../theme/assets/less/dialtone-syntax.less    |  8 ++
 .../docs/components/mode-island.md            | 88 ++++++++-----------
 .../docs/components/scrollbar.md              | 42 +++++----
 .../docs/components/text.md                   | 20 +++++
 .../build/less/components/mode-island.less    |  7 +-
 5 files changed, 94 insertions(+), 71 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
index bbbce8b258..eccb86b395 100644
--- a/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
+++ b/apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-syntax.less
@@ -3,6 +3,14 @@
  * Based on dabblet (http://dabblet.com)
  */
 
+
+:root {
+  --code-c-text: var(--dt-color-foreground-secondary);
+  --code-c-bg: blue;
+  --code-c-highlight-bg:var(--dt-color-blue-800);
+  --code-c-line-number: gray;
+}
+
 div[class*="language-"] {
 	margin: var(--dt-size-500) 0;
 	padding: var(--dt-size-500);
diff --git a/apps/dialtone-documentation/docs/components/mode-island.md b/apps/dialtone-documentation/docs/components/mode-island.md
index 2ae759f6b7..81c685ab68 100644
--- a/apps/dialtone-documentation/docs/components/mode-island.md
+++ b/apps/dialtone-documentation/docs/components/mode-island.md
@@ -2,13 +2,13 @@
 title: Mode Island
 description: Apply light, dark, or inverted color mode to any element or region.
 status: beta
-keywords: ["theme island","mode override","v-dt-mode","directive","light","dark","inverted"]
+keywords: ["theme island","mode override","v-dt-mode","directive","light","dark","invert","v-dt"]
 ---
 
 <code-well-header>
-  <dt-stack gap="500" class="d-ai-flex-start d-w100p">
-    <dt-stack direction="row" gap="500" class="d-jc-space-between d-w100p">
-      <dt-text as="h4" kind="headline" size="xl">Demo</dt-text>
+  <dt-stack gap="500">
+    <dt-stack direction="row" gap="500" justify="space-between" class="d-w100p">
+      <dt-text as="h4" kind="headline" size="lg">Demo</dt-text>
       <dt-dropdown
         navigation-type="arrow-keys"
         placement="bottom-end"
@@ -109,73 +109,61 @@ keywords: ["theme island","mode override","v-dt-mode","directive","light","dark"
       </dt-dropdown>
     </dt-stack>
     <dt-stack :direction="{ 'default': 'column', 'md': 'row' }" gap="500" class="d-w100p">
-      <section v-dt-mode class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default d-fl1">
-        <dt-stack gap="400">
-          <dt-stack direction="row" gap="400" class="d-jc-space-between">
-            <dt-text as="h3" kind="headline" size="md" density="200">Inverted <dt-text strength="normal">(auto)</dt-text></dt-text>
+      <dt-stack gap="400" class="d-fl1">
+        <dt-text as="h3" kind="headline" size="md">Inverted <dt-text strength="normal">(auto)</dt-text></dt-text>
+        <dt-stack v-dt-mode:invert gap="400" class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default">
+          <dt-stack gap="400" direction="row">
             <dt-icon name="circle-half-filled" size="300" class="d-fc-success" />
+            <dt-text as="p" kind="body" size="sm">Primary</dt-text>
+            <dt-text as="p" kind="body" size="sm" tone="muted">Muted</dt-text>
+            <dt-text as="p" kind="body" size="sm" tone="critical">Critical</dt-text>
+            <dt-link>Link</dt-link>
           </dt-stack>
-          <dt-stack gap="400" direction="row" class="d-py2 d-px8 d-bgc-moderate d-bar4 d-ba">
-            <dt-text as="p">Primary</dt-text>
-            <dt-text as="p" tone="tertiary">Tertiary</dt-text>
-            <dt-text as="p" tone="critical">Critical</dt-text>
-          </dt-stack>
-          <dt-text as="p">
-            <dt-link>Text link</dt-link>
-          </dt-text>
           <dt-stack direction="row" gap="400" class="d-100p">
-            <dt-button class="d-fl1">Button</dt-button>
-            <dt-button class="d-fl1" kind="danger">Button</dt-button>
+            <dt-button size="sm" class="d-fl1">Button</dt-button>
+            <dt-button size="sm" class="d-fl1" kind="danger">Button</dt-button>
           </dt-stack>
         </dt-stack>
-      </section>
-      <section v-dt-mode:light class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default d-fl1">
-        <dt-stack gap="400">
-          <dt-stack direction="row" gap="400" class="d-jc-space-between">
-            <dt-text as="h3" kind="headline" size="md" density="200">Explicit light</dt-text>
+      </dt-stack>
+      <dt-stack gap="400" class="d-fl1">
+        <dt-text as="h3" kind="headline" size="md">Explicit light</dt-text>
+        <dt-stack v-dt-mode:light gap="400" class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default">
+          <dt-stack gap="400" direction="row">
             <dt-icon name="sun" size="300" class="d-fc-success" />
+            <dt-text as="p" kind="body" size="sm">Primary</dt-text>
+            <dt-text as="p" kind="body" size="sm" tone="muted">Muted</dt-text>
+            <dt-text as="p" kind="body" size="sm" tone="critical">Critical</dt-text>
+            <dt-link>Link</dt-link>
           </dt-stack>
-          <dt-stack gap="400" direction="row" class="d-py2 d-px8 d-bgc-moderate d-bar4 d-ba">
-            <dt-text as="p">Primary</dt-text>
-            <dt-text as="p" tone="tertiary">Tertiary</dt-text>
-            <dt-text as="p" tone="critical">Critical</dt-text>
-          </dt-stack>
-          <dt-text as="p">
-            <dt-link>Text link</dt-link>
-          </dt-text>
           <dt-stack direction="row" gap="400" class="d-100p">
-            <dt-button class="d-fl1">Button</dt-button>
-            <dt-button class="d-fl1" kind="danger">Button</dt-button>
+            <dt-button size="sm" class="d-fl1">Button</dt-button>
+            <dt-button size="sm" class="d-fl1" kind="danger">Button</dt-button>
           </dt-stack>
         </dt-stack>
-      </section>
-      <section v-dt-mode:dark class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default d-fl1">
-        <dt-stack gap="400">
-          <dt-stack direction="row" gap="400" class="d-jc-space-between">
-            <dt-text as="h3" kind="headline" size="md" density="200">Explicit dark</dt-text>
+      </dt-stack>
+      <dt-stack gap="400" class="d-fl1">
+        <dt-text as="h3" kind="headline" size="md">Explicit dark</dt-text>
+        <dt-stack v-dt-mode:dark gap="400" class="d-bgc-secondary d-p16 d-bar8 d-ba d-bc-default">
+          <dt-stack gap="400" direction="row">
             <dt-icon name="moon" size="300" class="d-fc-success" />
+            <dt-text as="p" kind="body" size="sm">Primary</dt-text>
+            <dt-text as="p" kind="body" size="sm" tone="muted">Muted</dt-text>
+            <dt-text as="p" kind="body" size="sm" tone="critical">Critical</dt-text>
+            <dt-link>Link</dt-link>
           </dt-stack>
-          <dt-stack gap="400" direction="row" class="d-py2 d-px8 d-bgc-moderate d-bar4 d-ba">
-            <dt-text as="p">Primary</dt-text>
-            <dt-text as="p" tone="tertiary">Tertiary</dt-text>
-            <dt-text as="p" tone="critical">Critical</dt-text>
-          </dt-stack>
-          <dt-text as="p">
-            <dt-link>Text link</dt-link>
-          </dt-text>
           <dt-stack direction="row" gap="400" class="d-100p">
-            <dt-button class="d-fl1">Button</dt-button>
-            <dt-button class="d-fl1" kind="danger">Button</dt-button>
+            <dt-button size="sm" class="d-fl1">Button</dt-button>
+            <dt-button size="sm" class="d-fl1" kind="danger">Button</dt-button>
           </dt-stack>
         </dt-stack>
-      </section>
+      </dt-stack>
     </dt-stack>
   </dt-stack>
 </code-well-header>
 
 ## Usage
 
-Use the `v-dt-mode` directive to control the color mode of a region, component, or element. It creates an scoped region with the specified mode. Descendant elements retain their original styling but are rendered with the specified mode.
+Use the `v-dt-mode` directive to control the color mode of a region, component, or element. It creates a scoped region with the specified mode. Descendant elements retain their original styling but are rendered with the specified mode.
 
 <code-well-header>
   <dt-text v-dt-mode:dark tone="success"> Dark content </dt-text>
diff --git a/apps/dialtone-documentation/docs/components/scrollbar.md b/apps/dialtone-documentation/docs/components/scrollbar.md
index 4bcd18ad8e..0b9ba39522 100644
--- a/apps/dialtone-documentation/docs/components/scrollbar.md
+++ b/apps/dialtone-documentation/docs/components/scrollbar.md
@@ -4,7 +4,7 @@ description: A directive that adds a custom overlay scrollbar to any scrollable
 status: beta
 thumb: true
 image: assets/images/components/scrollbar.png
-keywords: ["scrollable", "d-scrollbar", "DtScrollbar", "dt-scrollbar", "custom scrollbar", "scroll container"]
+keywords: ["scrollable", "d-scrollbar", "DtScrollbar", "dt-scrollbar", "custom scrollbar", "scroll container", "v-dt", "directive"]
 ---
 
 ## Scrollbar Directive
@@ -95,10 +95,6 @@ To customize the behavior of the scrollbar, you can use different arguments with
 
 Show the scrollbar when the mouse enters the scrollable area. This is the default option, so no argument is needed.
 
-```javascript
-<div v-dt-scrollbar></div>
-```
-
 <code-well-header>
   <div class="d-hmx164 d-w30p d-bar8 d-ba" v-dt-scrollbar>
     <dt-stack>
@@ -109,14 +105,16 @@ Show the scrollbar when the mouse enters the scrollable area. This is the defaul
   </div>
 </code-well-header>
 
+<code-example-tabs
+vueCode='
+<div v-dt-scrollbar></div>
+'
+/>
+
 ### Always
 
 Always show the scrollbar if the region is overflowing the available space.
 
-```javascript
-<div v-dt-scrollbar:never></div>
-```
-
 <code-well-header>
   <div class="d-hmx164 d-w30p d-bar8 d-ba" v-dt-scrollbar:never>
     <dt-stack>
@@ -127,14 +125,16 @@ Always show the scrollbar if the region is overflowing the available space.
   </div>
 </code-well-header>
 
+<code-example-tabs
+vueCode='
+<div v-dt-scrollbar:never></div>
+'
+/>
+
 ### Scroll
 
 Show the scrollbar on scroll.
 
-```javascript
-<div v-dt-scrollbar:scroll></div>
-```
-
 <code-well-header>
   <div class="d-hmx164 d-w30p d-bar8 d-ba" v-dt-scrollbar:scroll>
     <dt-stack>
@@ -145,14 +145,16 @@ Show the scrollbar on scroll.
   </div>
 </code-well-header>
 
+<code-example-tabs
+vueCode='
+<div v-dt-scrollbar:scroll></div>
+'
+/>
+
 ### Move
 
 Show the scrollbar when the mouse moves inside the scrollable area.
 
-```javascript
-<div v-dt-scrollbar:move></div>
-```
-
 <code-well-header>
   <div class="d-hmx164 d-w30p d-bar8 d-ba" v-dt-scrollbar:move>
     <dt-stack>
@@ -163,6 +165,12 @@ Show the scrollbar when the mouse moves inside the scrollable area.
   </div>
 </code-well-header>
 
+<code-example-tabs
+vueCode='
+<div v-dt-scrollbar:move></div>
+'
+/>
+
 ## Limitations
 
 Adding this directive to a DOM element or a Vue component will alter the DOM structure, by adding four elements inside the one that the directive was attached to. If the scrollable region is a Vue component, it's recommended to wrap it in a `<div v-dt-scrollbar></div>`, to avoid altering the structure that the component needs.
diff --git a/apps/dialtone-documentation/docs/components/text.md b/apps/dialtone-documentation/docs/components/text.md
index 9f0e849332..31ed05c108 100644
--- a/apps/dialtone-documentation/docs/components/text.md
+++ b/apps/dialtone-documentation/docs/components/text.md
@@ -308,6 +308,26 @@ vueCode='
 <dt-text tone="critical-strong">critical-strong</dt-text>
 '/>
 
+### Inverted
+
+Rather than use the `-inverted` tone variants, use the [v-dt-mode](/components/mode-island.html) directive.
+
+<code-well-header>
+  <dt-stack gap="300" class="d-py8 d-px16 d-bar4">
+    <div class="d-p8 d-bgc-transparent">
+      <dt-text tone="critical">critical tone on default surface</dt-text>
+    </div>
+    <div class="d-p8 d-bgc-contrast">
+      <dt-text v-dt-mode:invert tone="critical">critical tone on contrasting surface</dt-text>
+    </div>
+  </dt-stack>
+</code-well-header>
+
+<code-example-tabs
+vueCode='
+<dt-text v-dt-mode:invert tone="critical">critical tone on contrasting surface</dt-text>
+'/>
+
 ## Render as
 
 Use `as` to declare the underlying HTML tag that the component should render, independent of the visual styling. Defaults to `span`.
diff --git a/packages/dialtone-css/lib/build/less/components/mode-island.less b/packages/dialtone-css/lib/build/less/components/mode-island.less
index f1f927be83..0d99a658ac 100644
--- a/packages/dialtone-css/lib/build/less/components/mode-island.less
+++ b/packages/dialtone-css/lib/build/less/components/mode-island.less
@@ -1,10 +1,9 @@
-@layer dialtone.base {
-// intentionally on base layer
-[data-dt-mode] {
+@layer dialtone.components {
+:where([data-dt-mode]) {
   color: var(--dt-color-foreground-primary);
 }
 
-.d-mode-island {
+:where(.d-mode-island) {
   background-color: var(--dt-color-surface-primary);
 }
 }

From 3a25a72ad2ed6436d698ecd3b01b97178ff8c3f0 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sun, 8 Mar 2026 07:18:25 -0500
Subject: [PATCH 28/47] .

---
 .../docs/components/mode-island.md            | 161 ++++++++++--------
 1 file changed, 88 insertions(+), 73 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/mode-island.md b/apps/dialtone-documentation/docs/components/mode-island.md
index 81c685ab68..f2dc23d052 100644
--- a/apps/dialtone-documentation/docs/components/mode-island.md
+++ b/apps/dialtone-documentation/docs/components/mode-island.md
@@ -346,12 +346,12 @@ showHtmlWarning />
 Mode boundaries can be nested. Each `v-dt-mode:invert` reads the nearest parent boundary and flips. In this example the first level is explicitly set to light mode, the second level inverts against that, and the third level inverts again.
 
 <code-well-header>
-  <dt-stack gap="400" ref="nestingExample" v-dt-mode:light class="d-p16 d-bar8 d-bgc-secondary d-ba">
-    <dt-text as="p" tone="success">Light</dt-text>
-    <dt-stack v-dt-mode gap="400" class="d-p16 d-bar8 d-bgc-secondary">
-      <dt-text as="p" tone="success">Inverted (Dark)</dt-text>
-      <dt-stack v-dt-mode gap="400" class="d-p16 d-bar4 d-bgc-secondary">
-        <dt-text as="p" tone="success">Inverted again (Light)</dt-text>
+  <dt-stack gap="500" ref="nestingExample" v-dt-mode:light class="d-p16 d-bar8 d-bgc-secondary d-ba">
+    <dt-text as="p" tone="success" text-box-trim="both">Explicit Light</dt-text>
+    <dt-stack v-dt-mode gap="500" class="d-p16 d-bar8 d-bgc-secondary">
+      <dt-text as="p" tone="success" text-box-trim="both">Inverted (Dark)</dt-text>
+      <dt-stack v-dt-mode gap="500" class="d-p16 d-bar4 d-bgc-secondary">
+        <dt-text as="p" tone="success" text-box-trim="both">Inverted again (Light)</dt-text>
       </dt-stack>
     </dt-stack>
   </dt-stack>
@@ -360,12 +360,12 @@ Mode boundaries can be nested. Each `v-dt-mode:invert` reads the nearest parent
 <code-example-tabs
 :htmlCode='() => $refs.nestingExample'
 vueCode='
-<dt-stack gap="400" v-dt-mode:light class="d-p16 d-bar8 d-bgc-secondary d-ba">
-  <dt-text as="p" tone="success">Light</dt-text>
-  <dt-stack v-dt-mode gap="400" class="d-p16 d-bar8 d-bgc-secondary">
-    <dt-text as="p" tone="success">Inverted (Dark)</dt-text>
-    <dt-stack v-dt-mode gap="400" class="d-p16 d-bar4 d-bgc-secondary">
-      <dt-text as="p" tone="success">Inverted again (Light)</dt-text>
+<dt-stack gap="500" ref="nestingExample" v-dt-mode:light class="d-p16 d-bar8 d-bgc-secondary d-ba">
+  <dt-text as="p" tone="success" text-box-trim="both">Explicit Light</dt-text>
+  <dt-stack v-dt-mode gap="500" class="d-p16 d-bar8 d-bgc-secondary">
+    <dt-text as="p" tone="success" text-box-trim="both">Inverted (Dark)</dt-text>
+    <dt-stack v-dt-mode gap="500" class="d-p16 d-bar4 d-bgc-secondary">
+      <dt-text as="p" tone="success" text-box-trim="both">Inverted again (Light)</dt-text>
     </dt-stack>
   </dt-stack>
 </dt-stack>
@@ -379,62 +379,13 @@ vueCode='
 A real-world pattern: the callbar container already exists as a semantic element. The directive applies mode theming directly — no wrapper needed.
 
 <code-well-header>
-  <nav ref="callbarExample" v-dt-mode class="d-ba d-bc-subtle d-bgc-secondary d-p8 d-py4 d-bar12 d-bs-md d-w100p">
-    <dt-stack direction="row" gap="600">
-      <dt-stack gap="400" direction="row">
-        <dt-avatar
-          full-name="TA"
-          seed="ted-anderson"
-          size="lg"
-        />
-        <dt-stack gap="200">
-          <dt-text kind="label" size="md" density="200">Ted Anderson</dt-text>
-          <dt-stack direction="row" gap="300" align="baseline">
-            <dt-text kind="body" size="xs" tone="tertiary" wrap="nowrap" numeric>(913) 555-6745</dt-text>
-            <dt-text kind="body" size="xs" tone="muted">&bull;</dt-text>
-            <dt-text kind="body" size="xs" tone="tertiary" numeric>21:18</dt-text>
-          </dt-stack>
-        </dt-stack>
-      </dt-stack>
-      <dt-stack class="d-fl1 d-jc-center" direction="row" gap="200">
-        <dt-button class="d-px8 d-w72" size="sm" kind="danger">
-          <template #blockStartIcon> <dt-icon name="mic" size="400" /> </template>
-          Unmute
-        </dt-button>
-        <dt-button class="d-px8 d-w72" size="sm" kind="muted" importance="clear">
-          <template #blockStartIcon> <dt-icon name="record-filled" size="400" /> </template>
-          Record
-        </dt-button>
-        <dt-button class="d-px8 d-w72" size="sm" kind="muted" importance="clear">
-          <template #blockStartIcon> <dt-icon name="keypad" size="400" /> </template>
-          Keypad
-        </dt-button>
-        <dt-button class="d-px8 d-w72" size="sm" kind="muted" importance="clear">
-          <template #blockStartIcon> <dt-icon name="user-plus" size="400" /> </template>
-          Add
-        </dt-button>
-        <dt-button class="d-px8 d-w72" size="sm" kind="muted" importance="clear">
-          <template #blockStartIcon> <dt-icon name="more-horizontal" size="400" /> </template>
-          More
-        </dt-button>
-      </dt-stack>
-      <dt-stack>
-        <dt-button class="d-p12" circle size="lg" kind="danger">
-          <template #startIcon> <dt-icon name="phone-hang-up" size="500" /> </template>
-        </dt-button>
-      </dt-stack>
-    </dt-stack>
-  </nav>
-  <dt-text as="p" tone="muted" class="d-mt8">* Not real, still just an example</dt-text>
-</code-well-header>
-
-<code-example-tabs
-:htmlCode='() => $refs.callbarExample'
-vueCode='
-<nav v-dt-mode class="d-ba d-bc-subtle d-p8 d-py4 d-bar32 d-bs-md d-w100p">
-  <dt-stack direction="row" gap="600">
+  <dt-stack ref="callbarExample" v-dt-mode class="d-ba d-bc-subtle d-bgc-secondary d-p6 d-py4 d-bar12 d-bs-md d-w100p" direction="row" gap="600">
     <dt-stack gap="400" direction="row">
-      <dt-avatar full-name="TA" seed="ted-anderson" size="lg" />
+      <dt-avatar
+        full-name="TA"
+        seed="ted-anderson"
+        size="lg"
+      />
       <dt-stack gap="200">
         <dt-text kind="label" size="md" density="200">Ted Anderson</dt-text>
         <dt-stack direction="row" gap="300" align="baseline">
@@ -444,20 +395,84 @@ vueCode='
         </dt-stack>
       </dt-stack>
     </dt-stack>
-    <dt-stack class="d-fl1 d-jc-center" direction="row" gap="200">
-      <dt-button class="d-px8 d-w72" size="sm" kind="danger">
-        <template #blockStartIcon><dt-icon name="mic" size="400" /></template>
+    <dt-stack class="d-fl1" direction="row" gap="200" justify="center">
+      <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="danger">
+        <template #blockStartIcon> <dt-icon name="mic" size="300" /> </template>
         Unmute
       </dt-button>
-      <!-- Additional buttons... -->
+      <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+        <template #blockStartIcon> <dt-icon name="record-filled" size="300" /> </template>
+        Record
+      </dt-button>
+      <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+        <template #blockStartIcon> <dt-icon name="keypad" size="300" /> </template>
+        Keypad
+      </dt-button>
+      <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+        <template #blockStartIcon> <dt-icon name="user-plus" size="300" /> </template>
+        Add
+      </dt-button>
+      <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+        <template #blockStartIcon> <dt-icon name="more-horizontal" size="300" /> </template>
+        More
+      </dt-button>
     </dt-stack>
     <dt-stack>
       <dt-button class="d-p12" circle size="lg" kind="danger">
-        <template #startIcon><dt-icon name="phone-hang-up" size="500" /></template>
+        <template #startIcon> <dt-icon name="phone-hang-up" size="500" /> </template>
       </dt-button>
     </dt-stack>
   </dt-stack>
-</nav>
+  <dt-text as="p" kind="label" size="sm" tone="muted" class="d-mt8">* Not real, still just an example</dt-text>
+</code-well-header>
+
+<code-example-tabs
+:htmlCode='() => $refs.callbarExample'
+vueCode='
+<dt-stack v-dt-mode class="d-ba d-bc-subtle d-bgc-secondary d-p6 d-py4 d-bar12 d-bs-md d-w100p" direction="row" gap="600">
+  <dt-stack gap="400" direction="row">
+    <dt-avatar
+      full-name="TA"
+      seed="ted-anderson"
+      size="lg"
+    />
+    <dt-stack gap="200">
+      <dt-text kind="label" size="md" density="200">Ted Anderson</dt-text>
+      <dt-stack direction="row" gap="300" align="baseline">
+        <dt-text kind="body" size="xs" tone="tertiary" wrap="nowrap" numeric>(913) 555-6745</dt-text>
+        <dt-text kind="body" size="xs" tone="muted">&bull;</dt-text>
+        <dt-text kind="body" size="xs" tone="tertiary" numeric>21:18</dt-text>
+      </dt-stack>
+    </dt-stack>
+  </dt-stack>
+  <dt-stack class="d-fl1" direction="row" gap="200" justify="center">
+    <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="danger">
+      <template #blockStartIcon> <dt-icon name="mic" size="300" /> </template>
+      Unmute
+    </dt-button>
+    <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+      <template #blockStartIcon> <dt-icon name="record-filled" size="300" /> </template>
+      Record
+    </dt-button>
+    <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+      <template #blockStartIcon> <dt-icon name="keypad" size="300" /> </template>
+      Keypad
+    </dt-button>
+    <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+      <template #blockStartIcon> <dt-icon name="user-plus" size="300" /> </template>
+      Add
+    </dt-button>
+    <dt-button class="d-px8 d-w64 d-w64" size="xs" kind="muted" importance="clear">
+      <template #blockStartIcon> <dt-icon name="more-horizontal" size="300" /> </template>
+      More
+    </dt-button>
+  </dt-stack>
+  <dt-stack>
+    <dt-button class="d-p12" circle size="lg" kind="danger">
+      <template #startIcon> <dt-icon name="phone-hang-up" size="500" /> </template>
+    </dt-button>
+  </dt-stack>
+</dt-stack>
 '
 showHtmlWarning />
 

From 871c6e4d4a33b18bb03da227881c0e3396c980c2 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sun, 8 Mar 2026 07:31:25 -0500
Subject: [PATCH 29/47] correct scrollbar css layer

---
 .../dialtone-css/lib/build/less/components/scrollbar.less  | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/packages/dialtone-css/lib/build/less/components/scrollbar.less b/packages/dialtone-css/lib/build/less/components/scrollbar.less
index 35d128ad41..2d5521d3b5 100644
--- a/packages/dialtone-css/lib/build/less/components/scrollbar.less
+++ b/packages/dialtone-css/lib/build/less/components/scrollbar.less
@@ -1,4 +1,4 @@
-@layer dialtone.components {
+// not in a layer because it's based on external library variables
 .d-scrollbar {
   .os-theme-dark {
     // main color for the scrollbars handle
@@ -22,11 +22,11 @@
       opacity: var(--dt-opacity-700);
 
       &:hover {
-        opacity: var(--dt-opacity-800);
+        opacity: var(--dt-opacity-900);
       }
 
       &:active {
-        opacity: var(--dt-opacity-900);
+        opacity: var(--dt-opacity-1000);
       }
     }
   }
@@ -40,4 +40,3 @@
     display: none;
   }
 }
-}

From 22b6ba2a7e508af8d3db492b45e8061474efea83 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Sun, 8 Mar 2026 07:51:21 -0500
Subject: [PATCH 30/47] add file-level disable comment support to
 validate-layers plugin

---
 .../dialtone-css/lib/build/less/components/scrollbar.less   | 5 +++--
 packages/dialtone-css/postcss/validate-layers.cjs           | 6 ++++++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/packages/dialtone-css/lib/build/less/components/scrollbar.less b/packages/dialtone-css/lib/build/less/components/scrollbar.less
index 2d5521d3b5..2a11a9c2fc 100644
--- a/packages/dialtone-css/lib/build/less/components/scrollbar.less
+++ b/packages/dialtone-css/lib/build/less/components/scrollbar.less
@@ -1,4 +1,5 @@
-// not in a layer because it's based on external library variables
+/* validate-layers: off */
+// intentionally outside @layer to win specificity over imported library overlayscrollbars.css
 .d-scrollbar {
   .os-theme-dark {
     // main color for the scrollbars handle
@@ -26,7 +27,7 @@
       }
 
       &:active {
-        opacity: var(--dt-opacity-1000);
+        opacity: var(--dt-opacity-1100);
       }
     }
   }
diff --git a/packages/dialtone-css/postcss/validate-layers.cjs b/packages/dialtone-css/postcss/validate-layers.cjs
index 6d2fcf0ffc..d0d8fb06e5 100644
--- a/packages/dialtone-css/postcss/validate-layers.cjs
+++ b/packages/dialtone-css/postcss/validate-layers.cjs
@@ -17,6 +17,12 @@ module.exports = ({
       const unlayeredRules = [];
       const validLayers = ['dialtone.reset', 'dialtone.base', 'dialtone.components', 'dialtone.utilities'];
 
+      // Check for file-level disable comment: /* validate-layers: off */
+      const fileDisabled = root.nodes.some(
+        n => n.type === 'comment' && n.text.trim() === 'validate-layers: off',
+      );
+      if (fileDisabled) return;
+
       root.walkRules(rule => {
         // Skip @font-face, @keyframes, etc - these are at-rules, not rules
         if (rule.parent.type === 'atrule' && ['font-face', 'keyframes'].includes(rule.parent.name)) {

From 752d181b61b795cfe9e9df9d146236b9902baab6 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Mon, 9 Mar 2026 19:04:53 -0500
Subject: [PATCH 31/47] clarify component vs directive usage

---
 .../docs/components/mode-island.md            | 27 +++++++++----------
 1 file changed, 12 insertions(+), 15 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/mode-island.md b/apps/dialtone-documentation/docs/components/mode-island.md
index f2dc23d052..1c7955ad58 100644
--- a/apps/dialtone-documentation/docs/components/mode-island.md
+++ b/apps/dialtone-documentation/docs/components/mode-island.md
@@ -722,12 +722,22 @@ vueCode='
 
 ## Component
 
-The `<dt-mode-island>` component is the underlying abstraction that the directive builds on. It creates a wrapper element, sets `data-dt-mode` and `data-dt-contrast`, and applies the `d-mode-island` CSS class (which sets `color` and `background-color` from tokens).
+The `<dt-mode-island>` component is the underlying abstraction that the directive builds on. The key rendered difference is that it creates a wrapper element, while the directive attaches to mode to the existing element.
 
-Use the component when no container element exists and you need one created for you.
+<dt-notice
+  kind="info"
+  class="d-wmx100p d-mt24 d-mb24"
+  hide-close
+  title="Warning"
+>
+  The only real case where you might want to use the component is when you need to create a container element that doesn't already exist, but even then, you can create any kind of containing element with the directive e.g. <code>&lt;span v-dt-mode:invert"&gt;...&lt;/span&gt;</code>.
+</dt-notice>
 
 <code-example-tabs
 vueCode='
+<dt-mode-island as="section">
+  Rendered as a section element inverted
+</dt-mode-island>
 <dt-mode-island>
   Inverted (default)
 </dt-mode-island>
@@ -737,22 +747,9 @@ vueCode='
 <dt-mode-island mode="dark">
   Dark
 </dt-mode-island>
-<dt-mode-island as="section" mode="dark">
-  Rendered as a section element
-</dt-mode-island>
 '
 />
 
-### When to use which
-
-| Scenario | Use |
-|----------|-----|
-| You already have a container element (`section`, `nav`, `div`, etc.) | `v-dt-mode` directive |
-| No container exists, you need a wrapper created | `<dt-mode-island>` component |
-| Inside slot content (popovers, dropdowns) | Either — directive preferred if a container element exists |
-
-Both set `data-dt-mode` on their element and are fully interoperable when nested.
-
 ## Vue API
 
 ### Directive

From 073919ecc3e69b379ae7a19492b39495d67fc925 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Mon, 9 Mar 2026 19:16:00 -0500
Subject: [PATCH 32/47] add suggestion for common "inverted" typo in mode
 directive validation

---
 .../directives/mode_directive/mode.js           | 12 ++++++++++++
 .../directives/mode_directive/mode.test.js      | 17 +++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode.js b/packages/dialtone-vue/directives/mode_directive/mode.js
index 93593dd9c4..61160b79b4 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.js
@@ -6,6 +6,10 @@ import {
 
 const VALID_MODES = ['light', 'dark', 'invert'];
 
+const SUGGESTIONS = {
+  inverted: 'invert',
+};
+
 export const DtModeDirective = {
   name: 'dt-mode-directive',
   install (app) {
@@ -36,6 +40,14 @@ export const DtModeDirective = {
     function resolveArg (arg) {
       if (!arg) return 'invert';
       if (VALID_MODES.includes(arg)) return arg;
+      if (SUGGESTIONS[arg]) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[DtModeDirective] Invalid mode "${arg}". Did you mean "${SUGGESTIONS[arg]}"? Falling back to "${SUGGESTIONS[arg]}".`,
+        );
+        return SUGGESTIONS[arg];
+      }
+      // eslint-disable-next-line no-console
       console.warn(
         `[DtModeDirective] Invalid mode "${arg}". Valid modes: ${VALID_MODES.join(', ')}. Falling back to "invert".`,
       );
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.test.js b/packages/dialtone-vue/directives/mode_directive/mode.test.js
index da487beb6a..36e9a8b3c1 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.test.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.test.js
@@ -221,6 +221,23 @@ describe('DtModeDirective Tests', () => {
   });
 
   describe('Validation Tests', () => {
+    it('should suggest "invert" when "inverted" is used', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      wrapper = mount({
+        template: '<section v-dt-mode:inverted data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Did you mean "invert"?'),
+      );
+      // Falls back to invert — root is light, so should be dark
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+      warnSpy.mockRestore();
+    });
+
     it('should warn and fall back to invert on invalid arg', () => {
       const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 

From a45c3c0573abb7ec38ed92e2f36119abd35eab4f Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 07:27:39 -0500
Subject: [PATCH 33/47] correct notice content gap

---
 packages/dialtone-css/lib/build/less/components/notice.less | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/dialtone-css/lib/build/less/components/notice.less b/packages/dialtone-css/lib/build/less/components/notice.less
index 8350dbeac2..633958b531 100644
--- a/packages/dialtone-css/lib/build/less/components/notice.less
+++ b/packages/dialtone-css/lib/build/less/components/notice.less
@@ -51,7 +51,7 @@
     flex: 1 auto;
     flex-direction: column;
     margin-inline-end: var(--dt-size-500);
-    gap: var(--dt-size-300);
+    gap: var(--dt-size-400);
     align-self: center;
 }
 

From 5471ce160035074a5b28ea31d31558b2d34afb0b Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 07:27:45 -0500
Subject: [PATCH 34/47] .

---
 apps/dialtone-documentation/docs/components/card.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/card.md b/apps/dialtone-documentation/docs/components/card.md
index a2515d3b8e..05b4fcc70e 100644
--- a/apps/dialtone-documentation/docs/components/card.md
+++ b/apps/dialtone-documentation/docs/components/card.md
@@ -15,7 +15,7 @@ keywords: ["panel", "container", "box", "d-card", "DtCard", "dt-card", "tile", "
       <dt-text as="p" kind="headline" size="md">
         Lorem ipsum
       </dt-text>
-      <button type="button" class="d-btn d-btn--xs d-btn--circle">
+      <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
         <dt-icon name="more-vertical" size="200" />
       </button>
     </div>
@@ -110,7 +110,7 @@ showHtmlWarning />
       <dt-text as="p" kind="headline" size="md">
         Lorem ipsum
       </dt-text>
-      <button type="button" class="d-btn d-btn--xs d-btn--circle">
+      <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
         <dt-icon name="more-vertical" size="200" />
       </button>
     </div>
@@ -127,7 +127,7 @@ htmlCode='
     <dt-text as="p" kind="headline" size="md">
       Lorem ipsum
     </dt-text>
-    <button type="button" class="d-btn d-btn--xs d-btn--circle">
+    <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
       <dt-icon name="more-vertical" size="200" />
     </button>
   </div>
@@ -240,7 +240,7 @@ showHtmlWarning />
       <dt-text as="p" kind="headline" size="md">
         Lorem ipsum
       </dt-text>
-      <button type="button" class="d-btn d-btn--xs d-btn--circle">
+      <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
         <dt-icon name="more-vertical" size="200" />
       </button>
     </div>
@@ -262,7 +262,7 @@ htmlCode='
     <dt-text as="p" kind="headline" size="md">
       Lorem ipsum
     </dt-text>
-    <button type="button" class="d-btn d-btn--xs d-btn--circle">
+    <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
       <dt-icon name="more-vertical" size="200" />
     </button>
   </div>

From 9bcd6d4f8c487eecfcca0851efff4671ab8e4a65 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 07:51:16 -0500
Subject: [PATCH 35/47] recommend v-dt-mode directive with examples

---
 .../baseComponents/FontUtilitiesNotice.vue    |  2 +-
 .../docs/utilities/backgrounds/color.md       | 25 +++++-
 .../docs/utilities/typography/font-color.md   | 80 ++++++++++++++-----
 3 files changed, 87 insertions(+), 20 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue
index a51dfdf341..f37e158d79 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/FontUtilitiesNotice.vue
@@ -3,7 +3,7 @@
     kind="warning"
     hide-close
     class="d-wmx100p d-my16"
-    title="Use DtText in favor CSS Utilities"
+    title="Use DtText over CSS Utilities"
   >
     <template #default>
       Reach for the
diff --git a/apps/dialtone-documentation/docs/utilities/backgrounds/color.md b/apps/dialtone-documentation/docs/utilities/backgrounds/color.md
index e85bc2e42d..0535423c01 100644
--- a/apps/dialtone-documentation/docs/utilities/backgrounds/color.md
+++ b/apps/dialtone-documentation/docs/utilities/backgrounds/color.md
@@ -111,10 +111,33 @@ Use `d-bgo{stop}` to change an element's background color opacity. You can also
 <p class="d-bgc-critical d-bgo0">...</p>
 ```
 
+## Inverted
+
 <dt-notice title="Tip" kind="info" class="d-wmx100p d-my16">
-  Prefer using the <dt-link to="/components/mode-island.html#inverting">v-dt-mode directive</dt-link> with base utility classes instead of <code>-inverted</code> variants. For example, use <code>&lt;div v-dt-mode:invert class="d-bgc-critical"&gt;</code> instead of <code>&lt;div class="d-bgc-critical-inverted"&gt;</code>.
+  Avoid <code>-inverted</code> utility variants. Use the <dt-link to="/components/mode-island.html#inverting">v-dt-mode directive</dt-link> with base classes instead — it automatically resolves the correct colors for the current mode.
 </dt-notice>
 
+<code-well-header>
+  <dt-stack
+    gap="500"
+    :direction="{ 'default': 'column', 'md': 'row' }"
+  >
+    <div
+      v-dt-mode:invert
+      v-for="color in ['primary', 'critical']"
+      class="d-p16 d-bar4"
+      :class="`d-bgc-${color}`"
+    >
+      {{ color.charAt(0).toUpperCase() + color.slice(1) }}
+    </div>
+  </dt-stack>
+</code-well-header>
+
+```html
+<div v-dt-mode:invert class="d-bgc-primary">...</div>
+<div v-dt-mode:invert class="d-bgc-critical">...</div>
+```
+
 ## Classes
 
 <new-utility-class-table :classes="backgroundColors">
diff --git a/apps/dialtone-documentation/docs/utilities/typography/font-color.md b/apps/dialtone-documentation/docs/utilities/typography/font-color.md
index 6d183437cc..6c4d300c25 100644
--- a/apps/dialtone-documentation/docs/utilities/typography/font-color.md
+++ b/apps/dialtone-documentation/docs/utilities/typography/font-color.md
@@ -13,7 +13,7 @@ Use [DtText's](/components/text.html#tone) `tone` prop to declare the text's ton
 <code-well-header>
   <dt-stack gap="500" direction="row">
     <dt-stack gap="300" class="d-py8 d-px16 d-bgc-primary d-bar4">
-      <dt-text>primary</dt-text>
+      <dt-text tone="primary">primary</dt-text>
       <dt-text tone="secondary">secondary</dt-text>
       <dt-text tone="tertiary">tertiary</dt-text>
       <dt-text tone="muted">muted</dt-text>
@@ -25,19 +25,6 @@ Use [DtText's](/components/text.html#tone) `tone` prop to declare the text's ton
       <dt-text tone="critical">critical</dt-text>
       <dt-text tone="critical-strong">critical-strong</dt-text>
     </dt-stack>
-    <dt-stack gap="300" class="d-py8 d-px16 d-bgc-primary-inverted d-bar4">
-      <dt-text tone="primary-inverted">primary-inverted</dt-text>
-      <dt-text tone="secondary-inverted">secondary-inverted</dt-text>
-      <dt-text tone="tertiary-inverted">tertiary-inverted</dt-text>
-      <dt-text tone="muted-inverted">muted-inverted</dt-text>
-      <dt-text tone="disabled-inverted">disabled-inverted</dt-text>
-      <dt-text tone="placeholder-inverted">placeholder-inverted</dt-text>
-      <dt-text tone="success-inverted">success-inverted</dt-text>
-      <dt-text tone="success-strong-inverted">success-strong-inverted</dt-text>
-      <dt-text tone="warning-inverted">warning-inverted</dt-text>
-      <dt-text tone="critical-inverted">critical-inverted</dt-text>
-      <dt-text tone="critical-strong-inverted">critical-strong-inverted</dt-text>
-    </dt-stack>
   </dt-stack>
 </code-well-header>
 
@@ -97,6 +84,67 @@ Use `fv:d-fc-{color}` to change an element's text color on `:focus-visible` stat
 <dt-button kind="unstyled" class="d-fc-critical fv:d-fc-success">Keyboard focus me</dt-button>
 ```
 
+## Inverted
+
+<dt-notice
+  title="Tip"
+  kind="info"
+  class="d-wmx100p d-my16"
+>
+  Avoid <code>-inverted</code> utility variants, which will be sunset. Use the
+  <dt-link to="/components/mode-island.html#inverting">v-dt-mode directive</dt-link>
+  with base classes instead — it automatically resolves the correct colors for
+  the current mode.
+</dt-notice>
+
+<code-well-header>
+  <dt-stack direction="row" gap="600">
+    <dt-stack gap="300" class="d-py8 d-px16 d-bgc-primary d-bar4">
+      <dt-text tone="primary">primary</dt-text>
+      <dt-text tone="secondary">secondary</dt-text>
+      <dt-text tone="tertiary">tertiary</dt-text>
+      <dt-text tone="muted">muted</dt-text>
+      <dt-text tone="disabled">disabled</dt-text>
+      <dt-text tone="placeholder">placeholder</dt-text>
+      <dt-text tone="success">success</dt-text>
+      <dt-text tone="success-strong">success-strong</dt-text>
+      <dt-text tone="warning">warning</dt-text>
+      <dt-text tone="critical">critical</dt-text>
+      <dt-text tone="critical-strong">critical-strong</dt-text>
+    </dt-stack>
+    <dt-stack gap="300" class="d-py8 d-px16 d-bgc-contrast d-bar4">
+      <dt-text v-dt-mode:invert tone="primary">primary</dt-text>
+      <dt-text v-dt-mode:invert tone="secondary">secondary</dt-text>
+      <dt-text v-dt-mode:invert tone="tertiary">tertiary</dt-text>
+      <dt-text v-dt-mode:invert tone="muted">muted</dt-text>
+      <dt-text v-dt-mode:invert tone="disabled">disabled</dt-text>
+      <dt-text v-dt-mode:invert tone="placeholder">placeholder</dt-text>
+      <dt-text v-dt-mode:invert tone="success">success</dt-text>
+      <dt-text v-dt-mode:invert tone="success-strong">success-strong</dt-text>
+      <dt-text v-dt-mode:invert tone="warning">warning</dt-text>
+      <dt-text v-dt-mode:invert tone="critical">critical</dt-text>
+      <dt-text v-dt-mode:invert tone="critical-strong">critical-strong</dt-text>
+    </dt-stack>
+  </dt-stack>
+</code-well-header>
+
+<code-example-tabs
+vueCode='
+<dt-stack gap="300" class="d-py8 d-px16 d-bgc-contrast d-bar4">
+  <dt-text v-dt-mode:invert tone="primary">primary</dt-text>
+  <dt-text v-dt-mode:invert tone="secondary">secondary</dt-text>
+  <dt-text v-dt-mode:invert tone="tertiary">tertiary</dt-text>
+  <dt-text v-dt-mode:invert tone="muted">muted</dt-text>
+  <dt-text v-dt-mode:invert tone="disabled">disabled</dt-text>
+  <dt-text v-dt-mode:invert tone="placeholder">placeholder</dt-text>
+  <dt-text v-dt-mode:invert tone="success">success</dt-text>
+  <dt-text v-dt-mode:invert tone="success-strong">success-strong</dt-text>
+  <dt-text v-dt-mode:invert tone="warning">warning</dt-text>
+  <dt-text v-dt-mode:invert tone="critical">critical</dt-text>
+  <dt-text v-dt-mode:invert tone="critical-strong">critical-strong</dt-text>
+</dt-stack>
+'/>
+
 ## Changing Opacity
 
 Use `d-fco{n}` to change an element's text color opacity. You can also change font color opacity on `:hover`, `:focus`,
@@ -126,10 +174,6 @@ Use `d-fco{n}` to change an element's text color opacity. You can also change fo
 <p class="d-fc-critical d-fco0">...</p>
 ```
 
-<dt-notice title="Tip" kind="info" class="d-wmx100p d-my16">
-  Prefer using the <dt-link to="/components/mode-island.html#inverting">v-dt-mode directive</dt-link> with base utility classes instead of <code>-inverted</code> variants. For example, use <code>&lt;dt-text v-dt-mode:invert tone="critical"&gt;</code> instead of <code>&lt;dt-text tone="critical-inverted"&gt;</code>.
-</dt-notice>
-
 ## Classes
 
 <new-utility-class-table :classes="fontColors">

From 0ec75544cb8ebe8c4af36f77a9a617d442185aea Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 16:06:19 -0500
Subject: [PATCH 36/47] conditional mode application via directive boolean
 value and tests

---
 .../directives/mode_directive/mode.js         | 26 ++++++++---
 .../directives/mode_directive/mode.test.js    | 45 +++++++++++++++++++
 2 files changed, 65 insertions(+), 6 deletions(-)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode.js b/packages/dialtone-vue/directives/mode_directive/mode.js
index 61160b79b4..daff17ae4c 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.js
@@ -17,22 +17,31 @@ export const DtModeDirective = {
 
     app.directive('dt-mode', {
       mounted (el, binding) {
+        if (binding.value === false) return;
         const mode = resolveArg(binding.arg);
         const state = applyMode(el, mode);
         instances.set(el, state);
       },
 
       updated (el, binding) {
-        if (binding.arg !== binding.oldArg) {
-          cleanup(instances.get(el));
-          const mode = resolveArg(binding.arg);
-          const state = applyMode(el, mode);
-          instances.set(el, state);
-        }
+        const valueChanged = binding.value !== binding.oldValue;
+        const argChanged = binding.arg !== binding.oldArg;
+        if (!valueChanged && !argChanged) return;
+
+        cleanup(instances.get(el));
+        removeAttributes(el);
+        instances.delete(el);
+
+        if (binding.value === false) return;
+
+        const mode = resolveArg(binding.arg);
+        const state = applyMode(el, mode);
+        instances.set(el, state);
       },
 
       unmounted (el) {
         cleanup(instances.get(el));
+        removeAttributes(el);
         instances.delete(el);
       },
     });
@@ -108,6 +117,11 @@ export const DtModeDirective = {
       return state;
     }
 
+    function removeAttributes (el) {
+      el.removeAttribute('data-dt-mode');
+      el.removeAttribute('data-dt-contrast');
+    }
+
     function cleanup (state) {
       if (!state) return;
       if (state.contrastObserver) {
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.test.js b/packages/dialtone-vue/directives/mode_directive/mode.test.js
index 36e9a8b3c1..661c7326cb 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.test.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.test.js
@@ -129,6 +129,51 @@ describe('DtModeDirective Tests', () => {
       expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('light');
     });
 
+    it('should not apply mode when value is false', () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:invert="false" data-qa="target">Content</section>',
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBeUndefined();
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-contrast')).toBeUndefined();
+    });
+
+    it('should apply mode when value changes from false to true', async () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:invert="enabled" data-qa="target">Content</section>',
+        data () {
+          return { enabled: false };
+        },
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBeUndefined();
+
+      await wrapper.setData({ enabled: true });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+    });
+
+    it('should remove mode when value changes from true to false', async () => {
+      wrapper = mount({
+        template: '<section v-dt-mode:invert="enabled" data-qa="target">Content</section>',
+        data () {
+          return { enabled: true };
+        },
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBe('dark');
+
+      await wrapper.setData({ enabled: false });
+
+      expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBeUndefined();
+    });
+
     it('should re-initialize when dynamic arg changes', async () => {
       wrapper = mount({
         template: '<section v-dt-mode:[mode] data-qa="target">Content</section>',

From 51fed8137effb58b4028327d3bee65203008df46 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 16:46:34 -0500
Subject: [PATCH 37/47] update button documentation deprecation notice clarity
 and kind

---
 apps/dialtone-documentation/docs/components/button.md |  6 +++---
 apps/dialtone-documentation/docs/scratch.md           | 10 +++++-----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/button.md b/apps/dialtone-documentation/docs/components/button.md
index 009638773a..ae483fff85 100644
--- a/apps/dialtone-documentation/docs/components/button.md
+++ b/apps/dialtone-documentation/docs/components/button.md
@@ -319,13 +319,13 @@ showHtmlWarning />
 
 <dt-notice
   title="Deprecated"
-  kind="error"
+  kind="info"
   class="d-wmx100p d-my16"
 >
-  <code>kind="inverted"</code> has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link> when no natural container element exists.
+  <code>kind="inverted"</code> has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>.
 </dt-notice>
 
-In place of `kind="inverted"`, use the [v-dt-mode directive](mode-island.html#inverting) on the component element. The previous `inverted` variant of DtButton was limited to a single presentation style. The directive now makes every combination available as an inverted style.
+Use the [v-dt-mode directive](mode-island.html#inverting) in place of `kind="inverted"` on the component element. The previous `inverted` variant of DtButton was limited to a single presentation style. The directive now makes every combination available as an inverted style.
 
 <code-well-header>
   <dt-toggle v-model="isInverted" size="sm" wrapperClass="d-g8 d-m-auto d-pb8">Inverted</dt-toggle>
diff --git a/apps/dialtone-documentation/docs/scratch.md b/apps/dialtone-documentation/docs/scratch.md
index 61feaaf7d7..ab5400d408 100644
--- a/apps/dialtone-documentation/docs/scratch.md
+++ b/apps/dialtone-documentation/docs/scratch.md
@@ -276,7 +276,7 @@ const checkRadioDisabled = ref(false);
     <dt-text as="h1" kind="headline" size="xl">
       Sizing update: Button/Input/Select
     </dt-text>
-    <dt-stack direction="row">
+    <dt-stack direction="row" align="end">
       <dt-select-menu
         size="xs"
         :options="[
@@ -302,7 +302,7 @@ const checkRadioDisabled = ref(false);
         Button
       </dt-button>
     </dt-stack>
-    <dt-stack direction="row">
+    <dt-stack direction="row" align="end">
       <dt-select-menu
         size="sm"
         :options="[
@@ -328,7 +328,7 @@ const checkRadioDisabled = ref(false);
         Button
       </dt-button>
     </dt-stack>
-    <dt-stack direction="row">
+    <dt-stack direction="row" align="end">
       <dt-select-menu
         size="md"
         :options="[
@@ -354,7 +354,7 @@ const checkRadioDisabled = ref(false);
         Button
       </dt-button>
     </dt-stack>
-    <dt-stack direction="row">
+    <dt-stack direction="row" align="end">
       <dt-select-menu
         size="lg"
         :options="[
@@ -380,7 +380,7 @@ const checkRadioDisabled = ref(false);
         Button
       </dt-button>
     </dt-stack>
-    <dt-stack direction="row">
+    <dt-stack direction="row" align="end">
       <dt-select-menu
         size="xl"
         :options="[

From c278cd4d2c8f83e54118c2e8e20f3a01d73780bd Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 16:48:10 -0500
Subject: [PATCH 38/47] mistake

---
 .../docs/.vuepress/baseComponents/tokens/TokenValue.vue         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue
index a9e4a99e4b..8b2c90cf69 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenValue.vue
@@ -11,7 +11,7 @@
       </span>
     </div>
     <div v-else>
-      {{ tokenValue }}s
+      {{ tokenValue }}
     </div>
   </dt-text>
 </template>

From 44917ce82e0a2e3a9bd33df47d492c5abd2a580b Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 16:48:44 -0500
Subject: [PATCH 39/47] mistake

---
 apps/dialtone-documentation/docs/components/button.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/button.md b/apps/dialtone-documentation/docs/components/button.md
index ae483fff85..207711d2f2 100644
--- a/apps/dialtone-documentation/docs/components/button.md
+++ b/apps/dialtone-documentation/docs/components/button.md
@@ -70,7 +70,6 @@ Dialtone provides five options for `kind`, with three levels of `importance`.
 The base button should be the go-to button for most of your needs. When in doubt, use this style. To help provide clarity to users, it is generally recommended to use only one primary button style within a section or page.
 
 <code-well-header>
-  <!-- asdfasdf -->
   <dt-stack direction="row" gap="400" ref="defaultExample">
       <dt-button> Place Call </dt-button>
       <dt-button importance="outlined"> Place Call </dt-button>
@@ -81,7 +80,6 @@ The base button should be the go-to button for most of your needs. When in doubt
 <code-example-tabs
 :htmlCode='() => $refs.defaultExample'
 vueCode='
-<!-- asdfasdf -->
 <dt-button> Place Call </dt-button>
 <dt-button importance="outlined"> Place Call </dt-button>
 <dt-button importance="clear"> Place Call </dt-button>

From f97fadd383e4d38e68b3c16ea3e49f913ee8e5c3 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 17:33:39 -0500
Subject: [PATCH 40/47] update card documentation examples to use vue
 components instead of html

---
 .../docs/components/card.md                   | 250 +++++++++---------
 1 file changed, 121 insertions(+), 129 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/card.md b/apps/dialtone-documentation/docs/components/card.md
index 05b4fcc70e..ff5cd2719a 100644
--- a/apps/dialtone-documentation/docs/components/card.md
+++ b/apps/dialtone-documentation/docs/components/card.md
@@ -10,24 +10,52 @@ keywords: ["panel", "container", "box", "d-card", "DtCard", "dt-card", "tile", "
 ---
 
 <code-well-header>
-  <div class="d-card d-w264">
-    <div class="d-card__header">
-      <dt-text as="p" kind="headline" size="md">
-        Lorem ipsum
-      </dt-text>
-      <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
-        <dt-icon name="more-vertical" size="200" />
-      </button>
-    </div>
-    <div class="d-card__content">
-      Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-    </div>
-    <div class="d-card__footer">
-      <dt-stack direction="row" gap="400">
-        <button type="button" class="d-btn d-btn--sm d-btn--outlined">Button</button>
+  <dt-card class="d-w264" header-class="d-bb d-bc-subtle d-py8 d-pr8" footer-class="d-bt d-bc-subtle d-py12">
+    <template #header>
+      <dt-stack gap="350" direction="row" align="center">
+        <dt-icon class="d-fc-tertiary" name="branch" size="300" />
+        <dt-text as="h3" kind="headline" size="md" tone="secondary">Lorem ipsum</dt-text>
       </dt-stack>
-    </div>
-  </div>
+      <dt-dropdown navigation-type="arrow-keys" placement="bottom-end">
+        <template #anchor="{ attrs }">
+          <dt-button
+            v-bind="attrs"
+            size="sm"
+            importance="clear"
+            kind="muted"
+            aria-label="Menu button"
+          >
+            <template #startIcon>
+              <dt-icon
+                name="more-vertical"
+                size="100"
+              />
+            </template>
+          </dt-button>
+        </template>
+        <template #list="{ close }">
+          <dt-list-item role="menuitem" navigation-type="arrow-keys" @click="close">Edit</dt-list-item>
+          <dt-list-item role="menuitem" navigation-type="arrow-keys" @click="close">Share</dt-list-item>
+          <dt-dropdown-separator />
+          <dt-list-item role="menuitem" navigation-type="arrow-keys" @click="close">Delete</dt-list-item>
+        </template>
+      </dt-dropdown>
+    </template>
+    <template #content>
+      <dt-stack gap="400">
+        <dt-text as="p" kind="body" text-box-trim="start">Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit, donec fermentum molestie semper.</dt-text>
+        <dt-text as="p" kind="body" text-box-trim="end">Morbi finibus nulla turpis, nec molestie mi rutrum</dt-text>
+      </dt-stack>
+    </template>
+    <template #footer>
+      <dt-button
+        importance="outlined"
+        size="sm"
+      >
+        Button
+      </dt-button>
+    </template>
+  </dt-card>
 </code-well-header>
 
 ## Usage
@@ -60,33 +88,20 @@ They should be easy to scan for relevant and actionable information. Elements, l
 ### Base
 
 <code-well-header>
-  <div class="d-card d-w264">
-    <div class="d-card__header">
-      <div>(header slot)</div>
-    </div>
-    <div class="d-card__content">
-      <div>(content slot)</div>
-    </div>
-    <div class="d-card__footer">
-      <div>(footer slot)</div>
-    </div>
-  </div>
+  <dt-card class="d-w264" header-class="h:d-bgc-moderate-opaque" content-class="h:d-bgc-moderate-opaque" footer-class="h:d-bgc-moderate-opaque">
+    <template #header>
+      (header slot)
+    </template>
+    <template #content>
+      (content slot)
+    </template>
+    <template #footer>
+      (footer slot)
+    </template>
+  </dt-card>
 </code-well-header>
 
 <code-example-tabs
-htmlCode='
-<div class="d-card d-w264">
-  <div class="d-card__header">
-    <div>(header slot)</div>
-  </div>
-  <div class="d-card__content">
-    <div>(content slot)</div>
-  </div>
-  <div class="d-card__footer">
-    <div>(footer slot)</div>
-  </div>
-</div>
-'
 vueCode='
 <dt-card class="d-w264">
   <template #header>
@@ -105,37 +120,30 @@ showHtmlWarning />
 ### With Header
 
 <code-well-header>
-  <div class="d-card d-w264">
-    <div class="d-card__header">
-      <dt-text as="p" kind="headline" size="md">
-        Lorem ipsum
-      </dt-text>
-      <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
-        <dt-icon name="more-vertical" size="200" />
-      </button>
-    </div>
-    <div class="d-card__content">
+  <dt-card class="d-w264">
+    <template #header>
+      <dt-text as="p" kind="headline" size="md">Lorem ipsum</dt-text>
+      <dt-button
+        size="xs"
+        importance="clear"
+        kind="muted"
+        aria-label="Menu button"
+      >
+        <template #startIcon>
+          <dt-icon
+            name="more-vertical"
+            size="100"
+          />
+        </template>
+      </dt-button>
+    </template>
+    <template #content>
       Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-    </div>
-  </div>
+    </template>
+  </dt-card>
 </code-well-header>
 
 <code-example-tabs
-htmlCode='
-<div class="d-card d-w264">
-  <div class="d-card__header">
-    <dt-text as="p" kind="headline" size="md">
-      Lorem ipsum
-    </dt-text>
-    <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
-      <dt-icon name="more-vertical" size="200" />
-    </button>
-  </div>
-  <div class="d-card__content">
-    Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-  </div>
-</div>
-'
 vueCode='
 <dt-card class="d-w264">
   <template #header>
@@ -143,6 +151,7 @@ vueCode='
     <dt-button
       size="xs"
       importance="clear"
+      kind="muted"
       aria-label="Menu button"
     >
       <template #startIcon>
@@ -163,31 +172,22 @@ showHtmlWarning />
 ### With Footer
 
 <code-well-header>
-  <div class="d-card d-w264">
-    <div class="d-card__content">
+  <dt-card class="d-w264">
+    <template #content>
       Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-    </div>
-    <div class="d-card__footer">
-      <dt-stack direction="row" gap="400">
-        <button type="button" class="d-btn d-btn--sm d-btn--outlined">Button</button>
-      </dt-stack>
-    </div>
-  </div>
+    </template>
+    <template #footer>
+      <dt-button
+        importance="outlined"
+        size="sm"
+      >
+        Button
+      </dt-button>
+    </template>
+  </dt-card>
 </code-well-header>
 
 <code-example-tabs
-htmlCode='
-<div class="d-card d-w264">
-  <div class="d-card__content">
-    Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-  </div>
-  <div class="d-card__footer">
-    <dt-stack direction="row" gap="400">
-      <button type="button" class="d-btn d-btn--sm d-btn--outlined">Button</button>
-    </dt-stack>
-  </div>
-</div>
-'
 vueCode='
 <dt-card class="d-w264">
   <template #content>
@@ -235,54 +235,46 @@ showHtmlWarning />
 ### With Header, Footer and Scrollable Content
 
 <code-well-header>
-  <div class="d-card d-w264">
-    <div class="d-card__header">
-      <dt-text as="p" kind="headline" size="md">
-        Lorem ipsum
-      </dt-text>
-      <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
-        <dt-icon name="more-vertical" size="200" />
-      </button>
-    </div>
-    <div class="d-card__content d-h72">
-      Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-    </div>
-    <div class="d-card__footer">
-      <dt-stack direction="row" gap="400">
-        <button type="button" class="d-btn d-btn--sm d-btn--outlined">Button</button>
-      </dt-stack>
-    </div>
-  </div>
+  <dt-card class="d-w264" content-class="d-pr0">
+    <template #header>
+      <dt-text as="p" kind="headline" size="md">Lorem ipsum</dt-text>
+      <dt-button
+        size="xs"
+        importance="clear"
+        kind="muted"
+        aria-label="Menu button"
+      >
+        <template #startIcon>
+          <dt-icon
+            name="more-vertical"
+            size="100"
+          />
+        </template>
+      </dt-button>
+    </template>
+    <template #content>
+      <div class="d-h72 d-pr16" v-dt-scrollbar:never>Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.</div>
+    </template>
+    <template #footer>
+      <dt-button
+        importance="outlined"
+        size="sm"
+      >
+        Button
+      </dt-button>
+    </template>
+  </dt-card>
 </code-well-header>
 
 <code-example-tabs
-htmlCode='
-<div class="d-card d-w264">
-  <div class="d-card__header">
-    <dt-text as="p" kind="headline" size="md">
-      Lorem ipsum
-    </dt-text>
-    <button type="button" class="d-btn d-btn--xs d-btn--icon-only d-btn--muted">
-      <dt-icon name="more-vertical" size="200" />
-    </button>
-  </div>
-  <div class="d-card__content d-h84">
-    Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
-  </div>
-  <div class="d-card__footer">
-    <dt-stack direction="row" gap="400">
-      <button type="button" class="d-btn d-btn--sm d-btn--outlined">Button</button>
-    </dt-stack>
-  </div>
-</div>
-'
 vueCode='
-<dt-card max-height="50px" class="d-w264">
+<dt-card class="d-w264" content-class="d-pr0">
   <template #header>
     <dt-text as="p" kind="headline" size="md">Lorem ipsum</dt-text>
     <dt-button
       size="xs"
       importance="clear"
+      kind="muted"
       aria-label="Menu button"
     >
       <template #startIcon>
@@ -294,7 +286,7 @@ vueCode='
     </dt-button>
   </template>
   <template #content>
-    Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.
+    <div class="d-h72 d-pr16" v-dt-scrollbar:never>Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum molestie semper. Morbi finibus nulla turpis, nec molestie mi rutrum.</div>
   </template>
   <template #footer>
     <dt-button

From b3b7f19b0e929458fdd28ce2fec046bbec74c0da Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 17:39:05 -0500
Subject: [PATCH 41/47] update card documentation examples to use vue
 components instead of html

---
 .../docs/components/card.md                   | 22 ++++++++++++++-----
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/card.md b/apps/dialtone-documentation/docs/components/card.md
index ff5cd2719a..ec45eec901 100644
--- a/apps/dialtone-documentation/docs/components/card.md
+++ b/apps/dialtone-documentation/docs/components/card.md
@@ -10,11 +10,16 @@ keywords: ["panel", "container", "box", "d-card", "DtCard", "dt-card", "tile", "
 ---
 
 <code-well-header>
-  <dt-card class="d-w264" header-class="d-bb d-bc-subtle d-py8 d-pr8" footer-class="d-bt d-bc-subtle d-py12">
+  <dt-card
+    class="d-w264"
+    header-class="d-bb d-bc-subtle d-py8 d-pr8"
+    content-class="d-pr0"
+    footer-class="d-bt d-bc-subtle d-py12"
+  >
     <template #header>
       <dt-stack gap="350" direction="row" align="center">
         <dt-icon class="d-fc-tertiary" name="branch" size="300" />
-        <dt-text as="h3" kind="headline" size="md" tone="secondary">Lorem ipsum</dt-text>
+        <dt-text as="h3" kind="headline" size="md" tone="secondary">Branch</dt-text>
       </dt-stack>
       <dt-dropdown navigation-type="arrow-keys" placement="bottom-end">
         <template #anchor="{ attrs }">
@@ -42,10 +47,15 @@ keywords: ["panel", "container", "box", "d-card", "DtCard", "dt-card", "tile", "
       </dt-dropdown>
     </template>
     <template #content>
-      <dt-stack gap="400">
-        <dt-text as="p" kind="body" text-box-trim="start">Content slot. Lorem ipsum dolor sit amet, consectetur adipiscing elit, donec fermentum molestie semper.</dt-text>
-        <dt-text as="p" kind="body" text-box-trim="end">Morbi finibus nulla turpis, nec molestie mi rutrum</dt-text>
-      </dt-stack>
+      <div class="d-h216 d-pr16" v-dt-scrollbar:never>
+        <dt-stack gap="400">
+          <dt-text as="p" kind="body" text-box-trim="start">Main branch, last updated 2 days ago. Currently 3 commits ahead and 1 behind the upstream target.</dt-text>
+          <dt-text as="p" kind="body">All checks passing. Latest build completed in 4m 12s with no warnings or errors.</dt-text>
+          <dt-text as="p" kind="body">Open pull requests: 2 pending review, 1 approved and ready to merge.</dt-text>
+          <dt-text as="p" kind="body">Recent activity includes dependency updates, a hotfix for the login flow, and minor copy changes across settings pages.</dt-text>
+          <dt-text as="p" kind="body" text-box-trim="end">Protected branch rules are enforced. Requires at least one approval before merging.</dt-text>
+        </dt-stack>
+      </div>
     </template>
     <template #footer>
       <dt-button

From f436ae36182cdcfc37c7c8b79bd156ac6f5f75ba Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Tue, 10 Mar 2026 17:41:48 -0500
Subject: [PATCH 42/47] update deprecation notices from error to info kind for
 inverted prop documentation

---
 apps/dialtone-documentation/docs/components/breadcrumbs.md      | 2 +-
 .../dialtone-documentation/docs/components/keyboard-shortcut.md | 2 +-
 apps/dialtone-documentation/docs/components/table.md            | 2 +-
 apps/dialtone-documentation/docs/components/tabs.md             | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/breadcrumbs.md b/apps/dialtone-documentation/docs/components/breadcrumbs.md
index cd34cceeb8..15b3f5758f 100644
--- a/apps/dialtone-documentation/docs/components/breadcrumbs.md
+++ b/apps/dialtone-documentation/docs/components/breadcrumbs.md
@@ -71,7 +71,7 @@ showHtmlWarning />
 
 ### Inverted
 
-<dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
   The <code>inverted</code> prop has been deprecated. Use the
   <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
   instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
diff --git a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
index fdb2fd7d26..4d4640acb2 100644
--- a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
+++ b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
@@ -39,7 +39,7 @@ vueCode='
 
 ### Inverted
 
-<dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
   The <code>inverted</code> prop has been deprecated. Use the
   <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
   instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
diff --git a/apps/dialtone-documentation/docs/components/table.md b/apps/dialtone-documentation/docs/components/table.md
index af38354b53..b5095299e6 100644
--- a/apps/dialtone-documentation/docs/components/table.md
+++ b/apps/dialtone-documentation/docs/components/table.md
@@ -82,7 +82,7 @@ keywords: ["data table", "grid", "rows", "d-table", "DtTable", "dt-table", "data
 
 ### Inverted Style
 
-<dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
   The <code>d-table--inverted</code> modifier has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead.
 </dt-notice>
 
diff --git a/apps/dialtone-documentation/docs/components/tabs.md b/apps/dialtone-documentation/docs/components/tabs.md
index 3e66d0aad9..24af618dd6 100644
--- a/apps/dialtone-documentation/docs/components/tabs.md
+++ b/apps/dialtone-documentation/docs/components/tabs.md
@@ -175,7 +175,7 @@ showHtmlWarning />
 
 ### Inverted
 
-<dt-notice title="Deprecated" kind="error" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
   The <code>inverted</code> prop has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link> when no natural container element exists.
 </dt-notice>
 

From 50b12a549030a38fa2776ad90d417a4851a3fe14 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Wed, 11 Mar 2026 10:42:19 -0500
Subject: [PATCH 43/47] hide-close

---
 apps/dialtone-documentation/docs/components/breadcrumbs.md  | 5 ++---
 apps/dialtone-documentation/docs/components/button.md       | 1 +
 .../docs/components/keyboard-shortcut.md                    | 5 ++---
 apps/dialtone-documentation/docs/components/link.md         | 3 +--
 apps/dialtone-documentation/docs/components/table.md        | 2 +-
 apps/dialtone-documentation/docs/components/tabs.md         | 6 +++---
 6 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/apps/dialtone-documentation/docs/components/breadcrumbs.md b/apps/dialtone-documentation/docs/components/breadcrumbs.md
index 15b3f5758f..b4b5ade6fe 100644
--- a/apps/dialtone-documentation/docs/components/breadcrumbs.md
+++ b/apps/dialtone-documentation/docs/components/breadcrumbs.md
@@ -71,11 +71,10 @@ showHtmlWarning />
 
 ### Inverted
 
-<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16" hide-close>
   The <code>inverted</code> prop has been deprecated. Use the
   <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
-  instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
-  when no natural container element exists.
+  instead.
 </dt-notice>
 
 In place of the `inverted` prop, use the [v-dt-mode directive](mode-island.html#inverting) on the component element.
diff --git a/apps/dialtone-documentation/docs/components/button.md b/apps/dialtone-documentation/docs/components/button.md
index 207711d2f2..0c9e8dd092 100644
--- a/apps/dialtone-documentation/docs/components/button.md
+++ b/apps/dialtone-documentation/docs/components/button.md
@@ -319,6 +319,7 @@ showHtmlWarning />
   title="Deprecated"
   kind="info"
   class="d-wmx100p d-my16"
+  hide-close
 >
   <code>kind="inverted"</code> has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>.
 </dt-notice>
diff --git a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
index 4d4640acb2..90337ea36e 100644
--- a/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
+++ b/apps/dialtone-documentation/docs/components/keyboard-shortcut.md
@@ -39,11 +39,10 @@ vueCode='
 
 ### Inverted
 
-<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16" hide-close>
   The <code>inverted</code> prop has been deprecated. Use the
   <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
-  instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
-  when no natural container element exists.
+  instead.
 </dt-notice>
 
 In place of the `inverted` prop, use the [v-dt-mode directive](mode-island.html#inverting) on the component element.
diff --git a/apps/dialtone-documentation/docs/components/link.md b/apps/dialtone-documentation/docs/components/link.md
index 347c4ae6d2..fd7f21d897 100644
--- a/apps/dialtone-documentation/docs/components/link.md
+++ b/apps/dialtone-documentation/docs/components/link.md
@@ -97,8 +97,7 @@ showHtmlWarning />
 >
   The <code>inverted</code> prop has been deprecated. Use the
   <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link>
-  instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link>
-  when no natural container element exists.
+  instead.
 </dt-notice>
 
 In place of the `inverted` prop, use the [v-dt-mode directive](mode-island.html#inverting) on the component element.
diff --git a/apps/dialtone-documentation/docs/components/table.md b/apps/dialtone-documentation/docs/components/table.md
index b5095299e6..54c7b37d91 100644
--- a/apps/dialtone-documentation/docs/components/table.md
+++ b/apps/dialtone-documentation/docs/components/table.md
@@ -82,7 +82,7 @@ keywords: ["data table", "grid", "rows", "d-table", "DtTable", "dt-table", "data
 
 ### Inverted Style
 
-<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16" hide-close>
   The <code>d-table--inverted</code> modifier has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead.
 </dt-notice>
 
diff --git a/apps/dialtone-documentation/docs/components/tabs.md b/apps/dialtone-documentation/docs/components/tabs.md
index 24af618dd6..d153901e3f 100644
--- a/apps/dialtone-documentation/docs/components/tabs.md
+++ b/apps/dialtone-documentation/docs/components/tabs.md
@@ -175,8 +175,8 @@ showHtmlWarning />
 
 ### Inverted
 
-<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16">
-  The <code>inverted</code> prop has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead, or <dt-link to="mode-island.html#dtmodeisland-component">DtModeIsland</dt-link> when no natural container element exists.
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16" hide-close>
+  The <code>inverted</code> prop has been deprecated. Use the <dt-link to="mode-island.html#inverting">v-dt-mode directive</dt-link> instead.
 </dt-notice>
 
 In place of the `inverted` prop, use the [v-dt-mode directive](mode-island.html#inverting) on the component element.
@@ -286,7 +286,7 @@ showHtmlWarning />
 
 Use the `#startIcon` or `#endIcon` slot on `dt-tab` to add an icon. The slot provides `iconSize` to match the tab's size.
 
-<dt-notice title="Deprecated" kind="warning" class="d-wmx100p d-my16">
+<dt-notice title="Deprecated" kind="info" class="d-wmx100p d-my16" hide-close>
   The <code>#icon</code> slot has been deprecated. Use <code>#startIcon</code> or <code>#endIcon</code> instead.
 </dt-notice>
 

From c41f92f8afb65e83f7299ae1dcaf5d453ba55724 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Wed, 11 Mar 2026 10:42:29 -0500
Subject: [PATCH 44/47] track resolved arg in directive state to prevent
 unnecessary observer teardown on re-render

---
 .../directives/mode_directive/mode.js         | 10 +++++----
 .../directives/mode_directive/mode.test.js    | 21 +++++++++++++++++++
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode.js b/packages/dialtone-vue/directives/mode_directive/mode.js
index daff17ae4c..5772a7a271 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.js
@@ -24,18 +24,19 @@ export const DtModeDirective = {
       },
 
       updated (el, binding) {
+        const prev = instances.get(el);
         const valueChanged = binding.value !== binding.oldValue;
-        const argChanged = binding.arg !== binding.oldArg;
+        const resolvedArg = resolveArg(binding.arg);
+        const argChanged = resolvedArg !== prev?.arg;
         if (!valueChanged && !argChanged) return;
 
-        cleanup(instances.get(el));
+        cleanup(prev);
         removeAttributes(el);
         instances.delete(el);
 
         if (binding.value === false) return;
 
-        const mode = resolveArg(binding.arg);
-        const state = applyMode(el, mode);
+        const state = applyMode(el, resolvedArg);
         instances.set(el, state);
       },
 
@@ -65,6 +66,7 @@ export const DtModeDirective = {
 
     function applyMode (el, mode) {
       const state = {
+        arg: mode,
         contrastObserver: null,
         modeObserver: null,
       };
diff --git a/packages/dialtone-vue/directives/mode_directive/mode.test.js b/packages/dialtone-vue/directives/mode_directive/mode.test.js
index 661c7326cb..f219f1203e 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.test.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.test.js
@@ -174,6 +174,27 @@ describe('DtModeDirective Tests', () => {
       expect(wrapper.find('[data-qa="target"]').attributes('data-dt-mode')).toBeUndefined();
     });
 
+    it('should not teardown observers on re-render when arg is unchanged', async () => {
+      const disconnectSpy = vi.spyOn(MutationObserver.prototype, 'disconnect');
+
+      wrapper = mount({
+        template: '<section v-dt-mode:dark data-qa="target">{{ count }}</section>',
+        data () {
+          return { count: 0 };
+        },
+      }, {
+        global: { plugins: [DtModeDirective] },
+      });
+
+      disconnectSpy.mockClear();
+
+      // Trigger a re-render without changing the directive arg or value
+      await wrapper.setData({ count: 1 });
+
+      expect(disconnectSpy).not.toHaveBeenCalled();
+      disconnectSpy.mockRestore();
+    });
+
     it('should re-initialize when dynamic arg changes', async () => {
       wrapper = mount({
         template: '<section v-dt-mode:[mode] data-qa="target">Content</section>',

From 27ab7dc820080cd8a27579a9a004f299fd7ee1aa Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Wed, 11 Mar 2026 21:20:08 -0500
Subject: [PATCH 45/47] mode directive it

---
 .../baseComponents/tokens/TokenTable.vue      | 198 +++++++++---------
 .../docs/.vuepress/views/ColorsCatalog.vue    |   6 +-
 .../docs/components/table.md                  |  30 ---
 3 files changed, 101 insertions(+), 133 deletions(-)

diff --git a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue
index 8f29605fb2..357683775f 100644
--- a/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokenTable.vue
@@ -1,107 +1,105 @@
 <template>
   <div v-dt-scrollbar:never class="d-hmx464 d-bar8 d-ba d-bc-subtle">
-    <dt-mode-island :mode="mode">
-      <table class="d-table dialtone-doc-table">
-        <thead class="d-bgc-primary d-ps-sticky d-zi-base1 d-t0">
-          <tr>
-            <th
-              scope="col"
-              class="d-p0 d-bbw0 d-tt-none"
-            >
-              <div class="d-p16 d-bb d-bbw1">
-                Preview
-              </div>
-            </th>
-            <th
-              scope="col"
-              class="d-p0 d-bbw0 d-tt-none"
-            >
-              <div class="d-p16 d-bb d-bbw1">
-                Token Name
-              </div>
-            </th>
-            <th
-              v-if="showValue"
-              scope="col"
-              class="d-p0 d-bbw0 d-tt-none d-ta-right"
-            >
-              <div class="d-p16 d-bb d-bbw1">
-                {{ tokenList ? "REM" : "Value" }}
-              </div>
-            </th>
-            <th
-              v-show="!!tokenList"
-              scope="col"
-              class="d-p0 d-bbw0"
-            >
-              <div class="d-p16 d-bb d-bbw1">
-                PX
-              </div>
-            </th>
-          </tr>
-        </thead>
-        <tbody>
-          <tr
-            v-for="({ exampleValue, exampleName, name, tokenValue, description, deprecated }) in shownTokens"
-            :key="name"
-            tabindex="0"
-            @mouseenter="onEnterRow(name)"
-            @mouseleave="onLeaveRow()"
-            @focusin="onEnterRow(name)"
-            @focusout="onLeaveRow()"
+    <table v-dt-mode:[mode] class="d-bgc-primary d-table dialtone-doc-table">
+      <thead class="d-bgc-primary d-ps-sticky d-zi-base1 d-t0">
+        <tr>
+          <th
+            scope="col"
+            class="d-p0 d-bbw0 d-tt-none"
           >
-            <td class="d-w72 sm:d-w128 d-box-content">
-              <token-example
-                :category="category"
-                :name="exampleName || name"
-                :value="exampleValue.toString()"
-                :mode="mode"
-              />
-            </td>
-            <th scope="row">
-              <dt-badge v-if="deprecated" type="critical" kind="label" text="Deprecated" />
-              <dt-stack
-                direction="row"
-                gap="300"
-                align="center"
-                class="token-name"
-              >
-                <dt-text as="p" kind="label" size="md">
-                  {{ name }}
-                </dt-text>
-                <div class="d-w32">
-                  <dt-lazy-show :show="showCopyButton(name)">
-                    <copy-button
-                      v-if="!isSmallDevice"
-                      :text="name"
-                      aria-label="Copy Token"
-                    />
-                  </dt-lazy-show>
-                </div>
-              </dt-stack>
-              <dt-text kind="body" size="sm" tone="tertiary">
-                {{ description }}
-              </dt-text>
-              <token-value
-                v-if="isSmallDevice && showValue"
-                :token-value="valueToString(tokenValue)"
-                :tokens="tokens"
-              />
-            </th>
-            <td v-if="!isSmallDevice && showValue" class="d-ta-right d-wmx164">
-              <dt-text as="span" kind="code" size="md" class="d-fc-blue-800">
-                <token-value :token-value="valueToString(tokenValue)" :tokens="tokens" />
-              </dt-text>
-            </td>
-            <td v-if="!!tokenList">
-              <dt-text as="div" kind="code" size="md" class="d-docsite-code d-wmx264">
-                {{ remToPixels(tokenValue) }}
+            <div class="d-p16 d-bb d-bbw1">
+              Preview
+            </div>
+          </th>
+          <th
+            scope="col"
+            class="d-p0 d-bbw0 d-tt-none"
+          >
+            <div class="d-p16 d-bb d-bbw1">
+              Token Name
+            </div>
+          </th>
+          <th
+            v-if="showValue"
+            scope="col"
+            class="d-p0 d-bbw0 d-tt-none d-ta-right"
+          >
+            <div class="d-p16 d-bb d-bbw1">
+              {{ tokenList ? "REM" : "Value" }}
+            </div>
+          </th>
+          <th
+            v-show="!!tokenList"
+            scope="col"
+            class="d-p0 d-bbw0"
+          >
+            <div class="d-p16 d-bb d-bbw1">
+              PX
+            </div>
+          </th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr
+          v-for="({ exampleValue, exampleName, name, tokenValue, description, deprecated }) in shownTokens"
+          :key="name"
+          tabindex="0"
+          @mouseenter="onEnterRow(name)"
+          @mouseleave="onLeaveRow()"
+          @focusin="onEnterRow(name)"
+          @focusout="onLeaveRow()"
+        >
+          <td class="d-w72 sm:d-w128 d-box-content">
+            <token-example
+              :category="category"
+              :name="exampleName || name"
+              :value="exampleValue.toString()"
+              :mode="mode"
+            />
+          </td>
+          <th scope="row">
+            <dt-badge v-if="deprecated" type="critical" kind="label" text="Deprecated" />
+            <dt-stack
+              direction="row"
+              gap="300"
+              align="center"
+              class="token-name"
+            >
+              <dt-text as="p" kind="label" size="md">
+                {{ name }}
               </dt-text>
-            </td>
-          </tr>
-        </tbody>
-      </table>
-    </dt-mode-island>
+              <div class="d-w32">
+                <dt-lazy-show :show="showCopyButton(name)">
+                  <copy-button
+                    v-if="!isSmallDevice"
+                    :text="name"
+                    aria-label="Copy Token"
+                  />
+                </dt-lazy-show>
+              </div>
+            </dt-stack>
+            <dt-text kind="body" size="sm" tone="tertiary">
+              {{ description }}
+            </dt-text>
+            <token-value
+              v-if="isSmallDevice && showValue"
+              :token-value="valueToString(tokenValue)"
+              :tokens="tokens"
+            />
+          </th>
+          <td v-if="!isSmallDevice && showValue" class="d-ta-right d-wmx164">
+            <dt-text as="span" kind="code" size="md" class="d-fc-blue-800">
+              <token-value :token-value="valueToString(tokenValue)" :tokens="tokens" />
+            </dt-text>
+          </td>
+          <td v-if="!!tokenList">
+            <dt-text as="div" kind="code" size="md" class="d-docsite-code d-wmx264">
+              {{ remToPixels(tokenValue) }}
+            </dt-text>
+          </td>
+        </tr>
+      </tbody>
+    </table>
   </div>
 </template>
 
diff --git a/apps/dialtone-documentation/docs/.vuepress/views/ColorsCatalog.vue b/apps/dialtone-documentation/docs/.vuepress/views/ColorsCatalog.vue
index a903933337..c5ce402ff9 100644
--- a/apps/dialtone-documentation/docs/.vuepress/views/ColorsCatalog.vue
+++ b/apps/dialtone-documentation/docs/.vuepress/views/ColorsCatalog.vue
@@ -1,6 +1,6 @@
 <template>
-  <dt-mode-island
-    :mode="mode"
+  <div
+    v-dt-mode:[mode]
     class="d-p16 d-bgc-secondary"
   >
     <dt-stack as="section" gap="500">
@@ -14,7 +14,7 @@
         />
       </div>
     </dt-stack>
-  </dt-mode-island>
+  </div>
 </template>
 
 <script setup>
diff --git a/apps/dialtone-documentation/docs/components/table.md b/apps/dialtone-documentation/docs/components/table.md
index 54c7b37d91..7e65c1b6fa 100644
--- a/apps/dialtone-documentation/docs/components/table.md
+++ b/apps/dialtone-documentation/docs/components/table.md
@@ -160,36 +160,6 @@ keywords: ["data table", "grid", "rows", "d-table", "DtTable", "dt-table", "data
 </table>
 ```
 
-<code-well-header>
-  <dt-mode-island class="d-p16 d-bar8">
-    <table class="d-table dialtone-doc-table d-table--striped">
-      <caption class="d-table__caption">Office List</caption>
-      <thead>
-        <tr>
-          <th scope="col">Office</th>
-          <th scope="col">Country</th>
-          <th scope="col" width="10%">Employees</th>
-          <th scope="col">Contact</th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr v-for="i in examples">
-          <th scope="row">{{ i.office }}</th>
-          <td>{{ i.country }}</td>
-          <td>{{ i.size }}</td>
-          <td>{{ i.contact }}</td>
-        </tr>
-      </tbody>
-    </table>
-  </dt-mode-island>
-</code-well-header>
-
-```html
-<dt-mode-island>
-  <table class="d-table d-table--striped">...</table>
-</dt-mode-island>
-```
-
 ## Classes
 
 <component-class-table component-name="table" />

From 09491c6b37469f7f3f570479927ea5136c12c9f9 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Fri, 13 Mar 2026 11:02:12 -0500
Subject: [PATCH 46/47] add value = false example

---
 .../mode_directive_default.story.vue          | 46 ++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue b/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
index 533b67afcf..5e6ab6d725 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
+++ b/packages/dialtone-vue/directives/mode_directive/mode_directive_default.story.vue
@@ -124,6 +124,48 @@
       </dt-stack>
     </div>
 
+    <dt-text
+      as="h3"
+      kind="headline"
+      size="lg"
+    >
+      Disabled (value = false)
+    </dt-text>
+    <dt-stack
+      gap="400"
+      direction="row"
+    >
+      <section
+        v-dt-mode:invert="false"
+        class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8 d-fl1"
+      >
+        <dt-text
+          kind="body"
+          tone="primary"
+        >
+          v-dt-mode:invert="false" — no mode applied
+        </dt-text>
+      </section>
+      <section
+        v-dt-mode:dark="enabled"
+        class="d-bgc-secondary d-p16 d-ba d-bc-subtle d-bar8 d-fl1"
+      >
+        <dt-stack gap="400">
+          <dt-text
+            kind="body"
+            tone="primary"
+          >
+            v-dt-mode:dark="{{ enabled }}" — toggle to compare
+          </dt-text>
+          <dt-toggle
+            :checked="enabled"
+            label="Enable mode"
+            @update:checked="enabled = $event"
+          />
+        </dt-stack>
+      </section>
+    </dt-stack>
+
     <dt-text
       as="h3"
       kind="headline"
@@ -158,12 +200,14 @@
 import DtStack from '@/components/stack/stack.vue';
 import DtText from '@/components/text/text.vue';
 import DtSelectMenu from '@/components/select_menu/select_menu.vue';
+import DtToggle from '@/components/toggle/toggle.vue';
 
 export default {
   name: 'DtModeDirectiveDefault',
-  components: { DtStack, DtText, DtSelectMenu },
+  components: { DtStack, DtText, DtSelectMenu, DtToggle },
   data () {
     return {
+      enabled: true,
       dynamicMode: 'invert',
       modeOptions: [
         { value: 'invert', label: 'invert' },

From 9e7df8f4d5ea2446807098fb2cf7220c4a4f02f1 Mon Sep 17 00:00:00 2001
From: francisrupert <francis.rupert@dialpad.com>
Date: Fri, 13 Mar 2026 11:04:37 -0500
Subject: [PATCH 47/47] add JSDoc with usage examples

---
 .../directives/mode_directive/mode.js         | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/packages/dialtone-vue/directives/mode_directive/mode.js b/packages/dialtone-vue/directives/mode_directive/mode.js
index 5772a7a271..a0f55d788f 100644
--- a/packages/dialtone-vue/directives/mode_directive/mode.js
+++ b/packages/dialtone-vue/directives/mode_directive/mode.js
@@ -10,6 +10,27 @@ const SUGGESTIONS = {
   inverted: 'invert',
 };
 
+/**
+ * v-dt-mode directive — applies a color mode (light, dark, or invert) to an element.
+ *
+ * Sets `data-dt-mode` and `data-dt-contrast` attributes so descendant token-based
+ * styles (`d-fc-primary`, `d-bgc-secondary`, etc.) resolve to the correct palette.
+ *
+ * @example
+ * // Explicit modes
+ * <section v-dt-mode:dark>Dark content</section>
+ * <section v-dt-mode:light>Light content</section>
+ *
+ * // Invert nearest parent mode (default when no arg)
+ * <section v-dt-mode>Inverted content</section>
+ * <section v-dt-mode:invert>Same as above</section>
+ *
+ * // Dynamic arg
+ * <section v-dt-mode:[reactiveMode]>Reactive mode</section>
+ *
+ * // Disable with false value
+ * <section v-dt-mode:dark="false">No mode applied</section>
+ */
 export const DtModeDirective = {
   name: 'dt-mode-directive',
   install (app) {