@ds-mo/ui 0.2.3 → 0.3.0

package/src/components/Banner/Banner.module.css

@@ -30,12 +30,50 @@
 .bannerBody {
   padding: var(--dimension-space-075);
   min-height: var(--dimension-size-400);
+  display: flex;
+  align-items: flex-start;
+  gap: var(--dimension-space-075);
 }
 
 .message {
   color: var(--banner-content);
   line-height: var(--typography-lineheight-md);
   display: block;
+  flex: 1;
+  min-width: 0;
+}
+
+.dismiss {
+  background: none;
+  border: none;
+  margin: 0;
+  padding: var(--dimension-space-025);
+  color: var(--banner-content);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border-radius: var(--dimension-radius-050);
+  position: relative;
+}
+
+.dismiss::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background-color: transparent;
+  transition: var(--effect-transition-interaction-background-short-2);
+  pointer-events: none;
+}
+
+.dismiss:hover::before  { background-color: var(--color-interaction-hover); }
+.dismiss:active::before { background-color: var(--color-interaction-pressed); }
+
+.dismiss:focus-visible {
+  outline: var(--dimension-stroke-width-025) solid var(--color-interaction-focus);
+  outline-offset: var(--dimension-stroke-width-015);
 }
 
 .floatingPosition {

package/src/components/Banner/Banner.tsx

@@ -1,5 +1,6 @@
 import React, { useState, useEffect, useCallback, useRef } from 'react';
 import { createPortal } from 'react-dom';
+import { Cross } from '@ds-mo/icons';
 import { Surface } from '@/components/Surface';
 import { Text } from '@/components/Text';
 import { getCssTimeMs } from '@/utils/css-tokens';
@@ -22,6 +23,8 @@ export interface BannerProps {
   className?: string;
   floating?: boolean;
   onDismiss?: () => void;
+  /** Accessible label for the dismiss button. Defaults to "Dismiss". */
+  dismissLabel?: string;
 }
 
 const getContentColorVar = (intent: BannerIntent, contrast: BannerContrast): string => {
@@ -38,6 +41,7 @@ export const Banner: React.FC<BannerProps> = ({
   className = '',
   floating = false,
   onDismiss,
+  dismissLabel = 'Dismiss',
 }) => {
   const toastDurationMs = getCssTimeMs('--effect-animation-delay-long-2', TOAST_DURATION_FALLBACK_MS);
   const messageColor = getContentColorVar(intent, contrast);
@@ -45,18 +49,28 @@ export const Banner: React.FC<BannerProps> = ({
   const dismissTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const closeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const scheduleDismiss = useCallback(() => {
+  const beginClose = useCallback(() => {
     if (dismissTimerRef.current) clearTimeout(dismissTimerRef.current);
     if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
-    dismissTimerRef.current = setTimeout(() => {
-      dismissTimerRef.current = null;
+    dismissTimerRef.current = null;
+    if (floating) {
       setIsClosing(true);
       closeTimerRef.current = setTimeout(() => {
         closeTimerRef.current = null;
         onDismiss?.();
       }, FADE_OUT_DURATION_MS);
+    } else {
+      onDismiss?.();
+    }
+  }, [floating, onDismiss]);
+
+  const scheduleDismiss = useCallback(() => {
+    if (dismissTimerRef.current) clearTimeout(dismissTimerRef.current);
+    dismissTimerRef.current = setTimeout(() => {
+      dismissTimerRef.current = null;
+      beginClose();
     }, toastDurationMs);
-  }, [onDismiss, toastDurationMs]);
+  }, [beginClose, toastDurationMs]);
 
   useEffect(() => {
     if (floating && message) scheduleDismiss();
@@ -66,10 +80,16 @@ export const Banner: React.FC<BannerProps> = ({
     };
   }, [floating, message, scheduleDismiss]);
 
+  const isAssertive = intent === 'negative';
+  const role = isAssertive ? 'alert' : 'status';
+  const ariaLive = isAssertive ? undefined : 'polite';
+
   const content = (
     <div
       className={`${styles.bannerWrapper} ${className}`.trim()}
       style={{ '--banner-content': messageColor } as React.CSSProperties}
+      role={role}
+      aria-live={ariaLive}
     >
       <Surface
         elevation={floating ? 'floating' : 'elevated'}
@@ -87,6 +107,16 @@ export const Banner: React.FC<BannerProps> = ({
           <Text variant="text-body-medium" as="span" className={styles.message}>
             {message}
           </Text>
+          {onDismiss && (
+            <button
+              type="button"
+              className={styles.dismiss}
+              onClick={beginClose}
+              aria-label={dismissLabel}
+            >
+              <Cross size={16} />
+            </button>
+          )}
         </div>
       </Surface>
     </div>

package/src/components/Button/Button.mdx

@@ -0,0 +1,143 @@
+import { Meta, Title, Subtitle, Canvas, Controls, Primary } from '@storybook/addon-docs/blocks';
+import * as ButtonStories from './Button.stories';
+
+<Meta of={ButtonStories} />
+
+<Title />
+
+<Subtitle>
+  Buttons trigger actions. They are the primary way users commit to a decision —
+  saving a record, opening a dialog, navigating somewhere meaningful.
+</Subtitle>
+
+A button should make its purpose obvious from its label, its visual weight, and
+its position on the page. The right button in the right place is invisible — it
+just feels like the next step. The wrong button competes for attention and slows
+the user down.
+
+## Playground
+
+Use the controls below to explore every prop the component accepts. This is the
+fastest way to understand how `variant`, `intent`, `contrast`, and `elevation`
+combine.
+
+<Primary />
+
+<Controls />
+
+## When to use
+
+Reach for a button when the user needs to perform an **action** — submit a form,
+delete a record, open a panel, run a process. If the user is navigating between
+pages or sections, prefer a link instead. Buttons are for verbs; links are for
+nouns.
+
+A page should have **one** clearly dominant button. If two actions look equally
+important, the user has to stop and read both before deciding — which is exactly
+the moment of friction good hierarchy avoids.
+
+## Variants
+
+`primary` is filled and carries the strongest visual weight. Use it for the one
+action you most want the user to take on a given screen.
+
+`secondary` is a softer treatment for actions that matter but should not compete
+with the primary action. Use `elevation="none"` to get the ghost treatment for
+tertiary actions like cancel, dismiss, or inline controls.
+
+<Canvas of={ButtonStories.Variants} />
+
+> **Do** pair one `primary` with one or more `secondary` buttons in a form footer.
+>
+> **Don't** stack two `primary` buttons next to each other — only one action can
+> be the primary one.
+
+## Intent
+
+Intent communicates the **meaning** of the action through color. Most buttons
+should use `brand` (the default) or `neutral`. Reserve semantic intents for
+moments when the meaning genuinely matches.
+
+<Canvas of={ButtonStories.Intents} />
+
+- `brand` — the default for primary calls-to-action
+- `neutral` — for actions that should not draw color, like filters or toolbar controls
+- `negative` — for destructive actions (delete, remove, discard)
+- `positive` — for confirmations of a successful state, used sparingly
+- `warning` / `caution` — for actions that need a moment of pause
+- `ai` — reserved for AI-generated or AI-triggering actions
+- `none` — inverted styling for use on colored or dark surfaces
+
+> **Don't** use `negative` intent for a cancel button. Cancel is not destructive;
+> it is the absence of an action. Use `secondary` with no intent.
+
+## Sizes
+
+Pick a size from the surrounding density, not the importance of the action.
+Forms and dialogs use `md`. Compact toolbars and table rows use `sm` or `xs`.
+Hero sections and marketing surfaces can use `lg`.
+
+<Canvas of={ButtonStories.Sizes} />
+
+## Icons
+
+A leading icon can clarify a button's purpose at a glance — but only when the
+icon's meaning is unambiguous. If you have to think about which icon to pick,
+the label alone is doing a better job.
+
+<Canvas of={ButtonStories.IconAndLabel} />
+
+Icon-only buttons must always have an `aria-label`. Without it, screen readers
+announce nothing meaningful, and keyboard users lose all context.
+
+<Canvas of={ButtonStories.IconOnly} />
+
+## States
+
+Buttons have several states that communicate progress or availability:
+
+- `inactive` — the action is not currently available, but may become available
+- `loading` — the action is in flight; prevents double-submission
+- `rounded` — pill-shaped variant for filter chips and compact actions
+
+<Canvas of={ButtonStories.Loading} />
+
+<Canvas of={ButtonStories.Inactive} />
+
+> **Do** use `loading` for any async action that takes longer than ~200ms.
+> Without it, users will click again, often submitting twice.
+
+## Full width
+
+Use `fullWidth` inside narrow containers like mobile sheets, side panels, or
+form footers where the button should fill the available width. Avoid full-width
+buttons on wide desktop layouts — they read as banner CTAs and feel heavy.
+
+<Canvas of={ButtonStories.FullWidth} />
+
+## On colored surfaces
+
+When a button sits on a colored or dark surface, set the `background` prop so
+the button can adapt its contrast to remain legible. The `BackgroundContext`
+story below demonstrates every variant against every supported surface.
+
+<Canvas of={ButtonStories.BackgroundContext} />
+
+## Accessibility
+
+- Every button must have a discernible name — either visible text in `label` or
+  an `aria-label` for icon-only buttons.
+- The `inactive` state is **not** the same as the HTML `disabled` attribute.
+  `inactive` keeps the button focusable and announceable; truly disabled buttons
+  vanish from the tab order and frustrate users who can't tell why an action
+  isn't working.
+- Touch targets meet the 24×24 CSS pixel minimum at all sizes; `xs` is intended
+  for dense desktop UIs and should not be used on mobile.
+
+## Full reference matrix
+
+The matrix below renders every meaningful combination of `variant`, `intent`,
+`contrast`, `elevation`, `size`, and state on a single canvas. Use it as a
+visual regression reference when changing tokens or styles.
+
+<Canvas of={ButtonStories.Matrix} />

package/src/components/Button/Button.stories.tsx

@@ -66,7 +66,7 @@ const ELEVATIONS: ButtonElevation[] = ['elevated', 'flat', 'none', 'floating'];
 
 const col: React.CSSProperties = { display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'flex-start' };
 const row: React.CSSProperties = { display: 'flex', gap: 8, alignItems: 'center' };
-const lbl = (text: string): React.CSSProperties => ({ fontSize: 10, fontFamily: 'monospace', color: '#888', minWidth: 80, flexShrink: 0 });
+const lbl = (_text: string): React.CSSProperties => ({ fontSize: 10, fontFamily: 'monospace', color: '#888', minWidth: 80, flexShrink: 0 });
 const section = (text: string) => (
   <div style={{ fontSize: 11, fontWeight: 600, letterSpacing: '0.05em', textTransform: 'uppercase', color: '#555', marginTop: 8 }}>
     {text}

package/src/components/Button/Button.tsx

@@ -14,13 +14,11 @@ export type ButtonSize     = 'xs' | 'sm' | 'md' | 'lg';
 export type ButtonContrast = 'strong' | 'bold' | 'medium' | 'faint';
 export type ButtonBackground = 'faint' | 'medium' | 'bold' | 'strong' | 'always-dark';
 
-export interface ButtonProps {
+interface ButtonBaseProps {
   /** Polymorphic element type. Defaults to 'button'. */
   as?: React.ElementType;
   /** Visual variant. Defaults to 'primary'. */
   variant?: ButtonVariant;
-  /** Label text. */
-  label?: string;
   /** Leading icon component from @ds-mo/icons. */
   icon?: IconComponent;
   /** Semantic intent. Defaults to 'brand'. */
@@ -67,12 +65,24 @@ export interface ButtonProps {
   inactive?: boolean;
   type?: 'button' | 'submit' | 'reset';
   id?: string;
-  'aria-label'?: string;
   href?: string;
   target?: string;
   rel?: string;
 }
 
+/**
+ * Accessible-name requirement: a Button must expose text via `label`,
+ * `aria-label`, or `aria-labelledby`. Icon-only buttons that omit all three
+ * fail at the call site (TypeScript), with a runtime warning as a soft
+ * fallback for callers that bypass the type system.
+ */
+type ButtonAccessibleNameProps =
+  | { label: string; 'aria-label'?: string; 'aria-labelledby'?: string }
+  | { label?: string; 'aria-label': string; 'aria-labelledby'?: string }
+  | { label?: string; 'aria-label'?: string; 'aria-labelledby': string };
+
+export type ButtonProps = ButtonBaseProps & ButtonAccessibleNameProps;
+
 const ICON_SIZE_MAP: Record<ButtonSize, number> = { xs: 12, sm: 16, md: 20, lg: 24 };
 
 const TEXT_STYLE_MAP: Record<ButtonSize, string> = {
@@ -84,8 +94,8 @@ const TEXT_STYLE_MAP: Record<ButtonSize, string> = {
 
 
 export const Button = forwardRef<HTMLElement, ButtonProps>(
-  (
-    {
+  (props, ref) => {
+    const {
       as,
       variant = 'primary',
       label,
@@ -109,14 +119,16 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(
       type = 'button',
       id,
       'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
       href,
       target,
       rel,
-    },
-    ref
-  ) => {
+    } = props;
+
     const Component = (as ?? 'button') as React.ElementType;
     const isButton = !as || as === 'button';
+    const isLink = as === 'a';
+    const isCustomInteractive = !isButton && !isLink;
     const isInteractive = !inactive && !loading;
 
     const hasIcon = !!Icon;
@@ -153,7 +165,11 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(
       className,
     );
 
-    const resolvedAriaLabel = ariaLabel || label || 'button';
+    if (isIconOnly && !ariaLabel && !ariaLabelledBy) {
+      console.warn(
+        '[@ds-mo/ui Button] Icon-only Button is missing an accessible name. Provide `label`, `aria-label`, or `aria-labelledby`.'
+      );
+    }
 
     const extraProps: Record<string, unknown> = {};
     if (isButton) {
@@ -164,6 +180,19 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(
     if (target) extraProps.target = target;
     if (rel) extraProps.rel = rel;
 
+    if (isCustomInteractive) {
+      extraProps.role = 'button';
+      extraProps.tabIndex = isInteractive ? 0 : -1;
+      if (isInteractive) {
+        extraProps.onKeyDown = (e: React.KeyboardEvent<HTMLElement>) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            (e.currentTarget as HTMLElement).click();
+          }
+        };
+      }
+    }
+
     return (
       <Component
         ref={ref}
@@ -173,7 +202,9 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(
         onClick={isInteractive ? onClick : undefined}
         onMouseEnter={isInteractive ? onMouseEnter : undefined}
         onMouseLeave={isInteractive ? onMouseLeave : undefined}
-        aria-label={resolvedAriaLabel}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-disabled={inactive || loading || undefined}
         aria-busy={loading || undefined}
         {...extraProps}
       >

package/src/components/Checkbox/Checkbox.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef } from 'react';
+import React, { forwardRef, useId } from 'react';
 import { cn } from '@/utils/cn';
 import { Text } from '@/components/Text';
 import type { IconComponent } from '@/types/icons';
@@ -34,6 +34,7 @@ export const Checkbox = forwardRef<HTMLDivElement, CheckboxProps>(
     },
     ref
   ) => {
+    const labelId = useId();
     const handleClick = () => {
       if (!inactive) onChange?.(!checked);
     };
@@ -46,7 +47,9 @@ export const Checkbox = forwardRef<HTMLDivElement, CheckboxProps>(
         ref={ref}
         role="checkbox"
         aria-checked={indeterminate ? 'mixed' : checked}
-        aria-inactive={inactive}
+        aria-disabled={inactive || undefined}
+        aria-labelledby={labelId}
+        data-inactive={inactive || undefined}
         tabIndex={inactive ? -1 : 0}
         className={cn(styles.checkbox, inactive && styles.inactive, className)}
         onClick={handleClick}
@@ -57,7 +60,7 @@ export const Checkbox = forwardRef<HTMLDivElement, CheckboxProps>(
             {(checked || indeterminate) && <span className={styles.checkmark}>{indeterminate ? '−' : '✓'}</span>}
           </span>
         )}
-        <Text variant="text-body-medium" as="span" color="inherit">
+        <Text id={labelId} variant="text-body-medium" as="span" color="inherit">
           {label}
         </Text>
       </div>

package/src/components/Field/Field.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef } from 'react';
+import React, { forwardRef, useId, isValidElement, cloneElement } from 'react';
 import { cn } from '@/utils/cn';
 import { Text } from '@/components/Text';
 import styles from './Field.module.css';
@@ -11,12 +11,25 @@ export interface FieldProps {
 }
 
 export const Field = forwardRef<HTMLDivElement, FieldProps>(
-  ({ label, children, id, className }, ref) => (
-    <div ref={ref} className={cn(styles.field, className)}>
-      <Text variant="text-body-small-emphasis" as="label" htmlFor={id}>{label}</Text>
-      {children}
-    </div>
-  )
+  ({ label, children, id, className }, ref) => {
+    const generatedId = useId();
+    const fieldId = id ?? generatedId;
+
+    let content = children;
+    if (isValidElement(children)) {
+      const childProps = children.props as { id?: string };
+      if (childProps.id === undefined) {
+        content = cloneElement(children as React.ReactElement<{ id?: string }>, { id: fieldId });
+      }
+    }
+
+    return (
+      <div ref={ref} className={cn(styles.field, className)}>
+        <Text variant="text-body-small-emphasis" as="label" htmlFor={fieldId}>{label}</Text>
+        {content}
+      </div>
+    );
+  }
 );
 
 Field.displayName = 'Field';

package/src/components/Input/Input.module.css

@@ -1,3 +1,10 @@
+.container {
+  display: flex;
+  flex-direction: column;
+  gap: var(--dimension-space-050);
+  width: 100%;
+}
+
 .wrapper {
   width: 100%;
   height: var(--dimension-size-400);
@@ -13,6 +20,20 @@
   box-shadow: inset 0 0 0 1.25px var(--color-foreground-bold-brand);
 }
 
+.wrapperError {
+  box-shadow: inset 0 0 0 1.25px var(--color-border-bold-negative);
+}
+
+.wrapperError:focus-within {
+  box-shadow: inset 0 0 0 1.25px var(--color-border-bold-negative);
+}
+
+.errorText {
+  font-size: var(--typography-fontsize-sm);
+  line-height: var(--typography-lineheight-sm);
+  color: var(--color-foreground-bold-negative);
+}
+
 .row {
   display: flex;
   align-items: center;

package/src/components/Input/Input.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef } from 'react';
+import React, { forwardRef, useEffect, useId } from 'react';
 import { cn } from '@/utils/cn';
 import type { IconComponent } from '@/types/icons';
 import styles from './Input.module.css';
@@ -20,8 +20,19 @@ export interface InputProps {
   /** Icon for clear button (search type). */
   clearIcon?: IconComponent;
   'aria-label'?: string;
+  'aria-labelledby'?: string;
+  'aria-describedby'?: string;
+  /** Marks the input as invalid; sets `aria-invalid` and applies error styling. */
+  error?: boolean;
+  /** Message rendered below the input when `error` is true; auto-linked via `aria-describedby`. */
+  errorMessage?: string;
 }
 
+const isDevEnv = (): boolean => {
+  const meta = import.meta as { env?: { DEV?: boolean } };
+  return Boolean(meta.env?.DEV);
+};
+
 export const Input = forwardRef<HTMLDivElement, InputProps>(
   (
     {
@@ -37,37 +48,67 @@ export const Input = forwardRef<HTMLDivElement, InputProps>(
       suffix,
       clearIcon: ClearIcon,
       'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledBy,
+      'aria-describedby': ariaDescribedBy,
+      error = false,
+      errorMessage,
     },
     ref
   ) => {
+    const reactId = useId();
+    const errorId = `${reactId}-error`;
     const showClear = type === 'search' && value.length > 0 && !inactive;
+    const showErrorMessage = error && Boolean(errorMessage);
+
+    const describedBy =
+      [ariaDescribedBy, showErrorMessage ? errorId : undefined].filter(Boolean).join(' ') ||
+      undefined;
+
+    useEffect(() => {
+      if (!isDevEnv()) return;
+      if (!id && !ariaLabel && !ariaLabelledBy) {
+        console.warn(
+          '[@ds-mo/ui] <Input> is missing an accessible name. Provide one of: `id` (paired with a <label htmlFor>), `aria-label`, or `aria-labelledby`.'
+        );
+      }
+    }, [id, ariaLabel, ariaLabelledBy]);
 
     const handleClear = () => {
       onChange({ target: { value: '' } } as React.ChangeEvent<HTMLInputElement>);
     };
 
     return (
-      <div ref={ref} className={cn(styles.wrapper, className)}>
-        <div className={styles.row}>
-          <input
-            type={type}
-            id={id}
-            value={value}
-            onChange={onChange}
-            onKeyDown={onKeyDown}
-            placeholder={placeholder}
-            className={styles.input}
-            autoFocus={autoFocus}
-            disabled={inactive}
-            aria-label={ariaLabel}
-          />
-          {showClear && (
-            <button type="button" className={styles.clearButton} onClick={handleClear} aria-label="Clear">
-              {ClearIcon ? <ClearIcon size={16} /> : <span aria-hidden>&times;</span>}
-            </button>
-          )}
-          {suffix && <div className={styles.suffix}>{suffix}</div>}
+      <div className={styles.container}>
+        <div ref={ref} className={cn(styles.wrapper, error && styles.wrapperError, className)}>
+          <div className={styles.row}>
+            <input
+              type={type}
+              id={id}
+              value={value}
+              onChange={onChange}
+              onKeyDown={onKeyDown}
+              placeholder={placeholder}
+              className={styles.input}
+              autoFocus={autoFocus}
+              disabled={inactive}
+              aria-label={ariaLabel}
+              aria-labelledby={ariaLabelledBy}
+              aria-describedby={describedBy}
+              aria-invalid={error || undefined}
+            />
+            {showClear && (
+              <button type="button" className={styles.clearButton} onClick={handleClear} aria-label="Clear">
+                {ClearIcon ? <ClearIcon size={16} /> : <span aria-hidden>&times;</span>}
+              </button>
+            )}
+            {suffix && <div className={styles.suffix}>{suffix}</div>}
+          </div>
         </div>
+        {showErrorMessage && (
+          <div id={errorId} role="alert" className={styles.errorText}>
+            {errorMessage}
+          </div>
+        )}
       </div>
     );
   }

package/src/components/Loader/Loader.module.css

@@ -3,6 +3,23 @@
   animation: spin 0.75s linear infinite;
 }
 
+.status {
+  display: inline-flex;
+  align-items: center;
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 @keyframes spin {
   from { transform: rotate(0deg); }
   to   { transform: rotate(360deg); }

package/src/components/Loader/Loader.stories.tsx

@@ -14,6 +14,15 @@ type Story = StoryObj<typeof Loader>;
 
 export const Default: Story = {};
 
+/**
+ * Standalone usage with an accessible label. Wraps the spinner in a
+ * `role="status"` live region and renders a visually-hidden label so
+ * screen readers announce the loading state on mount.
+ */
+export const WithLabel: Story = {
+  args: { label: 'Loading' },
+};
+
 /** Shows how stroke weight scales naturally with size — same as icon strokes. */
 export const Sizes: Story = {
   render: () => (