From c93faa97507875ed01c8aee9df9cc0af63b3c797 Mon Sep 17 00:00:00 2001
From: Todd Olson <todd@todd.olson>
Date: Mon, 13 Apr 2026 21:17:40 -0400
Subject: [PATCH 1/3] feat: enable direct CSS theme overrides with :where() and
 button refactor [NOVUS-392]

- Wrap all visual default styles in :where() for zero specificity so
  theme CSS (even simple selectors) can override them
- Refactor pendo-button to render directly on custom element instead of
  creating inner <button> with all:unset that blocked theme CSS
- Same refactor for pendo-close-button
- Add role="button", tabindex="0", and keyboard handlers for a11y
- Backward compat: .pendo-button--primary class aliases still work

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 src/elements/pendo-button.js       |  24 ++--
 src/elements/pendo-close-button.js |  25 ++--
 src/styles/defaults.css            | 185 ++++++++++++++++++++---------
 3 files changed, 154 insertions(+), 80 deletions(-)

diff --git a/src/elements/pendo-button.js b/src/elements/pendo-button.js
index 7fd4e9f..b311305 100644
--- a/src/elements/pendo-button.js
+++ b/src/elements/pendo-button.js
@@ -33,16 +33,20 @@ class PendoButton extends PendoBaseElement {
     }
 
     renderDefault(variant) {
-        const button = document.createElement('button');
-        button.type = 'button';
-        button.className = `pendo-button pendo-button--${variant}`;
-
-        // Move inner content to button
-        button.innerHTML = this.innerHTML;
-        this.innerHTML = '';
-        this.appendChild(button);
-
-        button.addEventListener('click', () => this.handleClick());
+        // Style the custom element directly — no inner <button>.
+        // This allows theme CSS targeting pendo-button to work without
+        // conflicting with an inner element's styles.
+        this.classList.add('pendo-button', `pendo-button--${variant}`);
+        this.setAttribute('role', 'button');
+        this.setAttribute('tabindex', '0');
+
+        this.addEventListener('click', () => this.handleClick());
+        this.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                this.handleClick();
+            }
+        });
     }
 
     renderCustom(CustomButton, variant) {
diff --git a/src/elements/pendo-close-button.js b/src/elements/pendo-close-button.js
index 0d7135e..b468be3 100644
--- a/src/elements/pendo-close-button.js
+++ b/src/elements/pendo-close-button.js
@@ -18,22 +18,23 @@ class PendoCloseButton extends PendoBaseElement {
     }
 
     render() {
-        const button = document.createElement('button');
-        button.type = 'button';
-        button.className = 'pendo-close-button';
-        button.setAttribute('aria-label', 'Close');
+        // Style the custom element directly — no inner <button>
+        this.classList.add('pendo-close-button');
+        this.setAttribute('role', 'button');
+        this.setAttribute('tabindex', '0');
+        this.setAttribute('aria-label', 'Close');
+        this.textContent = '\u00D7'; // × character
 
-        const icon = document.createElement('span');
-        icon.setAttribute('aria-hidden', 'true');
-        icon.textContent = '\u00D7'; // × character
-
-        button.appendChild(icon);
-        this.appendChild(button);
-
-        button.addEventListener('click', (e) => {
+        this.addEventListener('click', (e) => {
             e.preventDefault();
             this.emitAction('dismiss');
         });
+        this.addEventListener('keydown', (e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                this.emitAction('dismiss');
+            }
+        });
     }
 }
 
diff --git a/src/styles/defaults.css b/src/styles/defaults.css
index 859e0fb..ea6d180 100644
--- a/src/styles/defaults.css
+++ b/src/styles/defaults.css
@@ -1,9 +1,9 @@
 /**
  * @pendo/guide-components - Default Styles
  *
- * These styles provide sensible defaults while allowing easy customization
- * via CSS custom properties. Components inherit from customer design tokens
- * when available.
+ * Visual defaults use :where() for zero specificity so that theme CSS
+ * (even simple selectors like `pendo-guide pendo-button`) can override them.
+ * Structural properties (display, box-sizing, position) stay unwrapped.
  */
 
 /* =============================================================================
@@ -33,7 +33,6 @@ pendo-guide,
 
 /* =============================================================================
    CSS Reset (Light DOM protection)
-   Prevents external styles from breaking components
    ============================================================================= */
 
 pendo-guide,
@@ -53,10 +52,17 @@ pendo-guide {
    pendo-guide (Container)
    ============================================================================= */
 
+/* Structural — always applied */
 pendo-guide,
 .pendo-guide {
     position: relative;
     display: block;
+    width: 100%;
+}
+
+/* Visual defaults — theme CSS overrides via :where() zero specificity */
+:where(pendo-guide),
+:where(.pendo-guide) {
     background: var(--pendo-bg);
     border-radius: var(--pendo-radius);
     box-shadow: var(--pendo-shadow);
@@ -64,7 +70,6 @@ pendo-guide,
     font-family: var(--pendo-font);
     color: var(--pendo-text);
     max-width: 400px;
-    width: 100%;
 }
 
 /* Semantic layout elements */
@@ -75,17 +80,22 @@ pendo-guide-content {
 pendo-guide-footer {
     display: flex;
     gap: var(--pendo-spacing-xs);
-    margin-top: var(--pendo-spacing);
     justify-content: flex-end;
 }
 
-/* Layout variants (applied by pendo-client) */
+:where(pendo-guide-footer) {
+    margin-top: var(--pendo-spacing);
+}
+
+/* =============================================================================
+   Layout variants (applied by pendo-client)
+   ============================================================================= */
+
 .pendo-guide--lightbox {
     /* Lightbox is centered via container positioning */
 }
 
 .pendo-guide--tooltip {
-    /* Container handles absolute positioning; this is relative for caret */
     position: relative;
     min-width: 280px;
     width: max-content;
@@ -132,7 +142,6 @@ pendo-guide-footer {
     width: 100%;
     border-radius: 0;
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-    /* Horizontal layout for banner */
     display: flex;
     flex-direction: row;
     align-items: center;
@@ -155,7 +164,6 @@ pendo-guide-footer {
     margin-left: var(--pendo-spacing-xs);
 }
 
-/* Slideout layout */
 .pendo-guide--slideout {
     max-width: 360px;
     max-height: 80vh;
@@ -181,9 +189,15 @@ pendo-guide-footer {
    pendo-title
    ============================================================================= */
 
+/* Structural */
 pendo-title,
 .pendo-guide__title {
     display: block;
+}
+
+/* Visual defaults */
+:where(pendo-title),
+:where(.pendo-guide__title) {
     font-size: 1.25rem;
     font-weight: 600;
     color: var(--pendo-text);
@@ -195,121 +209,149 @@ pendo-title,
    pendo-text
    ============================================================================= */
 
+/* Structural */
 pendo-text,
 .pendo-guide__text {
     display: block;
+}
+
+/* Visual defaults */
+:where(pendo-text),
+:where(.pendo-guide__text) {
     font-size: 0.9375rem;
     color: var(--pendo-text);
     margin: 0 0 var(--pendo-spacing) 0;
     line-height: 1.6;
 }
 
-pendo-text:last-child {
+:where(pendo-text:last-child) {
     margin-bottom: 0;
 }
 
 /* =============================================================================
    pendo-button
+   The custom element IS the button (no inner <button> element).
+   Classes (.pendo-button, .pendo-button--primary, etc.) are added by JS
+   for backward compat with existing themes that target those classes.
    ============================================================================= */
 
+/* Structural — always applied */
 pendo-button {
-    display: inline-block;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    text-decoration: none;
+    white-space: nowrap;
 }
 
 pendo-button + pendo-button {
     margin-left: var(--pendo-spacing-xs);
 }
 
-.pendo-button {
-    all: unset;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
+/* Visual defaults — :where() for zero specificity */
+:where(pendo-button),
+:where(.pendo-button) {
     padding: var(--pendo-spacing-sm) var(--pendo-spacing);
     border-radius: var(--pendo-radius);
     font-family: var(--pendo-font);
     font-size: 0.9375rem;
     font-weight: 500;
-    cursor: pointer;
+    border: none;
     transition: background-color 0.15s ease, opacity 0.15s ease;
-    text-decoration: none;
-    white-space: nowrap;
-}
-
-.pendo-button:hover {
-    opacity: 0.9;
 }
 
-.pendo-button--primary {
+/* Primary variant (default) */
+:where(pendo-button:not([variant])),
+:where(pendo-button[variant="primary"]),
+:where(.pendo-button--primary) {
     background: var(--pendo-primary);
     color: var(--pendo-primary-text, #ffffff);
 }
 
-.pendo-button--primary:hover {
+:where(pendo-button:not([variant]):hover),
+:where(pendo-button[variant="primary"]:hover),
+:where(.pendo-button--primary:hover) {
     background: var(--pendo-primary-hover);
-    opacity: 1;
 }
 
-.pendo-button--secondary {
+/* Secondary variant */
+:where(pendo-button[variant="secondary"]),
+:where(.pendo-button--secondary) {
     background: transparent;
     border: 1px solid var(--pendo-border);
     color: var(--pendo-text);
 }
 
-.pendo-button--secondary:hover {
+:where(pendo-button[variant="secondary"]:hover),
+:where(.pendo-button--secondary:hover) {
     background: rgba(0, 0, 0, 0.05);
-    opacity: 1;
 }
 
-/* Button container for multiple buttons */
-pendo-guide > pendo-button:last-child,
-pendo-guide > :last-child pendo-button {
+/* Link variant */
+:where(pendo-button[variant="link"]) {
+    background: transparent;
+    border: none;
+    color: var(--pendo-text-muted);
+    padding: var(--pendo-spacing-sm) var(--pendo-spacing-xs);
+}
+
+/* Button container spacing */
+:where(pendo-guide > pendo-button:last-child),
+:where(pendo-guide > :last-child pendo-button) {
     margin-top: var(--pendo-spacing-sm);
 }
 
 /* =============================================================================
    pendo-close-button
+   The custom element IS the button (no inner <button> element).
    ============================================================================= */
 
+/* Structural */
 pendo-close-button {
     position: absolute;
-    top: var(--pendo-spacing-sm);
-    right: var(--pendo-spacing-sm);
-    z-index: 1;
-}
-
-.pendo-close-button {
-    all: unset;
     display: flex;
     align-items: center;
     justify-content: center;
+    cursor: pointer;
+    z-index: 1;
+}
+
+/* Visual defaults */
+:where(pendo-close-button),
+:where(.pendo-close-button) {
+    top: var(--pendo-spacing-sm);
+    right: var(--pendo-spacing-sm);
     width: 28px;
     height: 28px;
     border-radius: 50%;
-    cursor: pointer;
+    border: none;
+    background: transparent;
     color: var(--pendo-text-muted);
     font-size: 1.25rem;
     line-height: 1;
     transition: background-color 0.15s ease, color 0.15s ease;
 }
 
-.pendo-close-button:hover {
+:where(pendo-close-button:hover),
+:where(.pendo-close-button:hover) {
     background: rgba(0, 0, 0, 0.08);
     color: var(--pendo-text);
 }
 
-.pendo-close-button:focus-visible {
-    outline: 2px solid var(--pendo-focus);
-    outline-offset: 2px;
-}
-
 /* =============================================================================
    pendo-image
    ============================================================================= */
 
+/* Structural */
 pendo-image,
 .pendo-guide__image-container {
     display: block;
+}
+
+/* Visual defaults */
+:where(pendo-image),
+:where(.pendo-guide__image-container) {
     margin: var(--pendo-spacing-sm) 0;
 }
 
@@ -338,22 +380,34 @@ pendo-image,
    pendo-divider
    ============================================================================= */
 
+/* Structural */
 pendo-divider,
 .pendo-guide__divider {
     display: block;
+    border: none;
+}
+
+/* Visual defaults */
+:where(pendo-divider),
+:where(.pendo-guide__divider) {
     height: 1px;
     background: var(--pendo-border);
     margin: var(--pendo-spacing) 0;
-    border: none;
 }
 
 /* =============================================================================
    pendo-video
    ============================================================================= */
 
+/* Structural */
 pendo-video,
 .pendo-guide__video-container {
     display: block;
+}
+
+/* Visual defaults */
+:where(pendo-video),
+:where(.pendo-guide__video-container) {
     margin: var(--pendo-spacing-sm) 0;
 }
 
@@ -370,11 +424,13 @@ pendo-video,
    pendo-link
    ============================================================================= */
 
+/* Structural */
 pendo-link {
     display: inline;
 }
 
-.pendo-link {
+/* Visual defaults */
+:where(.pendo-link) {
     color: var(--pendo-primary);
     text-decoration: underline;
     text-decoration-thickness: 1px;
@@ -383,23 +439,23 @@ pendo-link {
     transition: color 0.15s ease;
 }
 
-.pendo-link:hover {
+:where(.pendo-link:hover) {
     color: var(--pendo-primary-hover);
 }
 
-.pendo-link:focus-visible {
-    outline: 2px solid var(--pendo-focus);
-    outline-offset: 2px;
-    border-radius: 2px;
-}
-
 /* =============================================================================
    pendo-list
    ============================================================================= */
 
+/* Structural */
 pendo-list,
 .pendo-list {
     display: block;
+}
+
+/* Visual defaults */
+:where(pendo-list),
+:where(.pendo-list) {
     margin: var(--pendo-spacing-sm) 0;
 }
 
@@ -845,11 +901,24 @@ select.pendo-input__field {
    ============================================================================= */
 
 /* Visible focus indicators */
-.pendo-button:focus-visible {
+:where(pendo-button:focus-visible),
+:where(.pendo-button:focus-visible) {
+    outline: 2px solid var(--pendo-focus);
+    outline-offset: 2px;
+}
+
+:where(.pendo-close-button:focus-visible),
+:where(pendo-close-button:focus-visible) {
     outline: 2px solid var(--pendo-focus);
     outline-offset: 2px;
 }
 
+:where(.pendo-link:focus-visible) {
+    outline: 2px solid var(--pendo-focus);
+    outline-offset: 2px;
+    border-radius: 2px;
+}
+
 pendo-guide:focus {
     outline: none;
 }
@@ -890,7 +959,7 @@ pendo-guide:focus {
         --pendo-shadow: 0 4px 24px rgba(0, 0, 0, 0.4);
     }
 
-    pendo-guide:not([data-theme="light"]) .pendo-close-button:hover {
+    pendo-guide:not([data-theme="light"]) pendo-close-button:hover {
         background: rgba(255, 255, 255, 0.1);
     }
 }

From 13acef2dcfd4c5f2eb7d5258b77adbdea4d50236 Mon Sep 17 00:00:00 2001
From: Todd Olson <todd@todd.olson>
Date: Sun, 19 Apr 2026 21:21:57 -0400
Subject: [PATCH 2/3] fix: make nested surfaces contrast-safe on any theme
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Before: nested elements (.pendo-nps__score, .pendo-number-scale__item,
.pendo-open-text__input) used var(--pendo-bg) and var(--pendo-text) with
hardcoded light-mode fallbacks. A theme that set a dark background
directly on pendo-guide without setting the CSS variables would produce
illegible results — white buttons on dark modals; dark text in a white
textarea embedded in a dark dialog.

- Split each nested element's rule into a structural block (kept at full
  specificity) and a :where()-wrapped visual block. Visual properties now
  use currentColor-derived values (color: inherit; background and border
  via color-mix) so the surface always contrasts slightly with the
  guide's own text color, regardless of which tokens the theme sets.

- :where(.pendo-nps__label) and :where(.pendo-number-scale__label) use
  color: inherit + opacity: 0.7 instead of var(--pendo-text-muted), so
  dark themes that only set a cascaded color stay readable without
  needing a separate --pendo-text-muted override.

- --pendo-text-muted fallback now derives from --pendo-text via color-mix
  (previously hardcoded #666666), so elements that still use this token
  — pendo-text, .pendo-open-text__counter, .pendo-input__field placeholder,
  etc. — get a sensible faded variant automatically on dark themes.

- --pendo-bg fallback stays at #ffffff (the earlier iteration had tried
  transparent but that broke the no-theme default modal render).

Hover/selected/focus states on scale buttons still use --pendo-primary
and keep their stronger specificity, so the active indication reads
clearly regardless of these baseline changes.

Theme CSS with simple selectors (pendo-guide, pendo-button, etc.) now
produces readable output with no additional overrides required.
---
 src/styles/defaults.css | 57 +++++++++++++++++++++++++++++++----------
 1 file changed, 44 insertions(+), 13 deletions(-)

diff --git a/src/styles/defaults.css b/src/styles/defaults.css
index ea6d180..7b6510a 100644
--- a/src/styles/defaults.css
+++ b/src/styles/defaults.css
@@ -20,7 +20,13 @@ pendo-guide,
     --pendo-radius: var(--brand-radius, 8px);
     --pendo-bg: var(--brand-surface, #ffffff);
     --pendo-text: var(--brand-text, #1a1a1a);
-    --pendo-text-muted: var(--brand-text-muted, #666666);
+    /* Muted text derives from --pendo-text so dark themes that only set a text
+       color get a sensible faded variant automatically, instead of a hardcoded
+       #666 that's unreadable on dark backgrounds. */
+    --pendo-text-muted: var(
+        --brand-text-muted,
+        color-mix(in oklab, var(--pendo-text) 65%, transparent)
+    );
 
     /* Component-specific */
     --pendo-shadow: 0 4px 24px rgba(0, 0, 0, 0.15);
@@ -675,6 +681,7 @@ select.pendo-input__field {
     margin-bottom: 8px;
 }
 
+/* Structural */
 .pendo-nps__score {
     display: flex;
     align-items: center;
@@ -682,13 +689,18 @@ select.pendo-input__field {
     flex: 1;
     min-width: 24px;
     height: 32px;
-    border: 1px solid var(--pendo-border);
     border-radius: 4px;
-    background: var(--pendo-bg);
     cursor: pointer;
     transition: all 0.15s ease;
 }
 
+/* Visual — currentColor-derived so buttons read on any theme */
+:where(.pendo-nps__score) {
+    color: inherit;
+    background: color-mix(in oklab, currentColor 4%, transparent);
+    border: 1px solid color-mix(in oklab, currentColor 20%, transparent);
+}
+
 .pendo-nps__score:hover {
     border-color: var(--pendo-primary);
 }
@@ -714,9 +726,13 @@ select.pendo-input__field {
     justify-content: space-between;
 }
 
-.pendo-nps__label {
+/* Labels inherit the guide's cascaded text color so dark themes stay
+   readable without requiring theme CSS to set --pendo-text-muted. opacity
+   provides the "muted" effect without depending on a separate token. */
+:where(.pendo-nps__label) {
     font-size: 0.75rem;
-    color: var(--pendo-text-muted);
+    color: inherit;
+    opacity: 0.7;
 }
 
 /* =============================================================================
@@ -732,6 +748,7 @@ select.pendo-input__field {
     gap: 4px;
 }
 
+/* Structural */
 .pendo-number-scale__item {
     display: flex;
     align-items: center;
@@ -739,13 +756,18 @@ select.pendo-input__field {
     min-width: 36px;
     height: 36px;
     padding: 0 8px;
-    border: 1px solid var(--pendo-border);
     border-radius: 4px;
-    background: var(--pendo-bg);
     cursor: pointer;
     transition: all 0.15s ease;
 }
 
+/* Visual — currentColor-derived so buttons read on any theme */
+:where(.pendo-number-scale__item) {
+    color: inherit;
+    background: color-mix(in oklab, currentColor 4%, transparent);
+    border: 1px solid color-mix(in oklab, currentColor 20%, transparent);
+}
+
 .pendo-number-scale__item:hover {
     border-color: var(--pendo-primary);
 }
@@ -772,9 +794,10 @@ select.pendo-input__field {
     margin-top: 6px;
 }
 
-.pendo-number-scale__label {
+:where(.pendo-number-scale__label) {
     font-size: 0.75rem;
-    color: var(--pendo-text-muted);
+    color: inherit;
+    opacity: 0.7;
 }
 
 /* =============================================================================
@@ -787,20 +810,28 @@ select.pendo-input__field {
     gap: 0.375em;
 }
 
+/* Structural */
 .pendo-open-text__input {
     width: 100%;
     padding: 0.625em 0.75em;
     font-family: var(--pendo-font);
     font-size: 0.9375rem;
-    color: var(--pendo-text);
-    background: var(--pendo-bg);
-    border: 1px solid var(--pendo-border);
-    border-radius: calc(var(--pendo-radius) / 2);
     resize: vertical;
     min-height: 4em;
     transition: border-color 0.15s ease, box-shadow 0.15s ease;
 }
 
+/* Visual defaults — derive from currentColor so the input reads correctly on
+   any theme (light-mode: dark text on faint dark tint; dark-mode: light text
+   on faint light tint) without requiring the theme to set --pendo-bg or
+   --pendo-text. :where() keeps specificity at zero so theme CSS wins. */
+:where(.pendo-open-text__input) {
+    color: inherit;
+    background: color-mix(in oklab, currentColor 6%, transparent);
+    border: 1px solid color-mix(in oklab, currentColor 20%, transparent);
+    border-radius: calc(var(--pendo-radius) / 2);
+}
+
 .pendo-open-text__input::placeholder {
     color: var(--pendo-text-muted);
 }

From d4387390f97a6095f1af7316d6f0b2d333cced7d Mon Sep 17 00:00:00 2001
From: Todd Olson <todd@todd.olson>
Date: Mon, 20 Apr 2026 13:48:09 -0400
Subject: [PATCH 3/3] fix: render tooltip caret as rotated square that inherits
 theme background

Caret now picks up whatever color the theme paints on pendo-guide, including
themes that set `background` directly instead of `--pendo-bg`. Adds
`isolation: isolate` to keep the caret's negative z-index scoped to the
tooltip.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/styles/defaults.css | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/src/styles/defaults.css b/src/styles/defaults.css
index 7b6510a..995b7fe 100644
--- a/src/styles/defaults.css
+++ b/src/styles/defaults.css
@@ -106,41 +106,46 @@ pendo-guide-footer {
     min-width: 280px;
     width: max-content;
     max-width: 360px;
+    /* Stacking context so the caret's z-index: -1 stays scoped to the
+       tooltip (otherwise it escapes to the document root and can render
+       behind ancestor backgrounds). */
+    isolation: isolate;
 }
 
+/* Caret is a rotated square that inherits the tooltip's background, so it
+   visually matches whatever color the theme painted on pendo-guide —
+   even when the theme sets `background` directly instead of --pendo-bg. */
 .pendo-guide--tooltip::before {
     content: '';
     position: absolute;
-    border: 8px solid transparent;
-    z-index: 1;
+    width: 14px;
+    height: 14px;
+    background: inherit;
+    z-index: -1;
 }
 
 .pendo-guide--tooltip-bottom::before {
-    top: -16px;
+    top: -7px;
     left: 50%;
-    transform: translateX(-50%);
-    border-bottom-color: var(--pendo-bg);
+    transform: translateX(-50%) rotate(45deg);
 }
 
 .pendo-guide--tooltip-top::before {
-    bottom: -16px;
+    bottom: -7px;
     left: 50%;
-    transform: translateX(-50%);
-    border-top-color: var(--pendo-bg);
+    transform: translateX(-50%) rotate(45deg);
 }
 
 .pendo-guide--tooltip-left::before {
-    right: -16px;
+    right: -7px;
     top: 50%;
-    transform: translateY(-50%);
-    border-left-color: var(--pendo-bg);
+    transform: translateY(-50%) rotate(45deg);
 }
 
 .pendo-guide--tooltip-right::before {
-    left: -16px;
+    left: -7px;
     top: 50%;
-    transform: translateY(-50%);
-    border-right-color: var(--pendo-bg);
+    transform: translateY(-50%) rotate(45deg);
 }
 
 .pendo-guide--banner {