# How I made Astro figures size themselves and enlarge on tap — intrinsic width, a native dialog, and @2x
> Why width:100% blurred a 256px screenshot in Astro, and how a native dialog made every diagram readable on a phone. Seven measurements corrected the design.
- Source: https://oharu121.com/blog/astro-figure-intrinsic-width-native-dialog-2x-density/
- Published: 2026-08-15T09:17:03+09:00
- Tags: Astro, CSS, Web API
---
## Introduction
I dropped a screenshot of this site's own table-of-contents sidebar into an article, and it came back looking terrible. The sidebar is a narrow strip of UI, and in the article it had been blown up to the full width of the reading column, soft enough that the text inside it was fuzzy, and tall enough to push everything else off the screen. While I was looking at it I noticed the other half of the problem: there was no way to make any figure bigger. If a reader wanted a closer look, the only thing available was pinching the whole page.
That screenshot had been live for an entire release and nothing had reported it. Nothing was wrong with the capture either. **The blur came from one CSS declaration applied to every figure on the site**, and the narrow ones were the only place it did any damage.
Fixing the blur turned out to be the small half. The bigger finding was on the other side of the same component: **the figures that had never been stretched, and therefore looked fine, were the ones nobody could read.** This article covers both, and the seven design decisions along the way that felt obviously right and were measurably wrong.
## One declaration stretched every figure to the column
Every figure on this site goes through one component, and that component had a single rule for whatever it wrapped:
```css title="src/components/article/Figure.astro"
.frame :global(svg),
.frame :global(img) {
display: block;
width: 100%;
height: auto;
}
```
For most of the corpus this is invisible. The illustrations are 1,100 to 1,774 pixels wide and the reading column is 662, so **the rule only ever scales them down, which costs nothing.** The sidebar screenshot was **256 pixels wide and 836 tall**, so the same rule stretched it 2.48 times, to 662 by 2,161.
The interesting part is what the browser had to work with. Astro generates a `srcset` from the source file, and a 256-pixel source produces exactly one candidate:
```html
```
**So the browser downloaded 256 pixels of image, was told by CSS to fill 662 pixels of layout, and had nothing larger to fetch.** On the laptop I was looking at it on, with a device pixel ratio of 2, the real budget was 1,324 device pixels covered by 256 real ones.
*Figure — StretchedRaster: The same file under both rules. The bars are the rendered width; the line underneath each is the number that decides whether it looks sharp.*
**Nothing in the repository was watching for this.** The cross-locale check confirms that a figure referenced in English is also referenced in Japanese and Traditional Chinese; it never looks at the file. The figure-fit check renders each diagram in a browser and measures whether its labels overflow their boxes, but it only measures the SVG components, because those are the ones with translated text in them. **A raster had no check of its own, so the only thing standing between a stretched screenshot and production was somebody noticing.**
## Deriving the size instead of declaring it
The fix is smaller than the bug. Astro emits `width` and `height` attributes on every image it processes, because it knows the file's real dimensions at build time. Setting the CSS width to `auto` makes the browser use that number:
```css title="src/components/article/Figure.astro"
.frame :global(img) {
display: block;
margin-inline: auto;
width: auto;
max-width: 100%;
max-height: 56rem;
height: auto;
}
```
The alternative was a `width` prop on the component, which I turned down. This blog keeps one folder per article with three locale files in it, so a width in the markup is a number that has to be written three times and kept in step with the asset by hand, and the consistency checker would need a new rule to police it. With `width: auto` **the file is the only place the size is recorded**, and replacing the file moves the layout with it.
The height cap was the first thing to go wrong. The agent's initial value was `min(48rem, 85svh)`, on the reasoning that a figure should never be taller than the window. Measured on a browser window 724 pixels tall, that clamped the 256-wide screenshot to **188 by 615**, which is to say it resampled an image that had just been fixed for being resampled. **A cap that tracks the viewport turns "never upscale" back into "always resize".** The value is now a flat `56rem`, which clears the tallest figure in the corpus at 836 pixels and still catches a pathological export.
One last piece was cosmetic. A 224-pixel screenshot centred in a 662-pixel bordered box reads as a mistake, so the frame shrink-wraps a raster. The component receives its contents through a slot and cannot know on the server whether it wrapped a picture or a diagram, so the test happens in CSS:
```css title="src/components/article/Figure.astro"
.figure:has(.frame img) .frame {
width: fit-content;
max-width: 100%;
margin-inline: auto;
}
```
## `@2x`, because `width: auto` cannot tell dense from big
Sizing from the intrinsic width leaves one thing unresolved. **A 448-pixel file meant to be a 224-pixel screenshot at double density is indistinguishable, to CSS, from a 448-pixel picture that wants to be 448 pixels wide.** The signal has to come from somewhere else, and the cheapest place is the filename: a raster named `@2x.webp` is stored at twice its intended size, and the component halves it with `zoom: 0.5`.
Two things in that rule were found by measurement rather than by reasoning, and both were silent.
The selector needs to match twice. `astro build` writes the stem into the asset name verbatim, producing `/_astro/sidebar-rail@2x.HASH.webp`, but the dev server routes images through an endpoint with the path as a query parameter, where **the `@` is percent-encoded to `%402x`.** A rule matching only the raw form works in production and does nothing at all locally, which is the worst arrangement available. It was written that way first, and **the reason it got caught is that the number in the browser did not move.**
The two caps then behave differently under `zoom`, which is why one is doubled and the other is not:
| Declared | Where it actually clamps |
| --- | --- |
| `max-height: 56rem` | 448 pixels of screen. Absolute lengths are in the element's own halved pixels, so the cap lands at half of what it says. |
| `max-width: 100%` | The frame's real width. Percentages resolve against the containing block, which is not zoomed, so they already mean what they say. |
The first attempt doubled both. **They do not behave alike, and the cost was an image overflowing a squeezed frame by 70 pixels.** With the rule working I asked for the original screenshot to be retaken at double resolution: it is now 448 by 1,672, draws at 224 by 836, and covers its 448 device pixels with 448 real ones.
## The figures that looked fine were the unreadable ones
That is the sizing story, and it affected exactly one file badly. The other half of the work started when the agent proposed showing the enlarge affordance only where a figure was actually being shrunk, on the reasoning that offering to enlarge something already at full size promises the reader nothing.
I rejected that. **A figure can be at full size and still have text in it too small to read**, and that applies at least as much to the diagrams as to the screenshots. It is worth showing the arithmetic that settled it, because it is the number the rest of the article rests on.
Every diagram in this repo is authored on an 800-unit `viewBox` and rendered into the same 662-pixel frame as everything else. That is a scale of 0.795 on a desktop. On a 390-pixel phone the frame is 324 pixels wide, which is a scale of 0.405. Running through the label sizes actually used across the corpus:
| Authored `font-size` | Uses | Desktop (0.795×) | Phone (0.405×) |
| --- | --- | --- | --- |
| `9px` | 20 | 7.2 CSS px | **3.6 CSS px** |
| `10px` | 136 | 8.0 CSS px | **4.1 CSS px** |
| `11px` | 135 | 8.7 CSS px | **4.5 CSS px** |
| `13px` | 78 | 10.3 CSS px | **5.3 CSS px** |
The diagrams are the most carefully made things on this site, and on a phone their labels render between three and a half and five pixels tall. **A gate keyed to "is this being shrunk" would have hidden the affordance from exactly them, because a diagram is never shrunk.** It is scaled, and scaling is what makes it illegible.
So the enlarge behaviour went universal: every figure opens, raster and diagram alike, at every viewport. **That decision is what turned a fix for one blurry screenshot into a change affecting all 86 figures on the site, in three languages.**
*Figure — ScaleCollapse: The same diagram at each size it is asked to be. The rightmost card is what opening it restores, and the rest of the article is about getting there.*
## The dialog needed two rules, not one
The site already had the pattern. The search modal is a native `
```
**So the browser downloaded 256 pixels of image, was told by CSS to fill 662 pixels of layout, and had nothing larger to fetch.** On the laptop I was looking at it on, with a device pixel ratio of 2, the real budget was 1,324 device pixels covered by 256 real ones.
*Figure — StretchedRaster: The same file under both rules. The bars are the rendered width; the line underneath each is the number that decides whether it looks sharp.*
**Nothing in the repository was watching for this.** The cross-locale check confirms that a figure referenced in English is also referenced in Japanese and Traditional Chinese; it never looks at the file. The figure-fit check renders each diagram in a browser and measures whether its labels overflow their boxes, but it only measures the SVG components, because those are the ones with translated text in them. **A raster had no check of its own, so the only thing standing between a stretched screenshot and production was somebody noticing.**
## Deriving the size instead of declaring it
The fix is smaller than the bug. Astro emits `width` and `height` attributes on every image it processes, because it knows the file's real dimensions at build time. Setting the CSS width to `auto` makes the browser use that number:
```css title="src/components/article/Figure.astro"
.frame :global(img) {
display: block;
margin-inline: auto;
width: auto;
max-width: 100%;
max-height: 56rem;
height: auto;
}
```
The alternative was a `width` prop on the component, which I turned down. This blog keeps one folder per article with three locale files in it, so a width in the markup is a number that has to be written three times and kept in step with the asset by hand, and the consistency checker would need a new rule to police it. With `width: auto` **the file is the only place the size is recorded**, and replacing the file moves the layout with it.
The height cap was the first thing to go wrong. The agent's initial value was `min(48rem, 85svh)`, on the reasoning that a figure should never be taller than the window. Measured on a browser window 724 pixels tall, that clamped the 256-wide screenshot to **188 by 615**, which is to say it resampled an image that had just been fixed for being resampled. **A cap that tracks the viewport turns "never upscale" back into "always resize".** The value is now a flat `56rem`, which clears the tallest figure in the corpus at 836 pixels and still catches a pathological export.
One last piece was cosmetic. A 224-pixel screenshot centred in a 662-pixel bordered box reads as a mistake, so the frame shrink-wraps a raster. The component receives its contents through a slot and cannot know on the server whether it wrapped a picture or a diagram, so the test happens in CSS:
```css title="src/components/article/Figure.astro"
.figure:has(.frame img) .frame {
width: fit-content;
max-width: 100%;
margin-inline: auto;
}
```
## `@2x`, because `width: auto` cannot tell dense from big
Sizing from the intrinsic width leaves one thing unresolved. **A 448-pixel file meant to be a 224-pixel screenshot at double density is indistinguishable, to CSS, from a 448-pixel picture that wants to be 448 pixels wide.** The signal has to come from somewhere else, and the cheapest place is the filename: a raster named `