frappe-ui-patterns

name	frappe-ui-patterns
description	UI/UX patterns and guidelines derived from official Frappe apps (CRM, Helpdesk, HRMS). Use when designing interfaces for custom Frappe applications to ensure consistency with the ecosystem.

Frappe UI Patterns

UI/UX patterns and design guidelines extracted from official Frappe applications.

When to use

• Designing UI for a new Frappe app
• Building CRUD interfaces with Frappe UI
• Implementing list views, detail panels, or forms
• Ensuring consistent UX with CRM, Helpdesk, HRMS
• Choosing component patterns and layouts

Inputs required

• App type (CRM-like, Helpdesk-like, data management)
• Key entities and their relationships
• Primary user workflows

Reference apps

Study these official apps for patterns:

App	Repo	Key Patterns
Frappe CRM	github.com/frappe/crm	Lead/Deal pipelines, Kanban, activity feeds
Frappe Helpdesk	github.com/frappe/helpdesk	Ticket queues, SLA indicators, agent views
Frappe HRMS	github.com/frappe/hrms	Employee self-service, approvals, dashboards
Frappe Insights	github.com/frappe/insights	Query builders, visualizations, dashboards
Frappe Builder	github.com/frappe/builder	Drag-drop interfaces, property panels

Procedure

0) App shell structure

All Frappe apps follow a consistent shell:

┌─────────────────────────────────────────────────────────────┐
│ Header (App title, search, user menu)                       │
├──────────────┬──────────────────────────────────────────────┤
│              │                                              │
│   Sidebar    │              Main Content                    │
│              │                                              │
│  - Nav items │  ┌─────────────────┬──────────────────────┐  │
│  - Filters   │  │   List View     │   Detail Panel       │  │
│  - Actions   │  │                 │                      │  │
│              │  │                 │                      │  │
│              │  └─────────────────┴──────────────────────┘  │
│              │                                              │
└──────────────┴──────────────────────────────────────────────┘

Implementation:

<template>
  <div class="flex h-screen">
    <!-- Sidebar -->
    <Sidebar />
    
    <!-- Main content with optional split view -->
    <div class="flex-1 flex">
      <ListView 
        :class="selectedDoc ? 'w-1/2' : 'w-full'"
        @select="selectDoc"
      />
      <DetailPanel 
        v-if="selectedDoc" 
        :doc="selectedDoc"
        class="w-1/2 border-l"
      />
    </div>
  </div>
</template>

1) Sidebar patterns

Standard structure:

<template>
  <aside class="w-56 border-r bg-gray-50 flex flex-col">
    <!-- App logo/title -->
    <div class="p-4 border-b">
      <h1 class="font-semibold">My App</h1>
    </div>
    
    <!-- Primary navigation -->
    <nav class="flex-1 p-2">
      <SidebarLink 
        v-for="item in navItems" 
        :key="item.name"
        :label="item.label"
        :icon="item.icon"
        :to="item.route"
        :count="item.count"
      />
    </nav>
    
    <!-- Quick filters (context-dependent) -->
    <div v-if="filters.length" class="p-2 border-t">
      <p class="text-xs text-gray-500 px-2 mb-1">Filters</p>
      <SidebarLink 
        v-for="filter in filters"
        :key="filter.name"
        :label="filter.label"
        :count="filter.count"
        @click="applyFilter(filter)"
      />
    </div>
    
    <!-- User/settings at bottom -->
    <div class="p-2 border-t">
      <UserMenu />
    </div>
  </aside>
</template>

CRM example nav items:

• Leads (with count badge)
• Deals (with count badge)
• Contacts
• Organizations
• Activities

---

• Settings

2) List view patterns

Standard list with filters:

<template>
  <div class="flex-1 flex flex-col">
    <!-- Toolbar -->
    <div class="flex items-center justify-between p-4 border-b">
      <div class="flex items-center gap-2">
        <Input 
          type="search" 
          placeholder="Search..." 
          v-model="searchQuery"
          :debounce="300"
        />
        <FilterDropdown :filters="availableFilters" v-model="activeFilters" />
      </div>
      <div class="flex items-center gap-2">
        <ViewToggle v-model="viewMode" :options="['list', 'kanban', 'grid']" />
        <Button variant="solid" @click="createNew">
          <template #prefix><FeatherIcon name="plus" /></template>
          New
        </Button>
      </div>
    </div>
    
    <!-- View modes -->
    <ListView v-if="viewMode === 'list'" :data="items" @row-click="select" />
    <KanbanView v-else-if="viewMode === 'kanban'" :data="items" :columns="stages" />
    <GridView v-else :data="items" @card-click="select" />
  </div>
</template>

List row structure:

<template>
  <div class="flex items-center p-3 hover:bg-gray-50 cursor-pointer border-b">
    <!-- Selection checkbox (for bulk actions) -->
    <Checkbox v-if="selectable" v-model="selected" class="mr-3" />
    
    <!-- Avatar/icon -->
    <Avatar :label="row.name" :image="row.image" class="mr-3" />
    
    <!-- Primary content -->
    <div class="flex-1 min-w-0">
      <p class="font-medium truncate">{{ row.title }}</p>
      <p class="text-sm text-gray-500 truncate">{{ row.subtitle }}</p>
    </div>
    
    <!-- Status badge -->
    <Badge :variant="statusVariant">{{ row.status }}</Badge>
    
    <!-- Metadata -->
    <span class="text-sm text-gray-500 ml-4">{{ timeAgo(row.modified) }}</span>
    
    <!-- Actions dropdown -->
    <Dropdown :options="rowActions" class="ml-2">
      <Button variant="ghost" icon="more-horizontal" />
    </Dropdown>
  </div>
</template>

3) Kanban view patterns

Used in: CRM (Deals), Helpdesk (Tickets by status)

<template>
  <div class="flex overflow-x-auto p-4 gap-4">
    <div 
      v-for="column in columns" 
      :key="column.name"
      class="flex-shrink-0 w-72 bg-gray-100 rounded-lg"
    >
      <!-- Column header -->
      <div class="p-3 font-medium flex items-center justify-between">
        <span>{{ column.label }}</span>
        <Badge>{{ column.items.length }}</Badge>
      </div>
      
      <!-- Cards -->
      <div class="p-2 space-y-2 min-h-[200px]">
        <KanbanCard 
          v-for="item in column.items"
          :key="item.name"
          :data="item"
          @click="select(item)"
          draggable
          @dragend="handleDrop"
        />
      </div>
      
      <!-- Add new in column -->
      <Button variant="ghost" class="w-full" @click="addTo(column)">
        + Add {{ column.singular }}
      </Button>
    </div>
  </div>
</template>

Kanban card structure:

<template>
  <div class="bg-white rounded-lg p-3 shadow-sm border cursor-pointer hover:shadow">
    <p class="font-medium mb-1">{{ data.title }}</p>
    <p class="text-sm text-gray-500 mb-2">{{ data.subtitle }}</p>
    <div class="flex items-center justify-between">
      <Avatar :label="data.assigned_to" size="sm" />
      <span class="text-xs text-gray-400">{{ data.due_date }}</span>
    </div>
  </div>
</template>

4) Detail panel / side panel

Split view pattern (CRM/Helpdesk style):

<template>
  <aside class="w-[480px] border-l bg-white flex flex-col">
    <!-- Header with close -->
    <div class="flex items-center justify-between p-4 border-b">
      <h2 class="font-semibold">{{ doc.name }}</h2>
      <Button variant="ghost" icon="x" @click="$emit('close')" />
    </div>
    
    <!-- Tabs -->
    <Tabs v-model="activeTab">
      <Tab name="details" label="Details" />
      <Tab name="activity" label="Activity" />
      <Tab name="notes" label="Notes" />
    </Tabs>
    
    <!-- Tab content -->
    <div class="flex-1 overflow-auto p-4">
      <DetailsTab v-if="activeTab === 'details'" :doc="doc" />
      <ActivityFeed v-else-if="activeTab === 'activity'" :doctype="doctype" :name="doc.name" />
      <NotesTab v-else :doctype="doctype" :name="doc.name" />
    </div>
    
    <!-- Footer actions -->
    <div class="p-4 border-t flex justify-end gap-2">
      <Button @click="edit">Edit</Button>
      <Button variant="solid" @click="primaryAction">{{ primaryActionLabel }}</Button>
    </div>
  </aside>
</template>

5) Form patterns

Standard form layout:

<template>
  <div class="max-w-2xl mx-auto p-6">
    <!-- Form header -->
    <div class="mb-6">
      <h1 class="text-xl font-semibold">{{ isNew ? 'New' : 'Edit' }} {{ doctype }}</h1>
    </div>
    
    <!-- Sections -->
    <FormSection title="Basic Information">
      <div class="grid grid-cols-2 gap-4">
        <FormControl label="Name" v-model="doc.name" :required="true" />
        <FormControl label="Status" type="select" v-model="doc.status" :options="statusOptions" />
      </div>
      <FormControl label="Description" type="textarea" v-model="doc.description" class="mt-4" />
    </FormSection>
    
    <FormSection title="Details" collapsible>
      <!-- More fields -->
    </FormSection>
    
    <!-- Actions -->
    <div class="flex justify-end gap-2 mt-6 pt-4 border-t">
      <Button @click="cancel">Cancel</Button>
      <Button variant="solid" @click="save" :loading="saving">Save</Button>
    </div>
  </div>
</template>

FormSection component:

<template>
  <div class="mb-6">
    <div 
      class="flex items-center justify-between mb-3 cursor-pointer"
      @click="collapsible && (collapsed = !collapsed)"
    >
      <h3 class="font-medium text-gray-700">{{ title }}</h3>
      <FeatherIcon v-if="collapsible" :name="collapsed ? 'chevron-down' : 'chevron-up'" />
    </div>
    <div v-show="!collapsed">
      <slot />
    </div>
  </div>
</template>

6) Activity feed pattern

Used across all apps for tracking changes:

<template>
  <div class="space-y-4">
    <!-- Add comment -->
    <div class="flex gap-3">
      <Avatar :label="$user.name" />
      <div class="flex-1">
        <Textarea v-model="newComment" placeholder="Add a comment..." rows="2" />
        <Button class="mt-2" @click="addComment" :disabled="!newComment">Comment</Button>
      </div>
    </div>
    
    <!-- Activity items -->
    <div v-for="item in activities" :key="item.name" class="flex gap-3">
      <Avatar :label="item.owner" size="sm" />
      <div class="flex-1">
        <div class="flex items-baseline gap-2">
          <span class="font-medium text-sm">{{ item.owner }}</span>
          <span class="text-xs text-gray-400">{{ timeAgo(item.creation) }}</span>
        </div>
        <!-- Different activity types -->
        <CommentContent v-if="item.type === 'comment'" :content="item.content" />
        <StatusChange v-else-if="item.type === 'status'" :from="item.from" :to="item.to" />
        <FieldChange v-else-if="item.type === 'change'" :field="item.field" :value="item.value" />
      </div>
    </div>
  </div>
</template>

7) Empty states

Always provide helpful empty states:

<template>
  <div class="flex flex-col items-center justify-center h-64 text-center">
    <FeatherIcon name="inbox" class="w-12 h-12 text-gray-300 mb-4" />
    <h3 class="font-medium text-gray-700 mb-1">{{ title }}</h3>
    <p class="text-sm text-gray-500 mb-4">{{ description }}</p>
    <Button v-if="action" variant="solid" @click="action.handler">
      {{ action.label }}
    </Button>
  </div>
</template>

<!-- Usage -->
<EmptyState 
  title="No leads yet"
  description="Create your first lead to get started"
  :action="{ label: 'Create Lead', handler: createLead }"
/>

8) Loading states

Skeleton loaders for perceived performance:

<!-- List skeleton -->
<template>
  <div v-if="loading" class="space-y-2 p-4">
    <div v-for="i in 5" :key="i" class="flex items-center gap-3 p-3">
      <Skeleton class="w-10 h-10 rounded-full" />
      <div class="flex-1">
        <Skeleton class="h-4 w-1/3 mb-2" />
        <Skeleton class="h-3 w-1/2" />
      </div>
    </div>
  </div>
  <ListView v-else :data="data" />
</template>

9) Color and status conventions

Status Type	Color	Usage
Success/Active	Green (bg-green-100 text-green-700)	Completed, Active, Resolved
Warning/Pending	Yellow (bg-yellow-100 text-yellow-700)	Pending, In Progress, Due Soon
Error/Blocked	Red (bg-red-100 text-red-700)	Failed, Blocked, Overdue
Info/Default	Blue (bg-blue-100 text-blue-700)	New, Open, Info
Neutral	Gray (bg-gray-100 text-gray-700)	Draft, Cancelled, Closed

Badge component usage:

<Badge variant="success">Active</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="error">Overdue</Badge>
<Badge variant="info">New</Badge>
<Badge variant="subtle">Draft</Badge>

10) Responsive patterns

Mobile-first considerations:

<template>
  <!-- Hide sidebar on mobile, show as drawer -->
  <Sidebar v-if="!isMobile" />
  <Drawer v-else v-model="sidebarOpen">
    <Sidebar />
  </Drawer>
  
  <!-- Stack list and detail on mobile -->
  <div :class="isMobile ? 'flex-col' : 'flex'">
    <ListView v-show="!isMobile || !selectedDoc" />
    <DetailPanel v-if="selectedDoc" :fullScreen="isMobile" />
  </div>
</template>

Component reference

Use these Frappe UI components consistently:

Component	Usage
<Button>	All actions, with variants: solid, subtle, ghost
<Input>	Text inputs, search fields
<FormControl>	Form fields with labels, validation
<Select>	Dropdowns, status selectors
<Checkbox>	Boolean inputs, bulk selection
<Avatar>	User images, entity icons
<Badge>	Status indicators, counts
<Dropdown>	Action menus, context menus
<Dialog>	Modal confirmations, forms
<Tabs>	Content organization
<Tooltip>	Helpful hints, truncated text

Verification

• App shell matches standard layout (sidebar + main + optional detail)
• List views have search, filters, view toggle, create button
• Detail panel has tabs (Details, Activity, Notes)
• Empty states are helpful with actions
• Loading states use skeletons, not spinners
• Status colors follow conventions
• Forms are sectioned and consistent
• Mobile experience is considered

Failure modes / debugging

• Inconsistent spacing: Use TailwindCSS spacing scale (p-2, p-4, gap-2, gap-4)
• Wrong component: Check Frappe UI docs for correct component and props
• Broken responsiveness: Test at mobile breakpoints; use sm:, md:, lg: prefixes
• Missing states: Ensure loading, empty, and error states are handled

Escalation

• For component implementation → frappe-frontend-development
• For backend API integration → frappe-api-development
• For enterprise workflows → frappe-enterprise-patterns

References

• references/app-shell-patterns.md — Detailed shell layouts
• references/component-patterns.md — Component usage guide
• references/mobile-patterns.md — Responsive design

Guardrails

• Study official apps first: Before designing UI, review CRM, Helpdesk, or relevant official app for patterns
• Use Frappe UI components: Never create custom components when Frappe UI has an equivalent
• Follow spacing conventions: Use consistent padding/margins (4px increments)
• Provide all states: Every view needs loading, empty, and error states
• Keep navigation consistent: Sidebar structure should match official apps
• Test responsively: Ensure mobile experience works

Common Mistakes

Mistake	Why It Fails	Fix
Custom app shell design	Unfamiliar UX for users	Copy CRM/Helpdesk shell structure
Missing empty states	Users confused when no data	Add EmptyState component with action
Spinner instead of skeleton	Jarring loading experience	Use Skeleton components for loading
Inconsistent status colors	User confusion	Follow color conventions table
Deep nesting without breadcrumbs	Users get lost	Add breadcrumb navigation
Modal overuse	Disruptive workflow	Prefer side panels for detail views
No keyboard navigation	Accessibility issues	Ensure Tab/Enter work for key flows