amare/openspec/specs/content-media/spec.md

content-media Specification

Purpose

Define validation, storage, responsive variants, disk selection, and accessibility requirements for public content images.

Requirements

Requirement: Public content images are validated and stored securely

The system SHALL validate public content uploads (service covers, portfolio covers/gallery, testimonial photos, site OG image) per SPEC §6.4 and §12.4. Validation MUST enforce MIME allowlist (jpeg, png, webp), matching extensions, maximum size of 10 MB, and mandatory alt text when an image is uploaded.

Scenario: Invalid MIME is rejected

• WHEN an admin uploads a file with disallowed MIME type
• THEN validation MUST fail with a pt-BR error message

Scenario: Oversized file is rejected

• WHEN an admin uploads an image exceeding 10 MB
• THEN validation MUST fail

Scenario: Storage path is not derived from original filename

• WHEN an image is stored
• THEN the physical path MUST be generated (UUID/hash based)
• AND MUST NOT use the original upload filename as the storage key

Scenario: Alt text required with image

• WHEN an admin uploads a cover or gallery image without alt text
• THEN validation MUST fail

Scenario: Images are not stored in PostgreSQL

• WHEN content with images is persisted
• THEN only the filesystem path MUST be stored in the database
• AND binary image data MUST NOT be written to PostgreSQL columns

Requirement: Public images are served in responsive variants

The system SHALL generate or serve responsive variants for public content images (service covers, portfolio covers and gallery, testimonial photos) and reference them with srcset and sizes so browsers download an appropriately sized file (SPEC §6.4). Variant generation MUST happen on upload, not on each request.

Scenario: Variants are produced on upload

• WHEN an admin uploads a public content image
• THEN responsive variants MUST be generated and stored alongside the original
• AND the database MUST keep only paths, never binary data

Scenario: Public markup offers multiple sources

• WHEN a public page renders a content image
• THEN the img element MUST expose srcset with the available variants
• AND MUST expose a sizes attribute matching the layout

Scenario: Missing variant falls back to the original

• GIVEN an image stored before variant generation existed
• WHEN it is rendered on a public page
• THEN the original file MUST be used without breaking the page

Requirement: Public images avoid layout shift and defer offscreen loading

Public content images SHALL reserve their space through explicit width and height (or equivalent aspect-ratio styling) and MUST use loading="lazy" when rendered below the fold. Above-the-fold hero imagery MUST NOT be lazy loaded (SPEC §6.4, §6.6).

Scenario: Offscreen image is lazy loaded

• WHEN a page renders an image below the first viewport
• THEN the img element MUST carry loading="lazy"

Scenario: Hero image loads eagerly

• WHEN the home hero image is rendered
• THEN it MUST NOT carry loading="lazy"

Scenario: Dimensions are reserved

• WHEN any public content image is rendered
• THEN width and height (or aspect ratio) MUST be declared so layout does not shift after load

Requirement: Production images are not served from ephemeral container disk

Public image variants SHALL be stored on the configured filesystem disk (S3-compatible in production) and referenced by URL, so a container restart or redeploy does not lose media (SPEC §6.4).

Scenario: Media survives container replacement

• GIVEN production uses the S3-compatible disk
• WHEN the application container is replaced
• THEN previously uploaded images and variants MUST remain reachable

Requirement: CMS public image uploads select production object storage disk

Public content image uploads (Filament FileUpload via PublicImageUploadRules) MUST store files on the disk matching the configured default filesystem (SPEC §6.4). When FILESYSTEM_DISK is r2, uploads MUST use the r2 disk. When FILESYSTEM_DISK is s3, uploads MUST use the s3 disk. Otherwise uploads MUST use the local public disk.

Scenario: Production R2 disk is used for CMS uploads

• WHEN FILESYSTEM_DISK=r2
• THEN PublicImageUploadRules::disk() MUST return r2

Scenario: Legacy S3 default still supported

• WHEN FILESYSTEM_DISK=s3
• THEN PublicImageUploadRules::disk() MUST return s3

Scenario: Local development uses public disk

• WHEN FILESYSTEM_DISK is local, unset, or any value other than r2/s3
• THEN PublicImageUploadRules::disk() MUST return public