---
name: minimalist-ui-design
description: This skill provides guidance for implementing the Thor Electric minimalist UI design system. Use this skill when styling Django templates with Tailwind CSS to maintain consistency across the application with clean, professional aesthetics featuring black buttons, light typography, white cards, and Heroicons.
context: fork
---
# Minimalist UI Design System
This skill documents the minimalist design pattern used throughout the Thor Electric application. Apply these patterns when creating or updating Django templates to ensure visual consistency and professional aesthetics.
## When to Use This Skill
Use this skill when:
- Creating new Django templates for Thor Electric
- Updating existing pages to match the minimalist design system
- Implementing forms, lists, cards, or navigation elements
- Adding search bars, buttons, or interactive components
- Converting designs from gradients/shadows to clean minimalist style
## Core Design Principles
### 1. Typography
- **Headers**: Use `font-light` (not font-bold or font-black) with `tracking-tight` for clean, modern appearance
- **Body text**: Use `text-sm text-gray-500` for secondary information
- **Primary text**: Use `text-gray-900` for main content
- **Examples**:
```html
Page Title
Subtitle or description
```
### 2. Buttons
#### Primary Action Buttons (Black)
Use for main actions like "Add", "Create", "Save", "Submit":
```html
```
#### Secondary Action Buttons (White with Gray Border)
Use for secondary actions like "View", "Cancel":
```html
```
#### Icon-Only Buttons
For actions in tight spaces:
```html
```
### 3. Cards
Replace gradient backgrounds and heavy shadows with clean white cards and gray borders:
```html
```
**Before (Old Style)**:
```html
```
**After (New Style)**:
```html
```
### 4. Search Bars (Flexbox Pattern)
All search bars should use this consistent pattern:
```html
```
**Key Features**:
- White background with gray border
- Icon container uses padding-left (pl-4) instead of absolute positioning
- Input uses flex-1 to fill remaining space
- Gray focus states (no colored rings)
- Transparent input background
### 5. Icons
#### Use Heroicons (Inline SVG)
Replace all Feather icons with Heroicons:
**Search Icon**:
```html
```
**Plus Icon**:
```html
```
**Arrow Left Icon**:
```html
```
**X (Close) Icon**:
```html
```
**Info Icon**:
```html
```
**Hash (Channel) Icon**:
```html
```
### 6. Form Inputs
#### Text Inputs & Dropdowns
```html
```
**Key Features**:
- Gray borders (border-gray-200)
- Gray focus states (no colored rings)
- Rounded corners (rounded-xl)
- Consistent padding (px-4 py-3)
#### Enhanced Date Picker with Flatpickr
For clean, minimalist date selection, use Flatpickr instead of default browser date inputs:
**1. Add Flatpickr CDN to template** (in `{% block extra_head %}`):
```html
{% block extra_head %}
{% endblock %}
```
**2. Initialize Flatpickr** (in your JavaScript):
```javascript
document.addEventListener('DOMContentLoaded', function () {
// Find all date inputs and apply Flatpickr
const dateInputs = document.querySelectorAll('input[type="date"]')
dateInputs.forEach((input) => {
flatpickr(input, {
dateFormat: 'Y-m-d',
altInput: true,
altFormat: 'F j, Y',
allowInput: true,
disableMobile: false,
theme: 'light',
})
})
})
```
**Result**: Clean calendar picker with:
- Rounded corners matching your design system
- Gray borders and subtle shadows
- Black selected date (matching button style)
- Light gray hover states
- Human-readable date display ("January 15, 2025")
#### Enhanced Dropdowns with Choices.js
For searchable, clean dropdowns instead of default browser selects:
**1. Add Choices.js CDN to template** (in `{% block extra_head %}`):
```html
{% block extra_head %}
{% endblock %}
```
**2. Initialize Choices.js BEFORE attaching event listeners**:
```javascript
document.addEventListener('DOMContentLoaded', function () {
// Initialize Choices.js on select elements FIRST
const mySelect = document.getElementById('mySelectElement')
let myChoices = null
if (mySelect) {
// Initialize Choices.js to transform the select
myChoices = new Choices(mySelect, {
searchEnabled: true,
shouldSort: false,
placeholder: true,
placeholderValue: 'Choose an option...',
searchPlaceholderValue: 'Search...',
allowHTML: false,
itemSelectText: '',
noResultsText: 'No results found',
noChoicesText: 'No options available',
})
// THEN attach event listeners AFTER Choices.js initialization
mySelect.addEventListener('change', function () {
const value = this.value
// Handle change event
})
}
})
```
**IMPORTANT**: Always initialize Choices.js BEFORE attaching event listeners to the select element. If you attach events first, they'll be attached to the raw select before Choices.js transforms it.
**Result**: Professional searchable dropdowns with:
- Clean rounded borders matching your design system
- Search functionality built-in
- Smooth animations and transitions
- Gray color palette (no bright colors)
- Keyboard navigation support
- Mobile-friendly
### 7. Icon Containers
For decorative icon containers (in cards, headers, etc.):
**Black Background** (Primary):
```html
```
**Before (Old Style - Gradients)**:
```html
```
**After (New Style - Black)**:
```html
```
### 8. Filter Sections
Filter panels should use clean white backgrounds:
```html
```
### 9. Color Palette
**Primary Colors**:
- Black buttons: `bg-gray-900` with `hover:bg-gray-800`
- Card backgrounds: `bg-white`
- Card borders: `border-gray-200`
- Hover borders: `hover:border-gray-300`
**Text Colors**:
- Primary headings: `text-gray-900`
- Body text: `text-gray-700`
- Secondary text: `text-gray-500`
- Placeholder text: `placeholder-gray-500`
- Icons: `text-gray-400` or `text-gray-600`
**Status Colors** (Keep these):
- Success: `bg-emerald-50 text-emerald-700 border-emerald-200`
- Warning: `bg-orange-50 text-orange-700 border-orange-200`
- Error: `bg-red-50 text-red-700 border-red-200`
- Info: `bg-blue-50 text-blue-700 border-blue-200`
### 10. Navigation Active States
For sidebar navigation, use conditional highlighting:
```html
```
## Migration Checklist
When updating an existing page to the minimalist design:
- [ ] Change `font-bold` or `font-black` headers to `font-light` with `tracking-tight`
- [ ] Replace gradient buttons with `bg-gray-900 hover:bg-gray-800`
- [ ] Update cards from `shadow-lg` to `border border-gray-200`
- [ ] Convert search bars to flexbox pattern
- [ ] Replace Feather icons with Heroicons (inline SVG)
- [ ] Update form inputs to gray borders and focus states
- [ ] Change icon containers from gradients to black (`bg-gray-900`)
- [ ] Update dropdown borders from colored to gray
- [ ] Ensure all text uses appropriate gray shades
- [ ] Remove any remaining gradient backgrounds
## Examples
See these successfully implemented pages:
- Materials Catalog (`core/templates/materials/materials_list.html`)
- Quote Form (`financial/templates/financial/quote_form.html`)
- Team Channels (`messaging/templates/messaging/team_channels.html`)
- Channel Detail (`messaging/templates/messaging/channel_detail.html`)
## Notes
- **Avoid emojis**: Don't use emojis in templates unless explicitly requested by the user
- **Keep accessibility**: Maintain proper ARIA labels and semantic HTML
- **Responsive design**: Ensure mobile-first responsive layouts work correctly
- **Consistency is key**: The goal is visual consistency across all pages