wordpress-public-workspace/GRACEPRESS-PUBLIC-PLUGIN-STANDARDS.md

GracePress Public Plugin Standards

House requirements for plugins built in the first-class wpplugin lane and intended for eventual WordPress.org publication. These supplement, but never replace, WORDPRESS-ORG-REQUIREMENTS.md.

A. Product identity and lane separation

• GP-01: The public plugin is a genuinely independent codebase under wordpress-plugins//, not an alias or release flag applied to the internal plugin.
• GP-02: The public slug, package name, text domain, PHP identifiers, assets, changelog, and metadata are internally consistent.
• GP-03: The existing internal GracePress plugin remains intact until an explicit migration and retirement decision.
• GP-04: The public and internal plugins can be installed together during transition without fatal collisions.
• GP-05: Private catalog updaters, private telemetry, internal control-plane assumptions, private credentials, and infrastructure-specific endpoints are absent from the public plugin.
• GP-06: Shared option compatibility is intentional and documented; migrations are reversible and never silently destroy settings.

B. GracePress visual language

• GP-07: The admin page has a module-specific wrapper and does not depend on GracePress Central or another private plugin for styling.
• GP-08: The page begins with a large, purposeful branded hero using a dark image or self-contained background, a module-color accent, a strong title, a concise purpose statement, and useful version/status chips.
• GP-09: Information architecture uses clear sections, cards, tabs, previews, or diagnostics rather than one long undifferentiated settings form.
• GP-10: Primary actions are obvious, destructive actions are visually distinct, defaults are understandable, and advanced controls are progressively disclosed.
• GP-11: Controls are compact but not cramped, labels explain outcomes, help text is plain, and saved/error states are unmistakable.
• GP-12: The interface has a polished narrow-screen single-column layout and remains usable with keyboard navigation, browser zoom, and reduced motion.
• GP-13: The footer displays the plugin name and version, a restrained GracePress/Christ IT attribution, "All glory to Jesus Christ," and a contextually relevant Bible verse.
• GP-14: Scripture and branding remain sincere and non-coercive; they do not interrupt public front-end output, create unsolicited links, or conflict with WordPress.org rules.
• GP-15: Admin assets are local, license-compatible, optimized, and do not leak visitor or administrator data through remote font, image, tracking, or analytics requests.

C. User experience and feature discipline

• GP-16: First-run behavior is safe, useful, and understandable without documentation.
• GP-17: Settings use sensible defaults and offer a reliable reset path without deleting unrelated site data.
• GP-18: Every visible control maps to real behavior, and every documented feature exists in the release candidate.
• GP-19: Advanced features solve a demonstrated user problem; competitor research informs prioritization but no proprietary code, wording, art, or distinctive trade dress is copied.
• GP-20: Features are evaluated for user value, maintenance burden, accessibility, performance, theme compatibility, and review risk before implementation.
• GP-21: The plugin provides concise in-page usage/help information and enough diagnostics to resolve ordinary problems without exposing secrets.
• GP-22: Defaults do not unexpectedly alter wp-admin, override accessibility preferences, or apply aggressive visual effects without clear consent.

D. Engineering and release discipline

• GP-23: Git source is canonical; scripts/build and scripts/ship are the only packaging and catalog paths.
• GP-24: A meaningful edit receives a timestamped rollback copy in the modules .old directory before modification.
• GP-25: Plugin header Version, runtime constant, readme Stable tag, CHANGELOG.md, public readme changelog, dist metadata, and package filename stay synchronized.
• GP-26: CHANGELOG.md records durable engineering detail; readme.txt records concise public-facing changes.
• GP-27: Source stays readable and ASCII by default; public copy avoids mojibake, pasted smart punctuation, and unexplained generated code.
• GP-28: No durable password, token, key, private endpoint credential, or recovery material enters source, documentation, packages, logs, Git, or memory.
• GP-29: Security, privacy, accessibility, performance, internationalization, and compatibility are release gates, not cleanup tasks deferred until after submission.
• GP-30: The independent Docker WordPress lab is the primary manual acceptance environment before any production installation.
• GP-31: The exact built ZIP, not merely the source directory, is installed and exercised before release.
• GP-32: Build is the default completion boundary. Ship, WordPress.org submission, SVN publication, and production replacement each require explicit authorization.
• GP-33: One coherent release candidate gets one bounded validation pass; failures return to a named repair phase instead of causing recursive or endless checking.
• GP-34: A release-readiness report records checklist status, unresolved risks, test evidence, exact artifact identity, and the decision to stop, ship, or submit.

E. Dark Mode specific acceptance additions

• DM-01: Dark mode never traps users in an unreadable state and always offers a reliable visible restoration path.
• DM-02: System preference, manual selection, schedule, and default mode have explicit precedence and deterministic behavior.
• DM-03: Anti-FOUC behavior does not block rendering, inject invalid markup, or create a flash worse than the condition it addresses.
• DM-04: Images, video, SVG, canvas, embeds, form controls, code blocks, editors, modals, and admin bars are checked for inappropriate inversion or low contrast.
• DM-05: Exclusion selectors and custom CSS are bounded, sanitized appropriately for their purpose, documented as powerful advanced settings, and cannot inject executable markup.
• DM-06: Keyboard shortcuts do not conflict with common browser, editor, or assistive-technology commands and can be disabled if needed.
• DM-07: Motion and transition effects honor prefers-reduced-motion.
• DM-08: Front-end JavaScript works without jQuery unless jQuery is an intentional declared dependency, and failure of localStorage degrades safely.
• DM-09: Generated CSS and inline scripts are minimized, safely encoded, and compatible with common Content Security Policy configurations where practical.
• DM-10: Theme, block editor, classic editor, full-site editing, logged-out, logged-in, mobile, and multisite-relevant behavior are tested according to declared support.

Last revised: 2026-08-22.