@nuvia-ui/components 4.0.1

package/src/ds-icon-button/ds-icon-button.a11y.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import axe from 'axe-core';
+import './ds-icon-button.js';
+
+describe('ds-icon-button accessibility', () => {
+    let container;
+
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+    });
+
+    afterEach(() => {
+        container.remove();
+    });
+
+    it('should pass axe checks with aria-label', async () => {
+        container.innerHTML = '<ds-icon-button icon="add" aria-label="Add item"></ds-icon-button>';
+
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const results = await axe.run(container, {
+            rules: {
+                'color-contrast': { enabled: false },
+                'button-name': { enabled: false }, // Handled by aria-label on host
+                'nested-interactive': { enabled: false } // Shadow DOM boundary issue
+            }
+        });
+
+        if (results.violations.length > 0) {
+            console.log('Violations:', JSON.stringify(results.violations, null, 2));
+        }
+        expect(results.violations).toHaveLength(0);
+    });
+
+    it('should pass axe checks for all variants', async () => {
+        const variants = ['primary', 'secondary', 'outline', 'action', 'tertiary'];
+
+        container.innerHTML = variants.map(v =>
+            `<ds-icon-button icon="star" variant="${v}" aria-label="Star ${v}"></ds-icon-button>`
+        ).join('');
+
+        await new Promise(resolve => setTimeout(resolve, 100));
+
+        const results = await axe.run(container, {
+            rules: {
+                'color-contrast': { enabled: false },
+                'button-name': { enabled: false },
+                'nested-interactive': { enabled: false }
+            }
+        });
+
+        expect(results.violations).toHaveLength(0);
+    });
+});

package/src/ds-icon-button/ds-icon-button.js

@@ -0,0 +1,224 @@
+import { LitElement, html, css } from 'lit';
+import '../ds-icon/ds-icon.js';
+
+
+/**
+ * Icon-only button component for the Design System
+ * 
+ * @element ds-icon-button
+ * 
+ * @prop {string} icon - Icon name (required)
+ * @prop {string} variant - Button style variant: 'primary' | 'secondary' | 'outline' | 'action' | 'tertiary' (default: 'primary')
+ * @prop {string} size - Button size: 'm' (32px) | 's' (24px) (default: 'm')
+ * @prop {boolean} disabled - Whether the button is disabled
+ * 
+ * @example
+ * <ds-icon-button icon="add" aria-label="Add item"></ds-icon-button>
+ * <ds-icon-button icon="close" variant="secondary" size="s" aria-label="Close"></ds-icon-button>
+ */
+export class DsIconButton extends LitElement {
+  static properties = {
+    icon: { type: String },
+    variant: { type: String, reflect: true },
+    size: { type: String, reflect: true },
+    disabled: { type: Boolean, reflect: true }
+  };
+
+  static shadowRootOptions = { ...LitElement.shadowRootOptions, delegatesFocus: true };
+
+  static styles = css`
+    :host {
+      display: inline-block;
+      vertical-align: middle;
+    }
+
+    button {
+      appearance: none;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      
+      /* Square layout - width equals height */
+      aspect-ratio: 1;
+      padding: 0;
+      border: 1px solid transparent;
+      border-radius: var(--ds-radius-action, 999px);
+      background: transparent;
+      color: inherit;
+      
+      cursor: pointer;
+      box-sizing: border-box;
+      transition: background-color 0.2s, color 0.2s, border-color 0.2s;
+    }
+
+    /* SIZE M (default): 32px */
+    :host([size="m"]) button,
+    :host(:not([size])) button {
+      width: var(--ds-space-xl, 32px);
+      height: var(--ds-space-xl, 32px);
+    }
+    :host([size="m"]) ds-icon,
+    :host(:not([size])) ds-icon {
+      --size: var(--ds-icon-size-sm, 20px);
+    }
+
+    /* SIZE S: 24px */
+    :host([size="s"]) button {
+      width: var(--ds-space-lg, 24px);
+      height: var(--ds-space-lg, 24px);
+    }
+    :host([size="s"]) ds-icon {
+      --size: var(--ds-icon-size-xs, 16px);
+    }
+
+    /* Disabled state */
+    :host([disabled]) button {
+      cursor: not-allowed;
+      pointer-events: none;
+    }
+    
+    :host([disabled]) {
+      pointer-events: none;
+    }
+
+    /* Focus */
+    button:focus-visible {
+      outline: 2px solid var(--ds-color-border-focus);
+      outline-offset: 2px;
+    }
+
+    /* 
+     * VARIANTS 
+     */
+
+    /* PRIMARY */
+    :host([variant="primary"]) button {
+      background: var(--ds-color-bg-brand);
+      color: var(--ds-color-text-inverse);
+    }
+    :host([variant="primary"]:not([disabled])) button:hover {
+      background: var(--ds-color-bg-brand-hover);
+    }
+    :host([variant="primary"]:not([disabled])) button:active {
+      background: var(--ds-color-bg-brand-pressed);
+    }
+    
+    /* SECONDARY */
+    :host([variant="secondary"]) button {
+      background: var(--ds-color-bg-secondary);
+      color: var(--ds-color-text-default);
+      border-color: var(--ds-color-border-strong);
+    }
+    :host([variant="secondary"]:not([disabled])) button:hover {
+      background: var(--ds-color-bg-hover);
+    }
+    :host([variant="secondary"]:not([disabled])) button:active {
+      background: var(--ds-color-bg-pressed);
+    }
+
+    /* OUTLINE */
+    :host([variant="outline"]) button {
+      background: transparent;
+      color: var(--ds-color-text-brand);
+      border-color: var(--ds-color-border-brand);
+    }
+    :host([variant="outline"]:not([disabled])) button:hover {
+      background: var(--ds-color-bg-hover);
+      color: var(--ds-color-text-brand-hover);
+      border-color: var(--ds-color-border-brand-hover);
+    }
+    :host([variant="outline"]:not([disabled])) button:active {
+      background: var(--ds-color-bg-pressed);
+      color: var(--ds-color-text-brand-pressed);
+      border-color: var(--ds-color-border-brand-pressed);
+    }
+
+    /* ACTION */
+    :host([variant="action"]) button {
+      background: transparent;
+      color: var(--ds-color-text-default);
+    }
+    :host([variant="action"]:not([disabled])) button:hover {
+      background: var(--ds-color-bg-hover);
+    }
+    :host([variant="action"]:not([disabled])) button:active {
+      background: var(--ds-color-bg-pressed);
+    }
+
+    /* TERTIARY */
+    :host([variant="tertiary"]) button {
+      background: transparent;
+      color: var(--ds-color-text-brand);
+    }
+    :host([variant="tertiary"]:not([disabled])) button:hover {
+      background: var(--ds-color-bg-hover);
+      color: var(--ds-color-text-brand-hover);
+    }
+    :host([variant="tertiary"]:not([disabled])) button:active {
+      background: var(--ds-color-bg-pressed);
+      color: var(--ds-color-text-brand-pressed);
+    }
+
+    /* DISABLED STATE for all variants */
+    :host([disabled]) button {
+      background: var(--ds-color-bg-disabled);
+      color: var(--ds-color-text-disabled);
+      border-color: transparent;
+    }
+    :host([variant="secondary"][disabled]) button {
+       border-color: var(--ds-color-border-disabled);
+    }
+    :host([variant="outline"][disabled]) button {
+       border-color: var(--ds-color-border-disabled);
+    }
+
+    :host([variant="action"][disabled]) button,
+    :host([variant="tertiary"][disabled]) button {
+       background: transparent;
+    }
+  `;
+
+  constructor() {
+    super();
+    this.icon = '';
+    this.variant = 'primary';
+    this.size = 'm';
+    this.disabled = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    // Set role for accessibility (allows aria-label on custom element)
+    // Set role for accessibility (allows aria-label on custom element)
+    // Removed: Host should not have role="button" because it contains a native button (Nested Interactive Controls violation)
+
+    // Accessibility warning
+    if (!this.hasAttribute('aria-label')) {
+      console.warn('ds-icon-button: "aria-label" is required for accessibility');
+    }
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    // No external listeners to clean up currently
+    // This method is here for lifecycle consistency and future extensions
+  }
+
+  render() {
+    if (!this.icon) {
+      console.warn('ds-icon-button: "icon" prop is required');
+      return html``;
+    }
+
+    const label = this.getAttribute('aria-label') || '';
+
+    return html`
+      <button ?disabled=${this.disabled} part="button" aria-label="${label}">
+        <ds-icon name=${this.icon}></ds-icon>
+      </button>
+    `;
+  }
+}
+
+customElements.define('ds-icon-button', DsIconButton);

package/src/ds-icon-button/ds-icon-button.mdx

@@ -0,0 +1,131 @@
+import { Meta, Canvas, Controls } from '@storybook/blocks';
+import * as DsIconButtonStories from './ds-icon-button.stories';
+
+<Meta of={DsIconButtonStories} />
+
+# Icon Button
+
+Compact buttons that use an icon to represent an action, without a text label.
+
+## Playground
+Interact with the button properties using the controls below.
+
+<Canvas of={DsIconButtonStories.Primary} />
+<Controls of={DsIconButtonStories.Primary} />
+
+## Usage
+
+### When to use
+- To display more actions (e.g., hamburger menu, overflow menu).
+- To navigate within the same screen (e.g., back to top, close modal).
+- When space is limited and the icon is universally understood (e.g., trash for delete).
+
+### When not to use
+- To display static or read-only information.
+- For bulk selection actions.
+- When the icon meaning is ambiguous without strict context.
+
+## Best Practices
+
+### Accessibility & Clarity
+- ✅ **Tooltips:** Icon-only buttons **must** show a tooltip label on hover for clarity and accessibility.
+- ✅ **Aria-label:** Always provide a descriptive `aria-label` since there is no visible text.
+
+### Layout & Sizing
+- ✅ **Exceptions:** Unlike standard buttons, icon buttons do **not** need to adhere to the 72px minimum width rule.
+- ✅ **Touch Target:** Ensure the touch target remains accessible (minimum 44x44px recommended for mobile) even if the visual size is smaller.
+
+## Types
+
+### Primary
+The primary button should draw attention to the most important action on a screen, so reserve it for actions that are essential to the experience. This helps create a clear visual hierarchy and keeps users focused on what matters most.
+
+<Canvas of={DsIconButtonStories.Primary} />
+
+### Secondary
+The secondary button supports less critical actions and complements the primary button.
+
+<Canvas of={DsIconButtonStories.Secondary} />
+
+### Outline
+Outline buttons have less prominence than a primary button and slightly more prominence than a tertiary button. It can be used on its own or when there is no clear distinction between multiple important actions on a screen.
+
+<Canvas of={DsIconButtonStories.Outline} />
+
+### Tertiary
+Tertiary buttons have the lowest prominence, so they should be used for low impact actions and/or actions that are not directly related with the primary button.
+
+<Canvas of={DsIconButtonStories.Tertiary} />
+
+### Action
+Action buttons let users complete routine tasks or make selections within a workflow. They’re designed to be subtle controls and usually appear inside containers like action bars, so they don’t compete with primary call-to-action elements.
+
+<Canvas of={DsIconButtonStories.Action} />
+
+## Functionality & States
+
+### Sizes
+Icon buttons support different sizes to fit various contexts.
+
+<Canvas of={DsIconButtonStories.SizeSmall} />
+
+### Disabled
+Use the disabled state to indicate that an action is currently unavailable.
+
+<Canvas of={DsIconButtonStories.Disabled} />
+
+## Accessibility
+
+<table style={{ width: '100%' }}>
+  <thead>
+    <tr>
+      <th>Attribute</th>
+      <th>Value</th>
+      <th>Notes</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>role</code></td>
+      <td><code>button</code></td>
+      <td>Native button element provides this</td>
+    </tr>
+    <tr>
+      <td><code>aria-label</code></td>
+      <td><strong>Required</strong></td>
+      <td>Must describe the action (e.g., "Close", "Add item")</td>
+    </tr>
+    <tr>
+      <td><code>disabled</code></td>
+      <td><code>true/false</code></td>
+      <td>Disables interaction and updates <code>aria-disabled</code></td>
+    </tr>
+  </tbody>
+</table>
+
+> ⚠️ **Important:** Icon-only buttons have no visible label, so `aria-label` is mandatory for screen reader users.
+
+### Keyboard Support
+
+<table>
+  <thead>
+    <tr>
+      <th>Key</th>
+      <th>Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><kbd>Enter</kbd> / <kbd>Space</kbd></td>
+      <td>Activates the button</td>
+    </tr>
+    <tr>
+      <td><kbd>Tab</kbd></td>
+      <td>Moves focus to next focusable element</td>
+    </tr>
+    <tr>
+      <td><kbd>Shift</kbd> + <kbd>Tab</kbd></td>
+      <td>Moves focus to previous focusable element</td>
+    </tr>
+  </tbody>
+</table>

package/src/ds-icon-button/ds-icon-button.stories.js

@@ -0,0 +1,128 @@
+import './ds-icon-button.js';
+
+export default {
+    title: 'Components/Icon Button',
+    component: 'ds-icon-button',
+    argTypes: {
+        icon: { control: 'text' },
+        variant: {
+            control: 'select',
+            options: ['primary', 'secondary', 'outline', 'action', 'tertiary'],
+        },
+        size: {
+            control: 'select',
+            options: ['m', 's'],
+        },
+        disabled: { control: 'boolean' },
+        'aria-label': { control: 'text' }
+    },
+};
+
+const createIconButton = ({ icon, variant, size, disabled, 'aria-label': ariaLabel }) => {
+    const btn = document.createElement('ds-icon-button');
+
+    if (icon) btn.setAttribute('icon', icon);
+    if (variant) btn.setAttribute('variant', variant);
+    if (size) btn.setAttribute('size', size);
+    if (disabled) btn.setAttribute('disabled', '');
+    if (ariaLabel) btn.setAttribute('aria-label', ariaLabel);
+
+    return btn;
+};
+
+export const Primary = {
+    args: {
+        icon: 'add',
+        variant: 'primary',
+        size: 'm',
+        'aria-label': 'Add item'
+    },
+    render: createIconButton
+};
+
+export const Secondary = {
+    args: {
+        icon: 'close',
+        variant: 'secondary',
+        size: 'm',
+        'aria-label': 'Close'
+    },
+    render: createIconButton
+};
+
+export const Outline = {
+    args: {
+        icon: 'info',
+        variant: 'outline',
+        size: 'm',
+        'aria-label': 'More Information'
+    },
+    render: createIconButton
+};
+
+export const Action = {
+    args: {
+        icon: 'more-vert',
+        variant: 'action',
+        size: 'm',
+        'aria-label': 'More Options'
+    },
+    render: createIconButton
+};
+
+export const Tertiary = {
+    args: {
+        icon: 'delete',
+        variant: 'tertiary',
+        size: 'm',
+        'aria-label': 'Delete'
+    },
+    render: createIconButton
+};
+
+export const SizeSmall = {
+    args: {
+        icon: 'add',
+        variant: 'primary',
+        size: 's',
+        'aria-label': 'Add item'
+    },
+    render: createIconButton
+};
+
+export const Disabled = {
+    args: {
+        icon: 'add',
+        variant: 'primary',
+        size: 'm',
+        disabled: true,
+        'aria-label': 'Add item'
+    },
+    render: createIconButton
+};
+
+export const AllVariants = {
+    render: () => {
+        const container = document.createElement('div');
+        container.style.cssText = 'display: flex; gap: 16px; align-items: center;';
+
+        ['primary', 'secondary', 'outline', 'action', 'tertiary'].forEach(variant => {
+            container.appendChild(createIconButton({ icon: 'star', variant, size: 'm', 'aria-label': `Star ${variant}` }));
+        });
+
+        return container;
+    }
+};
+
+export const AllSizes = {
+    render: () => {
+        const container = document.createElement('div');
+        container.style.cssText = 'display: flex; gap: 16px; align-items: center;';
+
+        ['m', 's'].forEach(size => {
+            container.appendChild(createIconButton({ icon: 'add', variant: 'primary', size, 'aria-label': `Add (${size})` }));
+        });
+
+        return container;
+    }
+};

package/src/ds-icon-button/ds-icon-button.test.js

@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import './ds-icon-button.js';
+
+describe('ds-icon-button', () => {
+    let container;
+
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+    });
+
+    afterEach(() => {
+        container.remove();
+    });
+
+    it('should render with default props', async () => {
+        container.innerHTML = '<ds-icon-button icon="add" aria-label="Add"></ds-icon-button>';
+        const iconButton = container.querySelector('ds-icon-button');
+
+        await new Promise(resolve => setTimeout(resolve, 50));
+
+        expect(iconButton.shadowRoot).toBeTruthy();
+        expect(iconButton.variant).toBe('primary');
+        expect(iconButton.size).toBe('m');
+        expect(iconButton.disabled).toBe(false);
+    });
+
+    it('should reflect variant attribute', async () => {
+        container.innerHTML = '<ds-icon-button icon="close" variant="secondary" aria-label="Close"></ds-icon-button>';
+        const iconButton = container.querySelector('ds-icon-button');
+
+        await new Promise(resolve => setTimeout(resolve, 50));
+
+        expect(iconButton.getAttribute('variant')).toBe('secondary');
+    });
+
+    it('should reflect size attribute', async () => {
+        container.innerHTML = '<ds-icon-button icon="add" size="s" aria-label="Add"></ds-icon-button>';
+        const iconButton = container.querySelector('ds-icon-button');
+
+        await new Promise(resolve => setTimeout(resolve, 50));
+
+        expect(iconButton.getAttribute('size')).toBe('s');
+    });
+
+    it('should reflect disabled attribute', async () => {
+        container.innerHTML = '<ds-icon-button icon="add" disabled aria-label="Add"></ds-icon-button>';
+        const iconButton = container.querySelector('ds-icon-button');
+
+        await new Promise(resolve => setTimeout(resolve, 50));
+
+        expect(iconButton.hasAttribute('disabled')).toBe(true);
+        const button = iconButton.shadowRoot.querySelector('button');
+        expect(button.disabled).toBe(true);
+    });
+
+    it('should render ds-icon with correct name', async () => {
+        container.innerHTML = '<ds-icon-button icon="star" aria-label="Star"></ds-icon-button>';
+        const iconButton = container.querySelector('ds-icon-button');
+
+        await new Promise(resolve => setTimeout(resolve, 50));
+
+        const icon = iconButton.shadowRoot.querySelector('ds-icon');
+        expect(icon).toBeTruthy();
+        expect(icon.getAttribute('name')).toBe('star');
+    });
+
+    it('should warn and render nothing when icon prop is missing', async () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        container.innerHTML = '<ds-icon-button aria-label="Test"></ds-icon-button>';
+        const iconButton = container.querySelector('ds-icon-button');
+
+        await new Promise(resolve => setTimeout(resolve, 50));
+
+        expect(warnSpy).toHaveBeenCalledWith('ds-icon-button: "icon" prop is required');
+        const button = iconButton.shadowRoot.querySelector('button');
+        expect(button).toBeFalsy();
+        warnSpy.mockRestore();
+    });
+
+    it('should warn when aria-label is missing', async () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        container.innerHTML = '<ds-icon-button icon="add"></ds-icon-button>';
+
+        await new Promise(resolve => setTimeout(resolve, 50));
+
+        expect(warnSpy).toHaveBeenCalledWith('ds-icon-button: "aria-label" is required for accessibility');
+        warnSpy.mockRestore();
+    });
+});

package/src/ds-icon-button/index.js

@@ -0,0 +1 @@
+export { DsIconButton } from './ds-icon-button.js';