@reliability-design/web 1.0.3 → 1.1.1

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-avatar/rel-avatar.ts

@@ -26,8 +26,8 @@ export class RelAvatar extends LitElement {
       border-radius: 50%;
       overflow: hidden;
 
-      background-color: var(--rel-colors-gray-heading);
-      color: var(--rel-colors-white);
+      background-color: #9E9E9E;
+      color: #ffffff;
       font-weight: var(--rel-fontWeights-bold);
 
       user-select: none;
@@ -71,6 +71,7 @@ export class RelAvatar extends LitElement {
       display: inline-flex;
       align-items: center;
       justify-content: center;
+      color: #ffffff;
     }
 
     .icon-slot ::slotted(svg) {

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

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

@@ -5,6 +5,10 @@ import { customElement, property } from "lit/decorators.js";
 export class RelBadge extends LitElement {
   @property({ type: String }) number = "";
 
+  @property({ type: String }) ariaLabel: string = "";
+
+  @property({ type: String }) suffix: string = "notifications";
+
   @property({ type: String, reflect: true })
   size: "sm" | "md" | "lg" = "md";
 
@@ -20,10 +24,10 @@ export class RelBadge extends LitElement {
       display: inline-flex;
       align-items: center;
       justify-content: center;
-      font-family: var(--rel-fontFamilies-primary);
-      font-weight: 600;
+      font-family: var(--rel-fontFamilies-primary, sans-serif);
+      font-weight: var(--rel-fontWeights-semibold, 600);
       background-color: var(--rel-colors-red-primary);
-      color: var(--rel-colors-white);
+      color: #ffffff;
       border-radius: 50%;
     }
 
@@ -31,19 +35,19 @@ export class RelBadge extends LitElement {
     .badge-sm {
       width: 20px;
       height: 20px;
-      font-size: 12px;
+      font-size: var(--rel-fontSizes-xs, 12px);
     }
 
     .badge-md {
       width: 28px;
       height: 28px;
-      font-size: 14px;
+      font-size: var(--rel-fontSizes-sm, 14px);
     }
 
     .badge-lg {
       width: 40px;
       height: 40px;
-      font-size: 20px;
+      font-size: var(--rel-fontSizes-lg, 20px);
     }
 
     /* DOT BADGES */
@@ -69,7 +73,7 @@ export class RelBadge extends LitElement {
 
   render() {
     return html`
-      <span class="${this.classes}">
+      <span class="${this.classes}" aria-label=${this.ariaLabel || `${this.number} ${this.suffix}`}>
         ${this.variant === "number" ? this.number : null}
       </span>
     `;

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

@@ -0,0 +1,102 @@
+#rel-breadcrumbs
+
+## Overview
+A breadcrumb navigation component that displays a hierarchical path of pages. Features accessible markup, automatic last-item detection, built-in chevron separators, and proper ARIA attributes. Automatically styles the last item as the current page.
+
+## Usage
+```html
+<!-- Basic breadcrumb -->
+<rel-breadcrumbs id="breadcrumb1"></rel-breadcrumbs>
+<script>
+  const breadcrumb = document.getElementById('breadcrumb1');
+  breadcrumb.items = [
+    { label: 'Home', url: '/' },
+    { label: 'Products', url: '/products' },
+    { label: 'Electronics', url: '/products/electronics' },
+    { label: 'Laptops' } // Last item has no URL
+  ];
+</script>
+
+<!-- Simple path -->
+<rel-breadcrumbs id="breadcrumb2"></rel-breadcrumbs>
+<script>
+  document.getElementById('breadcrumb2').items = [
+    { label: 'Dashboard', url: '/dashboard' },
+    { label: 'Settings' }
+  ];
+</script>
+
+<!-- Deep nested path -->
+<rel-breadcrumbs id="breadcrumb3"></rel-breadcrumbs>
+<script>
+  document.getElementById('breadcrumb3').items = [
+    { label: 'Docs', url: '/docs' },
+    { label: 'Components', url: '/docs/components' },
+    { label: 'Navigation', url: '/docs/components/navigation' },
+    { label: 'Breadcrumbs' }
+  ];
+</script>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `BreadcrumbItem[]` | `[]` | Array of breadcrumb items (see BreadcrumbItem interface below) |
+
+### BreadcrumbItem Interface
+```typescript
+interface BreadcrumbItem {
+  label: string;   // Display text
+  url?: string;    // Optional link URL (omit for current/last page)
+}
+```
+
+## Events
+None.
+
+## Slots
+Default slot not used.
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+- `--rel-fontSizes-md` - Font size
+- `--rel-fontWeights-medium` - Font weight for links
+- `--rel-fontWeights-bold` - Font weight for current page
+
+### Color Tokens
+- `--rel-text-primary` - Base text color
+- `--rel-text-heading` - Link and current page text color
+- `--rel-colors-blue-primary` - Link hover color and focus outline
+
+## Accessibility
+- Uses semantic `<nav>` with `aria-label="Breadcrumb"`
+- Uses `<ol>` ordered list for proper structure
+- Last item has `aria-current="page"` to indicate current page
+- Links have focus visible states with blue outline
+- Chevron separator has `aria-hidden="true"` to hide from screen readers
+
+### Keyboard Interactions
+- `Tab` - Navigate through breadcrumb links
+- `Enter` - Follow focused link
+
+### Focus Behavior
+- Links show 2px blue outline with 2px offset when focused
+- Border radius applied to focus outline for visual consistency
+
+## Notes / Edge Cases
+- The last item in `items` array is automatically treated as the current page
+- Last item renders as a `<span class="current">` instead of `<a>`, even if it has a `url`
+- Chevron separators (SVG chevron-right arrows) appear between all items except after the last one
+- Chevrons are 16px × 16px with 10px horizontal margins
+- Chevron color inherits `currentColor` from parent
+- Links have `text-decoration: none` by default, `underline` on hover
+- The current page label is bold and not clickable (`cursor: default`)
+- The component is `display: block` and takes full width
+- The ordered list uses `flex-wrap: wrap` to handle overflow gracefully

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

@@ -14,9 +14,9 @@ export class RelBreadcrumbs extends LitElement {
   static styles = css`
     :host {
       display: block;
-      font-family: var(--rel-fontFamilies-primary);
+      font-family: var(--rel-fontFamilies-primary, sans-serif);
       font-size: var(--rel-fontSizes-md);
-      color: var(--rel-colors-gray-text);
+      color: var(--rel-text-primary, #333);
     }
 
     nav {
@@ -39,18 +39,24 @@ export class RelBreadcrumbs extends LitElement {
     a {
       text-decoration: none;
       font-weight: var(--rel-fontWeights-medium);
-      color: var(--rel-colors-gray-heading);
+      color: var(--rel-text-heading, #2b2b2b);
       transition: color 0.2s ease;
     }
 
     a:hover {
       text-decoration: underline;
-      color: var(--rel-colors-primary);
+      color: var(--rel-colors-blue-primary, #0091ea);
+    }
+
+    a:focus-visible {
+      outline: 2px solid var(--rel-colors-blue-primary, #0091ea);
+      outline-offset: 2px;
+      border-radius: 2px;
     }
 
     .current {
       font-weight: var(--rel-fontWeights-bold);
-      color: var(--rel-colors-black);
+      color: var(--rel-text-heading, #2b2b2b);
       cursor: default;
     }
 
@@ -73,7 +79,7 @@ export class RelBreadcrumbs extends LitElement {
               <li>
                 ${item.url && !isLast
                   ? html`<a href=${item.url}>${item.label}</a>`
-                  : html`<span class="current">${item.label}</span>`}
+                  : html`<span class="current" aria-current="page">${item.label}</span>`}
                 ${!isLast
                   ? html`
                       <svg viewBox="0 0 24 24" aria-hidden="true">

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

@@ -0,0 +1,130 @@
+# rel-button
+
+## Overview
+A versatile button component with six variants (default, primary, secondary, text, link, icon), three tone options, three sizes, and configurable border radius. Features hover, active, and focus states with smooth transitions. Slots support custom content including text, icons, or combinations.
+
+## Usage
+```html
+<!-- Basic variants -->
+<rel-button variant="default">Default Button</rel-button>
+<rel-button variant="primary">Primary Button</rel-button>
+<rel-button variant="secondary">Secondary Button</rel-button>
+<rel-button variant="text">Text Button</rel-button>
+<rel-button variant="link">Link Style</rel-button>
+
+<!-- Icon button -->
+<rel-button variant="icon">⚙️</rel-button>
+
+<!-- Tones (affect color scheme) -->
+<rel-button variant="primary" tone="default">Default Tone</rel-button>
+<rel-button variant="primary" tone="critical">Critical Action</rel-button>
+<rel-button variant="primary" tone="success">Success Action</rel-button>
+
+<!-- Sizes -->
+<rel-button size="small">Small</rel-button>
+<rel-button size="medium">Medium</rel-button>
+<rel-button size="large">Large</rel-button>
+
+<!-- Border radius options -->
+<rel-button border="corner-radius">Rounded</rel-button>
+<rel-button border="small-corner-radius">Small Rounded</rel-button>
+<rel-button border="no-corner-radius">Sharp</rel-button>
+
+<!-- Disabled -->
+<rel-button disabled>Disabled Button</rel-button>
+
+<!-- With icon and text (using slot) -->
+<rel-button variant="primary">
+  <svg width="16" height="16" viewBox="0 0 16 16"><path d="M8 0l3 6h6l-5 4 2 6-6-4-6 4 2-6-5-4h6z"/></svg>
+  Save
+</rel-button>
+
+<!-- Listen for click -->
+<rel-button id="actionBtn" variant="primary">Click Me</rel-button>
+<script>
+  document.getElementById('actionBtn').addEventListener('click', () => {
+    console.log('Button clicked');
+  });
+</script>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "primary" \| "secondary" \| "text" \| "link" \| "icon"` | `"default"` | Visual style variant |
+| `tone` | `"default" \| "critical" \| "success"` | `"default"` | Color tone (affects default/primary variants) |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Button size |
+| `border` | `"corner-radius" \| "small-corner-radius" \| "no-corner-radius"` | `"corner-radius"` | Border radius style |
+| `disabled` | `boolean` (reflected) | `false` | Disables interaction and applies disabled styling |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `click` | `MouseEvent` | Re-dispatched from the internal button (for framework compatibility) |
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | Button content (text, icons, or combination) |
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+- `--rel-fontWeights-semibold` - Font weight
+- `--rel-fontSizes-sm`, `--rel-fontSizes-md`, `--rel-fontSizes-lg` - Font sizes for sizes
+
+### Spacing Tokens
+- `--rel-spacing-space-2xs` - Internal gap between elements
+- `--rel-spacing-space-md`, `--rel-spacing-space-lg`, `--rel-spacing-space-xl` - Horizontal padding by size
+
+### Color Tokens (by variant/tone)
+- **default + default tone**: `--rel-colors-gray-primary` (bg), `--rel-colors-white` (text)
+- **default + critical tone**: `--rel-colors-red-primary` (bg), `--rel-colors-white` (text)
+- **default + success tone**: `--rel-colors-green-success` (bg), `--rel-colors-white` (text)
+- **primary + default tone**: `--rel-colors-green-primary` (bg), `--rel-colors-black` (text)
+- **primary + critical tone**: `--rel-colors-red-primary` (bg), `--rel-colors-white` (text)
+- **primary + success tone**: `--rel-colors-green-success` (bg), `--rel-colors-white` (text)
+- **secondary**: `--rel-colors-white` (bg), `--rel-colors-black` (text + border)
+- **text**: transparent (bg), `--rel-colors-black` (text)
+- **link**: transparent (bg), `--rel-colors-blue-primary` (text), underlined
+- **icon**: `--rel-colors-gray-light` (bg), `--rel-colors-black` (text), circular (40px × 40px)
+- **disabled**: `--rel-colors-gray-border` (bg), `--rel-colors-gray-disabled-text` (text)
+
+### Border Tokens
+- `--rel-borders-radius-border-radius-500` - Large corner radius
+- `--rel-borders-radius-border-radius-200` - Small corner radius
+- `--rel-borders-radius-border-radius-0` - No corner radius
+
+## Accessibility
+- Uses native `<button>` element for proper semantics
+- `aria-disabled` attribute set on disabled buttons
+- Focus visible state with blue outline
+- Keyboard accessible (Space/Enter activation)
+
+### Keyboard Interactions
+- `Tab` - Focus the button
+- `Space/Enter` - Activate the button
+
+### Focus Behavior
+- Blue 2px outline with 2px offset on focus-visible
+- Focus outline works across all variants
+
+## Notes / Edge Cases
+- **Icon variant** is always circular (40px × 40px), ignores size property, and has no padding
+- **Link variant** has `text-decoration: underline`
+- **Secondary variant** includes a 1px border matching the text color
+- Hover effect applies `filter: brightness(0.92)` to darken
+- Active (pressed) effect applies `transform: scale(0.97)` for tactile feedback
+- Disabled buttons have `pointer-events: none` and use `!important` to override theming
+- The component re-dispatches click events to ensure framework compatibility (e.g., Angular)
+- Clicking a disabled button prevents default and stops propagation
+- Size variants affect height (32px/40px/48px) and horizontal padding
+- The button has `display: inline-flex` with `align-items: center` and `justify-content: center`
+- Internal gap of `var(--rel-spacing-space-2xs)` allows icons + text combinations
+- Transitions are `0.15s ease` for all visual changes