Frappe Ui Patterns

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:

1) Sidebar patterns

Standard structure:

  
    
    
      My App
    
    
    
    
      
    
    
    
    
      Filters
      
    
    
    
    
      
    
  

CRM example nav items:

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

2) List view patterns

Standard list with filters:

  
    
    
      
        
        
      
      
        
        
          
          New
        
      
    
    
    
    
    
    
  

List row structure:

  
    
    
    
    
    
    
    
    
      {{ row.title }}
      {{ row.subtitle }}
    
    
    
    {{ row.status }}
    
    
    {{ timeAgo(row.modified) }}
    
    
    
      
    
  

3) Kanban view patterns

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

  
    
      
      
        {{ column.label }}
        {{ column.items.length }}
      
      
      
      
        
      
      
      
      
        + Add {{ column.singular }}
      
    
  

Kanban card structure:

  
    {{ data.title }}
    {{ data.subtitle }}
    
      
      {{ data.due_date }}
    
  

4) Detail panel / side panel

Split view pattern (CRM/Helpdesk style):

  
    
    
      {{ doc.name }}
      
    
    
    
    
      
      
      
    
    
    
    
      
      
      
    
    
    
    
      Edit
      {{ primaryActionLabel }}
    
  

5) Form patterns

Standard form layout:

  
    
    
      {{ isNew ? 'New' : 'Edit' }} {{ doctype }}
    
    
    
    
      
        
        
      
      
    
    
    
      
    
    
    
    
      Cancel
      Save
    
  

FormSection component:

  
    
      {{ title }}
      
    
    
      
    
  

6) Activity feed pattern

Used across all apps for tracking changes:

  
    
    
      
      
        
        Comment
      
    
    
    
    
      
      
        
          {{ item.owner }}
          {{ timeAgo(item.creation) }}
        
        
        
        
        
      
    
  

7) Empty states

Always provide helpful empty states:

  
    
    {{ title }}
    {{ description }}
    
      {{ action.label }}
    
  

8) Loading states

Skeleton loaders for perceived performance:

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:

Active
Pending
Overdue
New
Draft

10) Responsive patterns

Mobile-first considerations:

Component reference

Use these Frappe UI components consistently:

| Component | Usage | |-----------|-------| | ` | All actions, with variants: solid, subtle, ghost | | | Text inputs, search fields | | | Form fields with labels, validation | | | Dropdowns, status selectors | | | Boolean inputs, bulk selection | | | User images, entity icons | | | Status indicators, counts | | | Action menus, context menus | | | Modal confirmations, forms | | | Content organization | | ` | 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](references/app-shell-patterns.md) — Detailed shell layouts
• [references/component-patterns.md](references/component-patterns.md) — Component usage guide
• [references/mobile-patterns.md](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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lubusIN
• Source: lubusIN/frappe-skills
• License: MIT

Install and usage instructions live in the source repository linked above.