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.