docs(opacity-checkerboard): enhance README with detailed usage

[blunteshwar]

docs(opacity-checkerboard): enhance README with detailed sections

Overview

This PR reorganizes the opacity-checkerboard README.md to follow the established documentation standards structure, improving accessibility and consistency with other components.

Changes Made

Structure Reorganization

• Overview: Replaced "Description" with "Overview" section to align with documentation standards
• Usage: Updated import code blocks with proper language syntax highlighting (bash, javascript)
• Integration: Added new section with clear guidance on how to integrate the CSS utility into components
• Examples: Created comprehensive examples section with:
  • Basic usage with accessibility attributes
  • Overlaid content demonstration showing transparency effects
• Accessibility: Added comprehensive new section including:
  • Screen reader support with proper ARIA implementation
  • Keyboard navigation considerations
  • Context and role attribution guidelines
  • Alternative text best practices

Code Quality Improvements

• Added language identifiers to all code blocks for proper syntax highlighting
• Maintained all existing content without removal
• Improved content organization for better readability
• Added NPM badges for package visibility and bundle size

Accessibility Enhancements

• Documented proper use of role="img" for visual indicators
• Added guidance on aria-label attributes for context
• Explained screen reader text implementation using visually-hidden class
• Provided examples of keyboard navigation considerations
• Included best practices for alternative text in color picker contexts

Testing

• Verified all existing content is preserved
• Checked that code examples render correctly with html-live syntax
• Ensured documentation follows established patterns from other components
• Validated markdown formatting
• No linting errors introduced

Related Documentation

This PR follows the documentation standards outlined in:

• Adding a Component - Documentation Standards
• Example PR docs(color-handle): enhance README with detailed component overview #5663 and docs(color-slider): enhance README with detailed sections #5728 (used as reference)

Screenshots

N/A - Documentation only changes

Before/After Structure Comparison

Before:

• Description
• Usage

After:

• Overview
• Usage
• Integration
• Examples
  • Basic usage
  • With overlaid content
• Accessibility
  • Screen reader support
  • Keyboard navigation

Checklist

• Documentation follows established structure and standards
• All code blocks have appropriate language hints
• Examples are accessible with proper ARIA attributes
• No content removed, only reorganized
• Keyboard navigation documented with proper guidance
• Consistent with other component documentation (color-area, color-handle, color-slider)
• NPM badges added for better discoverability
• html-live examples render correctly in documentation environment

This reorganization makes the opacity-checkerboard documentation more accessible, easier to navigate, and consistent with the established documentation standards across the Spectrum Web Components library, following the same structure and approach used in PR #5728.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4fe3e42

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview

• Documentation Site
• Storybook

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-5751

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

[github-actions]

Tachometer results

Currently, no packages are changed by this PR...

[Rajdeepc]

You are trying to surface up semantic meaning to the users but you shouldn't label the checkerboard itself. You can expose that information via a text node or a live region that updates as opacity changes.

<div
    class="opacity-checkerboard"
    style="inline-size: 100px; block-size: 100px;"
    aria-hidden="true"
></div>

<span class="visually-hidden">Checkerboard pattern indicating transparent areas</span>

[Rajdeepc]

Opacity Checkerboard is just a visual indicator it should remain hidden from screen readers.

[blunteshwar]

The opacity checkerboard is indeed just a visual pattern and shouldn't be announced to screen readers. I agree that the semantic meaning should come from the context where it's used, not the checkerboard itself. I have added aria-hidden:true in the documentation.

[blunteshwar]

Self Review - Documentation Changes

Structure Reorganization

• Before: 2 sections (Description, Usage)
• After: 6 sections following documentation standards (Overview, Usage, Integration, Examples, Accessibility)

Key Improvements

Enhanced Content

• Expanded Overview with clear component purpose and use cases
• Added NPM badges and proper syntax highlighting (bash, javascript)
• Created new Integration section with CSS implementation guidance
• Added comprehensive Examples section with basic and advanced use cases

Accessibility Implementation

• Initial approach: Added ARIA labels to checkerboard elements
• Corrected approach: Based on expert feedback, updated to:
  • Use aria-hidden="true" on decorative checkerboard elements
  • Implement aria-live regions for dynamic opacity announcements
  • Separate semantic information from visual indicators

Code Quality

• Added language identifiers to all code blocks
• Consistent html-live syntax for documentation rendering
• Improved markdown formatting and structure

Standards Compliance

• Follows established documentation patterns from other components
• All original content preserved and reorganized
• No breaking changes, documentation-only improvements

[nikkimk]

Nice work on this one!