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

<button class="btn btn-primary">Primary</button>

Success Button

<button class="btn btn-success">Success</button>

Danger Button

<button class="btn btn-danger">Delete</button>

Warning Button

<button class="btn btn-warning">Warning</button>

Sizes

<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

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

<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

<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

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

<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

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

---

⚠️ Alerts

Variants

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

<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

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

Input Sizes

<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

<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

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

Checkboxes

<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

<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

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

<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

<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

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

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

Table Pagination

<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

<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

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

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

<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

<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

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

<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

<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

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

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

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

Toggle Dark Mode with 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

<!-- 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
• Bootstrap 5 Official Docs
• Icon Library (FontAwesome)

---

🔄 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