@reliability-design/web 1.0.3 → 1.0.6

package/dist/components/rel-accordion/README.md

@@ -0,0 +1,132 @@
+# rel-accordion
+
+## Overview
+An animated accordion component with a collapsible body section. Features a clickable header with chevron icon rotation, smooth expand/collapse transitions, and keyboard support. Respects reduced motion preferences.
+
+## Usage
+```html
+<!-- Basic accordion -->
+<rel-accordion title="Section 1">
+  <p>This is the content of section 1.</p>
+</rel-accordion>
+
+<!-- Initially open -->
+<rel-accordion title="FAQ: How does it work?" open>
+  <p>This accordion starts in the open state.</p>
+  <ul>
+    <li>Bullet 1</li>
+    <li>Bullet 2</li>
+  </ul>
+</rel-accordion>
+
+<!-- Multiple accordions -->
+<rel-accordion title="Introduction">
+  <p>Introduction content...</p>
+</rel-accordion>
+<rel-accordion title="Features">
+  <p>Features content...</p>
+</rel-accordion>
+<rel-accordion title="Pricing">
+  <p>Pricing content...</p>
+</rel-accordion>
+
+<!-- Listen for open state changes -->
+<rel-accordion id="myAccordion" title="Details"></rel-accordion>
+<script>
+  const accordion = document.getElementById('myAccordion');
+  accordion.addEventListener('open-change', (e) => {
+    console.log('Accordion open:', e.detail); // true or false
+  });
+</script>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `"Accordion"` | Header title text |
+| `open` (reflected) | `boolean` | `false` | Whether the accordion is expanded |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `open-change` | `boolean` | Fired when the accordion is toggled (detail is the new `open` state) |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | Accordion body content |
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+
+### Font Tokens
+- `--rel-fontSizes-lg` - Title font size (20px)
+- `--rel-fontSizes-md` - Body font size (14px)
+- `--rel-fontWeights-medium` - Title font weight (500)
+
+### Color Tokens
+- `--rel-colors-white` - Background color
+- `--rel-text-heading` - Title text color
+- `--rel-text-primary` - Body text color, icon stroke color
+- `--rel-border-default` - Border color
+- `--rel-border-info` - Focus outline color
+
+### Shadow Tokens
+- `--rel-shadows-shadow-100` - Shadow
+
+### Border Tokens
+- `--rel-borders-radius-border-radius-200` - Border radius (8px)
+
+### Spacing Tokens
+- `--rel-spacing-space-md` - Header horizontal padding, body horizontal padding in closed state (16px)
+- `--rel-spacing-space-xl` - Body top padding when open (24px)
+- `--rel-spacing-space-lg` - Body bottom padding when open (20px)
+
+## Accessibility
+- Header uses `role="button"` and `aria-expanded` attribute
+- Header is keyboard accessible with `tabindex="0"`
+- Supports Enter and Space key activation
+- Focus visible outline on keyboard focus
+
+### Keyboard Interactions
+| Key | Action |
+|-----|--------|
+| `Enter` | Toggle accordion open/closed |
+| `Space` | Toggle accordion open/closed |
+| `Tab` | Navigate to/from the header |
+
+### Focus Behavior
+- Header receives focus outline (`outline: 2px solid --rel-border-info`)
+- Focus offset is `-2px` inset
+
+## Notes / Edge Cases
+- **Animation details**:
+  - Chevron rotates 180° when open (`transform: rotate(180deg)`)
+  - Body expands from `max-height: 0` to `max-height: 1000px`
+  - Body padding animates from `0` to full padding when opening
+  - Transitions: `transform 0.25s ease`, `max-height 0.25s ease`, `padding 0.2s ease`
+
+- **Reduced motion**: When `prefers-reduced-motion: reduce`, icon rotation and body transitions are disabled
+
+- **Body rendering**: The slotted content is always in the DOM (not conditionally rendered), but hidden via `max-height: 0` and `overflow: hidden` when closed
+
+- The header has hover styling (`background: --rel-surface-surface`)
+
+- The component is `display: block` and `width: 100%`
+
+- The accordion border is `1px solid` with rounded corners
+
+- The chevron icon is an inline SVG (9-point downward-pointing chevron)
+
+- When closed, the body has `padding: 0 var(--rel-spacing-space-md)` to maintain horizontal padding
+
+- The `open` attribute is reflected in HTML when set
+
+- Multiple accordions can be open simultaneously (no automatic closing of others)

package/dist/components/rel-accordion/rel-accordion.ts

@@ -10,13 +10,13 @@ export class RelAccordion extends LitElement {
     :host {
       display: block;
       width: 100%;
-      font-family: var(--rel-fontFamilies-primary);
+      font-family: var(--rel-fontFamilies-primary, sans-serif);
     }
 
     .accordion {
-      background: var(--rel-colors-white);
-      border: 1px solid var(--rel-border-default);
-      border-radius: var(--rel-borders-radius-border-radius-200);
+      background: var(--rel-colors-white, #fff);
+      border: 1px solid var(--rel-border-default, #ddd);
+      border-radius: var(--rel-borders-radius-border-radius-200, 8px);
       box-shadow: var(--rel-shadows-shadow-100);
       overflow: hidden;
     }
@@ -26,15 +26,25 @@ export class RelAccordion extends LitElement {
       display: flex;
       justify-content: space-between;
       align-items: center;
-      padding: var(--rel-spacing-space-md);
+      padding: var(--rel-spacing-space-md, 16px);
       cursor: pointer;
       user-select: none;
+      border-radius: var(--rel-borders-radius-border-radius-200, 8px);
+    }
+
+    .header:hover {
+      background: var(--rel-surface-surface, #f5f5f5);
+    }
+
+    .header:focus-visible {
+      outline: 2px solid var(--rel-border-info, #0091ea);
+      outline-offset: -2px;
     }
 
     .title {
-      font-size: var(--rel-fontSizes-lg);
-      font-weight: var(--rel-fontWeights-medium);
-      color: var(--rel-colors-black);
+      font-size: var(--rel-fontSizes-lg, 20px);
+      font-weight: var(--rel-fontWeights-medium, 500);
+      color: var(--rel-text-heading, #2b2b2b);
     }
 
     /* ICON ----------------------------------------------------- */
@@ -50,7 +60,7 @@ export class RelAccordion extends LitElement {
     .icon svg {
       width: 20px;
       height: 20px;
-      stroke: var(--rel-colors-gray-primary);
+      stroke: var(--rel-text-primary, #333);
       stroke-width: 2;
       fill: none;
       stroke-linecap: round;
@@ -65,16 +75,23 @@ export class RelAccordion extends LitElement {
     .body {
       overflow: hidden;
       max-height: 0;
-      padding: 0 var(--rel-spacing-space-md);
-      font-size: var(--rel-fontSizes-lg);
-      color: var(--rel-colors-gray-primary);
+      padding: 0 var(--rel-spacing-space-md, 16px);
+      font-size: var(--rel-fontSizes-md, 14px);
+      color: var(--rel-text-primary, #333);
       transition: max-height 0.25s ease, padding 0.2s ease;
     }
 
     .body.open {
-      max-height: 1000px; /* sufficiently large */
-      padding: var(--rel-spacing-space-xl) var(--rel-spacing-space-md)
-        var(--rel-spacing-space-lg);
+      max-height: 1000px;
+      padding: var(--rel-spacing-space-xl, 24px) var(--rel-spacing-space-md, 16px)
+        var(--rel-spacing-space-lg, 20px);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .icon,
+      .body {
+        transition: none;
+      }
     }
   `;
 
@@ -101,7 +118,17 @@ export class RelAccordion extends LitElement {
   render() {
     return html`
       <div class="accordion">
-        <div class="header" @click=${this.toggle}>
+        <div class="header"
+          role="button"
+          tabindex="0"
+          aria-expanded="${this.open}"
+          @click=${this.toggle}
+          @keydown=${(e: KeyboardEvent) => {
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              this.toggle();
+            }
+          }}>
           <div class="title">${this.title}</div>
 
           <div class="icon ${this.open ? "rotated" : ""}">

package/dist/components/rel-alert/README.md

@@ -0,0 +1,141 @@
+# rel-alert
+
+## Overview
+A versatile alert component for displaying informational, success, warning, error, or neutral messages. Features built-in icons, optional dismissibility, secondary message text, and inline links. Automatically hides when dismissed via the `dismissed` reflected attribute.
+
+## Usage
+```html
+<!-- Basic neutral alert -->
+<rel-alert
+  message1="This is a neutral alert"
+  type="neutral">
+</rel-alert>
+
+<!-- Info alert with secondary message -->
+<rel-alert
+  type="info"
+  message1="System Notification"
+  message2="Your settings have been updated successfully.">
+</rel-alert>
+
+<!-- Success alert -->
+<rel-alert
+  type="success"
+  message1="Operation Completed"
+  message2="Your data has been saved.">
+</rel-alert>
+
+<!-- Warning alert -->
+<rel-alert
+  type="warning"
+  message1="Warning"
+  message2="Please verify your input before continuing.">
+</rel-alert>
+
+<!-- Error alert -->
+<rel-alert
+  type="error"
+  message1="Error Occurred"
+  message2="Unable to process your request.">
+</rel-alert>
+
+<!-- With action link -->
+<rel-alert
+  type="info"
+  message1="Update Available"
+  message2="A new version is ready."
+  urlText="Learn More"
+  urlHref="https://example.com/release-notes">
+</rel-alert>
+
+<!-- Non-dismissible -->
+<rel-alert
+  type="warning"
+  message1="Required Action"
+  dismissible="false">
+</rel-alert>
+
+<!-- Listen for dismiss -->
+<rel-alert id="myAlert" type="success" message1="Success!"></rel-alert>
+<script>
+  const alert = document.getElementById('myAlert');
+  alert.addEventListener('dismiss', () => {
+    console.log('Alert was dismissed');
+  });
+</script>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"info" \| "success" \| "warning" \| "error" \| "neutral"` | `"neutral"` | Alert type determining icon and color scheme |
+| `message1` | `string` | `""` | Primary message text (bold) |
+| `message2` | `string` | - | Optional secondary message text (smaller, slightly transparent) |
+| `urlText` | `string` | - | Link text (shown below messages) |
+| `urlHref` | `string` | - | Link URL (both `urlText` and `urlHref` required for link to show) |
+| `dismissible` | `boolean` | `true` | Whether to show the close (✕) button |
+| `dismissed` | `boolean` (reflected) | `false` | When true, hides the component via `:host([dismissed])` |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `dismiss` | None | Fired when the close button is clicked (sets `dismissed` to true) |
+
+## Slots
+Default slot not used.
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+- `--rel-fontSizes-md` - Primary message font size
+- `--rel-fontSizes-sm` - Secondary message and link font size
+- `--rel-fontWeights-medium` - Primary message and link font weight
+- `--rel-fontWeights-semibold` - Used implicitly in link styling
+
+### Spacing Tokens
+- `--rel-spacing-space-xs` - Gap between icon and content
+- `--rel-spacing-space-sm` - Vertical padding
+- `--rel-spacing-space-md` - Horizontal padding
+- `--rel-spacing-space-2xs` - Close button padding
+
+### Color Tokens (by type)
+- **info**: `--rel-background-info` (background), `--rel-text-info` (text), `--rel-icon-info` (icon)
+- **success**: `--rel-background-success`, `--rel-text-success`, `--rel-icon-success`
+- **warning**: `--rel-background-warning`, `--rel-text-warning`, `--rel-icon-warning`
+- **error**: `--rel-background-error`, `--rel-text-error`, `--rel-icon-error`
+- **neutral**: `--rel-colors-white` (background), `--rel-text-primary` (text), `--rel-colors-black` (icon), `--rel-border-default` (border)
+
+### Border Tokens
+- `--rel-borders-radius-border-radius-200` - Border radius
+
+## Accessibility
+- Uses `role="alert"` for screen reader announcements
+- Close button has `aria-label="Dismiss"`
+- Focus visible states on close button with 2px outline
+- Secondary message has reduced opacity for visual hierarchy
+
+### Keyboard Interactions
+- `Tab` - Focus the close button (if dismissible)
+- `Space/Enter` - Dismiss the alert (when close button focused)
+
+### Focus Behavior
+- Close button shows 2px outline matching the alert's text color with 2px offset
+- Border radius applied to maintain visual consistency
+
+## Notes / Edge Cases
+- Icons are built-in SVG graphics that change based on `type` (info: ℹ️, success: ✓, warning: ⚠️, error: ❗, neutral: ℹ️)
+- Icon colors are controlled by type-specific `--rel-icon-*` tokens
+- The alert has a minimum width of `360px`
+- Both `urlText` and `urlHref` must be set for the link to appear
+- Links inherit the alert's text color and are underlined
+- `message2` has `opacity: 0.9` for subtle contrast with `message1`
+- When `dismissed` is set to `true`, the component applies `display: none` via `:host([dismissed])`
+- `dismissed` is a reflected attribute, meaning it appears in the HTML when true
+- The close button is always positioned at the right edge via `margin-left: auto`
+- Neutral type includes a 1px border while colored types do not

package/dist/components/rel-alert/rel-alert.ts

@@ -72,12 +72,23 @@ export class RelAlert extends LitElement {
       border: none;
       cursor: pointer;
       opacity: 0.6;
+      color: inherit;
+      font-size: 16px;
+      padding: var(--rel-spacing-space-2xs);
+      line-height: 1;
+      border-radius: var(--rel-borders-radius-border-radius-100, 4px);
     }
 
     .rel-close:hover {
       opacity: 1;
     }
 
+    .rel-close:focus-visible {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+      opacity: 1;
+    }
+
     /* COLORS */
     .alert-info {
       background: var(--rel-background-info);
@@ -130,7 +141,7 @@ export class RelAlert extends LitElement {
           >
             <path
               d="M9 4.75C8.75917 4.75 8.55715 4.8316 8.39395 4.9948C8.23132 5.15743 8.15 5.35917 8.15 5.6C8.15 5.84083 8.23132 6.04285 8.39395 6.20605C8.55715 6.36868 8.75917 6.45 9 6.45C9.24083 6.45 9.44257 6.36868 9.6052 6.20605C9.7684 6.04285 9.85 5.84083 9.85 5.6C9.85 5.35917 9.7684 5.15743 9.6052 4.9948C9.44257 4.8316 9.24083 4.75 9 4.75ZM9.85 8.15L8.15 8.15L8.15 13.25L9.85 13.25L9.85 8.15ZM9 0.499999C10.1758 0.499999 11.2808 0.723266 12.315 1.1698C13.3492 1.61633 14.2488 2.22182 15.0138 2.98625C15.7788 3.75068 16.3842 4.65027 16.8302 5.685C17.2762 6.71973 17.4994 7.82473 17.5 9C17.5006 10.1753 17.2773 11.2803 16.8302 12.315C16.3842 13.3492 15.7787 14.2487 15.0137 15.0137C14.2487 15.7787 13.3492 16.3845 12.315 16.831C11.2808 17.2776 10.1758 17.5006 9 17.5C7.82417 17.4994 6.71917 17.2764 5.685 16.831C4.65083 16.3845 3.75125 15.7787 2.98625 15.0137C2.22125 14.2487 1.61577 13.3492 1.1698 12.315C0.723834 11.2808 0.500567 10.1758 0.500001 9C0.499434 7.82417 0.722701 6.71917 1.1698 5.685C1.61577 4.65083 2.22125 3.75125 2.98625 2.98625C3.75125 2.22125 4.65084 1.61577 5.685 1.1698C6.71917 0.723832 7.82417 0.500566 9 0.499999ZM9 2.2C7.10167 2.2 5.49375 2.85875 4.17625 4.17625C2.85875 5.49375 2.2 7.10167 2.2 9C2.2 10.8983 2.85875 12.5062 4.17625 13.8237C5.49375 15.1412 7.10167 15.8 9 15.8C10.8983 15.8 12.5062 15.1412 13.8237 13.8237C15.1412 12.5062 15.8 10.8983 15.8 9C15.8 7.10167 15.1413 5.49375 13.8238 4.17625C12.5063 2.85875 10.8983 2.2 9 2.2Z"
-              fill="#4A90E2"
+              fill="var(--rel-icon-info)"
             />
           </svg>
         `;
@@ -145,7 +156,7 @@ export class RelAlert extends LitElement {
           >
             <path
               d="M7.81 12.91L13.8025 6.9175L12.6125 5.7275L7.81 10.53L5.3875 8.1075L4.1975 9.2975L7.81 12.91ZM9 17.5C7.82417 17.5 6.71917 17.2767 5.685 16.8302C4.65083 16.3837 3.75125 15.7782 2.98625 15.0138C2.22125 14.2493 1.61577 13.3497 1.1698 12.315C0.723834 11.2803 0.500568 10.1753 0.500001 9C0.499434 7.82473 0.722701 6.71973 1.1698 5.685C1.61577 4.65083 2.22125 3.75125 2.98625 2.98625C3.75125 2.22125 4.65083 1.61548 5.685 1.16895C6.71917 0.722418 7.82417 0.499434 9 0.500001C10.1758 0.500568 11.2808 0.723551 12.315 1.16895C13.3492 1.61548 14.2488 2.22125 15.0138 2.98625C15.7788 3.75125 16.3842 4.65083 16.8302 5.685C17.2762 6.71917 17.4994 7.82417 17.5 9C17.5006 10.1758 17.2773 11.2808 16.8302 12.315C16.3842 13.3492 15.7788 14.2488 15.0138 15.0138C14.2488 15.7788 13.3492 16.3842 12.315 16.8302C11.2808 17.2762 10.1758 17.4994 9 17.5ZM9 15.8C10.8983 15.8 12.5062 15.1412 13.8237 13.8237C15.1412 12.5062 15.8 10.8983 15.8 9C15.8 7.10167 15.1412 5.49375 13.8237 4.17625C12.5062 2.85875 10.8983 2.2 9 2.2C7.10167 2.2 5.49375 2.85875 4.17625 4.17625C2.85875 5.49375 2.2 7.10167 2.2 9C2.2 10.8983 2.85875 12.5062 4.17625 13.8237C5.49375 15.1412 7.10167 15.8 9 15.8Z"
-              fill="#4CAA47"
+              fill="var(--rel-icon-success)"
             />
           </svg>
         `;
@@ -160,7 +171,7 @@ export class RelAlert extends LitElement {
           >
             <path
               d="M0 14L8 0L16 14H0ZM2.50909 12.5263H13.4909L8 2.94737L2.50909 12.5263ZM8 11.7895C8.20606 11.7895 8.37891 11.7187 8.51855 11.5773C8.6577 11.4363 8.72727 11.2614 8.72727 11.0526C8.72727 10.8439 8.6577 10.669 8.51855 10.528C8.37891 10.3865 8.20606 10.3158 8 10.3158C7.79394 10.3158 7.62133 10.3865 7.48218 10.528C7.34255 10.669 7.27273 10.8439 7.27273 11.0526C7.27273 11.2614 7.34255 11.4363 7.48218 11.5773C7.62133 11.7187 7.79394 11.7895 8 11.7895ZM7.27273 9.57895H8.72727V5.89474H7.27273V9.57895Z"
-              fill="#FF6D00"
+              fill="var(--rel-icon-warning)"
             />
           </svg>
         `;
@@ -175,7 +186,7 @@ export class RelAlert extends LitElement {
           >
             <path
               d="M9 13.25C9.24083 13.25 9.44285 13.1684 9.60605 13.0052C9.76868 12.8426 9.85 12.6408 9.85 12.4C9.85 12.1592 9.76868 11.9571 9.60605 11.7939C9.44285 11.6313 9.24083 11.55 9 11.55C8.75917 11.55 8.55743 11.6313 8.3948 11.7939C8.2316 11.9571 8.15 12.1592 8.15 12.4C8.15 12.6408 8.2316 12.8426 8.3948 13.0052C8.55743 13.1684 8.75917 13.25 9 13.25ZM8.15 9.85H9.85V4.75H8.15V9.85ZM9 17.5C7.82417 17.5 6.71917 17.2767 5.685 16.8302C4.65083 16.3837 3.75125 15.7782 2.98625 15.0138C2.22125 14.2493 1.61577 13.3497 1.1698 12.315C0.723834 11.2803 0.500568 10.1753 0.500001 9C0.499434 7.82473 0.722701 6.71973 1.1698 5.685C1.61577 4.65083 2.22125 3.75125 2.98625 2.98625C3.75125 2.22125 4.65083 1.61548 5.685 1.16895C6.71917 0.722418 7.82417 0.499434 9 0.500001C10.1758 0.500568 11.2808 0.723551 12.315 1.16895C13.3492 1.61548 14.2488 2.22125 15.0138 2.98625C15.7788 3.75125 16.3842 4.65083 16.8302 5.685C17.2762 6.71917 17.4994 7.82417 17.5 9C17.5006 10.1758 17.2773 11.2808 16.8302 12.315C16.3842 13.3492 15.7788 14.2488 15.0138 15.0138C14.2488 15.7788 13.3492 16.3842 12.315 16.8302C11.2808 17.2762 10.1758 17.4994 9 17.5ZM9 15.8C10.8983 15.8 12.5062 15.1412 13.8237 13.8237C15.1412 12.5062 15.8 10.8983 15.8 9C15.8 7.10167 15.1412 5.49375 13.8237 4.17625C12.5062 2.85875 10.8983 2.2 9 2.2C7.10167 2.2 5.49375 2.85875 4.17625 4.17625C2.85875 5.49375 2.2 7.10167 2.2 9C2.2 10.8983 2.85875 12.5062 4.17625 13.8237C5.49375 15.1412 7.10167 15.8 9 15.8Z"
-              fill="#C62828"
+              fill="var(--rel-icon-error)"
             />
           </svg>
         `;
@@ -190,7 +201,7 @@ export class RelAlert extends LitElement {
           >
             <path
               d="M9 4.75C8.75917 4.75 8.55715 4.8316 8.39395 4.9948C8.23132 5.15743 8.15 5.35917 8.15 5.6C8.15 5.84083 8.23132 6.04285 8.39395 6.20605C8.55715 6.36868 8.75917 6.45 9 6.45C9.24083 6.45 9.44257 6.36868 9.6052 6.20605C9.7684 6.04285 9.85 5.84083 9.85 5.6C9.85 5.35917 9.7684 5.15743 9.6052 4.9948C9.44257 4.8316 9.24083 4.75 9 4.75ZM9.85 8.15L8.15 8.15L8.15 13.25L9.85 13.25L9.85 8.15ZM9 0.499999C10.1758 0.499999 11.2808 0.723266 12.315 1.1698C13.3492 1.61633 14.2488 2.22182 15.0138 2.98625C15.7788 3.75068 16.3842 4.65027 16.8302 5.685C17.2762 6.71973 17.4994 7.82473 17.5 9C17.5006 10.1753 17.2773 11.2803 16.8302 12.315C16.3842 13.3492 15.7787 14.2487 15.0137 15.0137C14.2487 15.7787 13.3492 16.3845 12.315 16.831C11.2808 17.2776 10.1758 17.5006 9 17.5C7.82417 17.4994 6.71917 17.2764 5.685 16.831C4.65083 16.3845 3.75125 15.7787 2.98625 15.0137C2.22125 14.2487 1.61577 13.3492 1.1698 12.315C0.723834 11.2808 0.500567 10.1758 0.500001 9C0.499434 7.82417 0.722701 6.71917 1.1698 5.685C1.61577 4.65083 2.22125 3.75125 2.98625 2.98625C3.75125 2.22125 4.65084 1.61577 5.685 1.1698C6.71917 0.723832 7.82417 0.500566 9 0.499999ZM9 2.2C7.10167 2.2 5.49375 2.85875 4.17625 4.17625C2.85875 5.49375 2.2 7.10167 2.2 9C2.2 10.8983 2.85875 12.5062 4.17625 13.8237C5.49375 15.1412 7.10167 15.8 9 15.8C10.8983 15.8 12.5062 15.1412 13.8237 13.8237C15.1412 12.5062 15.8 10.8983 15.8 9C15.8 7.10167 15.1413 5.49375 13.8238 4.17625C12.5063 2.85875 10.8983 2.2 9 2.2Z"
-              fill="black"
+              fill="var(--rel-colors-black)"
             />
           </svg>
         `;
@@ -199,7 +210,7 @@ export class RelAlert extends LitElement {
 
   render() {
     return html`
-      <div class="rel-alert alert-${this.type}">
+      <div class="rel-alert alert-${this.type}" role="alert">
         <div class="rel-icon">${this.iconSvg}</div>
 
         <div class="rel-content">
@@ -216,7 +227,7 @@ export class RelAlert extends LitElement {
         </div>
 
         ${this.dismissible
-          ? html`<button class="rel-close" @click=${this.dismissAlert}>
+          ? html`<button class="rel-close" @click=${this.dismissAlert} aria-label="Dismiss">
               ✕
             </button>`
           : null}

package/dist/components/rel-avatar/README.md

@@ -0,0 +1,119 @@
+# rel-avatar
+
+## Overview
+A circular avatar component supporting three display types: image, text initials, or custom icon content. Provides four size variants with automatic text transformation and SVG sizing for icons.
+
+## Usage
+```html
+<!-- Image avatar -->
+<rel-avatar
+  type="image"
+  src="./user-photo.jpg"
+  alt="John Doe">
+</rel-avatar>
+
+<!-- Text initials avatar -->
+<rel-avatar
+  type="text"
+  text="JD">
+</rel-avatar>
+
+<!-- Icon avatar with slotted SVG -->
+<rel-avatar type="icon">
+  <svg viewBox="0 0 24 24" fill="currentColor">
+    <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"/>
+  </svg>
+</rel-avatar>
+
+<!-- Different sizes -->
+<rel-avatar type="text" text="XS" size="xs"></rel-avatar>
+<rel-avatar type="text" text="SM" size="sm"></rel-avatar>
+<rel-avatar type="text" text="MD" size="md"></rel-avatar>
+<rel-avatar type="text" text="LG" size="lg"></rel-avatar>
+
+<!-- User list with avatars -->
+<div style="display: flex; gap: 8px; align-items: center;">
+  <rel-avatar type="image" src="user1.jpg" size="sm"></rel-avatar>
+  <span>John Doe</span>
+</div>
+
+<!-- Avatar group -->
+<div style="display: flex; margin-left: -8px;">
+  <rel-avatar type="text" text="A" size="md" style="margin-left: -8px;"></rel-avatar>
+  <rel-avatar type="text" text="B" size="md" style="margin-left: -8px;"></rel-avatar>
+  <rel-avatar type="text" text="C" size="md" style="margin-left: -8px;"></rel-avatar>
+</div>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` (reflected) | `"lg" \| "md" \| "sm" \| "xs"` | `"md"` | Avatar size variant |
+| `type` (reflected) | `"image" \| "text" \| "icon"` | `"image"` | Display type |
+| `src` | `string` | `""` | Image URL (for `type="image"`) |
+| `text` | `string` | `""` | Text content (for `type="text"`, usually initials) |
+| `alt` | `string` | `"Avatar"` | Alt text for the image |
+
+## Events
+None.
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | Custom icon content (for `type="icon"`, typically an SVG) |
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+
+### Font Tokens
+- `--rel-fontSizes-xl` - Large avatar text size
+- `--rel-fontSizes-lg` - Medium avatar text size
+- `--rel-fontSizes-md` - Small avatar text size
+- `--rel-fontSizes-xs` - Extra small avatar text size
+- `--rel-fontWeights-bold` - Text font weight
+
+### Color Tokens
+- `--rel-colors-gray-heading` - Avatar background color
+- `--rel-colors-white` - Text/icon color
+
+## Accessibility
+- Image avatars include `alt` attribute for screen readers
+- Text is automatically uppercased for consistency
+- Ensure meaningful `alt` text is provided for image avatars
+
+### Keyboard Interactions
+- None (purely presentational)
+
+### Focus Behavior
+- Does not receive focus
+
+## Notes / Edge Cases
+- **Size variants**:
+  - **lg**: 40px × 40px, font-size: `--rel-fontSizes-xl`
+  - **md**: 32px × 32px, font-size: `--rel-fontSizes-lg`
+  - **sm**: 24px × 24px, font-size: `--rel-fontSizes-md`
+  - **xs**: 18px × 18px, font-size: `--rel-fontSizes-xs`
+
+- **Display types**:
+  - **image**: Displays an `<img>` with `src` and `alt`
+    - Uses `object-fit: cover` for proper image scaling
+    - Image is `width: 100%`, `height: 100%`
+  - **text**: Displays the `text` property in a `<span>`
+    - Text is automatically uppercased via `text-transform: uppercase`
+  - **icon**: Displays slotted content (typically SVG)
+    - Slotted SVGs are automatically sized to 50% of the avatar size
+
+- The avatar is always circular via `border-radius: 50%`
+- The avatar uses `overflow: hidden` to clip images to circle shape
+- Text and icons are centered using flexbox
+- The avatar is `inline-flex` for easy inline usage with text
+- The `size` and `type` attributes are reflected in HTML
+- The component uses `user-select: none` to prevent text selection
+- If `type` is `image` but `src` is empty, nothing is displayed (no fallback)

package/dist/components/rel-badge/README.md

@@ -0,0 +1,86 @@
+# rel-badge
+
+## Overview
+A simple notification badge component displaying numeric counts or dot indicators. Supports three sizes (sm, md, lg) and two variants (number, dot). Ideal for indicating counts, status, or notifications in UI elements.
+
+## Usage
+```html
+<!-- Number badges -->
+<rel-badge number="5"></rel-badge>
+<rel-badge number="12" size="md"></rel-badge>
+<rel-badge number="99+" size="lg"></rel-badge>
+
+<!-- Dot badges (no number shown) -->
+<rel-badge variant="dot" size="sm"></rel-badge>
+<rel-badge variant="dot" size="md"></rel-badge>
+<rel-badge variant="dot" size="lg"></rel-badge>
+
+<!-- Common use case: Badge on icon/button -->
+<div style="position: relative; display: inline-block;">
+  <button>🔔 Notifications</button>
+  <rel-badge number="3" size="sm" style="position: absolute; top: -8px; right: -8px;"></rel-badge>
+</div>
+
+<!-- Sizes comparison -->
+<rel-badge number="1" size="sm"></rel-badge>
+<rel-badge number="2" size="md"></rel-badge>
+<rel-badge number="3" size="lg"></rel-badge>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `number` | `string` | `""` | Text to display in number variant (can be numeric or text like "99+") |
+| `size` | `"sm" \| "md" \| "lg"` (reflected) | `"md"` | Size variant |
+| `variant` | `"dot" \| "number"` (reflected) | `"number"` | Display mode (number shows text, dot shows indicator only) |
+
+## Events
+None.
+
+## Slots
+Default slot not used.
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+- `--rel-fontWeights-semibold` - Font weight (number variant)
+- `--rel-fontSizes-xs`, `--rel-fontSizes-sm`, `--rel-fontSizes-lg` - Font sizes for number variant sizes
+
+### Color Tokens
+- `--rel-colors-red-primary` - Background color
+- `--rel-colors-white` - Text color
+
+## Accessibility
+- Purely visual indicator (no ARIA roles)
+- For critical information, ensure accompanying text or ARIA labels on parent elements
+- Screen readers will not announce badge content unless used with proper labeling
+
+### Keyboard Interactions
+- None (not focusable)
+
+### Focus Behavior
+- Not focusable
+
+## Notes / Edge Cases
+- **Number variant sizes**:
+  - **sm**: 20px × 20px, 12px font
+  - **md**: 28px × 28px, 14px font
+  - **lg**: 40px × 40px, 20px font
+- **Dot variant sizes**:
+  - **sm**: 8px × 8px
+  - **md**: 10px × 10px
+  - **lg**: 12px × 12px
+- All badges are circular (`border-radius: 50%`)
+- The `number` property accepts any string (e.g., "99+", "NEW", or numeric values)
+- In dot variant, the `number` property is ignored and nothing is rendered inside
+- The component is `display: inline-flex` for easy positioning
+- Badges use `justify-content: center` and `align-items: center` for centering content
+- `size` and `variant` are reflected attributes (appear in HTML when set)
+- Common pattern: position badges absolutely over parent elements (e.g., icons, avatar images)
+- For very large numbers, consider truncating or using "99+" format to avoid overflow