When a Share Card Lost Its Bottom Edge: Checking OG Images by Pixels, Not by Declaration, Before the Build

Check 1: read the dimensions of the real file

The first guard is simple. Walk every image under public/og and list any whose real size is not 1200×630.

#!/usr/bin/env python3
"""Check images under public/og by real size. Reads pixels, not declarations."""
import sys
from pathlib import Path
from PIL import Image
 
TARGET = (1200, 630)          # real size for share-card images
EXEMPT = {"stripe.png"}       # names of square files for other uses, if kept under og
 
 
def check(root: Path):
    bad, total = [], 0
    for p in sorted(root.rglob("*")):
        if p.suffix.lower() not in {".png", ".jpg", ".jpeg", ".webp"}:
            continue
        total += 1
        if p.name in EXEMPT:
            continue
        with Image.open(p) as im:      # reads only the header, so it is fast
            size = im.size
        if size != TARGET:
            bad.append((p, size))
    return total, bad
 
 
if __name__ == "__main__":
    root = Path(sys.argv[1] if len(sys.argv) > 1 else "public/og")
    if not root.is_dir():
        sys.exit(f"NG: {root} does not exist")          # never pass silently
    total, bad = check(root)
    if total == 0:
        sys.exit(f"NG: no images at all under {root}")
    for p, (w, h) in bad:
        print(f"NG {p}  {w}x{h}  (expected {TARGET[0]}x{TARGET[1]})")
    print(f"checked {total} / violations {len(bad)}")
    sys.exit(1 if bad else 0)

I made one 1200×1200 and one 1200×630 test image and ran it. The output was:

NG public/og/site-ja.png  1200x1200  (expected 1200x630)
checked 2 / violations 1

The exit code is 1, so placed in front of the build, it stops right here.

Two details deserve attention. First, a missing folder and zero images are both failures. If a path changes and the target becomes empty, that looks identical to "no violations". A check that examined nothing and still reports green is the scariest state a check can be in. Second, Image.open reads only the header, so even a site that writes one image per article finishes the scan in a moment.

Check 2: is there text in the band that will be lost?

The size check is the first line of defense. Separately, an image of an unexpected size sometimes turns out to be intentional. What I then want to know is whether the band lost to cropping carries text I want readers to see.

To work with gradient backgrounds, I look at the spread of brightness along each row. A row of pure background barely changes color as you move across it. A row with text alternates between the background and the letters, so the spread is large.

#!/usr/bin/env python3
"""Check whether the band lost to a wide center crop contains text-like variation."""
import sys
from PIL import Image
 
CARD_RATIO = 1.91        # rough wide-card ratio (width / height)
ROW_STD_THRESHOLD = 12   # std dev of one row's brightness; a plain gradient stays below it
 
 
def lost_rows(h: int, w: int, ratio: float = CARD_RATIO):
    keep = round(w / ratio)
    if keep >= h:
        return []
    top = (h - keep) // 2
    return list(range(0, top)) + list(range(top + keep, h))
 
 
def rows_with_content(im: Image.Image, rows):
    g = im.convert("L")
    w = g.width
    hit = []
    for y in rows:
        line = list(g.crop((0, y, w, y + 1)).tobytes())
        mean = sum(line) / w
        std = (sum((v - mean) ** 2 for v in line) / w) ** 0.5
        if std > ROW_STD_THRESHOLD:
            hit.append(y)
    return hit
 
 
if __name__ == "__main__":
    with Image.open(sys.argv[1]) as im:
        im.load()
    lost = lost_rows(im.height, im.width)
    hit = rows_with_content(im, lost)
    print(f"{im.width}x{im.height}: {len(lost)} rows lost by cropping / text-like rows among them {len(hit)}")
    if hit:
        print(f"  first y={hit[0]} last y={hit[-1]}")
        sys.exit(1)

Here are the results on the same test images, a 1200×1200 with a text band at the bottom and a 1200×630 with the same layout.

1200x1200: 572 rows lost by cropping / text-like rows among them 24
  first y=1099 last y=1124
1200x630: 2 rows lost by cropping / text-like rows among them 0

The square one reports text in the lost area, rows 1099 to 1124. The 24 is simply the height of the text I drew for the test; on a real image it depends on your design. What matters is less the count than the fact that you learn the text is on the lost side without opening the image.

The threshold of 12 was tuned on these test images. Re-tune it by hand for your own background. A finely patterned background will produce false positives; feeding in a few pattern-only images and finding the smallest value that stays quiet was the quickest way for me.

Check 3: match the meta tag declaration against the real file

As I said at the start, og:image:width and og:image:height in the HTML are declarations. If you rebuild the image and forget the meta tags, they disagree. And if only the image goes back, the meta tags stay "correct". That is why this incident was hard to notice.

#!/usr/bin/env python3
"""Compare the og:image declaration in HTML against the real dimensions of the file it points to."""
import sys
from html.parser import HTMLParser
from pathlib import Path
from urllib.parse import urlparse
from PIL import Image
 
 
class Meta(HTMLParser):
    def __init__(self):
        super().__init__()
        self.m = {}
 
    def handle_starttag(self, tag, attrs):
        if tag != "meta":
            return
        a = dict(attrs)
        key = a.get("property") or a.get("name")
        if key and "content" in a:
            self.m.setdefault(key, a["content"])
 
 
def check(html_path: Path, public_dir: Path):
    p = Meta()
    p.feed(html_path.read_text(encoding="utf-8"))
    m, errs = p.m, []
    if m.get("twitter:card") != "summary_large_image":
        errs.append(f"twitter:card={m.get('twitter:card')!r}")
    url = m.get("og:image")
    if not url:
        return errs + ["og:image is missing"]
    f = public_dir / urlparse(url).path.lstrip("/")
    if not f.is_file():
        return errs + [f"file not found: {f}"]
    with Image.open(f) as im:
        real = im.size
    decl = (int(m.get("og:image:width", 0)), int(m.get("og:image:height", 0)))
    if decl != real:
        errs.append(f"declared {decl} differs from real {real}")
    if real != (1200, 630):
        errs.append(f"real size {real} is not 1200x630")
    return errs
 
 
if __name__ == "__main__":
    html, public = Path(sys.argv[1]), Path(sys.argv[2])
    errs = check(html, public)
    for e in errs:
        print("NG", e)
    print("OK" if not errs else f"{len(errs)} violation(s)")
    sys.exit(1 if errs else 0)

I prepared an HTML file that still declared 1200×630 but pointed at the 1200×1200 image, and ran it:

NG declared (1200, 630) differs from real (1200, 1200)
NG real size (1200, 1200) is not 1200x630
2 violation(s)

Pointing the same HTML at the 1200×630 image prints OK with exit code 0. Run it against the folder where the built HTML lands and you can check every article's og:image in one pass.

Line the three up in front of the build

A check means nothing if it is not run. Put them in the prebuild of package.json, and let any failure stop the whole build.

{
  "scripts": {
    "check:og": "python3 scripts/og_size_check.py public/og && python3 scripts/og_lost_band.py public/og/site-ja.png && python3 scripts/og_lost_band.py public/og/site-en.png",
    "prebuild": "npm run check:og"
  }
}

Because of &&, a failure in the first stops the rest. The meta tag comparison (Check 3) needs the built HTML, so it goes after the build. I wrote about a build that stopped because of synced-folder artifacts in when conflicted copies pile up in a Dropbox-synced build output. The lesson there was the same: put the check where it can stop the thing that should stop.

One more hole to check on the same day

Even with a correct image, no card appears if the crawler cannot reach it. Around OG tags I have stepped on three different causes.

The third one is invisible in a browser, because if your browser is set to Japanese you are never redirected. Imitate the crawler by sending the language header.

# Imitate an English-language crawler and print only the response code of the top page
curl -s -o /dev/null -I -w "%{http_code}\n" -H "Accept-Language: en-US,en;q=0.9" https://example.com/

To test the idea, I ran a tiny local server that returns a 307 only when the English header is present. With the header it printed 307, without it 200, so the difference does show up. In production, a 200 means the path is clear; a 307 means it is not fixed yet.

When you hand an image swap to Claude Code

Sometimes I hand the image swap itself to Claude Code. One line in CLAUDE.md reduces misses at that point.

- After touching OG images, run npm run check:og before reporting completion, and paste the result lines as they are

To make sure that line is actually read, watch the length of your CLAUDE.md. I wrote about how a subfolder file can lose its back half in when only the back half of a subfolder CLAUDE.md is ignored.

The words "I checked" are easy to put in a report. Make it paste the output lines and you can see whether it ran at all. I have found out about a mismatch after trusting only a completion report, so I prefer reports that carry the output.

Pitfalls

• The target set becomes empty: renaming a folder can make the scan cover zero files. Treat zero as a failure.
• Trusting the threshold: the per-row spread depends on the background pattern. Find the smallest quiet value on your own images.
• Keeping squares under og: put the Stripe or LINE square elsewhere. If they must live together, list them by name in the exemptions.
• Checking only in a browser: language headers and crawler behavior don't reproduce in a browser.

One thing to do next

Count the real sizes under public/og once. python3 scripts/og_size_check.py public/og is all it takes. If there are no violations, that is today's reward. If there are, someone's shared card may be cut right now.

With the check in prebuild, even if the same image comes back, it will stop before anyone shares it.