Components Library¶

Version: 0.6.0
Last Updated: January 3, 2026

Reusable UI components used throughout Arctyk ITSM. These components are built on Bootstrap 5 and provide consistent functionality and styling across the application.

Core Components¶

Breadcrumbs - Hierarchical navigation showing current location
Sidebar - Primary navigation menu with sections
Topbar - Top navigation with search, create button, user menu

Data Display¶

Tables - Data tables with sorting, filtering, pagination
Pagination - Page navigation and results-per-page selector
Sorting - Sortable column headers
Badges - Status indicators and labels

Forms & Interaction¶

Forms - Form components, validation, styling
Modals - Dialog boxes for confirmations and inputs

Component Stack¶

All components are built with:

Technology	Purpose
Bootstrap 5.3	Base CSS framework
Bootstrap Icons	Icon library
Django Templates	Server-side rendering
SCSS	Custom styling and variables
Vanilla JavaScript	Interactivity (no jQuery required)

Usage Patterns¶

Basic Include¶

{% include "partials/component_name.html" %}

With Context Variables¶

{% include "partials/pagination.html" with
    page_obj=page_obj
    model_name="users"
    view_name="user_list"
%}

Conditional Display¶

{% if items %}
    {% include "partials/tables.html" with items=items %}
{% else %}
    <p class="text-muted">No items found.</p>
{% endif %}

Directory Structure¶

src/
├── templates/
│   ├── base.html                    # Main layout
│   ├── layouts/
│   │   └── _layout_wrapper.html     # Page wrapper
│   └── partials/                    # Reusable components
│       ├── breadcrumbs.html
│       ├── sidebar.html
│       ├── topbar.html
│       ├── pagination.html
│       ├── sort_header.html
│       ├── tables.html
│       ├── forms.html
│       ├── modals.html
│       ├── badges.html
│       └── ...
└── static/
    └── scss/
        ├── app.scss                 # Main stylesheet
        └── components/
            ├── _breadcrumbs.scss
            ├── _tables.scss
            ├── _pagination.scss
            ├── _badges.scss
            └── ...

Styling¶

Bootstrap Classes¶

Components use standard Bootstrap 5 classes:

<!-- Button -->
<button class="btn btn-primary">Save</button>

<!-- Alert -->
<div class="alert alert-success">Saved successfully!</div>

<!-- Badge -->
<span class="badge bg-primary">New</span>

<!-- Table -->
<table class="table table-hover">
  <thead class="table-light">
    <tr>
      <th>Column</th>
    </tr>
  </thead>
</table>

Custom SCSS Variables¶

// colors
$primary: #007bff;
$success: #28a745;
$danger: #dc3545;
$warning: #ffc107;

// spacing
$spacer: 1rem;
$spacer-half: 0.5rem;

// typography
$font-size-base: 1rem;
$font-size-small: 0.875rem;

Dark Mode Support¶

Components support light/dark mode via CSS variables:

:root {
  --bs-body-bg: #ffffff;
  --bs-body-color: #212529;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bs-body-bg: #212529;
    --bs-body-color: #f8f9fa;
  }
}

Accessibility¶

All components follow WCAG 2.1 Level AA standards:

Semantic HTML¶

Use proper heading hierarchy (<h1> → <h6>)
Use semantic elements (<nav>, <main>, <section>)
Use form elements correctly (<label>, <input>, <button>)

ARIA Attributes¶

<!-- Navigation -->
<nav aria-label="Main navigation">
  <ul>
    ...
  </ul>
</nav>

<!-- Modal -->
<div role="dialog" aria-labelledby="modalTitle">
  <h2 id="modalTitle">Delete Item?</h2>
</div>

<!-- Current Page -->
<li aria-current="page">Dashboard</li>

All interactive elements accessible via Tab
Enter/Space to activate buttons
Escape to close modals
Arrow keys for select menus

Color Contrast¶

Minimum 4.5:1 for normal text
Minimum 3:1 for large text
Don't use color alone for meaning

JavaScript Integration¶

Vanilla JavaScript (No jQuery)¶

Components use modern vanilla JavaScript for interactivity:

// Get element
const button = document.querySelector(".btn-primary");

// Add event listener
button.addEventListener("click", function () {
  // Handle click
});

// Toggle class
button.classList.toggle("active");

// Query parameters
const params = new URLSearchParams(window.location.search);
const page = params.get("page");

Event Delegation¶

// Single event listener for multiple elements
document.addEventListener("click", function (e) {
  if (e.target.matches(".delete-btn")) {
    // Handle delete
  }
});

Common Patterns¶

Empty State¶

{% if items %}
    {% include "partials/tables.html" with items=items %}
{% else %}
    <div class="alert alert-info">
        <p>No items found. <a href="{% url 'create' %}">Create one?</a></p>
    </div>
{% endif %}

Loading State¶

{% if loading %}
    <div class="spinner-border" role="status">
        <span class="visually-hidden">Loading...</span>
    </div>
{% else %}
    {% include "partials/tables.html" with items=items %}
{% endif %}

Error Handling¶

{% if error %}
    <div class="alert alert-danger alert-dismissible fade show">
        {{ error }}
        <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
    </div>
{% endif %}

Testing Components¶

Template Tests¶

from django.test import TestCase, Client
from django.urls import reverse

class TestComponentRendering(TestCase):
    def test_pagination_renders(self):
        client = Client()
        response = client.get(reverse('users:list'))

        self.assertIn('pagination', response.content.decode())
        self.assertIn('Previous', response.content.decode())
        self.assertIn('Next', response.content.decode())

Visual Regression Tests¶

Use tools like Percy or BackstopJS to catch visual changes:

# Run visual tests
percy snapshot https://localhost:8000

Performance¶

Load Times¶

Components are optimized for:

CSS: Minified and compressed
Images: Optimized with proper formats
HTML: Semantic and minimal markup
JavaScript: Vanilla (no dependencies)

Bundle Size¶

styles.css: ~45KB (gzip)
scripts.js: ~12KB (gzip)

Rendering¶

Server-side rendered (no JS required for content)
Progressive enhancement for interactivity
Lazy loading for images

Customization¶

Overriding Styles¶

Create app-specific overrides:

// my-app/scss/components/_custom-badge.scss

.badge.custom-status {
  padding: 0.5rem 1rem;
  font-weight: 600;

  &.active {
    background-color: #28a745;
  }

  &.inactive {
    background-color: #6c757d;
  }
}

Extending Components¶

Extend templates via inheritance:

{# my-app/templates/partials/badge-custom.html #}
{% extends "partials/badges.html" %}

{% block badge_styles %}
    {# Add custom styles #}
{% endblock %}

Browser Support¶

Chrome/Edge (latest 2 versions)
Firefox (latest 2 versions)
Safari (latest 2 versions)
Mobile browsers (iOS Safari, Chrome Mobile)

Resources¶

Need help? Check the UI Development Guide for more details.