QuantEngineByItz/legacy/smartadmin/STYLE_GUIDE.md

# SmartAdmin Bootstrap 5 — Style Guide

**Version**: 5.5.0  
**Last Updated**: 2026-07-05  
**Status**: ✅ Complete

---

## 📖 Overview

This document provides comprehensive guidelines for using SmartAdmin Bootstrap 5 components and utilities. All styles are organized in modular CSS files for better maintainability and performance.

---

## 🎨 Color System

### Primary Palette

| Color | Hex Value | Usage |
|-------|-----------|-------|
| **Primary** | `#2196f3` | Main actions, links, highlights |
| **Secondary** | `#757575` | Neutral, less prominent elements |
| **Success** | `#4caf50` | Positive actions, confirmations |
| **Danger** | `#f44336` | Destructive actions, errors |
| **Warning** | `#ff9800` | Caution, warnings |
| **Info** | `#00bcd4` | Information, notifications |

### Neutral Palette

| Color | Hex Value | Usage |
|-------|-----------|-------|
| **Light** | `#f5f5f5` | Light backgrounds |
| **Dark** | `#212121` | Dark backgrounds, text |
| **White** | `#ffffff` | Main background |
| **Transparent** | `rgba(0,0,0,0)` | No background |

### Gray Scale

```
Gray 100: #f8f9fa (Lightest)
Gray 200: #e9ecef
Gray 300: #dee2e6
Gray 400: #ced4da
Gray 500: #adb5bd (Medium)
Gray 600: #6c757d
Gray 700: #495057
Gray 800: #343a40
Gray 900: #212529 (Darkest)
```

---

## 🔘 Buttons

### Variants

**Primary Button**
```html
<button class="btn btn-primary">Primary</button>
```

**Success Button**
```html
<button class="btn btn-success">Success</button>
```

**Danger Button**
```html
<button class="btn btn-danger">Delete</button>
```

**Warning Button**
```html
<button class="btn btn-warning">Warning</button>
```

### Sizes

```html
<button class="btn btn-primary btn-xs">Extra Small</button>
<button class="btn btn-primary btn-sm">Small</button>
<button class="btn btn-primary">Default</button>
<button class="btn btn-primary btn-lg">Large</button>
```

### States

```html
<!-- Disabled -->
<button class="btn btn-primary" disabled>Disabled</button>

<!-- Loading -->
<button class="btn btn-primary" disabled>
  <span class="spinner-border spinner-border-sm me-2"></span>
  Loading...
</button>

<!-- With Icon -->
<button class="btn btn-primary">
  <i class="fa-solid fa-save me-2"></i>Save
</button>
```

### Button Groups

```html
<div class="btn-group" role="group">
  <button type="button" class="btn btn-primary">Left</button>
  <button type="button" class="btn btn-primary">Middle</button>
  <button type="button" class="btn btn-primary">Right</button>
</div>
```

---

## 📇 Cards

### Basic Card

```html
<div class="card">
  <div class="card-header">
    Header
  </div>
  <div class="card-body">
    <h5 class="card-title">Title</h5>
    <p class="card-text">Content goes here...</p>
  </div>
  <div class="card-footer">
    Footer
  </div>
</div>
```

### Card Variants

```html
<!-- Card with Badge -->
<div class="card">
  <div class="card-body">
    <span class="badge badge-primary">New</span>
    <h5 class="card-title">Card Title</h5>
    <p class="card-text">Content here...</p>
  </div>
</div>

<!-- Hoverable Card -->
<div class="card" style="cursor: pointer;">
  <!-- Content -->
</div>
```

---

## 🏷️ Badges

### Variants

```html
<span class="badge badge-primary">Primary</span>
<span class="badge badge-success">Success</span>
<span class="badge badge-danger">Danger</span>
<span class="badge badge-warning">Warning</span>
<span class="badge badge-info">Info</span>
```

### Pill Badges

```html
<span class="badge badge-primary badge-pill">Primary</span>
<span class="badge badge-success badge-pill">Success</span>
```

---

## ⚠️ Alerts

### Variants

```html
<!-- Info Alert -->
<div class="alert alert-primary">
  <i class="fa-solid fa-info-circle me-2"></i>
  <strong>Info:</strong> Informational message
</div>

<!-- Success Alert -->
<div class="alert alert-success">
  <strong>Success!</strong> Operation completed
</div>

<!-- Warning Alert -->
<div class="alert alert-warning">
  <strong>Warning!</strong> Please be careful
</div>

<!-- Danger Alert -->
<div class="alert alert-danger">
  <strong>Error!</strong> Something went wrong
</div>
```

### Dismissible Alert

```html
<div class="alert alert-primary alert-dismissible">
  <strong>Info:</strong> Message goes here
  <button type="button" class="btn-close" data-dismiss="alert"></button>
</div>
```

---

## 📝 Forms

### Input Fields

```html
<div class="form-group">
  <label class="form-label">Email Address</label>
  <input type="email" class="form-control" placeholder="user@example.com">
</div>
```

### Input Sizes

```html
<input type="text" class="form-control form-control-sm" placeholder="Small input">
<input type="text" class="form-control" placeholder="Default input">
<input type="text" class="form-control form-control-lg" placeholder="Large input">
```

### Select

```html
<div class="form-group">
  <label class="form-label">Choose Option</label>
  <select class="form-select">
    <option>Select...</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </select>
</div>
```

### Textarea

```html
<div class="form-group">
  <label class="form-label">Message</label>
  <textarea class="form-control" rows="4"></textarea>
</div>
```

### Checkboxes

```html
<div class="form-check">
  <input type="checkbox" class="form-check-input" id="check1">
  <label class="form-check-label" for="check1">
    Check this option
  </label>
</div>
```

### Radio Buttons

```html
<div class="form-check">
  <input type="radio" class="form-check-input" name="options" id="radio1">
  <label class="form-check-label" for="radio1">
    Option 1
  </label>
</div>
```

### Form Validation

```html
<!-- Valid -->
<input type="text" class="form-control is-valid">
<div class="valid-feedback">Looks good!</div>

<!-- Invalid -->
<input type="text" class="form-control is-invalid">
<div class="invalid-feedback">Please correct this</div>
```

### Input Groups

```html
<div class="input-group">
  <span class="input-group-text">$</span>
  <input type="number" class="form-control">
</div>

<div class="input-group">
  <input type="text" class="form-control" placeholder="Search...">
  <button class="btn btn-primary">
    <i class="fa-solid fa-search"></i>
  </button>
</div>
```

---

## 📊 Tables

### Basic Table

```html
<table class="table">
  <thead>
    <tr>
      <th>ID</th>
      <th>Name</th>
      <th>Email</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>#001</td>
      <td>John Doe</td>
      <td>john@example.com</td>
    </tr>
  </tbody>
</table>
```

### Table Variants

```html
<!-- Striped -->
<table class="table table-striped">...</table>

<!-- Hover -->
<table class="table table-hover">...</table>

<!-- Bordered -->
<table class="table table-bordered">...</table>

<!-- Striped + Hover -->
<table class="table table-striped table-hover">...</table>
```

### Responsive Table

```html
<div class="table-responsive">
  <table class="table">...</table>
</div>
```

### Table Pagination

```html
<div class="table-pagination">
  <span>Showing 1-10 of 100</span>
  <ul class="pagination">
    <li class="page-item"><a class="page-link" href="#">Previous</a></li>
    <li class="page-item active"><a class="page-link" href="#">1</a></li>
    <li class="page-item"><a class="page-link" href="#">2</a></li>
    <li class="page-item"><a class="page-link" href="#">Next</a></li>
  </ul>
</div>
```

---

## 🎭 Modals

### Basic Modal

```html
<div class="modal" id="exampleModal">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title">Modal Title</h5>
        <button class="btn-close" data-dismiss="modal"></button>
      </div>
      <div class="modal-body">
        Modal content goes here...
      </div>
      <div class="modal-footer">
        <button class="btn btn-secondary" data-dismiss="modal">Close</button>
        <button class="btn btn-primary">Save</button>
      </div>
    </div>
  </div>
</div>
```

### Modal Sizes

```html
<!-- Small -->
<div class="modal-dialog modal-sm">...</div>

<!-- Default -->
<div class="modal-dialog">...</div>

<!-- Large -->
<div class="modal-dialog modal-lg">...</div>

<!-- Extra Large -->
<div class="modal-dialog modal-xl">...</div>
```

---

## 🌈 Utilities

### Spacing

```html
<!-- Margin -->
<div class="m-1">Margin 1</div>
<div class="m-2">Margin 2</div>
<div class="m-3">Margin 3</div>

<!-- Padding -->
<div class="p-1">Padding 1</div>
<div class="p-2">Padding 2</div>
<div class="p-3">Padding 3</div>

<!-- Specific Sides -->
<div class="mt-3">Margin Top</div>
<div class="mb-3">Margin Bottom</div>
<div class="ms-3">Margin Start</div>
<div class="me-3">Margin End</div>
```

### Display

```html
<div class="d-none">Hidden</div>
<div class="d-block">Block</div>
<div class="d-flex">Flex</div>
<div class="d-grid">Grid</div>

<!-- Responsive -->
<div class="d-none d-sm-block">Hidden on mobile, visible on tablet+</div>
<div class="d-sm-none">Visible on mobile, hidden on tablet+</div>
```

### Flexbox

```html
<div class="d-flex">
  <div class="flex-fill">Fill available space</div>
  <div class="flex-shrink-0">Don't shrink</div>
</div>

<div class="d-flex justify-content-between">
  <div>Left</div>
  <div>Right</div>
</div>

<div class="d-flex align-items-center gap-2">
  <i class="fa-solid fa-check"></i>
  <span>Centered vertically</span>
</div>
```

### Text Utilities

```html
<!-- Alignment -->
<p class="text-start">Left</p>
<p class="text-center">Center</p>
<p class="text-end">Right</p>

<!-- Transform -->
<p class="text-uppercase">UPPERCASE</p>
<p class="text-lowercase">lowercase</p>
<p class="text-capitalize">Capitalize</p>

<!-- Weight -->
<p class="text-bold">Bold</p>
<p class="text-semi-bold">Semi-bold</p>
<p class="text-normal">Normal</p>

<!-- Color -->
<p class="text-primary">Primary text</p>
<p class="text-success">Success text</p>
<p class="text-danger">Danger text</p>
<p class="text-muted">Muted text</p>
```

### Background Colors

```html
<div class="bg-primary text-white">Primary Background</div>
<div class="bg-success text-white">Success Background</div>
<div class="bg-danger text-white">Danger Background</div>
<div class="bg-warning text-white">Warning Background</div>
<div class="bg-light">Light Background</div>
```

### Borders

```html
<div class="border">All borders</div>
<div class="border-top">Top border only</div>
<div class="border-0">No border</div>
<div class="border border-primary">Primary border</div>

<!-- Rounded -->
<div class="rounded">Rounded corners</div>
<div class="rounded-circle">Circle</div>
<div class="rounded-pill">Pill shape</div>
```

### Shadows

```html
<div class="shadow">Small shadow</div>
<div class="shadow-lg">Large shadow</div>
<div class="shadow-none">No shadow</div>
```

---

## 🌙 Dark Mode

SmartAdmin supports dark mode through the `data-bs-theme` attribute:

```html
<!-- Light Mode (default) -->
<html data-bs-theme="light">

<!-- Dark Mode -->
<html data-bs-theme="dark">
```

### Toggle Dark Mode with JavaScript

```javascript
const html = document.documentElement;
const currentTheme = html.getAttribute('data-bs-theme');
const newTheme = currentTheme === 'light' ? 'dark' : 'light';
html.setAttribute('data-bs-theme', newTheme);

// Save preference
localStorage.setItem('theme', newTheme);
```

---

## 📱 Responsive Breakpoints

| Breakpoint | Viewport | Class Prefix |
|------------|----------|--------------|
| **Mobile** | < 576px | None |
| **Tablet (sm)** | ≥ 576px | `-sm-` |
| **Tablet (md)** | ≥ 768px | `-md-` |
| **Desktop (lg)** | ≥ 992px | `-lg-` |
| **Desktop (xl)** | ≥ 1200px | `-xl-` |
| **Desktop (xxl)** | ≥ 1400px | `-xxl-` |

### Examples

```html
<!-- Hide on mobile, show on tablet+ -->
<div class="d-none d-sm-block">...</div>

<!-- Different columns on different screens -->
<div class="col-12 col-sm-6 col-md-4 col-lg-3">
  Responsive column
</div>

<!-- Different padding on different screens -->
<div class="p-2 p-md-3 p-lg-4">
  Responsive padding
</div>
```

---

## ✅ Best Practices

1. **Use Semantic HTML**: Always use appropriate HTML elements
2. **Accessibility First**: Include ARIA labels and keyboard navigation
3. **Mobile First**: Design for mobile first, then enhance for larger screens
4. **Consistent Spacing**: Use spacing scale (1, 2, 3, 4, 5) consistently
5. **Color Contrast**: Ensure text has sufficient contrast (WCAG AA minimum)
6. **Component Reuse**: Use existing components instead of creating new ones
7. **Document Changes**: Update this guide when adding new components
8. **Test on Real Devices**: Don't rely only on browser DevTools

---

## 📚 Component Library

Visit **`components-showcase.html`** to see all components in action with interactive examples.

### Quick Links

- [Live Component Demo](./components-showcase.html)
- [Bootstrap 5 Official Docs](https://getbootstrap.com/docs/5.0/)
- [Icon Library (FontAwesome)](https://fontawesome.com/)

---

## 🔄 CSS File Structure

```
css/
├── base.css           (Foundation, resets, typography)
├── components.css     (Buttons, cards, badges, alerts)
├── forms.css          (Input fields, validation)
├── tables.css         (Table styles, responsive)
├── layout.css         (Header, sidebar, grid)
├── darkmode.css       (Dark theme overrides)
├── responsive.css     (Mobile-first media queries)
├── utilities.css      (Spacing, colors, helpers)
└── smartapp.min.css   (Legacy, for compatibility)
```

**Load Order (HTML <head>):**
1. base.css
2. components.css
3. forms.css
4. tables.css
5. layout.css
6. darkmode.css
7. responsive.css
8. utilities.css
9. smartapp.min.css (fallback)

---

## 📞 Support

For issues or questions:
1. Check the component library first
2. Review this style guide
3. Check Bootstrap 5 official documentation
4. Create an issue in the repository

---

**Last Updated:** 2026-07-05  
**Version:** 5.5.0  
**Status:** ✅ Complete & Ready for Use