Skip to content

Comments

Image management#312

Open
isaaclombardssw wants to merge 13 commits intomainfrom
image-management
Open

Image management#312
isaaclombardssw wants to merge 13 commits intomainfrom
image-management

Conversation

@isaaclombardssw
Copy link
Collaborator

@isaaclombardssw isaaclombardssw commented Feb 11, 2026

Summary

  • Implement build-time image dimension injection via image-size to eliminate Cumulative Layout Shift (CLS) for documentation images
  • Create unified TinaImage component with loading skeleton, error state, and optional lightbox
  • Migrate accordion image fields from plain strings to ImageMetadata objects with auto-captured dimensions via a custom TinaCMS field
  • Add descriptive alt text to existing content images for accessibility
  • Refactor lightbox overlay to correctly proxy TinaCloud CDN URLs through Next.js /_next/image

How it works

At build time, the server component walks the TinaCMS rich-text AST, finds img nodes pointing to local files in public/, reads their dimensions from disk using the image-size library, and injects width/height into the AST. The client-side ImageComponent renders with explicit dimensions when available, falling back to fill mode with a 16:9 aspect ratio container during live CMS editing or for external images.

For accordion components, a new custom TinaCMS field (ImageWithMetadataField) auto-captures image dimensions on upload in the CMS editor, storing them alongside the image path.

Key files

  • src/utils/docs/imageAugmentation.ts - Build-time dimension injection
  • src/components/ui/tina-image.tsx - Unified image component
  • src/utils/image-path.ts - Shared path resolution utilities
  • tina/customFields/image-with-metadata.tsx - CMS field with auto-dimension capture
  • src/components/tina-markdown/standard-elements/image.tsx - Markdown image renderer

Test plan

  • Verify images render with correct dimensions on all doc pages (no CLS)
  • Verify lightbox works for both local and TinaCloud CDN images
  • Verify accordion images display correctly
  • Test live CMS editing — images should fall back to fill mode gracefully
  • Run pnpm build to confirm no build errors
  • Run pnpm lint and npx tsc --noEmit

🤖 Generated with Claude Code

- Image management docs, components, and utilities
- Preloaded image embed, tina-image component, error state
- Image metadata collection and custom field
- Migration and cleanup scripts
@vercel
Copy link

vercel bot commented Feb 11, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
tina-docs Ready Ready Preview, Comment Feb 23, 2026 11:42pm

Request Review

…ack, fix Biome lint

- Split ImageComponent into two render paths (explicit dimensions vs fill fallback)
- Add min-height: 200px to fill container so it never collapses to 0
- Remove debug console.log from imageAugmentation
- Fix all Biome lint errors (import sorting, formatting)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Handle TinaCloud CDN URLs (assets.tina.io) by extracting the path
  portion and resolving against local public/ directory
- Add h-full to lightbox button so fill images have unbroken height chain

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…l URLs

- Revert h-full on lightbox button (was breaking accordion layout)
- Use padding-bottom: 56.25% for fill container instead of aspect-ratio
  (gives real height without relying on h-full chain)
- Fix lightbox loader to not append query params to external URLs
  (TinaCloud URLs were failing to load with unknown params)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
External URLs (TinaCloud) now omit the custom loader so Next.js routes
them through /_next/image, matching how inline images work. Custom loader
only used for local images.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove unused ImageWithMetadata export and default export from image-metadata.tsx
- Remove unused size prop from ImageErrorState (only "small" was ever used)
- Remove dead ImageMetadata re-export from tina-image.tsx
- Clean up scripts/README.md: remove stale preloadedImage and cleanup-backups docs
- Add TinaCloud URL coupling comments to imageAugmentation.ts
- Update README.md and CLAUDE.md with TinaCloud URL handling docs
- Remove broken image reference from deploying-your-docs.mdx

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Migration has already been run — accordion/showcase images are converted.
The script and its README docs are no longer needed.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Replace hand-rolled image dimension parser with `image-size` library
- Move imageAugmentation.ts from utils/docs/navigation/ to utils/docs/
- Revert scroll-showcase changes (not part of this PR's scope)
- Revert TinaImage usage in error-wrapper and navbar-logo (UI chrome)
- Revert text-components.mdx copy change and README image section
- Fix docs-navigation-bar.json broken indentation
- Add tsconfig.tsbuildinfo to .gitignore

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

🐛 Bug - Image Not Loading on Expand

1 participant