feat(mode-directive, mode-island): DLT-3067 add v-dt-mode directive

[Francis Rupert (francisrupert)]

Add v-dt-mode directive

🛠️ Type Of Change

• Feature

📖 Jira Ticket

DLT-3067

📖 Description

Bottom line

Before

<dt-mode-island>
  <el>Inverted (default)</el>
</dt-mode-island>
<dt-mode-island mode="inverted">
  <el>Inverted (explicit)</el>
</dt-mode-island>
<dt-mode-island mode="light">
  <el>Light (explicit)</el>
</dt-mode-island>
<dt-mode-island mode="dark">
  <el>Dark (explicit)</el>
</dt-mode-island>

After

<el v-dt-mode>Inverted (default)</el>
<el v-dt-mode:invert>Inverted (explicit)</el>
<el v-dt-mode:light>Light (explicit)</el>
<el v-dt-mode:dark>Dark (explicit)</el>

Introduces the v-dt-mode directive, a lightweight alternative to DtModeIsland that applies light, dark, or invert theming directly to any element — no wrapper node required. The directive observes ancestor mode context and computes the opposite when using invert, reacting dynamically to app-level theme changes.

Additional changes:

• Move mode island styles from component layer to base layer
• Fix scrollbar CSS layer assignment
• Update inverted prop deprecation notices across components to recommend v-dt-mode instead of DtModeIsland
• Add file-level disable comment support to the validate-layers PostCSS plugin
• Migrate doc site components to dt-text, dt-link, and dt-button
• Refine mode island demo layout and add code syntax color variables

📦 Cross-Package Impact

Package	Changes	Downstream Impact
dialtone-vue	New v-dt-mode directive; split-button alpha/omega → start/end rename	MCP server data should be updated for directive
dialtone-css	CSS layer fixes (scrollbar, mode island); validate-layers plugin improvement; button/table/mode-island Less changes	dialtone-vue depends on these styles
dialtone-tokens	Dark theme token updates	Cascades to CSS and Vue
dialtone-documentation	Extensive doc updates (mode-island, split-button, link, text, table, etc.); doc site component migrations	—

Dependency flow: tokens → CSS → Vue → docs/MCP/language-server

📄 Documentation Artifacts

Artifact	Status	Notes
Vue source	✅ Updated	New v-dt-mode directive added; split-button subcomponents renamed
Tests	✅ Updated	Mode directive unit tests and updated split-button tests included
Storybook stories	✅ Updated	Mode directive stories + split-button stories updated
Component docs JSON	⚠️ Needs rebuild	scripts/build-dialtone-vue-docs.mjs should be run to pick up the new directive export
VuePress docs	✅ Updated	mode-island.md, split-button.md, and related pages updated
MCP server data	⚠️ Needs attention	New v-dt-mode directive not yet registered in packages/dialtone-mcp-server/src/data.ts

💡 Context

DtModeIsland wraps content in an extra DOM node just to set data-dt-mode. Many real use cases already have a natural container (<section>, <nav>, <aside>), making the wrapper unnecessary. The v-dt-mode directive eliminates this overhead while providing the same reactive theming — including invert mode which computes the opposite mode from context, reacting when ancestors change.

📝 Checklist

For all PRs:

• I have ensured no private Dialpad links or info are in the code or pull request description (Dialtone is a public repo!).
• I have reviewed my changes.
• I have added all relevant documentation.
• I have considered the performance impact of my change.

For all Vue changes:

• I have added / updated unit tests.
• I have validated components with a screen reader.
• I have validated components keyboard navigation.

For all CSS changes:

• I have used design tokens whenever possible.
• I have considered how this change will behave on different screen sizes.
• I have visually validated my change in light and dark mode.
• I have used gap or flexbox properties for layout instead of margin whenever possible.

🔮 Next Steps

• Register v-dt-mode in MCP server data
• Rebuild component docs JSON
• Follow-up: deprecate DtModeIsland in favour of v-dt-mode directive

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b3b7f19b0e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "codex (@codex) address that feedback".

[github-actions]

✔️ Deploy previews ready!
😎 Dialtone documentation preview: https://dialtone.dialpad.com/deploy-previews/pr-1109/
😎 Dialtone-vue preview: https://dialtone.dialpad.com/vue/deploy-previews/pr-1109/

[Ignacio Ropolo (iropolo)]

I would add a when to use directive vs component. Im sure I saw something similar for tooltip somewhere.
In this case it can be something like:
-> Directive: When you already have a container element
-> Component: When you need the background-color and wrapper element

[Ignacio Ropolo (iropolo)]

Looks good to me, and thanks for the laugh seeing the PR image!!