Primitive Reference

UI Components

Shared practical primitives for building interfaces quickly and consistently.

Jump to section

Buttons

Shared action primitives for CTAs, navigation, and inline flows.

Call-To-Action Variants

Default and primary buttons are solid. Use gradient only when the button should carry explicit marketing emphasis.

<Button>Default</Button>
<Button variant="primary">Primary Solid</Button>
<Button variant="gradient">Gradient Marketing</Button>
<Button variant="secondary">Secondary</Button>

Structural Variants

Use these when the surrounding layout already provides the emphasis.

<Button variant="solid">Solid</Button>
<Button variant="neutral">Neutral</Button>
<Button variant="glass">Glass</Button>
<Button variant="alt">Outline</Button>

Filled Variants

Use filled buttons when the CTA needs a solid surface and a visible token border.

<Button variant="filled-primary">Filled Primary</Button>
<Button variant="filled-secondary">Filled Secondary</Button>
<Button variant="filled-dark">Filled Dark</Button>
<Button variant="filled-light">Filled Light</Button>

Outline Variants

Use outline buttons for secondary CTAs on light, dark, and branded surfaces.

<Button variant="outline-dark">Outline Dark</Button>
<Button variant="outline-light">Outline Light</Button>
<Button variant="outline-primary">Outline Primary</Button>
<Button variant="outline-secondary">Outline Secondary</Button>

Action vs Navigation

The same component renders a button for actions and a link for navigation.

Browse Sections

<Button variant="solid">Save Changes</Button>
<Button variant="neutral" href="/sections">Browse Sections</Button>

Directional Controls

Use the specialized button and link helpers for carousels and “read more” style flows.

Explore subsection patterns

<ArrowCircleButton direction="next" onClick={...} label="Next" />
<ArrowCircleLink href="/projects" label="Open project" />
<ArrowLink href="/sections/patterns" label="Explore subsection patterns" />

Buttons With Supporting Icons

Use icons to reinforce direction or confirmation, not to replace text labels.

<Button variant="primary">
  <span className="tw:text-slide-hover" data-text="Confirm">
    <span>Confirm</span>
  </span>
  <CheckIcon className="tw:size-icon-xs tw:shrink-0" />
</Button>
<Button variant="primary" showArrow>Start Project</Button>
<Button variant="gradient" showArrow>Launch Campaign</Button>
<Button variant="glass" enableRipple showArrow>Continue</Button>

Action State Continuity

The controlled action keeps every label in one sizing slot, prevents repeat submission while pending, and swaps instantly when reduced motion is enabled.

<ActionButton
  state={status}
  loadingText="Publishing…"
  successText="Published"
  errorText="Try again"
  onClick={publish}
>
  Publish changes
</ActionButton>

Cards

Surface primitives for content groupings, feature lists, and compact compositions.

Default

Use for standard content on the base page surface.

<Card variant="default">...</Card>

Gloss

Use when you want a more atmospheric or premium surface treatment.

<Card variant="gloss">...</Card>

Elevated

Use for emphasis, comparison, or stacked panels within dense layouts.

<Card variant="elevated">...</Card>

Interactive Surface States

Use the Card hover API for common lift behavior, and compose restricted utilities for specialized effects.

hoverEffect prop

scale utilities

glow utilities

shine utility

<Card variant="gloss" hoverEffect="hover-lift">Interactive card</Card>
<Card variant="gloss" className="motion-demo-scale-hover tw:motion-demo-scale-hover">Scale card</Card>

Composed Product Card

This is the usual pattern: card surface plus tags, text, and a button group.

FEATURED PATTERN

Reusable Marketing Card

Compose from the primitive. Do not invent a new base card if layout is the only difference.

UILibraryReact

See Sections

Media

Use media primitives for compact identity UI, especially team cards, testimonials, and author blocks.

Avatar

Token-based sizing keeps profile imagery aligned with the rest of the system.

<Avatar src="/profile.jpg" alt="Profile" status="online" />
<Avatar alt="Rahiel Studios" fallback="RS" />
<AvatarGroup>...</AvatarGroup>

Typical Composition

Maya Chen

Design systems lead

Shared identity block with role copy

<div className="tw:flex tw:gap-m">
  <Avatar src="/maya.jpg" alt="Maya Chen" />
  <div className="section-demo-tight-stack tw:section-demo-tight-stack">
    <h4>Maya Chen</h4>
    <p className="section-demo-copy tw:section-demo-copy">Design systems lead</p>
    <p className="section-demo-copy tw:section-demo-copy">Shared identity block</p>
  </div>
</div>

Form Primitives

Normal inputs, textareas, select, checkbox, radio, and switch controls for reusable form sections.

Text Inputs

Name

Message

Select

Project type

Use for compact choices where radio cards would be too heavy.

Compound Field API

Standard labels, helper copy, and errors compose independently for React Hook Form or another form-state library.

Work email

Label-free Input mode keeps the Field wrapper in control.

Project name

Use at least two characters.

Missing / Error States

Multi-step and contact forms should show the exact field that blocks progress.

Please enter a valid email before continuing.

Budget range

Choose one option to continue.

Choice Controls

Send project updatesUseful for consent and preference rows.Standard priorityHigh priorityEnable notificationsUse switches for immediate settings.

Date Picker

Calendar interaction is loaded only on routes that import it; submitted forms still receive a normal ISO date value.

Project kickoff

Keyboard navigation and disabled-date rules come from React DayPicker.

Attachments

Presentation stays separate from upload transport, validation, and storage.

PDF

project-brief.pdf2.4 MB · Ready

IMG

brand-reference.jpgProcessing preview

Navigation Primitives

Local content switching and delayed disclosure extracted from proven tabbed feature and navbar behavior.

Tabs

Use tabs for nearby content panels. Keep the section-specific copy, media, and CTA layout outside the primitive.

Use controlled or uncontrolled tabs for compact local navigation.

Compound API

<Tabs defaultValue="overview">
  <Tabs.List label="Product details">
    <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
    <Tabs.Trigger value="workflow">Workflow</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Panel value="overview">...</Tabs.Panel>
  <Tabs.Panel value="workflow">...</Tabs.Panel>
</Tabs>

Use for simple nav and utility menus. The primitive owns open state, delayed hover close, Escape/outside close, and menu-item keyboard focus.

Dropdown API

<DropdownMenu closeOnOutsidePointerDown>
  <DropdownMenu.Trigger>Open menu</DropdownMenu.Trigger>
  <DropdownMenu.Content variant="panel" aria-label="Example dropdown">
    <DropdownMenu.Item as="a" href="/library">Library</DropdownMenu.Item>
  </DropdownMenu.Content>
</DropdownMenu>

Breadcrumb & Separator

The compound API keeps page hierarchy semantic and makes separators decorative by default.

Swipe Carousel

Embla owns swipe, resize, snap state, and keyboard-safe controls; cards remain normal composition.

Typed API

Token styling

Swipe + keys

Responsive Sidebar

The section library is the live pilot: desktop collapse, mobile Drawer behavior, keyboard shortcut, and URL-backed filters.

Open section sidebar

Disclosure Primitives

Accordion behavior extracted from real FAQ sections: single or multiple open modes, tokenized reveal motion, and accessible button/panel wiring.

Single-open Accordion

Use this for FAQ-style lists where one answer should stay focused at a time.

Where did this primitive come from?

It was extracted from the approved FAQ section behavior, not invented as a generic component dump.

Can the open item collapse?

Multiple-open Disclosure

Use this when several cards can stay open, like the FAQ 2 split-card pattern.

Can multiple answers stay open?

Yes. This preserves the independent MAS-style FAQ 2 interaction.

Does this replace FAQ sections?

Overlay Primitives

Controlled panels for mobile menus, filters, carts, and contextual side sheets.

Drawer / Sheet

The primitive owns focus trap, Escape/backdrop close, scroll lock, restore focus, and close-on-link behavior. Content stays generic.

Controlled API

const [open, setOpen] = useState(false);

<Drawer
  open={open}
  onOpenChange={setOpen}
  side="right"
  size="sm"
  title="Menu"
>
  ...
</Drawer>

Modal Dialog

Use this for focused confirmations or compact detail flows. The primitive handles focus, Escape close, backdrop close, and tokenized motion presets.

Modal API

<Modal
  title="Modal example"
  trigger={<Button>Open modal</Button>}
>
  Compact dialog content
</Modal>

Tooltip

Use this for short contextual hints on controls or inline labels. The trigger receives aria-describedby automatically.

Tooltip API

<Tooltip text="Helpful hint" position="top">
  <Button>Hover or focus me</Button>
</Tooltip>

Feedback Primitives

Status labels, notices, and loading states with tokenized tones and reduced-motion support.

Badges & Alerts

NeutralPrimaryLiveDraftBlocked

Saved

The reusable primitive is ready for section composition.

Loading States

Fetching preview data

Toast

Spatial notifications with consistent enter/exit motion, dismiss controls, actions, and paused timeouts during stack interaction or while the tab is hidden.

Icon Lab

The icon catalog lives on its own page so this primitive reference stays focused.

Full Icon Catalog

Browse shared symbols, social marks, rating stars, and trust badges in the dedicated icon lab.

Open Icon Library

Badges

Use the Badge primitive for metadata, status labels, and compact taxonomy markers.

Common Badge Roles

Neutral metadata

CategoryNewv2.0

Featured or primary

BetaFeatured

Status and system feedback

LiveDraftDeprecated

Technology labels

ReactNext.jsTypeScript

<Badge>Category</Badge>
<Badge tone="primary">Featured</Badge>
<Badge tone="success">Live</Badge>
<Badge>React</Badge>