UI Design System - DeployStack - Enterprise Control Plane for MCP

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

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

<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

<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.

Basics

UI System

​Design Principles

​Color System

​Primary Colors

​WCAG Compliance

​Gray Colors

​Text Colors

​Background Colors

​Link Utility Class

​The .link Class

​Usage Examples

​When to Use .link

​Color Usage Guidelines

​Layout Design Patterns

​Content Wrapper Pattern

​Design Requirements

​Implementation

​Visual Hierarchy

​Data Tables

​Badge Design Patterns

​Status Badges

​Category/Tag Badges

​Numeric Badges

​Dialog Patterns

​Confirmation Dialogs

​When to Use AlertDialog

​Extracting Reusable Dialogs

​Form Design Patterns

​Modal Forms

​Form Field Pattern

​Loading State Patterns

​Content Loading → Use Skeleton

​Button Actions → Use Spinner

​Why Skeleton Over Spinner for Content

​Empty State Patterns

​Basic Empty State

​Empty State with Actions

​Button Patterns

​Loading States

​Primary Actions

​Secondary Actions

​Destructive Actions

​Icon-Only Buttons

​Layout Patterns

​Page Header

​Content Sections

​Icon Usage

​Standard Icon Sizes

​Icon with Text

​Status Icons

​Responsive Design

​Mobile-First Approach

​Hide/Show on Different Screens

​Accessibility Guidelines

​Screen Reader Support

​Proper Labels

​Focus Management

​Migration Guide

​Updating Existing Tables

Design Principles

Color System

Primary Colors

WCAG Compliance

Gray Colors

Text Colors

Background Colors

Link Utility Class

The `.link` Class

Usage Examples

When to Use `.link`

Color Usage Guidelines

Layout Design Patterns

Content Wrapper Pattern

Design Requirements

Implementation

Visual Hierarchy

Data Tables

Badge Design Patterns

Status Badges

Category/Tag Badges

Numeric Badges

Dialog Patterns

Confirmation Dialogs

When to Use AlertDialog

Extracting Reusable Dialogs

Form Design Patterns

Modal Forms

Form Field Pattern

Loading State Patterns

Content Loading → Use Skeleton

Button Actions → Use Spinner

Why Skeleton Over Spinner for Content

Empty State Patterns

Basic Empty State

Empty State with Actions

Button Patterns

Loading States

Primary Actions

Secondary Actions

Destructive Actions

Icon-Only Buttons

Layout Patterns

Page Header

Content Sections

Icon Usage

Standard Icon Sizes

Icon with Text

Status Icons

Responsive Design

Mobile-First Approach

Hide/Show on Different Screens

Accessibility Guidelines

Screen Reader Support

Proper Labels

Focus Management

Migration Guide

Updating Existing Tables