DEV Community: Daniel Cheong

The concentric border-radius rule: why nested rounded corners look slightly wrong

Daniel Cheong — Sun, 26 Jul 2026 05:55:44 +0000

You round a card at 16px. You round the thumbnail inside it at 16px too, because that's the design token. Then you squint at it and something is off — the gap between the two curves looks fatter at the diagonal than it does along the straight edges, and the inner corner reads as slightly pinched.

Your eyes are right. Two rounded rectangles only look parallel when their radii differ by exactly the distance between them.

The rule

inner radius = outer radius − gap

Where gap is the distance from the outer box's border edge to the inner box's border edge: border-width + padding.

The reason is just where the arc centres land. Put the outer box's top-left corner at (0, 0) with radius R: its corner arc is a quarter circle centred at (R, R). Inset the child by p on both sides and give it radius r, and its arc is centred at (p + r, p + r).

Those two centres coincide only when p + r = R, i.e. r = R − p. Concentric arcs, constant p gap the whole way round the curve. Any other value and the gap swells or collapses at 45°.

In CSS

Derive it instead of hardcoding two numbers that will drift apart the first time someone changes the padding:

.card {
  --radius: 16px;
  --pad: 8px;

  padding: var(--pad);
  border-radius: var(--radius);
}

.card > img {
  border-radius: calc(var(--radius) - var(--pad)); /* 8px */
  display: block;
  width: 100%;
}

Clamp it, and mind the unit on the zero

When the padding exceeds the radius, calc() produces a negative length. Negative border-radius is invalid, so the whole declaration is thrown away and you inherit whatever was there before — usually not what you wanted, and silent. Clamp it:

border-radius: max(0px, calc(var(--radius) - var(--pad)));

Note it's 0px, not 0. Inside a CSS math function you can't compare a unitless number against a length; max(0, calc(...)) is invalid and gets dropped exactly like the negative value you were trying to avoid.

Borders count as gap

border-radius applies to the border box, and the browser already narrows the curve of a border's inner edge by the border width for you. But your child element sits border-width + padding in from the parent's border box, so both go into the subtraction:

.card {
  --radius: 16px;
  --border: 1px;
  --pad: 12px;

  border: var(--border) solid #d4d4d8;
  padding: var(--pad);
  border-radius: var(--radius);
}

.card > .inner {
  border-radius: max(0px, calc(var(--radius) - var(--border) - var(--pad)));
}

Forgetting the border width is why 1px-off corners survive review — at 1px it's subtle, at 3px on a chunky outlined card it's obvious.

Uneven padding needs an ellipse

Horizontal padding is often bigger than vertical. One radius value can't stay parallel on both axes when the gaps differ, so give the corner two: a horizontal radius and a vertical one. The shorthand takes them either side of a slash.

.card {
  --radius: 20px;
  --pad-x: 12px;
  --pad-y: 6px;

  padding: var(--pad-y) var(--pad-x);
  border-radius: var(--radius);
}

.card > .inner {
  /* horizontal / vertical */
  border-radius:
    max(0px, calc(var(--radius) - var(--pad-x)))
    /
    max(0px, calc(var(--radius) - var(--pad-y)));
}

Strictly, the true parallel curve of a circle is another circle, not an ellipse — but this keeps both arc centres on the same point, and that's what reads as correct. It's how most design systems handle it.

The one that quietly breaks the math

The spec has an overlap rule: if the two radii on any one side add up to more than that side's length, the browser computes a scale factor f = min(side length ÷ sum of that side's two radii) across all four sides, and if f < 1 it multiplies every corner radius by f.

So border-radius: 40px on a chip that's 60px tall doesn't render at 40px. Each vertical side needs 40 + 40 = 80px of radius in a 60px space, so f = 0.75 and every corner comes out at 30px.

Your inner element never hears about this. It's still computing calc(40px - 12px) = 28px from the specified value, while the parent is actually drawing 30px. The gap is now wrong on every corner, and the DevTools computed style shows 40px, because the scaling happens at used-value time.

Two ways out:

Keep every radius at or below half the shortest dimension of the box, so f is always 1 and your arithmetic holds.
If you actually want a pill, don't derive anything — set a large radius on both boxes and let the rule do its job:

.pill        { border-radius: 999px; }
.pill > .dot { border-radius: 999px; }

Both get clamped to their own half-height, which is exactly the concentric result you'd have calculated by hand.

Checklist

inner = outer − (border-width + padding), derived with calc(), never two hardcoded tokens
Clamp with max(0px, …) — unit on the zero, or the declaration is invalid
Different horizontal and vertical gaps → use the horizontal / vertical slash form
Keep radii ≤ half the shortest side, otherwise the browser rescales all four and your derived value silently drifts
Pills are the exception: set both to a big number instead of subtracting

Once the arc centres line up, nested cards stop looking subtly cheap and you stop nudging values by 1px hoping it'll click.

I keep a small free border radius generator around for when I want to eyeball per-corner and elliptical values before committing them to tokens.

Your Product schema is invalid and you don't know it — the price string gotcha

Daniel Cheong — Fri, 24 Jul 2026 04:32:43 +0000

If you've added Product structured data, watched it pass a JSON linter, and still got "Invalid" in Search Console (or no price shown in rich results), you've almost certainly hit the one that catches everyone: the price field.

Valid JSON is not valid schema.org. Here's the trap and the fix.

The markup that looks right but isn't

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Aeron Chair",
  "offers": {
    "@type": "Offer",
    "price": "$1,299.00",
    "priceCurrency": "USD"
  }
}
</script>

That's perfectly valid JSON. It also fails Google's Product validation, because price has rules that JSON itself knows nothing about:

No currency symbol. $ belongs in priceCurrency, not in the number.
No thousands separator. The , makes it unparseable as a number.
Dot is the only decimal mark. 1.299,00 (common in the EU) is rejected.

So "$1,299.00" is three violations in one string. Google either drops the offer or flags the whole item invalid.

The fix

"offers": {
  "@type": "Offer",
  "price": "1299.00",
  "priceCurrency": "USD"
}

price is the bare number as a string; the symbol lives entirely in priceCurrency as an ISO 4217 code (USD, EUR, SGD, …). Schema.org's own note is explicit about this — it even warns against Unicode symbols like U+00A0.

If your price comes out of a formatter, strip it before it goes into JSON-LD, don't reuse the display string:

// display value: "$1,299.00" — do NOT ship this to JSON-LD
const display = new Intl.NumberFormat("en-US", {
  style: "currency", currency: "USD",
}).format(1299);

// what the schema actually needs:
const priceForSchema = (1299).toFixed(2); // "1299.00"

The three neighbours that break with it

Once the price parses, these are the next ones Search Console complains about:

1. priceCurrency is required inside every Offer. A price with no currency is meaningless, and Google treats it as an error, not a warning.

2. availability must be a schema.org URL, not a word.

// wrong
"availability": "in stock"
// right
"availability": "https://schema.org/InStock"

The enum values are InStock, OutOfStock, PreOrder, BackOrder, and a handful more — always the full URL.

3. priceValidUntil wants ISO 8601. Not "31 Dec 2026", but "2026-12-31". Omit it and Google will nudge you to add it for fixed-price offers.

Why the JSON linter can't catch any of this

A JSON linter checks syntax — brackets, commas, quotes. Schema.org rules are semantic — "this string must be a bare decimal", "that string must be one of these URLs". They live in the vocabulary, not the grammar, so a green checkmark in your editor tells you nothing about whether Google will accept the markup.

That's the gap you have to close with an actual structured-data validator that understands the schema.org types, not just JSON. I keep a small free schema markup validator around for exactly this — paste the JSON-LD, and it flags the price/currency/enum problems that a plain linter waves through.

The short version

price = bare number as a string: "1299.00". No symbol, no thousands separator, . for decimals only.
Currency goes in priceCurrency as an ISO 4217 code.
availability is a full schema.org/... URL, and dates are ISO 8601.
Valid JSON ≠ valid schema. Validate against the vocabulary, not just the syntax.

Your JWT expiry check is off by 1000x — the NumericDate gotcha

Daniel Cheong — Mon, 13 Jul 2026 04:33:21 +0000

You decode a JWT on the client to grab the expiry, write what looks like an obvious check, and suddenly every user is either logged out instantly or never logged out at all. The token is fine. Your comparison is off by a factor of 1000. Here's why, and how to get it right.

Peeking inside a JWT

A JWT is three Base64URL segments joined by dots: header.payload.signature. The middle segment is the claims. To read them in the browser you split on the dots and decode the payload:

function decodePayload(token) {
  const payload = token.split(".")[1];
  // Base64URL → Base64, then decode + parse
  const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
  return JSON.parse(json);
}

decodePayload(token);
// { sub: "1234", name: "Ada", iat: 1710000000, exp: 1710003600 }

So far so good. Then you try to check whether it's expired.

The bug

const { exp } = decodePayload(token);

if (Date.now() > exp) {
  logout(); // 💥 fires immediately, for every token
}

Date.now() returns milliseconds since the Unix epoch — right now that's a 13-digit number like 1710000000000. But exp in a JWT is a NumericDate: seconds since the epoch (RFC 7519), a 10-digit number like 1710003600.

So you're comparing 1710000000000 > 1710003600, which is always true. Every token reads as expired, and your users get bounced the moment they log in.

Flip the comparison the wrong way to "fix" it and you get the opposite failure: exp > Date.now() is always true, so tokens never expire on the client and stale sessions linger.

The fix: put both sides in the same unit

Multiply the JWT's seconds up to milliseconds, or divide Date.now() down to seconds. Pick one and be consistent:

const { exp } = decodePayload(token);

// Option A — compare in milliseconds
const isExpired = Date.now() >= exp * 1000;

// Option B — compare in seconds
const nowSec = Math.floor(Date.now() / 1000);
const isExpiredB = nowSec >= exp;

The same trap applies to iat (issued-at) and nbf (not-before) — both are NumericDate seconds. If you want a real Date object for display, remember the multiply:

new Date(exp * 1000).toISOString(); // "2024-03-09T17:00:00.000Z"
new Date(exp);                      // 🐞 1970 — forgot the *1000

A small clock-skew allowance is also worth adding so a token that expires in the next second or two isn't treated as still-valid:

const SKEW_SEC = 30;
const isExpired = Math.floor(Date.now() / 1000) >= exp - SKEW_SEC;

The bigger gotcha: decoding is not verifying

This part matters more than the timestamp. atob + JSON.parse only reads the payload — it does nothing to check that the token is genuine. Anyone can craft a JWT with exp set to next year and admin: true, because the signature (the third segment) is what proves authenticity, and you didn't check it.

That's fine for what client-side decoding is for: reading a username to show in the navbar, or checking exp to decide when to silently refresh. It is never okay as an authorization decision. The server must verify the signature against its secret/public key on every protected request — and reject alg: none tokens outright.

// OK on the client: a UI hint
navbar.textContent = decodePayload(token).name;

// NOT OK on the client: an auth gate
if (decodePayload(token).role === "admin") showAdminPanel(); // trivially forged

Three things to remember

JWT exp, iat, and nbf are seconds (NumericDate); Date.now() is milliseconds. Multiply by 1000 or divide by 1000, but never mix them.
Add a few seconds of clock-skew tolerance so borderline-expired tokens are handled sanely.
Decoding a JWT reads it; it does not trust it. Signature verification belongs on the server.

I kept re-eyeballing 13-digit timestamps to sanity-check this, so I keep a small free JWT decoder around that lays out the header, claims, and a human-readable exp for me.

Why lightening a hex color in RGB gives you grey (and the HSL fix)

Daniel Cheong — Thu, 09 Jul 2026 04:33:49 +0000

Your brand color has one hex value. A design system needs about nine: a light tint for hover backgrounds, a dark shade for pressed states, something in between for borders. The obvious way to generate them is to nudge the RGB channels up and down. It looks fine until you put the swatches side by side and notice the light end has gone grey and the dark end has gone muddy.

Here's why that happens, and how to build a scale that actually stays on-hue.

Why lightening in RGB goes grey

Take a saturated blue and lighten it the naive way — push every channel toward 255:

const lighten = (r, g, b, amount) => [
  Math.round(r + (255 - r) * amount),
  Math.round(g + (255 - g) * amount),
  Math.round(b + (255 - b) * amount),
];

lighten(37, 99, 235, 0.6); // #2563eb at 60% → [168, 192, 243]

That result, #a8c0f3, isn't a lighter version of the same blue. As all three channels race toward 255 they converge, and the gap between them — which is what carries the hue — shrinks. The color desaturates on its way up. Do the same trick downward toward 0 and the channels collapse together again, so your dark shades drift toward a dead near-black instead of a rich navy.

RGB is a hardware model. It describes how much light each phosphor emits, not anything a human would call "the same color but lighter." Lightness and hue are tangled together in it, so you can't move one without disturbing the other.

Move the work into HSL

HSL splits a color into Hue, Saturation, and Lightness. If you convert your brand color once, you can slide L up and down while H and S stay put — which is exactly the "same color, different brightness" operation you actually wanted.

function hexToHsl(hex) {
  let [r, g, b] = hex.match(/\w\w/g).map((x) => parseInt(x, 16) / 255);
  const max = Math.max(r, g, b), min = Math.min(r, g, b);
  const l = (max + min) / 2;
  let h = 0, s = 0;
  if (max !== min) {
    const d = max - min;
    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
    if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
    else if (max === g) h = ((b - r) / d + 2) / 6;
    else h = ((r - g) / d + 4) / 6;
  }
  return [h * 360, s * 100, l * 100];
}

Now a full scale is just a list of target lightness values with the original hue and saturation held constant:

function scale(hex) {
  const [h, s] = hexToHsl(hex);
  const stops = [95, 88, 78, 66, 54, 44, 36, 28, 18]; // 50 → 900
  return stops.map((l) => `hsl(${h.toFixed(0)} ${s.toFixed(0)}% ${l}%)`);
}

scale("#2563eb");
// hsl(217 83% 95%)  ← barely-tinted background
// hsl(217 83% 66%)  ← hover
// hsl(217 83% 54%)  ← your base, roughly
// hsl(217 83% 18%)  ← pressed / text-on-light

Every stop reads as the same blue. The light end is a pale sky, not grey; the dark end is a deep navy, not sludge. And because modern CSS accepts hsl() directly, you can often skip converting back to hex entirely.

One catch: equal L steps don't look equal

HSL fixes the hue drift, but it has its own quirk — human eyes aren't linear about lightness. A jump from L 90% to L 80% looks like a small change; the same 10-point jump from 30% to 20% looks much larger, because we perceive dark differences more strongly. That's why the stops array above isn't evenly spaced: the steps are tighter at the top and wider at the bottom to look even.

If you want the perceptual spacing handled for you, that's the whole point of OKLCH, a newer color space built so that equal numeric steps look like equal visual steps:

:root {
  --blue-100: oklch(0.95 0.03 255);
  --blue-500: oklch(0.62 0.19 255); /* base */
  --blue-900: oklch(0.30 0.11 255);
}

Here you can walk lightness in even increments and trust the result. OKLCH is supported in every current browser, so for a fresh design system it's often the better starting point than HSL.

The takeaways

Lightening or darkening in RGB desaturates — channels converge on 255 or 0 and the hue washes out.
Convert to HSL and vary only L to keep tints and shades on the same hue.
Perceived lightness isn't linear, so hand-tune your HSL stops or move to OKLCH, which spaces them for you.

I got tired of hand-tuning stop values, so I keep a small free color palette generator that spits out the full tint/shade scale from one hex and lets me copy it straight as CSS variables.

atob() can't decode a JWT — the Base64URL gotcha (and the fix)

Daniel Cheong — Sat, 04 Jul 2026 04:33:33 +0000

Ever pasted a Base64 string into atob() and gotten this?

Uncaught DOMException: Failed to execute 'atob' on 'Window':
The string to be decoded is not correctly encoded.

…yet the string looks like perfectly valid Base64. Nine times out of ten the culprit is that it isn't standard Base64 at all — it's Base64URL, and the two are not interchangeable. Here's the difference and how to decode either one safely.

Two alphabets, one name

Standard Base64 (RFC 4648 §4) uses these 64 characters:

A-Z  a-z  0-9  +  /

and pads the end with = so the length is always a multiple of 4.

The problem: +, /, and = all have special meaning in URLs and filenames. + becomes a space when form-decoded, / is a path separator, = is a query-string delimiter. So RFC 4648 §5 defines a URL-safe variant, Base64URL:

+  →  -
/  →  _
=  →  (dropped entirely)

This is what you find inside JWTs, in OAuth state params, in signed URLs, and in a lot of API tokens. It looks like Base64, so people feed it to atob() — which only understands the standard alphabet — and it breaks.

// A JWT payload segment (Base64URL)
const seg = "eyJ1c2VyIjoiZGFuIiwicm9sZSI6ImFkbWluIn0";

atob(seg);
// 💥 DOMException on the missing padding / '-' / '_'

The fix: normalize before you decode

Convert Base64URL back to standard Base64 first — swap the alphabet and restore the padding:

function fromBase64Url(input) {
  // 1. restore the standard alphabet
  let b64 = input.replace(/-/g, "+").replace(/_/g, "/");
  // 2. re-pad to a multiple of 4
  const pad = b64.length % 4;
  if (pad) b64 += "=".repeat(4 - pad);
  return atob(b64);
}

fromBase64Url("eyJ1c2VyIjoiZGFuIiwicm9sZSI6ImFkbWluIn0");
// '{"user":"dan","role":"admin"}' ✅

The padding math is the part people forget. Base64 encodes 3 bytes into 4 characters, so a valid string length is always 0 mod 4. Base64URL strips the =, leaving lengths of 2 mod 4 or 3 mod 4. atob() wants them back. (A remainder of 1 is never valid Base64 — if you see that, the string is genuinely corrupt.)

Encoding to Base64URL

Going the other way, encode as normal, then strip and swap:

function toBase64Url(bytes) {
  let bin = "";
  bytes.forEach((b) => (bin += String.fromCharCode(b)));
  return btoa(bin)
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");   // drop trailing padding
}

toBase64Url(new TextEncoder().encode('{"user":"dan"}'));
// "eyJ1c2VyIjoiZGFuIn0"

Notice the TextEncoder step — if your input might contain non-ASCII text, you need to go through UTF-8 first or btoa will throw on anything above code point 255. That's a separate sharp edge worth knowing about, but the alphabet swap above is what makes it URL-safe.

Node.js gets this for free

If you're on the server, the Buffer API has a native base64url encoding — no manual padding required:

Buffer.from("eyJ1c2VyIjoiZGFuIn0", "base64url").toString(); // decode
Buffer.from('{"user":"dan"}').toString("base64url");        // encode

Worth remembering that this only exists in Node (14.18+), not in the browser — hence the manual helper above for front-end code.

Three things to remember

atob/btoa only speak standard Base64. JWTs, OAuth params and signed URLs are usually Base64*URL* — normalize -→+, _→/, and re-pad before decoding.
The padding is length-dependent: re-add = until the length is a multiple of 4. A remainder of 1 means the data is actually broken.
Base64 (either flavour) is encoding, not encryption. A JWT payload is trivially readable — never put secrets in one and assume they're hidden.

I kept mixing up the two alphabets when eyeballing tokens, so I keep a small free Base64 encoder/decoder around that auto-detects the URL-safe variant and handles the padding for me.

Your contrast checker probably lies about rgba() text

Daniel Cheong — Wed, 24 Jun 2026 04:34:03 +0000

Your contrast checker probably lies about rgba() text. Most checkers — and most hand-rolled WCAG snippets — assume both colours are fully opaque. The moment your text or its background uses rgba() or opacity, the numbers can be off by a full pass/fail. Here's why, and the one extra step that fixes it.

The WCAG math, quickly

The contrast ratio between two colours is:

(L1 + 0.05) / (L2 + 0.05)

where L1 is the relative luminance of the lighter colour and L2 the darker. Relative luminance needs sRGB gamma correction first — you can't just average the RGB channels:

function luminance([r, g, b]) {
  const a = [r, g, b].map((v) => {
    v /= 255;
    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * a[0] + 0.7152 * a[1] + 0.0722 * a[2];
}

function ratio(fg, bg) {
  const [l1, l2] = [luminance(fg), luminance(bg)];
  const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
  return (hi + 0.05) / (lo + 0.05);
}

Sanity check: black on white is 21:1, white on white is 1:1. If those two anchors are right, the core is right. AA wants 4.5:1 for normal text and 3:1 for large text (≥ 18pt, or 14pt bold).

So far so standard. Here's the part that bites.

The bug: luminance has no concept of alpha

luminance() takes three numbers. There is no fourth slot for alpha — and there can't be, because a translucent colour has no luminance of its own. What you actually see is the translucent colour blended over whatever is behind it.

Consider muted helper text that a designer wrote as:

color: rgba(0, 0, 0, 0.55);   /* "black at 55%" */
background: #ffffff;

Run the naive check and you'll feed it [0,0,0] vs [255,255,255] and get a triumphant 21:1. But the pixels on screen are not black. They're black composited over white at 55% opacity, which is a medium grey — and its real ratio is closer to 3.7:1. That fails AA for body text. The checker said you passed by 4x. You shipped unreadable text.

The fix: composite first, then measure

Before computing luminance, flatten any translucent colour onto its actual backdrop using the standard "source-over" formula, per channel:

out = fg * alpha + bg * (1 - alpha)

// Flatten a translucent fg over an opaque bg.
function composite([fr, fg_, fb, fa], [br, bg_, bb]) {
  return [
    Math.round(fr * fa + br * (1 - fa)),
    Math.round(fg_ * fa + bg_ * (1 - fa)),
    Math.round(fb * fa + bb * (1 - fa)),
  ];
}

function ratioWithAlpha(fgRgba, bgRgb) {
  const flat = composite(fgRgba, bgRgb);   // real on-screen colour
  return ratio(flat, bgRgb);
}

ratioWithAlpha([0, 0, 0, 0.55], [255, 255, 255]); // ~3.7  ✅ now honest

Now the result matches what a human eye (and an auditor's tooling) actually sees.

Three things that trip people up

1. opacity is not rgba(), and it's worse. opacity: 0.55 on an element fades the text and lets the background show through, but it also composites over every ancestor layer, not just the immediate parent. If there's a background image or a gradient behind the element, there is no single backdrop colour to composite against — the contrast genuinely varies pixel by pixel. The honest move is to avoid opacity for text colour entirely and use a solid colour you can actually measure.

2. A translucent background needs the same treatment. A card with background: rgba(255,255,255,0.8) over a photo isn't white — flatten it over the dominant backdrop colour before checking the text on it.

3. Stacked alphas compound. Translucent text on a translucent panel on a page background means two composites, innermost backdrop first. Resolve from the bottom layer up.

Takeaways

The WCAG luminance formula has no alpha input by design — translucent colours must be flattened first.
Always composite (fg*a + bg*(1-a)) against the real backdrop before computing the ratio, or your checker reports a colour that never reaches the screen.
Prefer solid rgb/hex for text. If you must fade it, pre-compute the flattened colour so design, code, and audit all agree on one value.

I kept re-deriving the compositing step every time a design used faded text, so I keep a small free color contrast checker around that takes alpha into account. Get the two anchor values (21:1 and 1:1) right, remember to flatten, and contrast stops being guesswork.

How we cut INP from 480ms to under 200ms on a legacy site (no rewrite)

Daniel Cheong — Sun, 07 Jun 2026 07:25:32 +0000

Most "make it faster" advice assumes you can rebuild. On real small-business sites — a clinic on WordPress, a retailer on a 2018 theme — you usually can't. Here's how we cut Interaction to Next Paint (INP) on a legacy site from ~480ms to under 200ms without a rewrite.

1. Find the slow interactions, don't guess

INP measures the worst interaction, not the average. Pull real-user data first:

import { onINP } from 'web-vitals';
onINP((metric) => {
  // ship to your analytics endpoint
  navigator.sendBeacon('/vitals', JSON.stringify({
    value: metric.value,
    target: metric.attribution?.interactionTarget,
  }));
});

The interactionTarget tells you which element is slow — usually a menu toggle, a filter, or an "add to cart".

2. Break up long tasks

The usual culprit is a single handler doing too much synchronously. Yield to the main thread:

async function handleClick() {
  updateUIImmediately();           // cheap, visible feedback first
  await scheduler.yield?.() ?? new Promise(r => setTimeout(r));
  doExpensiveWork();               // the rest, after paint
}

3. Defer third-party scripts

Chat widgets, pixels and analytics are the silent INP killers. Load them after first interaction or on idle:

<script>
  addEventListener('load', () => requestIdleCallback(() => {
    const s = document.createElement('script');
    s.src = 'https://widget.example.com/chat.js';
    document.body.append(s);
  }));
</script>

4. Measure again

After these three changes, the legacy site moved from a failing INP to passing — no framework migration, no redesign.

If you want this run against your own legacy site, we do exactly this for Singapore SMEs at SGBP — performance and AI work on the site you already have. Happy to take a look — drop us a line.

— Daniel

I shipped 14 AI features to production in 2025. Here's the checklist nobody talks about.

Daniel Cheong — Tue, 26 May 2026 02:00:31 +0000

I run engineering at a small Singapore agency. Over 2025 we shipped 14 AI features into production websites — RAG chatbots, AI search, summary generators, document Q&A, agentic form fillers. None of them were "throw GPT-4 at it" demos. All had real users, real bills, real complaints.

This post is the checklist we use now, distilled from things that went wrong in the first 8 features. It's deliberately not aspirational. It's the boring operational layer most LLM tutorials skip.

If you're about to ship an AI feature past prototype, read this first.

The 7 failure modes that bit us, in order of pain

1. The "happy path demo" trap

The first 4 features all looked great on day one of QA. Three of them broke production within two weeks because the demo path is ~5% of real user traffic.

Real users:

Paste 8 KB of nested HTML when asked for a name
Ask "where is the chicken curry" to a real-estate chatbot
Trigger 14 concurrent requests by holding down the send button
Run the chatbot in an iframe inside an Outlook email preview pane

Fix: Before launch, run a "weirdness simulation" — script 200 inputs scraped from your existing customer-support transcripts, plus 50 deliberately broken inputs (emoji floods, SQL-injection-shaped strings, opposite-language Unicode). Don't ship until your tracing dashboard shows graceful handling for ≥95% of them.

2. Cost runaways from one bad page

Feature #5 (a "summarise this page" button on a documentation site) burned through three months of our LLM budget in 11 days. Why: one page that nobody had read in months had a 200,000-token rendered HTML output because of an infinite-recursion bug in their CMS.

Fix: Token budgets per request, enforced server-side. Always. Plus rate-limiting by IP+session, not just by API key. Plus a daily $-cap circuit breaker that pages you (literally) at 80% of budget.

// One example — Cloudflare Worker enforcing per-request input cap
const MAX_INPUT_TOKENS = 8000;
const inputTokens = await tokenizer.encode(userInput).length;
if (inputTokens > MAX_INPUT_TOKENS) {
  return new Response("Input too long. Please trim and retry.", { status: 413 });
}

3. "It works on Gemini Flash 2.5" doesn't mean it works on Gemini Flash 2.5

Two features that ran perfectly in our staging Gemini Flash 2.5 deployment started returning truncated answers in prod. Reason: regional capacity changes, Google was silently routing some prod requests to the older Flash 2.0 endpoint, which has tighter output limits.

Fix: Pin model versions explicitly (gemini-2.5-flash-001, not gemini-2.5-flash). Log the model that actually served each request from the response metadata. Alert if it deviates.

4. RAG retrieval drift after content updates

Feature #7 was a customer-service chatbot for a clinic. They updated their service-hours page in October. We didn't re-embed for 11 days. Customers kept being told outdated hours by the bot. Three angry phone calls before we figured it out.

Fix: Tie retrieval-index updates to your CMS publish webhook, not a cron. The CMS knows when content changes; cron only knows the time. We use a Cloudflare Workers webhook receiver that triggers re-embedding within ~30 seconds of a CMS publish.

5. The hallucination tax on "trustworthy" outputs

For feature #8 (a property-listing assistant), we used careful system prompts and grounding. The bot still confidently invented a 3-bedroom unit at a $X price that didn't exist. The agency that licensed it got a real customer enquiry for that imaginary unit.

Fix: Always show the source with the answer. If you can't cite, don't answer. Concretely: every chatbot response includes a sources: [] array linking to the retrieved chunks. The frontend renders them inline as [1] [2] markers. Users self-police when they can see sources are weak.

6. The "but what if they ask about competitors" question

Feature #9 was a chatbot for a regional bank. Marketing asked midway through QA: "What if a user asks 'is OCBC better than DBS?'" Nobody had thought about this. The bot, helpfully, answered with hallucinated comparative facts.

Fix: Topic-routing guards. Before the LLM call, classify the user query against a fixed list of allowed topics for that deployment. Off-topic queries get a polite deflection ("I can only help with X, Y, Z — try our search bar for general questions.") This is a 50ms classifier call. The savings on PR risk are huge.

7. Streaming UI looks fast but feels broken

We launched feature #11 with streamed token output. Beautiful in our office. In production, users on flaky mobile connections (60% of our traffic) saw text appear, pause for 3 seconds, then keep going. They thought it had crashed and refreshed. Refresh = start over = bad UX.

Fix: Streaming UX needs:

A "thinking" indicator that's separate from the streamed text (so users see something happens during gaps)
Heartbeat events every 500ms so the connection doesn't appear dead
A non-streaming fallback if the client supports it (mobile gets fallback by default in our setup)

The production checklist (the part most people scroll for)

Before any AI feature touches real users, we now run through this. It's saved us 3 weeks of post-launch firefighting per feature on average.

Inputs

[ ] Per-request input token cap, enforced server-side, returns 413 not 500
[ ] Per-user rate limit (cookie+IP), separate from per-API-key
[ ] "Weirdness simulation" run of 250 inputs passed before launch
[ ] Input is sanitized of HTML/script before logging (you WILL log inputs — don't log XSS)
[ ] Multi-language behaviour tested if your audience isn't 100% English

Costs

[ ] Daily $-budget circuit breaker that pages on-call at 80%
[ ] Per-tenant budget if multi-tenant (one customer can't burn the others' allocation)
[ ] Logged cost per request, with attribution tag (feature, userId, tenant)
[ ] Free-tier downgrade path: if budget exceeded, system serves cached/template responses instead of failing

Models

[ ] Pin model version explicitly (-001 suffix, not the moving alias)
[ ] Log the model that served each request (from response metadata)
[ ] Alert on model-version drift in production
[ ] Tested with the worst model in your fallback chain (some traffic will route there)
[ ] Temperature locked at the lowest value that doesn't break the use case (we default to 0.2)

Grounding & truthfulness

[ ] Every answer cites its sources, in the response payload
[ ] Frontend renders sources visibly with the answer
[ ] Retrieval index re-builds on CMS publish webhook, NOT on a daily cron
[ ] "I don't know" path tested — does the bot actually defer when context is weak?
[ ] Topic-routing guard before LLM call (fixed allowlist per deployment)

[ ] Streaming has separate "thinking" indicator from streamed content
[ ] Heartbeat events keep the connection alive for slow networks
[ ] Non-streaming fallback for clients/networks that need it
[ ] Loading states for the first 200ms (don't show empty boxes)
[ ] Error states clearly say "try again" with what went wrong, not "something happened"

Compliance & ethics

[ ] User data sent to LLM provider is logged in your privacy policy
[ ] DPA in place with the LLM provider for PII regions (Singapore PDPA, EU GDPR, etc.)
[ ] No PII in retraining or vendor analytics pipelines (check the small print)
[ ] User-facing disclaimer that this is AI-generated where it matters (medical, legal, financial)

Monitoring

[ ] Every request logged with: timestamp, tenant, latency, tokens-in, tokens-out, $, model, source IPs
[ ] Hallucination canaries — synthetic queries with known correct answers, run hourly, alert on drift
[ ] User feedback widget on every response ("Was this helpful? Y/N + free text")
[ ] Weekly review of low-rated responses → manual triage → prompt updates

What didn't make this list

A few things I expected to matter but didn't, in practice:

Model fine-tuning — every time we considered it, prompt iteration + better RAG got us there faster. Save fine-tuning for genuinely specialized domains.
GPU local inference — interesting at scale, but for our SMB clients the API cost is rarely the actual bottleneck. Engineering complexity is.
Embeddings choice — we tried 5 embedding models. text-embedding-004 and text-embedding-3-small were both fine. Pick one and move on.
Chunking strategy debates — 300-600 char chunks with sentence boundaries, overlap of 50 chars. Stop reading chunking blog posts. Ship.

The bigger pattern

AI features are now ~20% of new builds we ship at SGBP — Singapore Build Partners. The pattern that's emerged: the LLM part is the easiest 30% of the work. The other 70% is the boring operational scaffolding above. That's where the actual product-readiness lives.

If you're an in-house dev or agency about to ship your first production AI feature, save this checklist. The version I keep in our internal wiki has another ~40 items, but the ones above cover 80% of the pain.

If your team is staring at a "we should add AI to this" mandate from leadership and isn't sure where to start, we do this for clinics, retailers, and SaaS teams across Singapore — happy to talk through your specific stack.

Otherwise — ship slowly, log everything, and never trust the happy path.

Daniel Cheong is a Senior Frontend Engineer at SGBP. He writes about web performance, AI in production, and the boring infrastructure that makes web products actually work.

How to add a Gemini-powered chatbot to any legacy site in ~2 hours (with code)

Daniel Cheong — Sun, 24 May 2026 13:43:20 +0000

A clinic in Singapore came to us last month with a familiar problem: a 7-year-old WordPress site, no budget for a full rebuild, but their front desk was drowning in repeat phone questions. "Are you open on weekends?" "Do you do paediatric vaccinations?" "How do I book an MRI?"

They wanted an AI chatbot that knew their actual content — opening hours, services, doctor profiles — and could answer in English or Malay without making things up. Total spend cap: under S$20/month at their traffic.

I shipped it in one afternoon. This post is the actual walk-through, with code you can lift directly. No rewrites, no React migration, no Webflow. Just plain JavaScript + Gemini.

If you're staring at a legacy CMS and wondering how to add an AI helper without burning weeks, read on.

What we built (the 30-second version)

A floating chat widget that:

Loads as a single <script> tag at the bottom of the site (no plugin install, no template edit).
Pulls answers from a small RAG (Retrieval-Augmented Generation) index built from the clinic's own pages.
Hands off to a human (WhatsApp link) when confidence is low or the topic is medical.
Costs ~S$3-5/month at their traffic (a few hundred sessions/week).

Stack:

Gemini 2.5 Flash for the LLM (free tier covers most of their traffic; Flash is plenty smart for "what are your hours")
Cloudflare Workers as the proxy + RAG retriever (zero cold start, $0 at this scale)
Cloudflare Vectorize as the embedding store (free up to 5M dimensions; we used ~15K)
Vanilla JS + a tiny shadow-DOM widget for the UI

No framework dependency on the client side. Works on WordPress, Webflow, Shopify, a static HTML site from 2014 — anywhere you can drop a script tag.

Step 1 — Crawl your own site and chunk it

You can't RAG against pages you haven't indexed. The first job is pulling the site's content into clean chunks.

// scripts/crawl.mjs — run once locally
import { JSDOM } from "jsdom";

const SEED = "https://clinic.example.com";
const visited = new Set();
const chunks = [];

async function crawl(url) {
  if (visited.has(url) || visited.size > 200) return;
  visited.add(url);
  const html = await fetch(url).then(r => r.text());
  const dom = new JSDOM(html);
  const doc = dom.window.document;

  // Strip nav/footer/scripts — keep the body content only
  doc.querySelectorAll("nav, footer, script, style, .menu, .sidebar").forEach(el => el.remove());
  const text = doc.body.textContent.replace(/\s+/g, " ").trim();

  // Chunk by ~400 chars on sentence boundaries
  const sentences = text.match(/[^.!?]+[.!?]+/g) || [text];
  let buf = "";
  for (const s of sentences) {
    if ((buf + s).length > 400) {
      if (buf) chunks.push({ url, text: buf.trim() });
      buf = s;
    } else {
      buf += " " + s;
    }
  }
  if (buf) chunks.push({ url, text: buf.trim() });

  // Follow internal links
  const links = [...doc.querySelectorAll("a[href]")]
    .map(a => new URL(a.getAttribute("href"), url).toString())
    .filter(u => u.startsWith(SEED));
  for (const l of links) await crawl(l);
}

await crawl(SEED);
console.log(`Crawled ${visited.size} pages, ${chunks.length} chunks`);
await Deno.writeTextFile("chunks.json", JSON.stringify(chunks, null, 2));

For our clinic, this produced 143 chunks from 38 pages in under 90 seconds. The total token count after chunking was ~9,000 — well within free-tier embedding budgets.

Step 2 — Embed the chunks with Gemini

Gemini's text-embedding-004 model is free at modest volumes and gives 768-dim vectors that work fine for short docs.

// scripts/embed.mjs
import chunks from "./chunks.json" assert { type: "json" };

const KEY = process.env.GEMINI_API_KEY;
const out = [];
for (const c of chunks) {
  const r = await fetch(
    `https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=${KEY}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        model: "models/text-embedding-004",
        content: { parts: [{ text: c.text }] },
      }),
    }
  ).then(r => r.json());
  out.push({ ...c, embedding: r.embedding.values });
}
await Deno.writeTextFile("embedded.json", JSON.stringify(out));

143 embedding calls, free tier, ~40 seconds. Push the resulting vectors to Cloudflare Vectorize:

npx wrangler vectorize create clinic-rag --dimensions=768 --metric=cosine
node scripts/upsert-vectors.mjs   # iterates embedded.json → vectorize upsert

That's the entire offline build. Re-run the crawl + embed monthly (or via a CI cron) and you're never stale.

Step 3 — The Worker (the actual brain)

This is the only piece that runs in production. ~80 lines.

// worker.js — deployed via Wrangler
export default {
  async fetch(req, env) {
    const { question, history = [] } = await req.json();

    // 1. Embed the user question
    const qEmb = await embed(question, env.GEMINI_KEY);

    // 2. Retrieve top-5 chunks from Vectorize
    const hits = await env.VECTORIZE.query(qEmb, { topK: 5, returnMetadata: true });
    const context = hits.matches
      .map(m => `[Source: ${m.metadata.url}]\n${m.metadata.text}`)
      .join("\n\n");

    // 3. Decide whether to defer to a human
    if (hits.matches[0].score < 0.55 || /pain|emergency|chest|bleeding|dizzy/i.test(question)) {
      return json({
        answer: "I can't reliably answer that — please WhatsApp our front desk at +65 6815 4321 for the fastest response.",
        defer: true,
      });
    }

    // 4. Ask Gemini, grounded on the retrieved context
    const prompt = `You are a helpful assistant for ${env.CLINIC_NAME}. Answer ONLY from the context below. If unsure, say "Please call the clinic directly."

Context:
${context}

Conversation so far:
${history.map(h => `${h.role}: ${h.text}`).join("\n")}

User: ${question}
Assistant:`;

    const llm = await fetch(
      `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${env.GEMINI_KEY}`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          contents: [{ parts: [{ text: prompt }] }],
          generationConfig: { temperature: 0.2, maxOutputTokens: 400 },
        }),
      }
    ).then(r => r.json());

    return json({ answer: llm.candidates[0].content.parts[0].text, sources: hits.matches.map(m => m.metadata.url) });
  },
};

async function embed(text, key) {
  const r = await fetch(
    `https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=${key}`,
    { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ model: "models/text-embedding-004", content: { parts: [{ text }] } }) }
  ).then(r => r.json());
  return r.embedding.values;
}

const json = (data) => new Response(JSON.stringify(data), { headers: { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*" } });

Three production lessons that mattered:

The score < 0.55 defer threshold is gold. Tuned downward from 0.7 after the first 3 days — embeddings on short clinic content cluster low. Without this, the bot tried to answer "do you take Medisave for IVF" with hallucinations.
Hard-coded keyword defer for anything medical-symptomy. Legal cover. The bot will never try to diagnose, even when it could.
temperature: 0.2 keeps answers boring and factual. Anything higher and Gemini started inventing clinic hours that don't exist.

Step 4 — The 80-line frontend widget

This is the only thing the legacy site ever loads. Drop it in the footer, no other changes.

<script>
(() => {
  const WORKER = "https://clinic-bot.your-worker.workers.dev";
  const host = document.createElement("div");
  const root = host.attachShadow({ mode: "open" });
  root.innerHTML = `
    <style>
      :host { all: initial; }
      .fab { position: fixed; bottom: 24px; right: 24px; width: 56px; height: 56px; border-radius: 28px; background: #0EA5E9; color: white; display: grid; place-items: center; cursor: pointer; box-shadow: 0 4px 12px rgba(0,0,0,.15); font: 600 14px system-ui; z-index: 9999; }
      .panel { position: fixed; bottom: 96px; right: 24px; width: 360px; height: 480px; background: white; border-radius: 12px; box-shadow: 0 8px 24px rgba(0,0,0,.18); display: none; flex-direction: column; font: 14px/1.4 system-ui; }
      .panel.open { display: flex; }
      .msgs { flex: 1; overflow-y: auto; padding: 12px; }
      .msg { padding: 8px 12px; margin: 6px 0; border-radius: 12px; max-width: 80%; }
      .msg.user { background: #0EA5E9; color: white; margin-left: auto; }
      .msg.bot { background: #F1F5F9; color: #0F172A; }
      .input { display: flex; padding: 8px; border-top: 1px solid #E2E8F0; }
      .input input { flex: 1; padding: 8px; border: 1px solid #CBD5E1; border-radius: 6px; font: 14px system-ui; }
      .input button { margin-left: 6px; padding: 8px 14px; background: #0EA5E9; color: white; border: none; border-radius: 6px; cursor: pointer; }
    </style>
    <div class="fab" id="fab">Chat</div>
    <div class="panel" id="panel">
      <div class="msgs" id="msgs"><div class="msg bot">Hi! Ask about our hours, services, or how to book an appointment.</div></div>
      <form class="input" id="form"><input id="q" placeholder="Type a question…" required><button>Send</button></form>
    </div>
  `;
  document.body.appendChild(host);
  const $ = (s) => root.getElementById(s);
  const history = [];
  $("fab").onclick = () => $("panel").classList.toggle("open");
  $("form").onsubmit = async (e) => {
    e.preventDefault();
    const q = $("q").value.trim(); if (!q) return;
    $("q").value = "";
    $("msgs").insertAdjacentHTML("beforeend", `<div class="msg user">${escapeHtml(q)}</div>`);
    history.push({ role: "user", text: q });
    const r = await fetch(WORKER, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ question: q, history }) }).then(r => r.json());
    $("msgs").insertAdjacentHTML("beforeend", `<div class="msg bot">${escapeHtml(r.answer)}</div>`);
    history.push({ role: "assistant", text: r.answer });
    $("msgs").scrollTop = $("msgs").scrollHeight;
  };
  function escapeHtml(s) { return s.replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&#39;" }[c])); }
})();
</script>

Shadow DOM means it can't conflict with the host site's CSS — and we tested it against three increasingly broken WordPress themes without a single style collision. The whole script is 3.2 KB gzipped.

What it cost the clinic, real numbers

After 3 weeks running:

Item	Usage	Cost
Gemini 2.5 Flash	~4,200 requests	$0 (free tier)
Gemini text-embedding-004	~4,500 calls	$0 (free tier)
Cloudflare Workers	~9,000 invocations	$0 (free tier)
Cloudflare Vectorize	15K dimensions stored, ~9K queries	$0 (free tier)
Total monthly		S$0

At their projected scale (3× current traffic), they'd cross into paid tier — estimated S$3-5/month. Compare to a SaaS chatbot at S$50-100/month with worse grounding.

What I'd do differently next time

Crawl with sitemaps first, fall back to link-following. The link crawler hit two infinite calendar pages and ate 12 minutes before I added depth limits.
Store the embedded markdown source, not the stripped text. When the LLM cites a source URL, having clean markdown in the context lets it format lists/tables properly in answers.
Tag chunks by section (services, hours, doctors). Routing high-confidence intents directly to a deterministic answer skips the LLM call entirely for ~30% of traffic.

The bigger pattern

This same approach works for clinics, restaurants, professional services, real estate listings, any business with structured public content. The legacy-site constraint is actually a feature: you don't have to convince ops to change anything, just paste a script tag.

If you're an agency or in-house dev looking at a WordPress/Webflow site and getting asked "can we add AI?" — the answer in 2026 is yes, in an afternoon, for ~S$5/month. The model quality has crossed the line where you can ship grounded answers without a research team behind you.

At our agency SGBP — Singapore Build Partners we've rolled this same pattern out for clinics, hawker chains, and B2B service firms across Singapore — happy to compare notes if you're sizing one up. Drop your repo or stack in the comments and I'll share the version we used for that vertical.

Otherwise — go ship it. Three hours of your weekend, one less plugin invoice for your client.

Daniel Cheong is a Senior Frontend Engineer at SGBP. He writes about Vue, Astro, AI integrations, and the boring infrastructure that makes web products actually fast.