wordpress-public-workspace/design/dark-mode-admin-v1.1.0-spec.md

Dark Mode by GracePress 1.1.0 Admin Interface Specification

Date: 2026-08-22 Status: proposed for review Scope: information architecture and visual behavior only Source changes: none

Design objective

Replace the long implementation-oriented settings form with a native, purposeful administration workspace. The interface should explain effective behavior before exposing controls, preserve WordPress familiarity, carry the GracePress visual identity without private dependencies, and remain fully useful without JavaScript-only navigation.

Visual direction

• Light native settings canvas by default; the plugin's admin dark-mode preference may transform it only when that user selects Dark or Auto resolves to dark.
• Large navy hero with cyan module accent, restrained atmospheric geometry, and no remote assets.
• Expressive serif display heading paired with readable WordPress-compatible body typography.
• White or dark-neutral panels with modest borders and shadows.
• Color communicates state but is always paired with text and control semantics.
• No purple-on-white default, novelty gradients, giant decorative icons, or commercial upsell panels.
• Motion is limited to preview changes and status transitions and is removed under prefers-reduced-motion.

Page shell

1. WordPress administration chrome remains authoritative.
2. Plugin content has a maximum readable width but uses available space on desktop.
3. Hero spans the content width.
4. Section navigation follows the hero.
5. The active section renders below it.
6. A save/status bar follows the section content.
7. The GracePress footer closes the page.

Hero

Left side:

• Eyebrow: GracePress visual comfort.
• Title: Dark Mode.
• One-sentence user outcome, not engine terminology.
• Status chips: frontend state, default mode, privacy status, version.

Right side:

• Live status summary.
• Effective visitor mode.
• Current user's admin preference.
• Schedule state.
• Toggle placement.

The hero does not contain promotional links, remote imagery, or false health claims.

Navigation

Sections:

1. Overview
2. Behavior
3. Toggle
4. Rendering
5. Advanced
6. Help

Requirements:

• Native buttons or links with visible selected state.
• Server-rendered fallback permits direct section URLs.
• Keyboard and screen-reader state is explicit.
• Horizontal overflow is contained at narrow widths.
• Settings search is intentionally omitted at the current scale.

Overview

Live preview

• Representative heading, paragraph, link, form/control, media sample, and toggle.
• Light/dark preview control.
• Desktop/mobile width control.
• Preview uses unsaved form state without publishing it.
• Preview never loads the public site in a third-party frame.
• Preview motion honors reduced-motion.

Quick setup

• Frontend enable switch.
• New-visitor default: Light, Dark, or System.
• Current user's admin preference: Light, Dark, or Auto.
• Short explanation that a visitor's manual choice wins after first visit.

At a glance

• Current toggle style.
• Device visibility.
• Number of exclusions.
• No invented performance or accessibility scores.

Behavior

Deterministic precedence

Display the effective order directly:

1. Temporary preview or explicit URL override.
2. Visitor manual choice.
3. Active schedule.
4. Operating-system preference.
5. Site default.

Any implementation change to this order requires documentation and migration consideration.

Schedule

• Explicit enable switch.
• Configurable start and end time.
• WordPress site timezone displayed by name.
• Runtime evaluation remains cache-safe.
• Overnight ranges work correctly.
• Manual visitor choice remains authoritative.

Editing surfaces

• WordPress admin preference is per user.
• Admin, block editor canvas, and classic editor may be controlled separately.
• Disabling admin dark mode removes admin CSS, JavaScript, and toolbar controls.
• Disabling frontend dark mode emits no frontend assets or controls.

Toggle

Appearance

• Three initial styles: Classic moon, Compact switch, Text button.
• Every style uses a native button.
• Visible focus, descriptive accessible name, aria-pressed, and state text.
• Restrained accent-color setting with contrast validation.
• No unrestricted icon uploads in 1.1.0.

Placement

• Floating positions: four corners.
• Horizontal and vertical offsets.
• Desktop and mobile visibility.
• Safe z-index below critical modal and consent surfaces.
• Shortcode remains supported.
• Automatic injection into every menu is removed.
• Deliberate menu-item or block integration is deferred unless approved.

Rendering

Page transformation

• Existing brightness and contrast behavior receives strict ranges and plain-language help.
• The UI distinguishes page transformation from media correction.
• Invalid values are rejected, not silently reshaped.

Media

• Image/media brightness.
• Image/media contrast.
• Image/media grayscale.
• Default preserves original media appearance.
• Image/video replacement is out of scope.

Motion

• None, Gentle fade, and Soft wipe are the initial choices.
• Duration has a bounded range.
• Pulse is not enabled by default.
• prefers-reduced-motion disables nonessential motion.

Advanced

Content exclusions

• Search and choose pages/posts by title.
• Saved selections show title and content type, not raw IDs alone.
• Advanced manual ID fallback may be available for recovery.

Element exclusions

• One selector per parsed item.
• Each selector is validated independently.
• Invalid selectors show actionable errors.
• Common presets may be offered for logos, maps, charts, and embedded media.

Custom CSS

• Collapsed by default.
• Explicit warning about maintenance and external URL privacy.
• Reject closing markup and unsafe structures.
• Scope examples to the stable public root class.
• Never imply that arbitrary CSS is risk-free.

Help

• Shortcode and examples.
• Stable root class.
• Public hooks and filters.
• Preference and schedule explanation.
• Privacy statement: no telemetry, no remote runtime assets, browser-local visitor preference.
• Diagnostics summary with no secrets.
• Data retention and uninstall policy.
• WordPress.org support route once the plugin is published.

Save and reset behavior

• One explicit Save changes action.
• Visible Clean, Unsaved, Saving, Saved, and Error states.
• Validation errors remain beside their controls and are summarized accessibly.
• Reset section and Reset all are distinct.
• Reset requires confirmation and states exactly what will change.
• Reset never deletes unrelated WordPress or internal-plugin data.
• Failed saves preserve entered values.

GracePress footer

Required content:

• Relevant Scripture: John 1:5 is retained.
• Plugin name and version.
• All glory to Jesus Christ.
• Restrained Christ IT or GracePress attribution only if it complies with WordPress.org rules.
• No front-end backlink and no promotional call to action.

Responsive behavior

• Desktop: hero and main sections may use two columns.
• Tablet: hero and content stack while navigation remains horizontally usable.
• Mobile: WordPress sidebar is outside plugin ownership; plugin content becomes one column.
• No fixed viewport heights or internal page scrolling.
• Actions wrap without overlap.
• Labels remain visible; icon-only controls have accessible names.

Accessibility contract

• Native controls are mandatory.
• Labels are programmatically associated.
• Every state has a textual equivalent.
• Focus remains visible.
• Tab order follows document order.
• Contrast meets WCAG AA for text and essential controls.
• Preview controls expose pressed state.
• Dynamic save messages use polite announcements.
• Validation uses an alert summary and field associations.
• No global shortcut fires while focus is in an editable control.
• Reduced-motion preference is honored.

Implementation boundary

The proposed implementation should remain server-rendered PHP with scoped CSS and small progressive-enhancement JavaScript. React is not justified for this settings count.

Expected source decomposition:

• Main bootstrap/plugin file.
• Admin controller and settings registration.
• Admin view.
• Admin stylesheet.
• Admin JavaScript.
• Frontend engine stylesheet.
• Frontend engine JavaScript.
• Shared validation/helpers.
• Uninstall policy file when approved.

Exact file names will be selected during Phase 4 after the existing single-file plugin receives rollback copies.

Acceptance for Phase 3

Before implementation, confirm:

• Section names and order.
• Hero/status content.
• Preference precedence.
• Per-user admin model.
• Preview scope.
• Initial toggle styles.
• Schedule model.
• Exclusion workflow.
• Custom CSS policy.
• Save/reset behavior.
• GracePress footer content.
• Deferred-feature list.

No source implementation begins until this specification is accepted or revised.

Desktop density contract

The WordPress admin menu is the visual density baseline. A wide monitor must create more useful grouping and whitespace, not larger typography or controls.

• Body and control text: approximately 13px at 100 percent browser zoom.
• Secondary help text: 11-12px with sufficient contrast.
• Section headings: 18-20px; only the page title may exceed this materially.
• Standard input/select/button height: 32-38px.
• Card padding: 16-20px.
• Section gaps: 12-18px.
• Hero padding: 20-28px, with a target rendered height under roughly 220px on desktop.
• Control rows should use practical maximum widths; a select with four short options does not need to span a large card.
• Dense related switches may share a compact row or two-column group.
• Large screens add columns, preview area, and useful status information rather than scaling controls upward.
• Mobile touch targets remain at least 44px where needed without forcing desktop controls to that size.
• The layout must be reviewed at 100 percent zoom beside the native WordPress left menu.
• The current 1.0.0 values of 50px hero padding, 35px card padding, 20px card headings, and 15-18px action controls are explicitly rejected.