@fpkit/acss 0.5.12 → 0.5.13

package/src/components/icons/README.mdx

@@ -0,0 +1,332 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.REACT Components/Icons/Readme" />
+
+# Icon Component
+
+## Summary
+
+The `Icon` component is an accessibility-first wrapper for SVG icons that enforces WCAG 2.1 Level AA compliance by hiding decorative icons from screen readers by default. It provides a flexible, type-safe API for both decorative and semantic icon usage patterns.
+
+## Features
+
+- **Accessibility by Default** - Icons are hidden from screen readers (`aria-hidden="true"`) by default
+- **Decorative vs. Semantic Patterns** - Clear distinction between decorative and meaningful icons
+- **Type-Safe Props** - Full TypeScript support with comprehensive prop definitions
+- **Rich Icon Library** - 30+ pre-built SVG icons (arrows, actions, alerts, media controls)
+- **Customizable Styling** - Control size, color, stroke, and fill properties
+- **Compound Component Pattern** - Access icons via `Icon.Code`, `Icon.Home`, etc.
+- **WCAG 2.1 AA Compliant** - Follows accessibility best practices out of the box
+- **Backward Compatible** - Deprecated `alt` prop maintained for legacy code
+
+## Key Accessibility Principle
+
+> **Decorative images must be hidden from assistive technology** (WCAG 1.1.1)
+
+Most icons in user interfaces are **decorative** — they accompany visible text labels (e.g., a save icon next to "Save Changes"). Screen readers should not announce these redundantly.
+
+When icons are **semantic** (standalone without text), developers must explicitly:
+1. Set `aria-hidden={false}` to expose the icon
+2. Provide `aria-label` for an accessible name
+
+## Props
+
+### Icon Wrapper Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria-hidden` | `boolean` | `true` | Controls screen reader visibility. `true` = decorative, `false` = semantic |
+| `aria-label` | `string` | - | Accessible label (required for standalone semantic icons) |
+| `role` | `string` | - | ARIA role override (use `"img"` for complex semantic SVGs) |
+| `styles` | `React.CSSProperties` | - | Inline styles for the wrapper span |
+| `classes` | `string` | - | CSS class names |
+| `children` | `React.ReactNode` | - | Icon SVG component(s) to render |
+
+### Individual Icon Props
+
+Props for individual icon components (e.g., `Icon.Code`, `Icon.Home`):
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `number` | `16` | Icon size in pixels (sets both width and height) |
+| `fill` | `string` | `'none'` | SVG fill color (CSS color value) |
+| `strokeColor` | `string` | `'currentColor'` | SVG stroke color (CSS color value) |
+| `strokeWidth` | `string` | `'2'` | SVG stroke width |
+| `width` | `number` | - | Explicit width in pixels (overrides size) |
+| `height` | `number` | - | Explicit height in pixels (overrides size) |
+| `alt` | `string` | - | **@deprecated** Use `aria-label` instead |
+
+## Available Icons
+
+### Action Icons
+- `Icon.Add`, `Icon.Minus`, `Icon.Remove` (Close), `Icon.Copy`, `Icon.Star`
+
+### Navigation Icons
+- `Icon.ArrowUp`, `Icon.ArrowDown`, `Icon.ArrowLeft`, `Icon.ArrowRight`
+- `Icon.Up`, `Icon.Down`, `Icon.Left`, `Icon.Right`
+- `Icon.Home`
+
+### Media Control Icons
+- `Icon.Play`, `Icon.Pause`, `Icon.Stop`, `Icon.Resume`
+- `Icon.PlaySolid`, `Icon.PauseSolid`, `Icon.StopSolid`, `Icon.ResumeSolid`
+
+### Status/Alert Icons
+- `Icon.Info`, `Icon.InfoSolid`
+- `Icon.AlertSolid`, `Icon.AlertSquareSolid`
+- `Icon.WarnSolid`, `Icon.SuccessSolid`, `Icon.QuestionSolid`
+
+### Other Icons
+- `Icon.Code`, `Icon.Chat`, `Icon.User`
+
+### Aliases
+- `Icon.Close` → `Icon.Remove`
+
+## Usage Examples
+
+### ✅ Decorative Icon with Text (Default, Recommended)
+
+When icons accompany visible text, they are decorative and should be hidden from screen readers:
+
+```tsx
+import { Button } from "@fpkit/acss";
+import { Icon } from "@fpkit/acss";
+
+// Screen reader announces: "Save Changes, button"
+const SaveButton = () => (
+  <Button type="button" onClick={handleSave}>
+    <Icon>
+      <Icon.Code />
+    </Icon>
+    Save Changes
+  </Button>
+);
+```
+
+**Why this works:**
+- Icon is decorative (accompanies "Save Changes" text)
+- `aria-hidden="true"` is applied by default
+- Screen reader users hear only "Save Changes, button" (no redundancy)
+
+---
+
+### ✅ Semantic Icon-Only Button (Explicit Pattern)
+
+When icons stand alone without visible text, they must be exposed to screen readers:
+
+```tsx
+import { Button } from "@fpkit/acss";
+import { Icon } from "@fpkit/acss";
+
+// Screen reader announces: "Close dialog, button"
+const CloseButton = () => (
+  <Button type="button" aria-label="Close dialog" onClick={handleClose}>
+    <Icon aria-hidden={false}>
+      <Icon.Remove />
+    </Icon>
+  </Button>
+);
+```
+
+**Why this works:**
+- Icon is semantic (no visible text)
+- `aria-hidden={false}` exposes icon to screen readers
+- `aria-label` on the button provides accessible name
+- Meets WCAG 4.1.2 (Name, Role, Value)
+
+---
+
+### ✅ Semantic Icon with role="img"
+
+For complex SVG icons that convey meaning, use `role="img"`:
+
+```tsx
+import { Icon } from "@fpkit/acss";
+
+// Screen reader announces: "Code snippet, image"
+const CodeIcon = () => (
+  <Icon
+    aria-hidden={false}
+    aria-label="Code snippet"
+    role="img"
+  >
+    <Icon.Code size={32} />
+  </Icon>
+);
+```
+
+**Why this works:**
+- `role="img"` tells screen readers this is a meaningful image
+- `aria-label` provides the image description
+- Follows WCAG 1.1.1 (Non-text Content)
+
+---
+
+### ✅ Custom Styling
+
+Icons inherit text color by default (`strokeColor="currentColor"`):
+
+```tsx
+import { Icon } from "@fpkit/acss";
+
+const StyledIcon = () => (
+  <div style={{ color: "blue" }}>
+    <Icon>
+      <Icon.Star size={24} fill="gold" strokeColor="orange" />
+    </Icon>
+    Favorite
+  </div>
+);
+```
+
+---
+
+### ❌ Anti-Pattern: Icon-Only Button Without Label
+
+**This violates WCAG 4.1.2 (Name, Role, Value):**
+
+```tsx
+// ❌ BAD: Screen reader cannot identify button purpose
+const BadButton = () => (
+  <Button type="button" onClick={handleClose}>
+    <Icon>
+      <Icon.Remove />
+    </Icon>
+  </Button>
+);
+```
+
+**Why this fails:**
+- Icon-only button with no accessible name
+- Screen reader announces only "button" (no context)
+- Users cannot determine what the button does
+
+**Fix:**
+```tsx
+// ✅ GOOD: Add aria-label to button
+<Button type="button" aria-label="Close" onClick={handleClose}>
+  <Icon aria-hidden={false}>
+    <Icon.Remove />
+  </Icon>
+</Button>
+```
+
+---
+
+## Technical Details
+
+### Component Architecture
+
+The Icon component uses a **compound component pattern**:
+- `Icon` - Wrapper component handling accessibility
+- `Icon.Code`, `Icon.Home`, etc. - Individual SVG icon components
+- `Svg` - Base SVG component used by all icons
+
+### Polymorphic UI Component
+
+The Icon wrapper uses the polymorphic `UI` component from `#components/ui`, which:
+- Supports ref forwarding for focus management
+- Accepts all native HTML span attributes
+- Merges default and custom styles
+
+### Type Safety
+
+The component is fully typed with TypeScript:
+
+```tsx
+export type IconProps = React.ComponentProps<typeof UI> & {
+  "aria-hidden"?: boolean;
+  "aria-label"?: string;
+  role?: string;
+};
+```
+
+Individual icon props extend `IconProps` from `types.ts` with visual styling properties.
+
+---
+
+## Accessibility Checklist
+
+When using icons, ensure:
+
+- [ ] **Decorative icons** (with text) use default `aria-hidden="true"`
+- [ ] **Semantic icons** (standalone) have `aria-hidden={false}`
+- [ ] **Semantic icons** have `aria-label` or `aria-labelledby`
+- [ ] **Icon-only buttons** have `aria-label` on the button element
+- [ ] **Icon color contrast** meets WCAG 1.4.11 (3:1 for UI components)
+- [ ] **Touch targets** are at least 44×44 CSS pixels (WCAG 2.5.5)
+
+---
+
+## Migration Guide
+
+### Deprecation: `alt` Prop
+
+The `alt` prop is deprecated because it's only valid for `<img>` elements, not SVG.
+
+**Before:**
+```tsx
+<Icon.Code alt="Code icon" />
+```
+
+**After:**
+```tsx
+<Icon aria-hidden={false} aria-label="Code icon">
+  <Icon.Code />
+</Icon>
+```
+
+### Adding aria-hidden to Existing Icons
+
+If you have existing icon usage without explicit accessibility attributes:
+
+**Before:**
+```tsx
+<button>
+  <Icon><Icon.Remove /></Icon>
+  Close
+</button>
+```
+
+**After (no change needed):**
+```tsx
+// Icons are now hidden by default - existing code is more accessible!
+<button>
+  <Icon><Icon.Remove /></Icon>
+  Close
+</button>
+```
+
+For icon-only buttons, update to:
+
+```tsx
+<button aria-label="Close">
+  <Icon aria-hidden={false}>
+    <Icon.Remove />
+  </Icon>
+</button>
+```
+
+---
+
+## Additional Notes
+
+- **Color inheritance**: Icons use `strokeColor="currentColor"` by default, inheriting parent text color
+- **Size units**: Icon sizes are in pixels (e.g., `size={24}` = 24px)
+- **Performance**: SVG icons are lightweight and render efficiently
+- **Bundle size**: Icons are tree-shakeable when using named imports
+- **Browser support**: Works in all modern browsers supporting SVG
+
+---
+
+## Related Components
+
+- [Button](/docs/fp-react-components-buttons-readme--docs) - Learn about accessible button patterns
+- [Alert](/docs/fp-react-components-alert-readme--docs) - Uses icons for severity indicators
+
+---
+
+## Further Reading
+
+- [WCAG 1.1.1: Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
+- [WCAG 4.1.2: Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html)
+- [Accessible Icon Buttons (Sara Soueidan)](https://www.sarasoueidan.com/blog/accessible-icon-buttons/)

package/src/components/icons/icon.stories.tsx

@@ -53,9 +53,14 @@ export const IconButton = {
   },
 };
 
+/**
+ * Decorative icon (default behavior).
+ * Icon is hidden from screen readers via aria-hidden="true".
+ * Use when icon accompanies visible text.
+ */
 export const Code: Story = {
   args: {
-    children: <Icon.Code role="img" aria-label="code icon" />,
+    children: <Icon.Code />,
   },
 } as Story;
 
@@ -249,3 +254,71 @@ export const AlertSquareSolid: Story = {
     children: <Icon.AlertSquareSolid />,
   },
 } as Story;
+
+/**
+ * ✅ ACCESSIBLE PATTERN: Decorative icon with visible text.
+ * Icon is hidden from screen readers (default aria-hidden="true").
+ * Screen readers announce only "Save Changes".
+ */
+export const DecorativeIconWithText: Story = {
+  args: {},
+  render: () => (
+    <Button type="button">
+      <Icon>
+        <Icon.Code />
+      </Icon>
+      Save Changes
+    </Button>
+  ),
+} as Story;
+
+/**
+ * ✅ ACCESSIBLE PATTERN: Semantic icon-only button.
+ * Icon is exposed to screen readers with aria-hidden={false}.
+ * aria-label provides accessible name for screen readers.
+ */
+export const SemanticIconOnlyButton: Story = {
+  args: {},
+  render: () => (
+    <Button type="button" aria-label="Close dialog">
+      <Icon aria-hidden={false}>
+        <Icon.Remove />
+      </Icon>
+    </Button>
+  ),
+} as Story;
+
+/**
+ * ✅ ACCESSIBLE PATTERN: Icon with role="img" for semantic meaning.
+ * Use when icon conveys information beyond decoration.
+ * Requires aria-label for accessible name.
+ */
+export const SemanticIconWithRole: Story = {
+  args: {
+    "aria-hidden": false,
+    "aria-label": "Code snippet",
+    role: "img",
+    children: <Icon.Code />,
+  },
+} as Story;
+
+/**
+ * ❌ ANTI-PATTERN: Icon-only button without accessible name.
+ * This will fail WCAG 4.1.2 (Name, Role, Value).
+ * Screen readers cannot identify the button's purpose.
+ */
+export const IconOnlyButtonNoLabel: Story = {
+  args: {},
+  render: () => (
+    <div style={{ opacity: 0.5, border: "2px dashed red", padding: "1rem" }}>
+      <p style={{ color: "red", marginBottom: "0.5rem" }}>
+        ❌ BAD: No accessible name
+      </p>
+      <Button type="button">
+        <Icon>
+          <Icon.Remove />
+        </Icon>
+      </Button>
+    </div>
+  ),
+} as Story;

package/src/components/icons/icon.tsx

@@ -53,13 +53,98 @@ const defaultStyles = {
   width: "auto",
 };
 
-export type IconProps = React.ComponentProps<typeof UI>;
+export type IconProps = React.ComponentProps<typeof UI> & {
+  /**
+   * Controls screen reader visibility.
+   * - `true` (default): Hides icon from screen readers (decorative icon)
+   * - `false`: Makes icon visible to screen readers (semantic icon)
+   *
+   * **When to use decorative (aria-hidden="true", default):**
+   * - Icon accompanies visible text (e.g., button with icon + label)
+   * - Icon is purely visual decoration
+   *
+   * **When to use semantic (aria-hidden="false"):**
+   * - Icon is the only content (e.g., icon-only button)
+   * - Must provide `aria-label` or `aria-labelledby` for accessible name
+   *
+   * @default true
+   * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
+   */
+  "aria-hidden"?: boolean;
+  /**
+   * Accessible label for semantic icons.
+   * Required when icon is standalone (not accompanied by visible text).
+   *
+   * @example
+   * ```tsx
+   * // ✅ GOOD: Icon-only button with accessible name
+   * <button>
+   *   <Icon aria-hidden={false} aria-label="Close dialog">
+   *     <Icon.Remove />
+   *   </Icon>
+   * </button>
+   *
+   * // ✅ GOOD: Icon with visible text (default decorative)
+   * <button>
+   *   <Icon><Icon.Add /></Icon>
+   *   Add Item
+   * </button>
+   * ```
+   */
+  "aria-label"?: string;
+  /**
+   * Semantic role override.
+   * Use `role="img"` when icon conveys meaning and is not decorative.
+   *
+   * @default undefined (no role for decorative icons)
+   */
+  role?: string;
+};
 
+/**
+ * Icon wrapper component that enforces accessibility best practices.
+ *
+ * **Default behavior (decorative icon):**
+ * - Hidden from screen readers (`aria-hidden="true"`)
+ * - Used when icon accompanies visible text
+ *
+ * **Semantic icon pattern:**
+ * - Set `aria-hidden={false}` to expose to screen readers
+ * - Must provide `aria-label` for accessible name
+ * - Consider `role="img"` for complex SVG icons
+ *
+ * @param {IconProps} props - Component props
+ * @returns {React.ReactElement} Accessible icon wrapper
+ *
+ * @example
+ * // ✅ Decorative icon with text (default)
+ * <button>
+ *   <Icon><Icon.Save /></Icon>
+ *   Save Changes
+ * </button>
+ *
+ * @example
+ * // ✅ Semantic icon-only button
+ * <button aria-label="Close dialog">
+ *   <Icon aria-hidden={false}>
+ *     <Icon.Remove />
+ *   </Icon>
+ * </button>
+ *
+ * @example
+ * // ❌ BAD: Icon-only button without accessible name
+ * <button>
+ *   <Icon><Icon.Remove /></Icon>
+ * </button>
+ */
 export const Icon = ({
   id,
   classes,
   children,
   styles,
+  "aria-hidden": ariaHidden = true,
+  "aria-label": ariaLabel,
+  role,
   ...props
 }: IconProps) => {
   return (
@@ -70,6 +155,9 @@ export const Icon = ({
       className={classes}
       data-icon
       data-style="icons"
+      aria-hidden={ariaHidden}
+      aria-label={ariaLabel}
+      role={role}
       {...props}
     >
       {children}

package/src/components/icons/types.ts

@@ -1,12 +1,59 @@
 import { ComponentProps } from '#/types'
 
+/**
+ * Props for individual icon SVG components (e.g., Icon.Code, Icon.Home).
+ *
+ * These props control the visual presentation of SVG icons. Icon components
+ * are decorative by default and should be wrapped in the `Icon` container
+ * component which handles accessibility concerns.
+ *
+ * @property {string} [fill] - SVG fill color (CSS color value)
+ * @property {number} [size] - Icon size in pixels (sets both width and height)
+ * @property {string} [strokeColor] - SVG stroke color (CSS color value)
+ * @property {string} [strokeWidth] - SVG stroke width (e.g., '2px', '1.5')
+ * @property {string} [role] - ARIA role (use 'img' for semantic icons)
+ * @property {string} [aria-label] - Accessible label for standalone icons
+ * @property {boolean} [aria-hidden] - Hide from screen readers (default: true via Icon wrapper)
+ * @property {string} [alt] - @deprecated Use aria-label instead. Legacy prop for accessible label.
+ * @property {number} [width] - Explicit width in pixels (overrides size)
+ * @property {number} [height] - Explicit height in pixels (overrides size)
+ *
+ * @example
+ * ```tsx
+ * // Decorative icon with custom styling
+ * <Icon>
+ *   <Icon.Code size={24} fill="blue" />
+ *   View Code
+ * </Icon>
+ *
+ * // Standalone semantic icon
+ * <Icon aria-hidden={false} aria-label="Code snippet">
+ *   <Icon.Code size={20} />
+ * </Icon>
+ * ```
+ */
 export interface IconProps extends Partial<ComponentProps> {
+  /** SVG fill color */
   fill?: string
+  /** Icon size in pixels (sets both width and height) */
   size?: number
+  /** SVG stroke color */
   strokeColor?: string
+  /** SVG stroke width */
   strokeWidth?: string
+  /** ARIA role (use 'img' for semantic icons) */
   role?: string
+  /** Accessible label (required for standalone icons) */
+  'aria-label'?: string
+  /** Hide from screen readers (default: true) */
+  'aria-hidden'?: boolean
+  /**
+   * @deprecated Use aria-label instead. This prop exists for backward compatibility.
+   * The alt attribute is only valid for img elements, not SVG.
+   */
   alt?: string
+  /** Explicit width in pixels */
   width?: number
+  /** Explicit height in pixels */
   height?: number
 }