Officecli Accessibility

officecli-accessibility

Overlay skill for OfficeCLI that ensures documents meet accessibility standards. Use this skill for pre-delivery QA, compliance audits, or when creating documents for public distribution.

Install consent contract: probe with the agent's actual shell — command -v officecli on POSIX, Get-Command officecli -ErrorAction SilentlyContinue in PowerShell, or portably officecli --version. command -v is NOT a PowerShell builtin: on Windows it prints nothing, sets no exit code, and raises no error, so a working install reads as missing and the agent asks to install what is already there (#298). If genuinely missing, do not auto-install. Ask the user to install the supported fork from https://github.com/lidge-jun/OfficeCLI, continue with a lightweight/manual accessibility fallback after stating validation/remediation limits, or stop. If the user chooses lightweight mode, save that preference to memory for future Office work.

When to Use

• Creating documents for public distribution or government compliance
• Compliance requirement: WCAG 2.1 AA, Section 508, EN 301 549, PDF/UA
• User requests "accessible" or "ADA-compliant" document
• QA review before final delivery to clients

Standards Reference

1. Alt-Text Audit

Every image, chart, and non-text element needs alternative text for screen readers.

Find Images Without Alt-Text

# PPTX: query for pictures, check alt attribute
officecli query slides.pptx 'picture' --json
# Look for entries where "alt" is empty or missing

# DOCX: find all pictures
officecli query report.docx 'picture' --json

# PPTX: filter to only pictures with alt-text present
officecli query slides.pptx 'picture[alt]' --json
# Compare count with total pictures to find gaps

Set Alt-Text

# Add descriptive alt-text to a picture
officecli set slides.pptx '/slide[1]/picture[1]' \
  --prop alt="Bar chart showing Q4 revenue by region: East $2.1M, West $1.8M, Central $1.5M"

# Add alt-text to a shape used as a visual element
officecli set slides.pptx '/slide[1]/shape[2]' \
  --prop alt="Company logo - Acme Corp"

# Mark decorative images (empty alt = explicitly decorative)
officecli set slides.pptx '/slide[1]/picture[3]' --prop alt=""

Alt-Text Quality Guidelines

Rules:

• Describe the purpose, not just appearance
• Include data summaries for charts/graphs
• Keep under 125 characters when possible
• Use empty string "" only for truly decorative elements

2. Color Contrast

WCAG 2.1 AA minimum contrast ratios:

Inspect Colors

# PPTX: get shape properties including colors
officecli get slides.pptx '/slide[1]' --depth 2 --json
# Check font.color and fill values for each shape

# DOCX: inspect run formatting
officecli get report.docx '/body/p[1]/r[1]' --json
# Look at font.color and background

# XLSX: inspect cell colors
officecli get data.xlsx '/Sheet1/A1' --json
# Check font.color and fill properties

Common Problematic Combinations

Fix Contrast Issues

# Change low-contrast text to a darker color
officecli set slides.pptx '/slide[1]/shape[1]' --prop font.color=1A1A2E

# Change background to improve contrast
officecli set slides.pptx '/slide[1]/shape[1]' --prop fill=FFFFFF

# DOCX: fix light gray text
officecli set report.docx '/body/p[3]/r[1]' --prop font.color=333333

Contrast Calculation Formula

L = 0.2126 * R + 0.7152 * G + 0.0722 * B  (relative luminance)
Ratio = (L_lighter + 0.05) / (L_darker + 0.05)

Use an external contrast checker tool (e.g., WebAIM) for precise calculations. Use view issues and explicit queries for OfficeCLI-side accessibility scans. Visual contrast still needs a renderer or contrast checker for final proof:

officecli view slides.pptx issues --json
officecli query slides.pptx 'shape[text]' --json

3. Reading Order

For screen readers, the reading order in PowerPoint = the shape order (z-order) on each slide.

Check Current Reading Order

# View shapes in reading order (output order = tab/read order)
officecli get slides.pptx '/slide[1]' --depth 1 --json
# Shapes are listed in their current reading order

# Quick text-order view
officecli view slides.pptx text
# Text appears in the order a screen reader would read it

Fix Reading Order

# Move a shape to a specific reading-order position (1-based index)
officecli move slides.pptx '/slide[1]/shape[3]' --index 1
# Shape 3 is now read first

# Example: ensure title is read before body content
officecli move slides.pptx '/slide[1]/shape[2]' --index 1

Reading Order Checklist per Slide

1. Title/heading shapes should be first in order
2. Body content follows in logical sequence (top→bottom, left→right)
3. Decorative elements should be last (or marked as decorative)
4. Navigation elements should be in consistent position across slides

4. Document Structure (DOCX)

Heading Hierarchy

Headings must follow a logical hierarchy. Never skip levels.

Check Heading Structure

# Find all heading paragraphs
officecli query report.docx 'paragraph[style~=Heading]' --json

# View document outline (shows heading hierarchy)
officecli view report.docx outline

# Quick check: heading levels should increment by 1
officecli view report.docx outline | grep -E 'H[1-6]'

Fix Heading Levels

# Change a paragraph's heading style
officecli set report.docx '/body/p[5]' --prop style=Heading2

# Demote Heading1 to Heading2
officecli set report.docx '/body/p[3]' --prop style=Heading2

5. Tables

Table Headers

Tables must have a designated header row for screen readers.

# DOCX: check table structure
officecli get report.docx '/body/tbl[1]' --depth 2 --json
# Verify first row is marked as header

# XLSX: check if header row exists
officecli get data.xlsx '/Sheet1' --depth 1 --json

# PPTX: check table structure
officecli get slides.pptx '/slide[1]/table[1]' --depth 2 --json

Table Accessibility Rules

• Every table must have a header row
• Avoid merged cells (they confuse screen readers)
• Don't use tables for layout — use them for data only
• Add a table caption/title when the data needs context

6. Links

Check Link Text

# DOCX: find all hyperlinks
officecli query report.docx 'paragraph > run[link]' --json
# Verify link text is descriptive

# Check for generic link text
officecli view report.docx text | grep -iE 'click here|read more|learn more|here'

Fix Link Text

Links should describe their destination, not use generic phrases.

7. Font Size and Readability

Minimum Sizes

Check Font Sizes

# DOCX: find small text
officecli query report.docx 'paragraph > run[size<=10pt]' --json

# PPTX: check shape text sizes
officecli get slides.pptx '/slide[1]' --depth 2 --json

Pre-Delivery Accessibility Checklist

Run this checklist before delivering any document:

Images & Media

• All images have meaningful alt-text: officecli query file 'picture' --json
• Decorative images have empty alt-text (alt="")
• Charts have data summaries in alt-text
• No essential information conveyed only through images

Color & Contrast

• Text contrast ≥ 4.5:1 (normal) / 3:1 (large): run officecli view file.pptx issues --json, then verify final contrast with a renderer or contrast checker
• Information not conveyed by color alone
• Charts use patterns/labels in addition to color

Structure (DOCX)

• Heading hierarchy is correct (no skips): officecli view file.docx outline
• Lists use proper list styles (not manual bullets)
• Tables have header rows
• No empty paragraphs used for spacing

Reading Order (PPTX)

• Tab order matches visual reading order: officecli view file.pptx text
• Title is read first on each slide
• Content follows logical flow

Text & Links

• Font size ≥ 12pt for body: officecli query file.docx 'paragraph > run[size<=10pt]'
• No text embedded in images
• Links have descriptive text (not "click here")
• Language is set correctly for spell-check

Validation

• officecli validate file structural result is recorded
• officecli view file.pptx issues --json reports no critical PowerPoint issues
• render/app-open proof is recorded separately when visual fidelity matters

Batch Accessibility Fixes

For bulk remediation across an entire presentation:

# Example: set alt-text for multiple pictures in one batch
officecli batch slides.pptx --commands '[
  {"command":"set","path":"/slide[1]/picture[1]","props":{"alt":"Company revenue chart for Q4 2025"}},
  {"command":"set","path":"/slide[2]/picture[1]","props":{"alt":"Team photo at annual meeting"}},
  {"command":"set","path":"/slide[3]/picture[1]","props":{"alt":"Product roadmap timeline diagram"}},
  {"command":"set","path":"/slide[4]/picture[1]","props":{"alt":""}}
]'

# Validate after fixes
officecli validate slides.pptx

Quick Reference Card