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 |