Canonical interfaces for the components you build every day. Each one is a stable data contract — the what, independent of the how.
User image with fallback initials. The most fundamental identity primitive — appears inside profiles, comments, messages, and anywhere a person needs visual representation.
interface Avatar {
src?: string
alt: string
initials: string
size?: "xs" | "sm" | "md" | "lg" | "xl"
}Status label or count indicator. Used to communicate state (active, pending, error) or quantity (notification counts, unread messages) at a glance.
interface Badge {
label: string
variant?: "default" | "success" | "warning" | "error" | "info"
count?: number
}Action trigger with label and state. The universal interaction primitive — every form, dialog, toolbar, and card relies on buttons to initiate actions.
interface Button {
label: string
variant?: "primary" | "secondary" | "ghost" | "danger"
size?: "sm" | "md" | "lg"
disabled?: boolean
icon?: string
loading?: boolean
}Named icon with size and color. A semantic reference to a visual symbol, decoupled from the icon library or rendering method used by any particular shape.
interface Icon {
name: string
size?: number
color?: string
label?: string
}Categorization label for content. Used in blog posts, product listings, filters, and anywhere content needs to be classified or grouped by topic.
interface Tag {
label: string
color?: string
removable?: boolean
icon?: string
}Input with label, validation, and help text. The building block of every form — login screens, settings pages, checkout flows, and data entry interfaces all compose from this.
interface FormField {
name: string
label: string
type: "text" | "email" | "password" | "number" | "textarea"
value?: string
placeholder?: string
helpText?: string
error?: string
required?: boolean
}Navigation link with icon and active state. The recursive primitive for sidebars, tab bars, breadcrumbs, and menus — supports nesting for hierarchical navigation.
interface NavItem {
label: string
href: string
icon?: string
active?: boolean
badge?: number
children?: NavItem[]
}Metric display with label and trend indicator. Found in dashboards, analytics panels, and summary views wherever a key number needs context and direction.
interface Stat {
label: string
value: string | number
trend?: "up" | "down" | "flat"
change?: string
icon?: string
}Contextual hover content with placement. Provides supplementary information without cluttering the interface — used on icons, truncated text, and action buttons.
interface Tooltip {
content: string
placement?: "top" | "bottom" | "left" | "right"
delay?: number
}Title, excerpt, and metadata from a search hit. The universal result primitive — search engines, command palettes, autocomplete dropdowns, and filter results all use this shape.
interface SearchResult {
title: string
excerpt: string
url: string
type?: string
highlight?: string
meta?: Record<string, string>
}Full user identity with name, avatar, role, and membership date. Composes Avatar and Badge atoms into a complete identity representation for profile pages, team lists, and about sections.
interface UserProfile {
name: string
avatar?: string
initials: string
role: string
email?: string
joinedAt: Date
bio?: string
}Content container with media, title, description, and actions. The workhorse of content display — product listings, blog previews, dashboard widgets, and feature showcases all use cards.
interface Card {
title: string
description?: string
media?: { src: string; alt: string }
actions?: { label: string; href: string }[]
tags?: string[]
footer?: string
}Notification with severity, message, and optional action. System feedback for success confirmations, error messages, warnings, and informational banners that demand user attention.
interface Alert {
message: string
severity: "info" | "success" | "warning" | "error"
title?: string
dismissible?: boolean
action?: { label: string; href: string }
}Row with icon, primary/secondary text, and actions. The repeatable unit of any list — email inboxes, file browsers, settings panels, and contact lists all build from this primitive.
interface ListItem {
primary: string
secondary?: string
icon?: string
avatar?: string
actions?: { label: string; icon?: string }[]
href?: string
selected?: boolean
}Image, video, or audio with title, description, and metadata. The universal media primitive for galleries, playlists, file managers, and content management systems.
interface MediaItem {
src: string
type: "image" | "video" | "audio"
title: string
description?: string
duration?: number
thumbnail?: string
alt?: string
}Table row with typed columns, selection, and link state. The building block of data tables — admin panels, spreadsheets, CRM views, and reporting dashboards compose rows into grids.
interface DataRow {
id: string
cells: Record<string, string | number | boolean>
selected?: boolean
disabled?: boolean
href?: string
}Navigation path with labeled segments. Shows the user where they are in a hierarchy — essential for deep navigation in e-commerce, documentation, and file system interfaces.
interface Breadcrumb {
segments: {
label: string
href?: string
icon?: string
}[]
separator?: string
}Chronological event with timestamp, actor, and content. The unit of activity feeds, audit logs, version histories, and project tracking — anything ordered by time.
interface TimelineEntry {
timestamp: Date
title: string
description?: string
icon?: string
actor?: { name: string; avatar?: string }
type?: "event" | "milestone" | "comment"
}Page state with total items, current position, and page size. The universal navigation contract for paginated data — search results, tables, galleries, and infinite scroll all need this.
interface Pagination {
totalItems: number
currentPage: number
perPage: number
totalPages: number
}Dialog with title, content, actions, and dismiss behavior. The overlay primitive for confirmations, forms, detail views, and any focused interaction that interrupts the main flow.
interface Modal {
title: string
content: string
open: boolean
dismissible?: boolean
size?: "sm" | "md" | "lg"
actions?: { label: string; variant?: string }[]
}Every interface here is a starting point. Build shapes that render them. Compose them into larger interfaces. Publish your own intershapes and help grow the shared vocabulary.