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/4] 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/4] 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 From efef4cf4fcbacd17002d2bce19d414d0ef02fd4a Mon Sep 17 00:00:00 2001 From: Ashley Shaw Date: Thu, 23 Oct 2025 12:00:26 +0700 Subject: [PATCH 3/4] Commit staged changes: urgent commit, pre-commit hooks suppressed to allow progress. Review required for any missed lint or test issues. --- .all-contributorsrc | 37 + .babelrc | 7 + .coderabbit.yml | 198 +- .distignore | 18 + .editorconfig | 38 + .env | 19 + .eslintignore | 18 + .eslintrc.cjs | 16 + .eslintrc.json | 22 + .gitattributes | 13 + .gitignore | 32 + .husky/pre-commit | 6 + .markdownlint.json | 19 + .npmpackagejsonlintrc.json | 10 + .npmrc | 5 + .nvmrc | 1 + .prettierignore | 18 + .prettierrc | 9 + .prettierrc.js | 29 + .shellcheckrc | 12 + .spectral-workflows.yaml | 8 + .spectral.yaml | 6 + .yamllint | 12 + AGENTS.md | 106 + CHANGELOG.md | 123 + CLAUDE.md | 172 + CODEOWNERS | 7 + CODE_OF_CONDUCT.md | 68 + CONTRIBUTING.md | 108 + DEVELOPMENT.md | 104 + GEMINI.md | 172 + GOVERNANCE.md | 73 + LICENSE | 681 ++++ README.md | 226 +- SECURITY.md | 14 + SUPPORT.md | 17 + SUPPRESSIONS.md | 24 + VERSION | 1 + YAML Frontmatter Cheat Sheet.md | 525 ---- ...Hub, Copilot, Claude, and Gemini Files1.md | 30 - ...-Frontmatter-Copilot-Space-Instructions.md | 628 ---- block-themes/_temp.txt | 348 --- ...-practices-fluid-spacing-and typography.md | 47 - block-themes/css-specificity.md | 43 - block-themes/theme-68.json | 2733 ---------------- block-themes/theme-structure-epi.md | 53 - block-themes/typesets.md | 23 - coding-standards/_temp.md | 167 - .../9-fluid-spacing-typography.md | 43 - copilot-todo.md | 0 docs/ai-copilot/README.md | 0 .../coding-standards}/README.md | 11 +- docs/coding-standards/_temp.md | 167 + .../ash-research/0-common-standards.md | 10 +- .../ash-research/1-accessibility.md | 3 + .../coding-standards}/ash-research/2-php.md | 22 +- .../ash-research/4-javascript.md | 9 +- .../coding-standards}/ash-research/5-css.md | 16 +- .../ash-research/6-inline-documentation.md | 25 +- .../ash-research/7-markdown.md | 12 +- .../coding-standards}/ash-research/8-json.md | 20 +- .../9-fluid-spacing-typography.md | 53 + .../coding-standards}/ash-research/README.md | 16 +- .../coding-standards}/idiomatic-css.md | 260 +- .../coding-standards}/index.md | 19 +- .../inline-documentation-standards.md | 7 +- .../inline-documentation-standards/README.md | 4 +- .../javascript.md | 162 +- .../inline-documentation-standards/php.md | 139 +- .../coding-standards}/styleguide.md | 8 +- .../wordpress-coding-standards.md | 11 +- .../wordpress-coding-standards/README.md | 11 +- .../accessibility.md | 2 +- .../wordpress-coding-standards/css.md | 131 +- .../wordpress-coding-standards/html.md | 16 +- .../inline-documentation-standards/README.md | 0 .../wordpress-coding-standards/javascript.md | 241 +- .../wordpress-coding-standards/php.md | 11 +- {frontmatter => docs/frontmatter}/README.md | 7 +- .../YAML Frontmatter Cheat Sheet.md | 747 +++++ .../YAML-Frontmatter Schema-Guidelines.md | 2526 +++++++++++++++ ...-Frontmatter-Copilot-Space-Instructions.md | 328 +- .../gutenberg}/getting-started/README.md | 16 +- .../getting-started/devenv/README.md | 18 +- .../devenv/get-started-with-create-block.md | 29 +- .../devenv/get-started-with-wp-env.md | 24 +- .../devenv/get-started-with-wp-scripts.md | 42 +- .../devenv/nodejs-development-environment.md | 11 +- .../gutenberg}/getting-started/faq.md | 29 +- .../getting-started/fundamentals/README.md | 0 .../fundamentals/block-in-the-editor.md | 163 +- .../fundamentals/block-json.md | 65 +- .../fundamentals/block-wrapper.md | 40 +- .../fundamentals/file-structure-of-a-block.md | 15 +- .../javascript-in-the-block-editor.md | 35 +- .../markup-representation-block.md | 4 +- .../fundamentals/registration-of-a-block.md | 36 +- .../fundamentals/static-dynamic-rendering.md | 96 +- .../gutenberg}/getting-started/glossary.md | 0 .../getting-started/quick-start-guide.md | 6 +- .../gutenberg}/getting-started/tutorial.md | 585 ++-- .../gutenberg}/how-to-guides/README.md | 0 .../gutenberg}/how-to-guides/accessibility.md | 6 +- .../how-to-guides/block-tutorial/README.md | 0 .../applying-styles-with-stylesheets.md | 114 +- .../block-tutorial/creating-dynamic-blocks.md | 154 +- .../extending-the-query-loop-block.md | 227 +- .../nested-blocks-inner-blocks.md | 240 +- .../curating-the-editor-experience/README.md | 6 +- .../block-locking.md | 30 +- .../disable-editor-functionality.md | 50 +- .../filters-and-hooks.md | 79 +- .../patterns.md | 18 +- .../theme-json.md | 205 ++ .../data-basics/1-data-basics-setup.md | 175 +- .../data-basics/2-building-a-list-of-pages.md | 422 ++- .../data-basics/3-building-an-edit-form.md | 511 +++ .../4-building-a-create-page-form.md | 366 +++ .../data-basics/5-adding-a-delete-button.md | 437 +++ .../how-to-guides/data-basics/README.md | 3 +- .../media/create-form/basic-create-form.png | Bin .../media/create-form/create-button.png | Bin .../create-form/create-form-with-text.png | Bin .../media/create-form/create-saving.png | Bin .../media/create-form/created-item.png | Bin .../media/create-form/edit-page-form.png | Bin .../media/delete-button/delete-button.png | Bin .../delete-button/deleting-in-progress.png | Bin .../media/delete-button/snackbar-error.png | Bin .../media/delete-button/snackbar-example.png | Bin .../media/delete-button/snackbar-success.png | Bin .../media/delete-button/snackbar.png | Bin .../media/edit-form/edit-button.png | Bin .../media/edit-form/form-editable.png | Bin .../media/edit-form/form-error.png | Bin .../media/edit-form/form-finished.png | Bin .../media/edit-form/form-inactive.png | Bin .../media/edit-form/form-populated.png | Bin .../media/edit-form/form-scaffold.png | Bin .../media/edit-form/form-spinner.png | Bin .../media/edit-form/modal-initial.png | Bin .../data-basics/media/finished-app.jpg | Bin .../media/list-of-pages/fetch-the-data.jpg | Bin .../media/list-of-pages/filter-field.jpg | Bin .../media/list-of-pages/filter.jpg | Bin .../media/list-of-pages/indicator.jpg | Bin .../media/list-of-pages/make-a-table.jpg | Bin .../media/list-of-pages/no-results.jpg | Bin .../media/list-of-pages/pages-list.jpg | Bin .../media/list-of-pages/part1-finished.jpg | Bin .../media/list-of-pages/simple-list.jpg | Bin .../media/list-of-pages/unclear-status.jpg | Bin .../data-basics/media/setup/hello-from-js.jpg | Bin .../enqueueing-assets-in-the-editor.md | 2 + .../gutenberg}/how-to-guides/feature-flags.md | 36 +- .../gutenberg}/how-to-guides/format-api.md | 218 +- .../how-to-guides/internationalization.md | 80 +- .../gutenberg}/how-to-guides/metabox.md | 133 +- .../how-to-guides/notices/README.md | 66 +- .../notices/block-editor-notice.png | Bin .../notices/classic-editor-notice.png | Bin .../how-to-guides/platform/README.md | 15 +- .../platform/custom-block-editor.md | 197 +- .../how-to-guides/plugin-sidebar-0.md | 402 ++- .../how-to-guides/propagating-updates.md | 12 +- .../gutenberg}/how-to-guides/themes/README.md | 2 +- .../themes/global-settings-and-styles.md | 1592 +++++----- .../how-to-guides/themes/theme-support.md | 258 +- .../gutenberg}/how-to-guides/thunks.md | 210 +- .../how-to-guides/widgets/README.md | 0 .../widgets/legacy-widget-block.md | 150 +- .../how-to-guides/widgets/opting-out.md | 10 +- .../how-to-guides/widgets/overview.md | 0 docs/gutenberg/reference-guides/README.md | 71 + .../reference-guides/block-api/README.md | 22 + .../block-api/block-annotations.md | 30 +- .../block-api/block-api-versions.md | 5 +- .../block-api/block-attributes.md | 276 +- .../block-api/block-bindings.md | 210 +- .../block-api/block-context.md | 154 +- .../block-api/block-deprecation.md | 234 +- .../block-api/block-edit-save.md | 248 +- .../block-api/block-metadata.md | 659 ++-- .../block-api/block-patterns.md | 113 +- .../block-api/block-registration.md | 224 +- .../block-api/block-selectors.md | 60 +- .../block-api/block-styles.md | 40 +- .../block-api/block-supports.md | 784 ++--- .../block-api/block-templates.md | 152 +- .../block-api/block-transforms.md | 188 +- .../block-api/block-variations.md | 206 +- .../reference-guides/core-blocks.md | 958 +++--- .../gutenberg/reference-guides/data/README.md | 20 + .../data/data-core-annotations.md | 0 .../data/data-core-block-directory.md | 82 +- .../data/data-core-block-editor.md | 1912 ++++++++++++ .../reference-guides/data/data-core-blocks.md | 634 ++++ .../data/data-core-commands.md | 40 +- .../data/data-core-customize-widgets.md | 49 +- .../data/data-core-edit-post.md | 166 +- .../data/data-core-edit-site.md | 118 +- .../data/data-core-edit-widgets.md | 141 +- .../reference-guides/data/data-core-editor.md | 658 ++-- .../data/data-core-keyboard-shortcuts.md | 403 +++ .../data/data-core-notices.md | 380 +++ .../reference-guides/data/data-core-nux.md | 28 +- .../data/data-core-preferences.md | 34 +- .../data/data-core-reusable-blocks.md | 1 + .../data/data-core-rich-text.md | 69 +- .../data/data-core-viewport.md | 19 +- .../reference-guides/data/data-core.md | 920 ++++++ .../reference-guides/filters/README.md | 0 .../filters/autocomplete-filters.md | 44 +- .../reference-guides/filters/block-filters.md | 469 ++- .../filters/editor-filters.md | 114 +- .../filters/global-styles-filters.md | 42 +- .../reference-guides/filters/i18n-filters.md | 79 +- .../filters/parser-filters.md | 0 .../interactivity-api/README.md | 48 +- .../interactivity-api/api-reference.md | 1077 ++++--- .../interactivity-api/core-concepts/README.md | 0 .../core-concepts/server-side-rendering.md | 336 +- .../the-reactive-and-declarative-mindset.md | 345 +-- ...l-state-local-context-and-derived-state.md | 831 +++++ .../core-concepts/using-typescript.md | 695 +++-- .../interactivity-api/iapi-about.md | 39 +- .../interactivity-api/iapi-faq.md | 7 +- .../iapi-quick-start-guide.md | 3 - .../gutenberg}/reference-guides/packages.md | 6 +- .../gutenberg}/reference-guides/richtext.md | 76 +- .../reference-guides/slotfills/README.md | 351 +++ .../slotfills/main-dashboard-button.md | 32 +- .../plugin-block-settings-menu-item.md | 22 +- .../plugin-document-setting-panel.md | 92 + .../slotfills/plugin-more-menu-item.md | 18 +- .../slotfills/plugin-post-publish-panel.md | 12 +- .../slotfills/plugin-post-status-info.md | 8 +- .../slotfills/plugin-pre-publish-panel.md | 12 +- .../plugin-sidebar-more-menu-item.md | 61 + .../slotfills/plugin-sidebar.md | 54 + .../theme-json-reference/README.md | 11 + .../theme-json-reference/styles-versions.md | 57 + .../theme-json-reference/theme-json-living.md | 364 +++ .../gutenberg}/schemas/README.md | 20 +- docs/gutenberg/schemas/json/block.json | 931 ++++++ .../schemas/json/font-collection.json | 146 + docs/gutenberg/schemas/json/theme.json | 2585 ++++++++++++++++ docs/gutenberg/schemas/json/wp-env.json | 158 + .../wordpress/block-themes}/README.md | 7 +- .../wordpress/block-themes/docs.template.md | 5 +- .../block-themes/patterns}/patterns.md | 7 +- .../block-themes/theme.json}/block-styles.md | 29 +- .../theme.json}/colour-palettes.md | 10 +- .../theme.json/fluid-best-practices.md | 46 + .../theme.json/fluid-guidelines.md | 250 +- .../block-themes/theme.json}/fluid-spacing.md | 82 +- .../theme.json}/fluid-typography.md | 15 +- .../block-themes/theme.json}/global-styles.md | 11 +- .../theme.json}/naming-conventions.md | 24 +- .../section-styles-best-practices.md | 622 ++-- .../theme.json}/section-styles.md | 133 +- .../theme.json}/spacing-presets.md | 35 +- .../standardising-colours-fonts-spacing.md | 152 +- .../theme.json}/style-variations.md | 4 + .../block-themes/theme.json/theme-68.json | 2563 +++++++++++++++ .../block-themes/theme.json/typesets.md | 13 + eslint.config.js | 17 + eslint.config.mjs | 20 + extensions.json | 56 + frontmatter/YAML Frontmatter Cheat Sheet.md | 525 ---- ...Hub, Copilot, Claude, and Gemini Files1.md | 30 - .../YAML-Frontmatter Schema-Guidelines.md | 906 ------ .../theme-json.md | 206 -- .../data-basics/3-building-an-edit-form.md | 553 ---- .../4-building-a-create-page-form.md | 396 --- .../data-basics/5-adding-a-delete-button.md | 449 --- gutenberg/reference-guides/README.md | 71 - .../reference-guides/block-api/README.md | 22 - gutenberg/reference-guides/data/README.md | 20 - .../data/data-core-block-editor.md | 1913 ------------ .../reference-guides/data/data-core-blocks.md | 721 ----- .../data/data-core-keyboard-shortcuts.md | 440 --- .../data/data-core-notices.md | 404 --- gutenberg/reference-guides/data/data-core.md | 912 ------ ...l-state-local-context-and-derived-state.md | 842 ----- .../reference-guides/slotfills/README.md | 369 --- .../plugin-document-setting-panel.md | 100 - .../plugin-sidebar-more-menu-item.md | 80 - .../slotfills/plugin-sidebar.md | 69 - .../theme-json-reference/README.md | 11 - .../theme-json-reference/styles-versions.md | 57 - .../theme-json-reference/theme-json-living.md | 361 --- gutenberg/schemas/json/block.json | 1000 ------ gutenberg/schemas/json/font-collection.json | 146 - gutenberg/schemas/json/theme.json | 2755 ----------------- gutenberg/schemas/json/wp-env.json | 163 - jest.config.js | 17 + jest.config.json.bak | 9 + launch.json | 50 + mcp.json | 17 + wp-docs.code-workspace | 3 +- 301 files changed, 29410 insertions(+), 27484 deletions(-) create mode 100644 .all-contributorsrc create mode 100644 .babelrc create mode 100644 .distignore create mode 100644 .editorconfig create mode 100644 .env create mode 100644 .eslintignore create mode 100644 .eslintrc.cjs create mode 100644 .eslintrc.json create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100755 .husky/pre-commit create mode 100644 .markdownlint.json create mode 100644 .npmpackagejsonlintrc.json create mode 100644 .npmrc create mode 100644 .nvmrc create mode 100644 .prettierignore create mode 100644 .prettierrc create mode 100644 .prettierrc.js create mode 100644 .shellcheckrc create mode 100644 .spectral-workflows.yaml create mode 100644 .spectral.yaml create mode 100644 .yamllint create mode 100644 AGENTS.md create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 CODEOWNERS create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 DEVELOPMENT.md create mode 100644 GEMINI.md create mode 100644 GOVERNANCE.md create mode 100644 LICENSE create mode 100644 SECURITY.md create mode 100644 SUPPORT.md create mode 100644 SUPPRESSIONS.md create mode 100644 VERSION delete mode 100644 YAML Frontmatter Cheat Sheet.md delete mode 100644 YAML Frontmatter Schemas for GitHub, Copilot, Claude, and Gemini Files1.md delete mode 100644 YAML-Frontmatter-Copilot-Space-Instructions.md delete mode 100644 block-themes/_temp.txt delete mode 100644 block-themes/best-practices-fluid-spacing-and typography.md delete mode 100644 block-themes/css-specificity.md delete mode 100644 block-themes/theme-68.json delete mode 100644 block-themes/theme-structure-epi.md delete mode 100644 block-themes/typesets.md delete mode 100644 coding-standards/_temp.md delete mode 100644 coding-standards/ash-research/9-fluid-spacing-typography.md create mode 100644 copilot-todo.md create mode 100644 docs/ai-copilot/README.md rename {coding-standards => docs/coding-standards}/README.md (96%) create mode 100644 docs/coding-standards/_temp.md rename {coding-standards => docs/coding-standards}/ash-research/0-common-standards.md (75%) rename {coding-standards => docs/coding-standards}/ash-research/1-accessibility.md (99%) rename {coding-standards => docs/coding-standards}/ash-research/2-php.md (90%) rename {coding-standards => docs/coding-standards}/ash-research/4-javascript.md (93%) rename {coding-standards => docs/coding-standards}/ash-research/5-css.md (75%) rename {coding-standards => docs/coding-standards}/ash-research/6-inline-documentation.md (58%) rename {coding-standards => docs/coding-standards}/ash-research/7-markdown.md (81%) rename {coding-standards => docs/coding-standards}/ash-research/8-json.md (64%) create mode 100644 docs/coding-standards/ash-research/9-fluid-spacing-typography.md rename {coding-standards => docs/coding-standards}/ash-research/README.md (70%) rename {coding-standards => docs/coding-standards}/idiomatic-css.md (61%) rename {coding-standards => docs/coding-standards}/index.md (64%) rename {coding-standards => docs/coding-standards}/inline-documentation-standards.md (87%) rename {coding-standards => docs/coding-standards}/inline-documentation-standards/README.md (99%) rename {coding-standards => docs/coding-standards}/inline-documentation-standards/javascript.md (87%) rename {coding-standards => docs/coding-standards}/inline-documentation-standards/php.md (93%) rename {coding-standards => docs/coding-standards}/styleguide.md (98%) rename {coding-standards => docs/coding-standards}/wordpress-coding-standards.md (88%) rename {coding-standards => docs/coding-standards}/wordpress-coding-standards/README.md (96%) rename {coding-standards => docs/coding-standards}/wordpress-coding-standards/accessibility.md (99%) rename {coding-standards => docs/coding-standards}/wordpress-coding-standards/css.md (84%) rename {coding-standards => docs/coding-standards}/wordpress-coding-standards/html.md (92%) create mode 100644 docs/coding-standards/wordpress-coding-standards/inline-documentation-standards/README.md rename {coding-standards => docs/coding-standards}/wordpress-coding-standards/javascript.md (86%) rename {coding-standards => docs/coding-standards}/wordpress-coding-standards/php.md (98%) rename {frontmatter => docs/frontmatter}/README.md (99%) create mode 100644 docs/frontmatter/YAML Frontmatter Cheat Sheet.md create mode 100644 docs/frontmatter/YAML-Frontmatter Schema-Guidelines.md rename {frontmatter => docs/frontmatter}/YAML-Frontmatter-Copilot-Space-Instructions.md (58%) rename {gutenberg => docs/gutenberg}/getting-started/README.md (85%) rename {gutenberg => docs/gutenberg}/getting-started/devenv/README.md (86%) rename {gutenberg => docs/gutenberg}/getting-started/devenv/get-started-with-create-block.md (89%) rename {gutenberg => docs/gutenberg}/getting-started/devenv/get-started-with-wp-env.md (88%) rename {gutenberg => docs/gutenberg}/getting-started/devenv/get-started-with-wp-scripts.md (93%) rename {gutenberg => docs/gutenberg}/getting-started/devenv/nodejs-development-environment.md (91%) rename {gutenberg => docs/gutenberg}/getting-started/faq.md (91%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/README.md (100%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/block-in-the-editor.md (75%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/block-json.md (89%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/block-wrapper.md (91%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/file-structure-of-a-block.md (98%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/javascript-in-the-block-editor.md (93%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/markup-representation-block.md (98%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/registration-of-a-block.md (89%) rename {gutenberg => docs/gutenberg}/getting-started/fundamentals/static-dynamic-rendering.md (88%) rename {gutenberg => docs/gutenberg}/getting-started/glossary.md (100%) rename {gutenberg => docs/gutenberg}/getting-started/quick-start-guide.md (96%) rename {gutenberg => docs/gutenberg}/getting-started/tutorial.md (79%) rename {gutenberg => docs/gutenberg}/how-to-guides/README.md (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/accessibility.md (66%) rename {gutenberg => docs/gutenberg}/how-to-guides/block-tutorial/README.md (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md (75%) rename {gutenberg => docs/gutenberg}/how-to-guides/block-tutorial/creating-dynamic-blocks.md (66%) rename {gutenberg => docs/gutenberg}/how-to-guides/block-tutorial/extending-the-query-loop-block.md (79%) rename {gutenberg => docs/gutenberg}/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md (74%) rename {gutenberg => docs/gutenberg}/how-to-guides/curating-the-editor-experience/README.md (97%) rename {gutenberg => docs/gutenberg}/how-to-guides/curating-the-editor-experience/block-locking.md (89%) rename {gutenberg => docs/gutenberg}/how-to-guides/curating-the-editor-experience/disable-editor-functionality.md (86%) rename {gutenberg => docs/gutenberg}/how-to-guides/curating-the-editor-experience/filters-and-hooks.md (84%) rename {gutenberg => docs/gutenberg}/how-to-guides/curating-the-editor-experience/patterns.md (93%) create mode 100644 docs/gutenberg/how-to-guides/curating-the-editor-experience/theme-json.md rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/1-data-basics-setup.md (59%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/2-building-a-list-of-pages.md (66%) create mode 100644 docs/gutenberg/how-to-guides/data-basics/3-building-an-edit-form.md create mode 100644 docs/gutenberg/how-to-guides/data-basics/4-building-a-create-page-form.md create mode 100644 docs/gutenberg/how-to-guides/data-basics/5-adding-a-delete-button.md rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/README.md (95%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/create-form/basic-create-form.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/create-form/create-button.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/create-form/create-form-with-text.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/create-form/create-saving.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/create-form/created-item.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/create-form/edit-page-form.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/delete-button/delete-button.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/delete-button/deleting-in-progress.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/delete-button/snackbar-error.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/delete-button/snackbar-example.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/delete-button/snackbar-success.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/delete-button/snackbar.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/edit-button.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/form-editable.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/form-error.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/form-finished.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/form-inactive.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/form-populated.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/form-scaffold.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/form-spinner.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/edit-form/modal-initial.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/finished-app.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/fetch-the-data.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/filter-field.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/filter.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/indicator.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/make-a-table.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/no-results.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/pages-list.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/part1-finished.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/simple-list.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/list-of-pages/unclear-status.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/data-basics/media/setup/hello-from-js.jpg (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/enqueueing-assets-in-the-editor.md (99%) rename {gutenberg => docs/gutenberg}/how-to-guides/feature-flags.md (81%) rename {gutenberg => docs/gutenberg}/how-to-guides/format-api.md (63%) rename {gutenberg => docs/gutenberg}/how-to-guides/internationalization.md (84%) rename {gutenberg => docs/gutenberg}/how-to-guides/metabox.md (85%) rename {gutenberg => docs/gutenberg}/how-to-guides/notices/README.md (66%) rename {gutenberg => docs/gutenberg}/how-to-guides/notices/block-editor-notice.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/notices/classic-editor-notice.png (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/platform/README.md (92%) rename {gutenberg => docs/gutenberg}/how-to-guides/platform/custom-block-editor.md (81%) rename {gutenberg => docs/gutenberg}/how-to-guides/plugin-sidebar-0.md (63%) rename {gutenberg => docs/gutenberg}/how-to-guides/propagating-updates.md (81%) rename {gutenberg => docs/gutenberg}/how-to-guides/themes/README.md (79%) rename {gutenberg => docs/gutenberg}/how-to-guides/themes/global-settings-and-styles.md (60%) rename {gutenberg => docs/gutenberg}/how-to-guides/themes/theme-support.md (79%) rename {gutenberg => docs/gutenberg}/how-to-guides/thunks.md (56%) rename {gutenberg => docs/gutenberg}/how-to-guides/widgets/README.md (100%) rename {gutenberg => docs/gutenberg}/how-to-guides/widgets/legacy-widget-block.md (68%) rename {gutenberg => docs/gutenberg}/how-to-guides/widgets/opting-out.md (90%) rename {gutenberg => docs/gutenberg}/how-to-guides/widgets/overview.md (100%) create mode 100644 docs/gutenberg/reference-guides/README.md create mode 100644 docs/gutenberg/reference-guides/block-api/README.md rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-annotations.md (85%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-api-versions.md (63%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-attributes.md (78%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-bindings.md (67%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-context.md (73%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-deprecation.md (56%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-edit-save.md (73%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-metadata.md (69%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-patterns.md (61%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-registration.md (76%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-selectors.md (79%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-styles.md (86%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-supports.md (59%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-templates.md (57%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-transforms.md (56%) rename {gutenberg => docs/gutenberg}/reference-guides/block-api/block-variations.md (64%) rename {gutenberg => docs/gutenberg}/reference-guides/core-blocks.md (60%) create mode 100644 docs/gutenberg/reference-guides/data/README.md rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-annotations.md (100%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-block-directory.md (57%) create mode 100644 docs/gutenberg/reference-guides/data/data-core-block-editor.md create mode 100644 docs/gutenberg/reference-guides/data/data-core-blocks.md rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-commands.md (59%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-customize-widgets.md (58%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-edit-post.md (63%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-edit-site.md (62%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-edit-widgets.md (54%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-editor.md (54%) create mode 100644 docs/gutenberg/reference-guides/data/data-core-keyboard-shortcuts.md create mode 100644 docs/gutenberg/reference-guides/data/data-core-notices.md rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-nux.md (70%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-preferences.md (58%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-reusable-blocks.md (99%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-rich-text.md (64%) rename {gutenberg => docs/gutenberg}/reference-guides/data/data-core-viewport.md (67%) create mode 100644 docs/gutenberg/reference-guides/data/data-core.md rename {gutenberg => docs/gutenberg}/reference-guides/filters/README.md (100%) rename {gutenberg => docs/gutenberg}/reference-guides/filters/autocomplete-filters.md (54%) rename {gutenberg => docs/gutenberg}/reference-guides/filters/block-filters.md (68%) rename {gutenberg => docs/gutenberg}/reference-guides/filters/editor-filters.md (81%) rename {gutenberg => docs/gutenberg}/reference-guides/filters/global-styles-filters.md (70%) rename {gutenberg => docs/gutenberg}/reference-guides/filters/i18n-filters.md (51%) rename {gutenberg => docs/gutenberg}/reference-guides/filters/parser-filters.md (100%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/README.md (61%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/api-reference.md (63%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/core-concepts/README.md (100%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/core-concepts/server-side-rendering.md (73%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md (55%) create mode 100644 docs/gutenberg/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/core-concepts/using-typescript.md (68%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/iapi-about.md (95%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/iapi-faq.md (99%) rename {gutenberg => docs/gutenberg}/reference-guides/interactivity-api/iapi-quick-start-guide.md (99%) rename {gutenberg => docs/gutenberg}/reference-guides/packages.md (93%) rename {gutenberg => docs/gutenberg}/reference-guides/richtext.md (62%) create mode 100644 docs/gutenberg/reference-guides/slotfills/README.md rename {gutenberg => docs/gutenberg}/reference-guides/slotfills/main-dashboard-button.md (70%) rename {gutenberg => docs/gutenberg}/reference-guides/slotfills/plugin-block-settings-menu-item.md (68%) create mode 100644 docs/gutenberg/reference-guides/slotfills/plugin-document-setting-panel.md rename {gutenberg => docs/gutenberg}/reference-guides/slotfills/plugin-more-menu-item.md (66%) rename {gutenberg => docs/gutenberg}/reference-guides/slotfills/plugin-post-publish-panel.md (73%) rename {gutenberg => docs/gutenberg}/reference-guides/slotfills/plugin-post-status-info.md (73%) rename {gutenberg => docs/gutenberg}/reference-guides/slotfills/plugin-pre-publish-panel.md (74%) create mode 100644 docs/gutenberg/reference-guides/slotfills/plugin-sidebar-more-menu-item.md create mode 100644 docs/gutenberg/reference-guides/slotfills/plugin-sidebar.md create mode 100644 docs/gutenberg/reference-guides/theme-json-reference/README.md create mode 100644 docs/gutenberg/reference-guides/theme-json-reference/styles-versions.md create mode 100644 docs/gutenberg/reference-guides/theme-json-reference/theme-json-living.md rename {gutenberg => docs/gutenberg}/schemas/README.md (73%) create mode 100644 docs/gutenberg/schemas/json/block.json create mode 100644 docs/gutenberg/schemas/json/font-collection.json create mode 100644 docs/gutenberg/schemas/json/theme.json create mode 100644 docs/gutenberg/schemas/json/wp-env.json rename {block-themes => docs/wordpress/block-themes}/README.md (98%) rename block-themes/templates.md => docs/wordpress/block-themes/docs.template.md (97%) rename {block-themes => docs/wordpress/block-themes/patterns}/patterns.md (93%) rename {block-themes => docs/wordpress/block-themes/theme.json}/block-styles.md (69%) rename {block-themes => docs/wordpress/block-themes/theme.json}/colour-palettes.md (95%) create mode 100644 docs/wordpress/block-themes/theme.json/fluid-best-practices.md rename block-themes/FluidTypography-Fluid-Spacing-Guidelines.md => docs/wordpress/block-themes/theme.json/fluid-guidelines.md (87%) rename {block-themes => docs/wordpress/block-themes/theme.json}/fluid-spacing.md (66%) rename {block-themes => docs/wordpress/block-themes/theme.json}/fluid-typography.md (95%) rename {block-themes => docs/wordpress/block-themes/theme.json}/global-styles.md (97%) rename {block-themes => docs/wordpress/block-themes/theme.json}/naming-conventions.md (91%) rename block-themes/best-practices-best-practices-.md => docs/wordpress/block-themes/theme.json/section-styles-best-practices.md (72%) rename {block-themes => docs/wordpress/block-themes/theme.json}/section-styles.md (79%) rename {block-themes => docs/wordpress/block-themes/theme.json}/spacing-presets.md (72%) rename {block-themes => docs/wordpress/block-themes/theme.json}/standardising-colours-fonts-spacing.md (66%) rename {block-themes => docs/wordpress/block-themes/theme.json}/style-variations.md (99%) create mode 100644 docs/wordpress/block-themes/theme.json/theme-68.json create mode 100644 docs/wordpress/block-themes/theme.json/typesets.md create mode 100644 eslint.config.js create mode 100644 eslint.config.mjs create mode 100644 extensions.json delete mode 100644 frontmatter/YAML Frontmatter Cheat Sheet.md delete mode 100644 frontmatter/YAML Frontmatter Schemas for GitHub, Copilot, Claude, and Gemini Files1.md delete mode 100644 frontmatter/YAML-Frontmatter Schema-Guidelines.md delete mode 100644 gutenberg/how-to-guides/curating-the-editor-experience/theme-json.md delete mode 100644 gutenberg/how-to-guides/data-basics/3-building-an-edit-form.md delete mode 100644 gutenberg/how-to-guides/data-basics/4-building-a-create-page-form.md delete mode 100644 gutenberg/how-to-guides/data-basics/5-adding-a-delete-button.md delete mode 100644 gutenberg/reference-guides/README.md delete mode 100644 gutenberg/reference-guides/block-api/README.md delete mode 100644 gutenberg/reference-guides/data/README.md delete mode 100644 gutenberg/reference-guides/data/data-core-block-editor.md delete mode 100644 gutenberg/reference-guides/data/data-core-blocks.md delete mode 100644 gutenberg/reference-guides/data/data-core-keyboard-shortcuts.md delete mode 100644 gutenberg/reference-guides/data/data-core-notices.md delete mode 100644 gutenberg/reference-guides/data/data-core.md delete mode 100644 gutenberg/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md delete mode 100644 gutenberg/reference-guides/slotfills/README.md delete mode 100644 gutenberg/reference-guides/slotfills/plugin-document-setting-panel.md delete mode 100644 gutenberg/reference-guides/slotfills/plugin-sidebar-more-menu-item.md delete mode 100644 gutenberg/reference-guides/slotfills/plugin-sidebar.md delete mode 100644 gutenberg/reference-guides/theme-json-reference/README.md delete mode 100644 gutenberg/reference-guides/theme-json-reference/styles-versions.md delete mode 100644 gutenberg/reference-guides/theme-json-reference/theme-json-living.md delete mode 100644 gutenberg/schemas/json/block.json delete mode 100644 gutenberg/schemas/json/font-collection.json delete mode 100644 gutenberg/schemas/json/theme.json delete mode 100644 gutenberg/schemas/json/wp-env.json create mode 100644 jest.config.js create mode 100644 jest.config.json.bak create mode 100644 launch.json create mode 100644 mcp.json diff --git a/.all-contributorsrc b/.all-contributorsrc new file mode 100644 index 0000000..75cd396 --- /dev/null +++ b/.all-contributorsrc @@ -0,0 +1,37 @@ +{ + "projectName": ".github", + "projectOwner": "lightspeedwp", + "repoType": "github", + "repoHost": "https://github.com", + "projectDescription": "GitHub Community Health files for LightSpeedWP organization", + "projectWebsite": "https://lightspeedwp.agency", + "license": "GPL-3.0-or-later", + "files": [ + "README.md" + ], + "imageSize": 100, + "commit": false, + "commitConvention": "conventional", + "contributors": [ + { + "login": "lightspeedwp", + "name": "LightSpeedWP", + "avatar_url": "https://avatars.githubusercontent.com/u/13472139?v=4", + "profile": "https://github.com/lightspeedwp", + "contributions": [ + "ideas", + "fundingFinding", + "projectManagement", + "business", + "code", + "design", + "doc", + "infra", + "maintenance", + "test" + ] + } + ], + "contributorsPerLine": 7, + "linkToUsage": true +} diff --git a/.babelrc b/.babelrc new file mode 100644 index 0000000..469d3d5 --- /dev/null +++ b/.babelrc @@ -0,0 +1,7 @@ +{ + "presets": [ + "@babel/preset-env", + "@babel/preset-typescript", + "@babel/preset-react" + ] +} diff --git a/.coderabbit.yml b/.coderabbit.yml index c47ca9f..254717f 100644 --- a/.coderabbit.yml +++ b/.coderabbit.yml @@ -1,16 +1,186 @@ +# yaml-language-server: $schema=[https://coderabbit.ai/integrations/coderabbit-overrides.v2.json](https://coderabbit.ai/integrations/coderabbit-overrides.v2.json) + +# yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.v2.json +language: 'en-uk' +chat: + auto_reply: true reviews: + # === Review Workflow Settings === + status_checks: + required: + - markdownlint + - Run Tests + - ShellCheck + - Changelog + - Release + required_approvals: 2 + auto_labels: + enabled: true + rules: + - path: 'scripts/**/*.sh' + label: 'shell' + - path: '**/*.md' + label: 'docs' + - path: 'workflows/**/*.yml' + label: 'ci' + - path: 'tests/**/*.bats' + label: 'test' + - path: 'scripts/**/*.js' + label: 'js' + - path: 'scripts/**/*.py' + label: 'python' + auto_assign: + enabled: true + reviewers: + - 'ashleyshaw' + path_filters: + # === Path Filters (Exclude from Review) === + - '!build/**' + - '!dist/**' + - '!node_modules/**' + - '!.cache/**' + - '!.DS_Store' + - '!vendor/**' + - '!composer.lock' + - '!package-lock.json' + - '!yarn.lock' + - '!.phpunit.result.cache' + - '!.idea/**' + - '!*.zip' + - '!bin/**' + - '!test-results/**' + - '!playwright-report/**' + - '!blob-report/**' + - '!*.map' + # Allow markdown, config, workflows, and docs to be reviewed + request_changes_workflow: true # Require workflow for requesting changes + high_level_summary: true # Provide high-level summary in reviews + poem: false # Disable poem output in reviews + review_status: true # Show review status in output + collapse_walkthrough: true # Collapse walkthroughs by default + # === Auto Review Settings === + auto_review: + enabled: true + drafts: false + base_branches: + - 'main' + - 'develop' + - 'feature/*' + - 'fix/*' + - 'update/*' + # === Path-Specific Review Instructions === path_instructions: - - path: "**/*.md" - instructions: | - Review the Markdown documentation for: - - Clarity and conciseness of explanations - - Consistent formatting and heading structure - - Proper use of code blocks and inline code - - Correct spelling, grammar, and punctuation - - Accurate and up-to-date technical information - - Useful internal and external links - - Well-organized sections and logical flow - - Additional context: - - The repository contains documentation focused on block theme and block plug-in development topics for WordPress and related technologies. - - Please ensure that technical docs are developer-friendly, accurate, and up-to-date. + # 1. Copilot & AI Files + - path: '.github/custom-instructions.md' + instructions: | + Review custom-instructions.md: + - Ensure the file is easy to navigate and up to date with org standards. + - Ensure the file is a dynamic index of all major Copilot files and instructions. + - Validate YAML frontmatter for completeness and accuracy. + - Confirm references to chatmodes.md, prompts.md, agent.md, AGENTS.md, and all **/.github/instructions/*.instructions.md files. + - Check for up-to-date cross-references and clear documentation of Copilot usage. + +early_access: true +auto_labels: + enabled: true + - A canonical list of org wide default labels exists in this file "https://github.com/lightspeedwp/.github/blob/develop/.github/labels.yml" https://github.com/lightspeedwp/.github/blob/develop/.github/labeler.yml + - A set of labeler rules exist in this file "https://github.com/lightspeedwp/.github/blob/develop/.github/labeler.yml" +auto_assign: + enabled: true + reviewers: + - 'ashleyshaw' +auto_review: + enabled: true + ignore_title_keywords: + - 'WIP' + - 'DO NOT MERGE' + - 'DRAFT' + drafts: false + base_branches: + - 'main' + - 'develop' + - 'feature/*' + + path_instructions: + - path: 'scripts/**/*.sh' + instructions: | + "Review shell scripts for: + - Header comments and metadata + - Error handling (set -euo pipefail) + - ShellCheck compliance + - Test coverage with Bats + - Security best practices + - Documentation in README" + - path: 'scripts/**/*.js' + instructions: | + "Review JS scripts for: + - ESLint compliance + - Modular structure + - Test coverage + - Documentation and usage examples" + - path: 'scripts/**/*.py' + instructions: | + "Review Python scripts for: + - PEP8 compliance + - Test coverage + - Inline documentation and docstrings" + - path: 'workflows/**/*.yml' + instructions: | + "Review workflows for: + - Linting and test enforcement + - Required status checks + - Use of verified Marketplace actions + - Documentation and maintainability" + - path: 'CHANGELOG.md' + instructions: | + "Review changelog for: + - Accurate entries for all changes + - Customer-facing release notes + - Compliance with Keep a Changelog format" + - path: 'README.md' + instructions: | + "Review README for: + - Usage instructions + - Automation feature documentation + - Test coverage and status badges + - Compliance with documentation standards" + - path: 'scripts/product_dev_project.sh' + instructions: | + "Review project automation script for GitHub ProjectV2: + - Ensure script supports all automatable ProjectV2 actions (create project, add fields, add items/issues, link repositories/teams, update project/fields/items/status) + - Validate use of helper functions for each mutation and CLI/GraphQL integration + - Check for modular, maintainable, and well-documented code + - Confirm error handling and logging for automation steps + - Ensure script is tested with Bats and covers edge cases + - Verify script updates and syncs project meta/template files as required + - Confirm alignment with repo governance and automation standards" + - path: 'scripts/**/*.sh' + instructions: | + "Review shell scripts for automation and governance: + - Ensure script header includes metadata (name, description, usage, author, date) + - Validate error handling with set -euo pipefail + - Check for ShellCheck compliance + - Confirm test coverage with Bats + - Review for security best practices (input validation, least privilege) + - Ensure documentation is provided in README or inline comments" + - path: '**/*.md' + instructions: | + "Review markdown files for: + - Clarity and conciseness + - Proper formatting and structure + - Spelling and grammar + - Relevant links and references" + - path: 'workflows/**/*.yml' + instructions: | + "Review CI/CD workflows for: + - Correct triggers and conditions + - Proper job definitions and steps + - Use of secrets and environment variables + - Compliance with best practices and security guidelines" + - path: 'tests/**/*.bats' + instructions: | + "Reviewbats tests for: + - Comprehensive test coverage + - Clear and descriptive test names + - Proper setup and teardown procedures + - Use of assertions and validations" diff --git a/.distignore b/.distignore new file mode 100644 index 0000000..79ea2f9 --- /dev/null +++ b/.distignore @@ -0,0 +1,18 @@ +# Exclude from plugin/theme distribution packages +/.git +/.github +/node_modules +/vendor +/tests +/bin +/.vscode +/.DS_Store +/*.zip +/*.tar.gz +/*.log +composer.json +composer.lock +package.json +package-lock.json +pnpm-lock.yaml +*.map diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9a95228 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,38 @@ +# YAML files +[*.yml] +indent_style = space +indent_size = 2 + +[*.yaml] +indent_style = space +indent_size = 2 +# EditorConfig is awesome: https://EditorConfig.org + +# top-most EditorConfig file +root = true + +# Unix-style newlines with a newline ending every file +[*] +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 + +# PHP files - WordPress coding standards use tabs +[*.php] +indent_style = tab +indent_size = 4 + +# HTML files +[*.html] +indent_style = space +indent_size = 4 + +# CSS, SCSS, JavaScript, and JSON files +[*.{css,scss,js,json}] +indent_style = space +indent_size = 2 + +# Markdown files +[*.md] +trim_trailing_whitespace = false diff --git a/.env b/.env new file mode 100644 index 0000000..d81bdad --- /dev/null +++ b/.env @@ -0,0 +1,19 @@ +# Example .env file for local development and CI +# Do NOT commit secrets to public repositories + +# Node.js/CI/CD +NODE_ENV=development +PORT=3000 + +# WordPress/Database (if relevant) +# DB_HOST=localhost +# DB_USER=your_db_user +# DB_PASSWORD=your_db_password +# DB_NAME=your_db_name + +# API Keys (replace with your actual keys, do not commit real secrets) +# API_KEY=your_api_key_here +# GITHUB_TOKEN=your_github_token_here + +# Feature flags or custom config +# FEATURE_X_ENABLED=true diff --git a/.eslintignore b/.eslintignore new file mode 100644 index 0000000..c19184f --- /dev/null +++ b/.eslintignore @@ -0,0 +1,18 @@ +# Ignore files and directories that should not be formatted by Eslint + +# Node modules +node_modules + +# Build directories +build +dist + +# Log files + +# Vendor directories +vendor + +# Test directories +coverage +playwright-report +test-results diff --git a/.eslintrc.cjs b/.eslintrc.cjs new file mode 100644 index 0000000..18df04f --- /dev/null +++ b/.eslintrc.cjs @@ -0,0 +1,16 @@ +module.exports = { + root: true, + env: { es2022: true, browser: true, node: true }, + parser: '@typescript-eslint/parser', + parserOptions: { sourceType: 'module', ecmaVersion: 'latest' }, + plugins: ['@typescript-eslint', 'prettier'], + extends: [ + 'eslint:recommended', + 'plugin:@typescript-eslint/recommended', + 'plugin:prettier/recommended', + ], + ignorePatterns: ['node_modules/', 'build/', 'dist/'], + rules: { + 'prettier/prettier': 'warn' + } +}; diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 0000000..adec0c8 --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,22 @@ +{ + "env": { + "node": true, + "es2022": true, + "jest": true + }, + "extends": ["eslint:recommended", "plugin:jest/recommended", "plugin:prettier/recommended"], + "plugins": ["jest", "prettier"], + "parserOptions": { + "ecmaVersion": "latest", + "sourceType": "module" + }, + "rules": { + "prettier/prettier": "error", + "no-console": "warn", + "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }], + "jest/expect-expect": "error", + "jest/no-disabled-tests": "warn", + "jest/no-focused-tests": "error", + "jest/prefer-to-have-length": "warn" + } +} diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..2a8e447 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,13 @@ +# Normalize line endings +* text=auto eol=lf + +# Treat lock files as text +*.lock text +*.bat text eol=crlf + +# Linguist: docs and examples +docs/** linguist-documentation +*.md linguist-documentation + +# Zip-friendly export ignore +*.zip export-ignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..07d93e6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,32 @@ +# Node.js +node_modules/ # Node dependencies +npm-debug.log* # npm debug logs +.DS_Store # macOS system file + +# PHP / Composer +vendor/ # Composer dependencies +.phpunit.result.cache # PHPUnit cache +.idea/ # JetBrains IDE config + +# Lock Files +pnpm-lock.yaml # pnpm lock file +composer.lock # Composer lock file +package-lock.json # npm lock file +yarn.lock # Yarn lock file + +# Build related files & folders +dist/ # Build output +build/ # Build output +.cache/ # Build/cache +coverage/ # Test coverage output +.sass-cache/ # Sass cache +.git/ # Git directory (should not be in dist) +.gitattributes # Git attributes (should not be in dist) +bin/ # Binary scripts/tools +*.zip # Zipped packages +*.map # Source maps + +# Tests +test-results/ # Playwright test results +playwright-report/ # Playwright HTML reports +blob-report/ # Playwright blob reports diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 0000000..c9f5ca9 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,6 @@ +#!/usr/bin/env sh +. "$(dirname -- "$0")/_/husky.sh" + +npm run lint:fix +npm run format +npm test diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..11714dc --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,19 @@ +{ + "default": true, + "MD013": false, + "MD003": false, + "MD024": false, + "MD033": false, + "MD041": false, + "MD046": { + "style": "fenced" + }, + "MD040": false, + "MD036": false, + "MD001": false, + "MD022": false, + "MD025": false, + "MD051": false, + "MD052": false, + "MD012": false +} diff --git a/.npmpackagejsonlintrc.json b/.npmpackagejsonlintrc.json new file mode 100644 index 0000000..babe5fd --- /dev/null +++ b/.npmpackagejsonlintrc.json @@ -0,0 +1,10 @@ +{ + "rules": { + "name-format": "error", + "valid-values-name-scope": ["error", ["@lightspeedwp"]], + "version-format": "error", + "require-author": "warning", + "prefer-repository": "error", + "require-license": "error" + } +} diff --git a/.npmrc b/.npmrc new file mode 100644 index 0000000..34a408f --- /dev/null +++ b/.npmrc @@ -0,0 +1,5 @@ +save-exact=true +package-lock=true +fund=false +engine-strict=true +# resolution-mode=highest # Remove or comment out for deterministic installs \ No newline at end of file diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..209e3ef --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +20 diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..df29803 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,18 @@ +# Ignore files and directories that should not be formatted by Prettier + +# Node modules +node_modules + +# Build directories +build +dist + +# Log files + +# Vendor directories +vendor + +# Test directories +coverage +playwright-report +test-results diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..a2d42ed --- /dev/null +++ b/.prettierrc @@ -0,0 +1,9 @@ +{ + "semi": true, + "trailingComma": "es5", + "singleQuote": true, + "printWidth": 100, + "tabWidth": 2, + "useTabs": false, + "endOfLine": "lf" +} diff --git a/.prettierrc.js b/.prettierrc.js new file mode 100644 index 0000000..c29ff29 --- /dev/null +++ b/.prettierrc.js @@ -0,0 +1,29 @@ +/** + * Prettier Configuration + * + * Copyright (C) 2024 LightSpeed WP + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +module.exports = { + tabWidth: 4, + useTabs: false, + endOfLine: 'lf', + printWidth: 80, + singleQuote: true, + trailingComma: 'es5', + bracketSpacing: true, + arrowParens: 'always', +}; diff --git a/.shellcheckrc b/.shellcheckrc new file mode 100644 index 0000000..7eb0911 --- /dev/null +++ b/.shellcheckrc @@ -0,0 +1,12 @@ +# .shellcheckrc - ShellCheck configuration for LightSpeedWP +# See: https://github.com/koalaman/shellcheck/blob/master/shellcheckrc.example + +# Enable all recommended warnings +severity=style +shell=bash +external-sources=true +exclude=SC1091,SC2154 # Example: exclude sourcing and undefined var warnings + +# Custom project rules (uncomment as needed) +# source-path=./scripts +# enable=all diff --git a/.spectral-workflows.yaml b/.spectral-workflows.yaml new file mode 100644 index 0000000..1acf91b --- /dev/null +++ b/.spectral-workflows.yaml @@ -0,0 +1,8 @@ +extends: "./.spectral.yaml" +rules: + github-action-mandatory-name: + description: GitHub Action must have a name + given: "$" + then: + field: "name" + function: truthy diff --git a/.spectral.yaml b/.spectral.yaml new file mode 100644 index 0000000..6dd8fca --- /dev/null +++ b/.spectral.yaml @@ -0,0 +1,6 @@ +extends: "spectral:recommended" +rules: + document-defined: true + no-empty-keys: true + # Allow GitHub Actions style matrix expressions + no-unused-variables: false diff --git a/.yamllint b/.yamllint new file mode 100644 index 0000000..9643f27 --- /dev/null +++ b/.yamllint @@ -0,0 +1,12 @@ +--- +extends: default + +rules: + line-length: + max: 120 + allow-non-breakable-words: true + indentation: + spaces: 2 + indent-sequences: consistent + trailing-spaces: disable + document-start: disable \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..17c8484 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,106 @@ +# LightSpeed – Global AI Rules (AGENTS.md) + +- Use UK English; optimise for clarity, scalability, maintainability and profitable outcomes. +- Prefer minimal, modular solutions; justify heavier tools with return on investment and maintenance cost. +- Follow WordPress Coding Standards (CSS, HTML, JavaScript, PHP) and inline‑documentation standards at all times. +- All code changes must include lint fixes, relevant tests and a short rationale summarising the change. +- Never output secrets. Treat production and customer data as sensitive. Follow the OWASP top 10 for web security. +- Accessibility and performance are non‑negotiable; highlight potential issues during reviews. +- Prefer `theme.json` and block components over bespoke code when feasible to avoid vendor lock‑in. +- When unsure, propose safe defaults and ask **one** focused question to clarify requirements. + +## Global Principles & Agent Rules + +| Principle / Rule | Guidance / Details | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Language** | Use UK English; optimise for clarity, scalability, maintainability, and profitable outcomes. | +| **Modularity** | Prefer minimal, modular solutions; justify heavier tools with ROI and maintenance cost. | +| **Coding Standards** | Follow [Coding Standards Instructions](.github/instructions/coding-standards.instructions.md) and [Linting Instructions](.github/instructions/linting.instructions.md) for all code (CSS, HTML, JS, PHP, etc.). | +| **Code Changes** | All code changes must include lint fixes, relevant tests, and a short rationale summarising the change. | +| **Security** | Never output secrets. Treat production and customer data as sensitive. Follow OWASP top 10. | +| **Accessibility & Performance** | Non-negotiable; highlight potential issues during reviews. | +| **WordPress Block Usage** | Prefer `theme.json` and block components over bespoke code to avoid vendor lock-in. | +| **Safe Defaults & Questions** | When unsure, propose safe defaults and ask one focused question to clarify requirements. | + +--- + +## Contribution Guidelines & Indexes + +| Area | File Reference | Notes / Usage | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------- | +| **Coding Standards** | [.github/instructions/coding-standards.instructions.md](.github/instructions/coding-standards.instructions.md) | Unified standards for all code | +| **Linting Standards** | [.github/instructions/linting.instructions.md](.github/instructions/linting.instructions.md) | Main index for all linting rules | +| **HTML Templates** | [.github/instructions/html-template.instructions.md](.github/instructions/html-template.instructions.md) | Markup standards | +| **Pattern Development** | [.github/instructions/pattern-development.instructions.md](.github/instructions/pattern-development.instructions.md) | Block patterns for WordPress | +| **PHP Block Instructions** | [.github/instructions/php-block.instructions.md](.github/instructions/php-block.instructions.md) | PHP block usage | +| **Theme JSON** | [.github/instructions/theme-json.instructions.md](.github/instructions/theme-json.instructions.md) | Theme configuration standards | + +**Other Key Indexes:** + +- **Linting Index:** [.github/instructions/linting.instructions.md](.github/instructions/linting.instructions.md) +- **Coding Standards Index:** [.github/instructions/coding-standards.instructions.md](.github/instructions/coding-standards.instructions.md) + +--- + +## PR Templates + +- Use the default PR template: [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) +- Additional PR templates are available in: [.github/PULL_REQUEST_TEMPLATES/](.github/PULL_REQUEST_TEMPLATES/) + - Use the template most relevant to your change (e.g. feature, fix, documentation, etc.) + +--- + +## Core Index Instructions + +Start here for all key standards: + +- [Coding Standards Index](.github/instructions/coding-standards.instructions.md): Unified standards, best practices, and documentation for all LightSpeed projects. +- [Linting Instructions Index](.github/instructions/linting.instructions.md): Primary index and guidance for all linting rules, tools, and file-type-specific standards. + +--- + +## Cross-References & Discoverability + +| Resource Name | Reference | Purpose / Notes | +| ----------------------- | ---------------------------------------------------------------- | -------------------------------------------------------- | +| **Custom Instructions** | [.github/custom-instructions.md](.github/custom-instructions.md) | Central Copilot/org instructions, prompts, and standards | +| **Main Agent Index** | [.github/agents/agent.md](.github/agents/agent.md) | Directory of agent specs, stubs, usage, implementation | +| **Chat Modes Index** | [.github/chatmodes/chatmodes.md](.github/chatmodes/chatmodes.md) | List and guidance for all chat modes | +| **Prompts Index** | [.github/prompts/prompts.md](.github/prompts/prompts.md) | Master prompt index and authoring conventions | + +--- + +## Instruction Indexes (Recommended Reference Pattern) + +Reference main index files directly in your workflow or documentation: + +- `@lightspeedwp/.github/files/.github/instructions/coding-standards.instructions.md` +- `@lightspeedwp/.github/files/.github/instructions/linting.instructions.md` +- For file-type or topic-specific instructions, see all files in `.github/instructions/`. + +--- + +> For up-to-date standards, always reference the index instruction files above. +> See also: [.github/custom-instructions.md](.github/custom-instructions.md) for central org-wide Copilot and agent guidance. + +## Language Usage: UK English vs. Code Standards + +- **Documentation & Comments:** Use UK English spelling (e.g., "colour", "optimise", "organisation") in all documentation, inline comments, and prose. +- **Code, APIs & Identifiers:** Always use the spelling and conventions required by the underlying technology or WordPress Coding Standards. For example: + - Use `color` (not `colour`) in CSS, JavaScript, PHP, and JSON keys. + - Use WordPress function names, hooks, and filters as published, even if they use US spelling. +- **Automation:** If using language normalisation scripts (e.g., `npm run lang:en-gb`), ensure they exclude: + - Code blocks in Markdown + - CSS/JS/PHP identifiers + - Theme and block JSON keys + +> **Example:** +> +> - Documentation: "The primary colour palette is defined in `theme.json`." +> - CSS: `color: #fff;` (not `colour`) +> - JavaScript: `const backgroundColor = '#fff';` +> - PHP: `$text_color = '#fff';` + +**Rationale:** + +- This approach ensures clarity for contributors, avoids breaking code, and aligns with both LightSpeed and WordPress standards. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..31e221d --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,123 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] - DD-MM-YYYY + + + +### Added + +### Changed + +- Removed build step from required scripts and pre-commit checklist (no build process required for this repo). +- Resolved Jest configuration conflict (removed duplicate config file). + +### Deprecated + +### Documentation + +- Fixed markdownlint errors and improved accessibility (image alt text, code block style, ordered list prefixes). +- Added and clarified language usage guidance (UK English vs. code standards) in `AGENTS.md`. +- Updated documentation for clarity, maintainability, and compliance with WordPress and LightSpeed standards. + +### Fixed + +### Performance + +### Removed + +### Security + +--> + +## [0.1.0] - 2025-09-25 + +### Added + +- Initial release of LightSpeed WordPress organization community health files +- GitHub Copilot custom instructions and organization-wide guidelines +- Comprehensive instruction files for WordPress development: + - `coding-standards.instructions.md` - WordPress coding standards for PHP, JS, CSS + - `html-template.instructions.md` - Block template and template part guidelines + - `pattern-development.instructions.md` - Block pattern creation and advanced usage + - `php-block.instructions.md` - PHP block development and theme setup + - `playwright-tests.instructions.md` - Browser automation and accessibility testing + - `theme-json.instructions.md` - Theme.json configuration and design tokens +- AI prompt templates for: + - `accessibility-review.prompt.md` - Accessibility compliance review + - `dev-code-review.prompt.md` - Code review and standards verification + - `pattern-generation.prompt.md` - Block pattern generation assistance + - `refactor-theme-types.prompt.md` - WordPress theme refactoring guidance +- Issue templates for comprehensive project management: + - Bug reports, feature requests, documentation requests + - Performance issues, UX feedback, integration issues + - Code refactoring, task management, custom instructions proposals +- Pull request templates with WordPress-specific checklists +- VS Code configuration optimized for WordPress development: + - MCP (Model Context Protocol) auto-start configuration + - WordPress-specific extensions and settings + - GitHub Copilot integration with custom instructions + - Proper file associations for instruction and prompt files +- Example WordPress block structure following best practices +- Comprehensive documentation and README files +- GitHub Actions workflows for issue metrics and labeling +- Saved replies for common support scenarios +- Organization profile README showcasing LightSpeed projects + +### Deprecated + +- [placeholder] + +### Fixed + +- Standardized YAML frontmatter across all instruction files +- Corrected indentation and formatting inconsistencies +- Aligned VS Code settings with repository structure +- Removed non-standard configuration keys for better compatibility + +### Changed + +- Updated author attribution to "LightSpeedWP Team" for consistency +- Standardized related_links format as simple URL lists +- Enhanced MCP configuration for WordPress development context +- Improved file associations and discovery paths for AI tools + +### Documentation + +- Added comprehensive README files for instructions and prompts +- Created implementation guide for WordPress block development +- Established clear contribution guidelines and coding standards +- Documented VS Code configuration and MCP setup procedures + +### Performance + +- [placeholder] + +### Removed + +- [placeholder] + +### Security + +- Implemented proper input sanitization and output escaping in examples +- Added security guidelines in coding standards +- Established secure development practices in instruction files + +## Reference + +- [Branching Strategy](.github/BRANCHING_STRATEGY.md): Org-wide branch naming, merge discipline, and automation mapping. +- [CHANGELOG.md](./CHANGELOG.md): Changelog format, release notes, and versioning. +- [CONTRIBUTING.md](./CONTRIBUTING.md): Contribution guidelines, templates, coding standards. +- [AUTOMATION_GOVERNANCE.md](.github/AUTOMATION_GOVERNANCE.md): Org-wide automation, branching, labeling, and release strategy. +- [Org-wide Issue Labels](.github/ISSUE_LABELS.md): Default labels and usage guidance. +- [Pull Request Labels](.github/PR_LABELS.md): PR classification and automation standards. +- [Issue Types Guide](.github/ISSUE_TYPES.md): Classification and usage of issue types. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9c11991 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,172 @@ +--- +title: 'CLAUDE.md Template' +version: 'v1.1' +last_updated: '2025-10-21' +author: 'LightSpeed' +maintainer: 'Ash Shaw' +description: 'Root-level guidance for Claude agents, aligned with LightSpeed organisational standards.' +tags: ['lightspeed', 'templates', 'copilot', 'agents', 'prompts', 'models'] +type: 'agent' +references: + - 'https://github.com/lightspeedwp/.github/blob/master/.github/custom-instructions.md' + - 'https://github.com/lightspeedwp/.github/blob/master/AGENTS.md' + - 'https://github.com/lightspeedwp/.github/blob/master/.github/instructions/coding-standards.instructions.md' +--- + +# Role (required) + +You are a Claude agent operating within LightSpeed. Follow LightSpeed's [AGENTS.md](https://github.com/lightspeedwp/.github/blob/master/AGENTS.md), [custom instructions](https://github.com/lightspeedwp/.github/blob/master/.github/custom-instructions.md), and project-specific frameworks to deliver modular, maintainable WordPress solutions. Use UK English. Avoid non-WordPress tools, custom code, or exposing secrets unless explicitly directed. + +# Style (required) + +- Write modular, maintainable, and testable code and documentation. +- Use semantic, accessible markup and descriptive comments per WordPress standards. +- Optimise for performance, accessibility, and scalability. +- Justify any tool or pattern outside LightSpeed defaults with clear rationale. + +# Purpose (required) + +- Deliver clear, secure, and scalable outcomes for LightSpeed WordPress projects. +- Ensure all outputs meet LightSpeed’s standards for clarity, maintainability, security, and accessibility. +- Support and automate workflows for efficient Figma → WordPress handoff. + +# Type of Task (required) + +- Coding, code review, documentation, prompt authoring, agentic workflow design, and process checklists for WordPress and web projects. +- Validate outputs against [LightSpeed coding standards](https://github.com/lightspeedwp/.github/blob/master/.github/instructions/coding-standards.instructions.md), linting, and accessibility requirements. + +# How to ask for help (required) + +- Reference this Space and LightSpeed documentation first. +- Ask a single, focused question if requirements or context are unclear. +- Escalate blockers by tagging the maintainer and referencing relevant documentation or index files. + +# Conventions (optional) + +- Use YAML frontmatter in documentation. +- Reference core index files for standards ([see AGENTS.md](https://github.com/lightspeedwp/.github/blob/master/AGENTS.md)). +- Track issues and PRs via GitHub; reference/close issues in commit messages. + +# Process (required) + +- Start by checking AGENTS.md and custom-instructions.md for current org rules. +- Confirm project scope and constraints before coding. +- Use GitHub Issues and PRs for all changes; follow the [pull request template](https://github.com/lightspeedwp/.github/blob/master/.github/PULL_REQUEST_TEMPLATE.md). +- Log rationale and testing coverage for every change. + +# Examples (optional) + +- See [prompts index](https://github.com/lightspeedwp/.github/blob/master/.github/prompts/prompts.md) for reusable prompt files. +- Example outputs: accessible markup, modular WordPress block patterns, documented workflow YAML. + +# Important notes (optional) + +- Never expose secrets or sensitive data. +- Accessibility and performance are non-negotiable. +- Update documentation and rationale with every material change. + +# Who is this for (optional) + +- Claude agents, contributors, and maintainers working on LightSpeed WordPress projects. + +# Responsibilities (optional) + +- Validate code and outputs against LightSpeed standards. +- Document decisions, tests, and rationale. +- Promote safe and maintainable workflows. + +# Patterns or Frameworks to Follow (optional) + +- Use WordPress core blocks, theme.json, and native block patterns. +- Reference LightSpeed’s pattern development and coding standards instructions. + +# Practices (optional) + +- Prefer safe defaults; modularity over complexity. +- Use semantic CSS naming and ARIA roles for accessibility. +- Automate linting and tests before merging PRs. + +# Tools (optional) + +- Use WordPress tools, GitHub Actions, Playwright for testing. +- Avoid introducing bespoke tools unless justified. + +# Coverage (optional) + +- Ensure test coverage for new features and workflows. +- Use Playwright, Jest, or equivalent per project language. + +# Constraints (required) + +- Follow UK English, WordPress coding standards, and OWASP top 10 security rules. +- Accessibility and performance must be validated and documented. +- Only use approved tools and frameworks unless justified. + +# What to do (required) + +- Reference core indexes and instructions before starting work. +- Document rationale, tests, and accessibility for all changes. +- Ask clarifying questions if requirements are ambiguous. + +# What not do (required) + +- Do not output secrets, credentials, or sensitive data. +- Do not bypass linting, testing, or documentation standards. +- Do not use non-WordPress or unapproved tools without approval. + +# Best Practices (required) + +- Adhere to WordPress and LightSpeed coding/documentation standards. +- Promote accessibility and semantic markup. +- Propose modular, maintainable solutions and safe defaults. + +# Guardrails (required) + +- Always validate outputs against LightSpeed coding, security, and accessibility standards. +- Flag and document any deviations from best practice. +- Reference AGENTS.md for global principles. + +# Checklist relevant to instructions (required) + +- [ ] Used UK English and WordPress standards. +- [ ] Provided modular, maintainable code and documentation. +- [ ] Automated linting and accessibility validation. +- [ ] Documented rationale and tests. +- [ ] Referenced relevant LightSpeed instruction/index files. +- [ ] Avoided secrets and unapproved tools. + +# Outputs (required) + +- Modular code, accessible markup, documented workflows, rationale, and test results. +- YAML frontmatter in documentation. +- PRs and issues tracked via GitHub. + +# Contribution & Collaboration (optional) + +- Collaborate via GitHub Issues and PRs. +- Reference AGENTS.md and custom-instructions.md for org-wide guidance. +- Tag maintainers for blockers or review. + +# Non-goals (optional) + +- Do not provide generic, non-WordPress solutions. +- Do not deviate from LightSpeed and WordPress standards. + +# Resource links (optional) + +- [LightSpeed Custom Instructions](https://github.com/lightspeedwp/.github/blob/master/.github/custom-instructions.md) +- [AGENTS.md](https://github.com/lightspeedwp/.github/blob/master/AGENTS.md) +- [Coding Standards](https://github.com/lightspeedwp/.github/blob/master/.github/instructions/coding-standards.instructions.md) +- [Prompts Index](https://github.com/lightspeedwp/.github/blob/master/.github/prompts/prompts.md) +- [Pull Request Template](https://github.com/lightspeedwp/.github/blob/master/.github/PULL_REQUEST_TEMPLATE.md) + +# Prompt (required — see D2) + +- Write a concise, actionable prompt tailored to the task, referencing relevant LightSpeed standards, instructions, and indexes. +- Validate the output against coding, accessibility, and security requirements. + +--- + +Provide safe defaults; mark optional flags clearly. +Start by referencing any LightSpeed internal process, documentation, or best practice. This Space is your single source of truth for LightSpeed workflows. +Aim for small, safe, well-documented steps that make the Figma → WordPress handoff effortless. diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..102b87b --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,7 @@ +# CODEOWNERS for LightSpeed WP Scripts + +# See + +# All files in the repo + +* @ashleyshaw @lightspeedwp diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..dfb3980 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,68 @@ +# LightSpeed Code of Conduct (Aligned with the WordPress Community) + +## Our Pledge + +As contributors and maintainers of LightSpeed and the [lightspeedwp](https://github.com/lightspeedwp) GitHub organization, and as members of the broader WordPress community, we pledge to make participation in our project and community a welcoming, respectful, and harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community, in line with the [WordPress Community Code of Conduct](https://make.wordpress.org/community/handbook/code-of-conduct/). + +## Our Standards + +Examples of behavior that contribute to a positive environment for our community include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy and kindness toward other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others’ private information, such as a physical or electronic address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Project maintainers and community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Project maintainers and community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all LightSpeed and lightspeedwp community spaces, including GitHub repositories, issues, pull requests, and any public or private communication channels. It also applies when an individual is officially representing the project or community in public spaces, such as using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the LightSpeed community leaders at [support@lightspeedwp.agency](mailto:support@lightspeedwp.agency). All complaints will be reviewed and investigated promptly and fairly, and will be handled in accordance with the principles of the WordPress community. + +All LightSpeed community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: + +1. **Correction** + - _Community Impact_: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. + +1. **Warning** + - _Community Impact_: A violation through a single incident or series of actions. + +1. **Temporary Ban** + - _Community Impact_: A serious violation of community standards, including sustained inappropriate behavior. + +1. **Permanent Ban** + - _Community Impact_: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. + - _Consequence_: A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [WordPress Community Code of Conduct](https://make.wordpress.org/community/handbook/code-of-conduct/) and the [Contributor Covenant][homepage], version 2.0, available at , and customized for the LightSpeed and lightspeedwp GitHub community. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at . Translations are available at . diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..487c657 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,108 @@ +# Contributing + +**Last Updated:** 2025-10-21 • **Version:** v0.2.0 + +Thank you for your interest in contributing to LightSpeed! +To maintain a consistent, high-quality codebase and community, please follow these guidelines. + +--- + +## Getting Started + +### 1. Start with a GitHub Issue + +- **Select the correct [Issue template](https://github.com/lightspeedwp/.github/issues/new/choose)** for your contribution type: + - Bug report, feature/enhancement, documentation, integration, performance, UX feedback, task, code refactor, instructions, prompts, saved replies, or support question. + - Templates are designed to collect all required information, labels, and metadata for automation and efficient triage. +- **Provide thorough details:** + - For bugs: include reproduction steps, expected vs actual behavior, screenshots, logs, and environment info. + - For features/enhancements: describe the problem/opportunity, proposed solution, mockups/designs, and acceptance criteria. + - For other types: explain context, goals, action items, and impact. +- **Reference relevant docs or standards:** + See [Coding Standards](.github/instructions/coding-standards.instructions.md), [Pattern Development](.github/instructions/pattern-development.instructions.md), [Theme JSON](.github/instructions/theme-json.instructions.md), etc. +- **Outline your planned approach for complex issues** and request feedback before implementation. +- **Automation:** Well-formed issues using the right template are automatically labeled, routed, and prioritized. + +### 2. Branching & Development + +- **Branch naming:** + Use `{type}/{scope}-{short-title}` format (e.g., `feat/cart-coupon-flow`, `fix/wp6-6-compat`, `docs/readme-install-steps`, `chore/deps-2025-09`). +- **Allowed prefixes:** + `feat/`, `fix/`, `docs/`, `chore/`, `build/`, `refactor/`, `test/`, `perf/`, `ci/`, `release/`, `hotfix/`, `design/`, `research/`. +- See [Org-wide Branching Strategy](.github/git-org-wide-branching-strategy.md) for full rules and automation mapping. +- Ensure your branch maps to the correct issue type and PR template for automated labeling and changelog governance. + +### 3. Coding Standards + +- Follow [LightSpeed coding standards](.github/instructions/coding-standards.instructions.md) for PHP, JS, CSS, and other languages. +- Use configured linters/formatters (e.g. ESLint, Prettier, PHPCS) and ensure all code passes checks. +- Write clear, concise commit messages and document significant changes inline. + +--- + +## Pull Requests + +### 4. Create a Pull Request (PR) + +- **Select the correct PR template:** + Bugfix, Feature, Chore, Docs, Build/CI, Dependencies/Maintenance, Hotfix, Release, Refactor, or General PR template. + - Your branch prefix should match the PR template (e.g., `fix/` → Bugfix PR, `feat/` → Feature PR). + - See [PR_LABELS.md](.github/PR_LABELS.md) for template-to-label mapping and automation. +- **Required PR details:** + - Accurate, up-to-date description. + - Link to the related GitHub Issue. + - Testing instructions or demo (video/screenshots preferred for UI changes). + - Changelog entry following [CHANGELOG.md](./CHANGELOG.md) guidelines, grouped under the correct section. + - Document any skipped tests and provide justification. + - For version bumps, include release notes and summary. +- **Draft PRs:** If not ready for review, open as Draft. Convert to ready once complete. + +### 5. Review & Merge + +- PRs are reviewed by maintainers, Copilot, or designated reviewers. +- Respond to feedback and make requested changes. +- Only maintainers can approve and merge PRs. +- PRs must pass all CI checks/tests before merging. + +--- + +## Additional Guidelines + +## VS Code Setup + +To ensure a consistent development experience and code quality, all contributors should: + +- Install all recommended extensions from `.vscode/extensions.json` (includes ESLint, Prettier, YAML, WordPress, PHP, AI, and GitHub workflow tools). +- Use the workspace settings in `.vscode/settings.json` for code style, linting, and workflow automation. These settings align with `.editorconfig` and enforce 2-space indentation for YAML, JS, CSS, and JSON, and 4-space tabs for PHP. +- Enable format-on-save and linting in your editor for best results. +- Periodically review and update your extensions to match evolving project standards. + +Refer to `.vscode/extensions.json` and `.vscode/settings.json` for the authoritative list and configuration. + +- **Saved Replies:** Use [SAVED_REPLIES.md](.github/SAVED_REPLIES.md) for common responses and efficient communication. +- **Documentation:** Update relevant docs (README, instructions) for any user-facing change. +- **Automation & Labels:** Ensure your issue/PR complies with [AUTOMATION_GOVERNANCE.md](.github/AUTOMATION_GOVERNANCE.md), [ISSUE_LABELS.md](.github/ISSUE_LABELS.md), and [ISSUE_TYPES.md](.github/ISSUE_TYPES.md). +- **Changelog:** All user-facing changes, fixes, and features must be entered in [CHANGELOG.md](./CHANGELOG.md) in Keep a Changelog format. See example sections in the changelog for proper grouping and linking. + +--- + +## References + +- [BRANCHING_STRATEGY.md](.github/BRANCHING_STRATEGY.md): Org-wide branch naming, merge discipline, and automation mapping. +- [CHANGELOG.md](./CHANGELOG.md): Changelog format, release notes, and versioning. +- [AUTOMATION_GOVERNANCE.md](.github/AUTOMATION_GOVERNANCE.md): Org-wide automation, branching, label, and release strategy. +- [ISSUE_TYPES.md](.github/ISSUE_TYPES.md): Issue type mapping and usage. +- [ISSUE_LABELS.md](.github/ISSUE_LABELS.md): Label families, triage, and workflow. +- [PR_LABELS.md](.github/PR_LABELS.md): PR labeling, templates, and automation. +- [Org-wide Branching Strategy](.github/git-org-wide-branching-strategy.md): Full branching convention and rules. +- [Coding Standards](.github/instructions/coding-standards.instructions.md) +- [Pattern Development](.github/instructions/pattern-development.instructions.md) +- [Theme JSON](.github/instructions/theme-json.instructions.md) + +--- + +## License + +By contributing to this project, you agree that your contributions will be licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details. + +Thank you for helping us make LightSpeed better! diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..9584ab7 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,104 @@ +# Community Health Repository Setup + +This document provides guidance for contributing to and maintaining this community health repository for the [LightSpeed](https://github.com/lightspeedwp/) organization. + +## Prerequisites + +- [Node.js](https://nodejs.org/) (v18 or later) +- [npm](https://www.npmjs.com/) (v9 or later) + +## Installation & Package Review + +1. Clone the repository: + + ```bash + git clone https://github.com/lightspeedwp/.github.git + cd .github + ``` + +2. Install dependencies: + + ```bash + npm install + ``` + +3. **Review `package.json`:** + Before getting started, check the `package.json` file to understand available scripts, dependencies, and tooling relevant to this repository. + +## Linting and Code Quality + +This repository provides linting tools for JavaScript, CSS, and other code standards, which can be run using Node scripts. These tools help maintain code quality and enforce organization standards. + +- Lint JavaScript: + + ```bash + npm run lint:js + ``` + +- Lint CSS: + + ```bash + npm run lint:css + ``` + +- Run all linters: + + ```bash + npm run lint + ``` + +## Agents & Shared Scripts + +A `scripts/` folder is used to contain shared functions for agents. +Agents are written in JavaScript, and reusable logic or utilities should be placed here for maintainability and collaboration across the organization. + +## Git Workflow + +1. Create a feature branch for your work: + + ```bash + git checkout -b feature/your-feature-name + ``` + +2. Make your changes and commit them: + + ```bash + git add . + git commit -m "Your descriptive commit message" + ``` + +3. Push your changes and create a pull request: + + ```bash + git push origin feature/your-feature-name + ``` + +4. Reference any related issues in your pull request description. Please use the [pull request template](https://github.com/lightspeedwp/.github/blob/master/.github/PULL_REQUEST_TEMPLATE.md) for summaries. + +## Need Help? + +- Check the repository documentation and README files +- Review the [GitHub Copilot custom instructions](./.github/custom-instructions.md) +- Use the prompt files in `.github/prompts/` for guidance + +## Contributing and Code of Conduct + +We welcome contributions! Please review our [Contributing Guidelines](https://github.com/lightspeedwp/.github/blob/master/.github/CONTRIBUTING.md) and [Code of Conduct](https://github.com/lightspeedwp/.github/blob/master/.github/CODE_OF_CONDUCT.md). + +## License + +This project is licensed under the GNU General Public License v3.0 — see the [LICENSE](LICENSE) file for details. + +[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) + +## Reference + +- [BRANCHING_STRATEGY.md](./BRANCHING_STRATEGY.md): Org-wide branch naming, merge discipline, and automation mapping. +- [CHANGELOG.md](../CHANGELOG.md): Changelog format, release notes, and versioning. +- [CONTRIBUTING.md](../CONTRIBUTING.md): Contribution guidelines, templates, coding standards. +- [AUTOMATION_GOVERNANCE.md](./AUTOMATION_GOVERNANCE.md): Org-wide automation, branching, labeling, and release strategy. +- [Org-wide Issue Labels](./ISSUE_LABELS.md): Default labels and usage guidance. +- [Pull Request Labels](./PR_LABELS.md): PR classification labels and automation standards. +- [Canonical Issue Types YAML](./issue-types.yml): Machine-readable issue types for workflow and automation. +- [Canonical Label Definitions](./labels.yml): Label names, colours, and descriptions. +- [Automated Label Assignment Rules](./labeler.yml): Automation for applying labels based on file changes and branch patterns. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..a9197f3 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,172 @@ +--- +title: 'CLAUDE.md Template' +version: 'v1.1' +last_updated: '2025-10-21' +author: 'LightSpeed' +maintainer: 'Ash Shaw' +description: 'Root-level guidance for Claude agents, aligned with LightSpeed organisational standards.' +tags: ['lightspeed', 'templates', 'copilot', 'agents', 'prompts', 'models'] +type: 'agent' +references: + - 'https://github.com/lightspeedwp/.github/blob/master/.github/custom-instructions.md' + - 'https://github.com/lightspeedwp/.github/blob/master/AGENTS.md' + - 'https://github.com/lightspeedwp/.github/blob/master/.github/instructions/coding-standards.instructions.md' +--- + +# Role + +You are a Claude agent operating within LightSpeed. Follow LightSpeed's [AGENTS.md](https://github.com/lightspeedwp/.github/blob/master/AGENTS.md), [custom instructions](https://github.com/lightspeedwp/.github/blob/master/.github/custom-instructions.md), and project-specific frameworks to deliver modular, maintainable WordPress solutions. Use UK English. Avoid non-WordPress tools, custom code, or exposing secrets unless explicitly directed. + +# Style + +- Write modular, maintainable, and testable code and documentation. +- Use semantic, accessible markup and descriptive comments per WordPress standards. +- Optimise for performance, accessibility, and scalability. +- Justify any tool or pattern outside LightSpeed defaults with clear rationale. + +# Purpose + +- Deliver clear, secure, and scalable outcomes for LightSpeed WordPress projects. +- Ensure all outputs meet LightSpeed’s standards for clarity, maintainability, security, and accessibility. +- Support and automate workflows for efficient Figma → WordPress handoff. + +# Type of Task + +- Coding, code review, documentation, prompt authoring, agentic workflow design, and process checklists for WordPress and web projects. +- Validate outputs against [LightSpeed coding standards](https://github.com/lightspeedwp/.github/blob/master/.github/instructions/coding-standards.instructions.md), linting, and accessibility requirements. + +# How to ask for help + +- Reference this Space and LightSpeed documentation first. +- Ask a single, focused question if requirements or context are unclear. +- Escalate blockers by tagging the maintainer and referencing relevant documentation or index files. + +# Conventions + +- Use YAML frontmatter in documentation. +- Reference core index files for standards ([see AGENTS.md](https://github.com/lightspeedwp/.github/blob/master/AGENTS.md)). +- Track issues and PRs via GitHub; reference/close issues in commit messages. + +# Process + +- Start by checking AGENTS.md and custom-instructions.md for current org rules. +- Confirm project scope and constraints before coding. +- Use GitHub Issues and PRs for all changes; follow the [pull request template](https://github.com/lightspeedwp/.github/blob/master/.github/PULL_REQUEST_TEMPLATE.md). +- Log rationale and testing coverage for every change. + +# Examples + +- See [prompts index](https://github.com/lightspeedwp/.github/blob/master/.github/prompts/prompts.md) for reusable prompt files. +- Example outputs: accessible markup, modular WordPress block patterns, documented workflow YAML. + +# Important notes + +- Never expose secrets or sensitive data. +- Accessibility and performance are non-negotiable. +- Update documentation and rationale with every material change. + +# Who is this for + +- Claude agents, contributors, and maintainers working on LightSpeed WordPress projects. + +# Responsibilities + +- Validate code and outputs against LightSpeed standards. +- Document decisions, tests, and rationale. +- Promote safe and maintainable workflows. + +# Patterns or Frameworks to Follow + +- Use WordPress core blocks, theme.json, and native block patterns. +- Reference LightSpeed’s pattern development and coding standards instructions. + +# Practices + +- Prefer safe defaults; modularity over complexity. +- Use semantic CSS naming and ARIA roles for accessibility. +- Automate linting and tests before merging PRs. + +# Tools + +- Use WordPress tools, GitHub Actions, Playwright for testing. +- Avoid introducing bespoke tools unless justified. + +# Coverage + +- Ensure test coverage for new features and workflows. +- Use Playwright, Jest, or equivalent per project language. + +# Constraints + +- Follow UK English, WordPress coding standards, and OWASP top 10 security rules. +- Accessibility and performance must be validated and documented. +- Only use approved tools and frameworks unless justified. + +# What to do + +- Reference core indexes and instructions before starting work. +- Document rationale, tests, and accessibility for all changes. +- Ask clarifying questions if requirements are ambiguous. + +# What not do + +- Do not output secrets, credentials, or sensitive data. +- Do not bypass linting, testing, or documentation standards. +- Do not use non-WordPress or unapproved tools without approval. + +# Best Practices + +- Adhere to WordPress and LightSpeed coding/documentation standards. +- Promote accessibility and semantic markup. +- Propose modular, maintainable solutions and safe defaults. + +# Guardrails + +- Always validate outputs against LightSpeed coding, security, and accessibility standards. +- Flag and document any deviations from best practice. +- Reference AGENTS.md for global principles. + +# Checklist relevant to instructions + +- [ ] Used UK English and WordPress standards. +- [ ] Provided modular, maintainable code and documentation. +- [ ] Automated linting and accessibility validation. +- [ ] Documented rationale and tests. +- [ ] Referenced relevant LightSpeed instruction/index files. +- [ ] Avoided secrets and unapproved tools. + +# Outputs + +- Modular code, accessible markup, documented workflows, rationale, and test results. +- YAML frontmatter in documentation. +- PRs and issues tracked via GitHub. + +# Contribution & Collaboration + +- Collaborate via GitHub Issues and PRs. +- Reference AGENTS.md and custom-instructions.md for org-wide guidance. +- Tag maintainers for blockers or review. + +# Non-goals + +- Do not provide generic, non-WordPress solutions. +- Do not deviate from LightSpeed and WordPress standards. + +# Resource links + +- [LightSpeed Custom Instructions](https://github.com/lightspeedwp/.github/blob/master/.github/custom-instructions.md) +- [AGENTS.md](https://github.com/lightspeedwp/.github/blob/master/AGENTS.md) +- [Coding Standards](https://github.com/lightspeedwp/.github/blob/master/.github/instructions/coding-standards.instructions.md) +- [Prompts Index](https://github.com/lightspeedwp/.github/blob/master/.github/prompts/prompts.md) +- [Pull Request Template](https://github.com/lightspeedwp/.github/blob/master/.github/PULL_REQUEST_TEMPLATE.md) + +# Prompt + +- Write a concise, actionable prompt tailored to the task, referencing relevant LightSpeed standards, instructions, and indexes. +- Validate the output against coding, accessibility, and security requirements. + +--- + +Provide safe defaults; mark optional flags clearly. +Start by referencing any LightSpeed internal process, documentation, or best practice. This Space is your single source of truth for LightSpeed workflows. +Aim for small, safe, well-documented steps that make the Figma → WordPress handoff effortless. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..14e880a --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,73 @@ +# LightSpeed Community Health Repo Governance + +Defines maintainer/contributor roles and decision making. +See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). + +## Overview + +This document explains how the LightSpeed community health repository is governed. It describes project roles, responsibilities, decision-making processes, and references key organisational standards and policies. The goal is to ensure a transparent, inclusive, and maintainable project. + +## Maintainers + +| Name | GitHub Username | Profile URL | +| ---------------- | --------------- | --------------------------------------------- | +| Ash Shaw | @ashleyshaw | [ashleyshaw](https://github.com/ashleyshaw) | +| Warwick Booth | @krugazul | [krugazul](https://github.com/krugazul) | +| Chris Vancoillie | @eleshar | [eleshar](https://github.com/eleshar) | +| Zared Rogers | @ZaredRogers | [ZaredRogers](https://github.com/ZaredRogers) | + +## Decision Making + +- **Routine:** Maintainers review and merge PRs. +- **Major:** Consensus among maintainers. + +## Roles & Responsibilities + +#### Responsibilities + +- Triage issues and pull requests +- Review, merge, and release features and fixes +- Ensure code quality, security, and documentation standards +- Manage repo configuration and CI/CD +- Promote contributors to maintainers +- Update governance, automation, and workflow documents + +### Promotion criteria + +Contributors may be promoted to maintainer after a significant number of high-quality PRs, consistent engagement, and demonstration of LightSpeed standards. Promotion is at the discretion of existing maintainers. + +### Contributors + +- Anyone submitting code, content, or participating via issues or PRs. +- Can triage issues and PRs, and have commit access once approved. +- Expected to follow contribution guidelines and review requirements. + +## Decision Making + +- **Routine changes:** Maintainers review and merge PRs based on coding standards and contribution guidelines. +- **Major changes:** Discussed openly, decided by consensus among maintainers. If consensus cannot be reached, lead maintainer decides. +- **Conflict resolution:** Maintainers will mediate. Issues can be escalated via [contact methods](#reporting--contact). + +## Change Process + +- Governance changes are proposed via pull request and require review and approval from at least one maintainer. + +## Reporting & Contact + +- For governance or code of conduct concerns, open a GitHub issue or contact a maintainer directly. + +## Key Documents & Standards + +- [General Org Instructions](./.github/custom-instructions.md) +- [Coding Standards](./.github/instructions/coding-standards.instructions.md) +- [Contribution Guidelines](../CONTRIBUTING.md) +- [Branching Strategy](../BRANCHING_STRATEGY.md) +- [Automation Governance](../AUTOMATION_GOVERNANCE.md) +- [Issue & PR Labels](../ISSUE_LABELS.md), [../PR_LABELS.md](../PR_LABELS.md), [../labels.yml](../labels.yml), [../labeler.yml](../labeler.yml) +- [Issue Types YAML](../issue-types.yml) +- [Pull Request Template](./.github/PULL_REQUEST_TEMPLATE.md) +- [CHANGELOG](../CHANGELOG.md) + +--- + +_This document is maintained by the LightSpeed community. Propose changes via pull request._ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..79fa908 --- /dev/null +++ b/LICENSE @@ -0,0 +1,681 @@ + + ``` + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + ``` + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + +1. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + +2. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + +3. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +4. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +5. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +6. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + +7. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +8. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +9. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +10. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +11. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + +12. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +13. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +14. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +15. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + +16. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + ``` + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + ``` + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + ``` + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + ``` + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/README.md b/README.md index 1f497d0..86e29d5 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,238 @@ -# WordPress Documentation Hub +# lightspeedwp – WordPress Engineering & AI Assistant Docs -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. +Accelerating high‑quality WordPress development with reusable AI building blocks (prompts, instructions, chat modes, agent governance) +and domain handbooks (block themes, coding standards, Gutenberg guides). Everything is tuned to produce fast, secure, accessible, +internationalised, and maintainable solutions (themes, plugins, blocks, patterns). + +## Mission + +Empower WordPress developers to deliver production‑ready features at lightspeed while upholding coding standards, +accessibility (WCAG 2.2), performance, security (OWASP), and sustainable long‑term maintainability. + +## Repository Structure + +| Area | Path | Summary | +| -------------------- | ------------------------ | ------------------------------------------------------------------- | +| Documentation Hub | `docs/` | Master index & cross-cutting conventions (see `docs/README.md`). | +| Copilot / AI Assets | `docs/copilot-space/` | Prompts, instructions, chat modes, agent schemas & authoring rules. | +| Block Theme Guidance | `docs/block-themes/` | Fluid spacing, typography scales, global styles, naming, patterns. | +| Coding Standards | `docs/coding-standards/` | WordPress coding standards overlays, inline docs, research notes. | +| Gutenberg Guides | `docs/gutenberg/` | Getting started, how‑tos, reference, schemas. | +| Frontmatter Schemas | `docs/frontmatter/` | YAML frontmatter conventions & schemas. | +| Agent Governance | `AGENTS.md` | Behavioural contract for AI assistants & personas. | +| Automation Scripts | `.github/scripts/` | Generators, validators, normalisation tooling. | + +See also: `CHANGELOG.md` for historical evolution. + +## Why Keep Cross‑Technology Assets? + +Many engineering concerns (testing discipline, performance, security, accessibility, structured planning) transcend platform boundaries. +We intentionally retain high‑quality “generic” or multi‑stack assets because they: + +1. Provide architectural clarity applicable to large WordPress installations (headless, API integrations, infrastructure). +2. Reduce reinvention—reuse vetted language/framework guidance where analogous (e.g. performance patterns informing PHP + JS code paths). +3. Enable mixed‑stack teams (WP + services) to align on shared standards. + +Future refinement: lightweight tagging (e.g. `wp-core`, `block-dev`, `generic`, `infra`) to improve discoverability without deleting value. + +## Quick Start (Using AI Assets) + +1. Install desired Copilot assets (Prompts / Chat Modes / Instructions) via VS Code badges in each catalog. +2. Copy any custom instruction you want permanently into `.github/instructions/` (or merge into a project‑level `copilot-instructions.md`). +3. Open Copilot Chat and select a lightspeedwp chat mode (or paste a prompt) to accelerate tasks. +4. Iterate: refine instructions with project specifics (naming conventions, text domain, PHPCS rules). + +### Example: Generate a Block Scaffold + +1. Open your plugin or theme workspace. +2. Use the “Implementation Plan” prompt to outline the block (attributes, render strategy, style variants, i18n extraction). +3. Apply “Accessibility Review” prompt / chat mode to validate ARIA & keyboard flows. +4. Use performance & security instructions to audit dynamic rendering and REST endpoints. + +### Example: Harden a Custom REST Endpoint + +1. Invoke security instructions (OWASP) + performance optimization guidelines. +2. Provide the endpoint handler code to a “Security & Code Quality” chat mode. +3. Request: “Suggest nonce, capability checks, caching & schema validation improvements.” + +## Schema Validation & Automation + +### YAML/JSON Schema Validation + +All configuration schemas (e.g. for `.coderabbit.yml`) are stored in the `schemas/` directory at the project root. This enables: + +- **Offline validation**: Always validate against the latest downloaded schema, even without internet access. +- **Automated updates**: Keep schemas up to date with a single command. + +#### Validate `.coderabbit.yml` + +```sh +npm run validate:coderabbit +``` + +or + +```sh +node scripts/json-validation/validate-coderabbit-yml.cjs +``` + +#### Update the CodeRabbit schema + +```sh +node scripts/json-validation/update-coderabbit-schema.cjs +``` + +This fetches the latest schema from the remote source and saves it to `schemas/coderabbit-overrides.v2.json`. + +**Tip:** Add this as a pre-commit, pre-push, or CI step to ensure your validation is always up to date. + +--- + +## Contributing (Overview) + +See `CONTRIBUTING.md` for full process. Summary: + +1. Fork & branch. +2. Add or update a prompt / instruction / chat mode (include frontmatter) or improve a WordPress guide. +3. Keep scope tight; ensure examples are WP‑relevant where applicable. +4. Run any validation/update scripts (if present) before PR. +5. Provide rationale + before/after (if refactoring docs). + +### Quality Checklist (Abbreviated) + +- Clear purpose & actionable steps +- WordPress alignment (or clearly marked cross‑tech) +- Accessibility & security consciousness +- No hard‑coded secrets / unsafe patterns +- Consistent naming & formatting + +## Roadmap Snapshot + +High‑level items (see `CHANGELOG.md` for canonical history & upcoming): + +- Tagging taxonomy for AI assets & docs. +- WordPress‑specialised chat modes (Theme JSON Refiner, Block Accessibility Auditor, Hook Strategy Advisor). +- Collections curation once tagging lands. +- Domain surfacing (stability, domain) in generated README tables. +- Automated link & frontmatter validator. + +## Namespace & Badges + +Any legacy install badges still referencing upstream sources are intentionally preserved during transition; +they will migrate once tagging + mirroring strategy finalises. + +## License + +This repository is licensed under the **GNU GPL v3** (see `LICENSE`). Documentation and AI asset text are distributed under the same license for simplicity. +If you require alternative terms for specific reuse scenarios, open an issue to discuss. + +## Feedback & Improvements + +Open an issue with: context, goal, current friction, desired outcome. +Evidence (snippets, diffs) speeds triage. + +--- + +Crafted with accessibility, security, performance, and internationalisation in mind—manual review & testing still required. ## 📁 Documentation Sections -### [🎨 Block Themes](block-themes/) +### [🎨 Block Themes](docs/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) +**Key Files:** [Fluid Typography](docs/block-themes/fluid-typography.md) • [Global Styles](docs/block-themes/global-styles.md) + +- [Theme Structure](docs/block-themes/theme-structure-epi.md) + +### [📋 Coding Standards](docs/coding-standards/) -### [📋 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 + +- **[LightSpeed Standards](docs/coding-standards/ash-research/)** - Enhanced WordPress standards (WPCS v3.2.0) with security-first approach +- **[WordPress Core Standards](docs/coding-standards/wordpress-coding-standards/)** - Official WordPress coding guidelines +- **[Inline Documentation](docs/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/) +### [🤖 Copilot Space](docs/copilot-space/) + +AI-assisted development assets and configurations: + +- **Chat Modes** - Specialized AI conversation modes for WordPress development +- **Prompt Libraries** - Reusable prompts for common development tasks +- **Agent Instructions** - Behavioral contracts for AI assistants +- **Schemas** - Structured templates for consistent AI interactions + +**Key Files:** [Agents](docs/copilot-space/agents-md.md) • [Chat Modes](docs/copilot-space/chatmodes.md) + +- [Instructions](docs/copilot-space/copilot-instructions.md) + +### [⚙️ YAML Frontmatter](docs/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) +**Key Files:** [Frontmatter Cheat Sheet](docs/frontmatter/YAML%20Frontmatter%20Cheat%20Sheet.md) + +- [Schema Guidelines](docs/frontmatter/YAML-Frontmatter%20Schema-Guidelines.md) + +### [🧱 Gutenberg Documentation](docs/gutenberg/) -### [🧱 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 + +- **[Getting Started](docs/gutenberg/getting-started/)** - Development environment setup and tutorials +- **[How-to Guides](docs/gutenberg/how-to-guides/)** - Practical implementation guides +- **[Reference Guides](docs/gutenberg/reference-guides/)** - API references and technical documentation +- **[Schemas](docs/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 + +1. Review [Block Themes documentation](docs/block-themes/) for modern theme development +2. Implement [Fluid Typography](docs/block-themes/fluid-typography.md) and [Spacing](docs/block-themes/fluid-spacing.md) +3. Follow [LightSpeed Coding Standards](docs/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/) + +1. Start with [WordPress Coding Standards](docs/coding-standards/wordpress-coding-standards/) +2. Review [Gutenberg How-to Guides](docs/gutenberg/how-to-guides/) for block development +3. Implement [Inline Documentation Standards](docs/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 + +1. Set up [YAML Frontmatter](docs/frontmatter/) for standardized templates +2. Configure [Copilot Space](docs/copilot-space/) for AI workflows +3. Use [Schema Guidelines](docs/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 +- **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 | +| 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 +This documentation hub ensures consistent, secure, and maintainable WordPress development across all project types and development workflows. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..1868390 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,14 @@ +# Security Policy + +If you discover a security vulnerability in this project, please report it responsibly. + +- **Contact:** [support@lightspeedwp.agency](mailto:support@lightspeedwp.agency) +- Please provide as much detail as possible so we can address the issue quickly. + +We follow the [WordPress Security Best Practices](https://developer.wordpress.org/security) and adhere to the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/). + +We aim to respond to security reports within 3 business days. + +## License + +This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..76ea90d --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,17 @@ +## Support + +**Please note:** We do not provide free support for our open source software. Support is available as a paid service. + +For bug reports or issues, please use the relevant issue template in our [GitHub Issues](https://github.com/lightspeedwp/repo-name/issues/new/choose) section. + +For paid support, contact our team: + +- **Email:** [support@lightspeedwp.agency](mailto:support@lightspeedwp.agency) + +We aim to respond to paid support requests within 2 business days. + +For more information, please refer to our documentation or FAQ if available. + +## License + +This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. diff --git a/SUPPRESSIONS.md b/SUPPRESSIONS.md new file mode 100644 index 0000000..6c2f58f --- /dev/null +++ b/SUPPRESSIONS.md @@ -0,0 +1,24 @@ +# Markdown Lint Suppressions + +This file documents all global markdownlint suppressions applied in `.markdownlint.json` for the `wp-docs` repository. These suppressions are intended to balance code quality, maintainability, and practical constraints when working with legacy or complex documentation. + +## Suppressed Rules + +### MD013 – Line Length + +**Suppressed:** Yes (globally) +**Rationale:** Many legacy documentation files contain long URLs, tables, or code examples that would be impractical to reflow. Enforcing this rule would create excessive diffs and reduce readability for technical content. + +### MD003 – Heading Style (Setext vs ATX) + +**Suppressed:** Yes (globally) +**Rationale:** The documentation set includes a mix of Setext and ATX headings, and converting all Setext headings would be time-consuming and error-prone. Suppression avoids unnecessary churn and preserves original author intent. + +### MD040 – Fenced Code Block Language + +**Suppressed:** Yes (globally) +**Rationale:** Many code blocks in legacy docs lack a specified language. Enforcing this rule would require manual review of hundreds of blocks, with little practical benefit for current usage. + +--- + +> **Note:** These suppressions are reviewed periodically. If documentation is rewritten or significantly refactored, consider re-enabling these rules for new or heavily revised files. diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..b82608c --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +v0.1.0 diff --git a/YAML Frontmatter Cheat Sheet.md b/YAML Frontmatter Cheat Sheet.md deleted file mode 100644 index 0b13ec8..0000000 --- a/YAML Frontmatter Cheat Sheet.md +++ /dev/null @@ -1,525 +0,0 @@ -# **YAML Frontmatter Cheat Sheet for GitHub Templates and AI Agent Configurations** - -## **GitHub Issue Template Frontmatter (Issue Forms)** - -GitHub **issue templates** can use a YAML frontmatter (especially for the new **Issue Forms**) to define metadata and form fields. All issue form files **must** begin with at least three keys: `name`, `description` (often called “about” in legacy templates), and `body`[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=All%20issue%20form%20configuration%20files,value%20pairs). Additional optional keys let you preassign labels, assignees, etc. Here are the top-level frontmatter fields for an issue form template[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,repository%2C%20it%20will%20not%20be)[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,using%20this%20template%20to%20have): - -* **`name`** – Unique name for the template (appears in template picker UI) **(required)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,Required%20String). - -* **`description`** – Short explanation of the template’s purpose (shown in picker UI) **(required)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=templates%2C%20including%20Markdown%20templates,Required%20String). - -* **`body`** – An array defining the form fields and content blocks for the issue form **(required)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,assigned%20to%20issues%20created%20with). - -* **`title`** – Default title that will pre-fill in the new issue title input **(optional)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=template,Optional%20String). - -* **`labels`** – Labels to auto-apply on issue creation (array or comma-separated) **(optional)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,delimited%20string). - -* **`assignees`** – GitHub usernames to auto-assign the issue to (array or comma-separated) **(optional)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,repository%2C%20it%20will%20not%20be). - -* **`projects`** – GitHub Projects to auto-add the issue to (format `"OWNER/PROJECT-NUMBER"`) **(optional)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=to%20create%20a%20shared%20syntax,delimited%20string). - -* **`type`** – Issue type to assign (if your organization uses custom issue types) **(optional)**[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,created%20with%20this%20template%20will). - -Below is an **example** of a comprehensive issue form YAML frontmatter, including a variety of field types in the `body`. Comments (`# ...`) are added to explain each parameter and best practices: - -`---` -`name: "Bug Report" # Template name (must be unique in repo)` -`description: "Report a bug in the project." # Shown in the new issue template chooser` -`title: "[Bug]: " # Default issue title prefix` -`labels: ["bug", "needs-triage"] # Labels to apply automatically` -`assignees: ["octocat"] # Users to assign by default` -`projects: ["my-org/42"] # Add issue to project board (org/project-number)` -`type: bug # Issue type (if using typed issues in org)` - -`body:` - `- type: markdown` - `attributes:` - `value: "## Thank you for reporting a bug!\nPlease fill out the sections below."` - `# ^ A static guidance section (Markdown instructions for the user).` - `# Note: Use quotes for text containing '#' or special YAML chars:contentReference[oaicite:11]{index=11},` - `# and use '|' for multi-line content as shown above.` - - `- type: input` - `id: "contact"` - `attributes:` - `label: "Contact Details"` - `description: "How can the team reach you for more info?"` - `placeholder: "e.g. email@example.com"` - `value: "" # default can be left blank` - `validations:` - `required: false # mark field optional (true would prevent submission if empty)` - - `- type: textarea` - `id: "steps"` - `attributes:` - `label: "Steps to Reproduce"` - `description: "Provide step-by-step instructions to reproduce the issue."` - `placeholder: |` - `1. Step one...` - `2. Step two...` - `3. *Feel free to add more steps as needed...*` - `value: "" # you can pre-fill common steps or leave empty` - `render: markdown # if provided, the submitted text will be formatted as a code block of this type (e.g. markdown, bash)` - `validations:` - `required: true # this textarea must be filled in` - - `- type: dropdown` - `id: "browser"` - `attributes:` - `label: "Affected Browser(s)"` - `description: "Which web browsers show the issue?"` - `options:` - `- "Firefox"` - `- "Chrome"` - `- "Safari"` - `- "Edge"` - `multiple: true # allow multiple selections` - `validations:` - `required: true # at least one option must be selected` - - `- type: checkboxes` - `id: "agree"` - `attributes:` - `label: "Code of Conduct Agreement"` - `description: "Please confirm:"` - `options:` - `- label: "I have searched for duplicate issues"` - `required: true # this box must be checked to submit (ensures reporter did a search)` - `- label: "I agree to follow the project’s Code of Conduct"` - `required: true` -`---` - -In the **`body`** array above, we demonstrated each supported input type: - -* **Markdown (`type: markdown`)** – Just static text guidance (not included in final issue content). Use this for instructions or banners. *Tip:* If using `#` in the text (for headings), wrap the value in quotes to prevent YAML treating it as a comment[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,if%20we%20need%20more%20info). - -* **Text Input (`type: input`)** – Single-line text field. Supports `label`, `description`, `placeholder`, `value` (default text), and validations like `required`[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=%23%23%23%20Current%20Behavior%3A%20%3C%21,)[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=1.%20See%20error...%20). - -* **Textarea (`type: textarea`)** – Multi-line text field for longer input. Supports the same attributes as input, plus `render` (to automatically format user text as a code block of a given language)[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=attributes%3A%20label%3A%20Relevant%20log%20output,attributes%3A%20label%3A%20Code%20of%20Conduct)[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=description%3A%20Please%20copy%20and%20paste,Code%20of%20Conduct%5D%28https%3A%2F%2Fexample.com). - -* **Dropdown (`type: dropdown`)** – Single or multi-select from a list of options. Requires an `options` list. You can set `multiple: true` for multi-select. If you include a `default:` index (0-based) in attributes, that option will be pre-selected[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=id%3A%20version%20attributes%3A%20label%3A%20Version,3%20%28Edge%29%20default%3A%200%20validations). Validation `required: true` means the user must select at least one[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,type%3A%20dropdown). - -* **Checkboxes (`type: checkboxes`)** – A group of one or more checkbox items. Each option has a `label` (supports basic Markdown) and optionally `required: true` if that particular box must be checked[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=id%3A%20terms%20attributes%3A%20label%3A%20Code,Code%20of%20Conduct%20required%3A%20true). If any checkbox option is marked required, the form won’t submit until it’s checked (useful for “I agree” confirmations). - -**Best Practices:** - -* **Formatting:** Enclose the frontmatter between `---` lines at the top of the template file. Indentation is significant in YAML – use consistent two-space indents for nested fields. - -* **Quoting:** Quote strings that contain special characters (like `:` or `#`) or begin with square brackets. For instance, the `title` value `[Bug]:` is quoted in YAML[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=name%3A%20%20Bug%20description%3A%20File,already%20exists%20for%20the%20bug) to avoid parsing issues. - -* **Multiline Text:** Use the pipe `|` in YAML to input multiline default text or placeholders (as shown for the steps placeholder above) so that line breaks are preserved[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,if%20we%20need%20more%20info). - -* **Required Fields:** Use `validations: required: true` judiciously – only when the issue cannot be submitted without that info. Otherwise, leave as optional to not frustrate contributors. - -* **Unique IDs:** The `id` fields in inputs aren’t mandatory, but assigning them (alphanumeric, `-` or `_` only) can help reference responses programmatically (or for future automation). - -* **Keep it Short:** While you can include many fields, try not to overwhelm the contributor. Only ask for information that is necessary to triage the issue. - -## **GitHub Pull Request Template Frontmatter** - -Pull request templates are simpler – GitHub **does not currently support form-style PR templates with YAML-defined inputs** (issue forms are for issues only)[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=Issue%20forms%20are%20not%20supported,request%20template%20for%20your%20repository)[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=When%20a%20contributor%20fills%20out,issue%20created%20through%20other%20methods). However, you *can* include a YAML frontmatter at the top of a PR template file to pre-specify metadata like title, labels, etc., but as of now, **GitHub ignores these frontmatter fields for PRs** – any frontmatter will simply remain in the text of the PR body (not parsed out)[stackoverflow.com](https://stackoverflow.com/questions/66392676/github-pull-request-template-detect-yaml-front-matter-using-config-yml-and-apply#:~:text=5). In practice, this means the YAML block would just be visible to users opening the PR, which is usually undesirable. (There is no PR template picker UI, unlike issues.) - -For completeness, here are the **frontmatter keys** that parallel issue templates (even though they won’t be auto-applied by GitHub for PRs as of 2025): - -* **`name`** – Name of the PR template (if multiple templates via query parameter). - -* **`about`** – Description of the template’s use. - -* **`title`** – Default title for pull requests using this template. - -* **`labels`** – Labels to add to the PR. - -* **`assignees`** – Users to assign to the PR. - -These keys mirror the issue template keys (note: here it’s `about` instead of `description`). For example, a PR template might start like: - -`---` -`name: "Feature PR Template"` -`about: "Use this template for pull requests adding a new feature"` -`title: "feat: "` -`labels: enhancement, needs-review` -`assignees: octocat` -`---` - -*Even though you can include such a frontmatter in a PR template file, GitHub will currently just display it as text in the PR body[stackoverflow.com](https://stackoverflow.com/questions/66392676/github-pull-request-template-detect-yaml-front-matter-using-config-yml-and-apply#:~:text=5).* Therefore, many repositories omit YAML frontmatter in PR templates altogether, and instead just provide a structured markdown checklist or guidance for the contributor. A good pull request template includes sections like “Linked Issue”, “Summary of Changes”, “Testing Instructions”, etc., written as comments or headings in Markdown (since those will guide the PR author). - -**Best Practices:** - -* If you include a YAML header in a PR template, be aware it won’t be processed by GitHub (it might confuse contributors seeing raw `---` lines). It’s often better to stick to plain Markdown for PR templates. - -* Use HTML comments (``) in the template to provide guidance that won’t appear in the final PR description. For example, ``. - -* Encourage linking issues in the PR body (e.g., “Closes \#123”) and including screenshots or test output if applicable. These aren’t frontmatter parameters, but important content for PR quality. - -*(Note: GitHub might add support for parsing PR template frontmatter in the future, but at the time of writing it’s not implemented[stackoverflow.com](https://stackoverflow.com/questions/66392676/github-pull-request-template-detect-yaml-front-matter-using-config-yml-and-apply#:~:text=5).)* - -## **GitHub Saved Replies** - -GitHub **saved replies** are canned responses for commenting on issues and PRs. They **do not use file-based YAML frontmatter** at all – instead, they are created and managed via the GitHub web UI (under your profile’s **Saved replies** settings)[docs.github.com](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies#:~:text=Creating%20a%20saved%20reply). Each saved reply simply has two pieces of metadata: - -* **Title** – a short name you give the saved reply (for your own reference in the UI). - -* **Body content** – the actual text (which can include Markdown formatting) that will be inserted when you use the saved reply. - -For example, you might have a saved reply titled “Duplicate Issue Response” with a body like: - -“Thank you for reporting this. We’re tracking this issue in \#XYZ, so I’ll close this as a duplicate. Please follow the other thread for updates.” - -When you insert that saved reply, GitHub will populate the comment box with that message. - -**Key points:** - -* **No frontmatter file:** Saved replies are not stored in a repository file. They’re tied to your GitHub account. (There is no native way to define them in code or config files, thus no YAML format to document here.) - -* **Usage:** You create/edit them via **Settings \> Saved replies**. Each reply’s title is just for your menu; it isn’t inserted into the comment. Only the body content gets inserted[docs.github.com](https://docs.github.com/en/get-started/writing-on-github/working-with-saved-replies#:~:text=Using%20saved%20replies). - -* **Markdown Support:** The body supports normal comment formatting (Markdown links, lists, etc.), so you can include checklists or bold text as part of the saved reply. - -* **Best Practices:** Keep saved replies concise and general. You can always customize the inserted text after picking it, so they serve best as starting templates. For instance, it’s fine to include a placeholder like “\[issue link\]” in the saved reply text that you replace with a real link after insertion. - -*(Since saved replies don’t utilize YAML, there are no frontmatter parameters to list here.)* - -## **GitHub Copilot – Repository & Path-Specific Custom Instructions** - -GitHub Copilot allows you to provide **custom instructions** to guide code suggestions. These can be set at different levels: - -* **Personal instructions** (via your GitHub Copilot settings in your account) – not a file, just text you save in your profile. - -* **Repository-wide instructions** – a special file in the repository. - -* **Path-specific instructions** – files that apply only to certain files/paths in a repo. - -For **repository-wide instructions**, create a Markdown file named **`.github/copilot-instructions.md`** at the root of your repo[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=Creating%20repository). This file contains plain Markdown text with whatever guidance you want Copilot to always consider for this repository. For example, you might describe coding style, architectural guidelines, or context about the project. There is *no YAML frontmatter needed or used* in this file – it’s just a Markdown document of instructions (whitespace and newlines don’t matter to Copilot; it treats it as one block of text)[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=2,the%20file%2C%20in%20Markdown%20format). - -For **path-specific instructions**, create a folder `.github/instructions/`, and inside it one or more files with names like `XYZ.instructions.md` (the name can indicate the context). These files **do use YAML frontmatter** to specify where they apply. At the very top, include an `applyTo` key with a glob pattern (or multiple patterns) matching file paths[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=3,directories%20the%20instructions%20apply%20to)[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=). For example: - -`---` -`applyTo: "app/models/**/*.rb,app/controllers/**/*.rb" # apply to all Ruby files in app/models or app/controllers` -`---` -`# Rails Model/Controller Conventions` - -`- Follow Ruby on Rails idioms for models and controllers.` -`- Ensure to include necessary unit tests for any new model methods.` - -**Frontmatter fields for `*.instructions.md`:** - -* **`applyTo`** – Glob pattern of files that this instructions file should apply to[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=3,directories%20the%20instructions%20apply%20to). Use Unix shell style globs (e.g. `"**/*.ts"` for all TypeScript files, or `"docs/**/*"` for anything under docs). You can specify multiple patterns by separating with commas[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=You%20can%20specify%20multiple%20patterns,use%20the%20following%20frontmatter%20block). For a file that should apply to all files in the repo, use `applyTo: "**"`[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=). - -* **`description`** – *(Optional)* A short description of these instructions. In VS Code’s Copilot Chat UI, this description will show on hover or in the list of available instruction files[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#:~:text=Instructions%20files%20use%20the%20,extension%20and%20have%20this%20structure). This is mainly for your own organization; Copilot itself doesn’t use the description content for suggestions. - -After the frontmatter, the rest of the file is just Markdown text describing the instructions (similar to the repo-wide file). **Whitespace or blank lines are ignored** by Copilot, so you can format the instructions for readability[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=2,the%20file%2C%20in%20Markdown%20format). You can even use Markdown links to reference other files or documentation within your instructions. - -**Example path-specific instructions file:** - -`---` -`applyTo: "**/*.py" # apply to all Python files` -`description: "Python code style guidelines for this repo"` -`---` -`# Python Coding Guidelines` - -``- Follow PEP 8 style guide for Python code (use `black` for formatting).`` -`- Use type hints for all functions and methods.` -`- Prefer list comprehensions and generator expressions for simple loops.` -``- Avoid using wildcard `import` statements; import only what is needed.`` - -In the above, whenever Copilot is generating suggestions **while editing a `.py` file**, it will factor in these Python Coding Guidelines in addition to any repo-wide instructions. If multiple instruction files apply (say you had one for all backend code and one for Python specifically), all relevant instructions are combined. - -**Best Practices:** - -* Keep instruction statements **concise and in natural language** (Copilot works best with clear, high-level guidance). For example, “Use 4 spaces for indentation” or “All API calls must include error handling.” - -* Use **separate files for distinct domains** – e.g., language-specific guidelines, or testing guidelines vs. deployment guidelines. This modular approach makes it easier to maintain. You can have many instruction files as needed. - -* Name the files logically (the name before `.instructions.md` doesn’t affect function, but helps you identify it). For example, `python.instructions.md`, `frontend.instructions.md`, `security.instructions.md`, etc. - -* Leverage the `applyTo` glob to target precisely. Be careful that your pattern isn’t too broad or too narrow. (Multiple patterns can be combined in one file if the instructions are identical.) - -* **Tip:** In VS Code, you can manually attach an instructions file to a chat even if its pattern doesn’t auto-apply, via the *Add Context \> Instructions* option. This is useful if you want to use an instruction file in a one-off manner outside its auto scope. - -## **GitHub Copilot – Custom Prompt Files (`.prompt.md`)** - -Copilot also supports **reusable prompt files** (especially in VS Code’s Copilot Chat context). A prompt file is a Markdown file (with extension `.prompt.md`) that defines a specific prompt or task for the AI, which you can invoke easily. The file can include a YAML frontmatter header to configure how it runs[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=Prompt%20files%20are%20Markdown%20files,extension%20and%20have%20this%20structure). Here are the frontmatter fields for prompt files[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=): - -* **`description`** – A short description of what the prompt does. This is used as tooltip or help text in the UI. - -* **`mode`** – Which Copilot chat mode to execute the prompt in. Options: `"ask"`, `"edit"`, or `"agent"`. - - * **ask** \= default Q\&A chat mode, - - * **edit** \= the mode for modifying code, - - * **agent** \= the “agent” mode which can use tools. - If not specified, it defaults to the normal (currently selected) mode, which is typically “agent” for prompt files[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=,If%20not%20specified). - -* **`model`** – The AI model to use for this prompt. If omitted, it uses whatever model is currently selected by the user. You can specify something like `"gpt-4"`, `"GPT-4 Code Assist"`, `"Claude 2"`, etc., depending on what models are available in your environment[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=,in%20model%20picker%20is%20used). - -* **`tools`** – A list of tools or tool-set names that this prompt is allowed to use (only applicable if running in agent mode and if tools are available). For example, you might list `['terminal', 'browser', 'search']` to allow those tools during the prompt execution[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=,If). If a listed tool isn’t actually available, it will be ignored. (If not running in agent mode, tools list is ignored.) - -After the frontmatter, the **body of the `.prompt.md` file** is where you write the actual prompt instructions, in Markdown. This can be multiple paragraphs, include code blocks, etc. You can also reference other files or other prompt/instruction files by relative Markdown links to avoid duplication[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=Reference%20other%20workspace%20files%2C%20prompt,location%20of%20the%20prompt%20file). - -**Example prompt file with frontmatter:** - -`---` -`description: "Convert a code snippet into a well-documented function"` -`mode: "edit" # use edit mode (applies changes to code)` -`model: "GPT-4" # ensure a powerful model for better docs` -`tools: [] # (no external tools needed for this prompt)` -`---` -`# Convert to Documented Function` - -`Take the selected code and refactor it into a self-contained function with a clear name.` - -`- The new function should have a concise docstring explaining its purpose, inputs, and output.` -`- Add comments inside the function to explain complex logic, if any.` -`- **Do not** change the external behavior of the code.` - -`If the selected code is not a complete snippet (e.g., part of a larger expression), make an assumption to create a valid function.` - -In this example, the prompt file (say we named it `refactor.prompt.md`) can be invoked in VS Code by typing `/refactor` in the Copilot chat, or by running a command. It tells Copilot (in edit mode) to transform the selected code into a documented function. The YAML header ensures it uses the edit mode and GPT-4 model. - -**Notes and Best Practices:** - -* When writing the prompt (body), clearly state the task and any format you expect in the answer. The AI will follow these instructions when you run the prompt. - -* You can include **placeholders or variables** in prompt files. For instance, VS Code supports placeholders like `${selection}` (the currently selected text), `${file}` (current filename), or custom inputs like `${input:variableName}` where the user can supply additional data[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=Within%20a%20prompt%20file%2C%20you,can%20reference%20the%20following%20variables). In our example, we implicitly rely on the selected code (since it’s an edit mode prompt). - -* **Link to instructions or other prompts:** You can compose prompt files by linking to other instruction files or prompt files. For example, you might have a general style guide in an instructions file and within your prompt say “Follow our Python style guide” to automatically bring in those rules[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=Reference%20other%20workspace%20files%2C%20prompt,location%20of%20the%20prompt%20file). - -* Keep the `description` concise – think of it as tooltip text. It should summarize the prompt’s action (e.g., “Generate a release notes summary from commit messages”). - -* The `mode` field is important: use *ask* for things that don’t involve editing code (just Q\&A or explanation), *edit* for code transformations, and *agent* if the prompt might require using tools (like browsing documentation, running tests, etc.)[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=,If%20not%20specified). - -* Only list necessary `tools`. For instance, if your prompt needs to search the codebase or run a shell command, include those; otherwise leaving it empty (or omitting the field) is fine. Unnecessary tools can introduce side effects or extra context that might confuse the AI. - -## **GitHub Copilot – Custom Chat Modes (`.chatmode.md`)** - -**Custom chat modes** allow you to define an entirely new mode for Copilot Chat, with specialized behavior or purpose. Each mode is defined in a file with extension `.chatmode.md`. The structure is similar to prompt files: an optional YAML frontmatter header, followed by Markdown instructions in the body[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=Chat%20mode%20files%20are%20Markdown,extension%20and%20have%20this%20structure)[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=). - -**YAML frontmatter fields for chat modes**[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=)[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=,in%20model%20picker%20is%20used): - -* **`description`** – A brief description of the chat mode’s purpose. This is displayed as placeholder text in the chat input when the mode is active and as a tooltip when hovering over the mode in the mode selector[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=,in%20model%20picker%20is%20used). - -* **`tools`** – A list of tool names or predefined tool sets that are available in this mode[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=displayed%20as%20placeholder%20text%20in,and%20instructions%20in%20Markdown%20format). You might include built-in tools like `'terminal'`, `'browser'`, `'search'`, or any extension-contributed tools. (This works just like the `tools` field in prompt files, but here it defines tools for any prompt in this mode.) - -* **`model`** – The AI model to use when this mode is active. If not specified, it will use whichever model the user has currently selected by default[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=contributed%20by%20extensions,in%20model%20picker%20is%20used). You can set this if the mode is best suited to a particular model (e.g., a lightweight model for quick responses, or a specific one like `"Claude Instant 1"` or `"GPT-4"` if available). - -The body of the file contains the **detailed instructions or persona for that mode**. These instructions will be *prepended* or considered alongside the user’s inputs whenever this mode is used in chat. Essentially, this is where you set the behavior. For example, a “SQL Assistant” mode might have instructions like “You are an expert SQL assistant. Answer all questions with SQL examples when possible,” etc. You can include whatever guidance needed, including sections, lists, or Markdown formatting. - -You may also **reference other instruction or prompt files** in the mode’s body via Markdown links if you want to pull in shared rules (the content of those files will be included when the mode runs)[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=This%20is%20where%20you%20provide,when%20in%20this%20chat%20mode). - -**Example of a custom chat mode file:** - -`---` -`description: "Plan new features without writing any code (outputs an implementation plan)"` -`tools: ['search', 'codebase'] # allow searching the repository and codebase introspection` -`model: "GPT-4" # use a powerful model for thorough analysis` -`---` -`# Planning Mode` - -`You are in **Planning Mode**. Your job is to help plan out implementations for new feature requests or major refactors, without writing actual code.` - -`When the user asks a question or provides a feature description in this mode:` - `- Do **not** produce any source code.` - `- Instead, break the problem down into a series of steps, considerations, or tasks.` - `- Provide the output as a Markdown document with sections for "Overview", "Requirements", "Implementation Plan", and "Testing Strategy".` - -`Always ask for clarification if requirements are ambiguous. This mode is about high-level planning and clarification.` - -In this example, we set up a mode that helps with planning. We gave it a description (which would show up as placeholder text like “Plan new features without writing code…” in the chat input when selected). We limited tools to just `'search'` and `'codebase'` (so it can search the project, but not run terminal commands or web fetches, for instance). We also specified the model as GPT-4 for better quality. The body instructions clearly state the role and what the assistant should and shouldn’t do in this mode. - -**Using and creating chat modes:** - -* Chat mode files for a **workspace** are typically stored in `.github/chatmodes/` (you may need to create this folder). You can also keep personal modes in your user profile (outside of any repo)[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=2,mode%20file%20should%20be%20created). - -* Once a mode is created and the file is present, it will appear in the Copilot Chat interface as a selectable mode (alongside default modes like “Ask”, “Edit”, etc.). The `description` will show as ghost text in the input box, guiding the user on what that mode is for[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=). - -* Provide a clear **name** for the mode by the file name itself. For example, `planning.chatmode.md` will create a mode named “planning” (VS Code will use the file name as the mode name). - -* The YAML frontmatter is optional; if you omit, the mode will just use the current model and no special tool restrictions (which might be fine in some cases). However, providing at least a description is recommended for clarity. - -* **Tool configuration:** Only list tools that are needed for the mode’s purpose. For instance, a “Web Research” mode might enable a browser or web search tool, whereas a “Code Cleanup” mode might only need access to the codebase and perhaps a terminal to run linters. - -* **Testing:** After writing a mode’s instructions, test it by switching to that mode and prompting the assistant. Tweak the instructions as needed if the output isn’t as expected. For complex modes, sometimes breaking the instructions into bullet points (as in the example) helps the AI follow them systematically. - -## **Unified Multi-Agent Instructions – `AGENTS.md`** - -There is an emerging convention (sometimes called the “Agent Rules standard”) to use a file named **`AGENTS.md`** at the root of a project to provide guidelines that apply to *all* AI assistants/agents working on the repository[github.com](https://github.com/continuedev/continue/issues/6716#:~:text=The%20Agent%20Rules%20initiative%20proposes,continue%2Frules%2F%20system)[github.com](https://github.com/continuedev/continue/issues/6716#:~:text=,as%20natural%20language%20if%20none). Think of it as a central place to define coding conventions, architectural overviews, or any rules that any AI (whether GitHub Copilot, Claude, Gemini, or others) should follow when generating content for this repo. - -In the context of **GitHub Copilot in VS Code**, an `AGENTS.md` file (if enabled in settings) will automatically be pulled into context for **all Copilot chat requests**, regardless of mode[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#:~:text=If%20you%20work%20with%20multiple,chat%20requests%20within%20this%20workspace). This is useful if you work with multiple AI backends (GitHub’s model, OpenAI’s, Anthropic’s, etc.) so they all get the same project-specific instructions. - -**Format:** The `AGENTS.md` file is simply a Markdown file. Typically, it does **not require any YAML frontmatter** – you can just start with normal text or Markdown headings. For example, your `AGENTS.md` might contain: - -`# Project AI Guidelines` - -`- All code must follow the style guide in [CONTRIBUTING.md](CONTRIBUTING.md).` -`- Assume the user is familiar with the project’s domain; avoid explaining basic concepts.` -`- Prioritize security and privacy: do not output secrets or credentials, and mention security implications of code changes.` -`- Every generated function *must* have a docstring.` - -This would act as a set of universal instructions. Whenever Copilot (or other integrated agents) generate code or responses for this repository, they would ideally consider these guidelines. The **scope** of `AGENTS.md` is broad – by design it should hold rules that are generally applicable to any AI actions in the repo (akin to an `.editorconfig` but for AI). - -**Do’s and Don’ts:** - -* **Do include high-level or project-wide concerns**: e.g., “We use tabs, not spaces”, “No external library imports without approval”, “Follow OWASP security best practices”, etc. - -* **Don’t include extremely granular instructions** that might only apply in certain contexts – those might be better in the specific prompt or handled by an `.instructions.md` for that context. `AGENTS.md` should be relatively static and universal. - -* Typically, you don’t need `applyTo` patterns here, because it’s meant to always apply to everything (the tools or editors that support `AGENTS.md` treat it as global). Some tools or proposals allow YAML frontmatter in `AGENTS.md` to fine-tune applicability[github.com](https://github.com/continuedev/continue/issues/6716#:~:text=,as%20natural%20language%20if%20none), but generally you can omit it. The file is implicitly applied to all files/agents. - -* Keep it maintainable: since many AI tools now look for `AGENTS.md`, it’s a single source of truth. Update it as your practices evolve. If it gets too long, consider splitting certain parts into more targeted instruction files (and you can reference them from `AGENTS.md` if needed). - -**Note:** This concept is gaining traction to unify AI assistant behavior across different platforms. GitHub’s documentation notes that instead of multiple `.instructions.md` files, you can also use a single `AGENTS.md` (or model-specific files like `CLAUDE.md`, `GEMINI.md` as noted below) and the “nearest” such file up the directory tree will be used[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=,by%20AI%20agents). The goal is to avoid duplicating rules for each AI vendor. - -In summary, if you have a **mixed AI environment** or just want a one-stop config, `AGENTS.md` is the way to go. If you’re only using GitHub Copilot, `.github/copilot-instructions.md` plus selective instruction files might suffice, but there’s no harm in also having an `AGENTS.md` as a fallback for other tools (many third-party AI dev tools now check for this file). - -## **Anthropic Claude – Custom Instructions (`CLAUDE.md`)** - -Anthropic’s Claude (especially **Claude Code**, their coding assistant) allows project-specific customization via a file commonly named **`CLAUDE.md`**. This file serves a purpose similar to `AGENTS.md` but specifically for Claude. According to Anthropic, Claude will automatically look for a file named `CLAUDE.md` in your repository and load it as part of its system prompt (what Anthropic calls a “memory file”) every time you start a Claude session in that project[docs.claude.com](https://docs.claude.com/en/docs/claude-code/settings#:~:text=System%20prompt%20availability). - -**Format:** `CLAUDE.md` is a plain Markdown file. There is no required YAML frontmatter schema for it – you just fill it with any instructions or context you want Claude to always have. This could include things like coding style guidelines, a high-level overview of the project, important conventions, etc. Essentially, it’s a way to give Claude persistent knowledge or rules without having to repeat them in each prompt. - -For example, `CLAUDE.md` might contain: - -`# Claude Instructions for MyProject` - -`**Project Overview:** This is a web application for online book reviews. It uses a Python Flask backend and a React frontend.` - -`**Coding Style:** Follow PEP8 for Python code (use 4 spaces indentation, snake_case for functions). For JavaScript/React, follow Airbnb style guide.` - -`**Testing:** Whenever you write new code, include unit tests (PyTest for backend, Jest for frontend).` - -`**Do’s:**` -`- Be concise in explanations.` -`- Use docstrings in all public functions.` - -`**Don’ts:**` -`- Don’t disclose any API keys or secrets that might be in the code.` -`- Don’t make assumptions about user data; validate everything.` - -When you open Claude in the context of this repo, it will read that file and incorporate these points into its responses. This mechanism is powerful for shaping Claude’s behavior. - -**Tips:** - -* Think of `CLAUDE.md` as “setting the stage” for Claude. It’s loaded as part of Claude’s initial prompt. So it can contain a mix of factual info (project summary) and normative guidelines (style rules, etc.). - -* You can use Markdown formatting, but remember that it’s primarily for you – the formatting (bold, headings) might slightly influence Claude (it might assume bold means important), but mostly it’s to keep the file organized. - -* Keep it reasonably sized. Claude has context limits; a very large CLAUDE.md could consume a lot of tokens. Focus on the most important guidance. - -* If you have multiple Claude-specific files (though typically one is enough), Claude will by default load the one in the root. Anthropic’s tooling might also recognize `docs/claude.md` or similar, but **the standard is root-level `CLAUDE.md`**. - -**Note:** Claude also supports an **API for “sub-agents”** (discussed next) which use YAML frontmatter. But the top-level CLAUDE.md itself is straightforward Markdown. It’s essentially a special case of the more general `AGENTS.md` idea, dedicated just to Claude. GitHub’s Copilot integration notes that you can use a `CLAUDE.md` in combination with Copilot’s agent, presumably for when Copilot is backed by Claude or working alongside Claude[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=You%20can%20create%20one%20or,directory%20tree%20will%20take%20precedence). - -## **Anthropic Claude – Custom Sub-Agents (YAML Configuration)** - -Claude’s advanced **subagent** feature allows you to create multiple specialized AI “agents” under the main Claude agent. Each sub-agent is defined by a Markdown file with a YAML frontmatter header that Claude reads to configure that agent’s identity and permissions[docs.claude.com](https://docs.claude.com/en/docs/claude-code/settings#:~:text=Subagent%20configuration)[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=Subagents%20are%20defined%20as%20Markdown,or%20from%20your%20user%20scope). These are usually stored in a `.claude/agents/` directory (for project-specific agents) or `~/.claude/agents/` (for user-wide agents)[docs.claude.com](https://docs.claude.com/en/docs/claude-code/settings#:~:text=Claude%20Code%20supports%20custom%20AI,Markdown%20files%20with%20YAML%20frontmatter). - -A subagent file’s **YAML frontmatter** typically includes: - -* **`name`** – The name of the subagent. This is how you will invoke it (Claude can be prompted to delegate tasks to an agent by name)[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=,plus%20the%20system%20prompt). - -* **`description`** – A short description of what the subagent’s role or specialty is[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=,plus%20the%20system%20prompt). Claude may use this to decide when to auto-delegate tasks. It’s also useful documentation for you and your team. - -* **`tools`** – *(Optional)* A list of tools that this subagent is allowed to use[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=). Claude operates with a set of tools (like reading files, writing files, running shell commands, web search, etc.). By specifying `tools` here, you **whitelist** which ones the subagent can access. If you omit `tools`, the subagent inherits all the tools available to the main Claude session (which might be too permissive in some cases)[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=%60Use%20the%20implementer,presets). For tighter control, list only what it needs (e.g., maybe a “DatabaseAgent” only gets read/write database access, nothing else). - -After the frontmatter, the rest of the file is the **subagent’s prompt/instructions** – essentially a dedicated system prompt for that subagent. This is where you describe in detail how the subagent should behave, its step-by-step approach, or any domain knowledge it should have. - -**Example subagent file (`architect-review.md`):** - -`---` -`name: "architect-review"` -`description: "Architect Agent – validates designs against constraints and produces an architecture decision record."` -`tools: ["Read", "Search"] # e.g., can read files and search documentation, but not write code` -`---` -`You are the **Architect** sub-agent. Your goal is to review proposed software designs or feature specifications and ensure they meet the system's constraints and best practices.` - -`When activated, you will:` -``- Read the feature specification from the repository (`specs/` directory).`` -`- Analyze it for compliance with our scalability and security requirements.` -`- Output an **Architecture Decision Record (ADR)** with sections for Context, Decision, Rationale, and Consequences.` - -`You should not write any code. Focus only on architectural guidance. If the spec is unclear, list assumptions or ask for clarification.` - -In this file, the YAML header gives the subagent a name (“architect-review”), a description, and limits its tools. The body instructs it on exactly what to do when called. Claude’s main agent can be asked, *“Use the architect-review subagent on the new feature spec,”* and it will spin up this specialized agent with these instructions to perform that task[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=%2A%20Usage%3A%20Claude%20can%20auto,presets). - -**Key Points for Claude Subagents:** - -* Store project subagents in the repository under `.claude/agents/`. This makes them shareable with the team (and version controlled). User-level (global) agents go in `~/.claude/agents/` on your machine[docs.claude.com](https://docs.claude.com/en/docs/claude-code/settings#:~:text=Claude%20Code%20supports%20custom%20AI,Markdown%20files%20with%20YAML%20frontmatter). - -* The **filename** isn’t directly used as the name; it’s the `name:` in YAML that counts. However, by convention, you might name the file the same as the agent name for clarity. - -* The `description` should be action-oriented, because Claude can auto-select subagents based on descriptions. For instance, if the description says “writes unit tests”, Claude might automatically use that agent when a task is about testing. - -* If `tools` is not specified, the subagent can use any tool the main agent has, which might be fine for general-purpose agents. If you want to sandbox an agent, list only specific tools. For example, a “QA” agent might only need read access (to verify code) and perhaps run tests, but not write access. - -* You can define multiple subagents to form a pipeline. For example, one subagent could be “planner”, another “coder”, another “tester”, each with its own YAML config and instructions, and you orchestrate them (often using Claude’s **hooks** or by manual prompts)[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=%2A%20Reproducibility%3A%20Stop%20re,and%20hooks%20codify%20repeatable%20steps)[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=We%20started%20with%20a%20three,that%E2%80%99s%20generic%20to%20any%20stack). - -* **Best practices:** Give each subagent one clear responsibility (single responsibility principle)[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=1%29%20Single). Keep their instructions focused on that role. This makes the overall AI workflow more reliable and easier to troubleshoot. - -* **Security:** Use the `tools` limitation to prevent a subagent from doing things it shouldn’t. For instance, a planning agent probably doesn’t need the `Execute` (shell command) tool. And as noted in Anthropic’s docs, if you want to exclude access to certain files entirely, you’d configure that in Claude’s permissions (which is outside the scope of the YAML, done in `.claude/settings.json`)[docs.claude.com](https://docs.claude.com/en/docs/claude-code/settings#:~:text=,working%20directories%20that%20Claude%20has)[docs.claude.com](https://docs.claude.com/en/docs/claude-code/settings#:~:text=,to%20prevent%20%60bypassPermissions). - -In summary, Claude’s subagents use YAML frontmatter for **metadata and permissions** and Markdown body for the **agent’s persona/instructions**. It’s a powerful system to split tasks among “expert” agents. - -## **Google Gemini – Custom Instructions (`GEMINI.md`)** - -Google’s **Gemini** (an AI model from Google) is still relatively new on the scene for code assistance, and detailed public documentation on project-specific config is sparse. However, we can draw parallels from patterns established by others and hints from tools: - -GitHub’s Copilot documentation and community standards suggest that you can use a **`GEMINI.md`** file at the root of your repository to provide custom instructions when using a Gemini-based AI assistant[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=You%20can%20create%20one%20or,directory%20tree%20will%20take%20precedence). This is analogous to `CLAUDE.md` for Claude. For example, if an AI extension or tool uses Google’s Gemini model to assist with your code, it could check for `GEMINI.md` to preload instructions. - -Since specifics aren’t officially published, we’ll assume **`GEMINI.md` is treated like a free-form instructions file**, just like `CLAUDE.md`. That means likely no required YAML keys, just Markdown content (unless a specific tool layer adds its own frontmatter options). - -What might you put in a `GEMINI.md`? Probably similar content to CLAUDE.md or AGENTS.md: high-level guidelines, project overview, dos/don’ts for the AI. For example: - -`# Gemini Instructions for MyProject` - -`This project is a machine learning pipeline for image classification.` - -`- The codebase is primarily TensorFlow (Python) and some C++ for performance-critical components.` -`- **Style Guidelines:** Follow Google Python style guide. In C++ code, follow Google C++ style.` -`- **Important:** Do not use external packages that are not already in the requirements.txt.` -`- Focus on clarity and maintainability over cleverness.` - -`If asked to produce a solution, prefer simple implementations and add comments explaining any non-obvious steps.` - -If a Gemini-powered tool is being used, it would incorporate those notes. - -**Parameters for custom agents:** If in the future tools allow more structured config for Gemini, it would likely mirror the structure of subagents (name, description, etc.) if Gemini supports multiple specialized agents. There’s also mention that some CLI tools (Codex CLI, Aider, etc.) and potentially a “Gemini CLI” support the same **Agent Rules** standard (i.e., `AGENTS.md`)[github.com](https://github.com/continuedev/continue/issues/6716#:~:text=The%20Agent%20Rules%20initiative%20proposes,continue%2Frules%2F%20system). This means Gemini might already respect a unified format with YAML frontmatter if present. For now, though, a single `GEMINI.md` with plain text instructions is the safe bet. - -**Best Practices:** - -* Treat `GEMINI.md` much like `CLAUDE.md`: keep it concise and focused on things unique to your project or preferences. - -* Since Gemini is from Google and likely tuned with different data, be explicit about things like privacy or licensing constraints in your instructions (e.g., “Don’t suggest any solution that would violate our license terms” if relevant). - -* Update the file as the project evolves – if certain frameworks are deprecated or new conventions adopted, reflect that in the instructions. - -**Note:** If you’re not actively using any Gemini-based coding assistant, you don’t need a GEMINI.md yet. But some teams include it preemptively as part of adopting the `AGENTS.md` convention, in case collaborators use different AI tools. It doesn’t harm anything to have it there. In the future, we expect more concrete schemas or tools for Gemini; until then, stick to the general guidance approach. - ---- - -**Summary:** The table below recaps the **YAML frontmatter fields** discussed for each file type: - -* **Issue Template (YAML form)** – `name`, `description` (or `about`), `title`, `labels`, `assignees`, `projects`, `type`, and a structured `body` with `type`, `id`, `attributes`, and `validations` for each input[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,repository%2C%20it%20will%20not%20be)[docs.github.com](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#:~:text=,using%20this%20template%20to%20have). - -* **PR Template** – *(same fields as issue template, but not currently parsed by GitHub)*[stackoverflow.com](https://stackoverflow.com/questions/66392676/github-pull-request-template-detect-yaml-front-matter-using-config-yml-and-apply#:~:text=,request%20assignees%3A%20self). - -* **Saved Reply** – *no YAML (title & body managed via UI)*. - -* **Copilot Repo Instructions** – *no YAML needed (just markdown content in* `.github/copilot-instructions.md`*)*. - -* **Copilot Path Instructions** – `applyTo` (pattern) and optional `description` in frontmatter[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=3,directories%20the%20instructions%20apply%20to)[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-instructions#:~:text=,Body%3A%20Instructions%20in%20Markdown%20format); body is markdown instructions. - -* **Copilot Prompt File** – `description`, `mode` (`ask|edit|agent`), `model`, `tools` in frontmatter[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/prompt-files#:~:text=); body is the prompt text. - -* **Copilot Chat Mode** – `description`, `tools`, `model` in frontmatter[code.visualstudio.com](https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes#:~:text=,in%20model%20picker%20is%20used); body is mode-specific instructions. - -* **AGENTS.md** – *generally no fixed fields; global instructions for all AIs (some tools may parse frontmatter if included, but typically just markdown content)*. - -* **Claude CLAUDE.md** – *no fixed fields; markdown instructions for Claude*[docs.claude.com](https://docs.claude.com/en/docs/claude-code/settings#:~:text=System%20prompt%20availability). - -* **Claude Subagent** – `name`, `description`, `tools` (optional) in frontmatter[pubnub.com](https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/#:~:text=,plus%20the%20system%20prompt); body is that agent’s system prompt. - -* **Gemini GEMINI.md** – *no known fixed schema; markdown instructions (analogous to CLAUDE.md)*[docs.github.com](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#:~:text=You%20can%20create%20one%20or,directory%20tree%20will%20take%20precedence). - -By using the above configurations, you can customize issue and PR workflows on GitHub, as well as tailor AI assistants (like Copilot, Claude, and eventually Gemini) to better suit your project’s needs. Each file has a specific role – from guiding human contributors (templates) to guiding AI behavior (instructions and prompts). Use them in combination for the best effect (for instance, an issue template can gather structured data from a user, and your Copilot instructions can remind the AI to utilize that data when generating code or responses). - diff --git a/YAML Frontmatter Schemas for GitHub, Copilot, Claude, and Gemini Files1.md b/YAML Frontmatter Schemas for GitHub, Copilot, Claude, and Gemini Files1.md deleted file mode 100644 index d732a97..0000000 --- a/YAML Frontmatter Schemas for GitHub, Copilot, Claude, and Gemini Files1.md +++ /dev/null @@ -1,30 +0,0 @@ -# **YAML Frontmatter Schemas for GitHub, Copilot, Claude, and Gemini Files** - -comprehensive breakdown of YAML frontmatter schemas for the following file types: - -* GitHub issue and PR templates - -* GitHub saved replies - -* GitHub Copilot: custom instructions, prompt files, `AGENTS.md`, and `.chatmode.md` - -* Claude agents (Anthropic YAML-based config) - -* Gemini agents (Google) - -For each, I’ll include: - -* Maximum parameter set and required vs optional fields - -* Example YAML frontmatter blocks - -* Best practices and caveats - -* Placeholder documentation next to each field - -* Recommended folder/filename conventions - -* YAML schema examples where available or inferred - -I’ll also reference the two zips you provided (`awesome-copilot-main` and the awesome-chat examples) and cross-check with the official docs. - diff --git a/YAML-Frontmatter-Copilot-Space-Instructions.md b/YAML-Frontmatter-Copilot-Space-Instructions.md deleted file mode 100644 index a3ace17..0000000 --- a/YAML-Frontmatter-Copilot-Space-Instructions.md +++ /dev/null @@ -1,628 +0,0 @@ -# **Copilot Space Instructions v1** - -# **Build a "Copilot Space" with instructions for all frontmatter file types** - -Create directories: - -* .devcontainer -* .copilot -* .github -* .github/agents -* .github/chatmodes -* .github/instructions -* .github/prompts -* .github/ISSUE\_TEMPLATES -* .github/PULL\_REQUEST\_TEMPLATES -* .github/workflows -* .vscode -* docs/copilot-space -* docs/copilot-space/schemas - -# **Top-level README guiding to Copilot Space** - -readme \= """\# Copilot Space — Frontmatter & Agent Config Guide - -This repository contains a **Copilot Space**: a self-contained set of docs, prompts, and chat modes that teach GitHub Copilot (and other agents) how to use **YAML frontmatter** across common file types. - -**Start here:** `docs/copilot-space/INDEX.md` - -Contents: - -- Cheat sheets & examples for Issue/PR templates, Copilot instructions, prompt files, chat modes. -- Claude subagents, AGENTS.md, CLAUDE.md, GEMINI.md conventions. -- Ready-to-use Copilot prompt and chat mode for on-demand assistance. """ - -index\_md \= """\# Copilot Space Index — YAML Frontmatter Playbook - -Use the links below for targeted guidance and copy-pasteable examples. - -## **GitHub Templates** - -- [Issue Templates (Issue Forms)](http://issue-templates.md) -- [Pull Request Templates](http://pr-templates.md) -- [Saved Replies (no frontmatter)](http://saved-replies.md) - -## **Copilot Customisation** - -- [Repo & Path Instructions (`copilot-instructions.md`, `*.instructions.md`)](http://copilot-instructions.md) -- [Reusable Prompt Files (`*.prompt.md`)](http://prompt-files.md) -- [Custom Chat Modes (`*.chatmode.md`)](http://chatmodes.md) -- [AGENTS.md (universal rules)](http://agents-md.md) - -## **Claude & Gemini** - -- [Claude: `CLAUDE.md` & Subagents (`.github/agents/*.md`)](http://claude-agents.md) -- [Gemini: `GEMINI.md` (conventions)](http://gemini-md.md) - -## **Schemas (reference)** - -- [Issue Form YAML keys](http://schemas/issue-form-schema.md) -- [Copilot Prompt frontmatter](http://schemas/prompt-frontmatter-schema.md) -- [Chat Mode frontmatter](http://schemas/chatmode-frontmatter-schema.md) -- [Claude Subagent frontmatter](http://schemas/claude-subagent-schema.md) """ - -issue\_templates\_md \= """\# Issue Templates (Issue Forms) — YAML Frontmatter - -**Location:** `.github/ISSUE_TEMPLATE/*.yml` - -**Required top-level keys:** - -- `name` *(string)* — Template name (shown in picker). -- `description` *(string)* — What this template is for. -- `body` *(array)* — Form blocks (markdown/input/textarea/dropdown/checkboxes). - -**Optional top-level keys:** `title`, `labels`, `assignees`, `projects`, `type`. - -### **Full Example** - -name: "🐛 Bug report" \# required - -description: "Report a bug to help us improve" \# required - -title: "\[Bug\]: " \# optional default issue title - -labels: \["bug","needs-triage"\] \# optional auto labels - -assignees: \[\] \# optional auto assignees - -projects: \["my-org/42"\] \# optional projects - -type: bug \# optional issue type - -body: - - \- type: markdown - - attributes: - - value: | - - \#\# Thanks for reporting\! - - Please provide enough detail to reproduce the issue. - - \- type: input - - id: version - - attributes: - - label: "Version" - - description: "Which version/commit?" - - placeholder: "v1.2.3 or SHA" - - validations: - - required: true - - \- type: textarea - - id: repro - - attributes: - - label: "Steps to reproduce" - - placeholder: | - - 1\. Go to '...' - - 2\. Click '...' - - 3\. See error - - validations: - - required: true - - \- type: dropdown - - id: env - - attributes: - - label: "Environment" - - options: \["macOS","Windows","Linux","Other"\] - - multiple: true - - validations: - - required: true - - \- type: checkboxes - - id: checks - - attributes: - - label: "Checks" - - options: - - \- label: "I searched for duplicates" - - required: true - - \- label: "I can reproduce with latest" - -**Do** - -* Use `|` for multiline text blocks. - -* Quote strings that include `#` or `:`. - -* Require only fields that truly block triage. - -**Don’t** - -* Overload forms with unnecessary inputs. - -* Use PR-style frontmatter here. - """ - -pr\_templates\_md \= """\# Pull Request Templates - -**Location:** `.github/PULL_REQUEST_TEMPLATE/*.md` (Markdown) - -PR templates **do not** support form-style YAML frontmatter. Keep the template in Markdown with headings and HTML comments for guidance. - -### **Example** - -Always show details -`## Summary` -`` - -`## Related Issues` -`Closes #123` - -`## Changes` -`- [ ] Code` -`- [ ] Tests` -`- [ ] Docs` - -`## Screenshots` -`` - -`## Checklist` -`- [ ] Read CONTRIBUTING` -`- [ ] Ran tests` -`- [ ] Followed style guides` - -""" - -saved\_replies\_md \= """\# Saved Replies (GitHub UI) - -Saved replies are managed in **GitHub Settings** (Profile → Saved replies). - They have a **title** and **body**; there is **no file-based frontmatter**. - -**Tip:** Keep replies short and customise after insertion. - """ - -copilot\_instructions\_doc \= """\# Copilot Custom Instructions - -## **Repository-wide** - -**File:** `.github/copilot-instructions.md` - Plain Markdown. No YAML required. - -Use this file for always-on guidance (style, patterns, security notes). - -## **Path-specific** - -**Folder:** `.github/instructions/` - **File pattern:** `*.instructions.md` with YAML frontmatter. - -Always show details -`---` -`applyTo: "src/**/*.{js,ts,tsx}" # glob(s) for files this applies to` -`description: "Frontend coding rules" # optional tooltip/label` -`---` -`# Frontend Guidelines` -`- Prefer functional components and hooks` -`- Add tests for new components` - -**Tips** - -* Combine globs with commas: `applyTo: "src/**/*.ts,tests/**/*.ts"` - -* Keep rules concise; whitespace is ignored by Copilot. - """ - -prompt\_files\_doc \= """\# Copilot Reusable Prompts (`*.prompt.md`) - -**Folder:** `.github/prompts/` - -**Frontmatter keys:** - -* `description` — tooltip text for the prompt. - -* `mode` — `"ask" | "edit" | "agent"`. - -* `model` — model name (else use current). - -* `tools` — allowed tools (agent mode). - -### **Example** - -Always show details -`---` -`description: "Refactor selected code into a documented function"` -`mode: "edit"` -`model: "GPT-4"` -`tools: []` -`---` -`# Refactor to Function` -`Convert the selected code into a self-contained function:` -`- Add docstring` -`- Preserve behaviour` - -**Do** reference shared guides via Markdown links to avoid duplication. - """ - -chatmodes\_doc \= """\# Custom Chat Modes (`*.chatmode.md`) - -**Folder:** `.github/chatmodes/` - -**Frontmatter keys:** - -* `description` — placeholder text & hover text. - -* `tools` — available tools. - -* `model` — model to pin (optional). - -### **Example** - -Always show details -`---` -`description: "Plan features without writing code; output an implementation plan."` -`tools: ["search","codebase"]` -`model: "GPT-4"` -`---` -`# Planning Mode` -`- No source code in answers` -`- Provide: Overview, Requirements, Plan, Risks, Tests` - -**Tip:** Name the file to reflect the mode: `planning.chatmode.md` → mode **Planning**. - """ - -agents\_md\_doc \= """\# AGENTS.md (Universal Rules) - -**File:** `AGENTS.md` at repo root. - A vendor-neutral rulebook applied by many AI tools. - -**Content ideas** - -* Security & privacy (no secrets) - -* Style & testing expectations - -* Architectural patterns to follow/avoid - -* License and dependency policies - """ - -claude\_agents\_doc \= """\# Claude — `CLAUDE.md` & Subagents - -## **`CLAUDE.md`** - -Root-level Markdown file with persistent project instructions for Claude. No frontmatter needed. - -## **Subagents** - -**Folder:** `.github/agents/` - Each subagent is a Markdown file with YAML frontmatter: - -Always show details -`---` -`name: "architect-review" # how Claude refers to this agent` -`description: "Reviews designs and produces an ADR"` -`tools: ["Read","Search"] # limit tool access (optional)` -`---` -`# Architect Review Agent` -`Your task is to review specs and output an ADR (Context, Decision, Rationale, Consequences).` - -**Tips** - -* Single responsibility per subagent - -* Restrict tools to the minimum set - -* Keep the body focused and actionable - """ - -gemini\_doc \= """\# Gemini — `GEMINI.md` (Convention) - -**File:** `GEMINI.md` at repo root (conventional). - Use as a persistent instruction file for Gemini-based tools. - -**Suggested content** - -* Tech stack and constraints - -* Style & testing expectations - -* Privacy and security notes - """ - -# **Schemas (concise)** - -issue\_schema \= """\# Issue Form — Frontmatter Keys - -Always show details -`name: string # required` -`description: string # required` -`title: string # optional` -`labels: [string] | string # optional` -`assignees: [string] | string # optional` -`projects: [string] # optional (OWNER/NUMBER)` -`type: string # optional` -`body: # required` - `- type: markdown|input|textarea|dropdown|checkboxes` - `id: string # optional` - `attributes:` - `label: string # required (except markdown)` - `description: string # optional` - `placeholder: string # optional` - `value: string # optional` - `options: [string] # required for dropdown/checkboxes` - `multiple: boolean # dropdown only` - `render: string # textarea (e.g., bash, markdown)` - `validations:` - `required: boolean` - -""" - -prompt\_schema \= """\# Prompt File — Frontmatter Keys - -Always show details -`description: string # tooltip` -`mode: ask|edit|agent # defaults to current` -`model: string # optional` -`tools: [string] # agent-only` - -""" - -chatmode\_schema \= """\# Chat Mode — Frontmatter Keys - -Always show details -`description: string # placeholder & tooltip` -`tools: [string] # optional tool allowlist` -`model: string # optional pinned model` - -""" - -claude\_subagent\_schema \= """\# Claude Subagent — Frontmatter Keys - -Always show details -`name: string # subagent handle` -`description: string # purpose / when to use` -`tools: [string] # optional tool allowlist` - -""" - -# **Copilot prompt to pull the guide content on demand** - -## **frontmatter\_prompt \= """---** - -## **description: "Frontmatter Guide: answer using docs in docs/copilot-space/\*"** - -## **mode: "ask"** - -## **model: ""** - -## **tools: \[\]** - -# **Frontmatter Guide Prompt** - -When asked about YAML frontmatter or AI agent config: - -* Consult the repository docs under `docs/copilot-space/`. - -* Provide short, actionable answers with code blocks. - -* Link to the exact doc path you used. - """ - -# **Chat mode to anchor behaviour** - -## **frontmatter\_chatmode \= """---** - -## **description: "Frontmatter mode: quick answers \+ examples from docs/copilot-space"** - -## **tools: \["codebase"\]** - -## **model: ""** - -# **Frontmatter Chat Mode** - -You specialise in YAML frontmatter and AI agent configuration for GitHub repos. - Use examples from `docs/copilot-space/` and keep responses concise for developers. - """ - -# **Instruction file to bias markdown authoring** - -## **frontmatter\_instructions \= """---** - -## **applyTo: "\*\*/\*.md"** - -## **description: "Authoring guidance for frontmatter docs"** - -# **Authoring Guidance** - -* Prefer concise explanations next to examples. - -* Use fenced code blocks with language identifiers. - -* Include Do/Don’t lists where useful. - """ - -# **Agent example for this space** - -## **space\_agent \= """---** - -## **name: "frontmatter-librarian"** - -## **description: "Finds and cites the correct frontmatter pattern from docs/copilot-space"** - -## **tools: \["Read","Search"\]** - -# **Frontmatter Librarian Agent** - -* When queried, scan `docs/copilot-space/` for the most relevant example. - -* Return the example with a one-paragraph explanation and a short Do/Don’t list. - """ - -# **Write files** - -files \= { - "README.md": readme, - "docs/copilot-space/INDEX.md": index\_md, - "docs/copilot-space/issue-templates.md": issue\_templates\_md, - "docs/copilot-space/pr-templates.md": pr\_templates\_md, - "docs/copilot-space/saved-replies.md": saved\_replies\_md, - "docs/copilot-space/copilot-instructions.md": copilot\_instructions\_doc, - "docs/copilot-space/prompt-files.md": prompt\_files\_doc, - "docs/copilot-space/chatmodes.md": chatmodes\_doc, - "docs/copilot-space/agents-md.md": agents\_md\_doc, - "docs/copilot-space/claude-agents.md": claude\_agents\_doc, - "docs/copilot-space/gemini-md.md": gemini\_doc, - "docs/copilot-space/schemas/issue-form-schema.md": issue\_schema, - "docs/copilot-space/schemas/prompt-frontmatter-schema.md": prompt\_schema, - "docs/copilot-space/schemas/chatmode-frontmatter-schema.md": chatmode\_schema, - "docs/copilot-space/schemas/claude-subagent-schema.md": claude\_subagent\_schema, - ".github/prompts/frontmatter-guide.prompt.md": frontmatter\_prompt, - ".github/chatmodes/frontmatter.chatmode.md": frontmatter\_chatmode, - ".github/instructions/frontmatter.instructions.md": frontmatter\_instructions, - ".github/agents/frontmatter-librarian.md": space\_agent, - } - -for rel, content in files.items(): - p \= os.path.join(root, rel) - os.makedirs(os.path.dirname(p), exist\_ok=True) - with open(p, "w", encoding="utf-8", newline="\\n") as f: - f.write(content) - -# **Optional VS Code settings to highlight markdown and enable word wrap** - -vscode\_settings \= { - "editor.wordWrap": "on", - "editor.defaultFormatter": "esbenp.prettier-vscode", - "\[markdown\]": { - "editor.wordWrap": "on" - } - } - with open(os.path.join(root, ".vscode/settings.json"), "w", encoding="utf-8") as f: - json.dump(vscode\_settings, f, indent=2) - -# **Zip it** - -zip\_path \= "/mnt/data/copilot-space-frontmatter.zip" - with zipfile.ZipFile(zip\_path, "w", zipfile.ZIP\_DEFLATED) as z: - for base, \_, files\_in in os.walk(root): - for name in files\_in: - full \= os.path.join(base, name) - rel \= os.path.relpath(full, root) - z.write(full, arcname=os.path.join("copilot-space", rel)) - -zip\_path - -Always show details - -Alright Ash — I’ve generated a **Copilot Space** that teaches how to use every front-matter file you asked about, with docs, examples, schemas, and ready-to-run Copilot prompt/chat mode. - -Download the Copilot Space - -## **What’s inside** - -* **docs/copilot-space/** - - * **INDEX.md** → single place to start; links to everything. - - * **issue-templates.md** → YAML Issue Forms: required/optional keys \+ full example. - - * **pr-templates.md** → PR templates (Markdown-only, no YAML forms) \+ best practice template. - - * **saved-replies.md** → explains they’re UI-managed (no frontmatter). - - * **copilot-instructions.md** → repo-wide vs path-specific instructions, `applyTo` patterns. - - * **prompt-files.md** → `.prompt.md` frontmatter (`description`, `mode`, `model`, `tools`) \+ example. - - * **chatmodes.md** → `.chatmode.md` frontmatter \+ example “Planning Mode”. - - * **agents-md.md** → how to use `AGENTS.md` as universal rules. - - * **claude-agents.md** → `CLAUDE.md` \+ **Claude subagents** YAML (`name`, `description`, `tools`) \+ example. - - * **gemini-md.md** → `GEMINI.md` convention and what to include. - - * **schemas/** (quick reference) - - * **issue-form-schema.md**, **prompt-frontmatter-schema.md**, **chatmode-frontmatter-schema.md**, **claude-subagent-schema.md**. - -* **.github/** - - * **instructions/** - - * **frontmatter.instructions.md** → applies to all `*.md` (authoring guidance). - - * **prompts/** - - * **frontmatter-guide.prompt.md** → quick “Frontmatter Guide” prompt that tells Copilot to answer using the docs in `docs/copilot-space/`. - - * **chatmodes/** - - * **frontmatter.chatmode.md** → dedicated chat mode: fast answers \+ examples from this space. - - * **agents/** - - * **frontmatter-librarian.md** → Claude-style subagent with `name/description/tools`; it fetches the right example and returns a short Do/Don’t list. - -* **.vscode/settings.json** → basic markdown-friendly editor defaults (wrap on). - -## **How to use it** - -1. **Drop the folder into any repo** (or create a new one) and commit. - -2. Open Copilot Chat in VS Code: - - * Select **Frontmatter** from the chat mode dropdown (from `.github/chatmodes/frontmatter.chatmode.md`), **or** - - * Run the **Frontmatter Guide** prompt (`/frontmatter-guide`) to answer questions using the docs. - -3. Edit the examples to match your stack (WordPress/JS/TS/etc.). The Issue Forms and prompt/chat mode samples are ready to copy-paste. - -4. If you also use Claude/Gemini: - - * Add/trim **`AGENTS.md`**, **`CLAUDE.md`**, **`GEMINI.md`** at the repo root (or keep them in your main repo and link back here). - - * Define any project subagents in `.github/agents/`. - -Want me to merge this into the previous repo template I made for you so you’ve got a single combined starter? - diff --git a/block-themes/_temp.txt b/block-themes/_temp.txt deleted file mode 100644 index cc195cf..0000000 --- a/block-themes/_temp.txt +++ /dev/null @@ -1,348 +0,0 @@ -# Standardising Colours, Spacing, and Typography in Block Themes - -A predictable, token-based system for **colours, spacing, and typography** helps ensure consistency across design, WordPress editor UI, and front-end rendering. WordPress provides **default presets**, which can be enabled, overridden, or extended to match your design system. - ---- - -## WordPress Default Font Size Slugs -WordPress ships with four core font sizes: - -- `small` -- `medium` -- `large` -- `x-large` - -## WordPress Default Spacing Slugs -The default spacing scale is numeric and increments by 10: - -- `spacing-10` -- `spacing-20` -- `spacing-30` -- `spacing-40` -- `spacing-50` -- `spacing-60` - -(These correspond to approximate values from `0.125rem` to `3rem`, though values may vary by theme implementation.) - -### Extended Spacing Scale - -We extend this with additional slugs to cover larger gaps, while **keeping naming consistent**: - -- `spacing-70` → `3.5rem` (56px) -- `spacing-80` → `4rem` (64px) -- `spacing-90` → `4.5rem` (72px) -- `spacing-100` → `5rem` (80px) - -## Extended Spacing Scale - -We extend this with additional slugs to cover larger gaps, while **keeping naming consistent**: - -- `spacing-70` → `3.5rem` (56px) -- `spacing-80` → `4rem` (64px) -- `spacing-90` → `4.5rem` (72px) -- `spacing-100` → `5rem` (80px) - ---- - -### Example JSON - -```json -"spacing": { - "spacingScale": { - "steps": [ - { "slug": "spacing-10", "size": "0.625rem", "name": "10px" }, - { "slug": "spacing-20", "size": "1.25rem", "name": "20px" }, - { "slug": "spacing-30", "size": "1.875rem", "name": "30px" }, - { "slug": "spacing-40", "size": "2.5rem", "name": "40px" }, - { "slug": "spacing-50", "size": "3.125rem", "name": "50px" }, - { "slug": "spacing-60", "size": "3.75rem", "name": "60px" }, - { "slug": "spacing-70", "size": "3.5rem", "name": "56px" }, - { "slug": "spacing-80", "size": "4rem", "name": "64px" }, - { "slug": "spacing-90", "size": "4.5rem", "name": "72px" }, - { "slug": "spacing-100", "size": "5rem", "name": "80px" } - ] - } -} -``` - ---- - -## Extending with Custom Tokens - -You can extend the defaults with **semantic tokens** (e.g. `brand-primary`, `gigantic`) while **keeping WP defaults enabled** for editor familiarity. - -Best practice: -- **Keep slugs stable** (so editor UI remains predictable). -- **Override values** (so the design system reflects your scale). -- **Add extra sizes only where needed** (to avoid clutter). - ---- - -## Example `theme.json` Partial - -This example uses: - -- **Colour tokens**: semantic naming (`brand-primary`, `neutral-100`). -- **Spacing scale**: multiples of 8px → `0.5rem`, `1rem`, `2rem`, etc. -- **Typography scale**: includes extra sizes (`x-tiny`, `tiny`, `huge`, `gigantic`) also based on multiples of 8px. - -```json -{ - "$schema": "https://schemas.wp.org/trunk/theme.json", - "version": 3, - "settings": { - "color": { - "palette": [ - { "slug": "brand-primary", "name": "Brand Primary", "color": "#0047AB" }, - { "slug": "brand-secondary", "name": "Brand Secondary", "color": "#FF6F00" }, - { "slug": "neutral-100", "name": "Neutral 100", "color": "#F5F5F5" }, - { "slug": "neutral-900", "name": "Neutral 900", "color": "#111111" } - ] - }, - "spacing": { - "spacingScale": { - "steps": [ - { "slug": "spacing-8", "size": "0.5rem", "name": "8px" }, - { "slug": "spacing-16", "size": "1rem", "name": "16px" }, - { "slug": "spacing-24", "size": "1.5rem", "name": "24px" }, - { "slug": "spacing-32", "size": "2rem", "name": "32px" }, - { "slug": "spacing-40", "size": "2.5rem", "name": "40px" }, - { "slug": "spacing-48", "size": "3rem", "name": "48px" }, - { "slug": "spacing-64", "size": "4rem", "name": "64px" }, - { "slug": "spacing-80", "size": "5rem", "name": "80px" } - ] - } - }, - "typography": { - "fontSizes": [ - { "slug": "x-tiny", "size": "0.5rem", "name": "X-Tiny (8px)" }, - { "slug": "tiny", "size": "0.75rem", "name": "Tiny (12px)" }, - { "slug": "small", "size": "0.875rem", "name": "Small (14px)" }, - { "slug": "medium", "size": "1rem", "name": "Medium (16px)" }, - { "slug": "large", "size": "1.25rem", "name": "Large (20px)" }, - { "slug": "x-large", "size": "1.5rem", "name": "X-Large (24px)" }, - { "slug": "huge", "size": "2rem", "name": "Huge (32px)" }, - { "slug": "gigantic", "size": "3rem", "name": "Gigantic (48px)" } - ] - } - } -} - - ---- - -````markdown -# Global Styles and theme.json - -Describes how to use `theme.json` for global styles, design tokens, and editor/front-end parity in block themes. - ---- - -## Best practices - -- Use `theme.json` as the single source of truth for **site-wide styles** and editor/front-end consistency. -- Treat it as a **design system definition file** (colours, typography, spacing, layout, etc.). -- Define **design tokens** in `settings` (e.g., font sizes, spacing presets, custom line-heights). -- Use `styles` to apply global defaults, ensuring authors see the same result in both the Site Editor and front end. -- Leverage `style variations` within `theme.json` to offer alternate themes/skins without extra CSS files. -- Combine with **patterns** and **style variations** for modular theme composition. - -Example: adding custom line-height tokens - -```json -{ - "settings": { - "custom": { - "lineHeight": { "sm": 1.625, "md": 1.6875, "lg": 1.5 } - } - } -} -```` - ---- - -## When to use - - ---- - -## Limitations - - ---- - -## Key lessons from Rich Tabor’s “Full Site Editing” - - ---- - -## Reference Links - - - -``` - ---- - -Ash, do you want me to **split this into smaller `.md` docs** (e.g. `best-practices.md`, `limitations.md`, `when-to-use.md`) for modular GitHub documentation, or keep everything bundled in `global-styles.md`? -``` - - -### Want me to scaffold the `.md` files now with these seeds and drop in your `/styles/block/section-1…9.json` as examples? - -[1]: https://developer.wordpress.org/news/2024/06/21/styling-sections-nested-elements-and-more-with-block-style-variations-in-wordpress-6-6/ "Styling sections, nested elements, and more with Block Style Variations in WordPress 6.6 – WordPress Developer Blog" -[2]: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/?utm_source=chatgpt.com "Styles – Block Editor Handbook | Developer.WordPress.org" -[3]: -[4]: - - -Here’s a concise, structured roundup of Rich Tabor’s articles relevant to block‑theme development and `theme.json`. I’ve extracted insights on the key areas you flagged: block styles, style variations, palettes, typesets, section styles, global styles, and patterns. - ---- - -## Rich Tabor’s Theme.Log Articles — At a Glance - ---- - -### **Using a fluid type scale in block themes** - -* Explains applying a **fluid typographic scale** using CSS `clamp()` combined with a scale stored in `settings.custom.typography.scale` in `theme.json`. -* Proposes creating **custom CSS variables** (e.g., `--wp--custom--typography--large`) and using `clamp()` in `settings.typography.fontSizes` to build fluid yet scaled typography. - ([Rich Tabor][1]) - -**Relevance:** - -* This is gold for **fluid typography** guidelines and for mapping Figma → theme.json with token-based, responsive sizing. - ---- - -### **Standardizing theme.json spacing sizes** - -* Introduces `settings.spacing.spacingScale` (operator, increment, steps, unit) to automate systematic spacing presets. -* Alternatively, suggests `settings.spacing.spacingSizes` with explicit custom sizes (slugs, names, fluid expressions). -* Mentions future support for `styles.spacing.blockGap` to style gaps between child blocks. - ([Rich Tabor][2]) - -**Relevance:** - -* Crucial for your **fluid spacing** documentation and consistent preset usage in section styles. - ---- - -### **Standardizing theme.json font sizes** - -* Proposes using consistent slugs like `small`, `medium`, `large`, `x-large`, each with optional `fluid` min/max properties, plus `size` fallback. -* Illustrates how theme.json resolves into CSS variables (e.g., `--wp--preset--font-size--small`). -* Warns that inconsistent slugs produce broken layouts when switching themes. - ([Rich Tabor][1], [Rich Tabor][3]) - -**Relevance:** - -* Forms the basis for your **fluid typography recommendations** and emphasizes standardization across themes. - ---- - -### **Standardizing theme.json color slugs** - -* Recommends core color slugs: `base`, `contrast`, and at least `primary`. -* Shows how slug mismatch between themes breaks styles when switching themes. -* Encourages neutral, functional slug names rather than descriptive color names (e.g. `green`). - ([Rich Tabor][4]) - -**Relevance:** - -* Vital input for the **colour palettes** and **style variations** sections of your documentation, promoting interoperability. - ---- - -### **How to build WordPress patterns** - -* Walks through designing block patterns: copying content, registering with `register_block_pattern()`, including title, description, block content, categories, keywords, viewportWidth, `blockTypes`. -* Notes patterns are copied once inserted; changes to source don’t propagate. - ([Rich Tabor][3], [Rich Tabor][5]) - -**Relevance:** - -* Essential for your **Patterns** documentation: building, registering, and pattern vs style differences. - ---- - -### **Building WordPress block variations** - -* Clarifies **block variations** (configuration–changing variants shown when inserting blocks) are different from **block style variations**. -* Provides example of registering a variation (`wp.blocks.registerBlockVariation`) for a form block, with `innerBlocks`, name, title, icon, etc. - ([Rich Tabor][6]) - -**Relevance:** - -* Great for your **style variations** vs **block variations** section—clarifies distinctions. - ---- - -### **A primer on WordPress full site editing** - -* Defines block‑based themes: `theme.json` + block templates/parts, minimal PHP. -* Demonstrates how FSE uses `theme.json` to drive styles across editor and front‑end. - ([Rich Tabor][7]) - -**Relevance:** - -* Supports **global styles** framing and context for block‑theme direction. - ---- - -### **WordPress 6.6** - -* Highlights key enhancements: **colour palettes**, **typesets**, **block style variations** (i.e. section styles), reduced CSS specificity, responsive features like negative margins, Grid block, shadow presets, full‑site enhancements. - ([Rich Tabor][3], [Rich Tabor][8]) - -**Relevance:** - -* This ties directly into your **section styles**, **global styles**, and infrastructure expectations (like low specificity). - ---- - -## Summary Table - -| Topic | Key Contributions from Tabor’s Articles | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| **Fluid typography** | `clamp()` + scale via custom props; `theme.json` fontSizes with fluid presets ([Rich Tabor][1]) | -| **Fluid spacing** | `spacingScale` or `spacingSizes`, blockGap support ([Rich Tabor][9]) | -| **Typography standardization** | Common font-size slugs + fluid ranges, avoid slug inconsistencies ([Rich Tabor][10]) | -| **Colour standardization** | `base`, `contrast`, `primary` slugs for cross-theme portability ([Rich Tabor][11]) | -| **Patterns** | Building and registering block patterns; patterns vs style reuse ([Rich Tabor][12]) | -| **Block variations** | Clarifies API & usage differ from style variations ([Rich Tabor][13]) | -| **Full Site Editing / theme.json** | Context for block-based themes and `theme.json` roles ([Rich Tabor][14]) | -| **WordPress 6.6 features** | Introduced section styles, reduced specificity, typesets, palettes, block style variations ([Rich Tabor][15]) | - ---- - -## What’s Next? - -Would you like me to slot these insights into the `.md` docs hierarchy? For example: - -* `fluid-spacing.md` → reference `spacingScale` article -* `fluid-typography.md` → link to fluid type scale + standard font sizes -* `colour-palettes.md` → based on color slugs article -* `patterns.md` and `block-variations.md` → pattern vs variation context -* `global-styles.md` → FSE + 6.6 overview - -I can also create inline link anchors (e.g. `[fluid type scale](https://rich.blog/fluid-type-scale-theme-json/)`) ready for copy-paste. - -Let me know how you’d like to proceed—happy to scaffold the docs directly. - -[1]: https://rich.blog/fluid-type-scale-theme-json/?utm_source=chatgpt.com "Using a fluid type scale in block themes – Rich Tabor" -[2]: https://rich.blog/standardizing-theme-json-spacing/?utm_source=chatgpt.com "Standardizing theme.json spacing sizes – Rich Tabor" -[3]: https://rich.blog/theme-json-font-sizes/?utm_source=chatgpt.com "Standardizing theme.json font sizes – Rich Tabor" -[4]: https://rich.blog/standardizing-theme-json-colors/?utm_source=chatgpt.com "Standardizing theme.json color slugs – Rich Tabor" -[5]: https://rich.blog/patterns/?utm_source=chatgpt.com "How to build WordPress patterns – Rich Tabor" -[6]: https://rich.blog/block-variations/?utm_source=chatgpt.com "Building WordPress block variations – Rich Tabor" -[7]: https://rich.blog/full-site-editing/?utm_source=chatgpt.com "A primer on WordPress full site editing – Rich Tabor" -[8]: https://rich.blog/wordpress-6-6/?utm_source=chatgpt.com "WordPress 6.6 – Rich Tabor" -[9]: https://rich.blog/standardizing-theme-json-spacing/ "Standardizing theme.json spacing sizes – Rich Tabor" -[10]: https://rich.blog/theme-json-font-sizes/ "Standardizing theme.json font sizes – Rich Tabor" -[11]: https://rich.blog/standardizing-theme-json-colors/ "Standardizing theme.json color slugs – Rich Tabor" -[12]: https://rich.blog/patterns/ "How to build WordPress patterns – Rich Tabor" -[13]: https://rich.blog/block-variations/ "Building WordPress block variations – Rich Tabor" -[14]: https://rich.blog/full-site-editing/ "A primer on WordPress full site editing – Rich Tabor" -[15]: https://rich.blog/wordpress-6-6/ "WordPress 6.6 – Rich Tabor" diff --git a/block-themes/best-practices-fluid-spacing-and typography.md b/block-themes/best-practices-fluid-spacing-and typography.md deleted file mode 100644 index 1ed6908..0000000 --- a/block-themes/best-practices-fluid-spacing-and typography.md +++ /dev/null @@ -1,47 +0,0 @@ -# **Fluid Spacing Learnings** - -**Context Video** \- [WordPress Fluid Spacing - 18 August 2025](https://www.loom.com/share/f56e58ff587648df97f31247bf887744?sid=003d4168-98be-47e0-8e31-8aa9ffebda95) - -**Fluid spacin[https://www.loom.com/share/f56e58ff587648df97f31247bf887744?sid=003d4168-98be-47e0-8e31-8aa9ffebda95](https://www.loom.com/share/f56e58ff587648df97f31247bf887744?sid=003d4168-98be-47e0-8e31-8aa9ffebda95)g** uses `clamp(min, fluid, max)` so spacing (padding, margins, gaps) scales with the viewport width, but never goes smaller than `min` or larger than `max`. - -* **min**: the smallest allowed spacing (protects mobile). -* **fluid**: a viewport-based value (typically `vw`) that grows/shrinks with screen width. -* **max**: the largest allowed spacing (protects ultra-wide screens). - -### **What `vw` is (and why it’s important)** - -* `1vw` \= 1% of the **viewport width**. -* As the viewport changes, the `vw` portion of `clamp()` scales smoothly—no media queries needed. -* `min` and `max` act as guardrails: clamp picks the min on tiny screens, scales fluidly in the middle, and caps at the max on large screens. - -## **“Visual” table: when each part of `clamp()` applies** - -Using `clamp(10px, 2vw, 40px)`: - -| Viewport width | 2vw calculation | Result (chosen by `clamp`) | Why | -| ----- | ----- | ----- | ----- | -| 320px (small mobile) | 6.4px | **10px** | 6.4px \< min → use **min** | -| 375px (mobile) | 7.5px | **10px** | 7.5px \< min → use **min** | -| 768px (tablet) | 15.36px | **15.36px** | within min–max → **fluid** value | -| 1024px (tablet/SM desktop) | 20.48px | **20.48px** | within min–max → **fluid** value | -| 1440px (desktop) | 28.8px | **28.8px** | within min–max → **fluid** value | -| 1920px (large desktop) | 38.4px | **38.4px** | within min–max → **fluid** value | -| 2400px (ultra-wide) | 48px | **40px** | 48px \> max → use **max** | - -**Key idea:** **`vw` is not tied to a specific “device.”** It continuously scales with viewport width. `min` and `max` determine *when* scaling starts and stops. - -## **Understanding the impact VW has on a Mobile device.** - -## **480px Mobile (min/max fixed, vw adjusted)** - -### **Example: `clamp(10px, Xvw, 40px)`** - -| `vw` value | Calculation (Xvw @ 480px) | Result at 480px | Why | -| ----- | ----- | ----- | ----- | -| **1vw** | 4.8px | **10px** | 4.8 \< min → clamp uses min | -| **2vw** | 9.6px | **10px** | 9.6 \< min → clamp uses min | -| **2.5vw** | 12px | **12px** | Now ≥ min → clamp uses fluid | -| **3vw** | 14.4px | **14.4px** | Within min–max → fluid applies | -| **5vw** | 24px | **24px** | Within min–max → fluid applies | -| **10vw** | 48px | **40px** | Above max → clamp caps at max | - diff --git a/block-themes/css-specificity.md b/block-themes/css-specificity.md deleted file mode 100644 index d818a61..0000000 --- a/block-themes/css-specificity.md +++ /dev/null @@ -1,43 +0,0 @@ -# CSS Specificity - Details the CSS specificity model in WordPress 6.6+, its impact on block themes, and why low specificity enables reliable section and style variations. - ---- - -## Best practices -- - ---- - -## When to use -- - ---- - -## Limitations -- - ---- - -## Gutenberg Discussion #61810 — *“CSS Specificity for WordPress 6.6”* - -**What it is:** Deep dive + consensus thread on the **specificity overhaul** in 6.6 that underpins section styles. -**Key points** - -* Core shifts to very **low specificity (e.g., `0-1-0` via `:where(...)`)** to keep the cascade predictable. -* Enables section styles and nested variations to apply **without resorting to custom CSS**. -* Highlights implications for themes that previously depended on higher-specificity rules. ([GitHub][2]) - -**Why it matters** - -* Validates our “JSON-first” approach and explains **why moving rules into `blocks.*`/`elements.*`** inside the variation is the right fix for conflicts. - ---- - -## Reference Links -- [CSS Specificity for WordPress 6.6 · WordPress gutenberg · Discussion #61810 · GitHub](https://github.com/WordPress/gutenberg/discussions/61810) -- [Rich Tabor: Fluid Typography and Block Themes](https://rich.blog/fluid-typography-block-themes/) -- [Rich Tabor: Full Site Editing](https://rich.blog/full-site-editing/) -- [Rich Tabor: WordPress 6.6 Typeset Support](https://rich.blog/wordpress-6-6/) -- [Rich Tabor: Standardizing theme.json spacing sizes](https://rich.blog/standardizing-theme-json-spacing/) -- [Rich Tabor: Block Variations](https://rich.blog/block-variations/) -- [Rich Tabor: Patterns](https://rich.blog/patterns/) diff --git a/block-themes/theme-68.json b/block-themes/theme-68.json deleted file mode 100644 index 158b72e..0000000 --- a/block-themes/theme-68.json +++ /dev/null @@ -1,2733 +0,0 @@ -{ - "title": "JSON schema for WordPress block theme global settings and styles", - "$schema": "http://json-schema.org/draft-07/schema#", - "definitions": { - "//": { - "explainer": "https://developer.wordpress.org/themes/advanced-topics/theme-json/", - "createTheme": "https://developer.wordpress.org/themes/", - "reference": "https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-json/" - }, - "refComplete": { - "type": "object", - "properties": { - "ref": { - "description": "A reference to another property value. e.g. `styles.color.text`", - "type": "string" - } - }, - "additionalProperties": false - }, - "settingsAppearanceToolsProperties": { - "type": "object", - "properties": { - "appearanceTools": { - "description": "Setting that enables the following UI tools:\n\n- background: backgroundImage, backgroundSize\n- border: color, radius, style, width\n- color: link, heading, button, caption\n- dimensions: aspectRatio, minHeight\n- position: sticky\n- spacing: blockGap, margin, padding\n- typography: lineHeight", - "type": "boolean", - "default": false - } - } - }, - "settingsBackgroundProperties": { - "type": "object", - "properties": { - "background": { - "description": "Settings related to background.", - "type": "object", - "properties": { - "backgroundImage": { - "description": "Allow users to set a background image.", - "type": "boolean", - "default": false - }, - "backgroundSize": { - "description": "Allow users to set values related to the size of a background image, including size, position, and repeat controls.", - "type": "boolean", - "default": false - } - }, - "additionalProperties": false - } - } - }, - "settingsBorderProperties": { - "type": "object", - "properties": { - "border": { - "description": "Settings related to borders.", - "type": "object", - "properties": { - "color": { - "description": "Allow users to set custom border colors.", - "type": "boolean", - "default": false - }, - "radius": { - "description": "Allow users to set custom border radius.", - "type": "boolean", - "default": false - }, - "style": { - "description": "Allow users to set custom border styles.", - "type": "boolean", - "default": false - }, - "width": { - "description": "Allow users to set custom border widths.", - "type": "boolean", - "default": false - } - }, - "additionalProperties": false - } - } - }, - "settingsColorProperties": { - "type": "object", - "properties": { - "color": { - "description": "Settings related to colors.", - "type": "object", - "properties": { - "background": { - "description": "Allow users to set background colors.", - "type": "boolean", - "default": true - }, - "custom": { - "description": "Allow users to select custom colors.", - "type": "boolean", - "default": true - }, - "customDuotone": { - "description": "Allow users to create custom duotone filters.", - "type": "boolean", - "default": true - }, - "customGradient": { - "description": "Allow users to create custom gradients.", - "type": "boolean", - "default": true - }, - "defaultDuotone": { - "description": "Allow users to choose filters from the default duotone filter presets.", - "type": "boolean", - "default": true - }, - "defaultGradients": { - "description": "Allow users to choose colors from the default gradients.", - "type": "boolean", - "default": true - }, - "defaultPalette": { - "description": "Allow users to choose colors from the default palette.", - "type": "boolean", - "default": true - }, - "duotone": { - "description": "Duotone presets for the duotone picker.\nDoesn't generate classes or properties.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Name of the duotone preset, translatable.", - "type": "string" - }, - "slug": { - "description": "Kebab-case unique identifier for the duotone preset.", - "type": "string" - }, - "colors": { - "description": "List of colors from dark to light.", - "type": "array", - "items": { - "description": "CSS hex or rgb string.", - "type": "string" - } - } - }, - "required": [ "name", "slug", "colors" ], - "additionalProperties": false - } - }, - "gradients": { - "description": "Gradient presets for the gradient picker.\nGenerates a single class (`.has-{slug}-background`) and custom property (`--wp--preset--gradient--{slug}`) per preset value.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Name of the gradient preset, translatable.", - "type": "string" - }, - "slug": { - "description": "Kebab-case unique identifier for the gradient preset.", - "type": "string" - }, - "gradient": { - "description": "CSS gradient string.", - "type": "string" - } - }, - "required": [ "name", "slug", "gradient" ], - "additionalProperties": false - } - }, - "link": { - "description": "Allow users to set link colors in a block.", - "type": "boolean", - "default": false - }, - "palette": { - "description": "Color palette presets for the color picker.\nGenerates three classes (`.has-{slug}-color`, `.has-{slug}-background-color`, and `.has-{slug}-border-color`) and a single custom property (`--wp--preset--color--{slug}`) per preset value.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Name of the color preset, translatable.", - "type": "string" - }, - "slug": { - "description": "Kebab-case unique identifier for the color preset.", - "type": "string" - }, - "color": { - "description": "CSS hex or rgb(a) string.", - "type": "string" - } - }, - "required": [ "name", "slug", "color" ], - "additionalProperties": false - } - }, - "text": { - "description": "Allow users to set text colors in a block.", - "type": "boolean", - "default": true - }, - "heading": { - "description": "Allow users to set heading colors in a block.", - "type": "boolean", - "default": true - }, - "button": { - "description": "Allow users to set button colors in a block.", - "type": "boolean", - "default": true - }, - "caption": { - "description": "Allow users to set caption colors in a block.", - "type": "boolean", - "default": true - } - }, - "additionalProperties": false - } - } - }, - "settingsDimensionsProperties": { - "type": "object", - "properties": { - "dimensions": { - "description": "Settings related to dimensions.", - "type": "object", - "properties": { - "aspectRatio": { - "description": "Allow users to set an aspect ratio.", - "type": "boolean", - "default": false - }, - "defaultAspectRatios": { - "description": "Allow users to choose aspect ratios from the default set of aspect ratios.", - "type": "boolean", - "default": true - }, - "aspectRatios": { - "description": "Allow users to define aspect ratios for some blocks.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Name of the aspect ratio preset.", - "type": "string" - }, - "slug": { - "description": "Kebab-case unique identifier for the aspect ratio preset.", - "type": "string" - }, - "ratio": { - "description": "Aspect ratio expressed as a division or decimal.", - "type": "string" - } - } - } - }, - "minHeight": { - "description": "Allow users to set custom minimum height.", - "type": "boolean", - "default": false - } - }, - "additionalProperties": false - } - } - }, - "settingsLayoutProperties": { - "type": "object", - "properties": { - "layout": { - "description": "Settings related to layout.", - "type": "object", - "properties": { - "contentSize": { - "description": "Sets the max-width of the content.", - "type": "string" - }, - "wideSize": { - "description": "Sets the max-width of wide (`.alignwide`) content. Also used as the maximum viewport when calculating fluid font sizes", - "type": "string" - }, - "allowEditing": { - "description": "Disable the layout UI controls.", - "type": "boolean", - "default": true - }, - "allowCustomContentAndWideSize": { - "description": "Enable or disable the custom content and wide size controls.", - "type": "boolean", - "default": true - } - }, - "additionalProperties": false - } - } - }, - "settingsLightboxProperties": { - "type": "object", - "properties": { - "lightbox": { - "description": "Settings related to the lightbox.", - "type": "object", - "properties": { - "enabled": { - "description": "Defines whether the lightbox is enabled or not.", - "type": "boolean" - }, - "allowEditing": { - "description": "Defines whether to show the Lightbox UI in the block editor. If set to `false`, the user won't be able to change the lightbox settings in the block editor.", - "type": "boolean" - } - }, - "additionalProperties": false - } - } - }, - "settingsPositionProperties": { - "type": "object", - "properties": { - "position": { - "description": "Settings related to position.", - "type": "object", - "properties": { - "sticky": { - "description": "Allow users to set sticky position.", - "type": "boolean", - "default": false - } - }, - "additionalProperties": false - } - } - }, - "settingsShadowProperties": { - "type": "object", - "properties": { - "shadow": { - "description": "Settings related to shadows.", - "type": "object", - "properties": { - "defaultPresets": { - "description": "Allow users to choose shadows from the default shadow presets.", - "type": "boolean", - "default": true - }, - "presets": { - "description": "Shadow presets for the shadow picker.\nGenerates a single custom property (`--wp--preset--shadow--{slug}`) per preset value.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Name of the shadow preset, translatable.", - "type": "string" - }, - "slug": { - "description": "Kebab-case unique identifier for the shadow preset.", - "type": "string" - }, - "shadow": { - "description": "CSS box-shadow value", - "type": "string" - } - }, - "required": [ "name", "slug", "shadow" ], - "additionalProperties": false - } - } - }, - "additionalProperties": false - } - } - }, - "settingsSpacingProperties": { - "type": "object", - "properties": { - "spacing": { - "description": "Settings related to spacing.", - "type": "object", - "properties": { - "blockGap": { - "description": "Enables `--wp--style--block-gap` to be generated from styles.spacing.blockGap.\nA value of `null` instead of `false` further disables layout styles from being generated.", - "oneOf": [ - { "type": "boolean" }, - { "type": "null" } - ], - "default": null - }, - "margin": { - "description": "Allow users to set a custom margin.", - "type": "boolean", - "default": false - }, - "padding": { - "description": "Allow users to set a custom padding.", - "type": "boolean", - "default": false - }, - "units": { - "description": "List of units the user can use for spacing values.", - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "default": [ "px", "em", "rem", "vh", "vw", "%" ] - }, - "customSpacingSize": { - "description": "Allow users to set custom space sizes.", - "type": "boolean", - "default": true - }, - "defaultSpacingSizes": { - "description": "Allow users to choose space sizes from the default space size presets.", - "type": "boolean", - "default": true - }, - "spacingSizes": { - "description": "Space size presets for the space size selector.\nGenerates a custom property (`--wp--preset--spacing--{slug}`) per preset value.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Name of the space size preset, translatable.", - "type": "string" - }, - "slug": { - "description": "Unique identifier for the space size preset. For best cross theme compatibility these should be in the form '10','20','30','40','50','60', etc. with '50' representing the 'Medium' size step. If all slugs begin with a number they will be merged with default and user slugs and sorted numerically.", - "type": "string" - }, - "size": { - "description": "CSS space-size value, including units.", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "spacingScale": { - "description": "Settings to auto-generate space size presets for the space size selector.\nGenerates a custom property (--wp--preset--spacing--{slug}`) per preset value.", - "type": "object", - "properties": { - "operator": { - "description": "With + or * depending on whether scale is generated by increment or multiplier.", - "type": "string", - "enum": [ "+", "*" ], - "default": "*" - }, - "increment": { - "description": "The amount to increment each step by.", - "type": "number", - "exclusiveMinimum": 0, - "default": 1.5 - }, - "steps": { - "description": "Number of steps to generate in scale.", - "type": "integer", - "minimum": 1, - "maximum": 10, - "default": 7 - }, - "mediumStep": { - "description": "The value to medium setting in the scale.", - "type": "number", - "exclusiveMinimum": 0, - "default": 1.5 - }, - "unit": { - "description": "Unit that the scale uses, eg. rem, em, px.", - "type": "string", - "enum": [ - "px", - "em", - "rem", - "%", - "vw", - "svw", - "lvw", - "dvw", - "vh", - "svh", - "lvh", - "dvh", - "vi", - "svi", - "lvi", - "dvi", - "vb", - "svb", - "lvb", - "dvb", - "vmin", - "svmin", - "lvmin", - "dvmin", - "vmax", - "svmax", - "lvmax", - "dvmax" - ], - "default": "rem" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - } - }, - "settingsTypographyProperties": { - "type": "object", - "properties": { - "typography": { - "description": "Settings related to typography.", - "type": "object", - "properties": { - "defaultFontSizes": { - "description": "Allow users to choose font sizes from the default font size presets.", - "type": "boolean", - "default": true - }, - "customFontSize": { - "description": "Allow users to set custom font sizes.", - "type": "boolean", - "default": true - }, - "fontStyle": { - "description": "Allow users to set custom font styles.", - "type": "boolean", - "default": true - }, - "fontWeight": { - "description": "Allow users to set custom font weights.", - "type": "boolean", - "default": true - }, - "fluid": { - "description": "Enables fluid typography and allows users to set global fluid typography parameters.", - "oneOf": [ - { - "type": "object", - "properties": { - "minFontSize": { - "description": "Allow users to set a global minimum font size boundary in px, rem or em. Custom font sizes below this value will not be clamped, and all calculated minimum font sizes will be, at a minimum, this value.", - "type": "string" - }, - "maxViewportWidth": { - "description": "Allow users to set custom a max viewport width in px, rem or em, used to set the maximum size boundary of a fluid font size.", - "type": "string" - }, - "minViewportWidth": { - "description": "Allow users to set a custom min viewport width in px, rem or em, used to set the minimum size boundary of a fluid font size.", - "type": "string" - } - }, - "additionalProperties": false - }, - { - "type": "boolean" - } - ], - "default": false - }, - "letterSpacing": { - "description": "Allow users to set custom letter spacing.", - "type": "boolean", - "default": true - }, - "lineHeight": { - "description": "Allow users to set custom line height.", - "type": "boolean", - "default": false - }, - "textAlign": { - "description": "Allow users to set the text align.", - "type": "boolean", - "default": true - }, - "textColumns": { - "description": "Allow users to set the number of text columns.", - "type": "boolean", - "default": false - }, - "textDecoration": { - "description": "Allow users to set custom text decorations.", - "type": "boolean", - "default": true - }, - "writingMode": { - "description": "Allow users to set the writing mode.", - "type": "boolean", - "default": false - }, - "textTransform": { - "description": "Allow users to set custom text transforms.", - "type": "boolean", - "default": true - }, - "dropCap": { - "description": "Enable drop cap.", - "type": "boolean", - "default": true - }, - "fontSizes": { - "description": "Font size presets for the font size selector.\nGenerates a single class (`.has-{slug}-color`) and custom property (`--wp--preset--font-size--{slug}`) per preset value.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Name of the font size preset, translatable.", - "type": "string" - }, - "slug": { - "description": "Kebab-case unique identifier for the font size preset.", - "type": "string" - }, - "size": { - "description": "CSS font-size value, including units.", - "type": "string" - }, - "fluid": { - "description": "Specifies the minimum and maximum font size value of a fluid font size. Set to `false` to bypass fluid calculations and use the static `size` value.", - "oneOf": [ - { - "type": "object", - "properties": { - "min": { - "description": "A min font size for fluid font size calculations in px, rem or em.", - "type": "string" - }, - "max": { - "description": "A max font size for fluid font size calculations in px, rem or em.", - "type": "string" - } - }, - "additionalProperties": false - }, - { - "type": "boolean" - } - ] - } - }, - "additionalProperties": false - } - }, - "fontFamilies": { - "description": "Font family presets for the font family selector.\nGenerates a single custom property (`--wp--preset--font-family--{slug}`) per preset value.", - "type": "array", - "items": { - "description": "Font family preset", - "type": "object", - "properties": { - "name": { - "description": "Name of the font family preset, translatable.", - "type": "string" - }, - "slug": { - "description": "Kebab-case unique identifier for the font family preset.", - "type": "string" - }, - "fontFamily": { - "description": "CSS font-family value.", - "type": "string" - }, - "fontFace": { - "description": "Array of font-face declarations.", - "type": "array", - "items": { - "type": "object", - "properties": { - "fontFamily": { - "description": "CSS font-family value.", - "type": "string", - "default": "" - }, - "fontStyle": { - "description": "CSS font-style value.", - "type": "string", - "default": "normal" - }, - "fontWeight": { - "description": "List of available font weights, separated by a space.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "integer" - } - ], - "default": "400" - }, - "fontDisplay": { - "description": "CSS font-display value.", - "type": "string", - "enum": [ - "auto", - "block", - "fallback", - "swap", - "optional" - ], - "default": "fallback" - }, - "src": { - "description": "Paths or URLs to the font files.", - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ], - "default": [] - }, - "fontStretch": { - "description": "CSS font-stretch value.", - "type": "string" - }, - "ascentOverride": { - "description": "CSS ascent-override value.", - "type": "string" - }, - "descentOverride": { - "description": "CSS descent-override value.", - "type": "string" - }, - "fontVariant": { - "description": "CSS font-variant value.", - "type": "string" - }, - "fontFeatureSettings": { - "description": "CSS font-feature-settings value.", - "type": "string" - }, - "fontVariationSettings": { - "description": "CSS font-variation-settings value.", - "type": "string" - }, - "lineGapOverride": { - "description": "CSS line-gap-override value.", - "type": "string" - }, - "sizeAdjust": { - "description": "CSS size-adjust value.", - "type": "string" - }, - "unicodeRange": { - "description": "CSS unicode-range value.", - "type": "string" - } - }, - "required": [ "fontFamily", "src" ], - "additionalProperties": false - } - } - }, - "additionalProperties": false - } - } - }, - "additionalProperties": false - } - } - }, - "settingsCustomProperties": { - "type": "object", - "properties": { - "custom": { - "$ref": "#/definitions/settingsCustomAdditionalProperties" - } - } - }, - "settingsProperties": { - "allOf": [ - { "$ref": "#/definitions/settingsAppearanceToolsProperties" }, - { "$ref": "#/definitions/settingsBackgroundProperties" }, - { "$ref": "#/definitions/settingsBorderProperties" }, - { "$ref": "#/definitions/settingsColorProperties" }, - { "$ref": "#/definitions/settingsDimensionsProperties" }, - { "$ref": "#/definitions/settingsLayoutProperties" }, - { "$ref": "#/definitions/settingsLightboxProperties" }, - { "$ref": "#/definitions/settingsPositionProperties" }, - { "$ref": "#/definitions/settingsShadowProperties" }, - { "$ref": "#/definitions/settingsSpacingProperties" }, - { "$ref": "#/definitions/settingsTypographyProperties" }, - { "$ref": "#/definitions/settingsCustomProperties" } - ] - }, - "settingsPropertyNames": { - "enum": [ - "appearanceTools", - "background", - "border", - "color", - "dimensions", - "layout", - "lightbox", - "position", - "shadow", - "spacing", - "typography", - "custom" - ] - }, - "settingsPropertiesComplete": { - "allOf": [ - { - "$ref": "#/definitions/settingsProperties" - }, - { - "type": "object", - "propertyNames": { - "$ref": "#/definitions/settingsPropertyNames" - } - } - ] - }, - "settingsBlocksPropertiesComplete": { - "description": "Settings defined on a per-block basis.", - "type": "object", - "properties": { - "core/archives": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/audio": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/avatar": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/block": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/button": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/buttons": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/calendar": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/categories": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/code": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/column": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/columns": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comment-author-avatar": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comment-author-name": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comment-content": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comment-date": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comment-edit-link": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comment-reply-link": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comments": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comments-pagination": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comments-pagination-next": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comments-pagination-numbers": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comments-pagination-previous": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comments-title": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/comment-template": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/cover": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/details": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/embed": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/file": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/footnotes": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/freeform": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/gallery": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/group": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/heading": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/home-link": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/html": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/image": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/latest-comments": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/latest-posts": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/list": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/list-item": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/loginout": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/media-text": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/missing": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/more": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/navigation": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/navigation-link": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/navigation-submenu": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/nextpage": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/page-list": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/page-list-item": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/paragraph": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-author": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-author-biography": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-author-name": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-comment": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-comments-count": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-comments-form": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-comments-link": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-content": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-date": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-excerpt": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-featured-image": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-navigation-link": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-template": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-terms": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/post-title": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/preformatted": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/pullquote": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query-no-results": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query-pagination": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query-pagination-next": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query-pagination-numbers": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query-pagination-previous": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query-title": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/query-total": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/quote": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/read-more": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/rss": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/search": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/separator": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/shortcode": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/site-logo": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/site-tagline": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/site-title": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/social-link": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/social-links": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/spacer": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/table": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/tag-cloud": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/template-part": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/term-description": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/text-columns": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/verse": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/video": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/widget-area": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/legacy-widget": { - "$ref": "#/definitions/settingsPropertiesComplete" - }, - "core/widget-group": { - "$ref": "#/definitions/settingsPropertiesComplete" - } - }, - "patternProperties": { - "^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$": { - "$ref": "#/definitions/settingsPropertiesComplete" - } - }, - "additionalProperties": false - }, - "settingsCustomAdditionalProperties": { - "description": "Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-key}: {value};`. `camelCased` keys are transformed to `kebab-case` as to follow the CSS property naming schema. Keys at different depth levels are separated by `--`, so keys should not include `--` in the name.", - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "$ref": "#/definitions/settingsCustomAdditionalProperties" - } - ] - } - }, - "stylesProperties": { - "type": "object", - "properties": { - "background": { - "description": "Background styles.", - "type": "object", - "properties": { - "backgroundImage": { - "description": "Sets the `background-image` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" }, - { - "type": "object", - "properties": { - "url": { - "description": "A URL to an image file, or a path to a file relative to the theme root directory, and prefixed with `file:`, e.g., 'file:./path/to/file.png'.", - "type": "string" - } - }, - "additionalProperties": false - } - ] - }, - "backgroundPosition": { - "description": "Sets the `background-position` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "backgroundRepeat": { - "description": "Sets the `background-repeat` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "backgroundSize": { - "description": "Sets the `background-size` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "backgroundAttachment": { - "description": "Sets the `background-attachment` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "border": { - "description": "Border styles.", - "type": "object", - "properties": { - "color": { - "description": "Sets the `border-color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "radius": { - "description": "Sets the `border-radius` CSS property.", - "anyOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" }, - { - "type": "object", - "properties": { - "topLeft": { - "description": "Sets the `border-top-left-radius` CSS property.", - "oneOf": [ - { "type": "string" }, - { - "$ref": "#/definitions/refComplete" - } - ] - }, - "topRight": { - "description": "Sets the `border-top-right-radius` CSS property.", - "oneOf": [ - { "type": "string" }, - { - "$ref": "#/definitions/refComplete" - } - ] - }, - "bottomLeft": { - "description": "Sets the `border-bottom-left-radius` CSS property.", - "oneOf": [ - { "type": "string" }, - { - "$ref": "#/definitions/refComplete" - } - ] - }, - "bottomRight": { - "description": "Sets the `border-bottom-right-radius` CSS property.", - "oneOf": [ - { "type": "string" }, - { - "$ref": "#/definitions/refComplete" - } - ] - } - } - } - ] - }, - "style": { - "description": "Sets the `border-style` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "width": { - "description": "Sets the `border-width` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "top": { - "type": "object", - "properties": { - "color": { - "description": "Sets the `border-top-color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "style": { - "description": "Sets the `border-top-style` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "width": { - "description": "Sets the `border-top-width` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "right": { - "type": "object", - "properties": { - "color": { - "description": "Sets the `border-right-color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "style": { - "description": "Sets the `border-right-style` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "width": { - "description": "Sets the `border-right-width` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "bottom": { - "type": "object", - "properties": { - "color": { - "description": "Sets the `border-bottom-color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "style": { - "description": "Sets the `border-bottom-style` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "width": { - "description": "Sets the `border-bottom-width` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "left": { - "type": "object", - "properties": { - "color": { - "description": "Sets the `border-left-color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "style": { - "description": "Sets the `border-left-style` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "width": { - "description": "Sets the `border-left-width` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "color": { - "description": "Color styles.", - "type": "object", - "properties": { - "background": { - "description": "Sets the `background-color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "gradient": { - "description": "Sets the `background` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "text": { - "description": "Sets the `color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "css": { - "description": "Sets custom CSS to apply styling not covered by other theme.json properties.", - "type": "string" - }, - "dimensions": { - "description": "Dimensions styles.", - "type": "object", - "properties": { - "aspectRatio": { - "description": "Sets the `aspect-ratio` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "minHeight": { - "description": "Sets the `min-height` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - } - }, - "filter": { - "description": "CSS and SVG filter styles.", - "type": "object", - "properties": { - "duotone": { - "description": "Sets the duotone filter.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "outline": { - "description": "Outline styles.", - "type": "object", - "properties": { - "color": { - "description": "Sets the `outline-color` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "offset": { - "description": "Sets the `outline-offset` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "style": { - "description": "Sets the `outline-style` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "width": { - "description": "Sets the `outline-width` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "shadow": { - "description": "Box shadow styles.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "spacing": { - "description": "Spacing styles.", - "type": "object", - "properties": { - "blockGap": { - "description": "Sets the `--wp--style--block-gap` CSS custom property when settings.spacing.blockGap is true.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "margin": { - "description": "Margin styles.", - "type": "object", - "properties": { - "top": { - "description": "Sets the `margin-top` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "right": { - "description": "Sets the `margin-right` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "bottom": { - "description": "Sets the `margin-bottom` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "left": { - "description": "Sets the `margin-left` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - }, - "padding": { - "description": "Padding styles.", - "type": "object", - "properties": { - "top": { - "description": "Sets the `padding-top` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "right": { - "description": "Sets the `padding-right` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "bottom": { - "description": "Sets the `padding-bottom` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "left": { - "description": "Sets the `padding-left` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "typography": { - "description": "Typography styles.", - "type": "object", - "properties": { - "fontFamily": { - "description": "Sets the `font-family` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "fontSize": { - "description": "Sets the `font-size` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "fontStyle": { - "description": "Sets the `font-style` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "fontWeight": { - "description": "Sets the `font-weight` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "letterSpacing": { - "description": "Sets the `letter-spacing` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "lineHeight": { - "description": "Sets the `line-height` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "textAlign": { - "description": "Sets the `text-align` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "textColumns": { - "description": "Sets the `column-count` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "textDecoration": { - "description": "Sets the `text-decoration` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "writingMode": { - "description": "Sets the `writing-mode` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - }, - "textTransform": { - "description": "Sets the `text-transform` CSS property.", - "oneOf": [ - { "type": "string" }, - { "$ref": "#/definitions/refComplete" } - ] - } - }, - "additionalProperties": false - } - } - }, - "stylesPropertyNames": { - "enum": [ - "background", - "border", - "color", - "css", - "dimensions", - "filter", - "outline", - "shadow", - "spacing", - "typography" - ] - }, - "stylesPropertiesComplete": { - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "type": "object", - "propertyNames": { - "$ref": "#/definitions/stylesPropertyNames" - } - } - ] - }, - "stylesElementsPseudoSelectorsProperties": { - "type": "object", - "properties": { - ":active": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - ":any-link": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - ":focus": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - ":focus-visible": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - ":hover": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - ":link": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - ":visited": { - "$ref": "#/definitions/stylesPropertiesComplete" - } - } - }, - "stylesElementsPseudoSelectorsPropertyNames": { - "enum": [ - ":active", - ":any-link", - ":focus", - ":focus-visible", - ":hover", - ":link", - ":visited" - ] - }, - "stylesElementsPropertiesComplete": { - "description": "Styles defined on a per-element basis using the element's selector.", - "type": "object", - "properties": { - "button": { - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "$ref": "#/definitions/stylesElementsPseudoSelectorsProperties" - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/stylesPropertyNames" - }, - { - "$ref": "#/definitions/stylesElementsPseudoSelectorsPropertyNames" - } - ] - } - } - ] - }, - "link": { - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "$ref": "#/definitions/stylesElementsPseudoSelectorsProperties" - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/stylesPropertyNames" - }, - { - "$ref": "#/definitions/stylesElementsPseudoSelectorsPropertyNames" - } - ] - } - } - ] - }, - "heading": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "h1": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "h2": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "h3": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "h4": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "h5": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "h6": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "caption": { - "$ref": "#/definitions/stylesPropertiesComplete" - }, - "cite": { - "$ref": "#/definitions/stylesPropertiesComplete" - } - }, - "additionalProperties": false - }, - "stylesBlocksPropertiesComplete": { - "description": "Styles defined on a per-block basis using the block's selector.", - "type": "object", - "properties": { - "core/archives": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/audio": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/avatar": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/block": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/button": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/buttons": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/calendar": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/categories": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/code": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/column": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/columns": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comment-author-avatar": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comment-author-name": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comment-content": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comment-date": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comment-edit-link": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comment-reply-link": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comments": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comments-pagination": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comments-pagination-next": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comments-pagination-numbers": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comments-pagination-previous": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comments-title": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/comment-template": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/cover": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/details": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/embed": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/file": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/footnotes": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/freeform": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/gallery": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/group": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/heading": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/home-link": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/html": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/image": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/latest-comments": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/latest-posts": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/list": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/list-item": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/loginout": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/media-text": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/missing": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/more": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/navigation": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/navigation-link": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/navigation-submenu": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/nextpage": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/page-list": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/page-list-item": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/paragraph": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-author": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-author-biography": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-author-name": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-comment": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-comments-count": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-comments-form": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-comments-link": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-content": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-date": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-excerpt": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-featured-image": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-navigation-link": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-template": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-terms": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/post-title": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/preformatted": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/pullquote": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query-no-results": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query-pagination": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query-pagination-next": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query-pagination-numbers": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query-pagination-previous": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query-title": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/query-total": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/quote": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/read-more": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/rss": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/search": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/separator": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/shortcode": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/site-logo": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/site-tagline": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/site-title": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/social-link": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/social-links": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/spacer": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/table": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/tag-cloud": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/template-part": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/term-description": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/text-columns": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/verse": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/video": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/widget-area": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/legacy-widget": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/widget-group": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - } - }, - "patternProperties": { - "^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - } - }, - "additionalProperties": false - }, - "stylesPropertiesAndElementsComplete": { - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "type": "object", - "properties": { - "elements": { - "$ref": "#/definitions/stylesElementsPropertiesComplete" - }, - "variations": { - "$ref": "#/definitions/stylesVariationsPropertiesComplete" - } - } - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/stylesPropertyNames" - }, - { - "enum": [ "elements", "variations" ] - } - ] - } - } - ] - }, - "stylesVariationsProperties": { - "type": "object", - "patternProperties": { - "^[a-z][a-z0-9-]*$": { - "$ref": "#/definitions/stylesVariationProperties" - } - } - }, - "stylesVariationProperties": { - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "type": "object", - "properties": { - "elements": { - "$ref": "#/definitions/stylesElementsPropertiesComplete" - }, - "blocks": { - "$ref": "#/definitions/stylesVariationBlocksPropertiesComplete" - } - } - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/stylesPropertyNames" - }, - { - "enum": [ "elements", "blocks" ] - } - ] - } - } - ] - }, - "stylesVariationsPropertiesComplete": { - "type": "object", - "patternProperties": { - "^[a-z][a-z0-9-]*$": { - "$ref": "#/definitions/stylesVariationPropertiesComplete" - } - } - }, - "stylesVariationPropertiesComplete": { - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "type": "object", - "properties": { - "elements": { - "$ref": "#/definitions/stylesElementsPropertiesComplete" - }, - "blocks": { - "$ref": "#/definitions/stylesVariationBlocksPropertiesComplete" - } - } - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/stylesPropertyNames" - }, - { - "enum": [ "elements", "blocks" ] - } - ] - } - } - ] - }, - "stylesVariationBlocksPropertiesComplete": { - "type": "object", - "properties": { - "core/archives": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/audio": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/avatar": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/block": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/button": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/buttons": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/calendar": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/categories": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/code": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/column": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/columns": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comment-author-avatar": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comment-author-name": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comment-content": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comment-date": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comment-edit-link": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comment-reply-link": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comments": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comments-pagination": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comments-pagination-next": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comments-pagination-numbers": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comments-pagination-previous": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comments-title": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/comment-template": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/cover": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/details": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/embed": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/file": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/footnotes": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/freeform": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/gallery": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/group": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/heading": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/home-link": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/html": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/image": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/latest-comments": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/latest-posts": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/list": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/list-item": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/loginout": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/media-text": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/missing": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/more": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/navigation": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/navigation-link": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/navigation-submenu": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/nextpage": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/page-list": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/page-list-item": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/paragraph": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-author": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-author-biography": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-author-name": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-comment": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-comments-count": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-comments-form": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-comments-link": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-content": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-date": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-excerpt": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-featured-image": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-navigation-link": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-template": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-terms": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/post-title": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/preformatted": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/pullquote": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query-no-results": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query-pagination": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query-pagination-next": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query-pagination-numbers": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query-pagination-previous": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query-title": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/query-total": { - "$ref": "#/definitions/stylesPropertiesAndElementsComplete" - }, - "core/quote": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/read-more": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/rss": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/search": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/separator": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/shortcode": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/site-logo": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/site-tagline": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/site-title": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/social-link": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/social-links": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/spacer": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/table": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/tag-cloud": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/template-part": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/term-description": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/text-columns": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/verse": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/video": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/widget-area": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/legacy-widget": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - }, - "core/widget-group": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - } - }, - "patternProperties": { - "^[a-z][a-z0-9-]*/[a-z][a-z0-9-]*$": { - "$ref": "#/definitions/stylesVariationBlockPropertiesComplete" - } - }, - "additionalProperties": false - }, - "stylesVariationBlockPropertiesComplete": { - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "type": "object", - "properties": { - "elements": { - "$ref": "#/definitions/stylesElementsPropertiesComplete" - } - } - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/stylesPropertyNames" - }, - { - "enum": [ "elements" ] - } - ] - } - } - ] - } - }, - "type": "object", - "properties": { - "$schema": { - "description": "JSON schema URI for theme.json.", - "type": "string" - }, - "version": { - "description": "Version of theme.json to use.", - "type": "integer", - "const": 3 - }, - "title": { - "description": "Title of the global styles variation. If not defined, the file name will be used.", - "type": "string" - }, - "slug": { - "description": "Slug of the global styles variation. If not defined, the kebab-case title will be used.", - "type": "string" - }, - "description": { - "description": "Description of the global styles variation.", - "type": "string" - }, - "blockTypes": { - "description": "List of block types that can use the block style variation this theme.json file represents.", - "type": "array", - "items": { - "type": "string" - } - }, - "settings": { - "description": "Settings for the block editor and individual blocks. These include things like:\n- Which customization options should be available to the user. \n- The default colors, font sizes... available to the user. \n- CSS custom properties and class names used in styles.\n- And the default layout of the editor (widths and available alignments).", - "allOf": [ - { - "$ref": "#/definitions/settingsProperties" - }, - { - "type": "object", - "properties": { - "useRootPaddingAwareAlignments": { - "description": "Enables root padding (the values from `styles.spacing.padding`) to be applied to the contents of full-width blocks instead of the root block.\n\nPlease note that when using this setting, `styles.spacing.padding` should always be set as an object with `top`, `right`, `bottom`, `left` values declared separately.", - "type": "boolean", - "default": false - }, - "blocks": { - "$ref": "#/definitions/settingsBlocksPropertiesComplete" - } - } - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/settingsPropertyNames" - }, - { - "enum": [ - "useRootPaddingAwareAlignments", - "blocks" - ] - } - ] - } - } - ] - }, - "styles": { - "description": "Organized way to set CSS properties. Styles in the top-level will be added in the `body` selector.", - "allOf": [ - { - "$ref": "#/definitions/stylesProperties" - }, - { - "type": "object", - "properties": { - "elements": { - "$ref": "#/definitions/stylesElementsPropertiesComplete" - }, - "blocks": { - "$ref": "#/definitions/stylesBlocksPropertiesComplete" - }, - "variations": { - "$ref": "#/definitions/stylesVariationsProperties" - } - } - }, - { - "type": "object", - "propertyNames": { - "anyOf": [ - { - "$ref": "#/definitions/stylesPropertyNames" - }, - { - "enum": [ "elements", "blocks", "variations" ] - } - ] - } - } - ] - }, - "customTemplates": { - "description": "Additional metadata for custom templates defined in the templates folder.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Filename, without extension, of the template in the templates folder.", - "type": "string" - }, - "title": { - "description": "Title of the template, translatable.", - "type": "string" - }, - "postTypes": { - "description": "List of post types that can use this custom template.", - "type": "array", - "items": { - "type": "string" - }, - "default": [ "page" ] - } - }, - "required": [ "name", "title" ], - "additionalProperties": false - } - }, - "templateParts": { - "description": "Additional metadata for template parts defined in the parts folder.", - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "description": "Filename, without extension, of the template in the parts folder.", - "type": "string" - }, - "title": { - "description": "Title of the template, translatable.", - "type": "string" - }, - "area": { - "description": "The area the template part is used for. Block variations for `header` and `footer` values exist and will be used when the area is set to one of those.", - "type": "string", - "default": "uncategorized" - } - }, - "required": [ "name" ], - "additionalProperties": false - } - }, - "patterns": { - "description": "An array of pattern slugs to be registered from the Pattern Directory.", - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": [ "version" ], - "additionalProperties": false -} diff --git a/block-themes/theme-structure-epi.md b/block-themes/theme-structure-epi.md deleted file mode 100644 index 4a55bf8..0000000 --- a/block-themes/theme-structure-epi.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: "Epic Issue" -about: "Template for creating an EPIC issue to track a larger goal and its sub-tasks" -title: "[EPIC] WordPress Block Theme Structure Implementation" -labels: epic -assignees: ---- -## Priority - -- High - -## Goal - -Establish the complete folder and file structure for the WordPress block theme according to WordPress best practices and standards, creating a solid foundation for theme development. - -## Description - -This epic covers the creation of all necessary folders and files required for a modern WordPress block theme that follows the Full Site Editing (FSE) approach. We will implement the standard theme structure as outlined in the WordPress Block Theme Structure & Development Guidelines, including required core files, primary theme directories, global styles, and proper asset organization. - -The theme will follow WordPress coding standards and best practices for block themes, ensuring it's well-structured, maintainable, and ready for development. This foundation will establish the framework upon which all theme features and functionality will be built. - -## Acceptance Criteria - -- [ ] All child issues are closed and their deliverables present in the repository. -- [ ] File and folder structure matches project standards and guidelines. -- [ ] All documentation is clear, up-to-date, and accessible for contributors and users. -- [ ] The following directories are created with their appropriate initial files: - - [ ] `/templates/` (with at least `index.html`) - - [ ] `/parts/` (with header and footer parts) - - [ ] `/patterns/` (directory created, ready for patterns) - - [ ] `/styles/` (for style variations) - - [ ] `/assets/` or `/src/` (for development files) - - [ ] `/inc/` (for PHP includes if needed) -- [ ] Core theme files are created: - - [ ] `style.css` with proper theme metadata - - [ ] `functions.php` with basic theme setup - - [ ] `theme.json` with global styles configuration - - [ ] `screenshot.png` for theme preview - - [ ] `README.md` with theme documentation - - [ ] Build configuration files (package.json, webpack.config.js) - -## Sub-Issues - -- [ ] [#] Create core theme files (style.css, functions.php) -- [ ] [#] Set up template directory structure with index.html -- [ ] [#] Create template parts directory with header and footer -- [ ] [#] Configure theme.json for global styles and settings -- [ ] [#] Set up asset/build pipeline with @wordpress/scripts -- [ ] [#] Create README and documentation files -- [ ] [#] Generate theme screenshot -- [ ] [#] Establish patterns directory and initial patterns -- [ ] [#] Create style variations directory and base variation -- [ ] [#] Set up testing infrastructure diff --git a/block-themes/typesets.md b/block-themes/typesets.md deleted file mode 100644 index 9333798..0000000 --- a/block-themes/typesets.md +++ /dev/null @@ -1,23 +0,0 @@ -# Typesets (Font Size Presets) -The file style-variations.md provides a concise guide to the differences between style variations and block variations in WordPress block development. It explains that style variations are visual alternatives for blocks defined via theme.json, while block variations are structural alternatives registered with JavaScript. The document outlines best practices, use cases, and limitations, emphasizing not to confuse the two APIs. It also includes a reference link for further reading. ---- - -**Best practices** -- Leverage new **typeset support** in WordPress 6.6 for consistent font-size presets. ([Rich Tabor](https://rich.blog/wordpress-6-6/?utm_source=chatgpt.com)) - ---- - -## When to use -- - ---- - -## Limitations -- Requires theme authoring in WP 6.6+ to make use of this feature. - ---- - -## Reference Links -- [Rich Tabor: WordPress 6.6 Typeset Support](https://rich.blog/wordpress-6-6/) - ---- diff --git a/coding-standards/_temp.md b/coding-standards/_temp.md deleted file mode 100644 index b2f27f1..0000000 --- a/coding-standards/_temp.md +++ /dev/null @@ -1,167 +0,0 @@ -I need you to go through all of the links in the references below, and compile in markdown format comprehensive coding standard documents per language, there will be an individual document per language as per the numbering system below. - -The attached documentation and wordpress coding standards module should provide all of the information that you require to be able to compile LightSpeed specific coding standards. - -I also want you to review the following best practices and coding standards: -https://github.com/DekodeInteraktiv/coding-standards -https://10up.github.io/Engineering-Best-Practices/ -https://github.com/10up/Engineering-Best-Practices -https://gutenberg.10up.com/ -http://github.com/10up/gutenberg-best-practices/ -https://github.com/humanmade/coding-standards -https://packagist.org/packages/dekode/coding-standards - -The current version is 3.2.0 and was released on the 25th of July. The github repo is here - http://github.com/wordPress/WordPress-Coding-Standards/ - -The development documentation portal can be found here - https://developer.wordpress.org/coding-standards/ - -I would like you to define coding standard instructions to include clear details about the following: -0. Common coding standards topics that should be defined for all languages: - -- Why have coding standards: - --- https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards.md - -- Naming Conventions - -- Spacing or indentation - -- Commenting - -- White space - -- Formatting - -- Inline documentation - -- Best Practices - -- Reference links -1. Accessibility Coding Standards: - -- Applying WCAG Conformance Levels - -- WCAG 2.2 consists of 4 layers: - --- Principles - --- Guidance - --- Success criteria - --- Sufficient and advisory techniques - -- Reference links: - --- https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards/accessibility.md - --- https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Accessibility/Test_your_skills/CSS_and_JavaScript - --- https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Accessibility/CSS_and_JavaScript - --- https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Accessibility/What_is_accessibility - --- https://developer.wordpress.org/block-editor/how-to-guides/accessibility/ - --- https://github.com/WordPress/gutenberg/edit/trunk/docs/how-to-guides/accessibility.md -2. php: - -- General - -- Spacing - -- Naming Conventions - -- Whitespace - -- Declare Statements, Namespace, and Import Statements - -- Object-Oriented Programming - -- Singletons - -- Control Structures - -- Operators - -- Database - -- Recommendations - -- Comments - -- Formatting - -- References: - --- https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/ - --- https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards/php.md -3. html - -- Validation - -- Spacing - -- Naming Conventions - -- Comments - -- Self-closing Elements - -- Attributes and Tags - -- Quotes - -- Indentation - -- Best practices - -- References: - --- https://developer.wordpress.org/coding-standards/wordpress-coding-standards/html/ - --- https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards/html.md -4. JavaScript - -- Code Refactoring - -- Spacing - -- Semicolons - -- Indentation and Line Breaks - -- Multi-line Statements - -- Chained Method Calls - -- Assignments and Globals - -- Naming Conventions - -- Equality - -- Type Checks - -- Strings - -- Switch Statements - -- JSHint - -- Best Practices - -- Reference links - --- https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards/javascript.md -5. CSS - -- Structure - -- Selectors - -- Values - -- Media Queries - -- Naming connventions - -- Best Practices - -- References: - --- https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/ - --- https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards/css.md - --- https://github.com/necolas/idiomatic-css/blob/master/README.md -6. Inline Documentation Standards - -- Reference links - --- https://jjj.blog/2012/06/inline-documentation/ -6.1 PHP Documentation Standards - -- What Should Be Documented - --- Documenting Tips - --- Formatting Guidelines - -- DocBlock Formatting - -- PHPDoc Tags - -- References: - --- https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/ - --- https://github.com/WordPress/wpcs-docs/blob/master/inline-documentation-standards/php.md -6.2 JavaScript Documentation Standards - -- What Should Be Documented - -- Documenting Tips - -- Formatting Guidelines - -- Functions - -- Backbone classes - -- Local functions - -- Local ancestors - -- Class members - -- Namespaces - -- Inline Comments - -- File Headers - -- Supported JSDoc Tags - -- Unsupported JSDoc Tags - -- References: - --- https://developer.wordpress.org/coding-standards/inline-documentation-standards/javascript/ - --- https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/ - --- https://github.com/WordPress/wpcs-docs/blob/master/inline-documentation-standards/javascript.md -7. Markdown format - -- Headings (Note: h1 - h4 items will be automatically added to the Table of Contents.) - -- Emphasis / formatting - italics, bold, strikethrough - -- Links - -- Blockquotes - -- Lists - ordered, unordered & checkboxes - -- Horizontal Rules - -- Tables - -- Example Code - -- Reference links - --- https://github.com/WordPress/wpcs-docs/blob/master/styleguide.md -8. JSON - -- Reference links: - --- https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/theme-json-reference/styles-versions.md - --- https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/theme-json-reference/theme-json-living.md - --- https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/ - --- Block.json schema - https://github.com/WordPress/gutenberg/blob/trunk/schemas/json/block.json - --- Theme.json schema - https://github.com/WordPress/gutenberg/blob/trunk/schemas/json/theme.json - --- Font collection schema - https://github.com/WordPress/gutenberg/blob/trunk/schemas/json/font-collection.json -8. Fluid spacing & typography - -- Reference links - --- Handling block spacing - https://github.com/10up/gutenberg-best-practices/blob/main/guides/handeling-block-spacing.md - --- Different approaches to fluid typography and spacing - https://crinkles.dev/writing/different-approaches-to-fluid-typography-and-layouts/ - --- https://github.com/lightspeedwp/ls-handbooks/blob/main/docs/block-themes/fluid-spacing.md - --- https://github.com/lightspeedwp/ls-handbooks/blob/main/docs/block-themes/fluid-typography.md - --- https://css-tricks.com/linearly-scale-font-size-with-css-clamp-based-on-the-viewport/ - --- https://www.reddit.com/r/Wordpress/comments/1eaifh4/best_practices_for_measurements_ie_px_em_rem_vw_vh/ - --- https://developer.mozilla.org/en-US/docs/Web/CSS/clamp - --- https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Values_and_units - --- https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units - --- https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Responsive_Design - --- https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Introduction - --- https://developer.mozilla.org/en-US/docs/Web/CSS/length - --- https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Typography - --- https://www.designsystemscollective.com/fluid-typographic-scales-revolutionize-your-responsive-design-0d10ed7f740e - --- https://gutenberg.10up.com/guides/handeling-block-spacing/ diff --git a/coding-standards/ash-research/9-fluid-spacing-typography.md b/coding-standards/ash-research/9-fluid-spacing-typography.md deleted file mode 100644 index e00ec78..0000000 --- a/coding-standards/ash-research/9-fluid-spacing-typography.md +++ /dev/null @@ -1,43 +0,0 @@ -# 9. Fluid Spacing & Typography - -## Goals -- Scale type and spacing smoothly across viewports. -- Reduce brittle breakpoint stacks; prefer fluid curves with sensible clamps. - -## Typography -- Use `clamp(min, preferred, max)` to scale font sizes. -- Base on `rem`; define a typographic scale (e.g., 1.125 or 1.2 ratio). -- Maintain readable line length (45–85 chars) and line height (≈1.4–1.7). - -```css -:root { - /* Example scale */ - --step--1: clamp(0.875rem, 0.85rem + 0.2vw, 1rem); - --step-0: clamp(1rem, 0.95rem + 0.5vw, 1.125rem); - --step-1: clamp(1.125rem, 1rem + 1vw, 1.5rem); -} -h1 { font-size: var(--step-1); } -``` - -## Spacing -- Prefer rem for space tokens; define a scale and expose via CSS vars or theme.json custom properties. -- Use fluid clamp for key blocks when helpful; otherwise scale via responsive presets in theme.json. - -```css -:root { - --space-2xs: clamp(0.25rem, 0.2rem + 0.3vw, 0.5rem); - --space-xs: clamp(0.5rem, 0.4rem + 0.4vw, 0.75rem); - --space-s: clamp(0.75rem, 0.6rem + 0.6vw, 1rem); -} -.section { padding-block: var(--space-s); } -``` -## Gutenberg / theme.json -- Use Theme JSON typography and spacing presets for consistent tokens. -- Avoid pixel-locked values; use presets + fluid scaling where appropriate. - -## References -- LightSpeed: fluid spacing → https://github.com/lightspeedwp/ls-handbooks/blob/main/docs/block-themes/fluid-spacing.md -- LightSpeed: fluid typography → https://github.com/lightspeedwp/ls-handbooks/blob/main/docs/block-themes/fluid-typography.md -- CSS clamp intro: https://css-tricks.com/linearly-scale-font-size-with-css-clamp-based-on-the-viewport/ -- MDN clamp: https://developer.mozilla.org/en-US/docs/Web/CSS/clamp -- 10up Gutenberg best practices: https://gutenberg.10up.com/guides/handeling-block-spacing/ diff --git a/copilot-todo.md b/copilot-todo.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/ai-copilot/README.md b/docs/ai-copilot/README.md new file mode 100644 index 0000000..e69de29 diff --git a/coding-standards/README.md b/docs/coding-standards/README.md similarity index 96% rename from coding-standards/README.md rename to docs/coding-standards/README.md index 9116d77..992b48c 100644 --- a/coding-standards/README.md +++ b/docs/coding-standards/README.md @@ -5,9 +5,11 @@ This folder contains comprehensive coding standards and style guides for WordPre ## 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 @@ -15,19 +17,23 @@ Complete coding standards suite aligned with WordPress Coding Standards (WPCS v3 - 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 +- 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 @@ -35,6 +41,7 @@ Specialized documentation focusing on code commenting and inline documentation p ## 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 @@ -64,4 +71,4 @@ Specialized documentation focusing on code commenting and inline documentation p 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 +These standards ensure consistency, security, and maintainability across all WordPress development projects. diff --git a/docs/coding-standards/_temp.md b/docs/coding-standards/_temp.md new file mode 100644 index 0000000..a1c8667 --- /dev/null +++ b/docs/coding-standards/_temp.md @@ -0,0 +1,167 @@ +I need you to go through all of the links in the references below, and compile in markdown format comprehensive coding standard documents per language, there will be an individual document per language as per the numbering system below. + +The attached documentation and wordpress coding standards module should provide all of the information that you require to be able to compile LightSpeed specific coding standards. + +I also want you to review the following best practices and coding standards: + + + + + + + + +The current version is 3.2.0 and was released on the 25th of July. The github repo is here - + +The development documentation portal can be found here - + +I would like you to define coding standard instructions to include clear details about the following: 0. Common coding standards topics that should be defined for all languages: +-- Why have coding standards: +--- +-- Naming Conventions +-- Spacing or indentation +-- Commenting +-- White space +-- Formatting +-- Inline documentation +-- Best Practices +-- Reference links + +1. Accessibility Coding Standards: + -- Applying WCAG Conformance Levels + -- WCAG 2.2 consists of 4 layers: + --- Principles + --- Guidance + --- Success criteria + --- Sufficient and advisory techniques + -- Reference links: + --- + --- + --- + --- + --- + --- +2. php: + -- General + -- Spacing + -- Naming Conventions + -- Whitespace + -- Declare Statements, Namespace, and Import Statements + -- Object-Oriented Programming + -- Singletons + -- Control Structures + -- Operators + -- Database + -- Recommendations + -- Comments + -- Formatting + -- References: + --- + --- +3. html + -- Validation + -- Spacing + -- Naming Conventions + -- Comments + -- Self-closing Elements + -- Attributes and Tags + -- Quotes + -- Indentation + -- Best practices + -- References: + --- + --- +4. JavaScript + -- Code Refactoring + -- Spacing + -- Semicolons + -- Indentation and Line Breaks + -- Multi-line Statements + -- Chained Method Calls + -- Assignments and Globals + -- Naming Conventions + -- Equality + -- Type Checks + -- Strings + -- Switch Statements + -- JSHint + -- Best Practices + -- Reference links + --- +5. CSS + -- Structure + -- Selectors + -- Values + -- Media Queries + -- Naming connventions + -- Best Practices + -- References: + --- + --- + --- +6. Inline Documentation Standards + -- Reference links + --- + 6.1 PHP Documentation Standards + -- What Should Be Documented + --- Documenting Tips + --- Formatting Guidelines + -- DocBlock Formatting + -- PHPDoc Tags + -- References: + --- + --- + 6.2 JavaScript Documentation Standards + -- What Should Be Documented + -- Documenting Tips + -- Formatting Guidelines + -- Functions + -- Backbone classes + -- Local functions + -- Local ancestors + -- Class members + -- Namespaces + -- Inline Comments + -- File Headers + -- Supported JSDoc Tags + -- Unsupported JSDoc Tags + -- References: + --- + --- + --- +7. Markdown format + -- Headings (Note: h1 - h4 items will be automatically added to the Table of Contents.) + -- Emphasis / formatting - italics, bold, strikethrough + -- Links + -- Blockquotes + -- Lists - ordered, unordered & checkboxes + -- Horizontal Rules + -- Tables + -- Example Code + -- Reference links + --- +8. JSON + -- Reference links: + --- + --- + --- + --- Block.json schema - + --- Theme.json schema - + --- Font collection schema - +9. Fluid spacing & typography + -- Reference links + --- Handling block spacing - + --- Different approaches to fluid typography and spacing - + --- + --- + --- + --- + --- + --- + --- + --- + --- + --- + --- + --- + --- diff --git a/coding-standards/ash-research/0-common-standards.md b/docs/coding-standards/ash-research/0-common-standards.md similarity index 75% rename from coding-standards/ash-research/0-common-standards.md rename to docs/coding-standards/ash-research/0-common-standards.md index 23565fb..b4c4639 100644 --- a/coding-standards/ash-research/0-common-standards.md +++ b/docs/coding-standards/ash-research/0-common-standards.md @@ -3,6 +3,7 @@ **Why standards?** Consistency improves readability, onboarding, maintenance, and review velocity. It reduces cognitive load across projects and teams. ## Golden Rules + - **Indentation**: Use **tabs** to indent. Use **spaces only for alignment** (e.g., lining up parameters). - **Line length**: Aim for ~80–100 chars where practical. - **Whitespace**: No trailing spaces; single blank lines to separate logical sections. @@ -11,12 +12,13 @@ - PHP: functions/vars `snake_case`; classes `UpperCamelCase`; constants `UPPER_SNAKE_CASE`. - JS: variables/functions `camelCase`; classes `UpperCamelCase`. - CSS: classes/IDs lowercase, hyphenated (`.product-card__title` is fine; prefer BEM-ish clarity). -- **Comments & Docs**: Prefer clear code; document *why*, not just *what*. Use DocBlocks for public APIs. +- **Comments & Docs**: Prefer clear code; document _why_, not just _what_. Use DocBlocks for public APIs. - **Security**: Escape on output, sanitise on input, verify nonces/capabilities. - **Performance**: Keep bundles small; lazy-load when useful; avoid unnecessary queries. - **Accessibility**: WCAG 2.2 AA baseline; semantic markup; keyboard & screen-reader support. ## References -- General WPCS overview: https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards.md -- Dev Handbook: https://developer.wordpress.org/coding-standards/ -- 10up EBP: https://10up.github.io/Engineering-Best-Practices/ + +- General WPCS overview: +- Dev Handbook: +- 10up EBP: diff --git a/coding-standards/ash-research/1-accessibility.md b/docs/coding-standards/ash-research/1-accessibility.md similarity index 99% rename from coding-standards/ash-research/1-accessibility.md rename to docs/coding-standards/ash-research/1-accessibility.md index 706a065..62bb9ca 100644 --- a/coding-standards/ash-research/1-accessibility.md +++ b/docs/coding-standards/ash-research/1-accessibility.md @@ -3,12 +3,14 @@ LightSpeed targets **WCAG 2.2 Level AA** across products and content. ## WCAG 2.2 Layers + - **Principles**: Perceivable, Operable, Understandable, Robust. - **Guidelines**: Human-centered rules that map to Success Criteria. - **Success Criteria**: Testable checkpoints at A/AA/AAA. - **Techniques**: Sufficient & advisory patterns to implement criteria. ## Practical Requirements + - **Semantics**: Use proper headings, lists, landmarks (`
`, `