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.
Dropdown#
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#
- Use semantic tokens — never hardcode colors, use
tokens.semantic.* - Use design system components — don't create custom buttons, inputs, etc.
- Follow heading hierarchy — h1 > h2 > h3, no skipping levels
- Add aria-labels to icon-only buttons
- Use role="switch" with aria-checked for toggle buttons
- Test with keyboard — every interactive element must be keyboard accessible