npm - similarbuild - Versions diffs - 0.1.0 - Mend

similarbuild 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/templates/skills/sb-build-wp/references/wp-build-rules.md ADDED Viewed

@@ -0,0 +1,376 @@
+# WP/Elementor Build Rules
+Everything `sb-build-wp` needs to compose a production-grade `.html` file standalone enough to paste into an Elementor HTML widget and survive the theme's CSS overrides. These rules are non-negotiable — they encode hard-earned lessons from real WP migrations where the theme reset silently mutated the output.
+If the host project provides these files, prefer them — they reflect the user's most recent curated knowledge:
+- `<plugin>/memory/patterns.md` (overrides patterns A-H below)
+- `<plugin>/memory/anti-patterns.md` (overrides anti-patterns #1-9 below)
+- `<plugin>/memory/design-knowledge.md` (subset is usually passed by the orchestrator instead)
+- `<plugin>/presets/wp-elementor.yaml` (overrides the theme reset and known overrides below)
+When they're absent (early in the framework's life), use everything below as the source of truth.
+## Composition contract
+The output is a **single `.html` file** containing exactly:
+1. A `<style>` block scoped to one root class (`.{scope}`).
+2. Markup using that scope class on the outermost element.
+3. Optional `<script>` block for vanilla-JS interactivity (no frameworks).
+4. Optional `<link rel="preconnect">` + `<link rel="stylesheet">` for Google Fonts at the top of the markup or in `<head>`-like position (since Elementor strips real `<head>`, place fonts inline at the top of the body fragment).
+No `<html>`, no `<head>`, no `<body>` wrappers — this is a fragment that Elementor renders inside its own DOM. The scope class IS the boundary.
+## Scope class naming
+- Pick a kebab-case name from the section type detected in `inspection.sectionType` and a short content hint (e.g. `hero-mobile-shop`, `pdp-variant-card`, `faq-collapsible`).
+- The scope class appears on the outermost element and prefixes EVERY selector in the `<style>` block.
+- BEM-ish modifiers: `.{scope}__title`, `.{scope}__cta`, `.{scope}--variant-active`. Pick what reads cleanly — don't over-engineer.
+## Defensive specificity (anti-pattern #5b — non-negotiable)
+EVERY selector that styles user-visible content (typography, color, layout, spacing, borders) MUST include the scope class as an ancestor — not just as the element's own class.
+```css
+/* WRONG — single class, theme will win */
+.hero__title { font-size: 32px; }
+/* RIGHT — chained scope, beats theme specificity */
+.hero .hero__title { font-size: 32px; }
+```
+Even when the element already has the scope on itself, prefix with the scope as ancestor again. The double-occurrence raises specificity (0,2,0 vs 0,1,0) and protects against `.elementor-widget-container *` rules.
+## `!important` policy
+The Elementor + active theme stack frequently injects `!important` on these properties via `.elementor *` blanket rules. Match them:
+- `font-family` — almost always overridden by a theme typography block
+- `font-size` — set on `h1..h6`, `p`, `body`
+- `font-weight` — set on `h1..h6`, `body`
+- `color` — set on links via `.elementor a`, on body via theme
+Use `!important` ONLY on these four properties when they appear on critical text. Do NOT spray `!important` everywhere — overuse turns debugging into a nightmare. Specifically: do NOT `!important` margins, paddings, widths, heights, backgrounds, transforms, transitions.
+## Reset universal
+First rule in the `<style>` block, always:
+```css
+.{scope}, .{scope} * {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+```
+This neutralizes the most common theme bleed without touching properties Elementor needs (positioning, display, etc).
+## Full-bleed container (escape Elementor's max-width)
+When the section needs to span the viewport edge-to-edge, Elementor's column wrapper caps it at the theme's container width. Escape with:
+```css
+.{scope} {
+  width: 100vw;
+  margin-left: calc(50% - 50vw);
+}
+```
+This works regardless of how Elementor sized the widget. Do NOT use negative margins of fixed pixel values — they break on mobile breakpoints.
+## Mobile-first + desktop breakpoint
+Base styles target mobile (390px viewport). Desktop overrides go in:
+```css
+@media (min-width: 1000px) {
+  /* desktop-only overrides */
+}
+```
+1000px (not 768px, not 1024px) — large enough that tablets get the mobile layout (which is usually safe), small enough that landscape tablets and small laptops get desktop. This is the threshold the Alpha Infuse migration validated.
+## Asset substitution
+For every `<img>` you emit, the URL must be a value from `assetsMap.assets[originalUrl].localPath` — NEVER the original CDN URL, never an inline `data:` URI for raster, never a hand-drawn SVG approximation (anti-pattern #8).
+For SVGs: WP blocks SVG uploads by default, so SVGs come back as inline markup in `assetsMap.assets[url].inline`. Inline that markup directly into the HTML (it's already sanitized by `sb-extract-assets`). Do NOT save it to a file path.
+If a URL appears in `assetsMap.failed[]`, you have two choices:
+1. Drop the image entirely (preferred for decorative images).
+2. Use a `<div>` placeholder with a literal background-color from the inspection's color tokens (NEVER a stock-photo URL).
+Never fabricate a substitute asset. If a hero image failed, surface that to the orchestrator via a comment in the output: `<!-- sb-build-wp: hero asset failed download (URL recorded in assets-map.json) -->`.
+## Hero rules (anti-pattern #1)
+NEVER use `100vh` for hero height. Mobile browser chrome (URL bar collapse + safe areas) makes `100vh` taller than the visible viewport, causing the hero to clip below the fold. Use:
+```css
+.{scope} .{scope}__hero {
+  aspect-ratio: 1 / 1.3;   /* mobile: portrait-ish */
+  max-height: 700px;
+}
+@media (min-width: 1000px) {
+  .{scope} .{scope}__hero {
+    aspect-ratio: 16 / 9;
+    max-height: 720px;
+  }
+}
+```
+If the hero is a background-image: prefer `background-image` on the container with `background-size: cover` over an `<img>` with `height: 100%` (anti-pattern #2). The `<img>` approach breaks the moment Elementor injects `img { height: auto !important }`.
+## Google Fonts inlining
+At the top of the body fragment (before the scoped section), emit:
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family={Family}:wght@{weights}&display=swap">
+```
+`display=swap` is mandatory — without it, FOIT happens and Elementor's font-loading dance causes layout shift. Pull the family name and weights from `inspection.tokens.typography` (h1, h2, body, button — usually 2 weights cover all four).
+## Design knowledge — applied automatically
+These come from the `designKnowledge` subset the orchestrator passed in. When that subset is absent or thin, use these defaults — they are baseline web standards, not opinions:
+### Accessibility
+- Every `<img>` MUST have an `alt` attribute. Decorative images: `alt=""` (empty, intentional). Content images: descriptive alt derived from `inspection.imgUrls[].alt` if present, else from surrounding context.
+- Every `<button>` MUST have `type="button"` (so it doesn't submit a parent form by accident — Elementor pages often have hidden forms).
+- Buttons that are icon-only (no visible text) MUST have `aria-label="..."` describing the action.
+- Heading hierarchy: a section that starts with H2 cannot have an H1 below it. Don't skip levels (H1 → H2 → H3, not H1 → H3). The orchestrator may tell you this is a sub-section that should start at H2 — respect that.
+- Use `<nav>` for navigation regions, `<main>` is owned by the page (don't emit it from a section), `<dialog>` for modals (native, no library needed).
+### Performance
+- The hero image (largest above-the-fold content image) MUST get `loading="eager"` AND a `<link rel="preload" as="image" href="{localPath}">` at the top of the fragment. Every other image gets `loading="lazy"`.
+- `fetchpriority="high"` on the hero `<img>` is allowed but not required (Chromium-only at the time of writing).
+- `<link rel="preconnect">` for Google Fonts goes before the stylesheet link, not after.
+### Web standards
+- Responsive images: when the inspection has multiple sources (`imgUrls[].type === 'source-srcset'`), emit `srcset` + `sizes` on the `<img>`. The `sizes` value should be `"(min-width: 1000px) 50vw, 100vw"` for half-width desktop content, `"100vw"` for full-bleed.
+- Use `<dialog>` for modals — close with `dialog.close()`, open with `dialog.showModal()`. No library, no custom backdrop.
+- Use `<details>/<summary>` for FAQ collapsibles (Pattern F). Theme styling? Reset summary's default marker via `summary { list-style: none } summary::-webkit-details-marker { display: none }`.
+## fixHints (when present)
+`fixHints` arrives as a JSON array from `sb-review-checks` after a failed validation cycle. Each hint has the shape:
+```json
+{ "area": "string", "issue": "string", "fix": "string", "severity": "high|medium|low" }
+```
+When fixHints are present, you are NOT building from scratch — you are patching a previous build to address specific issues. Apply each fix surgically:
+- Re-read your previous output (the orchestrator passes its path).
+- For each fixHint, identify the exact selector or markup it references and apply the fix.
+- Keep everything else identical — don't refactor neighboring code, don't rename classes, don't re-pick patterns. The reviewer's diff should be the only diff.
+- High-severity fixes are mandatory. Medium are strongly recommended. Low are optional but apply them unless they conflict with high-severity ones.
+## Patterns (A-H fallback)
+These are the canonical recipes. When `<plugin>/memory/patterns.md` exists, prefer it. Each pattern is a markup-and-CSS skeleton — adapt the class names and content to the specific section.
+### A. Sticky Header (announcement + nav, mobile drawer)
+```html
+<header class="hdr">
+  <div class="hdr__bar">Free shipping over $50</div>
+  <nav class="hdr__nav" aria-label="Main">
+    <a href="/" class="hdr__logo"><img src="..." alt="Brand"></a>
+    <button class="hdr__menu-btn" type="button" aria-label="Open menu" aria-expanded="false">☰</button>
+    <ul class="hdr__menu" hidden>
+      <li><a href="/shop">Shop</a></li>
+      <li><a href="/about">About</a></li>
+    </ul>
+  </nav>
+</header>
+```
+Toggle `hidden` + `aria-expanded` on the button click via `<script>`. ~10 lines of vanilla JS.
+### B. Full-bleed Hero (aspect-ratio, background-image, escape Elementor)
+Use `background-image` on the container, NOT an `<img>` with `object-fit: cover`. See Hero rules above.
+### C. Carousel mobile / Grid desktop (scroll-snap → grid)
+```css
+.products { display: flex; overflow-x: auto; scroll-snap-type: x mandatory; gap: 16px; }
+.products__item { flex: 0 0 80vw; scroll-snap-align: start; }
+@media (min-width: 1000px) {
+  .products { display: grid; grid-template-columns: repeat(4, 1fr); overflow: visible; }
+  .products__item { flex: none; }
+}
+```
+### D. Image-with-text overlap
+When the source has an image overlapping a colored band, the band is a `::before` on the SECTION, not a sibling box. Inspect `inspection.pseudoElements` for the exact bounds (anti-pattern #6).
+```css
+.story { position: relative; }
+.story::before { content: ""; position: absolute; inset: 30% 0 0 0; background: #f4eee8; z-index: -1; }
+.story__image { width: 100%; }
+```
+### E. Defensive button (chain class + appearance + !important)
+```css
+.{scope} .{scope}__cta.{scope}__cta {
+  appearance: none;
+  background: #d8112a !important;
+  color: #fff !important;
+  font-family: inherit !important;
+  font-weight: 700 !important;
+  font-size: 16px !important;
+  border: 0;
+  padding: 14px 28px;
+  border-radius: 999px;
+  cursor: pointer;
+}
+```
+The double-class chain (`.{scope}__cta.{scope}__cta`) doubles specificity again — this is the only pattern where we double the modifier class itself, because button overrides are the most aggressive theme bleed.
+### F. FAQ collapsible (`<details>/<summary>`)
+```html
+<details class="faq__item">
+  <summary class="faq__q">How do I return an order?</summary>
+  <div class="faq__a">Email us within 30 days...</div>
+</details>
+```
+```css
+.faq__item summary::-webkit-details-marker { display: none; }
+.faq__item summary { list-style: none; cursor: pointer; }
+```
+### G. Trust banner with modal (vanilla JS ~30 lines)
+Use `<dialog>`:
+```html
+<button type="button" class="trust__more" data-open="trust-modal">Learn more</button>
+<dialog id="trust-modal" class="trust__modal">
+  <button type="button" class="trust__close" data-close>×</button>
+  <h2>Our guarantee</h2>
+  <p>...</p>
+</dialog>
+```
+```js
+document.querySelectorAll('[data-open]').forEach(btn =>
+  btn.addEventListener('click', () => document.getElementById(btn.dataset.open).showModal())
+);
+document.querySelectorAll('[data-close]').forEach(btn =>
+  btn.addEventListener('click', () => btn.closest('dialog').close())
+);
+```
+### H. Variant card e-commerce (radio + photo)
+Real product photos from `assetsMap`, not SVG illustrations. Radios with hidden inputs + styled labels.
+```html
+<fieldset class="variants">
+  <legend class="variants__title">Choose your size</legend>
+  <label class="variants__opt">
+    <input type="radio" name="size" value="30ml" checked>
+    <img src="{localPath}" alt="30ml bottle">
+    <span>30ml — $24</span>
+  </label>
+</fieldset>
+```
+## Anti-patterns (1-9 fallback)
+When `<plugin>/memory/anti-patterns.md` exists, prefer it. Otherwise these are the canon:
+1. **Hero `100vh` in Elementor** — clips on mobile. Use `aspect-ratio` + `max-height`.
+2. **`<img>` with `height: 100%` for full-bleed hero** — Elementor's `img { height: auto !important }` clobbers it. Use `background-image` on the container.
+3. **Guessing overlay opacity** — read the exact alpha from `inspection.tokens` or computed style. Never eyeball.
+4. **`.scope a { color: inherit }` clobbers button color** — buttons use `<button>`, not `<a>`. If a CTA must be an `<a>`, set its color literally, not via `inherit` or `currentColor`.
+5. **`<button>` decorative without defensive specificity** — chain the class + `!important` on the four font properties + background + color (Pattern E).
+6. **`!important` alone without ancestor prefix** — useless. The theme has both ancestor specificity AND `!important`. You need both too.
+7. **Modeling overlap-image as a sibling box** — it's a `::before` on the section. Check `inspection.pseudoElements`.
+8. **Showing output before validating in Playwright** — every build must pass through `sb-validate-render` before being shown. Aggressive theme reset injected, screenshot diff'd.
+9. **Replicating an image as inline SVG** — download the actual asset (it's already in `assetsMap`). Inline SVG is for icons that came from the source as SVG, not for raster impostors.
+## Theme reset (preset fallback — wp-elementor.yaml)
+When `<plugin>/presets/wp-elementor.yaml` exists, prefer its `theme_reset` block. Otherwise these are the known overrides Elementor + Hello/Astra/most themes inject:
+```css
+/* What the theme injects (informational — do NOT include in your output) */
+.elementor, .elementor * { font-weight: 300 !important; font-size: 18px !important; font-family: 'Roboto', sans-serif !important; }
+.elementor h1, .elementor h2, .elementor h3 { font-weight: 300 !important; font-size: 24px !important; }
+.elementor img, img { max-width: 100% !important; height: auto !important; border-radius: 0 !important; }
+.elementor button, button { background: transparent !important; border: 0 !important; padding: 0 !important; }
+.elementor a { color: inherit !important; text-decoration: none !important; }
+```
+This is what you are defending against. Every selector in your output that styles a property on this list MUST win on specificity (chained scope) and may need `!important` (font properties only).
+## Output skeleton
+Lay out the file in this order — it's the order Elementor parses and the order CSP browsers like:
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="preload" as="image" href="{hero localPath}">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=...&display=swap">
+<style>
+  /* 1. Reset */
+  .{scope}, .{scope} * { box-sizing: border-box; margin: 0; padding: 0; }
+  /* 2. Scope container (full-bleed if applicable) */
+  .{scope} { width: 100vw; margin-left: calc(50% - 50vw); }
+  /* 3. Element styles, mobile-first, with defensive specificity */
+  .{scope} .{scope}__hero { ... }
+  .{scope} .{scope}__title { font-size: 32px !important; font-weight: 700 !important; ... }
+  /* 4. Desktop overrides */
+  @media (min-width: 1000px) {
+    .{scope} .{scope}__hero { ... }
+  }
+</style>
+<section class="{scope}">
+  <!-- markup -->
+</section>
+<script>
+  /* optional vanilla JS */
+</script>
+```
+If there's no JS, omit the `<script>` block entirely. If no Google Font is needed (system stack only), omit the font links.
+## What "production-grade" means
+The output must score high on Lighthouse the moment it lands — not after follow-up tweaks. Concretely:
+- All images have alt + correct loading attr
+- Hero has preload link
+- Fonts have display=swap + preconnect
+- No layout-shift bombs (aspect-ratio set on media)
+- Buttons have type="button"
+- No console errors from missing assets (every src is a real localPath)
+- HTML validates (no unclosed tags, proper nesting)
+- CSS is scoped, no global pollution
+The structural validator (`scripts/build-wp.mjs validate`) checks the mechanical subset of these. The rest is on you — they're judgment calls.