| name | greenshift-blocks |
| description | Generate WordPress Gutenberg blocks using Greenshift/GreenLight plugin. Use when user asks to create WordPress sections, blocks, layouts, hero sections, galleries, or any Gutenberg element. Triggers on keywords: wordpress, gutenberg, greenshift, section, block, layout, hero, gallery, columns, element. |
Greenshift Block Generator
Purpose
Generate production-ready WordPress Gutenberg blocks using Greenshift/GreenLight Element block system. All output is HTML with JSON parameters in block comments - ready to paste directly into WordPress Gutenberg code editor.
Documentation Structure
Detailed documentation is split into modular files in the docs/ directory:
| File | Topic |
|---|
docs/00-index.md | Navigation index |
docs/01-core-structure.md | Block format, JSON parameters, content types, styleAttributes |
docs/02-attributes.md | HTML attributes, links, images, forms, icons |
docs/03-layouts.md | Sections, columns, flexbox configurations |
docs/04-styling-advanced.md | Local classes (dynamicGClasses), gradients, background images, parallax |
docs/05-animations.md | AOS animations, CSS keyframes, scroll animations |
docs/06-slider.md | Swiper slider block configuration |
docs/07-dynamic-content.md | Dynamic text, query grids, placeholders |
docs/08-variations.md | Accordion, tabs, counter, countdown, etc. |
docs/09-css-variables.md | All CSS variables (fonts, spacing, shadows, etc.) |
docs/10-scripts.md | Custom JavaScript and GSAP integration |
docs/11-charts.md | ApexCharts integration |
docs/12-migration-rules.md | CRITICAL - Typography stripping, semantic headings, minimal styling |
Read relevant docs files when you need detailed information on specific topics.
IMPORTANT: Always read docs/12-migration-rules.md when migrating or cloning blocks - it contains critical rules about what styles to REMOVE.
Quick Reference
Core Block Structure
Every Greenshift element follows this pattern:
<html_tag class="optional classes" ...attributes>
</html_tag>
Critical Rules
-
Block IDs: Unique id starting with gsbp- + 7 alphanumeric chars (e.g., gsbp-b3c761b). localId must be identical to id.
-
Content Types (type parameter):
"text": Text-only blocks - requires textContent with duplicated text
"inner": Container blocks - wrap plain text in <span> element blocks
"no": Empty/spacer elements
"chart": ApexCharts
-
Styling (styleAttributes):
- Never use inline
style="..." attributes
- Properties use camelCase (e.g.,
backgroundColor, paddingTop)
- Values are arrays for responsive:
["desktop", "tablet", "mobile_landscape", "mobile_portrait"]
- Single value
["10px"] applies to all breakpoints
- Pseudo-states:
backgroundColor_hover, color_focus
- If
styleAttributes exists, add localId to HTML class attribute
-
HTML Tags: Default is div. Prefer tag: "a" over tag: "button" for buttons (except forms).
-
Images: Always loading="lazy". Use https://placehold.co/WIDTHxHEIGHT. When using originalWidth and originalHeight in JSON, you MUST also add matching width and height HTML attributes to the <img> tag.
-
Links: linkNewWindow: true = target="_blank" + auto rel="noopener"
-
Column Children with Padding: Always add boxSizing: ["border-box"] to column children that have padding. Without this, padding adds to width and causes columns to wrap unexpectedly. See docs/03-layouts.md for details.
See docs/01-core-structure.md and docs/02-attributes.md for full details.
Minimal Intervention Philosophy
Core Principle: Less is More
When generating or migrating blocks, apply minimal styling intervention. Let the WordPress theme handle defaults.
See docs/12-migration-rules.md for comprehensive migration-specific rules.
What NOT to Do
| Avoid | Why |
|---|
Adding fontSize to headings (h1-h6) | Theme typography handles heading sizes |
Adding color to headings/paragraphs | Theme colors cascade from settings |
Adding fontWeight to headings | Theme defines heading weights |
Adding fontWeight: ["400"] anywhere | It's the default - remove it |
Adding lineHeight to headings | Theme handles heading line-heights |
| Setting responsive fontSize on headings | Theme's heading styles are already responsive |
| Using generic background colors | Use theme palette variables (palette-color-6, etc.) |
Typography Rules (CRITICAL)
Headings (h1, h2, h3, h4, h5, h6) - NEVER SET:
fontSize - theme handles heading sizes (even responsive ones)
fontWeight - theme handles heading weights
color - theme handles text colors (unless on dark background)
lineHeight - theme handles heading line-heights
Headings - OKAY TO SET:
marginTop, marginBottom - for spacing control
textAlign - for layout/centering
WRONG - Over-styled heading:
{
"tag": "h2",
"styleAttributes": {
"fontSize": ["3rem", "2.7rem"],
"fontWeight": ["700"],
"lineHeight": ["1.2"]
}
}
CORRECT - Minimal heading:
{
"tag": "h2",
"styleAttributes": {
"marginBottom": ["1rem"],
"textAlign": ["center"]
}
}
Paragraphs and text - NEVER SET:
color - unless on dark/colored background
fontWeight: ["400"] or fontWeight: ["normal"] - these are defaults
lineHeight - unless custom fontSize requires adjustment
Paragraphs and text - OKAY TO SET:
fontSize - ONLY for intentional accent/lead text (e.g., ["1.2rem"])
fontFamily - for specific font choices
fontWeight: ["700"] - for intentionally bold body text
maxWidth - for constraining text width
Exception - Text on dark backgrounds:
When text is over a dark background (hero overlays, dark sections, card overlays):
- White text:
"color":["var(--wp--preset--color--white, #ffffff)"]
- Semi-transparent white:
"color":["rgba(255,255,255,0.9)"]
Semantic Heading Hierarchy
Use proper HTML heading levels based on content structure:
h1 - Page title (usually in theme header)
h2 - Main section titles (one per section)
h3 - Subsection/card titles
h4 - Minor headings within cards/subsections
Example - Step Cards:
- Section intro:
h2
- Grid/subsection title:
h3
- Individual step headings:
h4
DON'T: Use multiple h2s in same section or h3 for minor card headings.
Background Colors - Use Theme Palette
WRONG - Generic variables:
"backgroundColor": ["var(--wp--preset--color--white, #ffffff)"]
"backgroundColor": ["var(--wp--preset--color--light-grey, #f8f8f8)"]
CORRECT - Theme palette:
"backgroundColor": ["var(--wp--preset--color--palette-color-6, var(--theme-palette-color-6, #f5f5f4))"]
"backgroundColor": ["var(--wp--preset--color--palette-color-7, var(--theme-palette-color-7, #fafaf9))"]
"backgroundColor": ["var(--wp--preset--color--palette-color-8, var(--theme-palette-color-8, #fffffe))"]
Palette colors (6, 7, 8) adapt to user's theme settings. Generic colors override theme customization.
When TO Style
- Text on dark backgrounds - white/light colors needed for readability
- Structural necessity - flexbox layouts, positioning
- Spacing control - gaps between sections, margins for element separation
- Explicit design override - screenshot shows specific non-default styling
Hardcoded Values vs CSS Variables
WRONG - Over-styled:
{
"styleAttributes": {
"fontSize": ["16px"],
"fontWeight": ["400"],
"lineHeight": ["1.5"],
"color": ["#333333"],
"marginBottom": ["20px"]
}
}
CORRECT - Minimal:
{
"styleAttributes": {
"marginBottom": ["var(--wp--preset--spacing--50)"]
}
}
Or even better - no styleAttributes at all if theme defaults are acceptable.
Column/Flexbox Spacing
For column gaps, use CSS variables:
{
"styleAttributes": {
"columnGap": ["var(--wp--preset--spacing--60, 2rem)"],
"rowGap": ["var(--wp--preset--spacing--60, 2rem)"]
}
}
AVOID hardcoded gaps like "columnGap": ["25px"] unless specifically required.
Migration/Cloning Rule
When migrating or cloning:
- Preserve structure - keep the layout working
- Remove unnecessary styles - strip redundant fontSize, fontWeight, color
- Convert hardcoded to variables - but only if the value is being kept
- Don't add styles - if original didn't have it, don't add it
Block Types Guide
Always Use GreenLight Element
Always use greenshift-blocks/element for most content. Convert old blocks to GreenLight Element:
| Old Block (AVOID) | Replace With |
|---|
greenshift-blocks/row | greenshift-blocks/element with tag:"section", align:"full" |
greenshift-blocks/row-column | greenshift-blocks/element with type:"inner" or remove entirely |
greenshift-blocks/heading | greenshift-blocks/element with tag:"h1/h2/h3", textContent |
Specialized Blocks (OK to use)
These specialized blocks are acceptable:
greenshift-blocks/element - GreenLight Element (primary block)
greenshift-blocks/swiper - Slider/carousel
greenshift-blocks/querygrid - Query loop for posts
greenshift-blocks/dynamic-post-image - Dynamic featured image
greenshift-blocks/dynamic-post-title - Dynamic post title
greenshift-blocks/meta - Post meta data
Heading Conversion Example
WRONG (old greenshift-blocks/heading):
<h2 id="gspb_heading-id-gsbp-xxx" class="gspb_heading gspb_heading-id-gsbp-xxx">Title</h2>
CORRECT (GreenLight Element - minimal):
<h2 class="gsbp-xxx">Title</h2>
Key differences:
- Use
textContent instead of headingContent
- Use
tag:"h2" instead of default div
- NO fontSize - theme handles heading sizes
- NO color - theme handles text colors
- Only add
marginBottom if spacing control needed
- Class is
gsbp-xxx not gspb_heading gspb_heading-id-gsbp-xxx
- No
id attribute in HTML, only class
SVG Icons Encoding
SVG content inside the JSON icon.icon.svg parameter MUST use Unicode escape sequences, not raw HTML or escaped quotes.
Character Encoding Table
| Character | Escape Sequence |
|---|
< | \u003c |
> | \u003e |
" | \u0022 |
Example
WRONG:
"icon":{"icon":{"svg":"<svg viewBox=\"0 0 24 24\"><path d=\"M8 12l2 2\"/></svg>"},...}
CORRECT:
"icon":{"icon":{"svg":"\u003csvg viewBox=\u00220 0 24 24\u0022\u003e\u003cpath d=\u0022M8 12l2 2\u0022/\u003e\u003c/svg\u003e"},...}
Card Design Pattern: Inset Rounded Images
When creating cards with images that have rounded corners INSIDE the card (with visible margin/padding around them):
Structure
Card Wrapper (white bg, border-radius: 15px, overflow: hidden)
├── Image Container (padding: 8px top/left/right, 0px bottom)
│ └── Image (border-radius: 10px on ALL 4 corners, object-fit: cover)
└── Footer/Label Area (padding for content)
Key Points
- Card wrapper:
overflow: hidden + larger border-radius (e.g., 15px)
- Image container: padding on 3 sides,
paddingBottom: 0px (no gap to footer)
- Image itself: SMALLER border-radius than card (e.g., 10px) on ALL 4 corners
- This creates the "inset" look where white card background shows as margin around image
Image styleAttributes for Inset Cards
"styleAttributes": {
"width": ["100%"],
"aspectRatio": ["16/10"],
"objectFit": ["cover"],
"borderTopLeftRadius": ["var(--wp--custom--border-radius--small, 10px)"],
"borderTopRightRadius": ["var(--wp--custom--border-radius--small, 10px)"],
"borderBottomLeftRadius": ["var(--wp--custom--border-radius--small, 10px)"],
"borderBottomRightRadius": ["var(--wp--custom--border-radius--small, 10px)"],
"borderRadiusLink_Extra": true
}
Common CSS Variables
Font Sizes
var(--wp--preset--font-size--mini, 11px)
var(--wp--preset--font-size--xs, 0.85rem)
var(--wp--preset--font-size--s, 1rem)
var(--wp--preset--font-size--m, 1.35rem)
var(--wp--preset--font-size--l, 1.55rem)
var(--wp--preset--font-size--xl, clamp(1.6rem, 2.75vw, 1.9rem))
var(--wp--preset--font-size--grand, clamp(2.2rem, 4vw, 2.8rem))
var(--wp--preset--font-size--giga, clamp(3rem, 5vw, 4.5rem))
var(--wp--preset--font-size--giant, clamp(3.2rem, 6.2vw, 6.5rem))
Spacing
var(--wp--preset--spacing--40, 1rem)
var(--wp--preset--spacing--50, 1.5rem)
var(--wp--preset--spacing--60, 2.25rem)
var(--wp--preset--spacing--70, 3.38rem)
var(--wp--preset--spacing--80, 5.06rem)
Border Radius
var(--wp--custom--border-radius--mini, 5px)
var(--wp--custom--border-radius--small, 10px)
var(--wp--custom--border-radius--medium, 15px)
var(--wp--custom--border-radius--large, 20px)
Shadows & Transitions
var(--wp--preset--shadow--soft, 0px 15px 30px 0px rgba(119, 123, 146, 0.1))
var(--wp--preset--shadow--elegant, 0px 5px 23px 0px rgba(188, 207, 219, 0.35))
var(--wp--custom--transition--ease, all 0.5s ease)
var(--wp--custom--transition--smooth, all 1s cubic-bezier(0.66,0,0.34,1))
See docs/09-css-variables.md for complete list.
Common Patterns
Page Wrapper (for multi-section pages)
ALWAYS wrap full pages in a single container. This is critical for controlling spacing.
Why Page Wrapper is essential:
- Eliminates unwanted gaps - WordPress/themes often add margins between blocks
- Unified control - one place to manage page-level spacing
- Prevents theme interference - overrides default block margins
- Consistent structure - predictable behavior across themes
<div class="gsbp-page001 alignfull">
</div>
Key points:
align:"full" in JSON + alignfull in HTML class
marginBlockStart:["0px"] removes top margin forced by themes
- All section wrappers go inside this container
- Sections inside should NOT have extra top/bottom margins
Full-Width Section Wrapper
<section class="gsbp-XXXXXXX alignfull">
</section>
Content Area (Centered Container)
IMPORTANT: Use content-size (not wide-size) for content width:
<div class="gsbp-XXXXXXX">
</div>
Two-Column Layout
<div class="gsbp-XXXXXXX">
</div>
See docs/03-layouts.md for more layout patterns.
Heading with Animation
<h2 data-aos="fade-up" data-aos-easing="ease" data-aos-duration="800" data-aos-once="true" class="gsbp-XXXXXXX">Your Heading</h2>
Note: No fontSize or color on heading - theme handles typography. Only marginBottom for spacing.
See docs/05-animations.md for all animation options.
Button/Link
<a class="gsbp-XXXXXXX" href="#">Click Here</a>
Image
<img class="gsbp-XXXXXXX" src="https://placehold.co/800x600" alt="Description" width="800" height="600" loading="lazy"/>
Block Variations (isVariation)
| Variation | Use Case | Details |
|---|
"contentwrapper" | Full-width section wrapper | See docs/03-layouts.md |
"nocolumncontent" | Centered content area | See docs/03-layouts.md |
"contentcolumns" / "contentarea" | Column layouts | See docs/03-layouts.md |
"accordion" | Collapsible accordion | See docs/08-variations.md |
"tabs" | Tab interface | See docs/08-variations.md |
"counter" | Animated number counter | See docs/08-variations.md |
"countdown" | Countdown timer | See docs/08-variations.md |
"marquee" | Scrolling marquee | See docs/08-variations.md |
"buttoncomponent" | Styled button | See docs/08-variations.md |
"videolightbox" | Video with lightbox | See docs/08-variations.md |
Animation Options
Available animation.type values:
fade, fade-up, fade-down, fade-left, fade-right
zoom-in, zoom-in-up, zoom-in-down, zoom-out
slide-up, slide-down, slide-left, slide-right
flip-up, flip-down, flip-left, flip-right
clip-right, clip-left, clip-up, clip-down
Animation parameters: duration (ms), delay (ms), easing, onlyonce (boolean)
See docs/05-animations.md for keyframe animations and scroll-linked animations.
Dynamic Content
For blocks displaying WordPress data (posts, users, taxonomies):
<div class="gsbp-xxx"><dynamictext></dynamictext></div>
See docs/07-dynamic-content.md for all dynamic types and query grids.
Slider Blocks
Use greenshift-blocks/swiper for image galleries and hero sliders.
CRITICAL: For image gallery slides, use greenshift-blocks/element with tag:"img" inside slider-content-zone. Do NOT put images directly in slider-image-wrapper.
See docs/06-slider.md for complete slider documentation and correct structure.
Design Detail Attention Checklist
Before generating output, verify these visual details from the reference design:
1. Border Radius
- Card/container radius vs image/inner element radius (usually different)
- Are corners rounded on all 4 sides or specific corners only?
- Is it subtle (5-10px), medium (15px), large (20-30px), or pill (50px+)?
2. Padding/Margins
- Is image edge-to-edge or inset with visible container background?
- Gap between image and footer/content below
- Internal padding of content areas
3. Image Handling
- Does image fill container (
object-fit: cover) or maintain aspect ratio (object-fit: contain)?
- Does image have its own rounded corners separate from container?
- Aspect ratio of image area
originalWidth/originalHeight in JSON → matching width/height in HTML
4. Shadows
- Subtle vs prominent shadow
- Shadow on card vs shadow on image
5. Background Relationships
- Section background vs card background vs image background
- Overlay effects or gradients
Output Validation Rules
Before outputting Greenshift blocks, verify these critical rules:
- No HTML comments - Use
metadata:{"name":"..."} instead of <!-- Section Name -->
- Page wrapper required - Multi-section pages MUST be wrapped in element with
align:"full" and <div class="... alignfull">
- Image dimensions - When
originalWidth/originalHeight in JSON, add matching width/height to HTML <img> tag
- SVG attributes - Don't include
fill="none" on outer <svg> element (WordPress strips it - put on <path> elements)
- Slider images - Use
greenshift-blocks/element blocks in slider-content-zone, NOT direct <img> in slider-image-wrapper
- Slider swipe JSON - Use
imageurl:"" (empty string), add bgContain:false
Output Requirements
- Return only the generated block code
- Block names:
wp:greenshift-blocks/element (or specialized like swiper, querygrid)
- No explanations or surrounding text
- No HTML comments - WordPress strips them; use
metadata:{"name":"..."} for organization
- Ready to paste directly into WordPress Gutenberg code editor
- Save output as
.html files
Example Templates
Reference templates are in the templates/ directory:
section-wrapper.html - Full-width section wrapper
two-columns.html - Two-column responsive layout
hero-section.html - Hero section with background
card-grid.html - Card grid layout