@amedia/brick-mcp 0.0.2 → 0.1.1

package/dist/data/components/brick-icon.md

@@ -0,0 +1,274 @@
+---
+name: brick-icon
+version: 2.3.1
+selector: brick-icon-v2
+category: Media
+tags: [icon, svg, graphics, accessibility, sprite, visual]
+use_cases:
+  [
+    all-ui,
+    navigation,
+    buttons,
+    visual-indicators,
+    status-display,
+    content-decoration,
+  ]
+related: [brick-button, brick-pill, brick-avatar]
+---
+
+# Brick Icon
+
+A lightweight Web Component for rendering SVG icons from an embedded SVG sprite with built-in accessibility features.
+
+## Key Capabilities
+
+- Renders icons from an inline SVG sprite using icon IDs
+- Automatic accessibility handling with configurable screen reader text
+- Dynamic icon switching via attribute changes
+- Size control through data attributes or CSS variables
+- Color customization via CSS custom properties
+- Special animation support for breaking news icon
+- Framework-agnostic Web Component
+
+## Props/Attributes
+
+| Attribute        | Type                          | Default  | Required | Description                                                                                                                                                                        |
+| ---------------- | ----------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-icon-id`   | string                        | -        | yes      | The ID of the SVG symbol inside the embedded SVG sprite                                                                                                                            |
+| `data-icon-text` | string                        | -        | no       | Screen reader announcement text. When provided, icon gets `role="graphics-symbol"` and a `<title>` tag. When omitted, icon is hidden from screen readers with `aria-hidden="true"` |
+| `data-icon-size` | 'small' \| 'medium' \| string | 'medium' | no       | Predefined size for the icon container. 'small' or 'medium' values use token-based sizing                                                                                          |
+
+## Examples
+
+### Basic Icon (Decorative)
+
+Icon without screen reader text, suitable for decorative purposes or when paired with visible text:
+
+```html
+<brick-icon-v2 data-icon-id="chevron-right"></brick-icon-v2>
+```
+
+### Accessible Icon
+
+Icon with screen reader text for meaningful standalone icons:
+
+```html
+<brick-icon-v2 data-icon-id="play" data-icon-text="Play video"> </brick-icon-v2>
+```
+
+### Sized Icon
+
+Icon with predefined size:
+
+```html
+<brick-icon-v2
+  data-icon-id="search"
+  data-icon-text="Search"
+  data-icon-size="small"
+>
+</brick-icon-v2>
+```
+
+### Icon in Button Context
+
+Decorative icon alongside text (hidden from screen readers):
+
+```html
+<button>
+  <brick-icon-v2 data-icon-id="play"></brick-icon-v2>
+  Play
+</button>
+```
+
+### Breaking News Icon
+
+Special icon with pulse animation:
+
+```html
+<brick-icon-v2 data-icon-id="pill-breaking" data-icon-text="Breaking news">
+</brick-icon-v2>
+```
+
+## Programmatic Usage
+
+### Client-Side Rendering
+
+```javascript
+import '@amedia/brick-icon';
+
+// The custom element defines itself automatically
+const icon = document.createElement('brick-icon-v2');
+icon.setAttribute('data-icon-id', 'chevron-right');
+icon.setAttribute('data-icon-text', 'Navigate right');
+document.body.appendChild(icon);
+```
+
+### Server-Side Rendering
+
+```javascript
+import { renderBrickIcon } from '@amedia/brick-icon/template';
+
+const html = renderBrickIcon({
+  dataIconId: 'play',
+  dataIconText: 'Play video',
+  dataIconSize: 'medium',
+});
+```
+
+### Dynamic Icon Changes
+
+Icons can be updated dynamically via attribute changes:
+
+```javascript
+const icon = document.querySelector('brick-icon-v2');
+
+// Update icon ID
+icon.setAttribute('data-icon-id', 'chevron-up');
+
+// Update screen reader text
+icon.setAttribute('data-icon-text', 'Collapse section');
+```
+
+## Prerequisites
+
+### SVG Sprite Requirement
+
+brick-icon requires an SVG sprite to be embedded in the HTML page. The sprite must contain `<symbol>` elements with IDs matching the `data-icon-id` values.
+
+```html
+<svg style="display: none;">
+  <symbol id="play" viewBox="0 0 24 24">
+    <path d="..." />
+  </symbol>
+  <symbol id="chevron-right" viewBox="0 0 24 24">
+    <path d="..." />
+  </symbol>
+</svg>
+```
+
+Check out `@amedia/brick-icons` package which provides theme-specific SVG sprites maintained in Figma.
+
+### Why Inline SVG Sprite
+
+- Eliminates additional network requests
+- Simpler implementation without asynchronous loading
+- Icons available immediately when HTML is parsed
+- Better perceived performance
+- Optimal for small to medium icon sets
+
+## Accessibility
+
+### Automatic ARIA Handling
+
+- **With `data-icon-text`**: Icon receives `role="graphics-symbol"` and a `<title>` element with the provided text, making it accessible to screen readers
+- **Without `data-icon-text`**: Icon receives `aria-hidden="true"`, hiding it from screen readers (appropriate for decorative icons)
+
+### VoiceOver Compatibility
+
+Icons include `aria-labelledby` attributes for proper announcement in Safari with VoiceOver.
+
+### Best Practices
+
+- Omit `data-icon-text` for decorative icons or when adjacent text provides context
+- Always provide `data-icon-text` for standalone interactive icons
+- Ensure color contrast meets WCAG 2.1 AA requirements when customizing colors
+
+## Styling
+
+### CSS Custom Properties
+
+| Property                             | Description                               | Default                                    |
+| ------------------------------------ | ----------------------------------------- | ------------------------------------------ |
+| `--b-icon-color`                     | Icon fill color                           | `currentColor`                             |
+| `--b-icon-size`                      | Container size (height)                   | `var(--brick-sizes-iconM)` (24px)          |
+| `--b-icon-svg-width`                 | SVG element width                         | `var(--brick-sizes-iconM)` (24px)          |
+| `--b-icon-svg-height`                | SVG element height                        | `var(--brick-sizes-iconM)` (24px)          |
+| `--b-icon-color-breaking-pulseStart` | Breaking icon pulse animation start color | `var(--brick-colors-pillNonePulseStartBg)` |
+| `--b-icon-color-breaking-pulseEnd`   | Breaking icon pulse animation end color   | `var(--brick-colors-pillNonePulseEndBg)`   |
+
+### Custom Sizing Example
+
+```css
+brick-icon-v2[data-icon-id='custom-large'] {
+  --b-icon-svg-width: 48px;
+  --b-icon-svg-height: 48px;
+}
+```
+
+### Color Customization
+
+```css
+brick-icon-v2 {
+  --b-icon-color: #007bff;
+}
+```
+
+## Common Patterns
+
+### Icon with Adjacent Text
+
+```html
+<a href="/search">
+  <brick-icon-v2 data-icon-id="search"></brick-icon-v2>
+  Search
+</a>
+```
+
+### Icon-Only Button
+
+```html
+<button aria-label="Close dialog">
+  <brick-icon-v2 data-icon-id="close" data-icon-text="Close"> </brick-icon-v2>
+</button>
+```
+
+### Responsive Icon Sizing
+
+```css
+brick-icon-v2 {
+  --b-icon-size: 16px;
+}
+
+@media (min-width: 768px) {
+  brick-icon-v2 {
+    --b-icon-size: 24px;
+  }
+}
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-icon-v2`
+- **Base Class**: BrickElement
+- **Dependencies**: @amedia/brick-tokens, @amedia/brick-template
+- **Renders as**: `<brick-icon-v2>` container with internal `<svg>` element
+- **Observed Attributes**: `data-icon-id`, `data-icon-text`
+- **Mirrored Props**: `data-icon-id`, `data-icon-text`, `data-icon-size`
+
+## Important Notes
+
+### Version 2 Breaking Changes
+
+Version 2.0.0 introduced breaking changes:
+
+- New tag name: `brick-icon-v2` (previously `brick-icon`)
+- Requires embedded SVG sprite in HTML (no external sprite loading)
+- Removed `theme` property (no longer needed)
+- Removed CommonJS build
+
+### Size Control
+
+The `data-icon-size` attribute sets predefined sizes:
+
+- `small`: Uses `--brick-sizes-iconS` token (typically 16px)
+- `medium`: Uses `--brick-sizes-iconM` token (typically 24px)
+
+For custom sizes, use CSS custom properties instead.
+
+### Breaking News Animation
+
+The icon with `data-icon-id="pill-breaking"` includes a special pulsing animation controlled by the `--b-icon-color-breaking-pulseStart` and `--b-icon-color-breaking-pulseEnd` CSS variables.
+
+## Version
+
+Current version: 2.3.1