Featured Image Alt Text Gate — 2026-05-29

이 artifact는 블로그가 접근성 표준 전체를 만족한다는 증거가 아니다. 대표 이미지가 제목 fallback에만 기대지 않고, front matter의 image_alt metadata로 의미 있는 대체 텍스트를 갖도록 만든 작은 접근성 게이트다.

Claim

대표 이미지가 있는 모든 Markdown content file은 non-empty image_alt metadata를 가져야 한다. 빌드된 HTML의 <img alt> 존재 여부만 확인하는 것은 충분하지 않다. 제목 fallback은 이미지의 역할을 설명하지 못할 수 있기 때문이다.

Verified Originals

source	Source class	operating grammar extracted	cannot support
WCAG 2.2 Success Criterion 1.1.1 Non-text Content	W3C Recommendation	사용자가 보는 non-text content는 동등한 목적의 text alternative를 가져야 한다.	이 사이트 전체가 WCAG conformant라는 주장을 증명하지 않는다.
HTML Standard: Requirements for text alternatives	living web standard	`alt`는 이미지의 대체 텍스트이며, 일반적으로 비어 있으면 안 되고 이미지가 없을 때 페이지 의미가 유지되도록 작성해야 한다.	각 alt 문구의 완벽한 품질이나 모든 assistive technology 경험을 증명하지 않는다.
MDN HTMLImageElement alt	primary web platform documentation	`alt`는 이미지가 표시되지 않을 때 fallback text로 쓰이며 접근성 의미가 있다.	자동 검사만으로 사람에게 가장 좋은 alt 문구를 보장하지 않는다.

Ontology Impact Map

object	changed or audited
`PostFrontMatter`	`image`가 있는 post는 `image_alt`를 명시해야 한다.
`FeaturedImage`	list/single template의 title fallback에만 기대지 않게 한다.
`StaticQualityGate`	`scripts/check-static-quality.ps1`가 content front matter를 검사한다.
`ClaimBoundary`	접근성 전체 준수와 대표 이미지 alt metadata gate를 분리한다.

Commands / Redlines

command	redline
If front matter has `image`, require non-empty `image_alt`.	Do not rely on the post title as the only image alternative.
Keep generated `<img alt>` checks.	Do not treat generated alt existence as proof that content metadata is complete.
Write alt text for the image purpose in the article.	Do not use file names, decorative filler, or SEO keyword stuffing as alt text.

What Changed

Added a static quality gate that fails when a Markdown content file has image: without non-empty image_alt:.
Added image_alt metadata to 20 posts that previously relied on title fallback.
Preserved the existing generated HTML check that every emitted <img> has non-empty alt.

Validation

Expected verification:

npm run check:quality
npm run check
npm run check:routes
npm run check:live

Claim Boundary

Allowed public claim:

The blog now has a repo-level gate requiring explicit featured-image image_alt metadata for Markdown content with image.

Forbidden public claim:

Do not claim full WCAG conformance, complete screen-reader QA, or complete accessibility remediation from this artifact alone.

Next Artifact

Run a browser and keyboard pass that checks focus order, skip/navigation behavior, command palette interaction, and article reading flow with generated pages.