# Accessibility

Accessibility (a11y) is a core consideration in the development and usage of the Gears CSS Library. Building accessible web interfaces ensures that all users, regardless of their abilities or the tools they use, can perceive, understand, navigate, and interact with your content.

## General Principles

-   **Semantic HTML**: Always prioritize using appropriate semantic HTML elements (e.g., `<button>`, `<nav>`, `<main>`, `<form>`) over generic `<div>`s or `<span>`s. Semantic elements convey meaning to assistive technologies.
-   **Keyboard Navigation**: Ensure all interactive elements are reachable and operable via keyboard. This includes proper tab order and focus management.
-   **Focus Styles**: Provide clear and visible focus indicators for all interactive elements. Gears components should inherently include focus styles. If you create custom components or use utilities on interactive elements, ensure they have a `:focus` and `:focus-visible` state.
    ```css
    /* Example focus style */
    .my-interactive-element:focus {
      outline: 2px solid var(--g-colors-primary);
      outline-offset: 2px;
    }
    .my-interactive-element:focus:not(:focus-visible) {
      outline: none; /* Hide default outline if not using keyboard */
    }
    ```
-   **Color Contrast**: Ensure sufficient color contrast between text and background colors to meet WCAG guidelines (minimum AA level). Use tools to check contrast ratios, especially when defining custom colors or themes.
-   **Meaningful Content**: Provide alternative text for images (`alt` attributes), labels for form controls (`<label>` elements), and clear, concise link text.

## Gears and Accessibility

### Components

When using Gears components (e.g., `btn`, `card`):

-   **Semantic Markup**: Components are designed with semantic HTML in mind. For instance, the `.btn` class is intended for `<button>` or `<a>` elements.
-   **Focus States**: Gears CSS components are built to include default focus styles. If you override component styles, ensure you maintain or enhance these focus indicators.

### Utilities

Utility classes can be powerful for styling, but use them thoughtfully to avoid accessibility pitfalls:

-   **Visual vs. Semantic**: Do not use utility classes to change the semantic meaning of an element. For example, do not style a `<div>` to look like a button without also adding appropriate ARIA roles and keyboard event handlers.
-   **`sr-only` Utility**: Consider adding an `sr-only` utility class to your project for content that should only be visible to screen readers. This is useful for providing additional context without cluttering the visual interface.
    ```css
    /* Example sr-only utility */
    .sr-only {
      position: absolute;
      width: 1px;
      height: 1px;
      padding: 0;
      margin: -1px;
      overflow: hidden;
      clip: rect(0, 0, 0, 0);
      white-space: nowrap;
      border-width: 0;
    }
    ```

## Testing Accessibility

Integrate accessibility testing into your development workflow:

-   **Automated Tools**: Use browser extensions (e.g., Axe DevTools, Lighthouse) or CI/CD tools to catch common accessibility issues.
-   **Manual Testing**: Navigate your application using only the keyboard. Test with screen readers (e.g., NVDA, JAWS, VoiceOver) to understand the user experience.
-   **User Testing**: Involve users with disabilities in your testing process to gain valuable insights.

By keeping accessibility in mind throughout the development process, you can create inclusive web experiences for everyone.