Quick Fixes

Writing About a Security Block Can Itself Get Blocked

The Culprit: A batch of debugging notes describing a previous incident (a hosting security layer rejecting a save based on field naming) failed to save — with the exact same "invalid response" symptom as the original bug it was documenting.

The Fix: The content itself was flagged, not any code in it — words like "firewall," "WAF," "403," and "blocked," clustered together, matched the same kind of pattern a security layer watches for in genuinely malicious payloads, since the vocabulary overlaps with both an honest bug report and an actual exploit description. Rewriting the same lesson with softer, more generic wording ("security software," "rejected," "a security layer") preserved the content while no longer matching the trigger pattern. When documenting a security-related bug, expect the documentation itself to sometimes hit the same wall the bug did.

Two Independently-Valid PHP Snippets Can Silently Block Each Other’s Registration

The Culprit: Both snippets passed php -l individually and executed cleanly through a full WordPress-function-stub test in isolation. No PHP error appeared anywhere – not the server's own error log, not the code-snippet plugin's internal error log. The failure only showed up as the shortcode tag rendering as literal unprocessed text on the page.

The Fix: Systematic bisection was the only thing that actually worked: deactivating every other active snippet one at a time (ruling out content, size, and execution order along the way) eventually proved the interference was specific to how the snippet-management plugin combines multiple "Run Everywhere" PHP snippets into one execution context – not a bug in either snippet's own code. The practical fix was converting both snippets into standalone plugin files instead, which fully resolved it. When two provably-correct pieces of code fail only in combination and never independently, suspect the platform combining them, not either piece itself.

A URL-Shaped Field Name Can Get a Legitimate Form Rejected on Save

The Culprit: An with an id referencing "url" and a placeholder that looked like a website address was enough to trigger the rejection. The exact same markup, already saved elsewhere on the site, worked fine – only a fresh save of that content failed.

The Fix: Bisecting the markup itself, one attribute at a time, isolated it to the specific combination of a URL-referencing id plus a URL-shaped placeholder value – a naming pattern that a hosting provider's own server-level security layer was reacting to before the request ever reached WordPress. Renaming the id and softening the placeholder text, with no other change, resolved it immediately. Hosting-level security software can reject a save based on field naming, not just field type or actual content.

Hardcoded Absolute URLs Break Cross-Origin Testing on Staging

The Culprit: The script's fetch URL was hardcoded to the production domain rather than a relative path, making it a genuine cross-origin request once loaded from staging – confirmed directly via a CORS error in the browser console.

The Fix: Changing the hardcoded absolute URL to a relative path let the browser resolve it to whichever domain is actually serving the page – same-origin on both staging and production, no CORS involved on either. This is a strictly better pattern than the original, not just a staging workaround.

// Wrong — hardcoded absolute URL, breaks on any other domain:
var ERRORS_URL = 'https://zu2b.com/zu2b-web-error-guide.json';

// Right — relative path, resolves to whichever domain serves the page:
var ERRORS_URL = '/zu2b-web-error-guide.json';

A Security Dashboard’s Activity Log Can Lag a Full Day Behind Real Time

The Culprit: The log's date picker couldn't even select the current day, only showing entries through the previous day – the dashboard's historical reporting view is built for later review, not real-time confirmation, and simply hadn't caught up yet.

The Fix: Most security dashboards that separate historical reporting from a live view have a separate live-activity tab – check for that specifically when debugging something that just happened, rather than trusting the historical log to reflect events from the current day.

Bisect to an Empty Baseline Before Trusting Any Single Theory

The Culprit: Reasoning about what code "looks like" it might be responsible for a bug is a weaker signal than actually testing it – several confident-sounding explanations (a specific function call, a naming collision, an execution-order issue) were each individually ruled out once tested directly.

The Fix: Reducing the suspect code down to the smallest possible non-functional stub, confirming that baseline works, then adding pieces back one at a time until it breaks again pinpoints the exact cause directly, rather than guessing based on appearance.

After a Site Restore, Several Unrelated Settings Can Silently Revert

The Culprit: A morning site restore fixed the immediate problem it was meant to fix, but also silently reverted several unrelated things: the Reading Settings homepage selection (causing a 404), a WPCode mu-plugins-style toggle-back, and a Sucuri hosting-IP entry pausing — none of which threw an obvious error pointing back to "the restore did this."

The Fix: After any full-site restore, explicitly re-check Settings → Reading (homepage/posts page), any security plugin's IP/origin configuration, and recently-active third-party integrations — rather than assuming a restore only touches the specific thing it was run to fix.

When Chasing “Everything Feels Slow,” Isolate the Narrow Symptom First

The Culprit: A REST API timeout got initially treated as a general "site is slow" problem, prompting checks across Action Scheduler queues, cron events, file permissions, and caching settings — most of which came back clean and cost real time to rule out.

The Fix: The single most useful step was deactivating plugins one at a time and re-checking Site Health after each, which isolated the failure to one specific plugin's one specific REST endpoint (real-queue/v1/jobs). That turned a vague complaint into a concrete, researchable error. When general slowness and a specific error coexist, isolate the specific error first — the general feeling of slowness is often just a symptom of that one narrow cause, not a separate problem to solve on its own.

Match Type Matters: “Matches” vs. “Begins With” in WAF URL Allowlist Rules

The Culprit: An allowlist rule for /wp-json/ saved successfully under "Matches" mode but had zero measurable effect — because "Matches" requires an exact, full-path match, while real REST requests hit longer sub-paths (e.g. /wp-json/wp/v2/types/post?context=edit).

The Fix: Switching the match type to "Begins with" made the rule cover everything under /wp-json/, not just the bare path. URL-path rules in most WAF/CDN tools offer distinct match modes (Matches/Exact, Begins With, Contains, Ends With) — a rule that saves cleanly can still be functionally inert if the match type doesn't fit the actual request shape.

An Intermittent REST API Timeout Can Point to a Correct Rule That Hasn’t Actually Applied Yet

The Culprit: Site Health's REST API check (cURL error 28: Operation timed out) kept flapping between clear and broken over several hours — even after adding a Sucuri WAF allowlist rule for /wp-json/. The rule saved without error and looked correct, but the timeout kept returning on its own unpredictable schedule.

The Fix: The rule itself wasn't wrong — it just hadn't been picked up cleanly by the firewall's rule engine. Toggling Sucuri's firewall off, then back on, forced a full rule reload, and the timeout stopped recurring afterward. A saved WAF/CDN rule isn't guaranteed to be "live" the instant it's saved; if a fix looks correct on paper but the symptom keeps intermittently returning, cycling the security layer off and on is worth trying before concluding the rule itself is wrong.

Make a Button Wider

The Culprit: A button's width defaults to fitting its own label and padding, which can look narrow or unbalanced next to other elements on the page.

The Fix: Set the button to a specific, larger width instead of relying on its own natural size.

.my-button {
  width: 220px;
}

Make a Button Narrower

The Culprit: A button sized for its longest possible label can look oversized once shorter text is used, or inside a tighter layout.

The Fix: Set the button to a specific, smaller width.

.my-button {
  width: 160px;
}

Make a Button Taller

The Culprit: A button's height is only as tall as its text and default padding require, which can look cramped next to more generously spaced elements.

The Fix: Increase the vertical padding to add height without changing the button's width.

.my-button {
  padding-top: 14px;
  padding-bottom: 14px;
}

Make a Button Shorter

The Culprit: A button with generous default padding can look oversized in a compact layout, like a form or a tight card.

The Fix: Reduce the vertical padding to make the button shorter.

.my-button {
  padding-top: 8px;
  padding-bottom: 8px;
}

Remove a Button’s Rounded Corners

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Square off the button's corners entirely.

.my-button {
  border-radius: 0;
}

Round Only the Top Corners of an Element

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round just the top two corners, leaving the bottom edge square. The four values go top-left, top-right, bottom-right, bottom-left, in that order.

.my-element {
  border-radius: 16px 16px 0 0;
}

Round Only the Bottom Corners of an Element

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round just the bottom two corners, leaving the top edge square.

.my-element {
  border-radius: 0 0 16px 16px;
}

Round Just One Corner of an Element

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Target a single corner directly, rather than using the four-value shorthand for one change.

.my-element {
  border-top-left-radius: 16px;
}

Make a Border Thicker

The Culprit: A default 1px border can look too thin to register as an intentional design element, especially at larger sizes.

The Fix: Increase the border's width while keeping its color and style unchanged.

.my-element {
  border-width: 2px;
}

Scale an Element Up or Down Slightly

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Scale the element larger or smaller than its natural size – a value above 1 scales up, below 1 scales down. This changes only the visual size, not the space the element takes up in the layout, so it can overlap neighboring elements if scaled too far.

.my-element {
  transform: scale(1.05); /* use scale(0.95) to shrink instead */
}

Change Text Size Directly

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Set the font size to a specific pixel value rather than relying on a default or inherited size.

.my-element {
  font-size: 20px; /* use a smaller value like 16px to reduce it */
}

Move an Element Sideways

The Culprit: A small horizontal positioning correction is needed, but changing margin or padding would shift other elements around it too.

The Fix: Shift the element left or right visually without affecting the normal document flow around it. A negative value moves left, a positive value moves right.

.my-element {
  transform: translateX(-10px); /* use a positive value to move right instead */
}

Move an Element Down

The Culprit: A small vertical positioning correction is needed, but changing margin or padding would shift other elements around it too. This is the downward counterpart to Move an Element Slightly.

The Fix: Shift the element down visually without affecting the normal document flow around it.

.my-element {
  transform: translateY(5px);
}

Keep an Image From Stretching to Fill Its Frame

The Culprit: object-fit: cover crops an image to fill its container, which isn't always what's wanted if the full image needs to stay visible.

The Fix: Let the image scale to fit within its container without cropping, adding empty space on the shorter side instead.

.my-image {
  object-fit: contain;
}

Center Content Vertically

The Culprit: Vertical centering isn't straightforward with normal block layout – content just sits at the top of its container by default.

The Fix: Turn the container into a flex container and center its content along the vertical axis. Depends on the container having a defined height; one that only sizes to fit its own content will show no visible change.

.my-element {
  display: flex;
  align-items: center;
}

Center Content Horizontally

The Culprit: Content doesn't center itself by default on either axis without deliberate layout instructions.

The Fix: Turn the container into a flex container and center its content along the horizontal axis.

.my-element {
  display: flex;
  justify-content: center;
}

Center Content Both Ways

The Culprit: Centering an element on only one axis leaves it aligned to the default edge on the other.

The Fix: Combine both properties to center the content vertically and horizontally at once. Same container-height dependency as vertical centering alone.

.my-element {
  display: flex;
  align-items: center;
  justify-content: center;
}

Adjust an Element’s Opacity

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Set a value between 0 and 1 to make the element partially see-through. Lower values are more transparent, higher values are closer to fully visible.

.my-element {
  opacity: 0.7; /* move closer to 1 for more visible, closer to 0 for more transparent */
}

Remove a Shadow

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Remove an existing shadow entirely.

.my-element {
  box-shadow: none;
}

When Every Error-Reporting Layer Stays Silent, Trace Execution With Direct File Writes

The Culprit: debug.log, the server-level error log, WPCode's own fatal-error auto-deactivation, a custom register_shutdown_function fatal catcher, and a custom set_error_handler catching every warning and notice all came back completely empty, despite the bug being fully and repeatedly reproducible. Whatever was happening wasn't a standard PHP fatal, warning, or notice that any of these layers are built to see.

The Fix: Bypass every error-reporting layer entirely and trace execution by hand: drop plain, unconditional markers directly into the code with file_put_contents(), writing to a plain text file outside any logging system. Compare which markers do and don't appear across test runs to pinpoint exactly how far execution gets before something goes wrong – this was the only method all session that produced any real signal.

function zfn_debug_mark( $label ) {
  file_put_contents(
    WP_CONTENT_DIR . '/uploads/your-debug.log',
    date('c') . " - $labeln",
    FILE_APPEND
  );
}
zfn_debug_mark( 'reached this point' );

A Clean init Hook Doesn’t Prove a Custom Post Type’s Admin Menu Will Appear

The Culprit: register_post_type() is commonly called on init, but WordPress builds the actual admin sidebar menu on a separate, later hook called admin_menu. A clean marker on init only proves the post type object itself registered – it says nothing about whether the later menu-building step actually succeeded. Trusting an init-only marker as proof the menu would appear cost a full round of false-negative testing before this was caught.

The Fix: When testing whether something admin-menu-related is actually working, add a diagnostic marker directly on admin_menu itself (a late priority like 999 ensures it runs after everything else on that hook) – test the specific hook that governs the real behavior in question, not just the nearest hook that happens to be convenient to log.

add_action( 'admin_menu', function() {
  // confirms the menu-building step itself actually ran
  zfn_debug_mark( 'admin_menu fired' );
}, 999 );

Keyword Auto-Linking Needs Word-Boundary Matching, Not Plain Substring Search

The Culprit: A plain substring search (JavaScript's indexOf, or an equivalent) matches a short term anywhere it appears as a sequence of characters, even mid-word. Confirmed directly: a dictionary term "URL" matched inside the unrelated word "curly," and "DOM" matched inside "domain" – both false positives from treating any character match as a hit, with no awareness of word boundaries.

The Fix: Match only whole-word occurrences using a word-boundary-anchored regular expression instead of plain substring search.

// Wrong — plain substring search, matches mid-word:
text.toLowerCase().indexOf(term.toLowerCase())

// Right — word-boundary regex, whole-word matches only:
var re = new RegExp("b" + term + "b", "i");
var match = re.exec(text);

Sorting a WordPress Admin Column by Meta Value Can Silently Exclude Unset Posts

The Culprit: Sorting a WP_Query by meta_key plus orderby: meta_value (or meta_value_num) uses an inner join on the postmeta table. Any post that doesn't have that meta key at all gets silently excluded from the result set – not sorted to one end, removed entirely. This happened twice independently on the same site: once for an existing Stage column, once for a brand-new column, both with the identical structural flaw.

The Fix: Add an explicit meta_query with an OR relation combining an EXISTS clause and a NOT EXISTS clause for the same key. This is WordPress's own documented pattern for keeping every post in the result set regardless of whether it has a value to sort by yet.

$query->set( 'meta_key', 'your_meta_key' );
$query->set( 'orderby', 'meta_value' ); // or meta_value_num

$query->set( 'meta_query', array(
  'relation' => 'OR',
  array( 'key' => 'your_meta_key', 'compare' => 'EXISTS' ),
  array( 'key' => 'your_meta_key', 'compare' => 'NOT EXISTS' ),
) );

A Snippet Calling a Function From Another Snippet Needs a function_exists Guard

The Culprit: One snippet calling a function defined in a separate snippet creates a hard, unguarded dependency. If the other snippet is ever deactivated, temporarily emptied for testing, or simply fails to load first, the calling snippet throws a fatal error the instant that function gets called – confirmed directly via a real error log entry, not a hypothetical.

The Fix: Wrap any cross-snippet function call in a function_exists() check. If the function isn't available for any reason, the page simply renders without that piece instead of crashing outright.

if ( function_exists( 'your_external_function' ) ) {
  echo your_external_function( $some_argument );
}

When a Bug’s Cause Is Unclear Across Several Recently-Changed Files, Isolate One at a Time

The Culprit: Code that looks structurally correct on review can still hide the actual cause, especially when several plausible suspects exist at once. Two fix attempts based on code review alone both missed the real cause in a recent case, before a more disciplined test finally isolated it.

The Fix: Reduce one file to completely empty (or comment out whole sections) while holding everything else constant, then retest. If the bug persists with that file doing nothing at all, its cause is proven to be somewhere else entirely – a definitive result from one round of testing, rather than another guess.

When a Snippet Search Comes Up Empty, the Content Might Not Be in a Snippet at All

The Culprit: Content pasted directly into page content (a Custom HTML block, for instance) lives in the WordPress database itself, not in any code snippet – so a snippet-only search, or even a plugin built specifically for search-and-replace, can come back completely empty while the real matches sit untouched in the pages table.

The Fix: Search the WordPress database directly – via phpMyAdmin's own search tab, or a direct SQL query against the posts table – rather than trusting a snippet-only tool to have covered every possible location content could live.

SELECT ID, post_title, post_type, post_status
FROM wp_posts
WHERE post_content LIKE '%your-search-text%'
AND post_status = 'publish'
AND post_type IN ('page', 'post')

Style Button Hover Transitions

The Culprit: A button with no transition property changes state instantly, which reads as stiff and unpolished rather than intentional.

The Fix: Add a smooth transition on the properties that change, then define what the hover state actually shifts to – here, a slight lift.

.my-button {
  transition: background-color 0.2s ease, transform 0.2s ease;
}
.my-button:hover {
  transform: translateY(-2px);
}

Place Two Images Side by Side

The Culprit: Image elements are block-level by default, so with no layout instruction they simply stack one on top of the other.

The Fix: Wrap the images in a flex container so they line up horizontally, with controlled spacing between them. Depends on the surrounding markup already grouping the images inside a shared wrapper.

.image-row {
  display: flex;
  gap: 16px;
}
.image-row img {
  width: 50%;
  height: auto;
}

Change the Color of a Specific Word or Phrase

The Culprit: A CSS color rule applies to an entire element uniformly – there's no way to target a single word inside a heading without first isolating it in its own element.

The Fix: Wrap just the one word in an inline span, then target that span's color independently of the rest of the heading.

<h2>Build your site <span class="highlight-word">faster</span></h2>

.highlight-word {
  color: #0DC0B3;
}

Style Custom Scrollbars

The Culprit: A default browser scrollbar is plain gray and doesn't match a custom dark or brand-colored theme.

The Fix: Set a slim, themed scrollbar for modern browsers. This covers Firefox directly – Chrome and Safari need additional ::-webkit-scrollbar pseudo-elements for the same effect, since they don't support this shorthand.

.scroll-container {
  scrollbar-width: thin;
  scrollbar-color: #0DC0B3 #0B0C10;
}

⚠️ Firefox only; Chrome/Safari need ::-webkit-scrollbar too

Create a Simple Pure-CSS Arrow Icon

The Culprit: Loading an icon font or an image for a single small arrow adds an extra network request and file weight for something CSS can draw directly.

The Fix: Build the arrow from two rotated borders. It automatically inherits the surrounding text color via currentColor, so it stays in sync with whatever element it sits inside.

.arrow-right {
  display: inline-block;
  width: 8px;
  height: 8px;
  border-top: 2px solid currentColor;
  border-right: 2px solid currentColor;
  transform: rotate(45deg);
  margin-left: 6px;
}

Add a Subtle Hover Lift to a Card

The Culprit: A static card with no hover feedback can feel flat, even when it's actually clickable.

The Fix: Combine a small upward shift with a slightly stronger shadow on hover, giving an instant tactile sense that the card is interactive.

.my-card {
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.my-card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.25);
}

Break an Element Out to Full Screen-Width

The Culprit: A section inherits its parent container's max-width, so it can't reach the real viewport edges on its own, however wide the parent lets it grow.

The Fix: This exact technique is also the confirmed cause of a real horizontal-scrollbar bug on pages that don't account for it – the negative margins can make the element measure slightly wider than the true viewport. Pairing this with body { overflow-x: hidden; } is often necessary (see "Prevent Horizontal Scrolling"), and applying it once to a single top-level wrapper – rather than separately per section – avoids a related centering bug (see "Wrap a Whole Page Once for Full-Bleed, Not Per-Section").

.full-width-breakout {
  width: 100vw;
  position: relative;
  left: 50%;
  right: 50%;
  margin-left: -50vw;
  margin-right: -50vw;
}

Responsive Mobile Spacing Adjustment

The Culprit: A padding value chosen for a wide desktop layout doesn't automatically scale down for a much narrower mobile viewport.

The Fix: Reduce the padding specifically at mobile widths. This site's own standard mobile breakpoint is 600px, used consistently across every page – matching it avoids one component behaving differently from everything else.

.my-section {
  padding: 60px 20px;
}
@media (max-width: 600px) {
  .my-section {
    padding: 30px 15px;
  }
}

A CSS Grid Item Won’t Shrink Below Its Content’s Natural Size

The Culprit: CSS Grid items default to min-width: auto, meaning a grid item won't shrink below its own content's natural minimum width – even a single card elsewhere in the same grid with a wide, unbreakable string (a long code block, an unbroken URL) can force the shared column wider for every card in that grid, not just the one that contains it.

The Fix: Explicitly override the default by setting min-width: 0 directly on the grid item. This allows it to shrink as intended and rely on internal wrapping or scrolling, instead of silently inheriting a sibling's content-driven minimum width.

.grid-item {
  min-width: 0;
}

Wrap a Whole Page Once for Full-Bleed, Not Per-Section

The Culprit: Applying the full-bleed 100vw technique separately to individual sections (rather than once, to a single top-level wrapper) leaves other sections centering relative to their own inconsistent container instead of the true viewport, producing a small, hard-to-trace horizontal offset.

The Fix: Wrap the page's entire content in one single element and apply the full-bleed technique there, once. Let everything else inside center normally relative to that one correctly-anchored wrapper, rather than each section doing its own separate breakout.

.page-wrap {
  width: 100vw;
  position: relative;
  left: 50%;
  right: 50%;
  margin-left: -50vw;
  margin-right: -50vw;
}

Replace Deprecated mb_convert_encoding HTML-ENTITIES Calls

The Culprit: mb_convert_encoding() with 'HTML-ENTITIES' as the target encoding was deprecated in PHP 8.2. Any server that upgrades its own PHP version will start logging this notice on unchanged code that previously ran silently.

The Fix: Replace it with mb_encode_numericentity(), which does the same job – converting non-ASCII characters to numeric HTML entities – without triggering the deprecation. Avoid htmlspecialchars() as a substitute here if the content contains real HTML tags you still need parsed afterward, since it would escape those tags too.

$convmap = array(0x80, 0x10FFFF, 0, 0xFFFFFF);
$safe_content = mb_encode_numericentity($content, $convmap, 'UTF-8');

Old, Unchanged Code Suddenly Erroring Means Check the Server First

The Culprit: It's tempting to assume you broke something, but unchanged code can't spontaneously introduce a new bug on its own.

The Fix: Check whether anything changed on the server side instead – most commonly a PHP version upgrade performed by the host. Compare the snippet's last-edited date against when the error first appeared; a real gap between the two is the clearest signal the cause is environmental, not code-side.

A Feature Split Across PHP and CSS Can Go Silently Half-Styled

The Culprit: When a single feature's markup and its styling live in two separate files or snippets, updating one without the other leaves the new markup with zero matching styles – and because nothing throws an error, this can go unnoticed for a long time.

The Fix: Whenever a feature's HTML or PHP output changes, treat its matching CSS as part of the same change, not a separate task – check both together, especially after adding a new element type or changing how something filters or displays.

Make an Element Sit Above Another Element

The Culprit: Overlapping elements stack in an order the browser determines on its own, which isn't always the order you want.

The Fix: Raise the element's stacking order above its sibling. Behavior depends on the surrounding stacking contexts – z-index alone doesn't always work as expected if a parent element establishes its own separate stacking context.

.my-element {
  position: relative;
  z-index: 2;
}

Background Image With Adjustable Opacity

The Culprit: Setting opacity directly on a section fades everything inside it, including the text and content, not just the background.

The Fix: Create a separate image layer using a pseudo-element, so its opacity can be controlled independently of the real content.

.example {
  position: relative;
  isolation: isolate;
}
.example::before {
  content: "";
  position: absolute;
  inset: 0;
  background-image: url("IMAGE-URL-HERE");
  background-size: cover;
  background-position: center;
  background-repeat: no-repeat;
  opacity: 0.25;
  z-index: -1;
}

Set a Minimum Hero Height

The Culprit: A fixed height can clip content that ends up taller than expected; no height at all can make a section feel too short with little content.

The Fix: Set a minimum height that the section will never go below, while allowing it to expand naturally if content requires more room.

.my-hero {
  min-height: 520px;
}

Position Media Consistently

The Culprit: Media doesn't always crop or center the way you'd want by default, especially across different aspect ratios.

The Fix: Make the media cover its container fully and keep the focal position centered. This alone does not fix a video loop jumping at its restart point – that's a footage/frame issue, not a CSS positioning one.

.my-media {
  object-fit: cover;
  object-position: center;
}

Create a Reusable CSS Class

The Culprit: Styling each element individually means the same change has to be made in many places every time it's adjusted.

The Fix: Define a reusable class once, then assign it to any block or element that needs the same treatment – in WordPress, this is typically added under a block's Advanced -> Additional CSS Class(es) setting.

.quick-fix {
  /* styles go here */
}

Use a Pseudo-Element as a Visual Layer

The Culprit: Adding a real extra div just for a visual effect adds markup that has nothing to do with the actual content.

The Fix: Create a pseudo-element that can serve as an overlay, decorative layer, gradient, or other visual effect – the same underlying technique behind the adjustable-opacity background fix above.

.example::before {
  content: "";
  position: absolute;
  inset: 0;
}

Put Text on a New Line

The Culprit: Text wraps wherever the browser decides, not necessarily where you want the visual break to happen.

The Fix: Insert a line break tag at the exact point you want the line to break. Unlike CSS-based wrapping, this forces a break at that specific spot regardless of container width.

<br>

Prevent Long Words From Overflowing

The Culprit: A long word or URL has no natural space for the browser to wrap at, so it just keeps going past the container edge.

The Fix: Allow the browser to break long words mid-word when necessary, rather than only at spaces.

.my-container {
  overflow-wrap: break-word;
}

Center Text

The Culprit: Text defaults to left-aligned unless told otherwise.

The Fix: Center inline text within its containing element. If a theme or page builder is overriding this, adding !important before the semicolon usually resolves it.

.my-section {
  text-align: center;
}

Left-Align Text

The Culprit: Some theme or block default is centering text that should read normally from the left edge.

The Fix: Explicitly set left alignment rather than relying on a default that something else may be overriding.

.my-section {
  text-align: left;
}

Add Space Below an Element

The Culprit: No margin is set between two stacked elements, so they sit flush against each other.

The Fix: Add space below the element, pushing whatever comes next further away.

.my-element {
  margin-bottom: 20px;
}

Add Space Inside an Element

The Culprit: No internal spacing is set, so content touches the container's own border or edge directly.

The Fix: Add internal space on every side of the element's content.

.my-box {
  padding: 20px;
}

Keep an Element From Getting Wider Than Its Container

The Culprit: The element has no width constraint, so it renders at its own natural size regardless of the space actually available.

The Fix: Cap the element's width at 100% of its container while letting height scale proportionally, so it never overflows.

.my-media {
  max-width: 100%;
  height: auto;
}

Make an Image Fill Its Container

The Culprit: A plain image tag displays at its natural aspect ratio, which may not match the shape of the space it needs to fill.

The Fix: Make the image fill its container fully, cropping automatically to maintain proportions.

.my-image {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

Keep an Image Proportional

The Culprit: Both width and height are being forced to specific values that don't match the image's real aspect ratio.

The Fix: Let the image's width scale to its container while height adjusts automatically, preserving the original proportions.

.my-image {
  width: 100%;
  height: auto;
}

Round Image Corners

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round the corners of the image.

.my-image {
  border-radius: 12px;
}

Create a Subtle Dark Image Overlay

The Culprit: A background image alone doesn't guarantee enough contrast for text placed on top of it.

The Fix: Add a translucent dark layer as part of the background treatment, darkening the image enough for light text to stay readable. Depends on how the rest of the section's background is structured.

.my-section {
  background-color: rgba(0, 0, 0, 0.4);
}

Control Background Image Positioning

The Culprit: A background image's default positioning may crop out the subject depending on the container's actual proportions.

The Fix: Center the background image within its container as a starting point.

.my-hero {
  background-position: center;
}

Hide Something on Mobile

The Culprit: An element that makes sense on desktop can be unnecessary or cluttered on a narrow mobile screen.

The Fix: Hide the element once the viewport narrows past a set breakpoint. Every page on this site uses 600px as the standard mobile breakpoint – matching that consistently avoids a component behaving differently from everything else.

@media (max-width: 600px) {
  .example { display: none; }
}

Show Something Only on Mobile

The Culprit: An element built specifically for mobile (like a condensed nav) shouldn't also show on desktop.

The Fix: Hide the mobile-only element once the viewport widens past the standard 600px breakpoint used across this site.

@media (min-width: 601px) {
  .mobile-only { display: none; }
}

Reduce Text Size on Mobile

The Culprit: A font size chosen for a wide desktop layout doesn't always scale down gracefully on its own.

The Fix: Reduce the font size specifically at mobile widths, using the site's standard 600px breakpoint.

@media (max-width: 600px) {
  .example { font-size: 18px; }
}

Reduce Spacing on Mobile

The Culprit: Generous desktop spacing can eat up a disproportionate amount of a small mobile viewport.

The Fix: Reduce internal spacing specifically at mobile widths, using the site's standard 600px breakpoint.

@media (max-width: 600px) {
  .example { padding: 20px; }
}

Prevent Horizontal Scrolling

The Culprit: An element somewhere on the page is rendering wider than the actual viewport.

The Fix: Hide horizontal overflow at the body level. Use this carefully as a general habit, since it can conceal a real underlying layout problem rather than fixing it – but on this site specifically, it is also the confirmed, deliberate fix for the known full-bleed 100vw scrollbar issue that several pages have hit (see the matching Error Guide entry): when a full-bleed element is the actual cause, this is the correct fix, not a workaround.

body {
  overflow-x: hidden;
}

Add Rounded Corners to a Card

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round the corners of the card.

.my-card {
  border-radius: 16px;
}

Add a Subtle Border

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Add a subtle, semi-transparent border around the element.

.my-card {
  border: 1px solid rgba(255, 255, 255, 0.15);
}

Add a Simple Shadow

The Culprit: A flat card with no shadow can blend into a matching background color.

The Fix: Add a soft shadow around the element to lift it visually off the background.

.my-card {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
}

Make a Button Stretch Across Its Container

The Culprit: A button defaults to only as wide as its own label and padding require.

The Fix: Make the button take up the full width of its container.

.my-button {
  width: 100%;
}

Change the Mouse Cursor

The Culprit: An element with a click handler (a div, a span) doesn't automatically get the pointer cursor the way a real link or button does.

The Fix: Change the cursor to the pointer style on hover, signaling the element is interactive.

.clickable-item {
  cursor: pointer;
}

Hide an Element Without Removing Its Space

The Culprit: display: none removes an element from the layout entirely, which can cause everything around it to shift.

The Fix: Hide the element visually while preserving its space in the layout – the key difference from display: none, which removes the element from the layout entirely rather than just hiding it in place.

.my-element {
  visibility: hidden;
}

Move an Element Slightly

The Culprit: A small positioning correction is needed, but changing margin or padding would shift other elements around it too.

The Fix: Shift the element visually without affecting the normal document flow around it. Depends on context – a repeated need for this on the same component is often a sign the underlying layout should be restructured instead, not a signal to keep nudging.

.my-element {
  transform: translateY(-5px);
}

WordPress Footer Template Requires Its Own Save Cycle

The Fix: 1. Identify whether the block is on a page or inside a template part (header, footer, sidebar).
2. If it is in a template part, navigate to Appearance → Editor and find the template.
3. Confirm the template shows unsaved changes and save it directly.
4. Clear caches after saving the template, not before.

iOS Safari Keyboard Scroll Collapses a Fixed-Position Popup Widget

The Fix: 1. Check whether `max-height` uses `100vh` — replace with `dvh`.
2. Check whether any `scroll` event listener closes or hides the widget.
3. Check whether the popup has `position: fixed` — if not, it may reposition unexpectedly when the viewport shifts.
Two fixes applied together:

**Fix 1 — Replace `vh` with `dvh`:**
```css
@media (max-width: 600px) {
  .widget-popup {
    max-height: 70dvh;
    position: fixed;
  }
}
```

**Fix 2 — Guard the scroll listener:**
```javascript
window.addEventListener('scroll', function() {
  if (popup.classList.contains('open')) return; // ignore scroll while widget is open
  // hide launcher logic...
});
```

Unicode Characters Inside Base64-Encoded JS Render as Garbled Text

The Fix: 1. Identify whether the garbled characters are special Unicode (em-dash, curly quotes, accented characters).
2. Check the original source file's encoding (`utf-8` vs. `latin-1`).
3. Look for any Unicode characters outside the basic ASCII range inside JS string literals.
Replace all non-ASCII characters in JS strings with plain ASCII equivalents before encoding:

- Em-dash `–` → hyphen `-`
- Left/right single quotes `'` `'` → straight apostrophe `'`
- Left/right double quotes `"` `"` → straight quote `"`

In Python before encoding:
```python
content = content.replace('u2013', '-')
content = content.replace('u2019', "'")

WordPress wptexturize Breaks JavaScript in Custom HTML Blocks

The Fix: 1. View the page source and find the “ block.
2. Look for curly quotes (`'` `'` or `"` `"`) where straight quotes should be.
3. Check whether the block is inside a WordPress template part or footer — these pass through the same wptexturize filter.
4. Check the browser console for a `SyntaxError` on script evaluation.
Base64-encode the entire JavaScript block and load it via `eval(atob("…"))`. Since the encoded string contains no quote characters, wptexturize has nothing to mangle.
The pattern:

```html
<script>eval(atob("BASE64_ENCODED_JS_HERE"))</script>
```

Encode in Python: `base64.b64encode(js.encode('utf-8')).decode('utf-8')`

Mobile breakpoint explicitly setting 1fr 1fr overrides any narrower fix

The Fix: 1. Find the lowest explicit grid column breakpoint in the CSS.
2. Confirm whether it is setting a specific column count (e.g., `1fr 1fr`) rather than just resetting other properties.
3. If so, that rule controls mobile layout regardless of what narrower breakpoints say — unless those narrower breakpoints also set the grid columns explicitly.
4. Verify any new breakpoints are inside the active “ tag, not in a comment block.
Edit the existing `600px` (or lowest active) breakpoint directly. Change `grid-template-columns: 1fr 1fr` to `grid-template-columns: 1fr`. Do not add a second narrower breakpoint — fix the one that's already firing.

```css
@media (max-width: 600px) {
  .grid-class { grid-template-columns: 1fr; }
}
```

When a View All Button Shows All Cards But “Show Fewer” Never Appears

The Fix: 1. Confirm `SHOW` value is less than the total card count — otherwise the button never appears
2. Check whether the ViewAll function hides the button (`display: none`) after click — this breaks the toggle
3. Verify the button text updates on both expand and collapse states

When a White Gap Appears at the Bottom of a Custom HTML Section

The Fix: 1. Open DevTools and click the element showing the wrong background — identify exactly which div is responsible
2. Count “ opens vs closes inside the suspected container
3. Check for comment markers (like “) that may give false confidence a div is closed
4. Verify the actual HTML structure rather than trusting the comment

When a WPCode Snippet Has No Location Set — and No Way to Set One

The Fix: 1. Open the snippet and look for an **Insertion** setting near the top of the editor (separate from Location).
2. Confirm whether it's set to Auto Insert, Shortcode, Page Builder, or another method — Location only exists under Auto Insert.
3. If it should be auto-inserted site-wide, switch Insertion to Auto Insert; the Location dropdown will then appear and can be set normally.
4. If it's intentionally a shortcode snippet, confirm the shortcode is actually placed somewhere — otherwise the snippet's code isn't running anywhere at all, even though it exists and is marked active.

When a Staging Fix “Looks Fine” But Isn’t Actually Live

The Fix: 1. Confirm you're actually viewing staging — check the address bar, not just the page content, especially after following in-page navigation links rather than typing the URL directly.
2. Clear the full cache stack in order, not just the browser cache, before concluding a fix didn't work.
3. Audit any Custom HTML blocks (nav menus, footers, embedded links) for hardcoded absolute domain URLs. Convert same-domain links to relative paths (`/page-slug/` instead of `https://domain.com/page-slug/`) so the same code behaves correctly on both staging and live.
4. To positively confirm you're looking at a fresh, correct version of a page — not a stale cache and not the wrong environment — make a small, visually obvious test change (e.g., an oversized font on one element), save, and hard-refresh. If the obvious change doesn't appear, the problem is caching or environment, not the original fix.

When an Accordion Opens But Never Closes, and No Error Appears Anywhere

The Fix: 1. Compare every class name referenced in the JavaScript against the actual class names used in the HTML markup, character by character. A single-letter typo in a class name inside a `querySelector` call will not produce any error.
2. Remember that `querySelector`/`querySelectorAll` matching zero elements is a silent no-op, not a failure state the browser will ever flag.
3. If part of a function's logic seems to be "missing" (like a reset or close step), check whether that step is actually running but simply matching nothing.

When a “Different Black” Section Turns Out to Be a Mislabeled Block, Not a Layout Bug

The Fix: 1. Use DevTools/List View to identify the exact block responsible, not just the visual area.
2. Check the block's HTML anchor name — a leftover or copy-pasted anchor from an earlier, unrelated block is a common source of confusion, especially in page builders where blocks get duplicated and repurposed over time.
3. Confirm the anchor name actually matches the block's current content before assuming a naming clue points to the real cause.
4. Compare the specific background color value (not just "looks dark") between the two sections — near-identical hex values are easy to mistake for a copy/paste of the same style, when they're actually two separate values that happened to land close to each other.

When One Domain Times Out on One Device While Everything Else Works Fine

The Fix: 1. Rule out the site/hosting first: if other domains work fine on the same network, and the affected domain works fine on a *different* network, the site itself is very unlikely to be the cause.
2. Flush DNS on the affected device as a first, low-effort step.
3. Test the domain on a completely different network (mobile hotspot) to isolate whether the problem is device-level or network-level.
4. If isolated to one network, suspect the router's own DNS cache rather than anything device-side.

When a Third-Party Search Widget’s Results Are Trapped in a Small Scrolling Box

The Fix: 1. Check whether the widget has a results *display mode* setting (Overlay vs. Full Width / inline / two-page results) in its own external configuration panel, separate from the embed code itself.
2. If available, switch away from an "overlay" or "floating" display mode to one that renders inline with the page's normal content flow.

WordPress FSE 404 Template Overridden by Full Site Editor Custom HTML Blocks

The Fix: Open Appearance → Editor → Templates → 404 → locate and delete the Custom HTML blocks containing the old content → add the new branded content as a fresh Custom HTML block → Save.

Preloaded Image 404 Persisting After Media Deletion

The Fix: Open Appearance → Editor → Templates → find the homepage template → locate the Cover block with the broken reference → remove the background image from within the block's settings directly.

When Fixing a Broken Script Accidentally Creates a Second, Conflicting Handler

The Fix: 1. Identify every place a given element's behavior might be bound, not just the one that's obviously broken.
2. Before patching a broken handler, check whether a working handler already exists elsewhere for the same element.
3. If two handlers do the same logical thing (like "toggle open, close others"), fixing the broken one without removing the redundant one will not restore correct behavior — it will create a race between two handlers that cancels the intended effect.

When a Styled Border Around a Third-Party Embed Is Missing Its Bottom Edge

The Fix: 1. Check whether a fixed `height` (rather than `min-height`) is being forced onto a container whose actual content comes from an external widget you don't fully control the internal padding of.
2. Check for `overflow: hidden` on the container or a parent element that could be clipping content taller than the fixed height.
3. Add `box-sizing: border-box` if border width isn't already being accounted for inside the stated dimensions.

When a Base64-Encoded Script Breaks Silently and Nothing on the Page Works

The Fix: The fix was to identify and remove the stray duplicated code fragment, re-balance the braces, then re-encode the corrected script back to base64 and swap it into the page.

When the Hero Height Needs to Change Without Changing the Video

The Fix: When a video hero is too tall on mobile:
1. Identify whether the video is a background video.
2. Inspect the surrounding Cover block.
3. Check the Cover's minimum height.
4. Check whether the video itself is actually determining the section height.
5. Adjust the container before modifying the media asset.
6. Verify that the overlaid content still fits comfortably.
7. Test the hero at several mobile viewport heights.

When the Mobile Version Needs a Different Layout Model

The Fix: When responsive CSS starts accumulating exceptions:
1. Count how many mobile-only offsets are being added.
2. Check whether transforms or negative margins are becoming necessary.
3. Ask whether the desktop structure still makes sense at the mobile width.
4. Consider Grid or Flexbox restructuring.
5. Group related content into predictable columns or rows.
6. Test intermediate widths, not just desktop and one phone size.
7. Remove obsolete positioning rules after changing the layout model.

Making a Hero Video Smaller Without Losing the Effect

The Fix: When optimizing a looping hero video:
1. Remove unnecessary duration.
2. Preserve only the motion needed to communicate the visual.
3. Make the beginning and ending visually compatible.
4. Compress the finished file.
5. Check the resulting file size.
6. Test the compressed version on the actual website.
7. Confirm that reducing the file size did not introduce an obvious loop artifact.

When a Short Hero Video Jumps at the Loop Point

The Culprit: The hero video was revised so the restart point produced a much smoother visual transition. The important troubleshooting principle was to examine the footage itself at the loop boundary rather than immediately assuming the HTML video element was malfunctioning.

Re-Uploading a File With the Same Name Doesn’t Replace It

The Fix: Don't upload a fresh copy to replace an existing file. Instead, open the existing Media Library item and use Replace Media (built into recent WordPress core versions, or available via a plugin like Enable Media Replace if your version doesn't show it). That swaps the actual file contents while keeping the same filename and URL — no code changes needed anywhere else on the site.
After replacing, clear caches in the usual order (build/optimization plugin cache → page cache plugin → any server or CDN-level cache) and hard-refresh, since a stale cache can still serve the old bytes even after the file itself has correctly been swapped.