Advance wizard UX, accessibility tiers, and contrast resilience

Author: alexphillips-dev

archive/folderview.plus-2026.03.21.09.txz

@@ -0,0 +1 @@
+d5b0d25ddfc3fe6d6352ca1387d785c0bb2114e099c5a3320a465fe21a9b8bc2  folderview.plus-2026.03.21.09.txz

archive/folderview.plus-2026.03.21.09.txz.sha256

@@ -6,13 +6,21 @@
 <!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.08">
-<!ENTITY md5 "2b06eaf64095913eb3e1727c7c831357">
+<!ENTITY version "2026.03.21.09">
+<!ENTITY md5 "6e420ddd983612b56a79faf408199b6b">
 ]>
 
 <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.09
+- Feature: Added wizard contrast system with explicit tiers (`normal/high/max`) plus auto contrast evaluation that selects safer tiers when needed.
+- Feature: Added wizard quick accessibility controls (Focus mode toggle + Contrast selector) and keyboard shortcuts (`Alt+F`, `Alt+C`).
+- UX: Improved active/selected affordance beyond color (shape, weight, highlight rails), added inline "how to fix" guidance, and mobile chip-row detail toggles.
+- UX: Introduced semantic wizard status color mapping (`info/success/warning/danger/neutral`) with stronger hierarchy for step/card/readability states.
+- Quality: Expanded wizard regression guards in runtime/theme smoke tests and updated theme guards for tier/selector contracts.
+
+
 ###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.

folderview.plus.plg

@@ -294,6 +294,19 @@ const runScenarioChecks = async (page, { label, browserName, mobile, zoom }) =>
         }
 
         const errors = [];
+        const contrastTier = String(dialog.getAttribute('data-fv-wizard-contrast-tier') || '').trim();
+        if (!['normal', 'high', 'max'].includes(contrastTier)) {
+            errors.push(`Wizard contrast tier attribute is invalid (${contrastTier || 'missing'}).`);
+        }
+        const focusModeButton = dialog.querySelector('#fv-setup-focus-mode');
+        if (!focusModeButton) {
+            errors.push('Wizard focus mode toggle is missing.');
+        }
+        const contrastSelect = dialog.querySelector('#fv-setup-contrast-mode');
+        if (!contrastSelect) {
+            errors.push('Wizard contrast mode selector is missing.');
+        }
+
         const fallbackBg = parseColor(window.getComputedStyle(dialog).backgroundColor) || { r: 10, g: 14, b: 20, a: 1 };
         const resolveBackground = (element) => {
             let current = element;
@@ -336,6 +349,7 @@ const runScenarioChecks = async (page, { label, browserName, mobile, zoom }) =>
         verifyContrast('.fv-setup-profile-help', 4.0, 'Profile helper text');
         verifyContrast('.fv-setup-step-list li', 4.0, 'Step list labels');
         verifyContrast('.fv-setup-chip', 3.5, 'Summary chips');
+        verifyContrast('.fv-setup-inline-guidance', 4.0, 'Inline guidance text');
 
         const disabledControls = Array.from(dialog.querySelectorAll('button:disabled, input:disabled, select:disabled'))
             .filter((element) => isVisible(element))
@@ -391,6 +405,13 @@ const runScenarioChecks = async (page, { label, browserName, mobile, zoom }) =>
             }
         }
 
+        if (context.mobile === true) {
+            const chipToggle = dialog.querySelector('.fv-setup-chip-toggle');
+            if (!chipToggle) {
+                errors.push('Wizard mobile chip collapse toggle was not rendered.');
+            }
+        }
+
         return { errors };
     }, { mobile, zoom });
 

scripts/theme_matrix_smoke.mjs

@@ -9,6 +9,7 @@ VM_CSS="${PLUGIN_DIR}/styles/vm.css"
 DASHBOARD_CSS="${PLUGIN_DIR}/styles/dashboard.css"
 SETTINGS_CSS="${PLUGIN_DIR}/styles/folderviewplus.css"
 SETTINGS_JS="${PLUGIN_DIR}/scripts/folderviewplus.js"
+WIZARD_JS="${PLUGIN_DIR}/scripts/folderviewplus.wizard.js"
 SETTINGS_PAGE="${PLUGIN_DIR}/FolderViewPlus.page"
 DOCKER_JS="${PLUGIN_DIR}/scripts/docker.js"
 VM_JS="${PLUGIN_DIR}/scripts/vm.js"
@@ -48,6 +49,7 @@ require_file "${VM_CSS}"
 require_file "${DASHBOARD_CSS}"
 require_file "${SETTINGS_CSS}"
 require_file "${SETTINGS_JS}"
+require_file "${WIZARD_JS}"
 require_file "${SETTINGS_PAGE}"
 require_file "${DOCKER_JS}"
 require_file "${VM_JS}"
@@ -75,12 +77,18 @@ require_contains "${SETTINGS_CSS}" '\.fv-setup-card\[data-fv-card-tone="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_contains "${SETTINGS_CSS}" '#fv-setup-assistant-dialog\[data-fv-wizard-contrast-tier="high"\]' 'wizard high contrast tier selector'
+require_contains "${SETTINGS_CSS}" '#fv-setup-assistant-dialog\[data-fv-wizard-contrast-tier="max"\]' 'wizard max contrast tier selector'
 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'
 require_contains "${SETTINGS_JS}" 'const applyResolvedThemeTokens = \(reason = '\''runtime'\''\) =>' 'theme resolver apply helper'
 require_contains "${SETTINGS_JS}" 'const runThemeSelfHeal = async \(\) =>' 'theme self-heal action'
+require_contains "${WIZARD_JS}" 'const normalizeSetupAssistantContrastPreference = \(value\) =>' 'wizard contrast preference normalizer'
+require_contains "${WIZARD_JS}" 'const applySetupAssistantContrastTier = \(\) =>' 'wizard contrast apply helper'
+require_contains "${WIZARD_JS}" 'id="fv-setup-focus-mode"' 'wizard focus mode control'
+require_contains "${WIZARD_JS}" 'id="fv-setup-contrast-mode"' 'wizard contrast mode control'
 require_contains "${SETTINGS_PAGE}" 'runThemeSelfHeal\(\)' 'theme self-heal button wiring'
 
 require_absent "${DOCKER_JS}" '\.css\(\s*["'"'"']color["'"'"']\s*,\s*statusColors' 'docker inline status color painting'

scripts/theme_runtime_guard.sh

@@ -667,6 +667,11 @@ const setupAssistantState = {
     environmentPreset: 'home_lab',
     applyEnvironmentDefaults: true,
     dryRunOnly: false,
+    focusModeEnabled: true,
+    contrastPreference: 'auto',
+    contrastTierApplied: 'normal',
+    lastContrastReport: null,
+    collapsedChipRows: {},
     context: null,
     importPlans: {
         docker: null,