feat(tokens): DLT-2802 DLT-2563 layered theming system and mode island component (#945)

Co-authored-by: Brad Paugh <brad.paugh@dialpad.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

README.md

@@ -22,92 +22,145 @@ npm install @dialpad/dialtone @dialpad/i18n
 
 ```shell
 npm install @dialpad/dialtone @dialpad/i18n-vue2
+```
 
-### Import packages:
+---
 
-#### Without theming
+### Theming
 
-If you don't care about theming and just want to use Dialtone with the default light theme:
+##### Quick Start
 
-- CSS
+**Install packages:**
 
-```css
-@import "@dialpad/dialtone/css-default-theme";
+```shell
+npm install @dialpad/dialtone @dialpad/dialtone-tokens
 ```
 
-- Javascript
+**Initialize (main.js or App.vue):**
 
 ```js
-import "@dialpad/dialtone/css-default-theme";
+import { initDialtoneTheme } from '@dialpad/dialtone/themes/config';
+import Dp from '@dialpad/dialtone-tokens/themes/dp';
+
+initDialtoneTheme(Dp, 'light');
 ```
 
-#### With theming
+Done. Your app now has theming.
 
-If you want to use theming, import from the below path. This file does not include design tokens so it is required to also set a theme to apply design tokens to the root element.
+---
 
-- CSS
+##### Basic Usage
 
-```css
-@import "@dialpad/dialtone/css";
+**Toggle light/dark mode:**
+
+```js
+import { setMode } from '@dialpad/dialtone/themes/config';
+setMode('dark');
 ```
 
-- Javascript
+**Use different theme at startup:**
 
 ```js
-import "@dialpad/dialtone/css";
+import Melon from '@dialpad/dialtone-tokens/themes/melon';
+initDialtoneTheme(Melon, 'light');
 ```
 
-##### Set theme via setTheme() javascript function (preferred)
+**Switch themes dynamically:**
+
+```js
+import { setBrand } from '@dialpad/dialtone/themes/config';
+import Tmo from '@dialpad/dialtone-tokens/themes/tmo';
+setBrand(Tmo);
+```
 
-Import the theme you want to use and set it via the `setTheme` function:
+**Enable high contrast:**
 
 ```js
-import { setTheme } from '@dialpad/dialtone/themes/config';
-import DpLight from '@dialpad/dialtone/themes/dp-light';
-setTheme(DpLight);
+import { setContrast } from '@dialpad/dialtone/themes/config';
+import HighContrast from '@dialpad/dialtone-tokens/themes/high-contrast';
+
+setContrast(HighContrast);
+setContrast(null);  // disable
 ```
 
-Possible themes are as follows:
+---
+
+##### Available Themes
+
+51 themes total. Use any with `initDialtoneTheme()` or `setBrand()`.
+
+**Standard:** dp, tmo, aegean, botany, buttercream, high-desert, melon, plum, sunflower, verdant-haze
+
+**Accessibility:** prota-deuter, trita
 
-- DpLight - Dialpad Light
-- DpDark - Dialpad Dark
-- TmoLight - T-Mobile Light
-- TmoDark - T-Mobile Dark
-- ExpressiveLight - Marketing Light
-- ExpressiveDark - Marketing Dark
-- ExpressiveSmLight - Marketing Small Light
-- ExpressiveSmDark - Marketing Small Dark
+**Experimental:** 101 through 137
 
-There is an optional second parameter to `setTheme` that allows you to set the theme on a specific element. This is useful in the case of a Shadow DOM
-when you want to apply the theme to the root element of the shadow DOM rather than the document root. If you do not set this parameter the theme will be applied to the document root.
+**Contrast:** high-contrast
+
+**Import pattern:**
 
 ```js
-import { setTheme } from '@dialpad/dialtone/themes/config';
-import DpLight from '@dialpad/dialtone/themes/dp-light';
-setTheme(DpLight, document.querySelector('#my-shadow-root-host'));
+import ThemeName from '@dialpad/dialtone-tokens/themes/theme-name';
 ```
 
-##### Set theme manually by importing files
+---
+
+##### Advanced
 
-You may want to use this method if you are unable to use javascript.
+**Shadow DOM (Web Components):**
 
-You need to import two tokens files in order to apply a theme. A base tokens files, which is either light or dark, and
-a semantic brand tokens file which is named after a brand and theme 'tokens-dp-light', 'tokens-dp-dark', 'tokens-tmo-light', ...
+Pass host element as third parameter.
 
-- CSS
+```js
+initDialtoneTheme(Dp, 'light', this);
+```
+
+**CSS only (no JS):**
 
 ```css
-@import "@dialpad/dialtone/tokens/tokens-base-light.css" // Base light theme
-@import "@dialpad/dialtone/tokens/tokens-dp-light.css" // Dialpad light brand
+@import "@dialpad/dialtone-tokens/layered/tokens-core.css";
+@import "@dialpad/dialtone-tokens/layered/tokens-base-colors.css";
+@import "@dialpad/dialtone-tokens/layered/tokens-dp-colors.css";
+```
+
+Then set attributes:
+
+```html
+<html data-dt-mode="light" data-dt-brand="dp" data-dt-contrast="default">
 ```
 
-- Javascript
+**Mode sections:**
+
+See [Mode Island component](https://dialtone.dialpad.com/components/mode-island.html) docs.
+
+---
+
+##### Legacy Theming System (Backward Compatible)
+
+The original theming system remains fully supported for existing projects. New projects should use the layered system above for better performance and smaller bundle sizes.
+
+**Note:** Both systems support Shadow DOM identically - pass the host element as the second parameter.
 
 ```js
-import "@dialpad/dialtone/tokens/tokens-base-light.css" // Base light theme
-import "@dialpad/dialtone/tokens/tokens-dp-light.css" // Dialpad light brand
+import { setTheme } from '@dialpad/dialtone/themes/config';
+import DpLight from '@dialpad/dialtone/themes/dp-light';
+import DpDark from '@dialpad/dialtone/themes/dp-dark';
+import TmoLight from '@dialpad/dialtone/themes/tmo-light';
+import TmoDark from '@dialpad/dialtone/themes/tmo-dark';
+
+// Set theme (automatically detected as legacy)
+setTheme(DpLight);
+
+// Shadow DOM support
+setTheme(DpLight, document.querySelector('#my-shadow-root-host'));
 ```
 
+**Legacy themes available:**
+
+- `DpLight`, `DpDark`, `TmoLight`, `TmoDark`
+
+**Note:** Legacy system loads complete token files (~1256KB per theme). Consider migrating to layered system for better performance.
+
 #### Dialtone icons
 
 - Vue 2:
@@ -193,36 +246,37 @@ the library.
 
 #### How does our bundling works
 
-To achieve this we needed to create certain configs through the monorepo to be able to handle them even if 
+To achieve this we needed to create certain configs through the monorepo to be able to handle them even if
 they have the same package name e.g: `@dialpad/dialtone-vue`.
 
 1. In root [package.json](package.json):
-   - `pnpm`: 
-     - `peerDependencyRules` include `vue": "^2.6 || ^3.2"` to make sure we don't have warnings related to vue version 
+   - `pnpm`:
+     - `peerDependencyRules` include `vue": "^2.6 || ^3.2"` to make sure we don't have warnings related to vue version
        mismatch.
      - `packageExtensions` tells pnpm which Vue version to use for each package.
-   - `dependencies` doesn't include any specific Vue 2 or Vue 3 dependencies as this causes issues on the client when 
+   - `dependencies` doesn't include any specific Vue 2 or Vue 3 dependencies as this causes issues on the client when
      trying to use exports from `./vue2` or `./vue3`.
 2. On individual packages `package.json` files:
    - Include the specific dependencies in case someone uses the individual package
-   - In `vite.config.js`[Vue 2](packages/dialtone-vue2/vite.config.js), 
-     [Vue 3](packages/dialtone-vue3/vite.config.js) add dependencies to external to make sure they don't cause 
-     issues on product. (This is more specific for the Vue 2 package, as product is depending on Vue 2.6 and any 
+   - In `vite.config.js`[Vue 2](packages/dialtone-vue2/vite.config.js),
+     [Vue 3](packages/dialtone-vue3/vite.config.js) add dependencies to external to make sure they don't cause
+     issues on product. (This is more specific for the Vue 2 package, as product is depending on Vue 2.6 and any
      dependency that needs a newer Vue version will cause issues).
 3. In [project.json](project.json)
    - Include implicit dependencies to make sure NX builds them before trying to copy the files to the mono-package.
 4. In `gulpfile.cjs`
    - Copy the built files into the root `dist` folder.
 
 #### Included packages
+
 - Dialtone CSS
 - Dialtone Tokens
 - Dialtone Vue 2
 - Dialtone Vue 3
 
 ### Tree-shaking
 
-Tree-shaking is a feature that allows you to remove unused code from your bundle, and it is enabled by default in our 
+Tree-shaking is a feature that allows you to remove unused code from your bundle, and it is enabled by default in our
 build process for Dialtone, Dialtone Vue, Dialtone Combinator and Dialtone Icons.
 
 We achieve tree-shaking primarily via three mechanisms across the packages:
@@ -240,14 +294,15 @@ We achieve tree-shaking primarily via three mechanisms across the packages:
 #### Publishing ESM builds (with dual ESM/CJS via exports map)
 
 Packages expose ESM for bundlers to statically analyze and tree-shake, with CJS fallbacks.
-- `@dialpad/dialtone-vue` (vue3): 
+
+- `@dialpad/dialtone-vue` (vue3):
   - `"type"`: `"module"`,
   - `"module"`: `"./dist/dialtone-vue.js"`,
   - `"main"`: `"./dist/dialtone-vue.cjs"`,
 
 #### Deep, per-module entry points to enable fine-grained import paths
 
-Exports maps expose subpath entries so consumers can import only what they need (which aids tree-shaking and avoids 
+Exports maps expose subpath entries so consumers can import only what they need (which aids tree-shaking and avoids
 pulling entire bundles):
 
 - `@dialpad/dialtone` exposes `./vue3/lib/*` and `./vue2/lib/*` map to individual component imports.
@@ -546,3 +601,5 @@ These will generate a JSON and HTML report in the `coverage` directory.
 
 The coverage thresholds are defined in the `vitest.config.ts` file.
 When submitting a PR the CI will run the tests with coverage and fail if the coverage is below the thresholds.
+
+<!-- test -->

apps/dialtone-documentation/docs/.vuepress/config.js

@@ -96,6 +96,7 @@ export default defineUserConfig({
     '@views': path.resolve(__dirname, './views'),
     '@mixins': path.resolve(__dirname, './common/mixins/'),
     '@utilities': path.resolve(__dirname, './common/utilities.js'),
+    '@composables': path.resolve(__dirname, './theme/composables'),
     '@projectRoot': path.resolve(__dirname, '../../'),
     '@': path.resolve(__dirname, '../'),
     '@workspaceRoot': path.resolve(__dirname, '../../../../'),

apps/dialtone-documentation/docs/.vuepress/theme/assets/less/dialtone-docs.less

@@ -297,20 +297,21 @@ html body {
   // border-inline-end: var(--dt-size-100) solid var(--dt-shell-color-border-subtle);
 
   &__list {
-    padding: var(--dt-size-550) var(--dt-size-450) var(--dt-size-750);
+    padding: var(--dt-size-550) 0 var(--dt-size-750) var(--dt-size-450);
     inset-block: var(--dt-space-700) 0;
     inline-size: calc(var(--dt-size-300) * 64);
   }
 }
 
 .dialtone-content {
   background-color: var(--dt-color-surface-primary);
-  border: var(--dt-size-border-100) solid var(--dt-color-border-subtle);
-  border-radius: var(--dt-size-radius-500);
+  border-block: var(--dt-size-border-100) solid var(--dt-color-border-subtle);
 
   @media (min-width: 980px) {
-    margin-right: var(--dt-space-500);
     margin-bottom: var(--dt-space-500);
+    border: var(--dt-size-border-100) solid var(--dt-color-border-subtle);
+    border-radius: var(--dt-size-radius-500);
+    margin-inline: var(--dt-space-500);
   }
 }
 
@@ -678,26 +679,28 @@ a.header-anchor {
 
 .dialtone-wall {
   display: grid;
-  grid-gap: var(--dt-space-500);
+  gap: var(--dt-space-500);
   margin-block-start: var(--dt-space-500);
 
   @media screen and (min-width: 640px) {
-    grid-gap: var(--dt-space-600);
     grid-template-columns: [full-start] repeat(2, [col-start] var(--col-width, minmax(0, 1fr)) [col-end]) [full-end] !important;
   }
 
   @media screen and (min-width: 768px) {
     grid-template-columns: [full-start] repeat(3, [col-start] var(--col-width, minmax(0, 1fr)) [col-end]) [full-end] !important;
   }
 
+  @media screen and (min-width: 1354px) {
+    gap: var(--dt-space-600);
+  }
+
   &__item {
     display: block;
     overflow: hidden;
     text-decoration: none;
-    background-color: var(--dt-color-surface-primary);
-    border: var(--dt-size-100) solid;
-    border-color: var(--dt-color-border-default);
-    border-radius: var(--dt-size-400);
+    background-color: var(--dt-color-surface-secondary);
+    border: var(--dt-size-border-100) solid var(--dt-color-border-subtle);
+    border-radius: var(--dt-size-radius-400);
     opacity: .7;
     transition-timing-function: var(--ttf-in-out);
     transition-duration: var(--td200);
@@ -709,7 +712,7 @@ a.header-anchor {
 
     &:is(a):hover {
       text-decoration: none;
-      border-color: var(--dt-color-border-moderate);
+      border-color: var(--dt-color-border-default);
       box-shadow: var(--dt-shadow-small);
     }
 
@@ -756,9 +759,14 @@ a.header-anchor {
   }
 
   &__description {
-    color: var(--dt-color-foreground-tertiary);
-    font-size: var(--dt-font-size-200);
-    line-height: var(--dt-font-line-height-300);
+    display: none;
+
+    @media screen and (min-width: 768px) {
+      display: block;
+      color: var(--dt-color-foreground-tertiary);
+      font-size: var(--dt-font-size-200);
+      line-height: var(--dt-font-line-height-300);
+    }
   }
 }