StarPunk/docs/design/v1.2.0-media-css-design.md

CSS Design for Media Display (v1.2.0)

Status

Superseded by media-display-fixes.md

This document contains an earlier design iteration. The authoritative specification is now in media-display-fixes.md which provides a more comprehensive solution including template refactoring and consistent media display across all pages.

Problem Statement

Images uploaded via the media upload feature display at full resolution, breaking layout bounds and creating poor user experience. Need CSS rules to constrain and style images appropriately.

Design Decision

CSS Rules to Add

Add the following CSS rules after line 49 (after .empty-state rules) in /home/phil/Projects/starpunk/static/css/style.css:

/* Media Display Styles (v1.2.0) */
.note-media { margin-bottom: var(--spacing-md); }
.note-media figure, .e-content figure { margin: 0 0 var(--spacing-md) 0; }
.note-media img, .e-content img, .u-photo { max-width: 100%; height: auto; display: block; border-radius: var(--border-radius); }
.note-media figcaption, .e-content figcaption { margin-top: var(--spacing-sm); font-size: 0.875rem; color: var(--color-text-light); font-style: italic; }

/* Multiple media items grid */
.note-media { display: flex; flex-wrap: wrap; gap: var(--spacing-md); }
.note-media .media-item { flex: 1 1 100%; }

/* Desktop: side-by-side for multiple images */
@media (min-width: 768px) {
  .note-media .media-item:only-child { flex: 1 1 100%; }
  .note-media .media-item:not(:only-child) { flex: 1 1 calc(50% - var(--spacing-sm)); }
}

Rationale

1. Responsive Image Constraints

• max-width: 100% ensures images never exceed container width
• height: auto maintains aspect ratio
• display: block removes inline spacing issues
• Works with existing HTML width and height attributes for proper aspect ratio hints

2. Consistent Visual Design

• border-radius: var(--border-radius) matches existing design system (4px)
• Uses existing spacing variables for consistent margins
• Caption styling matches .note-meta text style (0.875rem, light gray)

3. Flexible Layout

• Single images take full width
• Multiple images display in a responsive grid
• Mobile: stacked vertically (100% width each)
• Desktop: two columns for multiple images (50% width each)
• Flexbox with gap provides clean spacing

4. Scope Coverage

• .note-media img - images in the media section
• .e-content img - images in markdown content
• .u-photo - microformats photo class (covers both media and author photos)
• Applies to both figure and standalone img elements

5. Performance Considerations

• No complex calculations or transforms
• Leverages browser native image sizing
• Uses existing CSS variables (no new computations)
• Respects HTML width/height attributes for layout stability

Alternative Approaches Considered

Object-fit Approach (Rejected)

img { object-fit: cover; width: 100%; height: 400px; }

• Rejected: Crops images, losing content
• Rejected: Fixed height doesn't work for varied aspect ratios

Container Query Approach (Rejected)

@container (min-width: 600px) { ... }

• Rejected: Limited browser support
• Rejected: Unnecessary complexity for this use case

CSS Grid Approach (Rejected)

.note-media { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }

• Rejected: More complex than needed
• Rejected: Less flexible for single vs multiple images

Implementation Notes

1. Location in style.css: Insert after line 49, before .form-group rules

2. Testing Required:

   • Single image display
   • Multiple images (2, 3, 4 images)
   • Portrait and landscape orientations
   • Mobile and desktop viewports
   • Images in markdown content
   • Author avatar photos

3. Browser Compatibility: All rules use widely supported CSS features (flexbox, max-width, CSS variables)

4. Future Enhancements (not for v1.2.0):

   • Lightbox/modal for full-size viewing
   • Lazy loading optimization
   • WebP format support
   • Image galleries with thumbnails

Standards Compliance

• IndieWeb: Preserves .u-photo microformat class
• Accessibility: Maintains alt text display, proper figure/figcaption semantics
• Performance: No JavaScript required, pure CSS solution
• Progressive Enhancement: Images remain functional without CSS