design-system

Design System

Every screen in every application must look like it came from the same template, because it did. The single source of truth is the reference set in this skill — extracted from the licensed Bootstrap 5.3 admin template the applications are built on.

References (read the one you need before writing markup)

• references/design-decisions.md — read first; overrides everything else where they conflict. The locked, project-independent design choices (canonical table = the "Traffic Reports" pattern with server-rendered pagination, interaction defaults, and the running list of pinned decisions).
• references/layout-skeleton.html — the canonical app-shell page: head/CSS includes, sidebar navigation (nxl-navigation), header (nxl-header), the main content container HTMX swaps into (marked MAIN CONTENT TARGET), footer, script includes.
• references/components.md — canonical markup for page headers, cards, list/table pages, create/edit forms, detail pages, buttons, badges, avatars, tabs.
• references/auth-layout.html — the auth-page skeleton (login/register/reset use this, minimal style).
• references/assets.md — which CSS/JS files each page includes and in what order.
• examples/ — a working, trimmed example application: the shell (index.html), HTMX partials for the list/form/view screens, the auth page, and the actual theme CSS/JS/font assets. Copy examples/assets/ into every new application verbatim — this is what guarantees pixel-identical styling. Use the example pages as the starting point for Phase 2's shell and for each screen type.

Non-negotiable rules

1. Copy, don't compose. Take the exact markup structure and class names from the references. Do not substitute generic Bootstrap markup where the template has its own pattern (nxl-* classes are load-bearing — the theme CSS/JS depends on the exact nesting).
2. No modal forms or display surfaces. No .modal for anything that shows or collects data — create/edit/detail are dedicated full pages; quick edits swap inline via HTMX; offcanvas drawers only for filters/quick views, full-width on mobile. Confirmations are exempt: hx-confirm (the browser confirm dialog) is the standard guard on destructive actions.
3. Mobile first. Every screen works at 375px: no horizontal page scroll, tables inside .table-responsive, action toolbars stack vertically, touch targets ≥ 44px. Check this before declaring any screen done.
4. No new styling — except app-overrides.css. No inline style=, no ad-hoc CSS files, no overriding theme variables without explicit user approval. The single sanctioned override file is assets/css/app-overrides.css (ships in examples/assets/), loaded after theme.min.css on every page — plugin-level corrections to the theme live there and nowhere else. If a component pattern is missing from components.md, add it there (from the original template) first, then use it.
5. Assets are fixed. Include exactly the CSS/JS listed in assets.md, in that order. Page-specific init scripts follow the template's naming convention and are loaded only on their page. When content arrives via HTMX swap, re-run the page-specific init in the htmx:afterSwap handler — theme JS bound at load time does not see swapped-in DOM.
6. HTMX is the interactivity layer. Server-rendered partials swapped into the main content target; hx-push-url for navigable screens; no SPA frameworks, no jQuery beyond what the theme itself ships.
7. Every meaningful element gets a unique, stable, kebab-case id per the naming scheme in design-decisions.md (left-sidenav, customers-list-table, customer-form-field-email, customer-row-{id}). IDs are the change-request vocabulary: never rename one once shipped, prefix screen-level ids with the screen name, and interpolate record keys into loop-generated ids.
8. Scrollbars must be visible. The theme ships 5px scrollbars with a near-invisible thumb (and hides some entirely), which makes scrollable panels unusable. app-overrides.css forces clearly visible, grabbable scrollbars everywhere (12px, contrasting thumb, light and dark variants) — never remove or override those rules, never use scrollbar-width: none or ::-webkit-scrollbar { display: none }, and never overflow: hidden on a content panel. Any fixed-height panel gets overflow-y: auto and must show its scrollbar when content overflows.
9. Cards are as tall as their content. Use plain class="card" (plus modifiers like border-top-0); never the theme's stretch / stretch-full / stretch-half height classes, which force height: 100% and leave forms and summaries with large empty space. Cards side by side may differ in height — that is expected.