feat(dialtone-css, dialtone-documentation): DLT-3363 add theme-to-mode migration guide and codemod

[Belu Montoya (belumontoya)]

🛠️ Type Of Change

• Feature
• Documentation

📖 Jira Ticket

DLT-3363

📖 Description

Adds a migration guide and codemod for consumers moving from the legacy setTheme() theming API to the new layered API (setMode / setBrand / setContrast / initDialtoneTheme) shipping in next.

What's new

• New migration guide page at /guides/migration/theme-to-mode/ covering the deprecation, root attribute changes (data-dt-theme → data-dt-mode + data-dt-brand + data-dt-contrast), and recommendation to adopt the v-dt-mode directive for inverted regions.
• New theme-to-mode config in dialtone-migration-helper. Run with npx dialtone-migration-helper --cwd ./src and select theme to mode.
• 36 node:test cases covering each codemod transformation plus edge cases.

What's patched (existing docs)

• guides/theme-and-mode/index.md — fixed 5 stale module paths (@dialpad/dialtone/themes/config → @dialpad/dialtone-tokens/themes/config) and added a cross-link to the new dedicated migration guide.
• guides/getting-started/index.md — same module path fix on the Quick Start example.
• dialtone/whats-new/posts/2024-8-1.md — [!WARNING] notice block at the top redirecting readers to the new migration guide. Body unchanged (historical post).

💡 Context

Without this guide, consumers adopting next will hit silent breakage in three places: call sites still importing setTheme from the old @dialpad/dialtone module path, JS code reading data-dt-theme from the root, and CSS using [data-dt-theme=...] selectors. The codemod handles the obvious patterns; the guide explains the rest (especially the manual review needed for data-dt-theme="invert" regions, where a static rewrite is unsafe because the v-dt-mode directive resolves dynamically against the live parent mode).

Codemod scope

• Import path: @dialpad/dialtone/themes/<name> → @dialpad/dialtone-tokens/themes/<name> (filename unchanged).
• setTheme(KnownTheme) → initDialtoneTheme(KnownTheme, 'mode') for the eight legacy theme identifiers (Dp/Tmo/Expressive/ExpressiveSm × Light/Dark).
• setTheme(dynamicVar) → preserved + leading // TODO comment for manual review (no AST means we can't safely rewrite).
• data-dt-theme → data-dt-mode in HTML attributes, JS setAttribute/getAttribute calls, CSS attribute selectors.
• [data-dt-theme="invert"] CSS selectors → flagged with a /* TODO */ comment for v-dt-mode adoption review.

Negative-case coverage: data-dt-theme-x longer attributes, myObj.setTheme() unrelated methods, and already-migrated imports are all left untouched.

What's NOT included (separate Jiras to be created)

• ESLint rule for setTheme deprecation
• Stylelint rule for [data-dt-theme] selectors
• Removal of setTheme from the source
• Regenerating the stale dist/types/themes/config.d.ts (only declares legacy setTheme)

📝 Checklist

• I have ensured no private Dialpad links or info are in the code or pull request description.
• I have reviewed my changes.
• I have added all relevant documentation.
• I have considered the performance impact of my change.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 8ca32fe4-08dd-40f2-b10c-5c776018d234

📥 Commits

Reviewing files that changed from the base of the PR and between a7f76f5 and 8b226fa.

📒 Files selected for processing (2)

• apps/dialtone-documentation/docs/guides/migration/index.md
• apps/dialtone-documentation/docs/guides/migration/theme-to-mode/index.md

---

Adds a migration guide and codemod to move from deprecated setTheme() to the layered API (initDialtoneTheme, setMode, setBrand, setContrast, setMaterial); updates docs, tests, and removes incorrect import-path rewrites; flags invert selectors for manual review.

Overall Judgement: ✅ Ready to merge — P0 import-path and P1 Material issues were fixed, tests updated, and remaining items are documentation-facing or review TODOs.

Walkthrough

Adds a "Theme to Mode" migration guide and site nav entry, implements a migration-helper config that rewrites legacy setTheme()/data-dt-theme patterns to the layered theming API, and adds test examples and a test suite validating the transformations.

Changes

Theme-to-Mode Migration: Guide and Helper

Layer / File(s)	Summary
Migration guide documentation and site integration apps/dialtone-documentation/docs/_data/site-nav.json, apps/dialtone-documentation/docs/guides/migration/index.md, apps/dialtone-documentation/docs/dialtone/whats-new/posts/2024-8-1.md, apps/dialtone-documentation/docs/guides/migration/theme-to-mode/index.md	Navigation, migration index, and deprecation warning updated. New comprehensive guide documents the breaking change, explains startup migration to initDialtoneTheme(Dp, 'light'), runtime mode switching via setMode('dark'), brand changes, contrast toggling, material application, and attribute/selector rewrites from data-dt-theme to data-dt-mode. Includes special handling for invert cases requiring manual v-dt-mode directive adoption.
Migration helper configuration and transformation rules packages/dialtone-css/lib/build/js/dialtone_migration_helper/configs/theme-to-mode.mjs	Regex transformation rules rewrite setTheme(KnownLight|KnownDark) to initDialtoneTheme(identifier, 'light'|'dark'), preserve dynamic calls with TODO markers, rename data-dt-theme to data-dt-mode across HTML/Vue/JSX attributes, JavaScript setAttribute/getAttribute/removeAttribute/hasAttribute calls, and CSS selectors, and flag invert selectors for manual review.
Migration helper test examples and validation packages/dialtone-css/lib/build/js/dialtone_migration_helper/tests/theme-to-mode-test-examples.vue, packages/dialtone-css/lib/build/js/dialtone_migration_helper/tests/theme-to-mode.test.mjs	Vue example demonstrates legacy data-dt-theme="light" and setTheme imports/calls. Node.js test suite validates setTheme() rewrites, HTML attribute migrations, JavaScript API rewrites, CSS selector transformations, and invert value handling with TODO insertion.

Suggested labels

no-visual-test

Suggested reviewers

• francisrupert
• braddialpad
• ninarepetto

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/dlt-3363-theme-to-mode-migration-guide

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Francis Rupert (francisrupert)]

Belu Montoya (@belumontoya) I know you're still in Draft mode, but I figured I'd jump in since I merged #1252 and this is now more meaningfully out of date than just merge conflicts:

1. Opposite import-path direction. 1260 migrates consumers toward @dialpad/dialtone-tokens/themes/config. The work that just merged to next standardized toward @dialpad/dialtone/themes/config meta-package. Its docs now contradict the migration guide.
2. Documents a 3-dimensional theming system when there are now 4. Material is the new dimension, and should be added to the migration guide.

The codemod's setTheme → initDialtoneTheme and data-dt-theme → data-dt-mode rewrites are still correct (the legacy API hasn't moved). Only the import-path rewrite and the "what does the new system look like" framing are stale.

What's stale

Direction conflict: meta vs. sub-package

PR #1260's "What Changed" table claims:

	Before	After
Import path	@dialpad/dialtone/themes/config	@dialpad/dialtone-tokens/themes/config

This direction is exactly backwards relative to what landed on next. The just-merged refactor standardized theme-and-mode/index.md, getting-started/index.md, README.md, and the architecture doc all on @dialpad/dialtone/themes/config. The migration guide and codemod tell users to do the opposite.

The codemod (packages/dialtone-css/lib/build/js/dialtone_migration_helper/configs/theme-to-mode.mjs, lines 47–50):

{                                                                                                                                                                                                                                                                                                                      
  from: /(['"])@dialpad\/dialtone\/themes\//g,                                                                                                                                                                                                                                                                           
  to: (_match, quote) => `${quote}@dialpad/dialtone-tokens/themes/`,                                                                                                                                                                                                                                                     
},                                                                                                                                                                                                                                                                                                                       

This expression moves consumers in the wrong direction. Anyone who runs npx dialtone-migration-helper after the PR ships ends up on a path the freshly-updated docs say not to use.

File-level merge conflicts on rebase

PR #1260 changes three locations against files that just got merged:

• guides/getting-started/index.md line 35: @dialpad/dialtone/themes/config → @dialpad/dialtone-tokens/themes/config. Conflict. The merged change leaves it on the meta-package.
• guides/theme-and-mode/index.md lines 29, 62, 71, 82, 248: 5 imports flipped meta → sub. Conflict. The merged change standardized all on meta.
• guides/theme-and-mode/index.md lines 211–214: adds an [!INFO] cross-link block in the Migrating-from-Legacy section. Possible context drift. The merged change simplified the surrounding section; the chosen anchor may need adjustment, but the cross-link itself is fine.

Migration guide content gaps

The new file guides/migration/theme-to-mode/index.md (281 lines) needs material added in five places:

1. TLDR section. Lists the new API as initDialtoneTheme() for startup, setMode() / setBrand() / setContrast() for runtime switching. Missing setMaterial().
2. "Why" section. Lists three orthogonal dimensions (Mode, Brand, Contrast). Missing the fourth (Material) and its rationale.
3. "What Changed" table. The Import path row is wrong-direction post-merge (should be removed). No data-dt-material row. No row for setMaterial.
4. "Root attribute" section's HTML example shows <html data-dt-mode="light" data-dt-brand="dp" data-dt-contrast="default">. Missing data-dt-material="sandstone".
5. "Quick Checklist" mentions smoke-testing mode, brand, contrast. No mention of material.

The guide also does not mention brand-locked materials, getBrandMaterial / hasBrandMaterialLock, the setBrand side effect, or the attribute-only switching mechanism. These aren't strictly required for migration from legacy, but the guide reads as a "current state of the new system" reference, which migrators will treat as authoritative.

What's still correct

The setTheme → initDialtoneTheme rewrites for the 8 legacy identifiers (DpLight / DpDark / TmoLight / TmoDark / Expressive ×4), the data-dt-theme → data-dt-mode HTML/JS/CSS rewrites, the v-dt-mode adoption guidance for data-dt-theme="invert" regions, the 36 codemod test cases, and the "Manual Review for v-dt-mode Candidates" section are all unchanged in correctness. The just-merged work didn't touch the legacy API or mode handling, so most of the PR's value is preserved.

What needs to happen, in priority order

P0: Direction reconciliation (blocks merge cleanly)

Choose: meta-package (where the merged change landed) or sub-package (PR #1260's current direction). Since the meta-package version is already merged to next, defending that direction is the lower-friction path:

• Remove the import-path rewrite expression from the codemod (from: /(['"])@dialpad\/dialtone\/themes\//g).
• Drop the "Import path" row from the migration guide's "What Changed" table.
• Drop the "Import path" Before/After code block in the migration guide (~lines 60–90 of the new file).
• Drop the "Theme JSON imports" Before/After block (~lines 92–124). The legacy theme-module paths can stay on whatever package they're on; the codemod no longer touches them.
• Drop import { setContrast } from '@dialpad/dialtone-tokens/themes/config' from the Contrast Before/After example; revert to meta-package.
• Reconcile the 6 conflicting line-changes in getting-started/index.md and theme-and-mode/index.md. They become no-ops after rebase.
• Update relevant codemod test cases that asserted the import-path rewrite happens.

P1: Add material as a 4th dimension to the migration guide

• Update TLDR and "Why" sections: 3 dimensions → 4.
• Add setMaterial to the function list.
• Add data-dt-material row to "What Changed" table.
• Add data-dt-material="sandstone" to the HTML root-element example.
• Add Material to the smoke-test checklist.

P2: Optional contextual additions

• Brief paragraph on brand-locked materials with a cross-link to /guides/theme-and-mode/#brand-locked-materials.
• Note that material switching is attribute-only (vs. brand/contrast injection).

[Belu Montoya (belumontoya)]

Thanks Francis Rupert (@francisrupert) — pushed a commit addressing this. Summary of what changed:

P0 — direction reconciliation ✅

Verified against origin/next: meta-package (@dialpad/dialtone/themes/) is the canonical direction post-#1252. Removed the wrong-direction rewrite from the codemod and the guide.

Codemod (packages/dialtone-css/lib/build/js/dialtone_migration_helper/configs/theme-to-mode.mjs)

• Removed expression ci: test #1 (the @dialpad/dialtone/themes/ → @dialpad/dialtone-tokens/themes/ rewrite)
• Renumbered the remaining 6 expressions and updated the header docstring

Codemod tests (theme-to-mode.test.mjs)

• Removed the 11 import-path test cases (the describe('import path: ...') block). 25/25 remaining tests pass.

Migration guide (guides/migration/theme-to-mode/index.md)

• Removed the "Import path" bullet from the TLDR
• Removed the "Import path" row from the "What Changed" table
• Removed both ### Import path and ### Theme JSON imports Before/After sections
• Reverted the setContrast/HighContrast import in the Contrast example back to the meta-package

guides/theme-and-mode/index.md — fixed one leftover sub-package reference on line 90 (setMode import). The rest of the file was already on the meta-package after the merge from next.

guides/getting-started/index.md — no changes needed; already on the meta-package.

P1 — Material as 4th dimension ✅

Added Material in five places in the migration guide:

• TLDR: setMaterial() added to the runtime functions list; data-dt-material added to the new attributes list
• Why: changed "three orthogonal dimensions" → "four"; added Material bullet (with the full set: sandstone default, plus steel, graphite, iron, amethyst, jade)
• What Changed table: added Material row (setMaterial('sandstone')) and Root attribute (material) row (data-dt-material="sandstone")
• Root HTML example: added data-dt-material="sandstone"
• Quick Checklist smoke-test: "...apply a material if your app uses one"

P2 — brand-locked materials

Kept minimal: added a one-line cross-link to /guides/theme-and-mode/#brand-locked-materials from the Material bullet in the "Why" section, rather than duplicating getBrandMaterial / hasBrandMaterialLock / brand-lock behavior into this guide. Reasoning: this is a migration guide from the legacy API; brand-lock semantics are advanced features of the new API and live more cleanly in the theme-and-mode reference. Happy to expand if you think it's needed for migrators specifically.

Let me know if I've missed anything.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/dialtone-documentation/docs/guides/migration/index.md`:
- Around line 45-46: The Framework migration table has duplicated/incorrect
checklist numbers (rows for "Theme to Mode" and "Vue 2 Removal" show 15/16 while
the previous section already reached 16), so update the numeric sequence to
continue rather than reset: change the numeric prefixes for the "Theme to Mode"
and "Vue 2 Removal" rows to 17 and 18 respectively (or apply a consistent
per-table restart policy across all migration tables), and scan other table
entries to ensure numbering continuity for entries like "Theme to Mode" and "Vue
2 Removal".

In `@apps/dialtone-documentation/docs/guides/migration/theme-to-mode/index.md`:
- Around line 206-207: The import path for DtModeDirective is incorrect; change
the import statement that references DtModeDirective from
'`@dialpad/dialtone-vue`' to the public consumer package '`@dialpad/dialtone/vue`',
keeping the subsequent usage app.use(DtModeDirective) unchanged so the directive
is loaded from the correct exported module.

In
`@packages/dialtone-css/lib/build/js/dialtone_migration_helper/configs/theme-to-mode.mjs`:
- Around line 64-66: The RegExp used to match setTheme calls (the new RegExp
using `(?<!\\.)setTheme\\(\\s*(?!(${KNOWN_PATTERN})\\s*\\))([^)]*)\\)` ) fails
on nested parentheses (e.g., setTheme(getTheme()) or ternaries with nested
calls); replace this naive capture with a safe parser: either implement a small
balanced-parenthesis scanner that locates the matching closing `)` for the
setTheme(...) argument or switch to AST-based detection (parse source to an AST
and find CallExpression nodes where callee.name === "setTheme"), ensuring you
still skip known constants via KNOWN_PATTERN; update the logic around where this
RegExp is used so the TODO wrapper is applied to well-formed full argument text
only.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: ea2e5788-5a18-4623-abc9-8e34db329f36

📥 Commits

Reviewing files that changed from the base of the PR and between daace31 and a7f76f5.

📒 Files selected for processing (7)

• apps/dialtone-documentation/docs/_data/site-nav.json
• apps/dialtone-documentation/docs/dialtone/whats-new/posts/2024-8-1.md
• apps/dialtone-documentation/docs/guides/migration/index.md
• apps/dialtone-documentation/docs/guides/migration/theme-to-mode/index.md
• packages/dialtone-css/lib/build/js/dialtone_migration_helper/configs/theme-to-mode.mjs
• packages/dialtone-css/lib/build/js/dialtone_migration_helper/tests/theme-to-mode-test-examples.vue
• packages/dialtone-css/lib/build/js/dialtone_migration_helper/tests/theme-to-mode.test.mjs

[github-actions]

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

[Belu Montoya (belumontoya)]

Francis Rupert (@francisrupert) mind checking again? thanks

[Francis Rupert (francisrupert)]

Belu Montoya (@belumontoya), This looks great! I'm refraining from approving, though I approve from a design perspective and defer to technical review by a dialtone engineer. Thanks!

[Ignacio Ropolo (iropolo)]

Thanks Belu!