BlueSky image bugs usually look like design problems: a preview is blurry, the crop cuts off the important part, a card thumbnail feels too zoomed in, or a multi-image layout makes a good graphic hard to read.
The actual cause is usually a mix of image dimensions, metadata, client layout rules, and the difference between an attached image and an external website card thumbnail.
BlueSky's post documentation explains image embeds, aspectRatio metadata, external website card embeds, and image limits.
Start with the official aspectRatio field
For image embeds, BlueSky records can include an aspectRatio object with width and height. The documentation says the exact dimensions do not need to be known; the important part is the ratio between width and height. If you do not know the actual ratio, it is better to omit the field than guess.
That matters because a wrong ratio can make clients reserve the wrong display space before the real image loads. The image might still upload, but the preview can feel jumpy, cropped, or visually off.
Use the right mental model for multi-image posts
A BlueSky post can contain up to four images, and each image can have its own alt text and aspect ratio. A one-image post can give the image more room. A two-, three-, or four-image post has to fit multiple assets into a smaller grid.
- One image: prioritize the strongest single composition and use the real aspect ratio.
- Two images: avoid mixing a very tall image with a very wide one unless cropping is acceptable.
- Three or four images: assume thumbnails will be smaller and keep important text away from edges.
- Charts, maps, comics, and screenshots: export versions that still read at thumbnail size.
Before scheduling image-heavy posts, run assets through the BlueSky image metadata and EXIF stripper and confirm the final export size, format, and privacy posture.
Why link card thumbnails crop differently
A website card is not the same as an attached image. External embeds store the URL, title, description, and optional thumbnail blob. The original page metadata and the client card layout decide how the card feels.
For link cards, make the Open Graph image simple: centered subject, readable type, no important words at the edges, and enough contrast at small sizes. Treat the social image as a thumbnail first and a poster second.
A safer visual publishing checklist
- Export the actual image dimensions before upload.
- Use the true width and height ratio when setting aspectRatio.
- Keep important text and faces away from the outer edges.
- Test link cards before launch day instead of minutes before posting.
- Use alt text for each attached image.
- Avoid relying on one cropped preview to carry critical safety, legal, or financial context.
Where ONYX fits
ONYX helps visual teams plan image posts inside a content calendar instead of rushing assets directly into the live composer. That gives reviewers time to check caption, alt text, visual crop risk, link card metadata, and post timing before publishing.
Pair this checklist with the BlueSky content calendar template when image posts need approval before they enter the active queue.
Schedule reviewed BlueSky visual posts with ONYX after the crop, card, alt text, and timing checks are complete.