Refine wp-patterns skill

skills/wp-patterns/references/anti-patterns.md

@@ -2,31 +2,16 @@
 
 Common mistakes that produce generic, broken, or inaccessible patterns.
 
-## Generic AI Aesthetic Markers
+## Design Quality Checklist
 
-These indicate lazy generation — patterns that look like every other AI output:
-
-**Layout monotony:**
-- Three equal-width columns for everything (services, team, features)
-- Identical padding on every section (`spacing|50` everywhere)
-- Symmetric layouts with no visual hierarchy variation
-- Every section centered, no left-aligned or asymmetric compositions
-
-**Color flatness:**
-- Only using `base` and `contrast` — no accent colors, no dark sections
-- All sections have the same background — no rhythm of light/dark/accent
-- Buttons all the same color with no primary/secondary distinction
-
-**Typography sameness:**
-- All headings the same size — no scale contrast between hero and section heads
-- No use of `fontFamily` for heading/body distinction
-- Missing typographic details: no letter-spacing, no line-height tuning
-- All text the same color — no use of `secondary` or muted tones for supporting text
-
-**How to fix:** Make at least 3 distinctive design choices per pattern:
-1. One unexpected layout decision (asymmetric split, wide/narrow alternation, grid)
-2. One bold color move (dark section, accent background, gradient)
-3. One typographic contrast (display size, letter-spacing, font family switch)
+- [ ] **Not generic**: pattern makes at least 3 distinctive design choices
+- [ ] **Layout variety**: not defaulting to 3 equal columns or uniform symmetric layouts
+- [ ] **Color rhythm**: sections alternate or vary backgrounds — not all the same
+- [ ] **Typography contrast**: headings clearly distinct from body (size, family, or weight)
+- [ ] **Spatial intention**: padding and gaps vary by context, not uniform everywhere
+- [ ] **Meaningful content**: placeholder text reflects real use, buttons describe actions
+- [ ] **Specific structure**: comparisons, timelines, schedules, pricing, menus, and documentation cards have labels that make sense without relying on visual position alone
+- [ ] **Restrained but distinctive**: corporate/professional patterns still include a clear hierarchy, accent, or layout choice; playful patterns do not become a one-note palette or repeated gradient treatment
 
 ## Technical Anti-Patterns
 
@@ -51,7 +36,7 @@ These indicate lazy generation — patterns that look like every other AI output
 {"backgroundColor":"contrast","textColor":"base"}
 ```
 
-Use hardcoded values only when no suitable preset exists and the design requires a specific color. Always prefer presets — they adapt to theme changes and style variations.
+Use hardcoded values only when no suitable `preset` exists and the design requires a specific color.
 
 ### Missing Escaping and i18n
 ```php
@@ -91,8 +76,6 @@ Use hardcoded values only when no suitable preset exists and the design requires
   <!-- /wp:columns -->
 ```
 
-Every `<!-- wp:block -->` must have a matching `<!-- /wp:block -->` and nesting must be properly ordered.
-
 ### Placeholder Image URLs
 ```html
 <!-- WRONG: external placeholder service -->
@@ -149,3 +132,19 @@ When using dark backgrounds, verify text presets provide adequate contrast:
 
 ### Missing ARIA on Decorative Elements
 Spacer blocks should include `aria-hidden="true"` (WordPress adds this automatically). If generating custom separator patterns, ensure decorative elements don't announce to screen readers.
+
+## Technical Validation Checklist
+
+- [ ] Every `<!-- wp:block -->` has matching `<!-- /wp:block -->`
+- [ ] JSON in block comments is valid (no trailing commas, strings double-quoted)
+- [ ] All user-visible strings use `esc_html_e()` or `esc_html__()`
+- [ ] All URLs use `esc_url()`
+- [ ] All attribute values with translatable text use `esc_attr_e()` or `esc_attr__()`
+- [ ] Informational images have descriptive translated alt text; decorative images use empty alt text intentionally
+- [ ] Heading levels are sequential (h2 → h3 → h4, never skip)
+- [ ] Preset slugs are valid defaults or documented as theme-specific
+- [ ] `Slug` in header uses correct namespace: `theme-slug/pattern-name`
+- [ ] No inline `<style>`, no `<script>`, no custom CSS classes
+- [ ] No query-dependent PHP functions
+- [ ] Button/link labels are action-specific; avoid vague labels such as "Click Here" or "Read More"
+- [ ] Updating an existing pattern preserves the `Slug` unless intentionally creating a new pattern

skills/wp-patterns/references/design-with-tokens.md

@@ -2,14 +2,65 @@
 
 How to translate design intent into WordPress block attributes using theme.json presets.
 
+## Design Decisions
+
+### Purpose
+
+What does this pattern achieve for the end user? A hero converts visitors. A testimonial grid builds trust. A pricing table drives comparison. Let purpose drive every subsequent choice.
+
+### Tone
+
+| Tone | Color Strategy | Typography | Layout |
+|------|---------------|------------|--------|
+| **Bold/energetic** | High contrast, accent backgrounds, gradients | XX-large headings, tight letter-spacing, uppercase accents | Full-width, asymmetric columns, large padding |
+| **Minimal/refined** | Base + contrast only, subtle tertiary sections | Restrained sizes, generous line-height | Constrained width, generous whitespace, centered |
+| **Editorial/magazine** | Dark sections alternating with light | Mixed font families, varied heading scales | Asymmetric splits (66/33), media-text blocks |
+| **Playful/creative** | Multiple accent colors, bright backgrounds | Large display sizes, varied weights | Grid layouts, unexpected column ratios, rounded corners |
+| **Corporate/professional** | Neutral palette, primary for CTAs only | Consistent scale, body font dominant | Equal columns, structured grid, minimal decoration |
+
+### Spatial Composition
+
+Primary layout strategies:
+- **Constrained centered** — classic content width with wide breakouts
+- **Full-width sections** — alternating background bands
+- **Asymmetric split** — 60/40 or 70/30 columns with content + media
+- **Grid** — block-native grid or columns layouts for cards, team members, portfolio items
+- **Stacked vertical** — flex column with varied spacing for editorial feel
+
+### Typography Hierarchy
+
+Plan your type scale before writing markup:
+- **Hero heading**: `fontSize:"xx-large"` + `fontFamily:"heading"` + tight `lineHeight`
+- **Section heading**: `fontSize:"x-large"` + `fontFamily:"heading"`
+- **Subtitle/lead**: `fontSize:"large"` + `textColor:"secondary"` or `fontFamily:"body"`
+- **Body**: `fontSize:"medium"` or default
+- **Caption/meta**: `fontSize:"small"` + `textColor:"secondary"`
+
+Add at least one typographic accent:
+- Uppercase + letter-spacing for labels: `{"style":{"typography":{"textTransform":"uppercase","letterSpacing":"0.1em"}}}`
+- Tight letter-spacing on display headings: `{"style":{"typography":{"lineHeight":"1.1"}}}`
+- Italic for pull quotes
+- Monospace for technical/code content
+- Generous leading on body: `{"style":{"typography":{"lineHeight":"1.8"}}}`
+
+### Color Strategy
+
+Plan section-by-section color flow:
+- **Light section**: `base` background, `contrast` text (default)
+- **Dark section**: `contrast` background, `base` text (inverted)
+- **Accent section**: `primary` or `tertiary` background
+- **Gradient section**: cover block with gradient overlay
+
+A pattern with multiple sections should vary backgrounds — don't use the same background for every section.
+
 ## Core Principle
 
 In block patterns, **all visual design** is expressed through:
-1. **Preset slugs** — reference theme.json values by name (preferred)
+1. **`preset` slugs** — reference theme.json values by name (preferred)
 2. **Style attributes** — inline custom values in block JSON (fallback)
 3. **Block nesting** — layout and composition via container blocks
 
-Never use inline `<style>` tags, custom CSS classes not generated by blocks, or arbitrary HTML.
+Never use inline `<style>` tags, custom CSS classes not generated by blocks, or arbitrary HTML outside block wrappers.
 
 ## theme.json Preset Mapping
 
@@ -108,23 +159,7 @@ Vary `blockGap` between inner elements for hierarchy:
 - **Large padding** on groups creates breathing room and perceived importance
 - **Contrast inversion** (dark bg + light text) draws attention to sections
 - **Border accents** (left border, bottom border) create hierarchy without heaviness
-- **Spacer blocks** between sections: use preset spacing, not arbitrary pixel values
-
-## Typography Pairing
-
-Combine `fontFamily` with `fontSize` for hierarchy:
-
-```
-Hero:      fontFamily:"heading" + fontSize:"xx-large" + letterSpacing:"-0.02em"
-Subtitle:  fontFamily:"body" + fontSize:"large" + textColor:"secondary"
-Body:      fontFamily:"body" + fontSize:"medium"
-Caption:   fontFamily:"body" + fontSize:"small" + textColor:"secondary"
-```
-
-Emphasis techniques:
-- **All caps**: `{"style":{"typography":{"textTransform":"uppercase","letterSpacing":"0.1em"}}}`
-- **Tight leading**: `{"style":{"typography":{"lineHeight":"1.1"}}}` (headings only)
-- **Generous leading**: `{"style":{"typography":{"lineHeight":"1.8"}}}` (body for readability)
+- **Spacer blocks** between sections: use `preset` spacing, not arbitrary pixel values
 
 ## Gradient and Shadow Presets
 

skills/wp-patterns/references/example-prompts.md

@@ -0,0 +1,25 @@
+# Example Prompts
+
+## Hero Section
+
+> "Create a bold hero pattern with a large heading, subtitle, and two CTA buttons. Dark background, full-width, for a creative agency theme."
+
+Expected: Cover or Group block with contrast bg, constrained inner, heading with xx-large + heading font, paragraph with secondary color, Buttons with primary + outline styles.
+
+## Testimonial Grid
+
+> "Create a 3-column testimonial grid with avatar, quote, name, and role. Alternating card backgrounds."
+
+Expected: Group wrapper, block-native grid or Columns layout (3 columns, responsive), inner Group cards with varied tertiary/base backgrounds, Image block for avatar (rounded border-radius), Paragraph for quote (italic), Heading h3 for name, Paragraph small for role.
+
+## Blog Post Listing
+
+> "Create a starter page pattern for a blog index with featured post hero and 3-column grid of recent posts below."
+
+Expected: `Block Types: core/post-content` header, Query Loop for featured post (perPage 1, large layout), second Query Loop for grid (perPage 3, grid layout with post-template), clear visual separation between sections.
+
+## Footer with Columns
+
+> "Create a 4-column footer pattern with logo, navigation links, contact info, and social icons. Dark background."
+
+Expected: `Block Types: core/template-part/footer` header, Group full-width with contrast bg, Columns (4), Site Logo block, Navigation or list blocks, Paragraph blocks for contact, Social Icons block. `Inserter: no`.

skills/wp-patterns/references/pattern-categories-and-types.md

@@ -54,6 +54,8 @@ Register by setting `Block Types` to `core/post-content`:
 
 Starter patterns should be **complete page layouts** — not partial sections.
 
+Include `Block Types: core/post-content` unless the pattern is specifically for a template or template part.
+
 ## Template Patterns
 
 Patterns that suggest themselves when editing a specific template type in the Site Editor.
@@ -93,6 +95,22 @@ Register with `Template Types`:
 | `attachment` | Attachment page |
 | `comments` | Comments template section |
 
+## Query Loop Patterns
+
+Use `core/query` with `core/post-template`, post title/excerpt/date/featured image blocks, **pagination** when needed, and **`core/query-no-results`** where relevant.
+
+For archive, search, category, and author templates, **prefer inherited query context** (`"inherit":true`) instead of custom PHP or hardcoded query args.
+
+For CPT or event listings, confirm the post type slug, taxonomy/date assumptions, and available blocks before generating markup.
+
+## Comparison, Pricing, Timeline, and Schedule Patterns
+
+Use clear headings, list/table or labeled-card structure, and non-color-only emphasis for featured states.
+
+## Social, Navigation, and Search Patterns
+
+Use native blocks and verify accessible labels, link text, and search context. In 404 patterns, pair the Search block with recovery copy that explains what the user can try next.
+
 ## Block Type Connections
 
 Connect patterns to specific block types so they appear as options for those blocks:

skills/wp-patterns/references/visual-composition.md

@@ -0,0 +1,14 @@
+# Visual Composition Moves
+
+When the request calls for a visually _distinctive_ pattern, use these composition moves:
+
+- **Oversized display type**: use a short word or title at display scale with tight line-height, uppercase or italic treatment, and enough surrounding space. Keep letter spacing at `0` unless the design specifically needs a tracked wordmark.
+- **Offset color fields**: split a cover background with a hard-stop gradient or two-tone color field, then let the type or image cross the boundary.
+- **Editorial cover image**: use a full-bleed Cover block with image, dim/duotone treatment, and left-anchored copy; place the CTA in a clearly separated lower area.
+- **Image plus quiet content**: use Media & Text for case-study or portfolio patterns where the image carries visual weight and the content side stays intentionally sparse.
+- **Header plus hero**: combine a flex header with Site Logo, Site Title, and Navigation above a full-width Cover when the pattern is a page opener or starter page.
+- **Post index as graphic layout**: for Query Loop patterns, make dates and titles part of the visual hierarchy with large title links, strong separators, and pagination.
+- **Repeated display text**: repeat a single word or short phrase in varied tones when the design is poster-like, but keep it readable and avoid repeating long content.
+- **Centered image on two-tone field**: place a single image inside a constrained group over a split-color background for a gallery, collection, or album-style pattern.
+
+These moves must still pass the Technical Validation Checklist in `references/anti-patterns.md`.