UI Primitives

Spacedrive's UI is built on a set of reusable primitives from @sd/ui. These components provide consistent styling and behavior across the application.

Design Principles

Composition Over Configuration

Primitives are simple, composable building blocks rather than complex configured components.

tsx

// Complex configuration
<DataTable
  columns={...}
  data={...}
  filters={...}
  pagination={...}
/>

// Composable primitives
<div className="overflow-hidden rounded-lg border border-app-line">
  <table className="w-full">
    <thead className="bg-app-box">
      <tr>
        <th className="px-4 py-3 text-xs text-ink-dull">Name</th>
      </tr>
    </thead>
    <tbody className="divide-y divide-app-line">
      {data.map(item => (
        <tr className="bg-app-input/30">
          <td className="px-4 py-3 text-ink">{item.name}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

Semantic Color Usage

All primitives use semantic color tokens, never raw Tailwind colors.

tsx

// Raw colors
<div className="bg-gray-800 text-gray-200">

// Semantic colors
<div className="bg-app-box text-ink">

Consistent Patterns

Common patterns are standardized across primitives:

Card Pattern:

tsx

<div className="relative overflow-hidden rounded-2xl bg-sidebar/90 backdrop-blur-xl shadow-2xl">
	<div className="absolute top-0 h-px w-full bg-gradient-to-r from-transparent via-[#2D2D37]/60 to-transparent" />
	<div className="absolute bottom-0 h-px w-full bg-gradient-to-r from-transparent via-[#2D2D37]/60 to-transparent" />

	<div className="noise noise-faded noise-sm p-6"></div>
</div>

List Item Pattern:

tsx

<div className="rounded-lg border border-app-line bg-app-input/30 p-4 hover:bg-app-input/40">
</div>

Table Pattern:

tsx

<div className="overflow-hidden rounded-lg border border-app-line">
	<table className="w-full">
		<thead className="bg-app-box">
			<tr>
				<th className="px-4 py-3 text-xs font-medium text-gray-400">Column</th>
			</tr>
		</thead>
		<tbody className="divide-y divide-app-line">
			<tr className="bg-app-input/30 hover:bg-app-input/50">
				<td className="px-4 py-3 text-ink">Data</td>
			</tr>
		</tbody>
	</table>
</div>

Core Primitives

Button

Versatile button component with multiple variants and sizes.

tsx

import { Button } from '@sd/ui';

<Button variant="accent" size="md">
  Primary Action
</Button>

<Button variant="gray" size="sm">
  Secondary Action
</Button>

<Button variant="default" size="lg">
  Tertiary Action
</Button>

Variants:

default - Transparent with border, hover/active states
gray - App button background with hover/focus states
accent - Accent blue background with white text
subtle - Transparent border, subtle hover
outline - Sidebar line border style
dotted - Dashed border for add/create actions
colored - Custom colored backgrounds (pass bg color class)
bare - No styling whatsoever

Sizes:

xs - Extra small (px-1.5 py-0.5, text-xs)
sm - Small (px-2 py-0.5, text-sm) - default
md - Medium (px-2.5 py-1.5, text-sm)
lg - Large (px-3 py-1.5, text-md)
icon - Square icon button (!p-1)

Best Practice: Wrap icons and text in flex containers to prevent stacking:

tsx

<Button className="flex items-center gap-2">
	<Icon size={16} weight="fill" />
	<span>Label</span>
</Button>

Input

Form input with semantic styling and size variants.

tsx

import { Input, Label } from "@sd/ui";

<div>
	<Label>Username</Label>
	<Input placeholder="Enter username" size="lg" error={hasError} />
</div>;

Variants:

default - Standard input with border and background
transparent - Transparent background, no border on focus

Sizes:

xs - 25px height
sm - 30px height (default)
md - 36px height
lg - 42px height
xl - 48px height

Props:

error - Shows error state (red border/ring)
icon - Icon component or React node
iconPosition - 'left' | 'right' (default: 'left')
right - React node to display on the right side
inputElementClassName - Additional classes for the input element itself

Additional Components:

SearchInput - Input with MagnifyingGlass icon pre-configured
PasswordInput - Input with eye icon toggle for show/hide password
TextArea - Multi-line text input with same styling system
Label - Semantic label component with slug prop for htmlFor

Form Components

React Hook Form integration with automatic validation display.

tsx

import { Form, InputField, z } from "@sd/ui/src/forms";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";

const schema = z.object({
	username: z.string().min(3),
	email: z.string().email(),
});

function MyForm() {
	const form = useForm({
		resolver: zodResolver(schema),
	});

	return (
		<Form form={form} onSubmit={form.handleSubmit(onSubmit)}>
			<InputField
				name="username"
				label="Username"
				placeholder="Enter username"
			/>
			<InputField name="email" label="Email" type="email" />
			<Button type="submit">Submit</Button>
		</Form>
	);
}

Switch

Toggle switch for boolean settings.

tsx

import { Switch } from "@sd/ui";

const [enabled, setEnabled] = useState(false);

<div className="flex items-center justify-between">
	<div>
		<div className="text-sm text-ink">Enable Feature</div>
		<div className="text-xs text-ink-dull">Description</div>
	</div>
	<Switch checked={enabled} onCheckedChange={setEnabled} />
</div>;

ShinyToggle

Animated toggle component for switching between multiple options with a smooth glowing indicator.

tsx

import { ShinyToggle } from "@sd/ui";

const [view, setView] = useState<"grid" | "list">("grid");

<ShinyToggle
	value={view}
	onChange={setView}
	options={[
		{ value: "grid", label: "Grid", count: 42 },
		{ value: "list", label: "List", count: 42 },
	]}
/>;

Features:

Smooth animated indicator using Framer Motion
Gradient background with glow effect
Optional count badges
Type-safe with generics
Fully accessible

Props:

value - Current selected value (generic type T)
onChange - Callback when selection changes
options - Array of { value: T, label: ReactNode, count?: number }
className - Additional classes for the container

DropdownMenu

Context menu and dropdown with Radix UI.

tsx

import { DropdownMenu } from "@sd/ui";

<DropdownMenu.Root trigger={<button>Open Menu</button>}>
	<DropdownMenu.Item
		label="Action"
		icon={IconComponent}
		onClick={handleClick}
	/>
	<DropdownMenu.Separator />
	<DropdownMenu.Item label="Delete" icon={TrashIcon} variant="danger" />
</DropdownMenu.Root>;

Glassmorphism Effect

Spacedrive's signature glassmorphism effect combines backdrop blur, transparency, and gradient borders.

tsx

<div className="relative overflow-hidden rounded-2xl bg-sidebar/90 backdrop-blur-xl shadow-2xl">
	<div className="absolute top-0 h-px w-full bg-gradient-to-r from-transparent via-[#2D2D37]/60 to-transparent" />
	<div className="absolute bottom-0 h-px w-full bg-gradient-to-r from-transparent via-[#2D2D37]/60 to-transparent" />
	<div className="noise noise-faded noise-sm p-6">Content</div>
</div>

Noise Variants:

noise - Base noise texture
noise-faded - Faded intensity
noise-sm - Small grain size

Progress Bars

Consistent progress bar pattern for resource usage.

tsx

<div>
	<div className="mb-2 flex items-center justify-between text-xs">
		<span className="text-ink-dull">Storage</span>
		<span className="text-ink">45/100 GB</span>
	</div>
	<div className="h-2 overflow-hidden rounded-full bg-app-box">
		<div className="h-full bg-accent" style={{ width: "45%" }} />
	</div>
</div>

Color by type:

Storage: bg-accent (blue)
AI/Compute: bg-purple-500
Bandwidth: bg-green-500
Progress: bg-accent
Success: bg-green-400

Status Badges

Standard status badge pattern.

tsx

const STATUS_CONFIG = {
	running: { color: "text-green-400", bg: "bg-green-500/20" },
	stopped: { color: "text-gray-400", bg: "bg-gray-500/20" },
	error: { color: "text-red-400", bg: "bg-red-500/20" },
};

<div
	className={`flex items-center gap-1.5 rounded-full px-2.5 py-1 ${STATUS_CONFIG.running.bg}`}
>
	<div className="h-1.5 w-1.5 rounded-full bg-green-400" />
	<span className={`text-xs font-medium ${STATUS_CONFIG.running.color}`}>
		Running
	</span>
</div>;

Empty States

Pattern for when lists/grids are empty.

tsx

<div className="rounded-lg border border-dashed border-app-line bg-app-box/50 p-12 text-center">
	<Icon size={48} weight="fill" className="mx-auto mb-3 text-ink-dull" />
	<h3 className="mb-1 text-lg font-semibold text-white">No items yet</h3>
	<p className="mb-4 text-sm text-ink-dull">
		Description of what would appear here
	</p>
	<Button variant="accent" size="lg">
		Create First Item
	</Button>
</div>

Gradients

Background Gradients

tsx

<div className="bg-gradient-to-br from-accent to-blue-600">
  Icon background
</div>

<div className="bg-gradient-to-b from-white to-gray-400 bg-clip-text text-transparent">
  Gradient text
</div>

Border Gradients

tsx

<div className="h-px w-full bg-gradient-to-r from-transparent via-[#2D2D37]/60 to-transparent" />

Typography Scale

Consistent text sizing across the app.

tsx

<h1 className="text-3xl font-bold text-ink">
  Page Title
</h1>

<h2 className="text-xl font-semibold text-white">
  Section Title
</h2>

<p className="text-sm text-ink-dull">
  Description text
</p>

<span className="text-xs text-ink-faint">
  Helper text
</span>

Scale:

text-xs (12px) - Helper text, labels
text-sm (14px) - Body text, descriptions
text-base (16px) - Default body
text-lg (18px) - Subheadings
text-xl (20px) - Section titles
text-2xl (24px) - Card titles
text-3xl (30px) - Page titles

Icons

Use Phosphor Icons with consistent sizing and weights.

tsx

import { Icon } from '@phosphor-icons/react';

<Icon size={16} weight="fill" />  // Buttons, small UI
<Icon size={20} weight="fill" />  // Medium UI elements
<Icon size={24} weight="fill" />  // Large icons
<Icon size={32} weight="fill" />  // Headers
<Icon size={48} weight="fill" />  // Empty states

Weight Guidelines:

regular - Default, inactive states
fill - Active states, buttons, emphasis
bold - Strong emphasis

Spacing Scale

Consistent spacing using Tailwind's scale.

Common patterns:

Card padding: p-6
Button padding: px-3 py-1.5 (md), px-2.5 py-1.5 (sm)
Section spacing: space-y-4 or space-y-6
Grid gaps: gap-4 or gap-6
Icon-text gap: gap-2 or gap-3

Accessibility

Color Contrast

All semantic colors meet WCAG AA standards:

text-ink on bg-app - AAA
text-ink-dull on bg-app-box - AA
text-ink-faint on bg-app-input - AA (minimum)

Focus States

Interactive elements include focus rings:

tsx

<button className="
  focus:outline-none
  focus:ring-2
  focus:ring-accent
  focus:ring-offset-2
  focus:ring-offset-app-box
">

All interactive primitives support keyboard navigation out of the box via Radix UI.