Auto-generated reference for @pigna/component-library Every component follows the same folder convention, uses SCSS Modules with CSS custom properties from _tokens.scss, and is WCAG 2.2 AA compliant.

• Conventions
• Build Order
• Phase 1 — Leaf Components
  • CloseButton
  • TextLink
  • Spinner
  • SkeletonLoader
  • NotificationBadge
  • ProfilePicture
• Phase 2 — Composite Components
  • Banner
  • Dialog
  • Tag
  • Breadcrumb
  • Popover
  • ProgressIndicator
• Phase 3 — Form Components
  • FormField
  • Input
  • Textarea
  • Select
  • Checkbox
  • RadioGroup
  • Toggle
• Phase 4 — Navigation & Notifications
  • MenuItem
  • MenuItemGroup
  • SideMenu
  • HamburgerMenu
  • NotificationPopup
• Phase 5 — Documentation
  • ThemeColors
  • Tables

src/components/ComponentName/
  ├── ComponentName.tsx            # Component with typed props, JSDoc, ARIA
  ├── ComponentName.module.scss    # Scoped styles using CSS custom properties
  ├── ComponentName.stories.tsx    # Storybook stories with controls + a11y
  ├── ComponentName.test.tsx       # Vitest + Testing Library tests
  └── index.ts                     # Named re-export

src/components/Form/
  ├── FormField/
  ├── Input/
  ├── Textarea/
  ├── Select/
  ├── Checkbox/
  ├── RadioGroup/
  ├── Toggle/
  └── index.ts                     # Barrel re-export for all form components

• Extend native HTML attributes where possible (e.g. ButtonHTMLAttributes<HTMLButtonElement>)
• Always include ref?: Ref<HTMLElement> (React 19 — no forwardRef needed)
• Use JSDoc comments on every prop
• Export the interface and any union types

• Import @use '../../styles/mixins' as *; in every .module.scss
• Use CSS custom properties from _tokens.scss (never hardcode colors, spacing, etc.)
• Use @include focus-ring on all interactive elements
• Use @include sr-only for screen-reader-only text
• Use @include reduced-motion to disable animations for users who prefer it
• Use @include breakpoint-sm/md/lg/xl for mobile-first responsive styles

• Import types from @storybook/react-vite
• Use tags: ['autodocs'] for auto-generated docs
• Create individual stories for each variant/state
• Create a composite "All Variants" story

• Use vitest + @testing-library/react + @testing-library/user-event
• Test: renders correctly, ARIA attributes present, keyboard interaction, event callbacks, disabled/loading states

Components are built in dependency order. Phase 1 components have no internal dependencies. Each subsequent phase may depend on components from prior phases.

Reusable close/dismiss button with an × icon. Used by Dialog, Banner, NotificationPopup, Tag.

• Renders as <button type="button"> with aria-label
• SVG icon has aria-hidden="true"
• Keyboard focusable with visible :focus-visible ring

• Icon color: --color-text-secondary → --color-text-primary on hover
• Background: transparent → --color-surface on hover

Styled anchor component. Supports external links with automatic target="_blank", rel="noopener noreferrer", and a screen-reader "(opens in new tab)" announcement.

• Renders as native <a> element
• External links append <span class="sr-only">(opens in new tab)</span> for screen readers
• Visible :focus-visible ring via @include focus-ring

• Color: --color-primary
• Underline on hover
• Dark mode automatically adapts via --color-primary token

Animated loading spinner with screen-reader announcement.

• Container: role="status", aria-live="polite"
• Hidden sr-only <span> with label text
• Animation disabled when prefers-reduced-motion: reduce

• Spinner stroke: --color-primary

Placeholder loading shapes with a pulse animation. Supports text (multi-line), circle, and rectangle variants.

• Container: role="status", aria-busy="true"
• Sr-only <span> with "Loading…" text
• Visual skeleton elements: aria-hidden="true"
• Pulse animation disabled when prefers-reduced-motion: reduce

• Background pulse between --color-surface and --color-surface-raised

Small count/dot badge overlaid on a child element (e.g. a bell icon).

• Badge <span> has aria-label (e.g. "5 notifications")
• When dot, sr-only text "New notifications" is used
• When count is 0, badge is hidden and aria-label is omitted

• Background: --color-error
• Text: --color-text-inverse
• Positioned absolute relative to wrapper

Avatar component with image, fallback initials, and optional status indicator.

• <img> has the alt prop
• Initials fallback: <span role="img" aria-label="{alt}">
• Status indicator: sr-only <span> with status text (e.g. "Status: online")

• Fallback background: --color-surface-raised
• Fallback text: --color-text-secondary
• Status colors: online=--color-success, away=--color-warning, busy=--color-error, offline=--color-secondary
• Circle shape: border-radius: var(--radius-full)

Full-width informational banner with semantic variants and optional dismiss.

• role="alert" for error variant (assertive, interrupts screen reader)
• role="status" for info, warning, success (polite)
• CloseButton: aria-label="Dismiss banner"

• Left border accent: --color-info/warning/error/success
• Background: --color-info-subtle/warning-subtle/error-subtle/success-subtle
• Icon color matches the variant color

• Stacks icon + text vertically on mobile, inline on @include breakpoint-sm

Modal dialog using the native <dialog> element for built-in focus trapping and Escape-to-close.

• Native <dialog> with .showModal() — automatic focus trap, Escape handling, aria-modal="true"
• aria-labelledby pointing to the title element
• aria-describedby pointing to the content element
• Backdrop click calls onClose
• Focus returns to trigger element on close

• ::backdrop uses --color-overlay
• Surface: --color-surface-raised
• Shadow: --shadow-xl
• Z-index: --z-index-dialog

• Full screen on mobile (width: 100vw; height: 100vh)
• Centered card with max-width on @include breakpoint-sm

Informational tag/chip with optional color, link, and remove action.

• Remove button: aria-label="Remove {label}"
• Link variant: full anchor semantics via TextLink
• Keyboard: remove button focusable, Enter/Space triggers remove

• Default: --color-surface background, --color-border border
• Custom color prop overrides background with reduced opacity
• Text: --color-text-primary

Navigation breadcrumb trail. Compound component: Breadcrumb + BreadcrumbItem.

• <nav aria-label="Breadcrumb">
• <ol> ordered list
• Last item (no href): aria-current="page"
• Separators: aria-hidden="true"

• Separator + inactive text: --color-text-secondary
• Active link: --color-primary
• Current page: --color-text-primary, --font-weight-semibold

• Horizontal scroll with overflow-x: auto on narrow screens
• Items truncated with @include truncate when constrained

Floating content panel triggered by click or hover, positioned relative to a trigger element.

• Trigger: aria-expanded, aria-haspopup="dialog", aria-controls="{panelId}"
• Panel: role="dialog", id="{panelId}"
• Click mode: close on Escape, close on outside click
• Hover mode: close on mouse leave (with delay), close on Escape
• Focus management: first focusable element in panel receives focus on open

• Background: --color-surface-raised
• Border: --color-border
• Shadow: --shadow-lg
• Z-index: --z-index-popover

• Position flips when near viewport edge (CSS-based or JS fallback)
• Consider full-width on very small screens

Progress display in bar or circle form with percentage or step count.

• role="progressbar"
• aria-valuenow={value}, aria-valuemin={0}, aria-valuemax={max}
• aria-label for screen readers

• Track: --color-surface
• Fill: --color-primary
• Circle: SVG with stroke-dasharray animation
• Text: --color-text-secondary

All form components live under src/components/Form/ and share a common FormField wrapper that connects labels, error messages, and helper text via ARIA.

Wrapper component that links a label, input, error message, and helper text using ARIA attributes. Provides a useFormField() context hook for child inputs.

Returns { inputId, errorId, helperId, hasError } — used by child input components to wire aria-describedby and aria-invalid automatically.

• <label htmlFor="{inputId}">
• Error <span id="{errorId}"> — input links via aria-describedby
• Helper <span id="{helperId}"> — input links via aria-describedby
• Required: aria-required="true" on input, visible * indicator

• Label: --color-text-primary, --font-weight-medium
• Helper: --color-text-secondary, --font-size-sm
• Error: --color-error, --font-size-sm
• Required indicator: --color-error

Text input supporting multiple types with built-in validation patterns (overridable).

• Wraps with FormField — all ARIA wiring automatic
• aria-invalid="true" when error is present
• aria-describedby linked to error + helper spans
• aria-required when required

• Border: --color-border → --color-border-focus on focus → --color-error on error
• Background: --color-background
• Placeholder: --color-text-disabled
• Full-width by default

Multi-line text input with optional character count.

• Same ARIA wiring as Input via FormField
• When maxLength is set, display character count (e.g. "45/200")

Native dropdown select with options array.

• Native <select> — full keyboard support built-in
• Placeholder rendered as <option disabled selected hidden>

Single checkbox with custom styling and indeterminate support.

• Native <input type="checkbox"> with aria-checked (including "mixed" for indeterminate)
• aria-invalid when error
• Label via <label> wrapping the input
• Toggle via Space key (native)

• Custom styled via appearance: none + ::before pseudo-element
• Checked: --color-primary background with white checkmark
• Indeterminate: --color-primary background with – dash

Group of radio buttons rendered as a <fieldset> with <legend>.

• <fieldset> + <legend> (native group labeling)
• Native <input type="radio"> — arrow key navigation built-in
• aria-invalid on fieldset when error
• Error linked via aria-describedby

Toggle/switch input with on/off labels.

• role="switch" on the <input>
• aria-checked reflects state
• <label> association
• Toggle via Space or Enter key

• Track off: --color-secondary
• Track on: --color-primary
• Thumb: --color-text-inverse
• Transition: --transition-fast
• Min touch target: 44×24px

Single navigation item for use in menus. Renders as a link or button depending on props.

• role="menuitem"
• Active: aria-current="page"
• Disabled: aria-disabled="true"
• Keyboard focus management via tabIndex

• Active: --color-primary text, --color-surface background
• Hover: --color-surface background
• Disabled: --color-text-disabled, cursor: not-allowed

Collapsible group of MenuItems with a label/header.

• Trigger <button>: aria-expanded, toggles on click/Enter/Space
• Content region: role="group", aria-labelledby="{triggerId}"
• Collapse/expand animated with max-height transition

• Label: --font-weight-semibold, --color-text-secondary
• Separator: --color-border

Sidebar navigation composed of MenuItems and MenuItemGroups.

• <nav aria-label="{ariaLabel}">
• Inner <ul role="menu">

• Background: --color-surface
• Border-right: --color-border
• Width: fixed 260px on desktop

• Hidden below @include breakpoint-lg — replaced by HamburgerMenu

Mobile hamburger toggle button + slide-in menu panel with focus trapping.

• Toggle <button>: aria-expanded, aria-label="Open menu" / "Close menu"
• Panel: role="dialog", aria-modal="true"
• Custom focus trap (no external dependency)
• Close on Escape
• Close on overlay click

• Overlay: --color-overlay
• Panel background: --color-surface
• Slide-in: transform: translateX(-100%) → translateX(0)
• Animation disabled via @include reduced-motion

• Only visible below @include breakpoint-lg
• Hidden on desktop (SideMenu shown directly)

Toast notification card with pop-in animation, auto-dismiss, and close button.

• role="alert", aria-live="assertive"
• CloseButton: aria-label="Dismiss notification"
• Auto-dismiss pauses on hover/focus (gives user time to read)
• Animation disabled via @include reduced-motion

• Background: --color-surface-raised
• Shadow: --shadow-lg
• Left accent color: --color-info/success/warning/error (matches variant)
• Z-index: --z-index-notification
• Pop-in: @keyframes slideIn from right
• Fade-out: opacity transition

• Fixed bottom-right on desktop
• Full-width top on mobile

Storybook-only documentation page that displays all design tokens from _tokens.scss as visual swatches. Not exported from the public API.

A component that renders a table.

• Table can have header, body, footer sections
• Table can be sortable
• Table can be paginated
• Table can be searchable
• Table can be filtered
• Columns can be resizable
• Columns can be colored (Odd or even columns)
• Rows can be colored (Odd or even rows)
• Table can have a color

• title: 'Documentation/Theme Colors'
• Groups: Primary, Secondary, Semantic (success/warning/error/info), Surface, Text, Border
• Each swatch shows: color sample box, CSS variable name, computed hex value
• Renders in both light and dark themes (side by side or via Storybook theme toggle)
• Uses getComputedStyle(document.documentElement).getPropertyValue('--color-*') to read live values

CloseButton ─────┬── Banner
                  ├── Dialog (+ Button)
                  ├── Tag (+ TextLink)
                  ├── HamburgerMenu (+ SideMenu)
                  └── NotificationPopup

TextLink ─────────┬── Tag
                  └── Breadcrumb

FormField ────────┬── Input
                  ├── Textarea
                  ├── Select
                  └── Checkbox

MenuItem ─────────┬── MenuItemGroup
                  └── SideMenu ──── HamburgerMenu

(standalone)       Spinner, SkeletonLoader, NotificationBadge,
                   ProfilePicture, Popover, ProgressIndicator,
                   RadioGroup, Toggle, ThemeColors

After all components are built, the root barrel file exports everything:

// Existing
export { Button } from './components/Button';
export { CloseButton } from './components/CloseButton';

// Phase 1
export { TextLink } from './components/TextLink';
export { Spinner } from './components/Spinner';
export { SkeletonLoader } from './components/SkeletonLoader';
export { NotificationBadge } from './components/NotificationBadge';
export { ProfilePicture } from './components/ProfilePicture';

// Phase 2
export { Banner } from './components/Banner';
export { Dialog } from './components/Dialog';
export { Tag } from './components/Tag';
export { Breadcrumb, BreadcrumbItem } from './components/Breadcrumb';
export { Popover } from './components/Popover';
export { ProgressIndicator } from './components/ProgressIndicator';

// Phase 3 — Form
export {
  FormField,
  Input,
  Textarea,
  Select,
  Checkbox,
  RadioGroup,
  Toggle,
} from './components/Form';

// Phase 4
export { MenuItem } from './components/MenuItem';
export { MenuItemGroup } from './components/MenuItemGroup';
export { SideMenu } from './components/SideMenu';
export { HamburgerMenu } from './components/HamburgerMenu';
export { NotificationPopup } from './components/NotificationPopup';

// + all type exports

ThemeColors is NOT exported — it only exists as a Storybook documentation page.