block-accessibility-checks/docs/PROPOSAL.md at Add/Proposal · Troychaplin/Block-Accessibility-Checks · GitHub  🔗 **Source:** [block-accessibility-checks/docs/PROPOSAL.md at Add/Proposal · Troychaplin/Block-Accessibility-Checks · GitHub](https://github.com/troychaplin/block-accessibility-checks/blob/add/proposal/docs/PROPOSAL.md) > [!note]+ Document Notes > tags: #wordpress #accessibility #validation #block-editor > author: troychaplin > source: GitHub > reference: https://github.com/troychaplin/block-accessibility-checks/blob/add/proposal/docs/PROPOSAL.md > date created: 2025-01-16 14:42 > > # 🏷️ Title: Proposal: A Block Editor Validation API for WordPress > <!-- deep-read:sections start --> ## 🧰 Action Inbox - [H1] Review existing Gutenberg validation issues and PRs — understand prior art #wordpress - [H2] Evaluate Block Accessibility Checks plugin implementation — study reference architecture #validation - [H3] Consider async validation patterns for server-side checks — explore technical feasibility #block-editor ## 🧭 Table of Contents - [[#📝 Summary]] - [[#📖 Main Content]] - [[#🗒️ Notes]] - [[#📚 References]] - [[#🗣️ Paraphrase]] - [[#📰 Newsletter]] - [[#✅ Action Items]] - [[#🧪 Hypotheses]] - [[#📊 Methodology]] - [[#❓ Questions]] - [[#🔮 Future Research]] - [[#💡 Implications]] - [[#🧠 Learning Styles Assessment]] - [[#📊 Accessibility Assessment]] - [[#🌍 DEIB Assessment]] - [[#✅ Logical Validity]] - [[#🛡️ DARVO Analysis]] - [[#🎯 Conclusion]] ### 🔗 References - [Block Accessibility Checks Plugin](https://wordpress.org/plugins/block-accessibility-checks/) - [GitHub Repository](https://github.com/troychaplin/block-accessibility-checks) - [Plugin Documentation](https://blockaccessibilitychecks.com) ## 📝 Summary - **What happened**: Troy Chaplin proposes a standardized Validation API for WordPress block editor to enable real-time content validation - **Why it matters**: Currently, plugins must independently solve validation problems, creating fragmented user experiences and preventing widespread adoption of content quality tools - **Key stakeholders**: WordPress core team, plugin developers, content creators, accessibility advocates - **Risks and tradeoffs**: Additional API surface to maintain vs. ecosystem-wide validation consistency - **Bottom line**: A unified validation framework would lower barriers for quality plugins while providing consistent user experience ## 📖 Main Content The proposal introduces a declarative validation framework for WordPress that would standardize how plugins validate block content, post meta, and overall document structure. Unlike current approaches where each plugin builds custom validation systems, this API would provide unified registration, execution, and UI patterns. The system builds on existing WordPress primitives rather than introducing new mechanisms. It leverages established APIs like `@wordpress/hooks`, `lockPostSaving`, `editor.BlockEdit`, and `register_post_meta` but provides a cohesive layer that standardizes their use for validation purposes. Three validation scopes are proposed: block attributes (alt text, button labels), post meta fields (SEO descriptions, custom fields), and editor-wide checks (document structure, required elements). Each scope has distinct registration patterns but shares a unified severity model with configurable error/warning levels. The Block Accessibility Checks plugin serves as a working reference implementation, demonstrating the complete lifecycle from check registration to real-time feedback. The proposal emphasizes that only the API framework belongs in core—specific validation rules remain in plugin territory. ## 🗒️ Notes #### Key Problem Statement - Key idea: WordPress lacks unified content validation despite robust editing tools - Evidence: "Every plugin builds its own registration system" and "most plugins simply don't validate content at all" #### Three Validation Scopes Architecture - Key idea: Distinct patterns for block attributes, post meta, and editor-wide validation - Evidence: "Block attributes, post meta fields, and editor-wide document state each have distinct registration and execution patterns" #### Severity Model Design - Key idea: Four-level severity system from error (blocks saving) to none (disabled) - Evidence: "error prevents saving/publishing, warning shows feedback but allows saving, settings is admin-configurable" #### PHP Registration, JavaScript Validation - Key idea: Follows existing WordPress block API patterns - Evidence: "PHP declares configuration and JavaScript handles runtime behavior" #### Building on Existing Primitives - Key idea: No new low-level mechanisms, cohesive layer on stable APIs - Evidence: Lists @wordpress/hooks, lockPostSaving, editor.BlockEdit, PluginPrePublishPanel as existing building blocks #### Reference Implementation Success - Key idea: Block Accessibility Checks plugin proves concept viability - Evidence: "Available on WordPress.org since 2023 and demonstrates the full lifecycle" #### Clear Core vs Plugin Boundaries - Key idea: API framework in core, specific validation rules in plugins - Evidence: "What belongs in core is the underlying system that makes declarative content validation possible" #### Prior Art Documentation - Key idea: Multiple Gutenberg issues have requested pieces of this functionality - Evidence: References issues #4063, #14954, #13413, #7020 spanning 2017-2019 #### Standardized UI Patterns - Key idea: Consistent validation feedback across all plugins - Evidence: "Block-level indicators, consolidated sidebar, header summary" as unified patterns #### Ecosystem Benefits - Key idea: Lower barriers enable accessibility-focused plugin ecosystem - Evidence: "Plugin developers get validation capabilities 'for free' through a simple registration API" ## 📚 References - [Gutenberg Issue #4063 - Block Input Validation](https://github.com/WordPress/gutenberg/issues/4063) - [Gutenberg Issue #14954 - Server-side Block Validation](https://github.com/WordPress/gutenberg/issues/14954) - [Gutenberg Issue #13413 - Third-party Save Validation](https://github.com/WordPress/gutenberg/issues/13413) - [Block Accessibility Checks Documentation](https://blockaccessibilitychecks.com) ## 🗣️ Paraphrase - WordPress needs a unified way to validate block editor content because currently every plugin that wants to check content quality has to build its own validation system from scratch - The proposed Validation API would provide standardized patterns for registering checks, displaying results, and preventing publication when critical issues exist, all built on existing WordPress APIs - A reference implementation already exists and works in production, demonstrating that the technical approach is sound and the developer experience is practical ## 📰 Newsletter WordPress developers have long requested standardized content validation in the block editor, and now there's a concrete proposal for making it happen. Troy Chaplin's Validation API proposal offers a unified framework that would let plugins easily validate block attributes, post meta, and document structure without reinventing the wheel. The key insight? Build on what already works. Instead of new APIs, this leverages existing hooks, post-locking mechanisms, and editor components in a standardized way. The Block Accessibility Checks plugin proves the concept works—it's been validating content on WordPress.org since 2023. For the community, this could be transformative. Imagine accessibility plugins that "just work" together, SEO tools that share consistent UI patterns, and editorial workflows that don't conflict with each other. The proposal keeps the API in core while leaving specific validation rules to plugins—exactly the right boundary. Resources: [Learn WordPress](https://learn.wordpress.org/), [Developer Docs](https://developer.wordpress.org/), [WP-CLI](https://wp-cli.org/) ## ✅ Action Items #### WordPress - Core: Evaluate proposal for inclusion in Gutenberg roadmap, assess impact on existing editor APIs - Core Program Team: Coordinate review across accessibility, performance, and developer experience teams - Accessibility: Review validation patterns for WCAG compliance support, provide guidance on inclusive messaging - Design: Define standardized UI components for validation feedback across editor interfaces - Documentation: Prepare developer guides for validation API usage patterns and best practices #### DevRel - Developer advocacy: Present validation API benefits at WordCamps, demonstrate ecosystem opportunities - Education: Create workshops on content validation patterns, accessibility-focused development - Developer experience: Review API ergonomics, ensure registration patterns match WordPress conventions - Community management: Gather plugin developer feedback on validation needs and implementation barriers ## 🧪 Hypotheses - A standardized validation API will increase the number of accessibility-focused plugins in the WordPress ecosystem - Unified validation UI patterns will improve user experience compared to fragmented plugin-specific implementations - Building on existing WordPress primitives will reduce maintenance burden compared to introducing new core APIs - Separating validation infrastructure (core) from validation rules (plugins) will accelerate adoption ### 📊 Methodology - Plugin ecosystem analysis: Survey existing validation implementations to measure fragmentation and inconsistencies - Developer adoption study: Measure plugin creation rates for validation-focused tools before/after API availability - User experience testing: Compare task completion and error resolution across unified vs. fragmented validation UIs ### ❓ Questions - Should validation results live in a dedicated @wordpress/data store for better cross-plugin coordination? - How can async validation patterns support server-side checks without blocking editor performance? - Would block.json integration for simple validation rules improve developer adoption? ### 🔮 Future Research - Integration patterns with emerging WordPress features like DataViews and block variation APIs - Performance optimization strategies for real-time validation in content-heavy documents - Accessibility evaluation of validation feedback patterns for screen reader and keyboard users ### 💡 Implications - **Practice**: Plugin developers get standardized validation capabilities, reducing custom implementation effort - **Policy**: Organizations could enforce content governance and compliance requirements consistently - **Security**: Centralized validation provides single point for security review and updates - **Education**: Unified patterns reduce training overhead for content creators using validation tools - **Funding**: Lower development barriers could increase accessibility tool funding and adoption ### 🧠 Learning Styles Assessment Reading level estimate: 12-14 (technical documentation) #### 👀 Visual learners - Present: Code examples with syntax highlighting, architectural scope diagrams - Improve: API flow diagrams, validation UI mockups, component relationship visuals #### 🔊 Aural learners - Present: Embedded video demo of validation system in action - Improve: Audio walkthrough of code examples, developer interview discussions #### 🗣️ Verbal learners - Present: Clear terminology definitions, analogies to existing WordPress patterns - Improve: Glossary section, comparison tables with current approaches #### 🧩 Kinesthetic learners - Present: Working code examples, reference implementation to explore - Improve: Interactive demo environment, step-by-step integration tutorials #### 🧠 Logical learners - Present: Clear problem/solution structure, systematic API scope breakdown - Improve: Decision matrices for core vs plugin boundaries, performance impact analysis #### 🧑‍🤝‍🧑 Social learners - Present: GitHub discussion integration, community feedback mechanisms - Improve: Developer collaboration guides, plugin integration examples #### 🧘‍♀️ Solitary learners - Present: Comprehensive documentation with self-contained examples - Improve: Self-assessment checklists for implementation, independent exploration paths #### 🌿 Naturalistic learners - Present: Ecosystem impact analysis, organic adoption patterns - Improve: Plugin ecosystem health metrics, validation tool lifecycle thinking ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Proper heading hierarchy, code block labeling - Improve: ARIA landmarks for major sections, more descriptive link text #### Keyboard navigation - Present: Standard GitHub interface keyboard support - Improve: Skip links for long code examples, keyboard shortcuts documentation #### Contrast and readability - Present: GitHub's standard contrast meets WCAG requirements - Improve: Verify code syntax highlighting maintains sufficient contrast #### Text resizing and reflow - Present: Responsive GitHub layout supports text scaling - Improve: Ensure code examples remain readable at 200% zoom #### Media and captions - Present: Video demo link provided - Improve: Transcript for embedded video demo, audio descriptions for visual elements #### Forms and interactions - Present: Standard GitHub form accessibility - Improve: Consider validation API demo form with accessibility annotations ### 🌍 DEIB Assessment #### Cultural breadth - Present: Technical focus avoids cultural assumptions - Improve: Consider internationalization requirements for validation messages #### Inclusive language - Present: Technical terminology is well-defined - Improve: Ensure error messages accommodate non-native English speakers #### Neurodiversity support - Present: Well-structured document with clear sections - Improve: More frequent subheadings in long code sections, consistent formatting #### Representation - Present: Focus on technical content rather than personal representation - Improve: Consider diverse use cases beyond accessibility in examples #### Psychological safety - Present: Professional, respectful technical communication - Improve: Acknowledge learning curve concerns, provide supportive guidance language ### ✅ Logical Validity #### Strong reasoning - Deductive strength: Clear problem → standardized solution → ecosystem benefits logic chain - Inductive strength: Reference implementation success suggests broader API viability - Causal reasoning: API standardization → reduced fragmentation → better user experience - Analogical strength: Comparison to existing block API patterns supports design decisions #### Fallacies - Appeal to authority: References to core contributor endorsement could be strengthened with specific quotes - False dichotomy: Present binary choice between "unified API" vs "fragmented plugins" without exploring hybrid approaches #### Tone of voice - Overall tone: Professional and technical with clear problem-solution framing, appropriate for WordPress core contribution proposal ### 🛡️ DARVO Analysis - Deny: No denial patterns detected - straightforward technical proposal - Attack: No attacks on existing systems, constructive criticism of current fragmentation - Reverse victim/offender: Not applicable to technical proposal context - Emotional cues: Professional tone with solution-focused language, no manipulative rhetoric ## 🎯 Conclusion The Validation API proposal represents a mature approach to solving real developer pain points in the WordPress ecosystem. By building on proven primitives and providing a working reference implementation, it demonstrates both technical feasibility and practical value. The clear separation between infrastructure (core) and rules (plugins) respects WordPress's extensibility philosophy while enabling ecosystem-wide consistency. For WordPress core, this offers an opportunity to enable widespread accessibility and content quality improvements without taking on the burden of maintaining specific validation rules. For the developer community, it provides the foundation for building sophisticated content validation tools without reinventing complex infrastructure. The proposal merits serious consideration as part of WordPress's accessibility and developer experience initiatives. ## 🧱 Refactor Appendix ### 📚 Literature Split Pad Purpose: Stage CEE units that become Literature notes. Split level: H3 ### [H1] Validation API builds on existing WordPress primitives > [!quote] [Proposal: A Block Editor Validation API for WordPress](https://github.com/troychaplin/block-accessibility-checks/blob/add/proposal/docs/PROPOSAL.md) by [[troychaplin]] via [[GitHub]]. Published 2025. Accessed 2025-01-16. > "A Validation API would not introduce new low-level mechanisms. Instead, it would provide a cohesive layer on top of existing, stable WordPress and Gutenberg APIs" Architecture decision that reduces maintenance burden while standardizing validation patterns across plugins. [view highlight](https://github.com/troychaplin/block-accessibility-checks/blob/add/proposal/docs/PROPOSAL.md#H1) #xref #articleseed ID:rw_validation_api_primitives ### [H2] Three validation scopes require distinct patterns > [!quote] [Proposal: A Block Editor Validation API for WordPress](https://github.com/troychaplin/block-accessibility-checks/blob/add/proposal/docs/PROPOSAL.md) > "Block attributes, post meta fields, and editor-wide document state each have distinct registration and execution patterns, but share a unified results model" Recognizes technical differences while maintaining consistent developer and user experience. [view highlight](https://github.com/troychaplin/block-accessibility-checks/blob/add/proposal/docs/PROPOSAL.md#H2) #xref ID:rw_validation_scopes --- ### 🔖 Atomic Split Pad (Zettel Candidates) Purpose: Promote reusable claims into Atomic notes. Split level: H4 #### [Z1] Standardized APIs reduce ecosystem fragmentation - WordPress validation tools lack unified patterns, causing developer duplication and user confusion - Reference: Block Editor Validation API proposal documentation - Links: [[WordPress-APIs]] [[Developer-Experience]] [[Accessibility-Infrastructure]] #### [Z2] Reference implementations prove API design viability - Working plugins demonstrate technical feasibility before core integration proposals - Reference: Block Accessibility Checks plugin as validation API proof of concept - Links: [[WordPress-Development]] [[API-Design]] [[Technical-Proposals]] --- ### ✏️ Fleeting Queue Purpose: Capture quick actions for Fleeting notes. - [F1] Research Gutenberg validation issues #4063, #14954, #13413 — understand historical context #fleeting #inbox - [F2] Test Block Accessibility Checks plugin — evaluate user experience patterns #fleeting #inbox - [F3] Review DataViews Field API validation patterns — compare approaches #fleeting #inbox <!-- deep-read:sections end --> 📄 **Full text:** ![[Full Document Contents/Articles/block-accessibility-checksdocsPROPOSAL.md at AddProposal · TroychaplinBlock-Accessibility-Checks · GitHub|block-accessibility-checks/docs/PROPOSAL.md at Add/Proposal · Troychaplin/Block-Accessibility-Checks · GitHub, https://github.com/troychaplin/]] ## Highlights - **This proposal advocates for the Validation API framework only** -- not the specific accessibility checks, settings UI, or other features provided by the Block Accessibility Checks plugin. Those remain the domain of plugins. What belongs in core is the underlying system that makes declarative content validation possible for the entire ecosystem. ([View Highlight](https://read.readwise.io/read/01kk24b086hsyxwem91chqwchn)) - Tags: 👻 ai highlighted