From 11cf9acdc5b2ecba477bbc18e8490503cc72d0aa Mon Sep 17 00:00:00 2001 From: blunteshwar Date: Wed, 24 Sep 2025 10:22:57 +0530 Subject: [PATCH 1/2] docs(opacity-checkerboard): enhance README with detailed usage --- tools/opacity-checkerboard/README.md | 95 +++++++++++++++++++++++++--- 1 file changed, 87 insertions(+), 8 deletions(-) diff --git a/tools/opacity-checkerboard/README.md b/tools/opacity-checkerboard/README.md index 2d8928b48c2..20b5e0cd685 100644 --- a/tools/opacity-checkerboard/README.md +++ b/tools/opacity-checkerboard/README.md @@ -1,29 +1,108 @@ -## Description +## Overview -The `opacity-checkerboard` class is used to highlight opacity. Leverage these styles in your component as outlined below to unify you application's visuals with those delivered by various Spectrum Web Components. +The `opacity-checkerboard` class provides a CSS utility that displays a checkerboard pattern background, commonly used to highlight transparent or semi-transparent areas in UI components. This visual indicator helps users distinguish between transparent and opaque regions, making it an essential tool for color pickers, image editors, and other components that work with opacity. -## Usage +### Usage -Import the styles from the `opacity-checkerboard` CSS: +[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/opacity-checkerboard?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/opacity-checkerboard) +[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/opacity-checkerboard?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/opacity-checkerboard) +```bash +yarn add @spectrum-web-components/opacity-checkerboard ``` + +Import the opacity checkerboard styles from: + +```javascript import opacityCheckerBoardStyles from '@spectrum-web-components/opacity-checkerboard/src/opacity-checkerboard.css.js'; ``` -Add it to your component's styles array before your component's styles. The order that you include the styles in makes a difference, because selectors within opacity checkerboard may have the same -specificity as those within your component. +### Integration -```js +To integrate the opacity checkerboard styles into your component, add them to your component's styles array. The order of inclusion is important, as selectors within opacity checkerboard may have the same specificity as those within your component: + +```javascript public static override get styles(): CSSResultArray { return [opacityCheckerBoardStyles, styles]; } ``` -Use the `opacity-checkerboard` class in your component's `render()` method: +### Examples + +#### Basic usage + +Apply the `opacity-checkerboard` class to any element that needs to display the checkerboard pattern: ```html-live demo
``` + +#### With overlaid content + +The opacity checkerboard works well as a background for elements with partial transparency: + +```html-live + +``` + +### Accessibility + +When implementing the opacity checkerboard pattern, ensure proper accessibility by: + +- **Providing context**: Add appropriate ARIA labels to describe what the checkerboard pattern represents +- **Role attribution**: Use `role="img"` when the checkerboard serves as a visual indicator +- **Descriptive labels**: Include `aria-label` attributes that explain the purpose of the transparency indicator +- **Alternative text**: When used in color pickers or image editors, provide text alternatives that describe the transparency level + +#### Screen reader support + +The opacity checkerboard is a purely visual indicator. Always provide alternative text or descriptions for screen reader users: + +```html-live +
+ +
+``` + +#### Keyboard navigation + +When the opacity checkerboard is part of an interactive component, ensure it doesn't interfere with keyboard navigation: + +```html-live + +``` From 4fe3e42d6928cccf047f33f1533f9202d3446cf6 Mon Sep 17 00:00:00 2001 From: blunteshwar Date: Wed, 24 Sep 2025 12:53:24 +0530 Subject: [PATCH 2/2] docs(opacity-checkerboard): update README for improved accessibility practices --- tools/opacity-checkerboard/README.md | 60 +++++++++++++++++++--------- 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/tools/opacity-checkerboard/README.md b/tools/opacity-checkerboard/README.md index 20b5e0cd685..4e6453930f6 100644 --- a/tools/opacity-checkerboard/README.md +++ b/tools/opacity-checkerboard/README.md @@ -37,7 +37,7 @@ Apply the `opacity-checkerboard` class to any element that needs to display the ``` @@ -49,8 +49,7 @@ The opacity checkerboard works well as a background for elements with partial tr ``` @@ -67,22 +65,48 @@ The opacity checkerboard works well as a background for elements with partial tr When implementing the opacity checkerboard pattern, ensure proper accessibility by: -- **Providing context**: Add appropriate ARIA labels to describe what the checkerboard pattern represents -- **Role attribution**: Use `role="img"` when the checkerboard serves as a visual indicator -- **Descriptive labels**: Include `aria-label` attributes that explain the purpose of the transparency indicator -- **Alternative text**: When used in color pickers or image editors, provide text alternatives that describe the transparency level +- **Hiding from screen readers**: Use `aria-hidden="true"` on the checkerboard element since it's purely visual +- **Providing semantic information**: Use separate text nodes or live regions to convey opacity information +- **Using live regions**: Implement `aria-live` regions to announce opacity changes dynamically +- **Descriptive context**: Provide meaningful descriptions of the actual color and opacity values, not the visual pattern #### Screen reader support -The opacity checkerboard is a purely visual indicator. Always provide alternative text or descriptions for screen reader users: +The opacity checkerboard is a purely visual indicator and should remain hidden from screen readers. Instead, provide semantic information through separate text nodes or live regions that update as opacity changes: ```html-live -
- +
+ + +
+``` + +For components that change opacity dynamically, use a live region to announce changes: + +```html-live +
+ +
``` @@ -93,16 +117,16 @@ When the opacity checkerboard is part of an interactive component, ensure it doe ```html-live ```