@amedia/brick-mcp 0.0.1-LLM-DOCS → 0.0.1-NEW-PATH-1

package/data/components/brick-avatar.md

@@ -1,265 +0,0 @@
----
-name: brick-avatar
-version: 0.2.36
-selector: brick-avatar-v0
-category: Media
-tags: [avatar, profile, user, image, initials, icon, identity, media]
-use_cases: [user-profiles, author-bylines, comment-sections, team-rosters, sports-teams, contact-lists, chat-interfaces, social-features]
-related: [brick-image, brick-tokens]
----
-
-# Brick Avatar
-
-A visual component representing a person, object, or entity through an image, icon, or initials.
-
-## Key Capabilities
-
-- Display user profile images with automatic fallback to initials
-- Support for multiple sizes (small, medium, large) and shapes (default theme, circle)
-- Decorative letter shapes for sports teams and organizations (shield, t-shirt)
-- Custom CSS property support for SVG backgrounds
-- Accessible implementation with proper alt text handling
-- Server-side rendering support for optimal performance
-
-## Props/Attributes
-
-| Attribute | Type | Default | Required | Description |
-|-----------|------|---------|----------|-------------|
-| `data-img` | string | "" | no | URL for the avatar image. Preferably a square image (cropped from top if not square) |
-| `data-letters` | string | "" | no | One or two letter string used as initials when image is not provided or fails to load |
-| `data-alt` | string | "" | no | Alternative text for images or screen reader text for letter avatars. Empty string hides decorative avatars from assistive technology |
-| `data-size` | "small" \| "medium" \| "large" | "medium" | no | Controls the size of the avatar using design tokens |
-| `data-shape` | "circle" \| "" | "" | no | Sets the avatar shape. Empty string uses theme default avatar shape |
-| `data-letters-shape` | "shield" \| "tshirt" \| "" | "" | no | Adds a background shape behind letters. Only applies when using `data-letters`, not with `data-img` |
-
-## Examples
-
-### Basic Avatar with Initials
-Display user initials as a fallback or primary identifier.
-
-```html
-<brick-avatar-v0
-  data-letters="AM"
-  data-alt="Initials for Amedia"
-  data-size="medium">
-</brick-avatar-v0>
-```
-
-### Avatar with Image
-Show a profile photo with automatic fallback to initials if image fails.
-
-```html
-<brick-avatar-v0
-  data-img="https://example.com/profile-photo.jpg"
-  data-alt="Profile picture of John Doe"
-  data-letters="JD"
-  data-size="large">
-</brick-avatar-v0>
-```
-
-### Circle Avatar for User Profiles
-Use circle shape for a softer, more personal feel in user interfaces.
-
-```html
-<brick-avatar-v0
-  data-img="https://example.com/user-avatar.jpg"
-  data-alt="User profile picture"
-  data-shape="circle"
-  data-size="medium">
-</brick-avatar-v0>
-```
-
-### Sports Team Avatar with Shield
-Display team initials with a shield background, commonly used in sports applications.
-
-```html
-<brick-avatar-v0
-  data-letters="BSK"
-  data-alt="Bærum Sportsklubb team logo"
-  data-letters-shape="shield"
-  data-size="medium"
-  style="--b-avatar-color-fg:var(--brick-colors-supportiveSportFg);
-         --b-avatar-color-border:var(--brick-colors-supportiveSportBg);
-         --b-avatar-color-shape:var(--brick-colors-supportiveSportBg);">
-</brick-avatar-v0>
-```
-
-### Team Avatar with T-Shirt Shape
-Use t-shirt shape for team jerseys or sports team identification.
-
-```html
-<brick-avatar-v0
-  data-letters="T"
-  data-alt="Team T jersey"
-  data-letters-shape="tshirt"
-  data-size="large"
-  style="--b-avatar-color-fg:var(--brick-colors-supportiveSportFg);
-         --b-avatar-color-shape:red;">
-</brick-avatar-v0>
-```
-
-### Avatar with SVG Background
-Set a custom SVG as the avatar background using CSS custom property.
-
-```html
-<brick-avatar-v0
-  data-alt="Organization logo"
-  data-size="small"
-  style="--b-avatar-borderWidth:0;
-         --b-avatar-svg:url('https://example.com/logo.svg')">
-</brick-avatar-v0>
-```
-
-### Decorative Avatar (No Alt Text)
-For purely decorative avatars where information is conveyed elsewhere, omit `data-alt` for accessibility.
-
-```html
-<brick-avatar-v0
-  data-img="https://example.com/decorative-icon.jpg"
-  data-size="small">
-</brick-avatar-v0>
-```
-
-## Server-Side Rendering
-
-### Render Function
-Use the template function for optimal server-side rendering performance.
-
-```javascript
-import { renderBrickAvatar } from '@amedia/brick-avatar/template';
-
-const markup = renderBrickAvatar({
-  dataLetters: 'KN',
-  dataAlttext: 'Initials for Kari Nordmann',
-  dataSize: 'medium'
-});
-```
-
-### Client-Side Import
-Import the web component definition for client-side hydration and interactivity.
-
-```javascript
-import '@amedia/brick-avatar';
-```
-
-## CSS Custom Properties
-
-Customize the avatar appearance using CSS custom properties. Always scope your overrides and ensure WCAG 2.1 AA compliance.
-
-| Property | Description | Default |
-|----------|-------------|---------|
-| `--b-avatar-svg` | Set the background SVG image using `url()` notation | None |
-| `--b-avatar-size` | Controls the size (prefer using `data-size` attribute) | `var(--brick-sizes-avatarM)` |
-| `--b-avatar-color-bg` | Background color for letter avatars | `var(--brick-colors-baseNeutral00)` |
-| `--b-avatar-color-fg` | Text color for letter avatars | `var(--brick-colors-baseFg)` |
-| `--b-avatar-color-border` | Border color | `var(--brick-colors-baseNeutral00)` |
-| `--b-avatar-color-shape` | Background color for letter shapes (shield, t-shirt) | `transparent` |
-| `--b-avatar-borderWidth` | Border width | `var(--brick-borderWidths-baseS)` |
-| `--b-avatar-padding` | Internal padding | `0` |
-
-### Custom Styling Example
-```html
-<brick-avatar-v0
-  data-img="https://api.nifs.no/images/teams/logo/8/"
-  data-size="large"
-  style="--b-avatar-padding:10px;
-         --b-avatar-size:120px;
-         --b-avatar-color-bg:var(--brick-colors-supportiveSportBg);
-         --b-avatar-color-fg:var(--brick-colors-supportiveSportFg);
-         --b-avatar-color-border:transparent;">
-</brick-avatar-v0>
-```
-
-## Accessibility
-
-### Image Avatars
-- Always provide `data-alt` for informative images describing the person or entity
-- Omit `data-alt` for purely decorative avatars (automatically gets empty alt attribute)
-- Screen readers will ignore decorative images with empty alt text
-
-### Letter Avatars
-- The `data-alt` property creates a visually hidden element for screen readers
-- Provides context for abbreviated initials (e.g., "KN" becomes "Initials for Kari Nordmann")
-- Ensures users with assistive technology understand the meaning of the letters
-
-### Keyboard Navigation
-- Avatar component is non-interactive by default
-- If wrapped in an interactive element (button, link), ensure proper focus states
-
-## Common Patterns
-
-### Author Byline
-Display author information in article headers or comments.
-
-```html
-<div class="author-byline">
-  <brick-avatar-v0
-    data-img="https://example.com/author.jpg"
-    data-alt="Photo of Jane Smith"
-    data-letters="JS"
-    data-size="small"
-    data-shape="circle">
-  </brick-avatar-v0>
-  <span class="author-name">Jane Smith</span>
-</div>
-```
-
-### User List
-Show multiple users in a team or contact list.
-
-```html
-<ul class="user-list">
-  <li>
-    <brick-avatar-v0
-      data-letters="AM"
-      data-alt="Amedia"
-      data-size="medium">
-    </brick-avatar-v0>
-    <span>Amedia</span>
-  </li>
-  <li>
-    <brick-avatar-v0
-      data-letters="KN"
-      data-alt="Kari Nordmann"
-      data-size="medium">
-    </brick-avatar-v0>
-    <span>Kari Nordmann</span>
-  </li>
-</ul>
-```
-
-### Sports Team Roster
-Display team members with jersey-style avatars.
-
-```html
-<div class="team-roster">
-  <brick-avatar-v0
-    data-letters="10"
-    data-alt="Player number 10"
-    data-letters-shape="tshirt"
-    data-size="large"
-    style="--b-avatar-color-shape:#003366;
-           --b-avatar-color-fg:#ffffff;">
-  </brick-avatar-v0>
-</div>
-```
-
-## Technical Details
-
-- **Custom Element**: `brick-avatar-v0`
-- **Base Class**: BrickElement (from @amedia/brick-template)
-- **Dependencies**: @amedia/brick-tokens, @amedia/brick-image
-- **Renders as**: Custom element with internal image or text content
-- **Browser Support**: All modern browsers supporting Custom Elements v1
-
-## Important Notes
-
-- Images should preferably be square for best results; non-square images are cropped from the top
-- The `data-letters-shape` attribute only works with letter avatars, not image avatars
-- Custom CSS properties override default theme values; ensure color contrast meets WCAG 2.1 AA standards
-- When using `--b-avatar-svg`, the image is set as a background and will not have alt text for accessibility
-- Server-side rendering is recommended for optimal performance and SEO
-
-## Version
-
-Current version: 0.2.36

package/data/components/brick-button.md

@@ -1,364 +0,0 @@
----
-name: brick-button
-version: 9.3.1
-selector: brick-button-v9
-category: Forms
-tags: [button, cta, action, interactive, link, form-control]
-use_cases: [forms, call-to-action, navigation, user-interaction, authentication, checkout, product-listing, modal-triggers]
-related: [brick-icon, brick-tokens]
----
-
-# Brick Button
-
-A customizable, accessible button component that supports multiple visual variants, sizes, and can render as either a button or link element.
-
-## Key Capabilities
-
-- Three visual variants: primary, secondary, and outlined
-- Renders as `<button>` or `<a>` based on presence of `data-linkto` attribute
-- Two size options: small and medium
-- Icon support with configurable placement (left, right, top)
-- Full ARIA attribute support for accessibility
-- CSS custom properties for styling customization
-- Analytics integration via ADP attributes
-- Framework-agnostic web component with SSR support
-
-## Props/Attributes
-
-| Attribute | Type | Default | Required | Description |
-|-----------|------|---------|----------|-------------|
-| `data-label` | string | - | yes | Button text/label |
-| `data-version` | `'primary' \| 'secondary' \| 'outlined'` | `'primary'` | no | Visual style variant |
-| `data-size` | `'small' \| 'medium'` | `'medium'` | no | Button size |
-| `data-linkto` | string | - | no | URL to navigate to. When set, renders as `<a>` tag |
-| `data-target` | string | - | no | Link target (e.g., `_blank` for new tab) |
-| `data-icon-id` | string | - | no | ID of icon from brick-icon to display |
-| `data-iconplacement` | `'top' \| 'right' \| 'left'` | `'left'` | no | Position of icon relative to label |
-| `data-icontext` | string | - | no | Alternative text for icon |
-| `data-disabled` | string | - | no | Disables the button when set to "true" |
-| `data-as` | `'span' \| 'div'` | - | no | Renders as non-interactive element (for use with framework routers) |
-| `data-adplabel` | string | - | no | ADP analytics click label |
-| `data-adpvalue` | string | - | no | ADP analytics click value |
-| `data-aria-label` | string | - | no | ARIA label for accessibility |
-| `data-aria-labelledby` | string | - | no | ID of element that labels this button |
-| `data-aria-describedby` | string | - | no | ID of element that describes this button |
-| `data-aria-controls` | string | - | no | ID of element controlled by this button |
-| `data-aria-expanded` | string | - | no | Indicates if controlled element is expanded |
-| `data-aria-pressed` | string | - | no | Indicates pressed state for toggle buttons |
-
-## Examples
-
-### Basic Button
-
-```html
-<brick-button-v9
-  data-label="Click me"
-  data-version="primary">
-</brick-button-v9>
-```
-
-### Button Variants
-
-```html
-<!-- Primary button -->
-<brick-button-v9
-  data-label="Primary Action"
-  data-version="primary">
-</brick-button-v9>
-
-<!-- Secondary button -->
-<brick-button-v9
-  data-label="Secondary Action"
-  data-version="secondary">
-</brick-button-v9>
-
-<!-- Outlined button -->
-<brick-button-v9
-  data-label="Outlined Action"
-  data-version="outlined">
-</brick-button-v9>
-```
-
-### Button as Link
-
-```html
-<brick-button-v9
-  data-label="Visit Amedia"
-  data-version="primary"
-  data-linkto="https://www.amedia.no"
-  data-target="_blank">
-</brick-button-v9>
-```
-
-### Button with Icon
-
-```html
-<brick-button-v9
-  data-label="Search"
-  data-version="primary"
-  data-icon-id="search"
-  data-iconplacement="left">
-</brick-button-v9>
-
-<!-- Icon-only button -->
-<brick-button-v9
-  data-icon-id="menu"
-  data-aria-label="Open menu">
-</brick-button-v9>
-```
-
-### Small Button
-
-```html
-<brick-button-v9
-  data-label="Small Action"
-  data-version="secondary"
-  data-size="small">
-</brick-button-v9>
-```
-
-### Disabled Button
-
-```html
-<brick-button-v9
-  data-label="Disabled"
-  data-version="primary"
-  data-disabled="true">
-</brick-button-v9>
-```
-
-## Framework Integration
-
-### Svelte
-
-```svelte
-<script>
-  import '@amedia/brick-button';
-
-  function handleClick() {
-    console.log('Button clicked!');
-  }
-</script>
-
-<!-- svelte-ignore a11y_click_events_have_key_events -->
-<!-- svelte-ignore a11y_no_static_element_interactions -->
-<brick-button-v9
-  data-label="Click me"
-  data-version="primary"
-  onclick={handleClick}
-/>
-```
-
-### Using with Framework Routers
-
-When using with framework routers (like svelte-routing), use `data-as` to render as a non-interactive element:
-
-```svelte
-<script>
-  import { Link } from 'svelte-routing';
-</script>
-
-<Link to="/offers">
-  <brick-button-v9
-    data-label="See other subscriptions"
-    data-version="outlined"
-    data-as="span"
-  />
-</Link>
-```
-
-### React/Vue
-
-```javascript
-import '@amedia/brick-button';
-
-// React
-function MyComponent() {
-  return (
-    <brick-button-v9
-      data-label="Click me"
-      data-version="primary"
-      onClick={() => console.log('clicked')}
-    />
-  );
-}
-
-// Vue
-<template>
-  <brick-button-v9
-    data-label="Click me"
-    data-version="primary"
-    @click="handleClick"
-  />
-</template>
-```
-
-## Programmatic Usage
-
-```javascript
-import { BrickButton } from '@amedia/brick-button';
-
-const button = new BrickButton({
-  dataLabel: 'My Button',
-  dataVersion: 'primary',
-  dataSize: 'medium'
-});
-
-// Set click handler
-button.onClick = (event) => {
-  console.log('Button clicked!', event);
-};
-
-// Add to DOM
-document.body.appendChild(button);
-
-// Programmatically focus the button
-button.focus();
-```
-
-## Server-Side Rendering
-
-```javascript
-import { renderBrickButton } from '@amedia/brick-button/template';
-
-const buttonHTML = renderBrickButton({
-  dataLabel: 'Server Rendered',
-  dataVersion: 'primary',
-  dataLinkto: '/page'
-});
-
-// Include CSS file
-// <link rel="stylesheet" href="https://assets.acdn.no/pkg/@amedia/brick-button/v9/css/styles.css">
-```
-
-## Accessibility
-
-- Adheres to **WCAG 2.1 AA** guidelines
-- Full ARIA attributes support for screen readers
-- Keyboard navigation support (Enter/Space for buttons, Enter for links)
-- Focus visible states with clear outline
-- Disabled state prevents interaction and is communicated to assistive technology
-- Icon-only buttons require `data-aria-label` for proper accessibility
-- Proper semantic HTML (`<button>` vs `<a>`) based on behavior
-
-## Analytics Integration
-
-Brick-button supports ADP (Amedia Data Platform) tracking:
-
-```html
-<brick-button-v9
-  data-label="Subscribe Now"
-  data-version="primary"
-  data-adplabel="Subscribe CTA"
-  data-adpvalue="homepage-hero">
-</brick-button-v9>
-```
-
-## Common Patterns
-
-### Call-to-Action Button
-
-```html
-<brick-button-v9
-  data-label="Start Free Trial"
-  data-version="primary"
-  data-size="medium"
-  data-adplabel="CTA - Free Trial">
-</brick-button-v9>
-```
-
-### Modal Trigger with ARIA
-
-```html
-<brick-button-v9
-  data-label="Open Settings"
-  data-version="secondary"
-  data-aria-controls="settings-modal"
-  data-aria-expanded="false"
-  data-icon-id="settings">
-</brick-button-v9>
-```
-
-### Toggle Button
-
-```html
-<brick-button-v9
-  data-label="Follow"
-  data-version="outlined"
-  data-aria-pressed="false">
-</brick-button-v9>
-```
-
-### Navigation with Icon
-
-```html
-<brick-button-v9
-  data-label="Next"
-  data-version="primary"
-  data-linkto="/next-page"
-  data-icon-id="arrow-right"
-  data-iconplacement="right">
-</brick-button-v9>
-```
-
-## Styling and CSS Properties
-
-Customize button appearance using CSS custom properties:
-
-```css
-brick-button-v9 {
-  /* Width control */
-  --b-button-width: 100%;
-
-  /* Height control */
-  --b-button-height: 3rem;
-
-  /* Border width */
-  --b-button-border: 2px;
-
-  /* Border radius */
-  --b-button-radii: 8px;
-
-  /* Content alignment */
-  --b-button-justify: flex-start;
-}
-```
-
-### Color Overrides
-
-```css
-brick-button-v9 {
-  /* Primary button colors */
-  --brick-colors-buttonPrimaryBg: var(--brick-colors-utilityWarningBg);
-  --brick-colors-buttonPrimaryHoverBg: var(--brick-colors-utilityWarningBg);
-  --brick-colors-buttonPrimaryActiveBg: var(--brick-colors-utilityWarningBg);
-  --brick-colors-buttonPrimaryFg: var(--brick-colors-utilityWarningFg);
-}
-```
-
-**Note:** When overriding colors, ensure your customizations adhere to WCAG 2.1 AA contrast requirements.
-
-## Technical Details
-
-- **Custom Element**: `brick-button-v9`
-- **Base Class**: BrickElement
-- **Dependencies**:
-  - @amedia/brick-tokens (design tokens)
-  - @amedia/brick-icon (icon support)
-  - @amedia/brick-template (base class)
-- **Renders as**: `<button>` (default) or `<a>` (when data-linkto is set) or `<span>`/`<div>` (when data-as is set)
-- **SSR Compatible**: Yes, with hydration support
-- **Framework**: Framework-agnostic web component
-
-## Important Notes
-
-- When `data-linkto` is provided, the component renders as an `<a>` tag; otherwise, it renders as a `<button>` tag
-- When `data-as` is set to `span` or `div`, renders as non-interactive element (useful for wrapping with framework router components)
-- Icon-only buttons automatically get rounded background styling
-- The component observes attribute changes and updates the DOM reactively for `data-label`, `data-icon-id`, `data-icontext`, `data-linkto`, and all ARIA attributes
-- Do not nest interactive elements inside brick-button when using framework routers - use `data-as` instead
-- Version 9.0.0 removed CommonJS support and changed `data-iconid` to `data-icon-id`
-
-## Version
-
-Current version: 9.3.1