feat: add alt text support for gallery images

- Two-step gallery creation flow (title/description → image descriptions)
- New image descriptions page with grain-textarea for alt text entry
- ALT badge component displayed on images with alt text
- Clicking badge shows overlay with alt text over the image
- Overlay dismisses on click or carousel scroll
- Keyboard accessible (button element with aria-label)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

src/components/atoms/grain-alt-badge.js

···
+import { LitElement, html, css } from 'lit';
+
+export class GrainAltBadge extends LitElement {
+  static properties = {
+    alt: { type: String },
+    _showOverlay: { state: true }
+  };
+
+  static styles = css`
+    :host {
+      position: absolute;
+      bottom: 8px;
+      right: 8px;
+      z-index: 2;
+    }
+    .badge {
+      background: rgba(0, 0, 0, 0.7);
+      color: white;
+      font-size: 10px;
+      font-weight: 600;
+      padding: 2px 4px;
+      border-radius: 4px;
+      cursor: pointer;
+      user-select: none;
+      border: none;
+      font-family: inherit;
+    }
+    .badge:hover {
+      background: rgba(0, 0, 0, 0.85);
+    }
+    .badge:focus {
+      outline: 2px solid white;
+      outline-offset: 1px;
+    }
+    .overlay {
+      position: absolute;
+      bottom: 8px;
+      right: 8px;
+      left: -8px;
+      top: -8px;
+      transform: translate(-100%, -100%);
+      transform: none;
+      bottom: 0;
+      right: 0;
+      left: 0;
+      top: 0;
+      position: fixed;
+      background: rgba(0, 0, 0, 0.75);
+      color: white;
+      padding: 16px;
+      font-size: 14px;
+      line-height: 1.5;
+      overflow-y: auto;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      text-align: center;
+      box-sizing: border-box;
+    }
+  `;
+
+  #scrollHandler = null;
+  #carousel = null;
+
+  constructor() {
+    super();
+    this.alt = '';
+    this._showOverlay = false;
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#removeScrollListener();
+  }
+
+  #handleClick(e) {
+    e.stopPropagation();
+    this._showOverlay = !this._showOverlay;
+  }
+
+  #handleOverlayClick(e) {
+    e.stopPropagation();
+    this._showOverlay = false;
+  }
+
+  #removeScrollListener() {
+    if (this.#scrollHandler && this.#carousel) {
+      this.#carousel.removeEventListener('scroll', this.#scrollHandler);
+      this.#scrollHandler = null;
+      this.#carousel = null;
+    }
+  }
+
+  updated(changedProperties) {
+    if (changedProperties.has('_showOverlay')) {
+      if (this._showOverlay) {
+        // Position overlay to cover the parent slide
+        const slide = this.closest('.slide');
+        if (slide) {
+          const rect = slide.getBoundingClientRect();
+          const overlay = this.shadowRoot.querySelector('.overlay');
+          if (overlay) {
+            overlay.style.top = `${rect.top}px`;
+            overlay.style.left = `${rect.left}px`;
+            overlay.style.width = `${rect.width}px`;
+            overlay.style.height = `${rect.height}px`;
+          }
+
+          // Listen for carousel scroll to dismiss overlay
+          this.#carousel = slide.parentElement;
+          if (this.#carousel) {
+            this.#scrollHandler = () => {
+              this._showOverlay = false;
+            };
+            this.#carousel.addEventListener('scroll', this.#scrollHandler, { passive: true });
+          }
+        }
+      } else {
+        this.#removeScrollListener();
+      }
+    }
+  }
+
+  render() {
+    if (!this.alt) return null;
+
+    return html`
+      <button class="badge" @click=${this.#handleClick} aria-label="View image description">ALT</button>
+      ${this._showOverlay ? html`
+        <div class="overlay" @click=${this.#handleOverlayClick}>
+          ${this.alt}
+        </div>
+      ` : ''}
+    `;
+  }
+}
+
+customElements.define('grain-alt-badge', GrainAltBadge);

src/components/organisms/grain-image-carousel.js

···
 import { LitElement, html, css } from 'lit';
 import '../atoms/grain-image.js';
 import '../atoms/grain-icon.js';
+import '../atoms/grain-alt-badge.js';
 import '../molecules/grain-carousel-dots.js';
 
 export class GrainImageCarousel extends LitElement {
···
     .slide {
       flex: 0 0 100%;
       scroll-snap-align: start;
+      position: relative;
     }
     .slide.centered {
       display: flex;
···
               aspectRatio=${photo.aspectRatio || 1}
               style=${index === 0 && this.rkey ? `view-transition-name: gallery-hero-${this.rkey};` : ''}
             ></grain-image>
+            ${photo.alt ? html`<grain-alt-badge .alt=${photo.alt}></grain-alt-badge>` : ''}
           </div>
         `)}
       </div>

src/components/pages/grain-app.js

···
 import './grain-settings.js';
 import './grain-edit-profile.js';
 import './grain-create-gallery.js';
+import './grain-image-descriptions.js';
 import './grain-explore.js';
 import './grain-notifications.js';
 import './grain-terms.js';
···
       .register('/legal/privacy', 'grain-privacy')
       .register('/legal/copyright', 'grain-copyright')
       .register('/create', 'grain-create-gallery')
+      .register('/create/descriptions', 'grain-image-descriptions')
       .register('/explore', 'grain-explore')
       .register('/notifications', 'grain-notifications')
       .register('*', 'grain-timeline')

src/components/pages/grain-create-gallery.js

···
 import { router } from '../../router.js';
 import { auth } from '../../services/auth.js';
 import { draftGallery } from '../../services/draft-gallery.js';
-import { parseTextToFacets } from '../../lib/richtext.js';
-import { grainApi } from '../../services/grain-api.js';
 import '../atoms/grain-icon.js';
 import '../atoms/grain-button.js';
 import '../atoms/grain-input.js';
 import '../atoms/grain-textarea.js';
 import '../molecules/grain-form-field.js';
 
-const UPLOAD_BLOB_MUTATION = `
-  mutation UploadBlob($data: String!, $mimeType: String!) {
-    uploadBlob(data: $data, mimeType: $mimeType) {
-      ref
-      mimeType
-      size
-    }
-  }
-`;
-
-const CREATE_PHOTO_MUTATION = `
-  mutation CreatePhoto($input: SocialGrainPhotoInput!) {
-    createSocialGrainPhoto(input: $input) {
-      uri
-    }
-  }
-`;
-
-const CREATE_GALLERY_MUTATION = `
-  mutation CreateGallery($input: SocialGrainGalleryInput!) {
-    createSocialGrainGallery(input: $input) {
-      uri
-    }
-  }
-`;
-
-const CREATE_GALLERY_ITEM_MUTATION = `
-  mutation CreateGalleryItem($input: SocialGrainGalleryItemInput!) {
-    createSocialGrainGalleryItem(input: $input) {
-      uri
-    }
-  }
-`;
-
 export class GrainCreateGallery extends LitElement {
   static properties = {
     _photos: { state: true },
     _title: { state: true },
-    _description: { state: true },
-    _posting: { state: true },
-    _error: { state: true }
+    _description: { state: true }
   };
 
   static styles = css`
···
     .form {
       padding: var(--space-sm);
     }
-    .error {
-      color: #ff4444;
-      padding: var(--space-sm);
-      text-align: center;
-    }
   `;
 
   constructor() {
···
     this._photos = [];
     this._title = '';
     this._description = '';
-    this._posting = false;
-    this._error = null;
   }
 
   connectedCallback() {
     super.connectedCallback();
 
-    // Redirect to timeline if not authenticated
     if (!auth.isAuthenticated) {
       router.replace('/');
       return;
     }
 
     this._photos = draftGallery.getPhotos();
+
+    // Restore title/description if returning from descriptions page
+    this._title = sessionStorage.getItem('draft_title') || '';
+    this._description = sessionStorage.getItem('draft_description') || '';
+
     if (!this._photos.length) {
       router.push('/');
     }
···
   #handleBack() {
     if (confirm('Discard this gallery?')) {
       draftGallery.clear();
+      sessionStorage.removeItem('draft_title');
+      sessionStorage.removeItem('draft_description');
       history.back();
     }
   }
 
   #removePhoto(index) {
     this._photos = this._photos.filter((_, i) => i !== index);
+    draftGallery.setPhotos(this._photos);
     if (this._photos.length === 0) {
       draftGallery.clear();
+      sessionStorage.removeItem('draft_title');
+      sessionStorage.removeItem('draft_description');
       router.push('/');
     }
   }
···
     this._description = e.detail.value.slice(0, 1000);
   }
 
-  get #canPost() {
-    return this._title.trim().length > 0 && this._photos.length > 0 && !this._posting;
+  get #canProceed() {
+    return this._title.trim().length > 0 && this._photos.length > 0;
   }
 
-  async #handlePost() {
-    if (!this.#canPost) return;
-
-    this._posting = true;
-    this._error = null;
+  #handleNext() {
+    if (!this.#canProceed) return;
 
-    try {
-      const client = auth.getClient();
-      const now = new Date().toISOString();
+    sessionStorage.setItem('draft_title', this._title);
+    sessionStorage.setItem('draft_description', this._description);
+    draftGallery.setPhotos(this._photos);
 
-      // Upload photos and create photo records
-      const photoUris = [];
-      for (const photo of this._photos) {
-        // Upload blob
-        const base64Data = photo.dataUrl.split(',')[1];
-        const uploadResult = await client.mutate(UPLOAD_BLOB_MUTATION, {
-          data: base64Data,
-          mimeType: 'image/jpeg'
-        });
-
-        if (!uploadResult.uploadBlob) {
-          throw new Error('Failed to upload image');
-        }
-
-        // Create photo record
-        const photoResult = await client.mutate(CREATE_PHOTO_MUTATION, {
-          input: {
-            photo: {
-              $type: 'blob',
-              ref: { $link: uploadResult.uploadBlob.ref },
-              mimeType: uploadResult.uploadBlob.mimeType,
-              size: uploadResult.uploadBlob.size
-            },
-            aspectRatio: {
-              width: photo.width,
-              height: photo.height
-            },
-            createdAt: now
-          }
-        });
-
-        photoUris.push(photoResult.createSocialGrainPhoto.uri);
-      }
-
-      // Parse description for facets
-      let facets = null;
-      if (this._description.trim()) {
-        const resolveHandle = async (handle) => grainApi.resolveHandle(handle);
-        const parsed = await parseTextToFacets(this._description.trim(), resolveHandle);
-        if (parsed.facets.length > 0) {
-          facets = parsed.facets;
-        }
-      }
-
-      // Create gallery record
-      const galleryResult = await client.mutate(CREATE_GALLERY_MUTATION, {
-        input: {
-          title: this._title.trim(),
-          ...(this._description.trim() && { description: this._description.trim() }),
-          ...(facets && { facets }),
-          createdAt: now
-        }
-      });
-
-      const galleryUri = galleryResult.createSocialGrainGallery.uri;
-
-      // Create gallery items linking photos to gallery
-      for (let i = 0; i < photoUris.length; i++) {
-        await client.mutate(CREATE_GALLERY_ITEM_MUTATION, {
-          input: {
-            gallery: galleryUri,
-            item: photoUris[i],
-            position: i,
-            createdAt: now
-          }
-        });
-      }
-
-      // Clear draft and navigate to new gallery
-      draftGallery.clear();
-      const rkey = galleryUri.split('/').pop();
-      router.push(`/profile/${auth.user.handle}/gallery/${rkey}`);
-
-    } catch (err) {
-      console.error('Failed to create gallery:', err);
-      this._error = err.message || 'Failed to create gallery. Please try again.';
-    } finally {
-      this._posting = false;
-    }
+    router.push('/create/descriptions');
   }
 
   render() {
···
           <span class="header-title">Create a gallery</span>
         </div>
         <grain-button
-          ?disabled=${!this.#canPost}
-          ?loading=${this._posting}
-          loadingText="Posting..."
-          @click=${this.#handlePost}
-        >Post</grain-button>
+          ?disabled=${!this.#canProceed}
+          @click=${this.#handleNext}
+        >Next</grain-button>
       </div>
 
       <div class="photo-strip">
···
           </div>
         `)}
       </div>
-
-      ${this._error ? html`<p class="error">${this._error}</p>` : ''}
 
       <div class="form">
         <grain-form-field .value=${this._title} .maxlength=${100}>

src/components/pages/grain-image-descriptions.js

···
+import { LitElement, html, css } from 'lit';
+import { router } from '../../router.js';
+import { auth } from '../../services/auth.js';
+import { draftGallery } from '../../services/draft-gallery.js';
+import { parseTextToFacets } from '../../lib/richtext.js';
+import { grainApi } from '../../services/grain-api.js';
+import '../atoms/grain-icon.js';
+import '../atoms/grain-button.js';
+import '../atoms/grain-textarea.js';
+
+const UPLOAD_BLOB_MUTATION = `
+  mutation UploadBlob($data: String!, $mimeType: String!) {
+    uploadBlob(data: $data, mimeType: $mimeType) {
+      ref
+      mimeType
+      size
+    }
+  }
+`;
+
+const CREATE_PHOTO_MUTATION = `
+  mutation CreatePhoto($input: SocialGrainPhotoInput!) {
+    createSocialGrainPhoto(input: $input) {
+      uri
+    }
+  }
+`;
+
+const CREATE_GALLERY_MUTATION = `
+  mutation CreateGallery($input: SocialGrainGalleryInput!) {
+    createSocialGrainGallery(input: $input) {
+      uri
+    }
+  }
+`;
+
+const CREATE_GALLERY_ITEM_MUTATION = `
+  mutation CreateGalleryItem($input: SocialGrainGalleryItemInput!) {
+    createSocialGrainGalleryItem(input: $input) {
+      uri
+    }
+  }
+`;
+
+export class GrainImageDescriptions extends LitElement {
+  static properties = {
+    _photos: { state: true },
+    _title: { state: true },
+    _description: { state: true },
+    _posting: { state: true },
+    _error: { state: true }
+  };
+
+  static styles = css`
+    :host {
+      display: block;
+      width: 100%;
+      max-width: var(--feed-max-width);
+      min-height: 100%;
+      background: var(--color-bg-primary);
+      align-self: center;
+    }
+    .header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: var(--space-sm);
+      border-bottom: 1px solid var(--color-border);
+    }
+    .header-left {
+      display: flex;
+      align-items: center;
+      gap: var(--space-xs);
+    }
+    .back-button {
+      background: none;
+      border: none;
+      padding: 8px;
+      margin-left: -8px;
+      cursor: pointer;
+      color: var(--color-text-primary);
+    }
+    .header-title {
+      font-size: var(--font-size-md);
+      font-weight: 600;
+    }
+    .photo-list {
+      padding: var(--space-sm);
+    }
+    .photo-row {
+      display: flex;
+      gap: var(--space-sm);
+      margin-bottom: var(--space-md);
+    }
+    .photo-thumb {
+      flex-shrink: 0;
+      max-width: 80px;
+      max-height: 120px;
+      width: auto;
+      height: auto;
+      border-radius: 4px;
+      object-fit: contain;
+    }
+    .info {
+      margin: 0;
+      padding: var(--space-sm);
+      font-size: var(--font-size-sm);
+      color: var(--color-text-secondary);
+      border-bottom: 1px solid var(--color-border);
+    }
+    .alt-input {
+      flex: 1;
+    }
+    .alt-input grain-textarea {
+      --textarea-min-height: 60px;
+    }
+    .alt-input grain-textarea::part(textarea) {
+      min-height: 60px;
+    }
+    .error {
+      color: #ff4444;
+      padding: var(--space-sm);
+      text-align: center;
+    }
+  `;
+
+  constructor() {
+    super();
+    this._photos = [];
+    this._title = '';
+    this._description = '';
+    this._posting = false;
+    this._error = null;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    if (!auth.isAuthenticated) {
+      router.replace('/');
+      return;
+    }
+
+    this._photos = draftGallery.getPhotos();
+    this._title = sessionStorage.getItem('draft_title') || '';
+    this._description = sessionStorage.getItem('draft_description') || '';
+
+    if (!this._photos.length) {
+      router.push('/');
+    }
+  }
+
+  #handleBack() {
+    router.push('/create');
+  }
+
+  #handleAltChange(index, e) {
+    const alt = e.detail.value;
+    draftGallery.updatePhotoAlt(index, alt);
+    this._photos = [...draftGallery.getPhotos()];
+  }
+
+  async #handlePost() {
+    if (this._posting) return;
+
+    this._posting = true;
+    this._error = null;
+
+    try {
+      const client = auth.getClient();
+      const now = new Date().toISOString();
+
+      const photoUris = [];
+      for (const photo of this._photos) {
+        const base64Data = photo.dataUrl.split(',')[1];
+        const uploadResult = await client.mutate(UPLOAD_BLOB_MUTATION, {
+          data: base64Data,
+          mimeType: 'image/jpeg'
+        });
+
+        if (!uploadResult.uploadBlob) {
+          throw new Error('Failed to upload image');
+        }
+
+        const photoResult = await client.mutate(CREATE_PHOTO_MUTATION, {
+          input: {
+            photo: {
+              $type: 'blob',
+              ref: { $link: uploadResult.uploadBlob.ref },
+              mimeType: uploadResult.uploadBlob.mimeType,
+              size: uploadResult.uploadBlob.size
+            },
+            aspectRatio: {
+              width: photo.width,
+              height: photo.height
+            },
+            ...(photo.alt && { alt: photo.alt }),
+            createdAt: now
+          }
+        });
+
+        photoUris.push(photoResult.createSocialGrainPhoto.uri);
+      }
+
+      let facets = null;
+      if (this._description.trim()) {
+        const resolveHandle = async (handle) => grainApi.resolveHandle(handle);
+        const parsed = await parseTextToFacets(this._description.trim(), resolveHandle);
+        if (parsed.facets.length > 0) {
+          facets = parsed.facets;
+        }
+      }
+
+      const galleryResult = await client.mutate(CREATE_GALLERY_MUTATION, {
+        input: {
+          title: this._title.trim(),
+          ...(this._description.trim() && { description: this._description.trim() }),
+          ...(facets && { facets }),
+          createdAt: now
+        }
+      });
+
+      const galleryUri = galleryResult.createSocialGrainGallery.uri;
+
+      for (let i = 0; i < photoUris.length; i++) {
+        await client.mutate(CREATE_GALLERY_ITEM_MUTATION, {
+          input: {
+            gallery: galleryUri,
+            item: photoUris[i],
+            position: i,
+            createdAt: now
+          }
+        });
+      }
+
+      draftGallery.clear();
+      sessionStorage.removeItem('draft_title');
+      sessionStorage.removeItem('draft_description');
+      const rkey = galleryUri.split('/').pop();
+      router.push(`/profile/${auth.user.handle}/gallery/${rkey}`);
+
+    } catch (err) {
+      console.error('Failed to create gallery:', err);
+      this._error = err.message || 'Failed to create gallery. Please try again.';
+    } finally {
+      this._posting = false;
+    }
+  }
+
+  render() {
+    return html`
+      <div class="header">
+        <div class="header-left">
+          <button class="back-button" @click=${this.#handleBack}>
+            <grain-icon name="back" size="20"></grain-icon>
+          </button>
+          <span class="header-title">Add image descriptions</span>
+        </div>
+        <grain-button
+          ?loading=${this._posting}
+          loadingText="Posting..."
+          @click=${this.#handlePost}
+        >Post</grain-button>
+      </div>
+
+      ${this._error ? html`<p class="error">${this._error}</p>` : ''}
+
+      <p class="info">Alt text describes images for blind and low-vision users, and helps give context to everyone.</p>
+
+      <div class="photo-list">
+        ${this._photos.map((photo, i) => html`
+          <div class="photo-row">
+            <img class="photo-thumb" src=${photo.dataUrl} alt="Photo ${i + 1}">
+            <div class="alt-input">
+              <grain-textarea
+                placeholder="Alt text"
+                .value=${photo.alt || ''}
+                .maxlength=${1000}
+                @input=${(e) => this.#handleAltChange(i, e)}
+              ></grain-textarea>
+            </div>
+          </div>
+        `)}
+      </div>
+    `;
+  }
+}
+
+customElements.define('grain-image-descriptions', GrainImageDescriptions);

src/services/draft-gallery.js

···
   #photos = [];
 
   setPhotos(photos) {
-    this.#photos = [...photos];
+    // Ensure each photo has an alt property
+    this.#photos = photos.map(p => ({ ...p, alt: p.alt || '' }));
   }
 
   getPhotos() {
     return this.#photos;
+  }
+
+  updatePhotoAlt(index, alt) {
+    if (index >= 0 && index < this.#photos.length) {
+      this.#photos[index] = { ...this.#photos[index], alt };
+    }
   }
 
   clear() {