Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Feb 9, 2026 · 4 revisions

DesignSetGo Documentation

Complete reference documentation for developing blocks in the DesignSetGo WordPress plugin.

🚀 Quick Start

For New Contributors

Never contributed before? Start with these guides in order:

  1. GETTING-STARTED.md ⭐ Start here!

    • Complete setup walkthrough
    • Prerequisites and installation
    • Making your first change
    • Common workflows

  2. ARCHITECTURE.md - Understand the codebase

    • Project structure
    • How blocks work
    • Build system
    • Data flow

  3. ../CONTRIBUTING.md - Contribution workflow

    • Code standards
    • Testing requirements
    • Pull request process

For Experienced WordPress Developers

  1. Read BEST-PRACTICES-SUMMARY.md for quick patterns
  2. Review BLOCK-DEVELOPMENT-BEST-PRACTICES-COMPREHENSIVE.md for deep understanding
  3. Check WordPress Block Editor Best Practices when creating new blocks

For AI-Assisted Development

This plugin was built 100% with AI assistance!

  1. AI-ASSISTED-DEVELOPMENT.md ⭐ Complete AI development guide!

    • How this plugin was built with Claude Code
    • Available slash commands (/add-block, /lint, /test, etc.)
    • Best practices for AI-assisted development
    • Common workflows and examples
    • Tips, tricks, and limitations

  2. ../.claude/CLAUDE.md - Development patterns and context

    • Critical patterns AI follows
    • WordPress best practices
    • Project-specific conventions

  3. BEST-PRACTICES-SUMMARY.md - Quick reference

  4. BLOCK-TEMPLATE-EDIT.js - Block template to copy

📁 Folder Organization

The documentation is organized into the following categories:

Core Documentation (Root Level)

Categorized Documentation

api/

API references and technical documentation:

audits/

Block audits and analysis documents:

blocks/

User-facing documentation for blocks:

Container Blocks (3):

  • GRID.md - Responsive CSS Grid layouts
  • ROW.md - Horizontal flexbox containers
  • SECTION.md - Vertical stacking sections

Interactive Blocks (12):

Icon Blocks (3):

Content/UI Blocks (7):

Utility Blocks (3):

Forms (1):

extensions/

Documentation for all 15 block extensions that enhance any WordPress block:

Animation & Effects:

Scroll Effects:

Layout & Positioning:

Interaction:

Responsive & Styling:

compliance/

Accessibility and compliance documentation:

guides/

Development guides and best practices:

patterns/

Design patterns and architectural strategies:

planning/

Roadmaps, strategy, and future planning:

templates/

Code templates and boilerplate:

testing/

Testing documentation and strategies:

troubleshooting/

Debugging and problem-solving guides:

📚 Documentation Structure

Getting Started (New Contributors)

GETTING-STARTED.md

Complete step-by-step guide for new contributors:

  • Software prerequisites: Node.js, Git, Docker Desktop
  • Understanding the stack: What technologies we use and why
  • Step-by-step setup: From fork to first contribution
  • Your first change: Hands-on example walking through a real code change
  • Development tools: npm scripts, VS Code integration, browser DevTools
  • Common workflows: Daily development, updating fork, fixing issues
  • Troubleshooting: Solutions to common setup problems
  • Next steps: Learning resources and finding issues to work on

When to use: First time setting up the project or helping someone else get started.

ARCHITECTURE.md

Deep dive into project architecture and code organization:

  • High-level overview: Technology stack and core components
  • Complete directory structure: Every folder explained with purpose
  • Block architecture: Anatomy of a block, file-by-file breakdown
  • Build system: Webpack, asset compilation, dependency management
  • Data flow: How data moves from editor to database to frontend
  • Extension system: How extensions modify existing blocks
  • PHP backend: Server-side architecture and registration
  • Testing infrastructure: E2E and unit test setup
  • AI integration: WordPress Abilities API architecture

When to use: Understanding how the codebase works, onboarding to the project, or making architectural decisions.

../CONTRIBUTING.md

Complete contribution guide and workflow:

  • Development setup: Prerequisites and step-by-step installation
  • Project architecture: Quick overview with links to detailed docs
  • Development workflow: Creating branches, making changes, testing
  • Code standards: WordPress patterns, project-specific rules
  • Testing requirements: What to test before submitting
  • Submitting changes: Pull request process and checklist
  • Getting help: Where to ask questions and report issues

When to use: Ready to contribute code or submitting a pull request.

AI-ASSISTED-DEVELOPMENT.md

Complete guide to AI-assisted development (how this plugin was built):

  • Why AI-assisted development: Benefits and use cases
  • Getting started with Claude Code: Installation and setup
  • Available slash commands: /add-block, /lint, /test, /deploy, and more
  • Best practices: Effective prompts, iteration, validation
  • Common workflows: Creating blocks, debugging, refactoring with AI
  • Using other AI tools: ChatGPT, GitHub Copilot, Abilities API
  • Tips and tricks: Context management, learning patterns
  • Limitations and validation: When AI makes mistakes, validation checklist

When to use: Using AI tools (Claude Code, ChatGPT, Copilot) to contribute, or curious about how this entire plugin was built with AI.

🎯 Quick Reference Links

Critical Patterns (Read First!)

Color Controls - MOST IMPORTANT ⚠️

Location: ../.claude/CLAUDE.md

Rule: ALWAYS use ColorGradientSettingsDropdown, NEVER use PanelColorSettings

// CORRECT - Modern WordPress pattern
import {
  __experimentalColorGradientSettingsDropdown as ColorGradientSettingsDropdown,
  __experimentalUseMultipleOriginColorsAndGradients as useMultipleOriginColorsAndGradients,
} from '@wordpress/block-editor';

export default function Edit({ attributes, setAttributes, clientId }) {
  const colorGradientSettings = useMultipleOriginColorsAndGradients();

  return (
    <InspectorControls group="color">
      <ColorGradientSettingsDropdown
        panelId={clientId}
        title={__('Colors', 'designsetgo')}
        settings={[
          {
            label: __('Text Color', 'designsetgo'),
            colorValue: textColor,
            onColorChange: (color) =>
              setAttributes({ textColor: color || '' }),
            clearable: true,
          },
        ]}
        {...colorGradientSettings}
      />
    </InspectorControls>
  );
}

Why This Matters:

  • All 13 existing blocks use this pattern (migrated 2025-11-08)
  • PanelColorSettings is deprecated and will be removed
  • Places controls in Styles tab (better UX, WordPress standard)

Reference Documents

BEST-PRACTICES-SUMMARY.md

  • Use for: Quick reference during development
  • Contains: Critical rules, decision trees, copy-paste patterns
  • Read time: 5-10 minutes

BLOCK-DEVELOPMENT-BEST-PRACTICES-COMPREHENSIVE.md

  • Use for: Deep understanding of patterns and rationale
  • Contains: 15 major topics with real-world examples
  • Read time: 30-45 minutes

BLOCK-TEMPLATE-EDIT.js

  • Use for: Starting point for new blocks
  • Contains: Fully commented template with all critical patterns
  • Copy this file when creating new blocks

Specialized Guides

WORDPRESS-BLOCK-EDITOR-BEST-PRACTICES.md

WordPress block editor and FSE compatibility:

  • Block.json configuration
  • Supports properties
  • Testing checklist
  • Pattern creation

BLOCK-CONTROLS-ORGANIZATION.md

Inspector controls organization:

  • Settings tab vs Styles tab
  • Block Supports usage
  • Panel structure

🎯 Common Tasks

Creating a New Block

  1. Copy BLOCK-TEMPLATE-EDIT.js to src/blocks/{block-name}/edit.js
  2. Update block.json with proper supports (see WordPress Block Editor Best Practices)
  3. Implement save.js matching edit.js structure
  4. Add color controls using ColorGradientSettingsDropdown pattern
  5. Test in editor and frontend

Adding Color Controls to Existing Block

  1. Add imports: 
    import {
  __experimentalColorGradientSettingsDropdown as ColorGradientSettingsDropdown,
  __experimentalUseMultipleOriginColorsAndGradients as useMultipleOriginColorsAndGradients,
} from '@wordpress/block-editor';
  2. Add clientId to function signature
  3. Add useMultipleOriginColorsAndGradients() hook
  4. Replace PanelColorSettings with ColorGradientSettingsDropdown in Styles tab

See BLOCK-TEMPLATE-EDIT.js for complete example.

Refactoring Large Files

  1. Check file line count: wc -l src/blocks/{block-name}/edit.js
  2. If >300 lines, extract components and utilities
  3. Extract components into components/ directory
  4. Extract utilities into utils/ directory
  5. Keep index.js focused on registration only

📊 Project Statistics

Block Count

  • Total blocks: 48 (across 6 categories)
  • Container blocks: 3 (Row, Section, Grid)
  • Form blocks: 13 (Form Builder + 11 field types)
  • Interactive blocks: 12 (Accordion, Tabs, Slider, Flip Card, Reveal, Scroll Accordion, Image Accordion, Counter Group, Progress Bar, Scroll Marquee, Comparison Table, Timeline)
  • Content/UI blocks: 10 (Icon, Icon Button, Icon List, Card, Pill, Divider, Countdown Timer, Blobs, Breadcrumbs, Table of Contents)
  • Modal blocks: 2 (Modal, Modal Trigger)
  • Location blocks: 1 (Map)
  • Extensions: 15

Code Quality

  • Color controls: 100% modern (all blocks using ColorGradientSettingsDropdown)
  • Zero PanelColorSettings instances remaining in codebase
  • File size target: < 300 lines per file

🔍 Finding Information

"How do I add color controls?"

→ ../.claude/CLAUDE.md or BLOCK-TEMPLATE-EDIT.js

"What's the proper block structure?"

→ BEST-PRACTICES-SUMMARY.md or BLOCK-DEVELOPMENT-BEST-PRACTICES-COMPREHENSIVE.md

"How do I make my block FSE-compatible?"

→ WordPress Block Editor Best Practices

"My file is too large, how do I refactor?"

→ Best Practices Summary (see file size and extraction patterns)

"Should I use Block Supports or custom controls?"

→ BLOCK-CONTROLS-ORGANIZATION.md

🎓 Learning Path

Beginner

  1. Read BEST-PRACTICES-SUMMARY.md - Critical rules
  2. Copy BLOCK-TEMPLATE-EDIT.js - Build first block
  3. Read WordPress Block Editor Best Practices - Make it compatible

Intermediate

  1. Read BLOCK-DEVELOPMENT-BEST-PRACTICES-COMPREHENSIVE.md - Deep understanding
  2. Review BLOCK-CONTROLS-ORGANIZATION.md - Better UX patterns
  3. Study Design System - Proper styling

Advanced

  1. Review Block Extension Strategy - Extension architecture
  2. Study Color Controls Pattern - Advanced patterns
  3. Contribute patterns back to ../.claude/CLAUDE.md

📝 Contributing to Documentation

When you discover new patterns or best practices:

  1. Critical patterns → Add to ../.claude/CLAUDE.md
  2. Quick reference → Add to BEST-PRACTICES-SUMMARY.md
  3. Deep explanations → Add to BLOCK-DEVELOPMENT-BEST-PRACTICES-COMPREHENSIVE.md
  4. Specialized topics → Create new guide or update existing specialized guide in appropriate folder

Last Updated: 2026-02-06 Plugin Version: 1.4.1 WordPress Compatibility: 6.7+

Auto-generated from docs/README.md. To update, edit the source file and changes will sync on next push to main.

Home

Getting Started

Blocks

Extensions

API Reference

Development Guides

Patterns

Planning & Roadmap

Compliance

Formats

Testing

Troubleshooting

Audits

Plans

GitHub | Report Issue

Clone this wiki locally