Update public WordPress workspace working changes

- GRACEPRESS-PUBLIC-PLUGIN-STANDARDS.md - PUBLIC-PLUGIN-WORKFLOW.md - WORDPRESS-ORG-REQUIREMENTS.md - WORDPRESS-PUBLIC-CONVENTIONS.md - design/dark-mode-admin-v1.1.0-spec.md - plugins/bible-reference-tooltips/CHANGELOG.md - plugins/bible-reference-tooltips/bible-reference-tooltips.php - plugins/bible-reference-tooltips/readme.txt
2026-10-02 15:57:02 -05:00
parent f2bc638509
commit 331edafb60
11 changed files with 2069 additions and 1110 deletions
@@ -0,0 +1,299 @@
+# 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.