yaeyintlin199 · cto-new · Nov 8, 2025
diff --git a/ADMIN_UI_GUIDE.md b/ADMIN_UI_GUIDE.md
@@ -0,0 +1,385 @@
+# NxtBN Admin Dashboard UI - Lightswind Framework
+
+## Overview
+
+The NxtBN admin dashboard has been upgraded with a modern, responsive UI built on the **Lightswind** framework. This provides a native-feeling, high-performance dashboard experience across all devices (mobile, tablet, desktop).
+
+## 🎨 Design Philosophy
+
+### Responsive Breakpoints
+
+- **Mobile** (<768px): 2-column grid, compact layout, floating bottom dock navigation, FAB button for quick actions
+- **Tablet** (768px-1200px): 2-3 column grid, collapsible sidebar, medium-sized components
+- **Desktop** (>1200px): 3-4 column grid, persistent sidebar, large headings and controls
+
+### Visual Features
+
+- **Glassmorphic Panels**: Blurred backgrounds with depth shadows and floating layers
+- **Dynamic Typography**: Fonts and icons scale based on container width
+- **Rounded Corners**: Consistent use of 20-24px border radius for modern feel
+- **Proportional Spacing**: Tight spacing on mobile, generous on desktop
+- **Native-like Motion**: Smooth fade-in, spring transitions, touch feedback
+- **Micro-interactions**: Gradient buttons with depth-lift hover, card animations
+
+## 📁 File Structure
+
+```
+templates/
+├── admin/
+│   ├── base.html                 # Main base template with layout
+│   ├── dashboard.html            # Dashboard home page
+│   ├── products.html             # Products management
+│   ├── orders.html               # Orders management
+│   ├── users.html                # Users/customers management
+│   ├── settings.html             # Store settings
+│   ├── plugins.html              # Plugins & extensions
+│   └── includes/
+│       ├── header.html           # Top header with search & user menu
+│       ├── sidebar.html          # Left sidebar navigation
+│       └── mobile_dock.html      # Bottom mobile navigation dock
+
+static/
+├── css/
+│   └── admin.css                 # Lightswind-based CSS utilities
+└── js/
+    └── admin.js                  # JavaScript utilities & helpers
+```
+
+## 🔧 Components & Utilities
+
+### CSS Utilities
+
+The admin.css file provides comprehensive Tailwind-like utilities:
+
+- **Layout**: flex, grid, display, position, overflow
+- **Spacing**: padding, margin, gap
+- **Sizing**: width, height, max-width
+- **Colors**: text, background, borders with CSS custom properties
+- **Shadows & Effects**: shadow, rounded, transition, animation
+- **Responsive**: @media queries for mobile-first design
+
+### JavaScript Utilities
+
+The admin.js file exports several utility classes:
+
+```javascript
+// Toast notifications
+Toast.show('Success message', 'success', 3000);
+Toast.show('Error message', 'error');
+
+// Modal dialogs
+Modal.show('Title', '<div>Content</div>', [
+    { label: 'Cancel', type: 'secondary', onclick: 'Modal.close()' },
+    { label: 'Save', type: 'primary' }
+]);
+Modal.close();
+
+// API calls with CSRF token
+const data = await API.get('/order/dashboard/api/orders/');
+const result = await API.post('/order/dashboard/api/orders/', { name: 'Order' });
+const updated = await API.put('/order/dashboard/api/orders/1/', { status: 'shipped' });
+await API.delete('/order/dashboard/api/orders/1/');
+
+// Form utilities
+Form.validate(formElement);
+Form.reset(formElement);
+const data = Form.getFormData(formElement);
+
+// Data table utilities
+DataTable.sort(table, columnIndex, 'asc');
+DataTable.filter(table, columnIndex, searchTerm);
+
+// Responsive utilities
+Responsive.isMobile();   // < 768px
+Responsive.isTablet();   // 768px - 1024px
+Responsive.isDesktop();  // > 1024px
+
+// Debounce & Throttle
+const debouncedFunc = debounce(function, 300);
+const throttledFunc = throttle(function, 100);
+```
+
+## 🎯 Key Features
+
+### Accessibility
+
+- ARIA labels on interactive elements
+- Focus rings for keyboard navigation
+- Support for `prefers-reduced-motion`
+- Proper semantic HTML structure
+- Color contrast ratios meet WCAG standards
+
+### Performance
+
+- Smooth transitions under 200ms
+- Lazy-loaded images and components
+- Prefetching for navigation links
+- Minimized reflows and repaints
+- CSS custom properties for theme management
+
+### Usability
+
+- Keyboard shortcuts:
+  - `Cmd/Ctrl + K`: Open search
+  - `Esc`: Close modals
+- Mobile-first navigation with FAB button
+- Inline edit popups instead of page navigation
+- Sticky header on scroll
+- Floating action button for quick create on mobile
+
+## 🌓 Dark Mode
+
+Dark mode is automatically available and uses system preference detection:
+
+```javascript
+// Toggle theme
+toggleTheme();
+
+// Theme is saved to localStorage
+// Automatically loads on page load
+```
+
+The dark mode CSS is provided in admin.css under `@media (prefers-color-scheme: dark)`.
+
+## 📱 Responsive Design Examples
+
+### Mobile Layout
+- 2-column card grid (48% width each)
+- Floating dock at bottom with 5 main sections
+- Full-screen modals with slide-up animation
+- Compact buttons and inputs (0.9rem - 1rem font)
+- Floating "+" action button in bottom-right
+
+### Tablet Layout
+- 2-3 column grid with moderate padding
+- Collapsible sidebar
+- Medium-sized components
+- 1rem - 1.1rem font size
+
+### Desktop Layout
+- 3-4 column grid
+- Persistent sidebar
+- Hover elevation effects on cards
+- Large headings and controls
+- Animated shadows
+
+## 🚀 Usage Examples
+
+### Creating a New Admin Page
+
+1. **Create template file** `templates/admin/mypage.html`:
+
+```django
+{% extends 'admin/base.html' %}
+{% load static %}
+
+{% block title %}My Page - NXTBN Admin{% endblock %}
+
+{% block content %}
+<div class="py-6">
+    <h1 class="text-3xl font-bold">My Page</h1>
+
+    <div class="dashboard-grid">
+        <div class="card">
+            <h3 class="text-lg font-semibold">Card Title</h3>
+            <p class="text-gray-600">Card content here</p>
+        </div>
+    </div>
+</div>
+{% endblock %}
+```
+
+2. **Add route** in `nxtbn/home/urls.py`:
+
+```python
+from nxtbn.home import views as home_views
+
+path('mypage/', home_views.my_page, name='my_page'),
+```
+
+3. **Create view** in `nxtbn/home/views.py`:
+
+```python
+@staff_member_required
+def my_page(request):
+    return render(request, 'admin/mypage.html')
+```
+
+4. **Add navigation link** in `templates/admin/includes/sidebar.html`:
+
+```html
+<a href="{% url 'my_page' %}" class="nav-item">
+    <svg class="w-5 h-5"><!-- icon --></svg>
+    <span>My Page</span>
+</a>
+```
+
+### Adding API Integration
+
+Use the `API` utility to fetch data:
+
+```javascript
+// In your template
+<script>
+async function loadData() {
+    const data = await API.get('/order/dashboard/api/orders/');
+    console.log(data);
+
+    // Update UI with data
+}
+
+document.addEventListener('DOMContentLoaded', loadData);
+</script>
+```
+
+### Creating Forms
+
+```html
+<form onsubmit="handleSubmit(event)">
+    <div>
+        <label class="block text-sm font-medium mb-2">Email</label>
+        <input type="email" name="email" class="input" required>
+    </div>
+
+    <div class="mt-6 flex gap-3">
+        <button type="button" class="btn btn-secondary">Cancel</button>
+        <button type="submit" class="btn btn-primary">Save</button>
+    </div>
+</form>
+
+<script>
+function handleSubmit(event) {
+    event.preventDefault();
+    const form = event.target;
+
+    if (!Form.validate(form)) {
+        Toast.show('Please fill all fields', 'error');
+        return;
+    }
+
+    const data = Form.getFormData(form);
+    API.post('/endpoint/', data).then(result => {
+        Toast.show('Saved successfully', 'success');
+        Form.reset(form);
+    });
+}
+</script>
+```
+
+## 🎨 Customization
+
+### Colors
+
+Modify CSS custom properties in `admin.css`:
+
+```css
+:root {
+    --lw-primary: #0caf60;
+    --lw-primary-dark: #0a8a48;
+    --lw-secondary: #1f2937;
+    /* ... other colors ... */
+}
+```
+
+### Fonts
+
+Currently using 'Inter' font from Google Fonts. Modify in `base.html`:
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Your+Font:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
+```
+
+### Spacing
+
+Adjust spacing scale in `admin.css`:
+
+```css
+--spacing-xs: 0.25rem;
+--spacing-sm: 0.5rem;
+--spacing-md: 1rem;
+--spacing-lg: 1.5rem;
+--spacing-xl: 2rem;
+--spacing-2xl: 3rem;
+```
+
+## ⚡ Performance Tips
+
+1. **Use lazy loading** for images:
+```html
+<img src="..." loading="lazy" alt="...">
+```
+
+2. **Debounce search inputs**:
+```html
+<input onkeyup="debounce(search, 300)">
+```
+
+3. **Optimize images** before uploading
+4. **Minimize JavaScript** in critical paths
+5. **Use CSS classes** instead of inline styles
+
+## 🔒 Security
+
+- All API calls include CSRF token
+- Templates use Django's `{% csrf_token %}`
+- User authentication required via `@staff_member_required`
+- Form inputs are escaped by Django template engine
+
+## 🐛 Debugging
+
+Enable debug logging in browser console:
+
+```javascript
+// Log API calls
+const origFetch = window.fetch;
+window.fetch = function(...args) {
+    console.log('Fetch:', args);
+    return origFetch.apply(this, args);
+};
+
+// Log toast messages
+const origToastShow = Toast.show;
+Toast.show = function(msg, type) {
+    console.log(`[${type.toUpperCase()}]`, msg);
+    return origToastShow.apply(this, arguments);
+};
+```
+
+## 📚 Dependencies
+
+- Django 4.2
+- Python 3.10+
+- Browser with ES6 support
+- No external JavaScript libraries required (vanilla JS)
+- CSS uses custom properties (CSS variables)
+
+## 🤝 Contributing
+
+When adding new features to the admin UI:
+
+1. Follow existing code style
+2. Use the provided utility classes from admin.css
+3. Ensure responsive design across all breakpoints
+4. Test accessibility with keyboard navigation
+5. Support dark mode
+6. Maintain performance under 200ms transitions
+
+## 📝 Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## 🎓 Learning Resources
+
+- [MDN Web Docs](https://developer.mozilla.org/)
+- [Django Documentation](https://docs.djangoproject.com/)
+- [Responsive Design](https://web.dev/responsive-web-design-basics/)
+- [Web Accessibility](https://www.w3.org/WAI/ARIA/apg/)
+
+---
+
+**Version**: 1.0.0  
+**Framework**: Lightswind  
+**Last Updated**: 2024