documentation/development/frontend/ui/index.mdx at e6f7b0ab885ef36ea53e81e6f7f25c2b7e25aa5b · deploystackio/documentation

title	UI Design System
description	Comprehensive guide to UI components, styling patterns, and design standards for the DeployStack frontend.
sidebarTitle	Overview

This document establishes the official UI design patterns and component standards for the DeployStack frontend. All new components and pages must follow these guidelines to ensure consistency and maintainability.

Design Principles

Consistency: Use established patterns and components
Accessibility: Follow WCAG guidelines and semantic HTML
Responsiveness: Design for all screen sizes
Performance: Optimize for fast loading and smooth interactions
Maintainability: Write clean, reusable component code

Color System

Primary Colors

The DeployStack color palette uses neutral black as the primary color, following the default shadcn design system for a clean, professional appearance.

/* Primary Brand Colors */
--primary: hsl(240 5.9% 10%);     /* neutral-900 - Dark gray/black */
--primary-foreground: hsl(0 0% 98%);  /* White text on primary */

WCAG Compliance

Primary (neutral-900): Contrast ratio ~16:1 on white - ✅ AA Pass, ✅ AAA Pass
Dark mode primary (white): Contrast ratio ~16:1 on dark background - ✅ AA Pass, ✅ AAA Pass

This ensures excellent accessibility with high contrast ratios in both light and dark modes.

Gray Colors

**Only use Tailwind's `neutral` gray palette.** Do not use `zinc`, `gray`, `slate`, or `stone` for gray colors. This ensures consistent gray tones across the application matching our design system (#EBEBEB = neutral-200).

/* Approved gray scale */
neutral-50   /* #fafafa - Page backgrounds */
neutral-100  /* #f5f5f5 */
neutral-200  /* #e5e5e5 - Borders, dividers */
neutral-300  /* #d4d4d4 */
neutral-400  /* #a3a3a3 - Muted text */
neutral-500  /* #737373 */
neutral-600  /* #525252 - Secondary text */
neutral-700  /* #404040 */
neutral-800  /* #262626 - Primary text */
neutral-900  /* #171717 */

Text Colors

/* Light Mode / Dark Mode */
--text-primary: theme('colors.neutral.800') / theme('colors.neutral.100');
--text-secondary: theme('colors.neutral.600') / theme('colors.neutral.400');

Background Colors

/* Light Mode / Dark Mode */
--bg-primary: white / theme('colors.neutral.900');
--bg-secondary: theme('colors.neutral.50') / theme('colors.neutral.800');

Link Utility Class

DeployStack provides a .link utility class for styled text links. This is an opt-in approach - links are unstyled by default to avoid conflicts with navigation components and buttons.

The `.link` Class

Apply the .link class to anchor elements when you want styled text links:

<a href="https://docs.deploystack.io" target="_blank" class="link">
  View documentation
</a>

Styling applied:

text-blue-600 - Blue color
underline underline-offset-4 - Underline with offset
hover:text-blue-800 - Darker blue on hover

Usage Examples

<!-- ✅ Styled text link with .link class -->
<a href="/about" class="link">Learn more about us</a>

<!-- ✅ External link with .link class -->
<span>
  Read more in our <a href="https://docs.deploystack.io" target="_blank" class="link">documentation</a>.
</span>

<!-- ✅ Unstyled link (default behavior) -->
<a href="/dashboard">Dashboard</a>

<!-- ✅ Button-styled link (no .link class needed) -->
<a href="/signup" class="rounded-md bg-primary px-4 py-2 text-white">Sign Up</a>

When to Use `.link`

Use Case	Use `.link`?
Inline text links in paragraphs	✅ Yes
Documentation/help links	✅ Yes
External links	✅ Yes
Navigation menu items	❌ No
Button-styled links	❌ No
Sidebar/header links	❌ No

Color Usage Guidelines

Primary Actions: Use --primary (neutral-900) for primary buttons and key interactive elements
Hover States: Use slightly lighter/darker variants for hover feedback
Text Links: Add .link class for blue styled links in content areas
Button Links: Include styling classes (bg-*, rounded-*) to maintain button appearance
Focus States: Ensure all interactive elements have visible focus indicators

Layout Design Patterns

Content Wrapper Pattern

DeployStack follows a mandatory content wrapper pattern for all tabbed content and detail pages. This pattern ensures visual consistency and proper content hierarchy throughout the application.

Design Requirements

The content wrapper pattern is required for:

Team management pages
MCP server installation pages
Settings and configuration pages
Any page using tabbed content with DsTabs
Detail views that need elevated content presentation

Implementation

Use the ContentWrapper component for all qualifying pages:

<ContentWrapper>
  <YourTabContent />
</ContentWrapper>

The wrapper provides:

Gray background container (bg-muted/50)
Responsive max-width constraints
White card elevation with proper spacing
Consistent vertical rhythm

For complete implementation details, see the component source code at services/frontend/src/components/ContentWrapper.vue.

Visual Hierarchy

This pattern creates a three-tier visual hierarchy:

Page background - Default dashboard background
Content container - Gray muted background wrapper
Content card - White elevated card with content

This hierarchy is a design system requirement and must be followed consistently across all applicable pages.

Data Tables

For data table implementation, see the dedicated Table Design System guide.

For pagination implementation, see the Pagination Implementation Guide.

Badge Design Patterns

Badges are used for status indicators, categories, and metadata.

Status Badges

<Badge variant="default">Active</Badge>
<Badge variant="secondary">Inactive</Badge>
<Badge variant="destructive">Error</Badge>
<Badge variant="outline">Pending</Badge>

Category/Tag Badges

<Badge variant="secondary" class="font-mono text-xs">
  {{ category.icon }}
</Badge>

Numeric Badges

<Badge variant="outline">
  {{ item.sort_order }}
</Badge>

Dialog Patterns

Confirmation Dialogs

For simple yes/no confirmation dialogs (delete confirmations, enable/disable toggles, destructive actions), always use AlertDialog. This component interrupts the user with important content and expects a response.

<AlertDialog :open="isOpen" @update:open="(value) => isOpen = value">
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction @click="handleConfirm">
        Continue
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

When to Use AlertDialog

Delete confirmations
Enable/disable toggles
Destructive actions that cannot be undone
Any action requiring explicit user confirmation

Extracting Reusable Dialogs

For dialogs used in multiple places, extract them as reusable components in components/mcp-server/ or similar directories. Examples:

McpServerDeleteDialog.vue - Delete confirmation for MCP servers
McpServerStatusDialog.vue - Enable/disable confirmation

Form Design Patterns

Modal Forms

Use AlertDialog for forms in modals:

<AlertDialog :open="isOpen" @update:open="(value) => isOpen = value">
  <AlertDialogContent class="sm:max-w-[425px]">
    <AlertDialogHeader>
      <AlertDialogTitle>{{ modalTitle }}</AlertDialogTitle>
      <AlertDialogDescription>
        {{ modalDescription }}
      </AlertDialogDescription>
    </AlertDialogHeader>

    <form @submit.prevent="handleSubmit" class="space-y-4">
      <!-- Form fields -->
      <div class="space-y-2">
        <Label for="field-name">{{ t('form.field.label') }}</Label>
        <Input
          id="field-name"
          v-model="formData.name"
          :placeholder="t('form.field.placeholder')"
          :class="{ 'border-destructive': errors.name }"
          required
        />
        <div v-if="errors.name" class="text-sm text-destructive">
          {{ errors.name }}
        </div>
      </div>

      <AlertDialogFooter>
        <Button type="button" variant="outline" @click="handleCancel">
          {{ t('form.cancel') }}
        </Button>
        <Button type="submit" :disabled="!isFormValid || isSubmitting">
          {{ isSubmitting ? t('form.saving') : t('form.save') }}
        </Button>
      </AlertDialogFooter>
    </form>
  </AlertDialogContent>
</AlertDialog>

Form Field Pattern

<div class="space-y-2">
  <Label for="field-id">{{ t('form.field.label') }}</Label>
  <Input
    id="field-id"
    v-model="formData.field"
    :placeholder="t('form.field.placeholder')"
    :class="{ 'border-destructive': errors.field }"
    @input="handleFieldChange"
  />
  <div v-if="errors.field" class="text-sm text-destructive">
    {{ errors.field }}
  </div>
</div>

Loading State Patterns

Choose the appropriate loading indicator based on what's being loaded:

Content Loading → Use Skeleton

When loading page content, data lists, or complex UI sections, use Skeleton components that match the shape of the content being loaded. This provides a better user experience by showing users what to expect.

<script setup lang="ts">
import { Skeleton } from '@/components/ui/skeleton'
</script>

<template>
  <!-- Loading state mimics actual content structure -->
  <div v-if="isLoading" class="space-y-4">
    <Skeleton class="h-4 w-64" />           <!-- Title placeholder -->
    <Skeleton class="h-4 w-48" />           <!-- Subtitle placeholder -->
    <div class="flex gap-2">
      <Skeleton class="h-10 w-10 rounded" /> <!-- Icon placeholder -->
      <Skeleton class="h-10 w-full" />       <!-- Content placeholder -->
    </div>
  </div>

  <!-- Actual content -->
  <div v-else>
    <!-- Real content here -->
  </div>
</template>

Use Skeleton for:

Page content loading
Data tables and lists
Cards and detail views
Form sections loading from API
Any content where you can predict the layout

Button Actions → Use Spinner

For button clicks and quick actions, use the built-in button loading state with a spinner. This indicates the action is processing without disrupting the page layout.

<Button :loading="isSubmitting" loading-text="Saving...">
  Save Changes
</Button>

Use Spinner for:

Form submissions
Button click actions
Quick API calls (enable/disable toggles)
Actions that don't change page structure

Why Skeleton Over Spinner for Content

Aspect	Skeleton	Spinner
User expectation	Shows content shape	Shows "something is happening"
Layout shift	Minimal (matches content)	Can cause layout shift
Perceived speed	Feels faster	Can feel slower
Use case	Content loading	Action processing

Empty State Patterns

MANDATORY: Always use the shadcn-vue Empty component for no-data states. Never create custom empty state markup with manual styling.

Basic Empty State

<script setup lang="ts">
import { Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription } from '@/components/ui/empty'
import { Package } from 'lucide-vue-next'
</script>

<template>
  <Empty v-if="!hasData">
    <EmptyHeader>
      <EmptyMedia variant="icon">
        <Package />
      </EmptyMedia>
      <EmptyTitle>No data found</EmptyTitle>
      <EmptyDescription>
        There is currently no data to display.
      </EmptyDescription>
    </EmptyHeader>
  </Empty>
</template>

Empty State with Actions

<script setup lang="ts">
import { Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent } from '@/components/ui/empty'
import { Button } from '@/components/ui/button'
import { Package, Plus } from 'lucide-vue-next'
</script>

<template>
  <Empty v-if="!hasData">
    <EmptyHeader>
      <EmptyMedia variant="icon">
        <Package />
      </EmptyMedia>
      <EmptyTitle>No items found</EmptyTitle>
      <EmptyDescription>
        Get started by creating your first item.
      </EmptyDescription>
    </EmptyHeader>
    <EmptyContent>
      <Button @click="handleCreate">
        <Plus class="h-4 w-4 mr-2" />
        Create Item
      </Button>
    </EmptyContent>
  </Empty>
</template>

Use Empty component for:

No search results
Empty data tables
No tools/resources discovered
Missing configuration items
Any state where data is expected but not present

Button Patterns

Loading States

Buttons now include built-in loading state functionality. For comprehensive loading button documentation, see the Button Loading States Guide.

<!-- Button with loading state -->
<Button 
  :loading="isSubmitting"
  loading-text="Saving..."
  @click="handleSave"
>
  Save Changes
</Button>

Primary Actions

<Button @click="handlePrimaryAction">
  <Plus class="h-4 w-4 mr-2" />
  {{ t('actions.add') }}
</Button>

Secondary Actions

<Button variant="outline" @click="handleSecondaryAction">
  {{ t('actions.cancel') }}
</Button>

Destructive Actions

<Button 
  variant="destructive" 
  @click="handleDelete"
  :loading="isDeleting"
  loading-text="Deleting..."
  class="bg-destructive text-destructive-foreground hover:bg-destructive/90"
>
  <Trash2 v-if="!isDeleting" class="h-4 w-4 mr-2" />
  {{ t('actions.delete') }}
</Button>

Icon-Only Buttons

<Button 
  variant="ghost" 
  size="icon"
  :loading="isRefreshing"
>
  <span class="sr-only">{{ t('actions.menu') }}</span>
  <MoreHorizontal v-if="!isRefreshing" class="h-4 w-4" />
</Button>

Layout Patterns

Page Header

<div class="flex items-center justify-between">
  <div>
    <h1 class="text-2xl font-bold">{{ pageTitle }}</h1>
    <p class="text-muted-foreground">{{ pageDescription }}</p>
  </div>
  <Button @click="handlePrimaryAction" class="flex items-center gap-2">
    <Plus class="h-4 w-4" />
    {{ t('actions.add') }}
  </Button>
</div>

Content Sections

<div class="space-y-6">
  <!-- Header -->
  <div class="flex items-center justify-between">
    <!-- Header content -->
  </div>

  <!-- Success/Error Messages -->
  <Alert v-if="successMessage" class="border-green-200 bg-green-50 text-green-800">
    <CheckCircle class="h-4 w-4" />
    <AlertDescription>{{ successMessage }}</AlertDescription>
  </Alert>

  <!-- Main Content -->
  <div class="space-y-4">
    <!-- Content -->
  </div>
</div>

Icon Usage

Standard Icon Sizes

Small icons: h-4 w-4 (16px) - for buttons, table actions
Medium icons: h-5 w-5 (20px) - for form fields, navigation
Large icons: h-6 w-6 (24px) - for page headers, prominent actions

Icon with Text

<Button>
  <Settings class="h-4 w-4 mr-2" />
  {{ t('actions.settings') }}
</Button>

Status Icons

<CheckCircle class="h-4 w-4 text-green-600" />
<AlertCircle class="h-4 w-4 text-yellow-600" />
<XCircle class="h-4 w-4 text-red-600" />

Responsive Design

Mobile-First Approach

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <!-- Responsive grid -->
</div>

Hide/Show on Different Screens

<div class="hidden md:block">Desktop only</div>
<div class="block md:hidden">Mobile only</div>

Accessibility Guidelines

Screen Reader Support

<Button>
  <span class="sr-only">{{ t('actions.openMenu') }}</span>
  <MoreHorizontal class="h-4 w-4" />
</Button>

Proper Labels

<Label for="input-id">{{ t('form.label') }}</Label>
<Input id="input-id" v-model="value" />

Focus Management

<Button 
  @click="handleAction"
  :disabled="isLoading"
  class="focus:ring-2 focus:ring-ring focus:ring-offset-2"
>
  {{ t('actions.submit') }}
</Button>

Migration Guide

Updating Existing Tables

If you have an existing table using raw HTML elements, follow these steps:

Replace HTML elements with shadcn-vue components:
- <table> → <Table>
- <thead> → <TableHeader>
- <tbody> → <TableBody>
- <tr> → <TableRow>
- <th> → <TableHead>
- <td> → <TableCell>

Update imports:

import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table'

Add proper empty state handling
Update action menus to use AlertDialog for destructive actions
Ensure proper badge usage for status indicators

For detailed migration strategies and architectural considerations, see the Frontend Architecture - Migration Guidelines.

Uh oh!

FilesExpand file tree

index.mdx

Latest commit

History