@amedia/brick-mcp 1.0.3 → 1.0.4

package/data/components/brick-icon.md

@@ -1,9 +1,9 @@
 ---
 name: brick-icon
-version: 2.3.1
+version: 2.4.1
 selector: brick-icon-v2
 category: Media
-tags: [icon, svg, graphics, accessibility, sprite, visual]
+tags: [icon, svg, graphics, accessibility, sprite, visual, aria, breaking-news, pulse-animation]
 use_cases:
   [
     all-ui,
@@ -18,60 +18,65 @@ 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.
+A lightweight Web Component for rendering SVG icons from an embedded SVG sprite with built-in accessibility handling.
 
 ## 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
+- Renders icons from an inline SVG sprite sheet using symbol IDs
+- Automatic accessibility: hides decorative icons from screen readers, exposes meaningful icons with configurable text
+- Dynamic icon and text switching via observed attribute changes at runtime
+- Predefined size control (`small`/`medium`) through data attributes, with full CSS custom property override support
+- Customizable color via CSS custom properties (inherits `currentColor` by default)
+- Built-in pulse animation for breaking news icon (`pill-breaking`), with `color-mix()` for modern browsers and legacy fallback
 
 ## 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                                                                                          |
+| Attribute        | Type                          | Default | Required | Description                                                                                                                                                                        |
+| ---------------- | ----------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-icon-id`   | string                        | `""`    | yes      | The ID of the `<symbol>` element inside the embedded SVG sprite. Determines which icon is rendered via `<use href="#id">`.                                                         |
+| `data-icon-text` | string                        | `""`    | no       | Screen reader announcement text. When provided, the SVG gets `role="graphics-symbol"` and a `<title>` element linked via `aria-labelledby`. When omitted, the SVG is hidden from assistive technology with `aria-hidden="true"`. |
+| `data-icon-size` | `'small'` \| `'medium'` \| string | `""`    | no       | Predefined size for the icon. `'small'` maps to the `--brick-sizes-iconS` token (typically 12px). `'medium'` maps to `--brick-sizes-iconM` token (typically 24px). Custom string values are accepted but require corresponding CSS variable overrides to take effect. |
 
-## Examples
+## Usage
 
-### Basic Icon (Decorative)
+### Server-side rendering (preferred)
 
-Icon without screen reader text, suitable for decorative purposes or when paired with visible text:
+Import the render function from the `/template` submodule and call it to produce an HTML string:
 
-```html
-<brick-icon-v2 data-icon-id="chevron-right"></brick-icon-v2>
+```ts
+import { renderBrickIcon } from '@amedia/brick-icon/template';
+
+const html = renderBrickIcon({
+  dataIconId: 'play',
+  dataIconText: 'Play video',
+  dataIconSize: 'medium',
+});
 ```
 
-### Accessible Icon
+The returned HTML is a fully formed `<brick-icon-v2>` custom element with `is-rendered` and `brick-component="brick-icon"` attributes, ready for hydration on the client.
 
-Icon with screen reader text for meaningful standalone icons:
+Decorative icon (hidden from screen readers):
 
-```html
-<brick-icon-v2 data-icon-id="play" data-icon-text="Play video"> </brick-icon-v2>
+```ts
+import { renderBrickIcon } from '@amedia/brick-icon/template';
+
+const html = renderBrickIcon({
+  dataIconId: 'chevron-right',
+  dataIconSize: 'small',
+});
 ```
 
-### Sized Icon
+### Client-side (declarative HTML)
 
-Icon with predefined size:
+Use the custom element directly in HTML after registering the component:
 
 ```html
-<brick-icon-v2
-  data-icon-id="search"
-  data-icon-text="Search"
-  data-icon-size="small"
->
-</brick-icon-v2>
-```
+<script type="module" src="https://assets.acdn.no/pkg/@amedia/brick-icon/v2/brick-icon.js"></script>
 
-### Icon in Button Context
+<brick-icon-v2 data-icon-id="play" data-icon-text="Play video"></brick-icon-v2>
+```
 
-Decorative icon alongside text (hidden from screen readers):
+Decorative icon alongside visible text (no `data-icon-text` needed):
 
 ```html
 <button>
@@ -80,52 +85,23 @@ Decorative icon alongside text (hidden from screen readers):
 </button>
 ```
 
-### Breaking News Icon
-
-Special icon with pulse animation:
+Sized icon:
 
 ```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',
-});
+<brick-icon-v2
+  data-icon-id="search"
+  data-icon-text="Search"
+  data-icon-size="small"
+></brick-icon-v2>
 ```
 
-### Dynamic Icon Changes
+### Dynamic attribute changes
 
-Icons can be updated dynamically via attribute changes:
+Both `data-icon-id` and `data-icon-text` are observed attributes. Changing them at runtime updates the rendered SVG immediately without re-creating the element:
 
-```javascript
+```js
 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');
 ```
 
@@ -133,7 +109,7 @@ icon.setAttribute('data-icon-text', 'Collapse section');
 
 ### 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.
+`brick-icon` requires an SVG sprite to be embedded in the HTML page. The sprite must contain `<symbol>` elements whose `id` attributes match the `data-icon-id` values used on the component.
 
 ```html
 <svg style="display: none;">
@@ -146,32 +122,24 @@ brick-icon requires an SVG sprite to be embedded in the HTML page. The sprite mu
 </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
+The `@amedia/brick-icons` package provides theme-specific SVG sprites maintained in Figma.
 
 ## Accessibility
 
-### Automatic ARIA Handling
+### 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)
+- **With `data-icon-text`**: The inner `<svg>` receives `role="graphics-symbol"` and `aria-labelledby` pointing to a `<title>` element that contains the provided text. Screen readers announce the icon text.
+- **Without `data-icon-text`**: The inner `<svg>` receives `aria-hidden="true"`, completely hiding the icon from the accessibility tree. Use this for decorative icons or when adjacent visible text already conveys the meaning.
 
-### VoiceOver Compatibility
+### Reduced motion
 
-Icons include `aria-labelledby` attributes for proper announcement in Safari with VoiceOver.
+The breaking news pulse animation respects `prefers-reduced-motion` and disables itself when the user preference is set.
 
-### Best Practices
+### 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
+- Omit `data-icon-text` for purely decorative icons or when surrounding text provides the same information.
+- Always provide `data-icon-text` for standalone meaningful icons (e.g., an icon-only button must have icon text or an `aria-label` on the button).
+- Ensure color contrast meets WCAG 2.1 AA when customizing icon colors.
 
 ## Styling
 
@@ -180,22 +148,22 @@ Icons include `aria-labelledby` attributes for proper announcement in Safari wit
 | 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-size`                      | Container and default SVG size (height)   | `var(--brick-sizes-iconM)` (24px)          |
+| `--b-icon-svg-width`                 | SVG element width                         | Inherits from `--b-icon-size`              |
+| `--b-icon-svg-height`                | SVG element height                        | Inherits from `--b-icon-size`              |
 | `--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
+### Custom sizing example
 
 ```css
-brick-icon-v2[data-icon-id='custom-large'] {
+brick-icon-v2[data-icon-id="custom-large"] {
   --b-icon-svg-width: 48px;
   --b-icon-svg-height: 48px;
 }
 ```
 
-### Color Customization
+### Color customization
 
 ```css
 brick-icon-v2 {
@@ -203,26 +171,7 @@ brick-icon-v2 {
 }
 ```
 
-## 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
+### Responsive sizing
 
 ```css
 brick-icon-v2 {
@@ -238,37 +187,41 @@ brick-icon-v2 {
 
 ## 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`
+- **Package version**: `2.4.1`
+- **Custom Element tag**: `brick-icon-v2` -- must match the `selector` in frontmatter; the tag uses only the **major** version, not the full semver
+- **Base class**: `BrickElement` (from `@amedia/brick-template`)
+- **Dependencies**: `@amedia/brick-tokens@6.2.2`, `@amedia/brick-template@2.1.0`
+- **Observed attributes** (trigger `attributeChangedCallback`): `data-icon-id`, `data-icon-text`
+- **Mirrored props**: `data-icon-id`, `data-icon-text`, `data-icon-size`
+- **SSR submodule**: `@amedia/brick-icon/template` exports `renderBrickIcon`, `iconStyle`, `iconContainerStyle`
+- **Build target**: ES2020 + Safari 15
 
 ## Important Notes
 
-### Version 2 Breaking Changes
+### SVG sprite must be present in the DOM
+
+The component references icons via `<use href="#iconId">`. If the SVG sprite containing the corresponding `<symbol>` is not embedded in the page, no icon will be visible. There is no external sprite loading or error indication.
 
-Version 2.0.0 introduced breaking changes:
+### Version 2 breaking changes (from v1)
 
-- 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
+- Tag name changed to `brick-icon-v2` (previously `brick-icon`)
+- Requires embedded SVG sprite in HTML (external sprite loading was removed)
+- The `theme` property was removed
+- CommonJS build was removed; ESM only
 
-### Size Control
+### Size control
 
-The `data-icon-size` attribute sets predefined sizes:
+The `data-icon-size` attribute triggers predefined CSS overrides:
 
-- `small`: Uses `--brick-sizes-iconS` token (typically 16px)
-- `medium`: Uses `--brick-sizes-iconM` token (typically 24px)
+- `small`: Uses `--brick-sizes-iconS` token (fallback 12px)
+- `medium`: Uses `--brick-sizes-iconM` token (fallback 24px)
 
-For custom sizes, use CSS custom properties instead.
+For sizes outside these presets, use CSS custom properties directly.
 
-### Breaking News Animation
+### 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.
+The icon with `data-icon-id="pill-breaking"` has a pulse animation. Since version 2.4.0, the animation uses CSS `color-mix()` on browsers that support it, with an automatic fallback to dedicated pulse color variables (`--b-icon-color-breaking-pulseStart`, `--b-icon-color-breaking-pulseEnd`) for older browsers. The animation is disabled when the user has `prefers-reduced-motion` enabled.
 
-## Version
+### `data-icon-size` is not an observed attribute
 
-Current version: 2.3.1
+Only `data-icon-id` and `data-icon-text` are in the `observedAttributes` list. Changing `data-icon-size` after the element has connected does not trigger an automatic re-render of size styles. Set it before the element connects, or update the CSS custom properties directly.