Eve library

OSHUN Design System

Guide

Revision 1

On this page

Component reference for the OSHUN web app design system.

Components#

Button#

Interactive button with multiple variants, sizes, and states.

Prop Type Default Description
variant 'primary' | 'secondary' | 'ghost' | 'destructive' | 'domain' 'primary' Visual variant
size 'sm' | 'md' | 'lg' 'md' Size variant
loading boolean false Shows spinner, sets aria-busy
leadingIcon ReactNode — Icon before label
trailingIcon ReactNode — Icon after label
fullWidth boolean false Stretch to container width
disabled boolean false Disable interaction

When to use: Primary actions (submit, save, confirm), secondary actions (cancel, back), destructive actions (delete, remove).


IconButton#

Icon-only button with built-in tooltip and aria-label.

Prop Type Default Description
icon ReactNode required The icon element
label string required Accessible label and tooltip text
size 'sm' | 'md' | 'lg' 'md' Size variant
variant 'ghost' | 'outline' 'ghost' Visual variant
showTooltip boolean true Show tooltip on hover
disabled boolean false Disable interaction

When to use: Toolbar actions, compact controls where icon meaning is clear (close, settings, notifications).


Tabs#

Accessible tab interface with roving tabindex and animated indicator.

Prop Type Default Description
tabs TabItem[] required Tab definitions
activeTab string required Currently active tab ID
onChange (tabId: string) => void required Tab change handler
domain DomainName — Domain accent color
size 'sm' | 'md' 'md' Size variant

ARIA: Uses role="tablist", role="tab", aria-selected, aria-controls, and roving tabIndex.

Keyboard: ArrowLeft/Right to navigate, Home/End for first/last tab.


Menu dropdown with keyboard navigation and proper ARIA.

Prop Type Default Description
trigger ReactNode required Trigger element
items DropdownItem[] required Menu items
onSelect (id: string) => void required Selection handler
align 'start' | 'end' 'start' Menu alignment

ARIA: aria-haspopup="menu", aria-expanded, role="menu", role="menuitem", aria-activedescendant.

Keyboard: Enter/Space/ArrowDown to open, Arrow keys to navigate, Enter/Space to select, Escape to close, Home/End for first/last item.


SearchInput#

Search input with clear button, loading state, and shortcut hint.

Prop Type Default Description
value string required Controlled value
onValueChange (value: string) => void required Change handler
loading boolean false Show loading spinner
shortcutHint string — Keyboard shortcut hint (e.g., "Ctrl+K")
size 'sm' | 'md' 'md' Size variant
placeholder string 'Search...' Placeholder text

Accessibility: type="search", auto-derives aria-label from placeholder, clear button has aria-label="Clear search".


OverlaySheet#

Modal bottom sheet with focus trap, scroll lock, and restore.

Prop Type Default Description
open boolean required Open state
onClose () => void required Close handler
title string — Header title
description string — Header description
footer ReactNode — Sticky footer content
maxWidth number 540 Maximum sheet width
disableBackdropClose boolean false Disable backdrop click close

Accessibility: role="dialog", aria-modal="true", focus trap with Tab cycling, Escape to close, focus restoration on close, body scroll lock.


Toast / ToastProvider#

Toast notification system with auto-dismiss and screen reader support.

Provider: Wrap app in <ToastProvider>. Access via useToast() hook.

Toast variants: success, error, warning, info.

ToastMessage Prop Type Default Description
variant ToastVariant required Visual variant
title string required Toast title
description string — Description text
duration number 5000 Auto-dismiss ms (0 = never)
action { label, onClick } — Action button

Accessibility: role="alert", aria-live="assertive", dismiss button with aria-label="Dismiss notification".


Skeleton#

Loading placeholder with animated shimmer effect.

Prop Type Default Description
width string | number '100%' Width
height number 16 Height in px
radius string | number tokens.radii.md Border radius
lines number 1 Number of lines
gap number 8 Gap between lines
circle boolean false Circle shape (avatar)

Presets: KpiGridSkeleton, HeroBannerSkeleton, SplitGridSkeleton, DomainCardGridSkeleton, DomainSurfaceSkeleton, ActivityListSkeleton, ExploreSkeleton.


VirtualList#

Virtualized list for long content (sessions, articles, observations).

Prop Type Default Description
items T[] required Items array
estimatedItemHeight number required Estimated row height
renderItem (item, index) => ReactNode required Render function
overscan number 5 Extra items above/below viewport
getKey (item, index) => string | number — Key extractor

Design Tokens#

All components use semantic tokens from @/design-system/tokens:

  • Colors: tokens.semantic.text.*, tokens.semantic.surface.*, tokens.semantic.accent.*, tokens.semantic.status.*
  • Typography: tokens.typeScale.*, tokens.fontWeights.*, tokens.fontFamilies.*
  • Spacing: tokens.spacing.* (4px grid)
  • Radii: tokens.radii.* (xs=4, sm=6, md=8, lg=12, xl=16, 2xl=20, full=9999)
  • Shadows: tokens.shadows.* (sm, md, lg, xl)
  • Motion: tokens.motion.duration.*, tokens.motion.easing.*
  • Z-index: tokens.zIndex.* (dropdown, modal, toast, etc.)

Usage Guidelines#

  1. Use semantic tokens — never hardcode colors, use tokens.semantic.*
  2. Use design system components — don't create custom buttons, inputs, etc.
  3. Follow heading hierarchy — h1 > h2 > h3, no skipping levels
  4. Add aria-labels to icon-only buttons
  5. Use role="switch" with aria-checked for toggle buttons
  6. Test with keyboard — every interactive element must be keyboard accessible