# Frappe Ui Patterns

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

- **Type:** Skill
- **Install:** `agentstack add skill-lubusin-frappe-skills-frappe-ui-patterns`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lubusIN](https://agentstack.voostack.com/s/lubusin)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lubusIN](https://github.com/lubusIN)
- **Source:** https://github.com/lubusIN/frappe-skills/tree/main/frappe-ui-patterns

## Install

```sh
agentstack add skill-lubusin-frappe-skills-frappe-ui-patterns
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/frappe/crm) | Lead/Deal pipelines, Kanban, activity feeds |
| Frappe Helpdesk | [github.com/frappe/helpdesk](https://github.com/frappe/helpdesk) | Ticket queues, SLA indicators, agent views |
| Frappe HRMS | [github.com/frappe/hrms](https://github.com/frappe/hrms) | Employee self-service, approvals, dashboards |
| Frappe Insights | [github.com/frappe/insights](https://github.com/frappe/insights) | Query builders, visualizations, dashboards |
| Frappe Builder | [github.com/frappe/builder](https://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:**
```vue

  
    
    
    
    
    
      
      
    
  

```

### 1) Sidebar patterns

**Standard structure:**
```vue

  
    
    
      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:**
```vue

  
    
    
      
        
        
      
      
        
        
          
          New
        
      
    
    
    
    
    
    
  

```

**List row structure:**
```vue

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

```

### 3) Kanban view patterns

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

```vue

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

```

**Kanban card structure:**
```vue

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

```

### 4) Detail panel / side panel

**Split view pattern (CRM/Helpdesk style):**
```vue

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

```

### 5) Form patterns

**Standard form layout:**
```vue

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

```

**FormSection component:**
```vue

  
    
      {{ title }}
      
    
    
      
    
  

```

### 6) Activity feed pattern

**Used across all apps for tracking changes:**
```vue

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

```

### 7) Empty states

**Always provide helpful empty states:**
```vue

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

```

### 8) Loading states

**Skeleton loaders for perceived performance:**
```vue

  
    
      
      
        
        
      
    
  
  

```

### 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:**
```vue
Active
Pending
Overdue
New
Draft
```

### 10) Responsive patterns

**Mobile-first considerations:**
```vue

  
  
  
    
  
  
  
  
    
    
  

```

## 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](https://github.com/lubusIN)
- **Source:** [lubusIN/frappe-skills](https://github.com/lubusIN/frappe-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lubusin-frappe-skills-frappe-ui-patterns
- Seller: https://agentstack.voostack.com/s/lubusin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.