StarPunk/docs/design/v1.1.2-caption-alttext-update.md

Caption Display Update - Alt Text Only (v1.1.2)

Status

Superseded by media-display-fixes.md

This document contains an earlier approach to caption handling. The authoritative specification is now in media-display-fixes.md which provides a complete solution for media display including caption handling, CSS constraints, and homepage media.

Context

User has clarified that media captions should be used as alt text only, not displayed as visible <figcaption> elements in the note body.

Decision

Remove all visible caption display from templates while maintaining caption data for accessibility (alt text) purposes.

Required Changes

1. CSS Updates

File: /home/phil/Projects/starpunk/static/css/style.css

Remove: Lines related to figcaption styling (line 17 in the media CSS section)

/* REMOVE THIS LINE */
.note-media figcaption, .e-content figcaption { margin-top: var(--spacing-sm); font-size: 0.875rem; color: var(--color-text-light); font-style: italic; }

The remaining CSS should be:

/* Media Display Styles (v1.2.0) - Updated for alt-text only captions */
.note-media { margin-bottom: var(--spacing-md); }
.note-media img, .e-content img, .u-photo { max-width: 100%; height: auto; display: block; border-radius: var(--border-radius); }

/* 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)); }
}

2. Template Updates

File: /home/phil/Projects/starpunk/templates/note.html

Change: Lines 17-29 - Simplify media display structure

From:

{% if note.media %}
<div class="note-media">
  {% for item in note.media %}
  <figure class="media-item">
    <img src="{{ url_for('public.media_file', path=item.path) }}"
         alt="{{ item.caption or 'Image' }}"
         class="u-photo"
         width="{{ item.width }}"
         height="{{ item.height }}">
    {% if item.caption %}
    <figcaption>{{ item.caption }}</figcaption>
    {% endif %}
  </figure>
  {% endfor %}
</div>
{% endif %}

To:

{% if note.media %}
<div class="note-media">
  {% for item in note.media %}
  <div class="media-item">
    <img src="{{ url_for('public.media_file', path=item.path) }}"
         alt="{{ item.caption or 'Image' }}"
         class="u-photo"
         width="{{ item.width }}"
         height="{{ item.height }}">
  </div>
  {% endfor %}
</div>
{% endif %}

Changes:

• Replace <figure> with <div> (simpler, no semantic figure/caption relationship)
• Remove the {% if item.caption %} block and <figcaption> element entirely
• Keep caption in alt attribute for accessibility

File: /home/phil/Projects/starpunk/templates/index.html

Status: No changes needed

• Index template doesn't display media items in the preview
• Only shows truncated content

3. Feed Generators

Status: No changes needed

The feed generators already handle captions correctly:

• RSS, ATOM, and JSON Feed all use captions as alt text in <img> tags
• JSON Feed also includes captions in attachment metadata (correct behavior)

Current implementation (correct):

# In all feed generators
caption = media_item.get('caption', '')
content_html += f'<img src="{media_url}" alt="{caption}" />'

Rationale

1. Simplicity: Removing visible captions reduces visual clutter
2. Accessibility: Alt text provides necessary context for screen readers
3. User Intent: Captions are metadata, not content to be displayed
4. Clean Design: Images speak for themselves without redundant text

Implementation Checklist

• Update CSS to remove figcaption styles
• Update note.html template to remove figcaption elements
• Test with images that have captions
• Test with images without captions
• Verify alt text is properly set
• Test responsive layout still works
• Verify feed output unchanged

Testing Requirements

1. Visual Testing:

   • Confirm no caption text appears below images
   • Verify image layout unchanged
   • Test responsive behavior on mobile/desktop

2. Accessibility Testing:

   • Inspect HTML to confirm alt attributes are set
   • Test with screen reader to verify alt text is announced

3. Feed Testing:

   • Verify RSS/ATOM/JSON feeds still include alt text
   • Confirm JSON Feed attachments retain title field

Standards Compliance

• HTML: Valid use of img alt attribute
• Accessibility: WCAG 2.1 Level A compliance for images
• IndieWeb: Maintains u-photo microformat class
• Progressive Enhancement: Images functional without CSS