How to use the Decorative Elements Accessibility Check agent skill

What the decorative-elements skill makes the agent do

Once installed, the agent reviews web page markup and components for decorative images, icons and SVGs that screen readers would announce needlessly. It checks that decorative images use empty alt text, that decorative icons use aria-hidden, and that decoration is not exposed to assistive technology.

The skill also tells the agent not to flag harmless decorative elements unless there is a real semantic, focus or layout problem. Its guidance is that an image that is clearly decorative should produce no finding unless the snippet shows broken semantics, focusability, or visible layout instability.

• Decorative img elements should use alt="" (empty), not a missing alt or alt="image".
• Decorative SVGs and icon fonts should use aria-hidden="true".
• Purely decorative visuals can be drawn with CSS background-image instead of img elements.
• role="presentation" removes semantic meaning from an element, so use it with care.

Install the skill from the ZIP or the Claude apps

Download the ZIP for the decorative-elements skill from this directory page. Then choose one of the two install routes below.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available to you across projects, or into a project's .claude/skills/ folder to limit it to that project. The skill folder contains SKILL.md and references/rule.md.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. The skill is written to activate when you ask the agent to review rendered HTML, interactive components, or design-system patterns for decorative content. Name the thing you want checked and the rule in ordinary words.

Paste the markup or describe the component, then ask directly. Including the surrounding markup helps the agent judge whether an image is really decorative.

• "Check this HTML for decorative images that screen readers will announce."
• "Review this icon component: should its SVG be hidden from assistive technology?"
• "Does this divider image need an empty alt attribute?"
• "Give me a quick first-pass accessibility check on this snippet for decorative elements."

Read the results and check the examples

The source material shows the pattern the agent looks for. A missing alt makes a screen reader guess from the filename, and alt="border" is still noise. An empty alt is skipped by screen readers, and a CSS-drawn border avoids the image entirely.

Treat the agent's output as a starting point. Confirm each flagged element in a browser's accessibility tools or with a real screen reader before changing production code.

• Bad: missing alt, the screen reader announces the filename, for example "decorative-border.png, image".
• Bad: alt="border", announced as "border, image".
• Good: alt="", the image is skipped by screen readers.
• Better: a div with a CSS class for the border, with no image element at all.