From ed6523ebb1862ccb7437421a16e58e09ca356d6a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Sep 2025 03:14:13 +0000 Subject: [PATCH 1/2] Initial plan From 4a30a87759b2c04aa99db2b3726bd21fa9656c9f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Sep 2025 03:20:01 +0000 Subject: [PATCH 2/2] Create comprehensive README.md files for all major folders Co-authored-by: ashleyshaw <1805352+ashleyshaw@users.noreply.github.com> --- README.md | 79 ++++++++++++++++++- block-themes/README.md | 40 ++++++++++ coding-standards/README.md | 67 ++++++++++++++++ .../inline-documentation-standards/README.md | 47 +++++++++++ .../wordpress-coding-standards/README.md | 62 +++++++++++++++ frontmatter/README.md | 48 +++++++++++ 6 files changed, 342 insertions(+), 1 deletion(-) create mode 100644 block-themes/README.md create mode 100644 coding-standards/README.md create mode 100644 coding-standards/inline-documentation-standards/README.md create mode 100644 coding-standards/wordpress-coding-standards/README.md create mode 100644 frontmatter/README.md diff --git a/README.md b/README.md index a59173e..1f497d0 100644 --- a/README.md +++ b/README.md @@ -1 +1,78 @@ -# wp-docs \ No newline at end of file +# WordPress Documentation Hub + +A comprehensive collection of WordPress development documentation, coding standards, and best practices. This repository serves as a central resource for modern WordPress development workflows, from block themes to AI-assisted development patterns. + +## 📁 Documentation Sections + +### [🎨 Block Themes](block-themes/) +Modern WordPress theme development with comprehensive guides for: +- **Fluid Typography & Spacing** - Responsive design using clamp() and custom properties +- **Design Systems** - Color palettes, spacing presets, and design tokens +- **Theme Structure** - Templates, patterns, and global styles +- **Best Practices** - CSS specificity, naming conventions, and optimization + +**Key Files:** [Fluid Typography](block-themes/fluid-typography.md) • [Global Styles](block-themes/global-styles.md) • [Theme Structure](block-themes/theme-structure-epi.md) + +### [📋 Coding Standards](coding-standards/) +Comprehensive coding standards for WordPress development: +- **[LightSpeed Standards](coding-standards/ash-research/)** - Enhanced WordPress standards (WPCS v3.2.0) with security-first approach +- **[WordPress Core Standards](coding-standards/wordpress-coding-standards/)** - Official WordPress coding guidelines +- **[Inline Documentation](coding-standards/inline-documentation-standards/)** - Code commenting and documentation practices + +**Key Features:** Security by default • WCAG 2.2 AA accessibility • Performance optimization • Maintainable code patterns + +### [⚙️ YAML Frontmatter](frontmatter/) +Standardized frontmatter patterns for modern development workflows: +- **GitHub Templates** - Issue forms, PR templates, and repository configuration +- **AI Agent Configurations** - GitHub Copilot, Claude, and Gemini setups +- **Copilot Space** - Complete AI-assisted development environment +- **Schema Validation** - Consistent metadata patterns across all template types + +**Key Files:** [Frontmatter Cheat Sheet](frontmatter/YAML%20Frontmatter%20Cheat%20Sheet.md) • [Schema Guidelines](frontmatter/YAML-Frontmatter%20Schema-Guidelines.md) • [Copilot Space Instructions](frontmatter/YAML-Frontmatter-Copilot-Space-Instructions.md) + +### [🧱 Gutenberg Documentation](gutenberg/) +Complete Gutenberg block editor documentation: +- **[Getting Started](gutenberg/getting-started/)** - Development environment setup and tutorials +- **[How-to Guides](gutenberg/how-to-guides/)** - Practical implementation guides +- **[Reference Guides](gutenberg/reference-guides/)** - API references and technical documentation +- **[Schemas](gutenberg/schemas/)** - Block and configuration schemas + +**Key Areas:** Block development • Editor extensibility • Theme integration • API references + +## 🚀 Quick Start + +### For Theme Developers +1. Review [Block Themes documentation](block-themes/) for modern theme development +2. Implement [Fluid Typography](block-themes/fluid-typography.md) and [Spacing](block-themes/fluid-spacing.md) +3. Follow [LightSpeed Coding Standards](coding-standards/ash-research/) for best practices + +### For Plugin Developers +1. Start with [WordPress Coding Standards](coding-standards/wordpress-coding-standards/) +2. Review [Gutenberg How-to Guides](gutenberg/how-to-guides/) for block development +3. Implement [Inline Documentation Standards](coding-standards/inline-documentation-standards/) + +### For AI-Assisted Development +1. Set up [YAML Frontmatter](frontmatter/) for standardized templates +2. Configure [Copilot Space](frontmatter/YAML-Frontmatter-Copilot-Space-Instructions.md) for AI workflows +3. Use [Schema Guidelines](frontmatter/YAML-Frontmatter%20Schema-Guidelines.md) for validation + +## 🎯 Core Principles + +- **Security First**: All patterns emphasize WordPress security best practices +- **Accessibility**: WCAG 2.2 Level AA compliance baseline across all documentation +- **Performance**: Optimization-focused approaches in all recommendations +- **Modern Standards**: Up-to-date with latest WordPress and web development practices +- **AI Integration**: Documentation patterns optimized for AI-assisted development workflows + +## 🔧 Standards at a Glance + +| Area | Standard | Key Features | +|------|----------|--------------| +| **Theme Development** | Block-first, Fluid Design | Responsive typography, Design tokens, Performance optimization | +| **Code Quality** | WordPress + LightSpeed Standards | Security by default, WCAG 2.2 AA, PHPDoc documentation | +| **AI Integration** | YAML Frontmatter Schemas | GitHub templates, Copilot Space, Cross-platform AI configs | +| **Block Development** | Gutenberg Best Practices | Modern JavaScript, React patterns, WordPress APIs | + +--- + +This documentation hub ensures consistent, secure, and maintainable WordPress development across all project types and development workflows. \ No newline at end of file diff --git a/block-themes/README.md b/block-themes/README.md new file mode 100644 index 0000000..074893a --- /dev/null +++ b/block-themes/README.md @@ -0,0 +1,40 @@ +# Block Themes Documentation + +This folder contains comprehensive documentation for WordPress block themes, covering modern theme development practices, fluid design systems, and best practices for creating responsive, accessible themes. + +## Files + +### Core Theme Development +- **[Theme Structure](theme-structure-epi.md)** - Guidelines for organizing block theme files and structure +- **[Templates](templates.md)** - Working with block theme templates and template parts +- **[Patterns](patterns.md)** - Creating and managing block patterns for themes +- **[Global Styles](global-styles.md)** - Implementing theme.json and global styling systems + +### Design Systems & Styling +- **[Fluid Typography](fluid-typography.md)** - Responsive typography using clamp() and custom properties +- **[Fluid Spacing](fluid-spacing.md)** - Implementing fluid spacing systems for responsive layouts +- **[Fluid Typography & Spacing Guidelines](FluidTypography-Fluid-Spacing-Guidelines.md)** - Comprehensive guide to fluid design principles +- **[Spacing Presets](spacing-presets.md)** - Defining and using spacing scale in theme.json +- **[Typesets](typesets.md)** - Typography system configuration and best practices + +### Color & Visual Design +- **[Colour Palettes](colour-palettes.md)** - Setting up theme color systems and palettes +- **[Style Variations](style-variations.md)** - Creating theme style variations +- **[Block Styles](block-styles.md)** - Custom block styling approaches +- **[Section Styles](section-styles.md)** - Styling theme sections and layouts + +### Development Best Practices +- **[CSS Specificity](css-specificity.md)** - Managing CSS specificity in block themes +- **[Naming Conventions](naming-conventions.md)** - Consistent naming patterns for theme development +- **[Standardising Colours, Fonts & Spacing](standardising-colours-fonts-spacing.md)** - Creating consistent design tokens + +### Additional Resources +- **[Best Practices (Fluid Spacing & Typography)](best-practices-fluid-spacing-and%20typography.md)** - Advanced fluid design techniques +- **[theme-68.json](theme-68.json)** - Example theme.json configuration file + +## Key Concepts + +- **Fluid Design**: Modern responsive design using CSS clamp() and custom properties +- **Design Tokens**: Systematic approach to colors, typography, and spacing +- **Block-First**: Designing themes around the block editor experience +- **Progressive Enhancement**: Building accessible, performant themes that work everywhere \ No newline at end of file diff --git a/coding-standards/README.md b/coding-standards/README.md new file mode 100644 index 0000000..9116d77 --- /dev/null +++ b/coding-standards/README.md @@ -0,0 +1,67 @@ +# Coding Standards Documentation + +This folder contains comprehensive coding standards and style guides for WordPress development, covering multiple approaches and specialized areas of development practice. + +## Directories + +### [LightSpeed Coding Standards](ash-research/) +Complete coding standards suite aligned with WordPress Coding Standards (WPCS v3.2.0), incorporating guidance from industry leaders like 10up, Human Made, and Dekode. + +**Key Features:** +- Comprehensive coverage: PHP, JavaScript, CSS, HTML, Accessibility, and more +- Security-first approach with escaping, sanitization, and nonce requirements +- WCAG 2.2 Level AA accessibility baseline +- Performance-focused guidelines +- Fluid spacing and typography standards + +### [WordPress Coding Standards](wordpress-coding-standards/) +Official WordPress coding standards covering core development practices and community guidelines. + +**Includes:** +- PHP coding standards and best practices +- HTML structure and semantic guidelines +- CSS styling conventions +- JavaScript development standards +- Accessibility requirements + +### [Inline Documentation Standards](inline-documentation-standards/) +Specialized documentation focusing on code commenting and inline documentation practices. + +**Covers:** +- PHP documentation standards (PHPDoc-inspired) +- JavaScript commenting conventions +- Best practices for maintainable code documentation + +## Top-Level Files + +### Reference Materials +- **[WordPress Coding Standards](wordpress-coding-standards.md)** - Overview of official WordPress standards +- **[Inline Documentation Standards](inline-documentation-standards.md)** - Guide to code documentation practices +- **[Idiomatic CSS](idiomatic-css.md)** - CSS writing principles and conventions +- **[Style Guide](styleguide.md)** - General style and formatting guidelines +- **[Index](index.md)** - Comprehensive index of all standards and guidelines + +## Standards Hierarchy + +1. **Security First**: All code must follow security best practices +2. **Accessibility**: WCAG 2.2 Level AA compliance baseline +3. **Performance**: Lean dependencies and optimization-focused approach +4. **Maintainability**: Clear documentation and consistent patterns +5. **WordPress Compatibility**: Alignment with core WordPress practices + +## Key Principles + +- **Tabs for indentation** (spaces for alignment only) +- **Security by default** (escaping, sanitization, nonces) +- **Accessibility**: WCAG 2.2 Level AA baseline +- **Performance**: Keep dependencies lean; measure, then optimize +- **Documentation**: Prioritize clarity and maintainability + +## Getting Started + +1. **New to WordPress?** Start with [WordPress Coding Standards](wordpress-coding-standards/) +2. **Working on a LightSpeed project?** Use [LightSpeed Coding Standards](ash-research/) +3. **Need documentation guidance?** Check [Inline Documentation Standards](inline-documentation-standards/) +4. **Writing CSS?** Review [Idiomatic CSS](idiomatic-css.md) principles + +These standards ensure consistency, security, and maintainability across all WordPress development projects. \ No newline at end of file diff --git a/coding-standards/inline-documentation-standards/README.md b/coding-standards/inline-documentation-standards/README.md new file mode 100644 index 0000000..ba7a1bc --- /dev/null +++ b/coding-standards/inline-documentation-standards/README.md @@ -0,0 +1,47 @@ +# Inline Documentation Standards + +WordPress coding standards for inline documentation, ensuring code is well-documented, maintainable, and follows established patterns for commenting and documentation blocks. + +## Files + +- **[PHP Documentation Standards](php.md)** - Complete guide to PHP documentation in WordPress using PHPDoc-inspired standards +- **[JavaScript Documentation Standards](javascript.md)** - JavaScript commenting conventions and documentation practices + +## Overview + +These standards cover how to properly document your code using inline comments and documentation blocks. WordPress uses a customized documentation schema that draws inspiration from PHPDoc for PHP and established JavaScript documentation patterns. + +## Key Areas Covered + +### PHP Documentation +- Function and method documentation blocks +- Class and interface documentation +- Property documentation +- Parameter and return value documentation +- WordPress-specific hooks and filters documentation +- File header documentation + +### JavaScript Documentation +- Function and method commenting +- Object and class documentation +- Module documentation patterns +- Parameter and return documentation +- Event handler documentation + +## Documentation Principles + +- **Clarity**: Documentation should make code easier to understand +- **Completeness**: All public functions, classes, and methods should be documented +- **Consistency**: Follow established patterns across the codebase +- **Accuracy**: Keep documentation updated with code changes +- **Helpful Context**: Explain not just what, but why and how + +## WordPress-Specific Requirements + +- Use WordPress-specific tags for hooks, filters, and actions +- Document all parameters and return values +- Include @since tags for version tracking +- Follow WordPress coding standards for formatting +- Use proper escaping and sanitization in examples + +These documentation standards ensure that WordPress code is accessible to developers at all levels and maintains consistency across projects. \ No newline at end of file diff --git a/coding-standards/wordpress-coding-standards/README.md b/coding-standards/wordpress-coding-standards/README.md new file mode 100644 index 0000000..b45cdfe --- /dev/null +++ b/coding-standards/wordpress-coding-standards/README.md @@ -0,0 +1,62 @@ +# WordPress Coding Standards + +Official WordPress coding standards covering all aspects of development within the WordPress ecosystem. These standards are mandatory for WordPress Core and strongly recommended for themes and plugins. + +## Files + +- **[PHP Coding Standards](php.md)** - Comprehensive PHP coding standards for WordPress development +- **[HTML Coding Standards](html.md)** - HTML structure, semantics, and accessibility guidelines +- **[CSS Coding Standards](css.md)** - CSS writing conventions and organization practices +- **[JavaScript Coding Standards](javascript.md)** - JavaScript development standards and best practices +- **[Accessibility Standards](accessibility.md)** - WCAG compliance and accessibility requirements + +## Overview + +These coding standards are not just about code style, but encompass established best practices regarding interoperability, translatability, and security in the WordPress ecosystem. While themes and plugins may choose different coding styles, these standards represent critical best practices that should be followed regardless of style preferences. + +## Core Principles + +### Security First +- Sanitization of all input data +- Escaping of all output data +- Proper use of nonces for form security +- SQL injection prevention +- XSS attack mitigation + +### Accessibility +- WCAG 2.1 AA compliance baseline +- Semantic HTML structure +- Proper ARIA attributes +- Keyboard navigation support +- Screen reader compatibility + +### Performance +- Efficient database queries +- Optimized asset loading +- Minimal HTTP requests +- Proper caching strategies +- Mobile-first responsive design + +### Internationalization +- Translatable strings using WordPress i18n functions +- Proper text domain usage +- RTL language support +- Cultural sensitivity in design + +### Interoperability +- WordPress coding patterns and conventions +- Hook and filter usage +- Plugin/theme compatibility +- Core WordPress function usage + +## Implementation + +While not all existing code may fully comply with these standards, **all newly committed and/or updated code should fully comply** with these coding standards. This ensures progressive improvement of code quality across the WordPress ecosystem. + +## Related Resources + +- See [Inline Documentation Standards](../inline-documentation-standards/) for code commenting guidelines +- Review [LightSpeed Coding Standards](../ash-research/) for enhanced standards building on these foundations +- Check WordPress Developer Handbook for additional implementation guidance + +These standards form the foundation for secure, accessible, and maintainable WordPress development. \ No newline at end of file diff --git a/frontmatter/README.md b/frontmatter/README.md new file mode 100644 index 0000000..fa5e330 --- /dev/null +++ b/frontmatter/README.md @@ -0,0 +1,48 @@ +# YAML Frontmatter Documentation + +This folder contains comprehensive documentation for YAML frontmatter usage across GitHub templates, AI agent configurations, and Copilot Space setups. Essential for standardizing metadata and configuration patterns in WordPress development workflows. + +## Files + +### Core Documentation +- **[YAML Frontmatter Cheat Sheet](YAML%20Frontmatter%20Cheat%20Sheet.md)** - Quick reference guide for GitHub templates and AI agent configurations +- **[YAML Frontmatter Schema Guidelines](YAML-Frontmatter%20Schema-Guidelines.md)** - Comprehensive schema documentation and validation patterns +- **[YAML Frontmatter Copilot Space Instructions](YAML-Frontmatter-Copilot-Space-Instructions.md)** - Complete setup guide for Copilot Space with frontmatter standards + +### Additional Resources +- **[YAML Frontmatter Schemas for GitHub, Copilot, Claude, and Gemini Files](YAML%20Frontmatter%20Schemas%20for%20GitHub,%20Copilot,%20Claude,%20and%20Gemini%20Files1.md)** - Platform-specific schema documentation + +## What's Covered + +### GitHub Templates +- **Issue Forms**: YAML frontmatter for GitHub issue templates with form fields, labels, and assignments +- **Pull Request Templates**: Frontmatter configuration (though not processed by GitHub, useful for documentation) +- **Repository Configuration**: Standardizing template metadata across projects + +### AI Agent Configurations +- **GitHub Copilot**: Instructions, prompts, and chat modes with proper frontmatter +- **Claude Subagents**: Configuration schemas for Claude-specific agents and tools +- **Gemini Integration**: Frontmatter patterns for Gemini-based workflows +- **Universal Agents**: Cross-platform AI agent configuration standards + +### Copilot Space Setup +- **File Structure**: Organizing AI-related files in repositories +- **Schema Validation**: Ensuring consistent frontmatter across all template types +- **Best Practices**: WordPress-friendly Copilot Space configurations +- **Integration Patterns**: Connecting frontmatter with development workflows + +## Key Benefits + +- **Standardization**: Consistent metadata patterns across all template types +- **Validation**: Schema-based validation for frontmatter correctness +- **Automation**: AI-friendly configurations that enhance development workflows +- **WordPress Integration**: Templates and patterns optimized for WordPress development +- **Cross-Platform**: Works with GitHub, Copilot, Claude, Gemini, and other AI tools + +## Getting Started + +1. Start with the **[YAML Frontmatter Cheat Sheet](YAML%20Frontmatter%20Cheat%20Sheet.md)** for quick reference +2. Review **[Schema Guidelines](YAML-Frontmatter%20Schema-Guidelines.md)** for detailed implementation +3. Follow **[Copilot Space Instructions](YAML-Frontmatter-Copilot-Space-Instructions.md)** for complete setup + +This documentation ensures your WordPress projects maintain consistent, validated frontmatter across all GitHub templates and AI configurations. \ No newline at end of file