# 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`:

```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)
```css
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)
```css
@container (min-width: 600px) { ... }
```
- Rejected: Limited browser support
- Rejected: Unnecessary complexity for this use case

### CSS Grid Approach (Rejected)
```css
.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