+
+```
+
+## Best Practices for Trait Usage
+
+### 1. Start Simple
+Begin with basic traits and add complexity as needed:
+- **Modifier Classes** work automatically (no setup needed)
+- Add **Reduce Bottom Space** if spacing control is needed
+- Add **Icons** or **Color Choices** for enhanced functionality
+
+### 2. Understand Automatic Inclusion
+- **Modifier Classes** trait is automatically included
+- No need to manually add it to your block classes
+- Works seamlessly with the default template wrapper when enabled
+
+### 3. Always Provide Templates
+- **Every block must have a `template()` function**
+- The function must return a valid path to a template file
+- This is required regardless of wrapper settings
+
+### 4. Understand Wrapper Behavior
+- **`use_default_wrapper_template()` controls automatic integration**
+- When `true`: Trait methods are called automatically by the wrapper
+- When `false`: You must manually call trait methods in your templates
+
+### 5. Consider Dependencies
+Always check trait dependencies:
+- **Reduce Bottom Space** requires **Modifier Classes** (automatically included)
+- Some traits work better together than others
+
+### 6. Plan for Performance
+Be mindful of trait combinations:
+- Too many traits can impact performance
+- Consider if all functionality is necessary
+- Use traits that complement each other
+
+### 7. Test Thoroughly
+Always test trait combinations:
+- Verify all functionality works together
+- Test in different contexts and post types
+- Ensure error handling works correctly
+
+### 8. Document Usage
+Keep clear documentation:
+- Document which traits are used
+- Explain any special requirements
+- Provide examples of usage
+
+## Common Patterns
+
+### Content Blocks (Default Wrapper)
+- **Modifier Classes** (automatic) + **Reduce Bottom Space** + **Unique ID**
+- Add **Icons** or **Color Choices** for enhancement
+
+### Navigation Blocks
+- **Editor Restriction** + **Menu Integration** + **Modifier Classes** (automatic)
+
+### Product Blocks
+- **Post Type Restriction** + **Icons** + **Color Choices** + **Modifier Classes** (automatic)
+
+### Layout Blocks
+- **Editor Restriction** + **Modifier Classes** (automatic) + **Block Patterns**
+
+### Hero Sections
+- **Editor Restriction** + **Color Choices** + **Block Patterns** + **Modifier Classes** (automatic)
+
+## Troubleshooting
+
+### Common Issues
+1. **Trait not working** - Check if required dependencies are included
+2. **Performance issues** - Review trait combinations and remove unnecessary ones
+3. **Conflicts** - Ensure traits don't interfere with each other
+4. **Missing functionality** - Verify all required methods are implemented
+
+### Debugging Tips
+1. **Check trait order** - Some traits may need to be loaded in specific order
+2. **Verify dependencies** - Ensure all required traits are included
+3. **Test individually** - Test each trait separately before combining
+4. **Check error logs** - Look for PHP errors or warnings
+5. **Verify automatic inclusion** - Remember that Modifier Classes works automatically
+6. **Check wrapper settings** - Verify `use_default_wrapper_template()` returns the expected value
+7. **Ensure template function exists** - Every block must have a `template()` method
+
+## Conclusion
+
+The trait system provides a powerful and flexible way to extend block functionality. By understanding how traits work together and following best practices, you can create sophisticated blocks that are both powerful and maintainable.
+
+**Key Points:**
+- **Modifier Classes** trait works automatically with the default wrapper when enabled
+- **All blocks must provide a template function** - this is always required
+- **`use_default_wrapper_template()` controls automatic integration** - understand when it affects trait behavior
+- Start simple and add complexity gradually
+- Always check dependencies and requirements
+- Test thoroughly in different contexts
+- Document your usage and requirements
+- Consider performance implications
+- Use traits that complement each other
+
+With these guidelines, you'll be able to create blocks that leverage the full power of the trait system while maintaining clean, maintainable code.
diff --git a/docs/block-traits/traits/block-patterns.md b/docs/block-traits/traits/block-patterns.md
new file mode 100644
index 0000000..b26a3c7
--- /dev/null
+++ b/docs/block-traits/traits/block-patterns.md
@@ -0,0 +1,422 @@
+---
+title: Block Pattern Options Trait
+editLink: false
+---
+
+# Block Pattern Options Trait
+
+The `Trait_Block_Pattern_Options` provides blocks with the ability to reference and render reusable block patterns, allowing content editors to insert predefined content structures while maintaining consistency across the site.
+
+## Purpose
+
+This trait is designed to:
+- Allow blocks to reference reusable block patterns
+- Provide ACF field options for pattern selection
+- Enable dynamic pattern rendering within blocks
+- Maintain consistency across different content areas
+- Simplify content management for editors
+
+## How It Works
+
+The trait automatically:
+1. Scans for available reusable blocks (patterns) in the database
+2. Generates ACF choice fields with pattern options
+3. Provides methods to render patterns by slug
+4. Supports both direct pattern rendering and post-context rendering
+5. Integrates with WordPress's reusable block system
+
+## Usage
+
+### Basic Implementation
+
+```php
+ 'field_my_block_pattern',
+ 'name' => 'pattern',
+ 'label' => 'Content Pattern',
+ 'type' => 'select',
+ 'choices' => $this->get_block_pattern_choices(),
+ ),
+ );
+ }
+}
+```
+
+### Rendering Patterns in Templates
+
+```php
+get_field( 'pattern' );
+
+if ( ! empty( $pattern_slug ) ) {
+ $this->render_block_pattern( $pattern_slug );
+}
+?>
+```
+
+## Available Methods
+
+### `get_block_pattern_choices()`
+
+Returns all configured block patterns for use in ACF select fields.
+
+**Returns:** `array` - An array of pattern choices with slugs as keys and titles as values
+
+**Example:**
+```php
+$choices = $this->get_block_pattern_choices();
+// Returns: array(
+// '' => 'None',
+// 'hero-section' => 'Hero Section',
+// 'feature-grid' => 'Feature Grid',
+// 'testimonial' => 'Testimonial',
+// )
+```
+
+### `render_block_pattern( string $block_pattern_slug )`
+
+Renders a block pattern by slug.
+
+**Parameters:**
+- `$block_pattern_slug` (string) - The slug of the pattern to render
+
+**Returns:** `void` - Outputs the pattern HTML directly
+
+**Example:**
+```php
+$this->render_block_pattern( 'hero-section' );
+```
+
+### `render_block_pattern_in_post_context( int $post_id, string $block_pattern_slug )`
+
+Renders a block pattern in the context of a specific post.
+
+**Parameters:**
+- `$post_id` (int) - The ID of the post to render the pattern in context of
+- `$block_pattern_slug` (string) - The slug of the pattern to render
+
+**Returns:** `void` - Outputs the pattern HTML directly
+
+**Example:**
+```php
+$this->render_block_pattern_in_post_context( 123, 'related-posts' );
+```
+
+## Creating Reusable Block Patterns
+
+Before using this trait, you need to create reusable block patterns in WordPress:
+
+### Method 1: Block Editor
+
+1. Create a new post with the "Reusable" block type
+2. Build your pattern using blocks
+3. Save it with a descriptive name
+4. The pattern will be available for selection
+
+### Method 2: Programmatically
+
+```php
+
+
+```
+
+## CSS Integration
+
+### Basic Color Classes
+
+```scss
+.my-block {
+ // Base styles
+
+ &--bg-primary {
+ background-color: var(--wp--preset--color--primary);
+ }
+
+ &--bg-secondary {
+ background-color: var(--wp--preset--color--secondary);
+ }
+
+ &--text-primary {
+ color: var(--wp--preset--color--primary);
+ }
+
+ &--text-secondary {
+ color: var(--wp--preset--color--secondary);
+ }
+}
+```
+
+### Using CSS Custom Properties
+
+```scss
+.my-block {
+ &--bg-primary {
+ background-color: var(--wp--preset--color--primary);
+ }
+
+ &--bg-secondary {
+ background-color: var(--wp--preset--color--secondary);
+ }
+
+ &--bg-accent {
+ background-color: var(--wp--preset--color--accent);
+ }
+}
+```
+
+### Responsive Color Variations
+
+```scss
+.my-block {
+ &--bg-primary {
+ background-color: var(--wp--preset--color--primary);
+
+ @media (max-width: 768px) {
+ background-color: var(--wp--preset--color--secondary);
+ }
+ }
+}
+```
+
+## Use Cases
+
+### Content Blocks with Color Themes
+
+```php
+ 'field_content_block_theme',
+ 'name' => 'theme',
+ 'label' => 'Color Theme',
+ 'type' => 'radio',
+ 'choices' => $this->get_color_choices(),
+ ),
+ );
+ }
+}
+```
+
+### Call-to-Action Buttons
+
+```php
+ 'field_cta_button_background',
+ 'name' => 'background_color',
+ 'label' => 'Button Background',
+ 'type' => 'radio',
+ 'choices' => $this->get_color_choices(),
+ ),
+ array(
+ 'key' => 'field_cta_button_text',
+ 'name' => 'text_color',
+ 'label' => 'Button Text Color',
+ 'type' => 'radio',
+ 'choices' => $this->get_color_choices(),
+ ),
+ );
+ }
+}
+```
+
+### Section Backgrounds
+
+```php
+ 'field_section_background',
+ 'name' => 'background_color',
+ 'label' => 'Section Background',
+ 'type' => 'radio',
+ 'choices' => $this->get_color_choices(),
+ ),
+ );
+ }
+}
+```
+
+## Admin Interface
+
+The trait automatically adds CSS to the admin head to style the color choice preview elements:
+
+```css
+.color-choice-preview {
+ display: inline-block;
+ width: 12px;
+ height: 12px;
+ margin-right: 7px;
+ border: solid 1px black;
+}
+```
+
+This creates small color squares next to each color option in the ACF field, making it easy for content editors to see the actual colors.
+
+## Error Handling
+
+The trait gracefully handles various scenarios:
+
+- **No theme colors:** Returns empty choices array
+- **Invalid color slug:** Returns empty string for color code
+- **Missing theme.json:** Falls back gracefully
+- **Color not found:** Returns empty string
+
+## Best Practices
+
+1. **Use semantic names** - Choose color names that describe their purpose (e.g., "primary", "secondary", "accent")
+2. **Limit color options** - Don't overwhelm editors with too many color choices
+3. **Consider accessibility** - Ensure sufficient contrast between text and background colors
+4. **Test color combinations** - Verify that all color combinations work well together
+5. **Document color usage** - Let editors know when and how to use different colors
+6. **Use CSS custom properties** - Leverage WordPress CSS custom properties for consistent theming
+
+## Common Color Patterns
+
+- **Primary/Secondary:** Main brand colors
+- **Accent:** Highlight and call-to-action colors
+- **Neutral:** Text and background colors
+- **Semantic:** Success, warning, error colors
+- **Brand:** Company-specific color schemes
diff --git a/docs/block-traits/traits/editor-restriction.md b/docs/block-traits/traits/editor-restriction.md
index a08aeda..716d531 100644
--- a/docs/block-traits/traits/editor-restriction.md
+++ b/docs/block-traits/traits/editor-restriction.md
@@ -1,6 +1,432 @@
---
-title: Editor Restriction
+title: Editor Restriction Trait
editLink: false
---
-# Editor Restriction
+# Editor Restriction Trait
+
+The `Trait_Restrict_To_Editor_Context` provides blocks with the ability to control where they can be used within the WordPress block editor, allowing developers to restrict blocks to specific editor contexts like the site editor or post editor.
+
+## Purpose
+
+This trait is designed to:
+- Control block availability in different editor contexts
+- Restrict blocks to specific editing environments
+- Improve user experience by showing only relevant blocks
+- Prevent blocks from being used in inappropriate contexts
+- Support modern WordPress block editor workflows
+
+## How It Works
+
+The trait automatically:
+1. Integrates with WordPress block editor context system
+2. Filters block availability based on editor context
+3. Provides convenient methods for common restrictions
+4. Handles context detection and filtering
+5. Works with both site and post editors
+
+## Usage
+
+### Basic Implementation
+
+```php
+restrict_to_site_editor();
+ }
+}
+```
+
+### Restricting to Post Editor Only
+
+```php
+restrict_to_post_editor();
+ }
+}
+```
+
+### Custom Editor Context Restriction
+
+```php
+restrict_to_editor_context( 'core/edit-widgets' );
+ }
+}
+```
+
+## Available Methods
+
+### `restrict_to_site_editor()`
+
+Restricts block availability to the site editor only.
+
+**Returns:** `void`
+
+**Example:**
+```php
+$this->restrict_to_site_editor();
+```
+
+### `restrict_to_post_editor()`
+
+Restricts block availability to the post editor only.
+
+**Returns:** `void`
+
+**Example:**
+```php
+$this->restrict_to_post_editor();
+```
+
+### `restrict_to_editor_context( string $editor_context_name )`
+
+Restricts block availability to a specified editor context.
+
+**Parameters:**
+- `$editor_context_name` (string) - The name of the editor context
+
+**Returns:** `void`
+
+**Example:**
+```php
+$this->restrict_to_editor_context( 'core/edit-site' );
+```
+
+## Editor Contexts
+
+WordPress provides several editor contexts that you can restrict blocks to:
+
+### Common Editor Contexts
+
+- **`core/edit-post`** - Post and page editor
+- **`core/edit-site`** - Site editor (FSE)
+- **`core/edit-widgets`** - Widget editor
+- **`core/customize-widgets`** - Customizer widget editor
+
+### Custom Editor Contexts
+
+You can also create custom editor contexts for specific use cases:
+
+```php
+
+```
+
+## Use Cases
+
+### Site-Only Blocks
+
+```php
+restrict_to_site_editor();
+ }
+
+ protected function name(): string {
+ return 'header';
+ }
+
+ protected function label(): string {
+ return 'Header';
+ }
+}
+?>
+```
+
+### Post-Only Blocks
+
+```php
+restrict_to_post_editor();
+ }
+
+ protected function name(): string {
+ return 'content';
+ }
+
+ protected function label(): string {
+ return 'Content';
+ }
+}
+?>
+```
+
+### Widget-Only Blocks
+
+```php
+restrict_to_editor_context( 'core/edit-widgets' );
+ }
+
+ protected function name(): string {
+ return 'widget';
+ }
+
+ protected function label(): string {
+ return 'Widget';
+ }
+}
+?>
+```
+
+### Conditional Restrictions
+
+```php
+restrict_to_site_editor();
+ } else {
+ $this->restrict_to_post_editor();
+ }
+ }
+}
+?>
+```
+
+## Advanced Usage
+
+### Dynamic Context Detection
+
+```php
+auto_detect_context();
+ }
+
+ private function auto_detect_context() {
+ // Check if we're in a site editor context
+ if ( function_exists( 'wp_is_block_theme' ) && wp_is_block_theme() ) {
+ $this->restrict_to_site_editor();
+ } else {
+ $this->restrict_to_post_editor();
+ }
+ }
+}
+?>
+```
+
+### Multiple Context Support
+
+```php
+allow_multiple_contexts();
+ }
+
+ private function allow_multiple_contexts() {
+ // This block can be used in multiple contexts
+ // No restrictions applied
+ }
+}
+?>
+```
+
+### Context-Based Field Display
+
+```php
+restrict_to_site_editor();
+ }
+
+ protected function fields(): array {
+ $fields = array();
+
+ // Add context-specific fields
+ if ( $this->is_site_editor_context() ) {
+ $fields[] = array(
+ 'key' => 'field_global_setting',
+ 'name' => 'global_setting',
+ 'label' => 'Global Setting',
+ 'type' => 'text',
+ );
+ }
+
+ return $fields;
+ }
+
+ private function is_site_editor_context(): bool {
+ // Check if we're in site editor context
+ return defined( 'WP_IS_SITE_EDITOR' ) && WP_IS_SITE_EDITOR;
+ }
+}
+?>
+```
+
+## Integration with Other Traits
+
+### With Menu Integration
+
+```php
+restrict_to_site_editor();
+ }
+
+ protected function fields(): array {
+ return array(
+ array(
+ 'key' => 'field_navigation_menu',
+ 'name' => 'menu_location',
+ 'label' => 'Menu to Display',
+ 'type' => 'select',
+ 'choices' => $this->get_menu_choices(),
+ ),
+ );
+ }
+}
+?>
+```
+
+### With Icon Support
+
+```php
+ 'Star',
+ 'heart' => 'Heart',
+ );
+ }
+}
+?>
+```
+
+## Error Handling
+
+The trait gracefully handles various scenarios:
+
+- **Invalid context names:** Gracefully handles unknown editor contexts
+- **Context detection failure:** Falls back to allowing the block everywhere
+- **Filter conflicts:** Works alongside other block filtering systems
+- **Missing editor context:** Handles cases where context is not available
+
+## Best Practices
+
+1. **Choose appropriate contexts** - Restrict blocks to contexts where they make sense
+2. **Consider user experience** - Don't overly restrict blocks unless necessary
+3. **Test restrictions** - Verify blocks appear/disappear in correct contexts
+4. **Document restrictions** - Let developers know where blocks can be used
+5. **Plan for flexibility** - Consider if blocks might be useful in multiple contexts
+6. **Follow WordPress patterns** - Use standard context names when possible
+
+## Common Restriction Patterns
+
+- **Global blocks** → Site editor only
+- **Content blocks** → Post editor only
+- **Layout blocks** → Site editor only
+- **Widget blocks** → Widget editor only
+- **Navigation blocks** → Site editor only
+- **Footer blocks** → Site editor only
diff --git a/docs/block-traits/traits/icons.md b/docs/block-traits/traits/icons.md
new file mode 100644
index 0000000..14b6495
--- /dev/null
+++ b/docs/block-traits/traits/icons.md
@@ -0,0 +1,379 @@
+---
+title: Icons Trait
+editLink: false
+---
+
+# Icons Trait
+
+The `Trait_Has_Icons` provides comprehensive icon management capabilities for blocks, including icon selection fields, rendering methods, and file location handling.
+
+## Purpose
+
+This trait is designed to:
+- Add icon selection capabilities to blocks
+- Provide standardized icon rendering methods
+- Handle icon file location and validation
+- Integrate with ACF fields for easy content editing
+- Support both IMG and SVG rendering methods
+
+## How It Works
+
+The trait automatically:
+1. Provides methods to define available icons
+2. Generates ACF field schemas for icon selection
+3. Handles icon file location resolution
+4. Offers multiple rendering methods (IMG and SVG)
+5. Integrates with theme icon directories
+
+## Usage
+
+### Basic Implementation
+
+```php
+ 'Arrow Right',
+ 'checkmark' => 'Checkmark',
+ 'star' => 'Star',
+ 'heart' => 'Heart',
+ 'download' => 'Download',
+ );
+ }
+}
+```
+
+### Adding Icon Fields
+
+Use the `get_icon_field_schema()` method to create ACF fields:
+
+```php
+get_icon_field_schema(
+ 'field_my_block_icon',
+ true, // Include "None" option
+ 'icon' // Field name
+ ),
+ );
+ }
+
+ private function icons(): array {
+ return array(
+ 'arrow-right' => 'Arrow Right',
+ 'checkmark' => 'Checkmark',
+ 'star' => 'Star',
+ );
+ }
+}
+```
+
+## Available Methods
+
+### `icons()`
+
+Private method that returns a keyed array of available icons.
+
+**Returns:** `array` - Keyed array where keys are icon references and values are human-readable names
+
+**Example:**
+```php
+private function icons(): array {
+ return array(
+ 'arrow-right' => 'Arrow Right',
+ 'checkmark' => 'Checkmark',
+ );
+}
+```
+
+### `get_icon_field_schema( string $key, bool $include_none = false, string $name = 'icon' )`
+
+Returns an ACF field schema for the icon field.
+
+**Parameters:**
+- `$key` (string) - The ACF field key
+- `$include_none` (bool) - Whether to include a "None" option. Defaults to `false`
+- `$name` (string) - The ACF field name. Defaults to `"icon"`
+
+**Returns:** `array` - The ACF field schema
+
+**Example:**
+```php
+$field = $this->get_icon_field_schema(
+ 'field_my_block_icon',
+ true, // Include "None" option
+ 'icon' // Field name
+);
+```
+
+### `get_icon_img( string $base_class = 'example-block', bool $use_default = true, string $field_name = 'icon' )`
+
+Returns HTML for an icon using an IMG element.
+
+**Parameters:**
+- `$base_class` (string) - Base string for element classes. Defaults to `'example-block'`
+- `$use_default` (bool) - Whether to use the default icon if the field is empty. Defaults to `true`
+- `$field_name` (string) - Name of the field containing the icon reference. Defaults to `"icon"`
+
+**Returns:** `string` - The icon HTML or empty string if icon is not set
+
+**Example:**
+```php
+$icon_html = $this->get_icon_img( 'my-block', true, 'icon' );
+```
+
+### `get_icon_svg( string $base_class = 'example-block', bool $use_default = true, string $field_name = 'icon' )`
+
+Returns HTML for an icon using an SVG element.
+
+**Parameters:**
+- `$base_class` (string) - Base string for element classes. Defaults to `'example-block'`
+- `$use_default` (bool) - Whether to use the default icon if the field is empty. Defaults to `true`
+- `$field_name` (string) - Name of the field containing the icon reference. Defaults to `"icon"`
+
+**Returns:** `string` - The icon HTML or empty string if icon is not set
+
+**Example:**
+```php
+$icon_html = $this->get_icon_svg( 'my-block', true, 'icon' );
+```
+
+### `get_icon_name( string $icon )`
+
+Returns the human-readable name of an icon.
+
+**Parameters:**
+- `$icon` (string) - Unique reference to a particular icon
+
+**Returns:** `string` - Human-readable icon name or empty string if invalid
+
+**Example:**
+```php
+$icon_name = $this->get_icon_name( 'arrow-right' ); // Returns: "Arrow Right"
+```
+
+### `get_color_code_by_slug( string $slug )`
+
+Returns a theme color code by color slug.
+
+**Parameters:**
+- `$slug` (string) - The slug of the color
+
+**Returns:** `string` - The color code or empty string if color cannot be found
+
+**Example:**
+```php
+$color_code = $this->get_color_code_by_slug( 'primary' ); // Returns: "#007cba"
+```
+
+## Icon File Locations
+
+The trait automatically searches for icon files in the following locations:
+
+1. **Child Theme:** `{child-theme}/images/icons/default/{icon-name}.svg`
+2. **Parent Theme:** `{parent-theme}/images/icons/default/{icon-name}.svg`
+
+### Custom Icon Locations
+
+You can customize icon locations using the `creode_blocks_icon_locations` filter:
+
+```php
+ get_stylesheet_directory() . '/custom-icons/' . $icon . '.svg',
+ 'url' => get_stylesheet_directory_uri() . '/custom-icons/' . $icon . '.svg',
+ );
+
+ return $locations;
+}, 10, 2 );
+```
+
+## Template Usage
+
+### Basic Icon Rendering
+
+```php
+get_icon_img( 'my-block' );
+
+// Render icon as SVG element
+echo $this->get_icon_svg( 'my-block' );
+```
+
+### With Conditional Logic
+
+```php
+get_field( 'icon' );
+
+if ( ! empty( $icon ) ) {
+ echo $this->get_icon_img( 'my-block', false );
+}
+```
+
+### Custom Field Names
+
+```php
+get_icon_img( 'my-block', true, 'custom_icon_field' );
+```
+
+## CSS Integration
+
+### Basic Icon Styling
+
+```scss
+.my-block__icon-img-wrapper {
+ display: inline-block;
+ vertical-align: middle;
+
+ &--arrow-right {
+ // Specific styles for arrow-right icon
+ }
+
+ &--checkmark {
+ // Specific styles for checkmark icon
+ }
+}
+
+.my-block__icon-image {
+ width: 24px;
+ height: 24px;
+ display: block;
+}
+```
+
+### SVG Icon Styling
+
+```scss
+.my-block__icon-svg-wrapper {
+ display: inline-block;
+ vertical-align: middle;
+
+ svg {
+ width: 24px;
+ height: 24px;
+ fill: currentColor;
+ }
+
+ &--arrow-right {
+ svg {
+ transform: rotate(0deg);
+ }
+ }
+}
+```
+
+## Use Cases
+
+### Feature Lists
+
+```php
+ 'Checkmark',
+ 'star' => 'Star',
+ 'heart' => 'Heart',
+ );
+ }
+}
+```
+
+### Call-to-Action Buttons
+
+```php
+ 'Arrow Right',
+ 'download' => 'Download',
+ 'play' => 'Play',
+ );
+ }
+}
+```
+
+### Navigation Elements
+
+```php
+ 'Menu',
+ 'search' => 'Search',
+ 'user' => 'User',
+ 'shopping-cart' => 'Shopping Cart',
+ );
+ }
+}
+```
+
+## Error Handling
+
+The trait includes comprehensive error handling:
+
+- **File not found:** Throws an exception with possible locations
+- **Invalid icon reference:** Returns empty string for invalid icons
+- **Missing field:** Gracefully handles empty icon fields
+- **Network errors:** Handles SVG loading failures gracefully
+
+## Best Practices
+
+1. **Use descriptive names** - Choose clear, human-readable icon names
+2. **Organize icons logically** - Group related icons together
+3. **Provide fallbacks** - Always include a default icon option
+4. **Optimize SVG files** - Ensure SVG files are optimized for web use
+5. **Test icon rendering** - Verify icons display correctly in all contexts
+6. **Consider accessibility** - Provide meaningful alt text for icon images
+
+## Common Icon Patterns
+
+- **Navigation:** `menu`, `close`, `arrow-left`, `arrow-right`
+- **Actions:** `download`, `upload`, `play`, `pause`, `stop`
+- **Status:** `checkmark`, `cross`, `warning`, `info`
+- **Social:** `facebook`, `twitter`, `instagram`, `linkedin`
+- **Content:** `image`, `video`, `document`, `link`
diff --git a/docs/block-traits/traits/menu-rendering.md b/docs/block-traits/traits/menu-rendering.md
index fe5ab51..cf37dfe 100644
--- a/docs/block-traits/traits/menu-rendering.md
+++ b/docs/block-traits/traits/menu-rendering.md
@@ -1,6 +1,490 @@
---
-title: Menu Rendering
+title: Menu Integration Trait
editLink: false
---
-# Menu Rendering
\ No newline at end of file
+# Menu Integration Trait
+
+The `Trait_Menu_Integration` provides blocks with the ability to work with WordPress navigation menus, including menu selection fields, rendering methods, and location-based menu management.
+
+## Purpose
+
+This trait is designed to:
+- Allow blocks to integrate with WordPress navigation menus
+- Provide ACF field options for menu selection
+- Enable dynamic menu rendering within blocks
+- Support menu location-based rendering
+- Simplify menu integration for content editors
+
+## How It Works
+
+The trait automatically:
+1. Scans for available WordPress menu locations
+2. Generates ACF choice fields with menu options
+3. Provides methods to render menus by location
+4. Handles menu ID resolution and validation
+5. Integrates with WordPress's menu system
+
+## Usage
+
+### Basic Implementation
+
+```php
+ 'field_my_block_menu',
+ 'name' => 'menu_location',
+ 'label' => 'Menu to Display',
+ 'type' => 'select',
+ 'choices' => $this->get_menu_choices(),
+ ),
+ );
+ }
+}
+```
+
+### Rendering Menus in Templates
+
+```php
+get_field( 'menu_location' );
+
+if ( ! empty( $menu_location ) ) {
+ $this->render_menu_by_location( $menu_location );
+}
+?>
+```
+
+## Available Methods
+
+### `get_menu_choices()`
+
+Returns all WordPress menu locations for use in ACF select fields.
+
+**Returns:** `array` - An array of menu choices with locations as keys and names as values
+
+**Example:**
+```php
+$choices = $this->get_menu_choices();
+// Returns: array(
+// '' => 'None',
+// 'primary' => 'Primary Menu',
+// 'footer' => 'Footer Menu',
+// 'mobile' => 'Mobile Menu',
+// )
+```
+
+### `render_menu_by_location( string $location, array $args = array() )`
+
+Renders a menu by menu location.
+
+**Parameters:**
+- `$location` (string) - The menu location
+- `$args` (array) - Optional array of arguments for rendering the menu
+
+**Returns:** `void` - Outputs the menu HTML directly
+
+**Example:**
+```php
+$this->render_menu_by_location( 'primary' );
+```
+
+### `get_menu_id_by_location( string $location )`
+
+Returns the ID of a menu assigned to a specified location.
+
+**Parameters:**
+- `$location` (string) - The menu location
+
+**Returns:** `int|null` - The menu ID or null if menu cannot be found
+
+**Example:**
+```php
+$menu_id = $this->get_menu_id_by_location( 'primary' );
+// Returns: 123 or null
+```
+
+## WordPress Menu Setup
+
+Before using this trait, you need to register menu locations in your theme:
+
+### Registering Menu Locations
+
+```php
+ 'Primary Menu',
+ 'footer' => 'Footer Menu',
+ 'mobile' => 'Mobile Menu',
+ 'sidebar' => 'Sidebar Menu',
+ ) );
+}
+add_action( 'after_setup_theme', 'my_theme_setup' );
+```
+
+### Assigning Menus to Locations
+
+1. Go to **Appearance > Menus** in WordPress admin
+2. Create or select a menu
+3. In the "Menu Settings" section, check the desired location
+4. Save the menu
+
+## Template Usage
+
+### Basic Menu Rendering
+
+```php
+get_field( 'menu_location' );
+
+if ( ! empty( $menu_location ) ) {
+ ?>
+
+
+```
+
+### Custom Menu Arguments
+
+```php
+get_field( 'menu_location' );
+
+if ( ! empty( $menu_location ) ) {
+ $menu_args = array(
+ 'container_class' => 'my-block__menu-container',
+ 'menu_class' => 'my-block__menu-list',
+ 'fallback_cb' => false,
+ );
+
+ $this->render_menu_by_location( $menu_location, $menu_args );
+}
+?>
+```
+
+### Conditional Menu Rendering
+
+```php
+get_field( 'show_menu' );
+$menu_location = $this->get_field( 'menu_location' );
+
+if ( $show_menu && ! empty( $menu_location ) ) {
+ ?>
+
+
Navigation
+ render_menu_by_location( $menu_location ); ?>
+
+
+```
+
+### Multiple Menu Support
+
+```php
+get_field( 'primary_menu' );
+$secondary_menu = $this->get_field( 'secondary_menu' );
+?>
+
+
+
+
+
+
+
+
+
+
+```
+
+## Use Cases
+
+### Navigation Blocks
+
+```php
+ 'field_navigation_menu',
+ 'name' => 'menu_location',
+ 'label' => 'Menu to Display',
+ 'type' => 'select',
+ 'choices' => $this->get_menu_choices(),
+ 'instructions' => 'Choose which menu to display in this navigation block.',
+ ),
+ );
+ }
+}
+```
+
+### Footer Menu Blocks
+
+```php
+ 'field_footer_menu',
+ 'name' => 'footer_menu',
+ 'label' => 'Footer Menu',
+ 'type' => 'select',
+ 'choices' => $this->get_menu_choices(),
+ ),
+ );
+ }
+}
+```
+
+### Sidebar Navigation
+
+```php
+ 'field_sidebar_menu',
+ 'name' => 'sidebar_menu',
+ 'label' => 'Sidebar Menu',
+ 'type' => 'select',
+ 'choices' => $this->get_menu_choices(),
+ ),
+ );
+ }
+}
+```
+
+## CSS Integration
+
+### Basic Menu Styling
+
+```scss
+.my-block__navigation {
+ margin: 1rem 0;
+
+ .my-block__menu-container {
+ // Container styles
+ }
+
+ .my-block__menu-list {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+
+ li {
+ margin: 0.5rem 0;
+
+ a {
+ text-decoration: none;
+ color: inherit;
+ padding: 0.5rem;
+ display: block;
+
+ &:hover {
+ background-color: rgba(0, 0, 0, 0.1);
+ }
+ }
+ }
+ }
+}
+```
+
+### Responsive Menu Handling
+
+```scss
+.my-block__navigation {
+ .my-block__menu-list {
+ @media (min-width: 768px) {
+ flex-direction: row;
+
+ li {
+ margin: 0 1rem 0 0;
+ }
+ }
+ }
+}
+```
+
+### Menu State Styling
+
+```scss
+.my-block__navigation {
+ .my-block__menu-list {
+ li {
+ &.current-menu-item {
+ a {
+ font-weight: bold;
+ color: var(--wp--preset--color--primary);
+ }
+ }
+
+ &.current-menu-parent {
+ a {
+ color: var(--wp--preset--color--secondary);
+ }
+ }
+ }
+ }
+}
+```
+
+## Advanced Usage
+
+### Custom Menu Walker
+
+```php
+ 'field_custom_menu',
+ 'name' => 'custom_menu',
+ 'label' => 'Custom Menu',
+ 'type' => 'select',
+ 'choices' => $this->get_menu_choices(),
+ ),
+ );
+ }
+
+ public function render() {
+ $menu_location = $this->get_field( 'custom_menu' );
+
+ if ( ! empty( $menu_location ) ) {
+ $menu_args = array(
+ 'walker' => new Custom_Menu_Walker(),
+ 'container_class' => 'custom-menu-container',
+ );
+
+ $this->render_menu_by_location( $menu_location, $menu_args );
+ }
+ }
+}
+?>
+```
+
+### Dynamic Menu Filtering
+
+```php
+
+```
+
+### Menu Context Switching
+
+```php
+ 'field_context_menu',
+ 'name' => 'context_menu',
+ 'label' => 'Context Menu',
+ 'type' => 'select',
+ 'choices' => $this->get_menu_choices(),
+ ),
+ );
+ }
+
+ public function render() {
+ $menu_location = $this->get_field( 'context_menu' );
+
+ if ( ! empty( $menu_location ) ) {
+ // Add context-specific menu arguments
+ $menu_args = array();
+
+ if ( is_front_page() ) {
+ $menu_args['container_class'] = 'homepage-menu';
+ } elseif ( is_page() ) {
+ $menu_args['container_class'] = 'page-menu';
+ }
+
+ $this->render_menu_by_location( $menu_location, $menu_args );
+ }
+ }
+}
+?>
+```
+
+## Error Handling
+
+The trait gracefully handles various scenarios:
+
+- **No menu assigned:** Displays "No menu found." message
+- **Invalid location:** Gracefully handles missing menu locations
+- **Menu rendering failure:** Continues execution without breaking
+- **No menu locations:** Returns empty choices array
+
+## Best Practices
+
+1. **Register meaningful locations** - Use descriptive names for menu locations
+2. **Test menu rendering** - Verify menus display correctly in different contexts
+3. **Consider mobile experience** - Ensure menus work well on all devices
+4. **Use semantic markup** - Leverage proper HTML5 navigation elements
+5. **Plan menu structure** - Design menus with clear hierarchy and purpose
+6. **Test menu states** - Verify current page highlighting works correctly
+
+## Common Menu Patterns
+
+- **Primary Navigation:** Main site navigation
+- **Footer Links:** Secondary navigation and legal links
+- **Mobile Menu:** Collapsible mobile navigation
+- **Sidebar Navigation:** Context-specific navigation
+- **Breadcrumbs:** Page hierarchy navigation
+- **Social Links:** Social media and external links
\ No newline at end of file
diff --git a/docs/block-traits/traits/modifier-classes.md b/docs/block-traits/traits/modifier-classes.md
index 3041e91..3f5354c 100644
--- a/docs/block-traits/traits/modifier-classes.md
+++ b/docs/block-traits/traits/modifier-classes.md
@@ -1,6 +1,432 @@
---
-title: Modifier Classes
+title: Modifier Classes Trait
editLink: false
---
-# Modifier Classes
+# Modifier Classes Trait
+
+The `Trait_Has_Modifier_Classes` provides a systematic way to manage CSS modifier classes for blocks, allowing for flexible styling variations based on block configuration or user selections.
+
+## Important Notes
+
+**This trait is automatically included in the `Creode_Blocks\Block` abstract class by default.** You do not need to explicitly add it to your block classes unless you want to override its behavior.
+
+**Important:** The automatic calling of `get_modifier_class_string()` only happens when the `use_default_wrapper_template()` method returns `true`. When this method returns `true`, the contents of your template file are automatically enclosed within the default block wrapper template, which calls `get_modifier_class_string()` automatically.
+
+**All blocks must always provide a `template()` function that returns a valid path to a template file.** The `use_default_wrapper_template()` method only determines whether your template content is wrapped in the default wrapper.
+
+## Purpose
+
+This trait is designed to:
+- Generate consistent CSS modifier class names
+- Allow blocks to have multiple visual variations
+- Provide a standardized approach to CSS class management
+- Enable dynamic class generation based on block fields
+- Automatically integrate with the default block wrapper system when enabled
+
+## How It Works
+
+The trait follows a BEM (Block Element Modifier) naming convention and automatically generates modifier classes by appending them to a base class. It integrates with WordPress filters to allow dynamic modification of classes.
+
+**Automatic Integration:** When `use_default_wrapper_template()` returns `true`, modifier classes are automatically applied to the block's wrapper element through the default wrapper template.
+
+**Manual Integration:** When `use_default_wrapper_template()` returns `false`, you must manually call `get_modifier_class_string()` in your template files.
+
+## Usage
+
+### Automatic Integration (Default Wrapper Enabled)
+
+When `use_default_wrapper_template()` returns `true` (the default behavior):
+
+```php
+
+```
+
+**What happens:**
+1. Your template file (`block.php`) contains only the block content
+2. The default wrapper automatically encloses your content
+3. Modifier classes are automatically applied to the wrapper
+4. No manual template code needed for modifier classes
+
+### Manual Integration (Default Wrapper Disabled)
+
+When `use_default_wrapper_template()` returns `false`:
+
+```php
+
+```
+
+**What happens:**
+1. Your template file (`custom-block.php`) must handle the complete block structure
+2. You must manually call `get_modifier_class_string()` in your template
+3. You have full control over the HTML structure
+
+### In Custom Templates (When Default Wrapper is Disabled)
+
+Only use this when `use_default_wrapper_template()` returns `false`:
+
+```php
+get_modifier_class_string( 'my-block__wrapper' );
+?>
+
+
+
+
+```
+
+## Generated Class Format
+
+The trait generates classes in the following format:
+```
+{base-class}--{modifier-class}
+```
+
+For example, with base class `my-block__wrapper`:
+- `my-block__wrapper--primary`
+- `my-block__wrapper--secondary`
+- `my-block__wrapper--large`
+- `my-block__wrapper--small`
+
+## Available Methods
+
+### `get_modifier_class_string( string $base_class = 'example-block__wrapper' )`
+
+Returns a string of additional classes to be added to block wrappers.
+
+**Parameters:**
+- `$base_class` (string) - The base class that modifiers should be appended to. Defaults to `'example-block__wrapper'`.
+
+**Returns:** `string` - A space-separated string of modifier classes
+
+**Note:** This method is automatically called by the default wrapper template when `use_default_wrapper_template()` returns `true`. You only need to call it manually when the default wrapper is disabled.
+
+**Example:**
+```php
+$classes = $this->get_modifier_class_string( 'my-block__wrapper' );
+// Returns: "my-block__wrapper--primary my-block__wrapper--secondary"
+```
+
+### `modifier_classes()`
+
+Protected method that returns an array of single terms (no prefix) to be converted to modifier classes.
+
+**Returns:** `array` - An array of modifier terms
+
+**Example:**
+```php
+protected function modifier_classes(): array {
+ return array(
+ 'primary',
+ 'secondary',
+ 'large',
+ 'small',
+ );
+}
+```
+
+## Default Template Wrapper Integration
+
+When `use_default_wrapper_template()` returns `true`, the system automatically:
+
+1. **Uses the default wrapper template** - Your template content is enclosed in the default structure
+2. **Automatic Method Call** - `get_modifier_class_string()` is called automatically by the wrapper
+3. **Wrapper Integration** - Classes are applied to the block's wrapper element
+4. **Seamless Operation** - Modifier classes work out of the box
+
+### Example with Default Wrapper
+
+```php
+
+```
+
+**Template file (`templates/block.php`):**
+```php
+
Block Title
+
Block content goes here.
+```
+
+**Resulting HTML (automatically generated):**
+```html
+
+
+
+
Block Title
+
Block content goes here.
+
+
+
+```
+
+## When to Use Manual Integration
+
+You only need to manually integrate this trait when:
+
+1. **Default wrapper disabled** - `use_default_wrapper_template()` returns `false`
+2. **Custom HTML structure** - Need complete control over the block's HTML
+3. **Override behavior** - Want to change how modifier classes are generated
+4. **Custom logic** - Need custom modifier class logic beyond the standard implementation
+5. **Multiple wrapper elements** - Need modifier classes on multiple elements
+
+## Dynamic Class Modification
+
+The trait integrates with WordPress filters to allow dynamic modification of classes:
+
+### Filter Hook: `block-{block-name}-modifier-classes`
+
+This filter allows you to modify the modifier classes at runtime:
+
+```php
+
+```
+
+## Use Cases
+
+### Basic Modifier Classes (Default Wrapper Enabled)
+
+```php
+
+```
+
+### Field-Based Modifiers (Default Wrapper Enabled)
+
+```php
+get_field( 'full_height' ) ) {
+ $classes[] = 'full-height';
+ }
+
+ if ( $this->get_field( 'dark_theme' ) ) {
+ $classes[] = 'dark';
+ }
+
+ return $classes;
+ }
+
+ protected function template(): string {
+ return __DIR__ . '/templates/block.php';
+ }
+
+ // Modifier classes automatically reflect field values
+}
+?>
+```
+
+### Conditional Modifiers (Default Wrapper Enabled)
+
+```php
+
+```
+
+## CSS Integration
+
+### Basic CSS Structure
+
+```scss
+.my-block__wrapper {
+ // Base styles
+
+ &--primary {
+ background-color: #007cba;
+ color: white;
+ }
+
+ &--secondary {
+ background-color: #f0f0f0;
+ color: #333;
+ }
+
+ &--large {
+ padding: 2rem;
+ font-size: 1.2rem;
+ }
+
+ &--small {
+ padding: 0.5rem;
+ font-size: 0.9rem;
+ }
+}
+```
+
+### Responsive Modifiers
+
+```scss
+.my-block__wrapper {
+ &--mobile-only {
+ @media (min-width: 768px) {
+ display: none;
+ }
+ }
+
+ &--desktop-only {
+ @media (max-width: 767px) {
+ display: none;
+ }
+ }
+}
+```
+
+## Dependencies
+
+This trait has no dependencies and can be used independently. However, it's automatically included in the `Block` abstract class, so you typically don't need to add it manually.
+
+## Best Practices
+
+1. **Use the default wrapper when possible** - Let the system handle modifier classes automatically
+2. **Always provide a template function** - Every block must return a valid template path
+3. **Override modifier_classes()** - Define your modifier classes in the method
+4. **Keep modifiers focused** - Each modifier should represent a single concept
+5. **Follow BEM conventions** - Use the established naming pattern for consistency
+6. **Consider CSS specificity** - Ensure your CSS selectors have appropriate specificity
+7. **Document your modifiers** - Keep a clear list of available modifiers for developers
+8. **Test automatic integration** - Verify modifier classes work with the default wrapper
+9. **Understand when manual integration is needed** - Only when `use_default_wrapper_template()` returns `false`
+
+## Common Modifier Patterns
+
+- **Size variations:** `small`, `medium`, `large`
+- **Color themes:** `primary`, `secondary`, `accent`
+- **Layout options:** `left`, `center`, `right`, `full-width`
+- **Visual styles:** `outlined`, `filled`, `minimal`
+- **Context variations:** `homepage`, `archive`, `single`
diff --git a/docs/block-traits/traits/post-type-restriction.md b/docs/block-traits/traits/post-type-restriction.md
new file mode 100644
index 0000000..3d140b5
--- /dev/null
+++ b/docs/block-traits/traits/post-type-restriction.md
@@ -0,0 +1,431 @@
+---
+title: Post Type Restriction Trait
+editLink: false
+---
+
+# Post Type Restriction Trait
+
+The `Trait_Restrict_To_Post_Types` provides blocks with the ability to control which post types they can be used with, allowing developers to create specialized blocks that only appear in relevant content areas.
+
+## Purpose
+
+This trait is designed to:
+- Restrict blocks to specific post types
+- Improve content editor experience by showing relevant blocks
+- Prevent blocks from being used in inappropriate contexts
+- Support specialized content workflows
+- Enable post-type-specific functionality
+
+## How It Works
+
+The trait automatically:
+1. Integrates with WordPress post type system
+2. Filters block availability based on current post type
+3. Provides methods to restrict blocks to specific post types
+4. Handles post type detection and validation
+5. Works with both built-in and custom post types
+
+## Usage
+
+### Basic Implementation
+
+```php
+restrict_to_post_types( array( 'product' ) );
+ }
+}
+```
+
+### Restricting to Multiple Post Types
+
+```php
+restrict_to_post_types( array( 'post', 'page' ) );
+ }
+}
+```
+
+### Restricting to Built-in Post Types
+
+```php
+restrict_to_post_types( array( 'post' ) );
+ }
+}
+```
+
+## Available Methods
+
+### `restrict_to_post_types( array $post_types )`
+
+Restricts block availability to specified post types.
+
+**Parameters:**
+- `$post_types` (array) - Array of post type names to restrict to
+
+**Returns:** `void`
+
+**Example:**
+```php
+$this->restrict_to_post_types( array( 'post', 'page', 'product' ) );
+```
+
+## Post Type Examples
+
+### Built-in Post Types
+
+WordPress provides several built-in post types:
+
+- **`post`** - Blog posts
+- **`page`** - Static pages
+- **`attachment`** - Media attachments
+- **`revision`** - Post revisions
+- **`nav_menu_item`** - Navigation menu items
+- **`custom_css`** - Custom CSS
+- **`oembed_cache`** - OEmbed cache
+
+### Custom Post Types
+
+Common custom post types include:
+
+- **`product`** - E-commerce products
+- **`event`** - Events and calendar items
+- **`testimonial`** - Customer testimonials
+- **`team`** - Team member profiles
+- **`portfolio`** - Portfolio items
+- **`faq`** - Frequently asked questions
+
+## Use Cases
+
+### Product-Specific Blocks
+
+```php
+restrict_to_post_types( array( 'product' ) );
+ }
+
+ protected function name(): string {
+ return 'product-gallery';
+ }
+
+ protected function label(): string {
+ return 'Product Gallery';
+ }
+}
+?>
+```
+
+### Event-Specific Blocks
+
+```php
+restrict_to_post_types( array( 'event' ) );
+ }
+
+ protected function name(): string {
+ return 'event-details';
+ }
+
+ protected function label(): string {
+ return 'Event Details';
+ }
+}
+?>
+```
+
+### Content-Type Specific Blocks
+
+```php
+restrict_to_post_types( array( 'post' ) );
+ }
+
+ protected function name(): string {
+ return 'blog-content';
+ }
+
+ protected function label(): string {
+ return 'Blog Content';
+ }
+}
+?>
+```
+
+### Multi-Post Type Blocks
+
+```php
+restrict_to_post_types( array( 'post', 'page', 'product', 'event' ) );
+ }
+
+ protected function name(): string {
+ return 'flexible-content';
+ }
+
+ protected function label(): string {
+ return 'Flexible Content';
+ }
+}
+?>
+```
+
+## Advanced Usage
+
+### Conditional Post Type Restrictions
+
+```php
+apply_smart_restrictions();
+ }
+
+ private function apply_smart_restrictions() {
+ // Check if WooCommerce is active
+ if ( class_exists( 'WooCommerce' ) ) {
+ $this->restrict_to_post_types( array( 'post', 'page', 'product' ) );
+ } else {
+ $this->restrict_to_post_types( array( 'post', 'page' ) );
+ }
+ }
+}
+?>
+```
+
+### Dynamic Post Type Detection
+
+```php
+auto_detect_post_types();
+ }
+
+ private function auto_detect_post_types() {
+ $post_types = get_post_types( array( 'public' => true ) );
+
+ // Filter out unwanted post types
+ $excluded_types = array( 'attachment', 'revision', 'nav_menu_item' );
+ $allowed_types = array_diff( $post_types, $excluded_types );
+
+ $this->restrict_to_post_types( array_values( $allowed_types ) );
+ }
+}
+?>
+```
+
+### Role-Based Restrictions
+
+```php
+apply_role_based_restrictions();
+ }
+
+ private function apply_role_based_restrictions() {
+ if ( current_user_can( 'manage_options' ) ) {
+ // Admins can use in all post types
+ $this->restrict_to_post_types( array( 'post', 'page', 'product', 'event' ) );
+ } elseif ( current_user_can( 'edit_posts' ) ) {
+ // Editors can use in posts and pages
+ $this->restrict_to_post_types( array( 'post', 'page' ) );
+ } else {
+ // Authors can only use in posts
+ $this->restrict_to_post_types( array( 'post' ) );
+ }
+ }
+}
+?>
+```
+
+## Integration with Other Traits
+
+### With Editor Context Restriction
+
+```php
+restrict_to_post_types( array( 'product' ) );
+ $this->restrict_to_post_editor();
+ }
+}
+?>
+```
+
+### With Icon Support
+
+```php
+restrict_to_post_types( array( 'product' ) );
+ }
+
+ private function icons(): array {
+ return array(
+ 'star' => 'Star Rating',
+ 'heart' => 'Favorite',
+ 'share' => 'Share',
+ );
+ }
+}
+?>
+```
+
+### With Color Choices
+
+```php
+restrict_to_post_types( array( 'event' ) );
+ }
+
+ protected function fields(): array {
+ return array(
+ array(
+ 'key' => 'field_event_theme',
+ 'name' => 'event_theme',
+ 'label' => 'Event Theme Color',
+ 'type' => 'radio',
+ 'choices' => $this->get_color_choices(),
+ ),
+ );
+ }
+}
+?>
+```
+
+## Error Handling
+
+The trait gracefully handles various scenarios:
+
+- **Invalid post types:** Gracefully handles non-existent post types
+- **Post type detection failure:** Falls back to allowing the block everywhere
+- **Filter conflicts:** Works alongside other block filtering systems
+- **Missing post type data:** Handles cases where post type information is unavailable
+
+## Best Practices
+
+1. **Choose appropriate post types** - Restrict blocks to post types where they make sense
+2. **Consider user experience** - Don't overly restrict blocks unless necessary
+3. **Test restrictions** - Verify blocks appear/disappear in correct post types
+4. **Document restrictions** - Let developers know which post types support each block
+5. **Plan for flexibility** - Consider if blocks might be useful in multiple post types
+6. **Follow WordPress patterns** - Use standard post type names when possible
+
+## Common Restriction Patterns
+
+- **Content blocks** → `post`, `page`
+- **Product blocks** → `product`
+- **Event blocks** → `event`
+- **Portfolio blocks** → `portfolio`
+- **Testimonial blocks** → `testimonial`
+- **Team blocks** → `team`
+- **FAQ blocks** → `faq`
+- **News blocks** → `post`, `news`
+- **Gallery blocks** → `post`, `page`, `gallery`
+- **Form blocks** → `post`, `page`, `contact`
diff --git a/docs/block-traits/traits/reduce-bottom-spacing.md b/docs/block-traits/traits/reduce-bottom-spacing.md
index 4196be5..f58a570 100644
--- a/docs/block-traits/traits/reduce-bottom-spacing.md
+++ b/docs/block-traits/traits/reduce-bottom-spacing.md
@@ -1,6 +1,283 @@
---
-title: Reduce Bottom Spacing
+title: Reduce Bottom Space Trait
editLink: false
---
-# Reduce Bottom Spacing
+# Reduce Bottom Space Trait
+
+The `Trait_Has_Reduce_Bottom_Space_Option` adds a "Reduce Bottom Space" setting to blocks, allowing content editors to control the spacing between blocks when there's no clear visual boundary.
+
+## Purpose
+
+This trait is designed to:
+- Provide editors with control over block spacing
+- Improve visual hierarchy between adjacent blocks
+- Add a standardized spacing control option
+- Integrate seamlessly with the modifier classes system
+- Work automatically with the default template wrapper
+
+## Dependencies
+
+**Important:** This trait **requires** `Trait_Has_Modifier_Classes` to function properly. However, since `Trait_Has_Modifier_Classes` is automatically included in the `Block` abstract class by default, you typically don't need to worry about this dependency.
+
+The trait will throw an exception if used without `Trait_Has_Modifier_Classes`, but this should never happen when extending the `Block` class normally.
+
+## How It Works
+
+The trait automatically:
+1. Adds a "Reduce Bottom Space" ACF field to the block
+2. Integrates with the modifier classes system
+3. Applies the `reduce-bottom-space` modifier class when enabled
+4. Handles all initialization automatically
+5. Works seamlessly with the default template wrapper
+
+## Usage
+
+### Basic Implementation
+
+```php
+
+```
+
+## Auto-Initialization
+
+This trait automatically initializes when added to a block class. The initialization process:
+
+1. **Dependency Check** - Verifies `Trait_Has_Modifier_Classes` is present (automatically satisfied)
+2. **Field Addition** - Adds the "Reduce Bottom Space" ACF field
+3. **Modifier Integration** - Connects with the modifier classes system
+4. **Default Wrapper Integration** - Works automatically with the default template system
+
+## Added ACF Field
+
+The trait automatically adds the following ACF field:
+
+| Property | Value |
+|----------|-------|
+| **Key** | `field_{block_name}_reduce_bottom_space` |
+| **Name** | `reduce_bottom_space` |
+| **Label** | `Bottom Space` |
+| **Message** | `Reduce Bottom Space` |
+| **Instructions** | `Useful when there is no clear boundary between an adjacent block.` |
+| **Type** | `true_false` |
+
+## Generated Modifier Class
+
+When the "Reduce Bottom Space" option is enabled, the trait automatically adds the `reduce-bottom-space` modifier class to your block's modifier classes.
+
+## CSS Integration
+
+### Basic CSS Structure
+
+```scss
+.my-block__wrapper {
+ // Base styles with normal bottom margin
+ margin-bottom: 2rem;
+
+ &--reduce-bottom-space {
+ // Reduced bottom margin when the option is enabled
+ margin-bottom: 1rem;
+ }
+}
+```
+
+### Advanced CSS Examples
+
+```scss
+.my-block__wrapper {
+ margin-bottom: 2rem;
+
+ &--reduce-bottom-space {
+ margin-bottom: 0.5rem;
+
+ // You can also adjust other spacing properties
+ padding-bottom: 1rem;
+
+ // Or use negative margins for tighter spacing
+ margin-bottom: -0.5rem;
+ }
+}
+```
+
+### Responsive Spacing
+
+```scss
+.my-block__wrapper {
+ margin-bottom: 2rem;
+
+ @media (max-width: 768px) {
+ margin-bottom: 1.5rem;
+ }
+
+ &--reduce-bottom-space {
+ margin-bottom: 1rem;
+
+ @media (max-width: 768px) {
+ margin-bottom: 0.75rem;
+ }
+ }
+}
+```
+
+## Use Cases
+
+### Content Blocks
+
+```php
+
+```
+
+### Hero Sections
+
+```php
+
+```
+
+### Call-to-Action Blocks
+
+```php
+
+```
+
+## Template Usage
+
+### With Default Wrapper (Automatic)
+
+The trait works automatically with the default template wrapper - no additional template code is needed. The modifier class will be applied through the existing `get_modifier_class_string()` method automatically.
+
+### With Custom Templates
+
+If you're using a custom template, you can manually access the modifier classes:
+
+```php
+get_modifier_class_string( 'my-block__wrapper' );
+?>
+
+
+
+
+```
+
+## Error Handling
+
+If you attempt to use this trait without `Trait_Has_Modifier_Classes`, you'll receive a clear exception message:
+
+```
+Exception: Creode_Blocks\Trait_Has_Reduce_Bottom_Space_Option should only ever be used alongside Creode_Blocks\Trait_Has_Modifier_Classes. Please add this trait to [Your_Class_Name] and conform to its requirements.
+```
+
+**Note:** This error should never occur when extending the `Block` class normally, as `Trait_Has_Modifier_Classes` is automatically included.
+
+## Best Practices
+
+1. **Use with default wrapper** - Let the system handle modifier classes automatically
+2. **Plan your CSS** - Design your CSS to handle the `reduce-bottom-space` modifier
+3. **Consider context** - Use this option when blocks need tighter visual grouping
+4. **Test spacing** - Verify that reduced spacing works well in your design
+5. **Document usage** - Let content editors know when to use this option
+6. **Leverage automatic integration** - No need to manually handle modifier classes
+
+## Common Scenarios
+
+- **Tight content grouping** - When multiple related blocks should appear as a unit
+- **Visual hierarchy** - When you want to emphasize the relationship between blocks
+- **Layout optimization** - When standard spacing creates too much visual separation
+- **Mobile considerations** - When you need tighter spacing on smaller screens
diff --git a/docs/block-traits/traits/unique-id.md b/docs/block-traits/traits/unique-id.md
index f812e0e..b1873b5 100644
--- a/docs/block-traits/traits/unique-id.md
+++ b/docs/block-traits/traits/unique-id.md
@@ -1,6 +1,156 @@
---
-title: Reduce Bottom Spacing
+title: Unique ID Trait
editLink: false
---
-# Unique ID
+# Unique ID Trait
+
+The `Trait_Has_Unique_Id` provides a mechanism for generating unique identifiers for blocks, ensuring that each block instance has a distinct identifier during rendering.
+
+## Purpose
+
+This trait is essential when you need to:
+- Generate unique CSS IDs for styling
+- Create unique JavaScript selectors
+- Ensure accessibility compliance with unique IDs
+- Avoid conflicts when multiple instances of the same block exist on a page
+
+## How It Works
+
+The trait maintains an internal counter for each block type and generates sequential identifiers. Each call to `get_unique_id()` returns a unique string that will never repeat within a single WordPress execution.
+
+**Note:** This functionality is only applicable to front-end output because editors use multiple WordPress executions.
+
+## Usage
+
+### Basic Implementation
+
+```php
+get_unique_id();
+?>
+
+
+```
+
+## Generated ID Format
+
+The trait generates IDs in the following format:
+```
+{block-name}-{sequential-number}
+```
+
+For example:
+- `my-block-0`
+- `my-block-1`
+- `my-block-2`
+
+## Available Methods
+
+### `get_unique_id()`
+
+Returns a unique ID string for the current block instance.
+
+**Returns:** `string` - A unique identifier
+
+**Example:**
+```php
+$id = $this->get_unique_id(); // Returns: "my-block-0"
+```
+
+## Internal Implementation
+
+The trait uses WordPress filters to maintain state:
+
+1. **Filter Hook:** `{block_name}_iterator`
+2. **Default Value:** `0`
+3. **Increment:** Each call adds 1 to the counter
+
+## Use Cases
+
+### CSS Styling
+```php
+get_unique_id();
+?>
+
+
+```
+
+### JavaScript Integration
+```php
+get_unique_id();
+?>
+
+
+```
+
+### Accessibility
+```php
+get_unique_id();
+?>
+
+
+
Block Title
+
+
+```
+
+## Dependencies
+
+This trait has no dependencies and can be used independently.
+
+## Performance Considerations
+
+- The trait uses WordPress filters which have minimal performance impact
+- IDs are generated on-demand, not pre-computed
+- No database queries or heavy operations are performed
+
+## Best Practices
+
+1. **Use for unique identification** - Only use when you need truly unique identifiers
+2. **Escape output** - Always use `esc_attr()` or `esc_js()` when outputting IDs
+3. **Consider context** - Remember this only works on the front-end
+4. **Plan for multiple instances** - Design your CSS and JavaScript to handle multiple block instances