refactor(tokens,css,link,text,breadcrumbs,input-group,split-button): tokens, CSS foundation, deprecations, tooling DLT-3011 DLT-2961 DLT-3068 DLT-3069 DLT-3070 DLT-3071 DLT-3072 (#1092)

Author: francisrupert

.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()`.

.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.

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>

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>

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"

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>

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>

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>

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>