DEV Community: Sherotree

SVG to PNG in the tab when the design export is vector-only

Sherotree — Tue, 03 Nov 2026 15:34:09 +0000

Design drops an SVG. Slack wants a PNG. The App Store listing wants a PNG. Email clients laugh at SVG. Your CI screenshot fixture wants a PNG. And you're on Linux, so "just Open in Preview → Export" is not a thing.

I hit this weekly. The vector file is correct — scale, colors, viewBox all fine — but the consumer only eats raster. Opening Illustrator (or waiting for design to re-export at 1x/2x/3x) for a one-off PNG is the slow path.

So I keep a tab workflow: SVG in → PNG out, without uploading the mark to a random converter.

When SVG alone isn't enough

SVG is great inside the product:

Icons that follow currentColor
Responsive logos that stay crisp
Inline chrome that never blur on retina

PNG still wins outside the product:

Chat / docs — Slack, Notion, Linear comments often strip or refuse SVG
Marketing surfaces — many email clients, some CMS uploaders, OG image pipelines
Stores & listings — App Store / Play / directory forms that hard-require PNG/JPG
Diff fixtures — visual regression baselines are almost always raster
Partner handoff — "send me the logo" usually means a transparent PNG, not XML

Keeping the source as SVG and deriving PNG at the moment of need beats maintaining a parallel PNG folder that drifts.

What goes wrong with the naive paths

Ask design for another export — fine for a brand refresh; painful for "I need a 512px transparent mark before standup."

Desktop converters — ImageMagick / Inkscape / Affinity work, until you're on a locked laptop, a hotel Wi‑Fi machine, or someone else's Chromebook.

Upload-to-convert sites — easiest to regret. Brand SVGs are IP. I don't want the mark sitting in someone else's temp bucket because I needed a PNG for a README.

Screenshot the SVG in the browser — you get wrong DPI, wrong background, wrong crop, and a JPEG-looking mess more often than you admit.

What I actually need from the convert step

For frontend / DX use, the checklist is boring and specific:

Transparent background by default (don't bake white unless I ask)
Explicit pixel size — 128 / 256 / 512 / 1024, not "whatever the viewBox felt like"
No upload — file stays in the tab (DevTools Offline litmus still applies)
Predictable naming — logo-512.png, not download (17).png
Sanity preview before download — catch missing fonts / clipped paths early

If the tool can't do those five, I'm back to Inkscape CLI.

A tab that fits the handoff

When design already gave me the SVG and I just need raster for a non-SVG surface, I've used Uwarp's SVG → PNG tool — drop the file, pick a size, download PNG in the browser. Worth trying when the alternative is another desktop install or an upload converter you can't audit.

For a recurring pipeline (favicon set, store assets, email header), script it: rsvg-convert, inkscape --export-type=png, or a tiny Puppeteer render. The tab is for the one-offs that shouldn't block a PR.

Keep the SVG as source of truth

A few rules that stopped me from growing a junk drawer of PNGs:

Commit SVG in the design-system / brand repo; generate PNG at publish time
Name by intent + size (mark-on-dark-512.png), never final_final2.png
Don't "edit" the PNG — if color changes, change the SVG and re-export
Document the sizes you actually ship (email 600w, OG 1200×630, store 1024) so people stop inventing new ones in Slack

SVG → PNG is a packaging step, not a design decision. Treat it like that and the folder stays boring.

Tiny habit

Next time someone asks for "the logo as PNG" and you already have the SVG, don't reopen the design tool and don't upload the brand mark. Convert in a local-ish tab (or a one-liner CLI), verify transparency and size, send the file, close the loop.

Fewer blocked handoffs. Fewer mystery PNGs in Downloads. Same vector source — just the raster shape the other surface actually accepts.

Tiny icons as data URIs — skip another network hop for chrome assets

Sherotree — Tue, 03 Nov 2026 14:33:38 +0000

Chrome UI is full of tiny assets that should never fight the critical path: a 16×16 chevron, a mute glyph, a spinner frame, a toolbar mark that shows up before the rest of the page finishes deciding who you are.

I still see those shipped as separate /icons/*.svg or /icons/*.png requests. On a good day they ride HTTP/2 multiplexing and you barely notice. On a cold CDN edge, a flaky hotel Wi‑Fi, or a settings drawer that mounts before the icon sprite is warm, you get the classic flash of empty boxes.

For chrome icons — not hero art, not user avatars — I default to inlining as data URIs more often than I used to.

What I mean by "chrome assets"

Not the marketing hero. Not a product screenshot. The boring bits that make the shell feel finished:

Sidebar / toolbar glyphs under ~2–4 KB each
Empty-state illustrations that are basically icons with padding
Status dots and badges that are vector or tiny PNG
Favicon-sized marks reused inside the app chrome

If an asset is decorative, tiny, and shown before meaningful paint, a network hop is a tax. If it's large, user-generated, or rarely shown, leave it as a normal URL.

The network hop you forget about

A separate icon URL costs more than bytes:

Priority / queue — competes with CSS, fonts, and your first API call
Cache miss on first visit — every new deploy with hashed filenames resets the miss
CORS / CSP footguns — SVG-as-<img> vs inline SVG vs background-image all behave differently
Layout flash — width/height reserved late → CLS or empty toolbar buttons

Data URIs don't magically shrink bytes (base64 costs ~33%), but they remove a round trip and make the asset travel with the CSS/JS that needs it. For a 600-byte SVG that's often the right trade.

When data URIs win (and when they don't)

Prefer data URI when:

The icon is ≤ ~2–3 KB uncompressed (SVG preferred)
It appears in first paint / shell / authenticated chrome
You're already shipping a CSS or JS module that owns that surface
You don't need the browser to cache the same glyph across many unrelated pages independently

Prefer a normal URL (or sprite) when:

The asset is large or shared across many independent entry points
You need CDN edge caching and long-lived immutable URLs
Design iterates the icon weekly and you don't want CSS churn
You're shipping dozens of icons and a sprite / icon font / SVG sprite sheet is cleaner

I don't inline a 40 KB illustration. I do inline the 800-byte "copy" glyph next to every code block toolbar.

A workflow that doesn't fight the design handoff

Design still exports PNG/SVG. Engineering still needs a string you can paste into CSS:

.toolbar-copy {
  background-image: url("data:image/svg+xml,...");
  background-size: 16px 16px;
}

or:

const COPY_ICON =
  "data:image/svg+xml," + encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>`);

The friction is converting the export into a safe data URI without opening three tabs and hoping the encoder didn't mangle # / quotes.

Checklist I use:

Prefer SVG over PNG when the mark is flat UI chrome
Strip editor junk (id, unused defs, Illustrator cruft) before encoding
Prefer encodeURIComponent for SVG (not base64) so the string stays readable in diffs
Cap size — if the data URI is longer than the component that uses it, reconsider
Keep width/height in CSS so you don't rely on intrinsic size for layout

Converting without another upload site

I don't want to POST a brand mark to a random "image to base64" site just to get a data: string. Same Offline litmus as other one-off transforms: if convert dies with DevTools Offline, it wasn't local enough for me.

When I need a quick tab for this, I've used Uwarp's image → data URI tool — drop the icon, get a data URI, paste into CSS/JS. Worth trying when the alternative is a desktop converter or an upload encoder you can't audit.

Roll your own if this is daily: a tiny Node script with fs.readFileSync + encodeURIComponent is fine. The point is the habit (inline tiny chrome) more than the tool.

Don't turn this into a religion

A few failure modes I hit:

Inlining everything → CSS balloons; first paint gets worse, not better
Base64 PNG for every glyph → you paid the 33% tax and still ship raster blur on retina
Inlining user avatars → privacy + size disaster; never do this
Forgetting dark mode → one data URI, one color; prefer currentColor SVG or dual tokens

Rule of thumb: if I can't justify the icon as "shell chrome under a few KB," it stays a URL.

Tiny habit

Next time you add a toolbar button and reach for /assets/icons/copy.svg, ask: is this a critical-path chrome glyph? If yes, inline it as a data URI (SVG + encodeURIComponent preferred). If no, leave the network hop alone.

Fewer empty boxes on first paint. Fewer "why is the mute icon late?" threads. Same design file — just a better shipping shape for the tiny stuff.

Record a short repro for the agent instead of describing the bug in Slack

Sherotree — Tue, 03 Nov 2026 12:54:13 +0000

I’ve lost count of how many Slack threads start with “the settings page is weird on save” and end with three people guessing which field, which browser, and whether it’s staging or prod. Then someone pastes a paragraph of vibes into the coding agent and wonders why the patch misses.

Agents don’t need your narrative. They need a short, replayable repro — something they can open, run, or watch once and map onto files. Describing the bug in chat is the slow path.

What “short repro” means (under ~90 seconds)

Not a full Loom walkthrough. Not a five-minute screen share. One of these, whichever is cheapest:

Recorded steps — numbered clicks + expected vs actual (fits in a comment)
Failing URL + query/state — deep link with the bad filter, locale, or feature flag already on
Minimal HAR / network snippet — the one 500 that matters, not the whole waterfall
10–30s screen recording — only if timing / animation / hover is the bug
Console + stack — the red line and the first app frame, not a wall of React warnings

If it takes longer to make the repro than to guess twice, you’re overbuilding. Cap it.

The Slack description tax

A typical thread looks like:

“User said save doesn’t work. I tried once, seemed fine. Maybe race? Can someone check?”

That message is useful for humans coordinating. It’s garbage input for an agent. There’s no route, no payload, no browser, no “works on /settings?tab=billing but fails on /settings?tab=team”.

I treat Slack as the routing layer (“who owns this / is it Sev?”) and the agent chat / PR as the artifact layer. Don’t merge those jobs.

A repro pack I actually paste

I keep a stub next to bug triage so I’m not inventing format every time:

## Repro for agent

**Surface:** Settings → Team members  
**Env:** staging, Chrome 130, logged in as org-admin  
**URL:** https://staging.example.com/settings/team?invite=open  
**Steps:**
1. Open invite modal
2. Enter email already in org
3. Click Send invite
**Expected:** inline error “Already a member”
**Actual:** spinner forever; network tab shows POST /invites → 409 with body `{ "code": "duplicate" }`; UI never reads `code`
**Artifacts:**
- console: `Unhandled rejection: InviteError`
- optional: 18s recording `repro-invite-409.mp4` (only if steps unclear)
**Out of scope:** redesign modal, change API status codes
**Ask:** smallest UI fix — map 409/duplicate to the existing error component

That pack is boring on purpose. Agents thrive on boring.

Why recordings beat paragraphs (sometimes)

When the bug is timing — toast that flashes, focus that jumps, drag that drops a pixel early — prose fails. A 15-second clip with the mouse visible beats five Slack messages.

Rules I use so recordings stay useful:

Start already on the broken screen (no login theater)
One take; don’t narrate a podcast over it
Name the file with the symptom (invite-spinner-409.mp4), not screen-recording-tuesday
Still write the Expected/Actual lines — video alone is slow to index

If the bug is a clear 409 and a missing branch, skip the video. Steps + network row win.

Wire it into the agent workflow

Before asking for a fix: drop the repro pack (and file paths if you know them).
Constraint line: “touch only the invite modal + its error mapper; no API changes.”
Acceptance: “show me the branch that handles code === 'duplicate' and a one-line test or Storybook state.”

A prompt I reuse:

Here’s a short repro. Don’t ask clarifying questions you can answer from the pack. Propose the smallest patch and name the files you’ll change.

Agents that can see the failure waste less of your review time inventing theories.

What I stopped doing

Pasting “it’s broken” into the agent and hoping
Screenshot-only reports with no URL or status code
Long voice notes that never become steps
Letting the agent “explore the settings area” without a target state

Exploration without a repro is how you get drive-by refactors.

Tiny habit, big DX win

Next time you’re about to type a paragraph in Slack and into the agent, stop. Spend ninety seconds on a repro pack. Route ownership in Slack; feed artifacts to the agent.

You’ll get smaller diffs, fewer “works on my machine” loops, and fewer threads that exist only to reconstruct what one recording would have shown.

Prompt packs for empty / error / loading states — stop shipping happy-path only

Sherotree — Tue, 03 Nov 2026 11:25:49 +0000

Agents are weirdly good at the happy path. Give them a Figma frame of a filled dashboard and you get a filled dashboard. Give them a “build a projects list” prompt and you get rows, avatars, and a neat toolbar.

What you usually don’t get: the empty list on day one, the 500 that lands mid-scroll, or the skeleton that doesn’t jump when real data arrives. Those states are where users decide whether the product feels finished — and they’re the first thing agents skip unless you ask for them on purpose.

So I stopped describing “the screen” and started shipping prompt packs for the three non-happy states every surface needs.

The pattern: one pack per surface, four stories minimum

For any list / detail / settings panel the agent touches, I keep a tiny markdown pack next to the feature (or in the PR description). Four required stories:

Happy — data present, primary actions enabled
Empty — zero rows / first-run / filtered-to-nothing (these are different)
Error — failed fetch, partial failure, retry affordance
Loading — initial load and refetch / pagination (also different)

If the agent only returns #1, the PR is incomplete. Same bar as “missing tests.”

Example pack stub I paste into the agent chat:

## Surface: Projects list (`ProjectsPage`)

Implement ALL four states before considering this done.

### Happy
- 3–12 projects; name, updatedAt, owner avatar
- Primary CTA: New project (top-right)
- Row click → project detail

### Empty (three variants — do all)
- First-run: zero projects ever → illustration + “Create your first project”
- Filtered empty: filters active, zero matches → “No projects match” + Clear filters
- Archived-only: toggle shows archived but none → short copy, no big empty art

### Error
- List fetch failed → inline error in list region, Retry button, keep chrome
- Do NOT full-page crash the app shell
- Preserve last-known list if refetch fails (stale-while-error)

### Loading
- Initial: skeleton rows matching final layout (same columns / gutters)
- Refetch: subtle top progress or opacity — do NOT remount full-page spinner
- No layout shift when data lands (reserve avatar + title width)

That pack is boring on purpose. Agents love inventing a clever empty illustration and forgetting Clear filters.

Why “empty” needs variants

“Empty state” is not one design. First-run is marketing-adjacent. Filtered-empty is a recovery path. Permission-empty (“you can’t see any projects yet”) is a different CTA entirely.

If you only say “add an empty state,” the model picks the prettiest one and ships it for every case. Then support gets “I filtered by tag and the whole page turned into onboarding.”

Name the variants in the pack. Force the agent to emit separate components or clear branches:

type ListPhase =
  | { kind: 'loading'; mode: 'initial' | 'refetch' }
  | { kind: 'error'; error: Error; stale: Project[] | null }
  | { kind: 'empty'; reason: 'first-run' | 'filtered' | 'archived' | 'forbidden' }
  | { kind: 'ready'; items: Project[] };

I ask the agent to type the phase union first. The UI has somewhere to hang after that.

Error states agents keep getting wrong

Common agent mistakes I reject in review:

Full-page error that unmounts the nav
Toast-only failure with an infinite spinner underneath
Retry that re-runs the whole route loader and wipes scroll
Copy that blames the user (“Something went wrong. Try again later.”) with no Retry

In the pack I spell the contract:

### Error contract
- Error UI lives *inside* the list landmark (`role="region"` / labelled heading)
- Retry calls the same query fn; disable button while in flight
- If `stale` exists, show dimmed list + banner — don’t blank the page
- Log `error.message` for support; never render raw stack to the user

Agents follow contracts better than vibes.

Loading without the layout jump

Happy-path demos hide CLS. Real users notice when the toolbar drops 40px after load.

I put explicit anti-shift rules in the loading section:

### Loading anti-shift
- Skeleton row height === real row height (measure once, hardcode)
- Keep page title + primary CTA mounted during initial load
- Prefer `content-visibility` / fixed skeleton count over “spinner in a void”
- Refetch must not replace the list with a centered spinner

If the design system already has <Skeleton>, tell the agent which one — otherwise it invents a new shimmer.

How I wire this into the agent workflow

Before codegen: paste the pack (or @-mention docs/prompt-packs/projects-list.md).
Acceptance: “PR must include Storybook stories or Playwright cases for empty/error/loading, not only happy.”
Review checklist: open the four states in Storybook before reading the diff. If empty looks like happy with items=[] and no CTA, bounce it.

A one-liner that saves me hours:

Don’t merge agent UI that only has a happy path Storybook story.

Minimal Storybook set I ask for

export default { title: 'Projects/List', component: ProjectsList };

export const Happy = () => <ProjectsList phase={{ kind: 'ready', items: mockProjects }} />;
export const FirstRun = () => <ProjectsList phase={{ kind: 'empty', reason: 'first-run' }} />;
export const FilteredEmpty = () => <ProjectsList phase={{ kind: 'empty', reason: 'filtered' }} />;
export const LoadError = () => (
  <ProjectsList phase={{ kind: 'error', error: new Error('503'), stale: null }} />
);
export const InitialLoading = () => (
  <ProjectsList phase={{ kind: 'loading', mode: 'initial' }} />
);

Five stories beats a paragraph of “please handle edge cases.”

What changed after we did this

Fewer “looks done in staging, broken for new orgs” launches
Reviewers stop arguing about taste and point at a missing story
Agents stop optimizing only for the screenshot we pasted from Figma

Happy path is still the demo. Empty / error / loading are the product. Put them in the prompt pack up front, or you’ll keep shipping demos.

Feature-flag AI-suggested UI before it hits every user

Sherotree — Mon, 02 Nov 2026 15:32:22 +0000

The first time we shipped an agent-written settings panel straight to main, it looked fine in staging. Then support got three tickets in an hour: a toggle that did nothing for free plans, a “Save” that double-fired on slow networks, and a new empty state that hid the only CTA half our users needed.

CI was green. Visuals looked close. The bug was product judgment the model never had — and we gave 100% of traffic that judgment on day one.

So we stopped treating “agent UI merged” as “agent UI live.” Feature flags became the default release valve for anything an agent touched in the UI layer.

The failure mode: merge = rollout

Agent PRs tempt you to skip the usual caution:

Diff is “just UI”
Screenshots look right
Playwright clicked through the happy path
Reviewer approved the code shape

None of that answers: does this layout work for the cohort that never sees premium fields? Does the new empty state break the onboarding funnel? Does the regenerated form still respect the old keyboard path power users rely on?

Those are traffic questions. Feature flags are how you ask them without a full revert.

What I flag (and what I don’t)

I flag user-visible surfaces the agent authored or heavily rewrote:

New panels, modals, empty / error / loading states
Regenerated forms and settings sections
Agent-refactored navigation / IA changes
Copy-heavy UI where tone or CTA placement shifted

I usually don’t flag:

Pure token / lint / type cleanup with no layout change
Test-only or Storybook-only diffs
Internal admin tools with a tiny known audience (still stage them; just don’t burn a flag name)

Rule of thumb: if a stranger on the free plan could hit it tomorrow, it gets a flag.

The default pattern we use

Keep it boring. One boolean (or percentage) per agent UI surface, named after the ticket, not the model:

// flags.ts — names are product, not “gpt-panel-v3”
export const flags = {
  settingsBillingV2: booleanFlag('settings-billing-v2', false),
  emptyProjectsAgentCopy: booleanFlag('empty-projects-agent-copy', false),
} as const;

In the route / component:

export function SettingsBilling() {
  const enabled = useFlag('settings-billing-v2');

  if (!enabled) {
    return <SettingsBillingLegacy />;
  }

  return <SettingsBillingV2 />; // agent-authored surface
}

Kill switch lives next to the flag definition, not in a Slack thread:

// ops: set settings-billing-v2 = false → instant revert without redeploy

If your stack is LaunchDarkly / Unleash / Statsig / a homegrown % cookie — same idea. The important part is default off for agent UI, not which vendor.

Rollout ladder (what we actually do)

Internal / dogfood — flag on for the team only. Click the weird paths humans use.
1–5% — watch error rate, rage clicks, support tags for that surface.
25% → 50% — only if step 2 is quiet for a real workday, not twenty quiet minutes.
100% — then delete the legacy branch when you’re sure, not “someday.”

Agent UI fails differently than human UI: it often fails narrowly (one plan tier, one locale, one empty-state branch). Small percentages catch that before it becomes a Monday war room.

What I put in the agent prompt

Feature flags are a release policy. The agent still needs to build behind them:

Implement this UI behind flag settings-billing-v2 (default off).

Keep SettingsBillingLegacy working and unchanged.

Do not delete legacy routes/components in this PR.

Wire the flag at the route/section boundary, not inside every leaf.

Add a short “flag off = legacy” note in the PR body.

Without that, agents “helpfully” delete the old panel and leave you with a binary deploy rollback.

PR template checkboxes

### Agent UI rollout
- [ ] New/changed user-visible UI is behind a named flag (default off)
- [ ] Legacy path still renders when flag is off
- [ ] Flag name matches the ticket / surface (not the model name)
- [ ] Rollout plan noted: dogfood → % → 100% (or “internal-only”)
- [ ] Kill switch owner named (who can flip it in prod)

Reviewers stop arguing “is this ready?” and start asking “who turns it on?”

Metrics I watch for the first day

Not vanity:

Error / exception rate on the flagged route
Support tickets tagged with that surface
Funnel drop at the new empty / CTA step
Accessibility smoke (keyboard + one screen reader pass on dogfood)

If any of those spike at 5%, you don’t “monitor overnight.” You flip the flag off and open a fix PR.

Review comments I leave

When the agent rewrote a panel with no flag:

This surface ships to every user on merge. Wrap it in settings-billing-v2 (default off) and keep legacy until we ramp. Agent UI doesn’t get a free pass on rollout.

When they deleted legacy in the same PR:

Don’t delete SettingsBillingLegacy here. Flag-off must still work. Removal is a follow-up after 100% + quiet metrics.

When the flag is hardcoded true “for testing”:

Hardcoded true is a silent 100% rollout. Use the real flag client; leave default false in prod config.

What I stopped doing

Merging agent UI straight to 100% because staging looked pretty
Naming flags after models (gpt-settings-rewrite) instead of product surfaces
Letting the agent delete legacy in the same PR that introduces the new UI
Treating “Playwright green” as “safe for everyone”

Feature-flagging AI-suggested UI isn’t distrust of the model — it’s admitting the model never saw your free-plan edge cases, your support queue, or your Monday traffic. Ship the code when it’s ready. Ship the exposure when the numbers say so.

Constraining agent CSS to design tokens (without pasting the whole theme)

Sherotree — Mon, 02 Nov 2026 14:32:43 +0000

I used to drop the entire tokens.css into the agent prompt so it “wouldn’t invent colors.” It still invented colors. Just prettier ones — #3B82F6 instead of blue, 14px instead of space.3, a one-off radius that almost matched radius.md.

Pasting the whole theme teaches the model what exists. It does not teach it that everything else is illegal. Agents treat big token dumps like a style moodboard, then freestyle.

Here’s the thinner constraint that actually stuck in our agent UI PRs.

The failure mode: theme dump

A prompt like this looks responsible and fails quietly:

Here is our full design token file (800 lines of CSS variables). Style this settings panel to match.

What came back:

Hex that “felt close” to --color-accent-primary
padding: 18px because “the mock looked about that”
A new --card-shadow-soft declared inline in the component
Tailwind arbitrary values (bg-[#0f172a]) next to token classes

The model saw the tokens. It optimized for “looks like our product,” not “uses only the legal surface.”

What “token-constrained CSS” means

I define it as four hard rules the agent can fail against:

No raw values — no hex, rgb, hsl, or bare px/rem for color, space, radius, or shadow in changed CSS/JSX
Import / reference allowlist — only named tokens from the published set (var(--space-4), theme('spacing.4'), tokens.space[4], whatever your stack uses)
No local token invention — do not declare new --* custom properties in feature CSS unless the ticket says “new token approved”
Closest-token rule — if the design asks for something off-scale, stop and name the gap; don’t invent a near-miss

If the prompt only says “use our design system,” the agent hears “make it pretty.” Name the bans.

The slim token pack I actually paste

Instead of the whole theme, I keep a token cheat sheet under ~40–60 lines and refresh it when the public scale changes:

## Legal tokens (CSS / Tailwind / JS — same names)

### Color
- bg.default, bg.subtle, bg.muted
- fg.default, fg.muted, fg.danger
- border.default, border.strong
- accent.primary, accent.primary-hover
Forbidden: raw hex/rgb, inventing --color-*, opacity hacks that bake a new tint

### Space
- 1 2 3 4 5 6 8 10 12 (map to --space-* or spacing.*)
Forbidden: 13px, 18px, 22px, “eyeballed” padding, gap: 7

### Radius
- sm | md | lg | full
Forbidden: border-radius: 10px, rounded-[10px]

### Shadow
- shadow.sm | shadow.md | shadow.lg
Forbidden: one-off box-shadow stacks in feature CSS

### Type
- font.size: sm | md | lg | xl
- font.weight: regular | medium | semibold
Forbidden: font-size: 15px, font-weight: 450

## How to reference (pick your stack)
- CSS: var(--space-4), var(--color-fg-muted)
- Tailwind: p-4, text-fg-muted, rounded-md (token-mapped utilities only)
- JS/CSS-in-JS: tokens.space[4], tokens.color.fg.muted

## Acceptance (must pass before PR)
- [ ] Zero hex/rgb/hsl in the diff
- [ ] Zero bare px for space/radius/type (layout hacks like 1px hairlines need a one-line NOTE)
- [ ] Zero new --* declarations outside tokens/
- [ ] Any off-scale design ask is listed as a blocker, not approximated

That’s the whole “theme” most feature tasks get. The full tokens.css stays in the repo for humans and for codegen — the prompt carries the decision surface.

Prompt shape that works

My default ask looks like this:

Style X using only the Legal tokens below.

Do not invent colors, spacing, radius, or shadows.

If a value isn’t on the scale, stop and name the missing token — don’t approximate.

Prefer existing utility / token classes over new CSS files.

When done, paste the Acceptance checklist with pass/fail and list every token you used.

I also add one explicit ban that cut a lot of noise:

Forbidden: Tailwind arbitrary values for color/space/radius (bg-[#…], p-[18px], rounded-[10px]). If the utility doesn’t exist, the token doesn’t exist for this task.

Arbitrary values are how agents smuggle freestyle CSS past a “we use Tailwind” rule.

A tiny CI gate that catches the same mistakes

Prompts leak. I pair them with a cheap lint on agent-touched paths:

# scripts/check-no-raw-css-values.sh — run on changed UI files
rg -n --pcre2 \
  '(#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|\b\d+(\.\d+)?px\b|rounded-\[[^\]]+\]|bg-\[[^\]]+\]|p-\[[^\]]+\]|gap-\[[^\]]+\])' \
  src/components src/app \
  -g '!**/tokens/**' \
  -g '!**/*.test.*' \
  && exit 1 || exit 0

False positives happen (SVG path data, 1px hairlines). Allowlist those with a comment:

/* RAW_OK: 1px hairline separator — not a spacing token */
border-top: 1px solid var(--color-border-default);

The point isn’t zero exceptions. It’s that every exception is named, so agent PRs can’t quietly grow a second palette.

For Tailwind shops, eslint-plugin-tailwindcss with no-arbitrary-value (or a custom restrict) on src/features/** works even better — fail the PR when the model reaches for [#0f172a].

What I put in the PR template

A short checkbox beats another paragraph in the system prompt:

### Token compliance
- [ ] No raw color / space / radius / shadow values in the diff
- [ ] No new --* tokens outside tokens/
- [ ] Off-scale design requests called out (not approximated)
- [ ] `scripts/check-no-raw-css-values.sh` (or ESLint) passed

Reviewers stop arguing taste (“that blue is fine”) and start enforcing the scale.

Review comments I actually leave

When I see freestyle CSS in an agent diff:

Token miss: padding: 18px isn’t on the space scale. Use var(--space-4) / p-4 or stop and request a new token. Don’t approximate.

When the model invents a local variable:

New --card-shadow-soft belongs in tokens/ with a design OK, not in the feature file. Revert and use shadow.md or file a token RFC.

When Tailwind arbitrary values show up:

bg-[#0f172a] is a banned escape hatch here. Map to bg-subtle / bg-muted or name the missing token. Arbitrary color values fail the token gate on purpose.

What I stopped doing

Pasting the entire theme “for completeness”
Saying “match the design system” without listing banned value types
Trusting the model to “prefer tokens” without a lint gate
Letting one-off hex land because “it’s only in this panel”

Constraining agent CSS to design tokens is less about teaching every variable name and more about shrinking the legal alphabet. Give a short allowlist, ban raw values out loud, and fail CI when freestyle sneaks in. The full theme can stay in the repo — it just doesn’t need to live in every prompt.

Pair agent UI work with visual regression before you trust green CI

Sherotree — Mon, 02 Nov 2026 13:01:11 +0000

Unit tests pass. Typecheck is green. Playwright happy-path clicks through. The agent PR still ships a button that jumped 8px, a modal that lost its shadow, and a table whose sticky header now overlaps the first row.

I stopped treating “green CI” as proof that agent UI work is safe. Green means the logic didn’t break. Layout and visual regressions need their own gate.

Why agents are especially good at silent UI breaks

Agents rewrite JSX and CSS with confidence. They:

Swap gap for margin “to match the design”
Drop a wrapper that “wasn’t doing anything” (it was)
Change flex → grid mid-component without updating children
Tweak token usage that only shows up at a specific viewport
“Clean up” class names and lose a one-off override that fixed Safari

None of that fails a unit test. Snapshot DOM tests often miss spacing. E2E that asserts text still passes. Humans catch it in review — if they open the preview and squint hard enough.

What I mean by visual regression here

Not a full design QA suite on day one. A thin, blocking check on the surfaces the agent is allowed to touch:

Capture baseline screenshots of key states (default / hover / error / empty / mobile)
On the PR, re-capture the same states
Fail (or require human ACK) when pixels drift past a small threshold

Tools I’ve used in this role: Playwright screenshot diffs, Chromatic / Lost Pixel / Argos on Storybook stories, or a cheap custom Playwright compare in CI. The brand matters less than blocking merge when the diff is real.

Pair it with the agent prompt — don’t bolt it on after

If visual checks only run after the model already rewrote half the page, you burn a review cycle. I put the expectation in the task:

## Visual regression (HARD for UI diffs)

You are editing UI. Before you finish:

1. List the stories / routes / states you changed (default, hover, focus, error, empty, sm/md breakpoints if layout changed).
2. Do not claim “looks fine” without a screenshot or story URL.
3. Prefer smallest CSS/DOM change that keeps existing visual baselines.
4. If you must change layout structure, say so explicitly and list which baselines will need an intentional update.

Forbidden: drive-by spacing “cleanup”, deleting wrappers without checking computed layout, renaming classes that might be used in CSS modules / global CSS.

The agent still ships UI. It just knows silent restyles are not free.

Minimal Playwright gate that actually catches agent PRs

I don’t need full Storybook coverage on every legacy page. For agent-heavy areas I pin a few routes:

// e2e/visual/agent-surfaces.spec.ts
import { test, expect } from '@playwright/test';

const surfaces = [
  { name: 'settings-billing', path: '/settings/billing' },
  { name: 'checkout-summary', path: '/checkout/summary' },
  { name: 'empty-projects', path: '/projects?empty=1' },
];

for (const s of surfaces) {
  test(`visual: ${s.name}`, async ({ page }) => {
    await page.goto(s.path);
    await expect(page).toHaveScreenshot(`${s.name}.png`, {
      maxDiffPixelRatio: 0.01,
      animations: 'disabled',
    });
  });
}

maxDiffPixelRatio: 0.01 is strict enough that an 8px shift fails, loose enough that font hinting noise rarely pages me. Tune per app.

When an agent PR intentionally changes the look, update the baseline in the same PR with a one-line note: VISUAL_OK: billing card padding 16→20 per design. Silent baseline refreshes are how regressions hide.

Storybook is even better when you already have stories

If the component has stories, prefer visual diffs on stories over full-page shots:

Faster
Stable (less app chrome / data noise)
Matches how agents should work anyway — “edit Button story states, not random pages”

My rule for agent UI tasks: no story, no merge for shared components. Either the agent adds a story for the state it touched, or a human already had one. Page-level screenshots are the fallback for app shells.

What green CI means after this

Check	Catches
Unit / typecheck	Logic + types
E2E happy path	Flows still click
Visual regression	Spacing, color, overlay, breakpoint layout
Review	Taste, a11y nuance, product intent

Agent PRs that are “all green” without a visual gate are only green on the first two rows. That’s incomplete.

Review comments I actually leave

When I see a UI-only agent diff with no visual evidence:

Visual gate missing: this touches checkout summary layout. Add/update Playwright screenshot (or Storybook + Chromatic) for default + error + mobile, or paste preview screenshots in the PR. Don’t merge on typecheck alone.

When baselines change without explanation:

Baseline bump needs VISUAL_OK: <why>. Pixel drift without a design reason is a regression, not a cleanup.

What I stopped trusting

“I checked the preview” with no artifact
DOM snapshots as a substitute for pixels
Full E2E coverage as proof of layout
Agent claims that spacing changes are “equivalent”

Pair agent UI work with visual regression before you trust green CI. Keep the suite small, block on drift, and make intentional visual changes explicit. The unit tests can stay green — your users still see the 8px jump.

When agents invent APIs — make grep-first a merge gate

Sherotree — Mon, 02 Nov 2026 11:23:41 +0000

I keep catching agent PRs that call helpers that do not exist. Not typos — confident imports of fetchUserProfileV2, useCheckoutMachine, formatMoneyLocale. Green TypeScript locally (because the agent also invented a stub), red in CI once the stub is gone, or worse: green forever with a hand-rolled fake that nobody asked for.

The fix that stuck for me is boring: grep-first as a merge gate. Before the model writes a call site, it has to prove the symbol already lives in the repo — or stop and ask.

The failure mode

Agents optimize for “the feature works in this chat.” They do not feel the cost of a new private API. So they:

Import a name that sounds like your codebase
Add a 20-line util next to the feature instead of reusing the real one three folders away
Duplicate a hook with a slightly different signature
“Fix” missing exports by creating them, then leave the real module untouched

Reviewers then spend time deciding whether the new thing is intentional architecture or hallucinations with types.

Grep-first means what, exactly?

In the prompt (and later in CI), I require:

Search before invent — rg / IDE search for the intended symbol, path, or behavior
Cite the hit — paste the file path + a one-line snippet that proves it exists
Reuse or stop — if nothing matches, do not invent a public helper; either use a nearby existing pattern or stop with a short note: “no existing X; options are A/B”

Inventing a local private function inside the file you’re already editing is fine. Inventing a shared API is not — that’s a separate decision.

Paste this into the agent prompt

## API invent ban (HARD)

Before you import or call any symbol outside the files you are allowed to edit:

1. Search the repo for an existing equivalent (`rg -n "functionName|HookName|ModuleName"`).
2. In your reply, cite at least one real path + line that you will reuse.
3. If search returns nothing: STOP. Do not create a new shared util/hook/service.
   List 2–3 options (reuse nearby pattern / extend existing module / new module needs human OK).
4. Allowed without search: private helpers scoped to the current file only (not exported).

Do not invent `*V2`, `*New`, or parallel hooks “for clarity.”
Do not add barrel re-exports to paper over a missing symbol.

The STOP clause is the whole point. Without it, agents treat “prefer reuse” as vibes and keep typing.

What I grep for (frontend patterns)

I don’t only search the exact name the model wants. I search for behavior:

Intent	Grep seeds I actually try
Money / currency format	`formatMoney`, `Intl.NumberFormat`, `currency`
Auth header / session	`getSession`, `authHeaders`, `useUser`
Feature flag	`useFlag`, `isEnabled`, `Statsig`, `LaunchDarkly`
Analytics event	`track(`, `analytics.`, `capture(`
Date display	`formatDate`, `dayjs`, `date-fns`, `Temporal`

If any of those hit a shared module, the agent must wire that — not ship utils/formatPrice.ts #4.

Merge gate, not just a prompt

Prompts alone drift. I also fail the PR when the diff introduces new exports under shared folders without a checklist comment.

Lightweight version that has worked:

# fail if agent added exports under shared API dirs without REVIEW_OK
git diff --name-only origin/dev...HEAD | rg '^src/(lib|shared|api|hooks)/' || true

Then in review (or a bot comment): any new file under those roots needs either:

A link to the existing API it replaces, or
A one-line REVIEW_OK: new shared X because Y from a human

I’m not trying to ban new APIs. I’m trying to ban silent new APIs from a model that never looked.

How I push back in review

When I see a fresh helper that duplicates something:

Grep-first miss: formatMoney already lives in src/lib/money.ts. Drop formatPriceLocale. Reuse the existing export. If the signature is wrong, extend that module in a follow-up — don’t fork it in the feature folder.

Concrete path beats “please reuse existing utilities.”

Exceptions I allow

Generated clients (OpenAPI / GraphQL) — inventing wrappers is still gated; calling generated types is fine
One-file prototypes behind a feature flag — still no new shared exports
True greenfield modules — human says so up front in the prompt (“create src/lib/playback/”)

If the task is “add a shared date lib,” say that. Don’t let “fix checkout copy” smuggle one in.

Tiny checklist before I merge agent UI/API work

[ ] Every new import outside the blast radius was grepped and cited
[ ] No new files under shared / lib / hooks without human OK
[ ] No *V2 / parallel hook next to an existing one
[ ] Private helpers stay unexported
[ ] CI or review bot can spot new shared exports

What I stopped doing

Trusting “I checked the codebase” without a path citation
Merging “small util, we’ll consolidate later”
Letting TypeScript green mean the API is real
Arguing about taste when the issue is a missing rg

Agents invent APIs because inventing is cheap and searching is optional. Make search mandatory, cite the hit, and treat new shared exports as a merge gate. The feature still ships — just on the APIs you already own.

Diff budgets for AI PRs: lines, files, and blast radius

Sherotree — Mon, 02 Nov 2026 09:33:31 +0000

I stopped arguing with agents about “keep the PR small.” Small is mushy. What works is a diff budget — hard numbers for lines, files, and blast radius — written into the prompt before the model starts typing.

Green CI on a 1,200-line agent PR is not a win. It’s a review hostage situation.

Why agents blow past “small”

Models don’t feel review pain. Given a feature ask, they’ll happily:

Touch every file that might be related
Rewrite tests “for clarity” while fixing the bug
Drive-by format / rename / import-sort half the package
Open shared UI primitives because “the Button was almost right”

You said small. They optimized for complete. Completeness without a budget looks like a megadiff.

The three budgets I actually use

I put all three in the prompt. Soft limits get ignored; hard stops get obeyed more often.

Lines — max changed lines (insertions + deletions), e.g. ≤ 200 for a bugfix, ≤ 400 for a feature slice
Files — max paths touched, e.g. ≤ 8 (tests count)
Blast radius — allowed directories / globs, e.g. only src/features/checkout/** + colocated tests

Miss any one and reviewers lose the thread. A 150-line change across 25 files is still painful. A 300-line change inside one feature folder is often fine.

Paste this into the prompt

## Diff budget (HARD — stop if you would exceed)

- Max files: 8 (including tests / stories)
- Max lines: 250 (git diff --stat total)
- Blast radius: ONLY src/features/checkout/** and **/checkout*.test.*
- Do NOT edit: src/components/ui/**, shared hooks, CI, package.json, lockfiles

If the task needs more: STOP. List what you’d need and why.
Do not “almost finish” outside the fence.
Prefer a follow-up PR over expanding scope.

That STOP clause matters. Without it, agents treat the budget as a suggestion and keep going.

How I pick the numbers

Rough defaults I reuse on frontend work:

Kind of change	Files	Lines	Typical fence
Bug fix / copy / a11y	1–4	≤ 120	One component + test/story
Small feature slice	3–8	≤ 250	Feature folder only
Refactor (rename/extract)	2–6	≤ 200	One intent, no behavior change
Migration / codegen	separate rules	—	Often file-count heavy; budget by intent, not vanity lines

If the real work can’t fit, I split the ask before prompting — not after reviewing a monster.

Measure, don’t vibe

After the agent stops, I run:

git diff --stat
git diff --name-only | wc -l

If --stat or the file count is over budget, I don’t deep-review. I send it back:

Over budget: 14 files / 480 lines. Fence was checkout/**, max 8 / 250. Split into (1) UI state (2) API wiring — or justify the overrun in one paragraph.

Agents respond well to concrete overruns. “Too big” does nothing. Numbers do.

Blast radius beats line count

Line budgets alone miss the scary cases:

One-line changes in auth, payments, and i18n config
Touching design-system primitives for a page-level tweak
Editing both app code and generated GraphQL types “while here”

So I always name allowed globs and forbidden areas. When the agent needs a shared Button change, I want a stop + a note — maybe that becomes PR #2 with its own reviewers.

Pair budgets with one intent

A diff budget without one intent still fails. “Fix checkout + clean hooks + update Storybook” will thrash inside the numbers by doing three half-jobs.

Prompt shape I like:

One sentence intent
Diff budget block
Acceptance checks (tests / story / manual path)
Explicit non-goals

Example non-goals: no renames, no dependency bumps, no “improve types” outside touched signatures.

What I do when overrun is legitimate

Sometimes 12 files is correct (rename across the feature). Then I:

Raise the file budget and freeze line budget for behavior
Or require one commit per concern inside the PR
Or stack two PRs: mechanical rename first, behavior second

I still write the new budget into the prompt. “Unlimited because rename” is how you get rename + rewrite.

Tiny checklist before I hit send

[ ] Intent is one sentence
[ ] File max + line max + path fence are numbers/globs, not adjectives
[ ] Forbidden paths listed
[ ] STOP-and-report rule present
[ ] How I’ll measure (git diff --stat) stated up front

What I stopped doing

Saying “keep it reviewable” with no numbers
Accepting “I had to touch Button” without a separate PR
Reviewing over-budget diffs hoping the important hunks would jump out
Letting test rewrites eat half the line budget on a one-line product fix

Diff budgets turn “please be careful” into something the agent can fail against. Lines, files, blast radius — pick all three, put them in the prompt, and send the PR back when the meter trips. Review time stays scarce; the model’s typing speed doesn’t get a blank check.

Give the agent a failing Storybook story, not a vague “fix a11y”

Sherotree — Sat, 31 Oct 2026 15:41:24 +0000

I used to type “make this component accessible” into the agent and hope for the best. It would sprinkle aria-labels, flip a couple of roles, and declare victory. CI still failed. Reviewers still found focus traps. The agent wasn’t wrong about intent — I had given it a vibe instead of a failing unit.

What actually works: hand the agent a red Storybook a11y story (or the axe / Accessibility addon output for that story) and ask for the smallest fix that turns it green. Same pattern as pasting a Playwright failure — artifacts beat slogans.

Why “fix a11y” produces fake green

Vague a11y prompts invite:

Decorative aria-labels on elements that already have visible text
Role swaps that silence axe but break keyboard order
“Skip to content” links that aren’t in the story under test
Color-contrast “fixes” that only work on the agent’s assumed theme

Agents optimize for the prompt you wrote. If the prompt is “be accessible,” they’ll invent compliance. If the prompt is “story Button/Loading fails rule button-name — fix only that,” they have a target.

The artifact I paste now

I keep stories that are supposed to fail until fixed — or I run the a11y addon / @storybook/addon-a11y / axe-playwright against a specific story id and paste the raw report.

## Storybook a11y failure (paste raw)

Story id: ui-button--loading
Story file: src/components/Button/Button.stories.tsx
Component: src/components/Button/Button.tsx

<<< paste axe / addon violations: rule id, nodes, html, failureSummary >>>

Goal: smallest change so THIS story passes a11y for the listed rules
Out of scope: rewriting the design system, adding new variants, “improving” unrelated stories
Do not: invent aria-labels that duplicate visible text; do not remove interactive roles to silence axe

That “out of scope” line matters. Left alone, agents will refactor the Button API mid-fix.

Make the failure cheap to reproduce

A few habits that keep this loop under five minutes:

Name stories after states that break a11y — Loading, IconOnly, DisabledWithTooltip, ErrorInline. Happy-path Default rarely teaches the agent anything.
Run one story in CI (or locally) with axe attached — don’t wait for a full visual suite.
Prefer rule ids in the prompt (button-name, label, color-contrast, focus-order) so the agent doesn’t “fix” a different problem.
Include the rendered HTML snippet from the report when the DOM is the bug (extra wrappers, missing for/id).

Example constraint I reuse:

You are fixing ONE Storybook a11y failure.

Rules:
- Change the component or the story controls — prefer the component if the bug is real
- Keep visible labels; do not hide text and replace it with aria-only labels
- Icon-only buttons need an accessible name that matches the UI meaning
- If contrast fails, use design tokens / existing theme vars — do not hardcode hex the design system doesn’t own
- If the failure looks like a false positive from the test harness, STOP and say so — do not paper over it

What good agent output looks like

I want:

Which rule failed and why in one sentence
The minimal diff (often 5–20 lines)
How to re-check (storybook --test / addon panel / axe on that story id)
What they deliberately did not change

I reject “added aria-label everywhere.” That’s the vibe fix again.

Pair this with review, not instead of it

A green Storybook story is necessary, not sufficient. Humans still catch:

Focus order that axe doesn’t flag as broken but feels wrong in a modal
Live regions that announce too often
Mobile zoom / dynamic type issues outside the story viewport

So the workflow is: agent clears the measurable violation → you tab through the story once → then merge. Don’t skip the tab-through because axe went quiet.

A tiny checklist before you prompt

[ ] Story id + file path
[ ] Raw violation list (rule + node)
[ ] Theme / mode if contrast is involved (light/dark)
[ ] Explicit “do not invent labels / do not delete assertions”
[ ] Re-run command for that story only

What I stopped doing

Pasting Figma screenshots and saying “make it WCAG”
Asking for a full a11y audit of a folder in one shot
Accepting blanket aria-hidden on icons without checking the button name
Treating addon green as “we’re done” without a keyboard pass

Give the agent a failing story. Get a patch you can re-run. Save the sermons for design critique — the model is much better at turning red axe output green than at inventing your accessibility policy from a slogan.

GIF to Live Photo without leaving the tab

Sherotree — Sat, 31 Oct 2026 14:28:46 +0000

Someone on the marketing channel drops a looping GIF and asks if we can use it as an iPhone Lock Screen. Half the team is on Linux. The other half has never heard of a .livp file. Nobody wants to install another "GIF to Live Photo" Mac app for a one-off wallpaper request.

For a while my path was: find a cloud converter, upload the GIF, download something that might open on iPhone, AirDrop it, discover Photos rejected the package, try again. That was fine for memes. It was wrong the moment the GIF included unreleased UI or a client brand mark.

These days I convert GIF → Live Photo in the browser, preview the loop in the same tab, download a .livp, and only then AirDrop to the phone. No desktop app. No account. No "we delete uploads in 24h" promise I can't verify.

Why this shows up in frontend work

Live Photos are an Apple Photos format: a still JPEG paired with a short H.264 movie, tied together with a content identifier and a still-image-time track. Designers and PMs want them for:

Lock Screen / wallpaper motion from an existing GIF
iMessage shares that feel more "Photos" than "Giphy"
Reaction loops that should press-and-hold like a real Live Photo
Demo assets for iOS marketing that started life as a Slack GIF

It's almost never a product feature. It's a format bridge between "we already have a GIF" and "Photos will accept it." Wiring FFmpeg into the app for that is usually overkill.

The upload tax (again)

Most "GIF to Live Photo online" tools still POST the bytes. The UI looks local; the Network panel says otherwise. For anything from a private beta, client work, or staging UI, that's the wrong default.

What I want for this job:

Frames stay in the tab — decode → encode locally (WASM / FFmpeg-in-browser), then download
Preview before download — so I catch a broken loop before AirDrop
No signup before the download button works
A real .livp Photos can import — not a lone MOV with "hope for the best" metadata
Survives Offline in DevTools after the first WASM load

If convert dies the moment I flip Offline (after the runtime is cached), I close the tab.

A quick check before I trust the tool

Same habit as with HEIC converters:

// After dropping a redacted sample GIF and clicking Convert:
performance.getEntriesByType("resource")
  .filter((r) =>
    r.initiatorType === "fetch" ||
    r.initiatorType === "xmlhttprequest"
  )
  .map((r) => r.name);

Expect a one-time fetch for the WASM/FFmpeg core. Do not expect a POST of the GIF itself to some api.* host. Then flip Offline and convert again — if export still works, the bytes stayed local.

Always use a redacted sample first (no faces, no product chrome). Never validate the trust model with the real asset.

The loop I reuse

1. Redacted sample GIF first
2. Open a browser-local GIF → Live Photo tool
3. Drop → convert → preview the loop in-tab
4. Download .livp
5. AirDrop to iPhone → open from Files → save to Photos
6. Confirm press-and-hold motion + still look right
7. Close the tab, then run the real GIF

Under the hood the good tools encode frames to H.264, pair a JPEG still, stamp Apple's content identifier / still-image-time metadata, and zip that into .livp. You can roll your own with ffmpeg.wasm if this is a weekly pipeline. For "someone Slack'd a wallpaper GIF," a solid tab beats a side project.

When I need that tab fast, I've used Uwarp's GIF to Live Photo tool — drop the GIF, convert in the browser, preview, download .livp. Worth trying when you don't want an App Store install or another upload site in the critical path.

Tips that actually matter for wallpaper GIFs

Keep it short. Live Photos only play a few seconds; trim long GIFs first.
Prefer clean loops. A hard cut mid-motion looks worse after H.264 than a GIF that already looped cleanly.
Portrait or square for Lock Screen. Wide landscape memes waste the phone chrome.
Finish on device. AirDrop the .livp and open it on iPhone so Photos can register the paired still + movie. Don't expect Linux to "preview" a Live Photo the way Photos does.

When you should put this in the product

Sometimes the one-off habit is wrong:

Users upload GIFs and your iOS app must emit Live Photos at the API boundary
You're building a creator tool where Live Photo export is a checked feature
You need batch conversion with consistent CRF / duration caps

Then own the encode path (server or WASM), test the metadata, and don't paper over failures with "please use this random website." That's product work.

For internal wallpaper requests and marketing one-offs? Keep it out of the codebase. Convert once in a tab, AirDrop, move on.

DX note: agents and media uploads

If an agent is helping with asset pipelines, constrain it: browser-local convert or local FFmpeg; no third-party upload of product or client assets. Agents default to whichever cloud converter snippet ranks first — which is often the upload path you're trying to avoid. Paste the policy into the prompt the same way you'd paste a lint rule.

What I stopped doing

Installing a one-purpose Mac app for a single Lock Screen request
Uploading unreleased UI GIFs to the first Google result for "gif to live photo"
Shipping a lone MOV and hoping Photos treats it as a Live Photo
Asking the agent to "just host the GIF somewhere and convert it"

GIF → Live Photo is a packaging problem, not a collaboration problem. Fix it in the browser, verify on the phone, close the tab. If you want a concrete starting point, the GIF → Live Photo page on Uwarp is the one I've reached for when the team is mostly on Linux and nobody wants another desktop converter.

HEIC from iPhone in the browser — no desktop converter, no upload

Sherotree — Sat, 31 Oct 2026 13:00:48 +0000

I still get HEIC files dropped into Slack with a cheerful "can you resize this for the docs?" They look fine on the sender's Mac. They open as a mystery blob on my Linux box, and half the preview tools just shrug.

For a long time my default was: AirDrop to a Mac, open Preview, Export as JPEG, send it back. Or worse — upload to whichever "free HEIC converter" ranked first that week, wait for a download, hope the file wasn't sitting on someone else's disk. That worked until I started treating staging screenshots and unreleased UI as sensitive by default.

These days I convert HEIC → JPG in the browser and leave. No desktop app, no account, no "we delete in 24h" promise I can't audit.

Why HEIC shows up in frontend work

iPhones default to HEIC. Designers and PMs on iOS share photos that way without thinking. Frontend folks then need a JPG (or PNG) for:

Docs / Notion / GitHub markdown that won't render HEIC
Lighthouse / LCP samples where you want a boring baseline format
PR comments that reviewers can open on Windows or Linux
Tiny marketing crops that shouldn't require Photopea + an account

It's a one-off file job, not a product feature. That matters: the right fix is usually transform once and move on, not wire heic2any into the app.

The upload tax is the real bug

Most "HEIC to JPG online" tools still POST the bytes. Even when the UI feels local, the Network panel tells on them. For client UI, brand marks, or anything from a private beta, that's the wrong default.

What I want for this job:

File stays in the tab — FileReader / WASM / canvas, then URL.createObjectURL for download
No signup before the download button works
Survives Offline in DevTools (cheap litmus test)
Boring output — a real .jpg I can open in another tool, not a "close enough" re-encode with a surprise watermark

If step 3 fails, I close the tab.

A quick Offline check I actually run

Before I trust a converter with a real file:

// After dropping a redacted sample HEIC and clicking Convert:
performance.getEntriesByType("resource")
  .filter((r) =>
    r.initiatorType === "fetch" ||
    r.initiatorType === "xmlhttprequest"
  )
  .map((r) => r.name);

If convert fires a POST to some api.* host, it wasn't local. Flip Offline and try again — if export dies, same conclusion.

I keep a redacted sample HEIC (no faces, no product UI) for that first pass. Never test the trust model with the real asset.

Browser-local HEIC → JPG without a desktop app

The loop I reuse:

1. Redacted sample first
2. Open a browser-local HEIC→JPG tool
3. Drop file → convert → download JPG
4. Verify in a second app (Preview / feh / Photos)
5. Close the tab (don't leave the bytes in IndexedDB forever)
6. Only then run the real file

Under the hood the good tools are doing some flavor of decode → canvas/draw → toBlob('image/jpeg'). You can roll your own with a WASM decoder if this is a daily pipeline. For "someone Slack'd me three HEICs," a solid tab beats a side project.

When I need that tab fast, I've used Uwarp's HEIC to JPG tool — drop the file, convert in the browser, download. Worth trying when you don't want Preview, ImageMagick, or another upload site in the critical path.

When you should put HEIC support in the product

Sometimes the one-off habit is the wrong answer:

Users upload camera rolls and you must accept HEIC at the API boundary
You're building an editor that should round-trip EXIF / orientation
Marketing wants "works with iPhone photos" as a checked feature

Then own the decode path in the app (server-side or WASM), add tests for orientation, and don't paper over it with "please export as JPG first" copy. That's product work.

For internal docs and PR screenshots? Keep it out of the codebase. Convert once, commit the JPG, move on.

DX note: agents and HEIC

If an agent is helping with asset pipelines, don't ask it to "fix the HEIC" by inventing a random CDN upload. Give it a constrained prompt: browser-local convert or ImageMagick locally; no third-party upload of product assets. Agents default to whatever Stack Overflow snippet looks fastest — which is often the upload path you're trying to avoid.

What I stopped doing

AirDrop → Preview → Export as the only path on a Linux day
Pasting unreleased UI into the first Google result for "heic to jpg"
Trusting a green progress bar without checking the Network panel
Installing a one-purpose desktop converter for a job that finishes in a tab

HEIC from iPhone is a format mismatch, not a collaboration problem. Fix it in the browser, verify the JPG, close the tab. If you want a concrete starting point, the HEIC → JPG page on Uwarp is the one I've reached for when Preview isn't around.