Make setup wizard card theming token-driven and module-mapped

Author: alexphillips-dev

archive/folderview.plus-2026.03.21.08.txz

@@ -0,0 +1 @@
+ebb0163a6f90560afcd747cba57bb8e7aae127fea549ca2d818ec24ca35f0967  folderview.plus-2026.03.21.08.txz

archive/folderview.plus-2026.03.21.08.txz.sha256

@@ -6,13 +6,19 @@
 <!ENTITY launch "Settings/FolderViewPlus">
 <!ENTITY plugdir "/usr/local/emhttp/plugins/&name;">
 <!ENTITY pluginURL "https://raw.githubusercontent.com/&github;/dev/folderview.plus.plg">
-<!ENTITY version "2026.03.21.07">
-<!ENTITY md5 "1c1b3ec507597d78f3bd54d63f3b0ab8">
+<!ENTITY version "2026.03.21.08">
+<!ENTITY md5 "2b06eaf64095913eb3e1727c7c831357">
 ]>
 
 <PLUGIN name="&name;" author="&author;" version="&version;" launch="&launch;" pluginURL="&pluginURL;" icon="folder-icon.png" support="https://forums.unraid.net/topic/197631-plugin-folderview-plus/" min="7.0.0">
     <CHANGES>
 
+###2026.03.21.08
+- Feature: Reworked setup-wizard card theming to use explicit `data-fv-card-tone` module mapping instead of positional `nth-child` styling.
+- UX: Tokenized wizard panel/card backgrounds, accents, and shell surfaces to reduce hardcoded style coupling while preserving contrast-safe fallbacks.
+- Quality: Added guardrails/tests to prevent regression to positional tone mapping and raw card color literals.
+
+
 ###2026.03.21.07
 - UX: Introduced multi-tone setup-wizard module styling so Environment/Mode/Bundle/Preset cards are visually distinct at a glance.
 - Fix: Increased contrast boundaries for wizard sidebar/header/footer and step panels to stop sections blending together.

folderview.plus.plg

@@ -71,6 +71,11 @@ require_contains "${SETTINGS_CSS}" '--fvplus-settings-surface-muted:' 'settings
 require_contains "${SETTINGS_CSS}" '--fvplus-settings-accent:' 'settings tokenized accent'
 require_contains "${SETTINGS_CSS}" '#fv-setup-assistant-dialog[[:space:]]*\{' 'wizard dialog token block exists'
 require_contains "${SETTINGS_CSS}" 'color-scheme:[[:space:]]*dark' 'wizard dark color scheme'
+require_contains "${SETTINGS_CSS}" '\.fv-setup-card\[data-fv-card-tone="env"\]' 'wizard card tone selector (env)'
+require_contains "${SETTINGS_CSS}" '\.fv-setup-card\[data-fv-card-tone="mode"\]' 'wizard card tone selector (mode)'
+require_contains "${SETTINGS_CSS}" '\.fv-setup-card\[data-fv-card-tone="bundle"\]' 'wizard card tone selector (bundle)'
+require_contains "${SETTINGS_CSS}" '\.fv-setup-card\[data-fv-card-tone="preset"\]' 'wizard card tone selector (preset)'
+require_absent "${SETTINGS_CSS}" '\.fv-setup-step-grid > \.fv-setup-card:nth-child' 'wizard should not use positional tone mapping'
 require_absent "${SETTINGS_CSS}" '--fv-wizard-text-primary:[[:space:]]*var\(--text' 'wizard text token must not follow host text token directly'
 require_absent "${SETTINGS_CSS}" '--fv-wizard-text-primary:[[:space:]]*var\(--fvplus-settings-text-primary\)' 'wizard text token must not follow settings token directly'
 require_contains "${SETTINGS_JS}" 'const buildResolvedThemeSnapshot = \(modeInput = null\) =>' 'theme resolver snapshot helper'

scripts/theme_runtime_guard.sh

@@ -1577,7 +1577,7 @@ const renderSetupAssistantWelcomeStep = () => {
     `).join('');
     return `
         <div class="fv-setup-step-grid">
-            <section class="fv-setup-card">
+            <section class="fv-setup-card" data-fv-card-tone="env">
                 <h4>Detected environment</h4>
                 <div class="fv-setup-chip-row">
                     <span class="fv-setup-chip">Docker folders: ${context.dockerFolders}</span>
@@ -1600,7 +1600,7 @@ const renderSetupAssistantWelcomeStep = () => {
                     <button type="button" id="fv-setup-apply-detected"><i class="fa fa-magic"></i> Use detected setup</button>
                 </div>
             </section>
-            <section class="fv-setup-card">
+            <section class="fv-setup-card" data-fv-card-tone="mode">
                 <h4>Default settings mode</h4>
                 <p class="fv-setup-muted">You can change this any time in the top bar.</p>
                 <div class="fv-setup-mode-toggle">
@@ -1615,15 +1615,15 @@ const renderSetupAssistantWelcomeStep = () => {
                     <button type="button" class="${experienceMode === 'expert' ? 'is-active' : ''}" data-fv-setup-experience="expert">Expert</button>
                 </div>
             </section>
-            <section class="fv-setup-card">
+            <section class="fv-setup-card" data-fv-card-tone="bundle">
                 <h4>Quick start bundle</h4>
                 <p class="fv-setup-muted">Pick a ready-made bundle. You can still fine tune profile and behavior in later steps.</p>
                 <div class="fv-setup-quick-preset-grid">
                     ${quickPresetHtml}
                 </div>
                 <p class="fv-setup-muted">Current bundle: <strong>${escapeHtml(selectedQuickPreset)}</strong></p>
             </section>
-            <section class="fv-setup-card">
+            <section class="fv-setup-card" data-fv-card-tone="preset">
                 <h4>Saved wizard presets</h4>
                 <p class="fv-setup-muted">Save your preferred setup path and reuse it later.</p>
                 <div class="fv-setup-field-grid">
@@ -1655,7 +1655,7 @@ const renderSetupAssistantWelcomeStep = () => {
 
 const renderSetupAssistantProfileStep = () => {
     return `
-        <div class="fv-setup-card">
+        <div class="fv-setup-card" data-fv-card-tone="profile">
             <h4>Choose a defaults profile</h4>
             <p class="fv-setup-muted">Profile defaults only apply if you enable them below.</p>
             <div class="fv-setup-profile-grid">
@@ -1709,7 +1709,7 @@ const renderSetupAssistantImportTypeCard = (type) => {
     const warnings = Array.isArray(plan?.warnings) ? plan.warnings : [];
 
     return `
-        <section class="fv-setup-card fv-setup-import-card">
+        <section class="fv-setup-card fv-setup-import-card" data-fv-card-tone="import-${resolvedType}">
             <div class="fv-setup-import-header">
                 <h4>${title} import</h4>
                 <div class="fv-setup-chip-row">
@@ -1790,7 +1790,7 @@ const renderSetupAssistantRuleTypeCard = (type) => {
     }).join('');
 
     return `
-        <section class="fv-setup-card">
+        <section class="fv-setup-card" data-fv-card-tone="rules-${resolvedType}">
             <label class="fv-setup-inline-toggle">
                 <input type="checkbox" data-fv-setup-rules-enable="${resolvedType}" ${bootstrap.enabled ? 'checked' : ''} ${suggestions.length ? '' : 'disabled'}>
                 Add starter ${title} rules (${selectedCount}/${suggestions.length} selected)
@@ -1817,7 +1817,7 @@ const renderSetupAssistantBehaviorTypeCard = (type) => {
     const title = resolvedType === 'docker' ? 'Docker' : 'VM';
     const isExpert = normalizeSetupAssistantExperienceMode(setupAssistantState.experienceMode) === 'expert';
     return `
-        <section class="fv-setup-card">
+        <section class="fv-setup-card" data-fv-card-tone="behavior-${resolvedType}">
             <h4>${title} behavior</h4>
             <div class="fv-setup-field-grid ${isExpert ? '' : 'is-guided'}">
                 <label class="fv-setup-field">
@@ -1865,7 +1865,7 @@ const renderSetupAssistantReviewStep = () => {
     setupAssistantState.reviewNotes = notes;
 
     return `
-        <div class="fv-setup-card">
+        <div class="fv-setup-card" data-fv-card-tone="review">
             <h4>Review planned changes</h4>
             <div class="fv-setup-review-grid">
                 <span class="fv-setup-chip">Mode: ${escapeHtml(setupAssistantState.mode)}</span>
@@ -1876,15 +1876,15 @@ const renderSetupAssistantReviewStep = () => {
                 <span class="fv-setup-chip">Dry run: ${setupAssistantState.dryRunOnly ? 'ON' : 'OFF'}</span>
             </div>
             <div class="fv-setup-impact-grid">
-                <article class="fv-setup-impact-card">
+                <article class="fv-setup-impact-card" data-fv-card-tone="impact-prefs">
                     <h5>Preferences</h5>
                     <p>${impact.prefs.totalChanges} changes planned</p>
                     <div class="fv-setup-chip-row">
                         <span class="fv-setup-chip">Docker: ${impact.prefs.byType.docker.count}</span>
                         <span class="fv-setup-chip">VM: ${impact.prefs.byType.vm.count}</span>
                     </div>
                 </article>
-                <article class="fv-setup-impact-card">
+                <article class="fv-setup-impact-card" data-fv-card-tone="impact-imports">
                     <h5>Imports</h5>
                     <p>${impact.imports.totals.totalOps} operations planned</p>
                     <div class="fv-setup-chip-row">
@@ -1893,7 +1893,7 @@ const renderSetupAssistantReviewStep = () => {
                         <span class="fv-setup-chip is-delete">Delete: ${impact.imports.totals.deletes}</span>
                     </div>
                 </article>
-                <article class="fv-setup-impact-card">
+                <article class="fv-setup-impact-card" data-fv-card-tone="impact-rules">
                     <h5>Starter rules</h5>
                     <p>${impact.rules.creatable} new rules planned</p>
                     <div class="fv-setup-chip-row">
@@ -1902,7 +1902,7 @@ const renderSetupAssistantReviewStep = () => {
                         <span class="fv-setup-chip">Missing folder: ${impact.rules.unresolvedFolder}</span>
                     </div>
                 </article>
-                <article class="fv-setup-impact-card">
+                <article class="fv-setup-impact-card" data-fv-card-tone="impact-total">
                     <h5>Total impact</h5>
                     <p>${impact.totalPlannedChanges} net changes estimated</p>
                     <div class="fv-setup-chip-row">

src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/scripts/folderviewplus.wizard.js

@@ -3809,6 +3809,33 @@ body.fv-mobile-compact .fv-setup-field-grid {
     --fv-wizard-accent-amber-rgb: 255, 170, 94;
     --fv-wizard-accent-green-rgb: 147, 225, 159;
     --fv-wizard-accent-cyan-rgb: 92, 213, 255;
+    --fv-wizard-accent-env-rgb: var(--fv-wizard-accent-blue-rgb);
+    --fv-wizard-accent-mode-rgb: var(--fv-wizard-accent-amber-rgb);
+    --fv-wizard-accent-bundle-rgb: var(--fv-wizard-accent-green-rgb);
+    --fv-wizard-accent-preset-rgb: var(--fv-wizard-accent-cyan-rgb);
+    --fv-wizard-accent-profile-rgb: var(--fv-wizard-accent-blue-rgb);
+    --fv-wizard-accent-import-docker-rgb: var(--fv-wizard-accent-amber-rgb);
+    --fv-wizard-accent-import-vm-rgb: var(--fv-wizard-accent-cyan-rgb);
+    --fv-wizard-accent-rules-docker-rgb: var(--fv-wizard-accent-green-rgb);
+    --fv-wizard-accent-rules-vm-rgb: var(--fv-wizard-accent-cyan-rgb);
+    --fv-wizard-accent-behavior-docker-rgb: var(--fv-wizard-accent-amber-rgb);
+    --fv-wizard-accent-behavior-vm-rgb: var(--fv-wizard-accent-blue-rgb);
+    --fv-wizard-accent-review-rgb: var(--fv-wizard-accent-blue-rgb);
+    --fv-wizard-accent-impact-prefs-rgb: var(--fv-wizard-accent-blue-rgb);
+    --fv-wizard-accent-impact-imports-rgb: var(--fv-wizard-accent-amber-rgb);
+    --fv-wizard-accent-impact-rules-rgb: var(--fv-wizard-accent-green-rgb);
+    --fv-wizard-accent-impact-total-rgb: var(--fv-wizard-accent-cyan-rgb);
+    --fv-wizard-shell-sidebar-bg: linear-gradient(180deg, rgba(17, 25, 37, 0.88) 0%, rgba(11, 18, 28, 0.86) 100%);
+    --fv-wizard-shell-head-bg: linear-gradient(180deg, rgba(17, 25, 37, 0.84) 0%, rgba(12, 20, 32, 0.78) 100%);
+    --fv-wizard-shell-strip-bg: rgba(10, 16, 25, 0.88);
+    --fv-wizard-row-bg: rgba(11, 17, 27, 0.74);
+    --fv-wizard-card-border-alpha: 0.34;
+    --fv-wizard-card-tint-alpha: 0.14;
+    --fv-wizard-card-surface-stop: 20%;
+    --fv-wizard-card-base-bg: rgba(10, 16, 25, 0.9);
+    --fv-wizard-card-topline-strong-alpha: 0.92;
+    --fv-wizard-card-topline-soft-alpha: 0.34;
+    --fv-wizard-card-inset-highlight: inset 0 1px 0 rgba(255, 255, 255, 0.06);
     --fv-wizard-card-shadow: 0 10px 22px rgba(0, 0, 0, 0.24);
 }
 
@@ -3881,7 +3908,7 @@ body.fv-mobile-compact .fv-setup-field-grid {
 .fv-setup-assistant-sidebar {
     border-right: 1px solid var(--fv-wizard-border-subtle);
     padding: 0.65rem 0.62rem;
-    background: linear-gradient(180deg, rgba(17, 25, 37, 0.88) 0%, rgba(11, 18, 28, 0.86) 100%);
+    background: var(--fv-wizard-shell-sidebar-bg);
     overflow-y: auto;
 }
 
@@ -3952,7 +3979,7 @@ body.fv-mobile-compact .fv-setup-field-grid {
     padding: 0;
     border-radius: 8px;
     border: 1px solid var(--fv-wizard-border-subtle);
-    background: rgba(11, 17, 27, 0.74);
+    background: var(--fv-wizard-row-bg);
     font-size: var(--fv-wizard-font-103);
     color: var(--fv-wizard-text-primary);
     opacity: 0.92;
@@ -4067,7 +4094,7 @@ body.fv-mobile-compact .fv-setup-field-grid {
     gap: 0.55rem;
     border-bottom: 1px solid var(--fv-wizard-border-subtle);
     padding: 0.7rem 0.8rem;
-    background: linear-gradient(180deg, rgba(17, 25, 37, 0.84) 0%, rgba(12, 20, 32, 0.78) 100%);
+    background: var(--fv-wizard-shell-head-bg);
 }
 
 .fv-setup-assistant-head h4 {
@@ -4085,7 +4112,7 @@ body.fv-mobile-compact .fv-setup-field-grid {
     padding: 0.45rem 0.8rem 0.38rem 0.8rem;
     display: grid;
     gap: 0.25rem;
-    background: rgba(10, 16, 25, 0.88);
+    background: var(--fv-wizard-shell-strip-bg);
 }
 
 .fv-setup-step-grid {
@@ -4095,22 +4122,22 @@ body.fv-mobile-compact .fv-setup-field-grid {
 }
 
 .fv-setup-card {
-    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-blue-rgb);
-    border: 1px solid rgba(var(--fv-wizard-card-accent-rgb), 0.34);
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-env-rgb);
+    border: 1px solid rgba(var(--fv-wizard-card-accent-rgb), var(--fv-wizard-card-border-alpha));
     border-radius: 10px;
     background: linear-gradient(
         180deg,
-        rgba(var(--fv-wizard-card-accent-rgb), 0.14) 0%,
-        var(--fv-wizard-surface-card) 20%,
-        rgba(10, 16, 25, 0.9) 100%
+        rgba(var(--fv-wizard-card-accent-rgb), var(--fv-wizard-card-tint-alpha)) 0%,
+        var(--fv-wizard-surface-card) var(--fv-wizard-card-surface-stop),
+        var(--fv-wizard-card-base-bg) 100%
     );
     padding: 0.6rem 0.65rem;
     display: grid;
     gap: 0.5rem;
     min-width: 0;
     position: relative;
     overflow: hidden;
-    box-shadow: var(--fv-wizard-card-shadow), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+    box-shadow: var(--fv-wizard-card-shadow), var(--fv-wizard-card-inset-highlight);
 }
 
 .fv-setup-card::before {
@@ -4122,27 +4149,59 @@ body.fv-mobile-compact .fv-setup-field-grid {
     height: 2px;
     background: linear-gradient(
         90deg,
-        rgba(var(--fv-wizard-card-accent-rgb), 0.92) 0%,
-        rgba(var(--fv-wizard-card-accent-rgb), 0.34) 70%,
+        rgba(var(--fv-wizard-card-accent-rgb), var(--fv-wizard-card-topline-strong-alpha)) 0%,
+        rgba(var(--fv-wizard-card-accent-rgb), var(--fv-wizard-card-topline-soft-alpha)) 70%,
         transparent 100%
     );
     pointer-events: none;
 }
 
-.fv-setup-step-grid > .fv-setup-card:nth-child(4n + 1) {
-    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-blue-rgb);
+.fv-setup-card[data-fv-card-tone="env"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-env-rgb);
 }
 
-.fv-setup-step-grid > .fv-setup-card:nth-child(4n + 2) {
-    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-amber-rgb);
+.fv-setup-card[data-fv-card-tone="mode"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-mode-rgb);
 }
 
-.fv-setup-step-grid > .fv-setup-card:nth-child(4n + 3) {
-    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-green-rgb);
+.fv-setup-card[data-fv-card-tone="bundle"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-bundle-rgb);
 }
 
-.fv-setup-step-grid > .fv-setup-card:nth-child(4n + 4) {
-    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-cyan-rgb);
+.fv-setup-card[data-fv-card-tone="preset"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-preset-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="profile"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-profile-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="import-docker"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-import-docker-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="import-vm"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-import-vm-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="rules-docker"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-rules-docker-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="rules-vm"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-rules-vm-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="behavior-docker"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-behavior-docker-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="behavior-vm"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-behavior-vm-rgb);
+}
+
+.fv-setup-card[data-fv-card-tone="review"] {
+    --fv-wizard-card-accent-rgb: var(--fv-wizard-accent-review-rgb);
 }
 
 .fv-setup-card h4 {
@@ -4487,14 +4546,36 @@ body.fv-mobile-compact .fv-setup-field-grid {
 }
 
 .fv-setup-impact-card {
-    border: 1px solid var(--fv-wizard-border-subtle);
+    --fv-wizard-impact-accent-rgb: var(--fv-wizard-accent-impact-prefs-rgb);
+    border: 1px solid rgba(var(--fv-wizard-impact-accent-rgb), 0.3);
     border-radius: 8px;
-    background: var(--fv-wizard-surface-card-strong);
+    background: linear-gradient(
+        180deg,
+        rgba(var(--fv-wizard-impact-accent-rgb), 0.12) 0%,
+        var(--fv-wizard-surface-card-strong) 20%,
+        var(--fv-wizard-card-base-bg) 100%
+    );
     padding: 0.42rem 0.48rem;
     display: grid;
     gap: 0.28rem;
 }
 
+.fv-setup-impact-card[data-fv-card-tone="impact-prefs"] {
+    --fv-wizard-impact-accent-rgb: var(--fv-wizard-accent-impact-prefs-rgb);
+}
+
+.fv-setup-impact-card[data-fv-card-tone="impact-imports"] {
+    --fv-wizard-impact-accent-rgb: var(--fv-wizard-accent-impact-imports-rgb);
+}
+
+.fv-setup-impact-card[data-fv-card-tone="impact-rules"] {
+    --fv-wizard-impact-accent-rgb: var(--fv-wizard-accent-impact-rules-rgb);
+}
+
+.fv-setup-impact-card[data-fv-card-tone="impact-total"] {
+    --fv-wizard-impact-accent-rgb: var(--fv-wizard-accent-impact-total-rgb);
+}
+
 .fv-setup-impact-card > h5 {
     margin: 0;
     font-size: var(--fv-wizard-font-103);
@@ -4588,7 +4669,7 @@ body.fv-mobile-compact .fv-setup-field-grid {
     align-items: center;
     justify-content: space-between;
     gap: 0.45rem;
-    background: rgba(10, 16, 25, 0.88);
+    background: var(--fv-wizard-shell-strip-bg);
 }
 
 .fv-setup-nav-note {
@@ -4598,7 +4679,7 @@ body.fv-mobile-compact .fv-setup-field-grid {
     display: inline-flex;
     align-items: center;
     gap: 0.35rem;
-    background: rgba(10, 16, 25, 0.88);
+    background: var(--fv-wizard-shell-strip-bg);
 }
 
 .fv-setup-foot-left,
@@ -4612,7 +4693,7 @@ body.fv-mobile-compact .fv-setup-field-grid {
     display: none;
     border-top: 1px solid var(--fv-wizard-border-subtle);
     padding: 0.45rem 0.8rem 0.52rem 0.8rem;
-    background: rgba(10, 16, 25, 0.88);
+    background: var(--fv-wizard-shell-strip-bg);
 }
 
 .fv-setup-progress.is-visible {