ultimate-jekyll-manager 1.4.3 → 1.5.0

package/dist/assets/themes/neobrutalism/README.md

@@ -0,0 +1,98 @@
+# Neobrutalism Theme
+
+A bold, high-contrast UJM theme built on the neobrutalist design language:
+**pure-ink borders, hard offset shadows (no blur), zero border-radius, chunky
+grotesk display type, and flat saturated color blocks.** Buttons and cards
+"press" into the page on interaction. Full light + dark mode support.
+
+> See [`docs/themes.md`](../../../../docs/themes.md) for how the theme system
+> works and how to author your own theme (inside UJM or in a consumer project).
+
+## Use it
+
+In your consuming project's `src/_config.yml`:
+
+```yaml
+theme:
+  id: "neobrutalism"
+  appearance: "light"   # or "dark" / "system"
+```
+
+That's it — every layout, nav, footer, and page is inherited from the shared
+defaults (via the Classy layout fallback) and restyled in neobrutalist form.
+
+## Customize it (without editing the theme)
+
+All design tokens are `!default` variables. Override them **before** the theme
+is imported — in your project's `src/assets/css/main.scss`, set the variables,
+then `@use 'ultimate-jekyll-manager' as *;`:
+
+```scss
+// Change the accent + structure, then import the framework (which loads the theme)
+$primary:           #FF5C00;   // your brand color
+$nb-border-width:   4px;       // chunkier borders
+$nb-shadow-offset:  7px;       // deeper hard shadow
+$nb-accent-yellow:  #D4FF00;   // swap the signature highlight
+
+@use 'ultimate-jekyll-manager' as *;
+```
+
+### Key tokens (see `_config.scss` for the full list)
+
+| Token | Purpose | Default |
+|---|---|---|
+| `$primary` … `$danger` | Bootstrap semantic colors | electric blue, hot pink, etc. |
+| `$nb-ink` / `$nb-paper` | Border/shadow color + page surface (light) | `#111` / `#FFFEF2` |
+| `$nb-ink-dark` / `$nb-paper-dark` | Same, dark mode | `#F5F5F5` / `#16161A` |
+| `$nb-border-width` | Standard border thickness | `3px` |
+| `$nb-shadow-offset` | Hard shadow distance | `5px` |
+| `$nb-accent-*` | Color-block palette | blue/pink/yellow/green/purple/orange |
+| `$nb-font-display` | Heading font | `Archivo` |
+| `$font-family-sans-serif` | Body font | `Space Grotesk` |
+
+> Fonts are loaded via the theme's `head` block in the base layout. If you
+> change the font tokens, update the Google Fonts `<link>` accordingly (in your
+> page/layout `theme.head.content`, or by overriding the base layout).
+
+## No theme-prefixed classes
+
+This theme deliberately uses **NO `nb-` prefixed classes in markup** — so the same
+HTML is swappable across themes (change `theme.id`, done). It styles:
+
+- **Standard Bootstrap classes** wherever they fit: `.card` (the canonical container —
+  gets the ink frame + hard shadow), `.btn` / `.btn-primary` / `.btn-warning` (yellow
+  accent), `.text-bg-{primary,secondary,success,warning,…}` (the color-block fills),
+  `.border`, `.shadow`, `.accordion`, `.badge`.
+- **Universal semantic layout classes** for structures with no Bootstrap equivalent:
+  `.section-hero`, `.hero-title`, `.action-block`, `.logo-strip`, `.showcase-row`,
+  `.step-card`, `.stat-block`, `.cta-panel`, `.pricing-plan`, `.billing-toggle`,
+  `.kicker`, `.highlight`. Any theme can style these same names. See
+  [docs/themes.md → Universal layout classes](../../../../docs/themes.md).
+
+The `nb-` prefix survives ONLY on SCSS internals (the `$nb-*` config tokens, `--nb-*`
+CSS variables, and `@mixin nb-border/nb-shadow/nb-press`) — these never appear in HTML.
+
+## Structure
+
+```
+neobrutalism/
+├── _config.scss          ← all customizable tokens (!default) + Bootstrap forward
+├── _theme.scss           ← entry point (config → mixins → root → base → layout → components → bootstrap overrides)
+├── _theme.js             ← JS entry (Bootstrap UMD + behaviors on DOM ready)
+├── css/
+│   ├── base/
+│   │   ├── _mixins.scss   ← nb-border / nb-shadow / nb-press (the SSOT for the look)
+│   │   ├── _root.scss     ← SCSS → CSS-variable bridge (light/dark)
+│   │   ├── _typography.scss
+│   │   └── _utilities.scss
+│   ├── layout/
+│   │   ├── _general.scss  ← sections, hero, footer, gradient/accent overrides
+│   │   └── _navigation.scss
+│   └── components/
+│       ├── _buttons.scss
+│       ├── _cards.scss
+│       └── _forms.scss
+└── js/
+    ├── navbar-scroll.js
+    └── initialize-tooltips.js
+```

package/dist/assets/themes/neobrutalism/_config.scss

@@ -0,0 +1,139 @@
+// Neobrutalism Theme Configuration
+// ALL customizable variables are defined here with !default.
+// Consuming projects override any of these BEFORE the theme is imported.
+//
+// Design language: raw, high-contrast color blocks; pure-black hard borders;
+// hard offset shadows (no blur); zero border-radius; chunky grotesk type.
+// This is NOT a recolored Classy — the shadow/border/press system is the identity.
+
+// ============================================
+// Bootstrap Color Overrides
+// ============================================
+// Loud, saturated, high-contrast. These map onto Bootstrap's semantic colors.
+$primary:    #2563EB !default;   // electric blue
+$secondary:  #EC4899 !default;   // hot pink
+$success:    #16A34A !default;   // grass green
+$info:       #06B6D4 !default;   // cyan
+$warning:    #FACC15 !default;   // acid yellow
+$danger:     #EF4444 !default;   // red
+$light:      #FFFEF2 !default;   // paper white (warm off-white)
+$dark:       #111111 !default;   // near-black
+
+// ============================================
+// Ink & Paper (the structural neutrals)
+// ============================================
+// "Ink" = the universal border/shadow color. "Paper" = the page surface.
+$nb-ink:            #111111 !default;   // borders + hard shadows (light mode)
+$nb-paper:          #FFFEF2 !default;   // body background (light mode)
+$nb-surface:        #FFFFFF !default;   // cards / elevated surfaces (light mode)
+$nb-surface-alt:    #F4F1E4 !default;   // alt sections / wells (light mode)
+
+// Dark mode counterparts
+$nb-ink-dark:       #F5F5F5 !default;   // borders + shadows become near-white
+$nb-paper-dark:     #16161A !default;   // body background (dark mode)
+$nb-surface-dark:   #1F1F25 !default;   // cards (dark mode)
+$nb-surface-alt-dark: #25252D !default; // alt sections (dark mode)
+
+// ============================================
+// Accent Palette (for color-block sections, tags, highlights)
+// ============================================
+// Used directly as section backgrounds and decorative blocks.
+$nb-accent-blue:    #2563EB !default;
+$nb-accent-pink:    #EC4899 !default;
+$nb-accent-yellow:  #FACC15 !default;
+$nb-accent-green:   #16A34A !default;
+$nb-accent-purple:  #8B5CF6 !default;
+$nb-accent-orange:  #FB923C !default;
+
+// ============================================
+// Borders — the defining structural element
+// ============================================
+$nb-border-width:     3px !default;          // standard border thickness
+$nb-border-width-lg:  4px !default;          // emphasis (hero buttons, feature cards)
+$nb-border-width-sm:  2px !default;          // small controls (inputs, tags)
+$nb-border-color:     $nb-ink !default;      // remapped to ink-dark in dark mode via _root
+$nb-border:           $nb-border-width solid $nb-border-color !default;
+
+// Zero radius everywhere — this is the neobrutalist signature.
+$border-radius:     0 !default;
+$border-radius-sm:  0 !default;
+$border-radius-lg:  0 !default;
+$border-radius-xl:  0 !default;
+$border-radius-2xl: 0 !default;
+$border-radius-pill: 0 !default;
+
+// ============================================
+// Hard Offset Shadows — the second defining element
+// ============================================
+// No blur, no spread — a solid block offset down-right in ink color.
+$nb-shadow-offset:     5px !default;   // default offset distance
+$nb-shadow-offset-sm:  3px !default;
+$nb-shadow-offset-lg:  8px !default;
+$nb-shadow-color:      $nb-ink !default;  // remapped in dark mode via _root
+
+$nb-shadow-sm: $nb-shadow-offset-sm $nb-shadow-offset-sm 0 $nb-shadow-color !default;
+$nb-shadow:    $nb-shadow-offset    $nb-shadow-offset    0 $nb-shadow-color !default;
+$nb-shadow-lg: $nb-shadow-offset-lg $nb-shadow-offset-lg 0 $nb-shadow-color !default;
+
+// ============================================
+// Typography
+// ============================================
+// Chunky geometric grotesk for display; clean grotesk for body.
+$font-family-sans-serif: 'Space Grotesk', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif !default;
+$nb-font-display: 'Archivo', 'Space Grotesk', sans-serif !default;
+$nb-font-mono: 'Space Mono', ui-monospace, SFMono-Regular, Menlo, monospace !default;
+
+$headings-font-weight: 800 !default;
+$nb-heading-letter-spacing: -0.02em !default;
+$font-weight-bold: 700 !default;
+
+// ============================================
+// Motion — snappy, mechanical, no easing softness
+// ============================================
+// Neobrutalism favors instant/linear motion over smooth cubic-beziers.
+$nb-transition-fast: all 0.08s ease-out !default;
+$nb-transition:      all 0.12s ease-out !default;
+
+// ============================================
+// Component Sizing
+// ============================================
+// Avatar sizes map (matches Classy so shared layouts/includes render correctly)
+$avatar-sizes: (
+  null: 3rem,
+  2xs: 0.5rem,
+  xs: 1.5rem,
+  sm: 2rem,
+  md: 2.5rem,
+  lg: 3.5rem,
+  xl: 5rem,
+  2xl: 7.5rem,
+  3xl: 10rem,
+  4xl: 12.5rem,
+  5xl: 15rem
+) !default;
+
+// ============================================
+// Forward Bootstrap with our configuration
+// ============================================
+@forward '../bootstrap/scss/bootstrap.scss' with (
+  $primary: $primary,
+  $secondary: $secondary,
+  $success: $success,
+  $info: $info,
+  $warning: $warning,
+  $danger: $danger,
+  $light: $light,
+  $dark: $dark,
+  $font-family-sans-serif: $font-family-sans-serif,
+  $headings-font-weight: $headings-font-weight,
+  $font-weight-bold: $font-weight-bold,
+  $border-radius: $border-radius,
+  $border-radius-sm: $border-radius-sm,
+  $border-radius-lg: $border-radius-lg,
+  // Neobrutalism uses solid borders everywhere, so Bootstrap's default
+  // border width is bumped and box-shadow softness is disabled.
+  $border-width: $nb-border-width,
+  $enable-rounded: false,
+  $enable-shadows: false,
+  $enable-negative-margins: true
+);

package/dist/assets/themes/neobrutalism/_theme.js

@@ -0,0 +1,27 @@
+// Neobrutalism Theme — JS entry point
+// Loaded at runtime via webpack's __theme__ alias (import('__theme__/_theme.js')).
+// Exposes Bootstrap globally and wires up theme behaviors on DOM ready.
+import bootstrap from '__main_assets__/themes/bootstrap/js/index.umd.js';
+import { ready as domReady } from 'web-manager/modules/dom.js';
+
+// Make Bootstrap available globally (used by UJM utilities + components)
+window.bootstrap = bootstrap;
+
+/* @dev-only:start */
+{
+  console.log('Neobrutalism theme loaded successfully (assets/themes/neobrutalism/_theme.js)');
+}
+/* @dev-only:end */
+
+// Theme behaviors
+import setupNavbarScroll from './js/navbar-scroll.js';
+import initializeTooltips from './js/initialize-tooltips.js';
+
+// Initialize when DOM is ready
+domReady().then(() => {
+  // Neobrutalism behaviors
+  setupNavbarScroll();
+
+  // Generic Bootstrap initializations
+  initializeTooltips();
+});

package/dist/assets/themes/neobrutalism/_theme.scss

@@ -0,0 +1,33 @@
+// Neobrutalism Theme — SCSS entry point
+// Forwards config (so consuming projects can override vars), loads Bootstrap via
+// config, then layers the neobrutalist system on top. Import order matters:
+// config → mixins → root vars → base → layout → components → bootstrap overrides.
+
+// Forward theme configuration (allows consuming project to override)
+@forward 'config';
+@use 'config' as *;
+
+// Mixins must be available to every partial below.
+// @import (not @use) so the mixins land in the global scope the @imports share.
+@import 'css/base/mixins';
+
+// CSS custom properties (light/dark bridge)
+@import 'css/base/root';
+
+// Base styles
+@import 'css/base/typography';
+@import 'css/base/utilities';
+
+// Layout styles
+@import 'css/layout/general';
+@import 'css/layout/navigation';
+
+// Component styles
+@import 'css/components/buttons';
+@import 'css/components/cards';
+@import 'css/components/forms';
+@import 'css/components/infinite-scroll';
+
+// Universal Bootstrap overrides (shared across all UJ themes).
+// Must come AFTER Bootstrap is loaded via config to use @extend.
+@import '../bootstrap/overrides';

package/dist/assets/themes/neobrutalism/css/base/_mixins.scss

@@ -0,0 +1,46 @@
+// Neobrutalism Theme — Mixins
+// The shared building blocks of the neobrutalist look. Components @include these
+// so the border/shadow/press system lives in ONE place (SSOT) rather than being
+// copy-pasted across buttons, cards, inputs, etc.
+
+// Hard border in the current ink color.
+@mixin nb-border($width: var(--nb-border-width)) {
+  border: $width solid var(--nb-border-color);
+}
+
+// Hard offset shadow (no blur). $size: sm | md | lg.
+@mixin nb-shadow($size: md) {
+  @if $size == sm {
+    box-shadow: var(--nb-shadow-sm);
+  } @else if $size == lg {
+    box-shadow: var(--nb-shadow-lg);
+  } @else {
+    box-shadow: var(--nb-shadow);
+  }
+}
+
+// The signature interaction: the element sits on a hard offset shadow, then
+// "presses" toward the page on hover/active. THE INVARIANT: the element's
+// translate distance + the shrunk shadow offset must always equal the RESTING
+// shadow offset, so the bottom-right edge stays perfectly pinned (the face and
+// shadow line up exactly when the press completes — no drift).
+//
+// $rest = the element's resting shadow offset. Pass the SAME size you gave
+// nb-shadow() (default 5px = md; pass $nb-shadow-offset-lg for lg-shadow elements).
+@mixin nb-press($rest: $nb-shadow-offset) {
+  transition: $nb-transition;
+
+  // Hover: press ~40% of the way in. shadow = rest - translate (stays pinned).
+  &:hover {
+    $hover-move: round($rest * 0.4);
+    $hover-shadow: $rest - $hover-move;
+    transform: translate($hover-move, $hover-move);
+    box-shadow: #{$hover-shadow} #{$hover-shadow} 0 var(--nb-shadow-color);
+  }
+
+  // Active: press fully in. translate == rest, shadow collapses to 0 → flush.
+  &:active {
+    transform: translate($rest, $rest);
+    box-shadow: 0 0 0 var(--nb-shadow-color);
+  }
+}

package/dist/assets/themes/neobrutalism/css/base/_root.scss

@@ -0,0 +1,80 @@
+// Neobrutalism Theme — CSS Custom Properties
+// Bridges SCSS config into runtime CSS variables so light/dark mode switching
+// works without recompilation. Components read these var(--nb-*) tokens, never
+// the raw SCSS values, so dark mode is a single block of overrides.
+
+// ============================================
+// Light Mode (default)
+// ============================================
+:root,
+[data-bs-theme="light"] {
+  // Structural tokens
+  --nb-ink: #{$nb-ink};
+  --nb-paper: #{$nb-paper};
+  --nb-surface: #{$nb-surface};
+  --nb-surface-alt: #{$nb-surface-alt};
+
+  // Height of the fixed navbar — the first section adds this to its top padding
+  // so content clears the overlapping nav (see _general.scss "Section rhythm").
+  --nb-navbar-height: 4.5rem;
+
+  // Border + shadow color follow the ink
+  --nb-border-color: var(--nb-ink);
+  --nb-shadow-color: var(--nb-ink);
+
+  // Border + shadow recipes (used by components)
+  --nb-border-width: #{$nb-border-width};
+  --nb-border: #{$nb-border-width} solid var(--nb-border-color);
+  --nb-shadow-sm: #{$nb-shadow-offset-sm} #{$nb-shadow-offset-sm} 0 var(--nb-shadow-color);
+  --nb-shadow: #{$nb-shadow-offset} #{$nb-shadow-offset} 0 var(--nb-shadow-color);
+  --nb-shadow-lg: #{$nb-shadow-offset-lg} #{$nb-shadow-offset-lg} 0 var(--nb-shadow-color);
+
+  // Accent palette (for color-block sections)
+  --nb-accent-blue: #{$nb-accent-blue};
+  --nb-accent-pink: #{$nb-accent-pink};
+  --nb-accent-yellow: #{$nb-accent-yellow};
+  --nb-accent-green: #{$nb-accent-green};
+  --nb-accent-purple: #{$nb-accent-purple};
+  --nb-accent-orange: #{$nb-accent-orange};
+
+  // INTERACTIVE accent — the single token every hover/active fill points at
+  // (nav links, footer links, dropdown items, body links, mobile toggler). It
+  // tracks the rendered primary blue (--bs-primary), NOT the yellow signature
+  // accent. Retune all interactive states from this one line. Yellow stays
+  // reserved for static signature blocks (kicker, highlight, hero, badges).
+  --nb-accent-interactive: var(--bs-primary);
+  --nb-accent-interactive-ink: #ffffff; // readable text on the interactive fill
+
+  // Map onto Bootstrap surfaces
+  --bs-body-bg: #{$nb-paper};
+  --bs-body-bg-rgb: #{red($nb-paper)}, #{green($nb-paper)}, #{blue($nb-paper)};
+  --bs-body-color: #{$nb-ink};
+  --bs-secondary-bg: #{$nb-surface};
+  --bs-tertiary-bg: #{$nb-surface-alt};
+  --bs-border-color: var(--nb-ink);
+  --bs-card-bg: #{$nb-surface};
+  --bs-emphasis-color: #{$nb-ink};
+}
+
+// ============================================
+// Dark Mode
+// ============================================
+// Ink flips to near-white: borders and hard shadows become light on dark paper.
+[data-bs-theme="dark"] {
+  --nb-ink: #{$nb-ink-dark};
+  --nb-paper: #{$nb-paper-dark};
+  --nb-surface: #{$nb-surface-dark};
+  --nb-surface-alt: #{$nb-surface-alt-dark};
+
+  --nb-border-color: var(--nb-ink);
+  --nb-shadow-color: var(--nb-ink);
+
+  --bs-body-bg: #{$nb-paper-dark};
+  --bs-body-bg-rgb: #{red($nb-paper-dark)}, #{green($nb-paper-dark)}, #{blue($nb-paper-dark)};
+  --bs-body-color: #{$nb-ink-dark};
+  --bs-secondary-bg: #{$nb-surface-dark};
+  --bs-tertiary-bg: #{$nb-surface-alt-dark};
+  --bs-border-color: var(--nb-ink);
+  --bs-card-bg: #{$nb-surface-dark};
+  --bs-emphasis-color: #{$nb-ink-dark};
+}

package/dist/assets/themes/neobrutalism/css/base/_typography.scss

@@ -0,0 +1,77 @@
+// Neobrutalism Theme — Typography
+// Chunky, confident, tightly-tracked headings; clean grotesk body.
+// Fonts are loaded via the theme's `head` block in base.html (Google Fonts),
+// NOT @import-ed here, to avoid render-blocking duplicate loads.
+
+body {
+  font-family: $font-family-sans-serif;
+  font-weight: 400;
+  -webkit-font-smoothing: antialiased;
+}
+
+h1, h2, h3, h4, h5, h6,
+.h1, .h2, .h3, .h4, .h5, .h6 {
+  font-family: $nb-font-display;
+  font-weight: $headings-font-weight;
+  letter-spacing: $nb-heading-letter-spacing;
+  line-height: 1.05;
+  text-wrap: balance;
+}
+
+// Display headings get extra weight + tighter tracking
+.display-1, .display-2, .display-3, .display-4, .display-5, .display-6 {
+  font-family: $nb-font-display;
+  font-weight: 900;
+  letter-spacing: -0.03em;
+  line-height: 0.98;
+}
+
+// Monospace accents (kickers, labels, code-ish tags)
+.font-mono,
+code, kbd, samp, pre {
+  font-family: $nb-font-mono;
+}
+
+// Eyebrow / kicker label — universal "section kicker" above headlines.
+.kicker {
+  display: inline-block;
+  font-family: $nb-font-mono;
+  font-weight: 700;
+  font-size: 0.8rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  padding: 0.35rem 0.65rem;
+  background: var(--nb-accent-yellow);
+  color: #111111;
+  @include nb-border($nb-border-width-sm);
+
+  // On a dark/ink panel (e.g. the CTA), keep the accent block readable.
+  &--invert { background: var(--nb-accent-yellow); color: #111111; }
+}
+
+// Highlighted inline text — marker-style background swipe.
+.highlight {
+  background: var(--nb-accent-yellow);
+  color: #111111;
+  padding: 0 0.15em;
+  box-decoration-break: clone;
+  -webkit-box-decoration-break: clone;
+}
+
+// Links: bold, underlined, no fade — they look clickable and stay readable in both
+// modes. Hover shifts to the interactive accent (blue), matching every other hover
+// in the theme. Buttons/nav/dropdown/footer links opt out of this generic rule via
+// their own higher-specificity hover, so this only catches plain in-content links.
+a {
+  font-weight: 600;
+  text-underline-offset: 0.15em;
+  text-decoration-thickness: 2px;
+
+  &:hover { color: var(--nb-accent-interactive); }
+}
+
+// Buttons are <a> too, but set their text via --bs-btn-color. A direct `color` on
+// `a:hover` would beat that var and turn button labels blue — exclude them so the
+// button keeps its own (frozen) text color. Nav/dropdown/footer links already win
+// on specificity with their explicit white hover, so they need no guard here.
+a.btn:hover { color: var(--bs-btn-color); }

package/dist/assets/themes/neobrutalism/css/base/_utilities.scss

@@ -0,0 +1,25 @@
+// Neobrutalism Theme — Base
+// Body surface + neobrutalist treatment of Bootstrap's accent-block utilities.
+// No theme-prefixed classes: the look comes from restyling STANDARD classes
+// (.text-bg-*, .border, .shadow, .card) so markup stays swappable across themes.
+
+// Body surface
+body {
+  background-color: var(--nb-paper);
+  color: var(--bs-body-color);
+}
+
+// ============================================
+// Accent blocks: .text-bg-* (Bootstrap) get the hard neobrutalist edge when
+// used as full-bleed section/decorative blocks. Bootstrap already sets the
+// background + a readable contrast color; we just square the corners.
+// (Borders/shadows are added per-component where needed, e.g. .showcase-num.)
+// ============================================
+.text-bg-primary,
+.text-bg-secondary,
+.text-bg-success,
+.text-bg-info,
+.text-bg-warning,
+.text-bg-danger {
+  border-radius: 0;
+}

package/dist/assets/themes/neobrutalism/css/components/_buttons.scss

@@ -0,0 +1,148 @@
+// Neobrutalism Theme — Buttons
+// Every button is a hard-bordered block sitting on an offset shadow that
+// "presses" into the page on interaction. This restyles Bootstrap's own
+// .btn / .btn-* classes so all existing markup (nav CTAs, hero buttons,
+// forms) inherits the look with zero HTML changes.
+
+.btn {
+  font-family: $nb-font-display;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  border-radius: 0;
+  @include nb-border();
+  @include nb-shadow(md);
+  text-transform: none;
+  padding: 0.6rem 1.25rem;
+}
+
+// Press EXACTLY like the stat cards. These use the DOUBLED `.btn.btn` selector
+// (specificity 0,2,0) on purpose: every theme page bundle re-emits Bootstrap's own
+// `.btn { transition: color … }` and `.btn:hover` (because page SCSS @forwards
+// Bootstrap), and those load AFTER the main bundle. The doubled class beats them so
+// the press is pure transform+shadow with the stat-card timing — no color flash, no
+// focus-ring fighting the offset shadow.
+.btn.btn {
+  // Same transition the stat cards use → identical feel.
+  @include nb-press();
+
+  // Focus shows an OUTLINE ring (outside the box, never conflicts with the offset
+  // shadow). No focus box-shadow — that was the "flash of border".
+  &:focus { outline: 0; }
+  &:focus-visible {
+    outline: 3px solid var(--nb-border-color);
+    outline-offset: 3px;
+  }
+}
+
+.btn {
+
+  // Bootstrap adds a subtle border-color per-variant; force ink so the
+  // signature black/white frame is consistent across every color.
+  // (btn-adaptive / -inverse are the mode-flipping solids used by the nav CTA,
+  // auth buttons, etc. — they MUST be in this list or they'd keep Bootstrap's
+  // default "darken on hover" and feel different from every other button.)
+  &.btn-primary,
+  &.btn-secondary,
+  &.btn-success,
+  &.btn-info,
+  &.btn-warning,
+  &.btn-danger,
+  &.btn-light,
+  &.btn-dark,
+  &.btn-adaptive,
+  &.btn-adaptive-inverse {
+    border-color: var(--nb-border-color);
+    --bs-btn-hover-border-color: var(--nb-border-color);
+    --bs-btn-active-border-color: var(--nb-border-color);
+  }
+
+  // 3. SOLID buttons: freeze hover/active fill to the resting color so the press is
+  //    pure transform+shadow (no color shift) — exactly the stat-card feel. Outline
+  //    buttons are intentionally EXCLUDED so they keep their fill-on-hover.
+  //    Freezing to `var(--bs-btn-bg)` works in BOTH modes automatically because the
+  //    adaptive classes already set --bs-btn-bg per light/dark.
+  &.btn-primary,   &.btn-secondary, &.btn-success,
+  &.btn-info,      &.btn-warning,   &.btn-danger,
+  &.btn-light,     &.btn-dark,
+  &.btn-adaptive,  &.btn-adaptive-inverse {
+    --bs-btn-hover-bg: var(--bs-btn-bg);
+    --bs-btn-hover-color: var(--bs-btn-color);
+    --bs-btn-active-bg: var(--bs-btn-bg);
+    --bs-btn-active-color: var(--bs-btn-color);
+  }
+}
+
+// btn-adaptive / -inverse RESTING fill. The global _buttons-adaptive.scss sets these
+// via `.btn-adaptive` (0,1,0), but Bootstrap's own `.btn { --bs-btn-bg: transparent }`
+// re-emission can tie/beat it on order, leaving the button transparent. Restate the
+// resting fill here at `.btn.btn-adaptive` (0,2,0) so it always wins — same trick the
+// press uses. Mode-flip handled by pairing with [data-bs-theme="dark"].
+.btn.btn-adaptive {
+  --bs-btn-color: #fff;
+  --bs-btn-bg: var(--bs-dark);
+  --bs-btn-border-color: var(--nb-border-color);
+}
+[data-bs-theme="dark"] .btn.btn-adaptive {
+  --bs-btn-color: #000;
+  --bs-btn-bg: var(--bs-light);
+}
+.btn.btn-adaptive-inverse {
+  --bs-btn-color: #000;
+  --bs-btn-bg: var(--bs-light);
+  --bs-btn-border-color: var(--nb-border-color);
+}
+[data-bs-theme="dark"] .btn.btn-adaptive-inverse {
+  --bs-btn-color: #fff;
+  --bs-btn-bg: var(--bs-dark);
+}
+
+// Size variants keep the chunky proportions
+.btn-lg {
+  padding: 0.85rem 1.75rem;
+  font-size: 1.1rem;
+  @include nb-border($nb-border-width-lg);
+}
+
+.btn-sm {
+  padding: 0.35rem 0.8rem;
+  font-size: 0.85rem;
+}
+
+// Outline buttons: transparent fill, ink frame, fill-on-hover (no fade)
+[class*="btn-outline-"] {
+  background: transparent;
+  border-color: var(--nb-border-color);
+  color: var(--bs-body-color);
+
+  &:hover {
+    color: #111111;
+  }
+}
+.btn-outline-primary:hover { background: $primary; }
+.btn-outline-secondary:hover { background: $secondary; }
+.btn-outline-success:hover { background: $success; }
+.btn-outline-danger:hover { background: $danger; }
+.btn-outline-warning:hover { background: $warning; }
+.btn-outline-info:hover { background: $info; }
+
+// Link-style button stays flat (no border/shadow) but bold + underlined
+.btn-link {
+  border: 0;
+  box-shadow: none;
+  font-weight: 700;
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+
+  &:hover,
+  &:active {
+    transform: none;
+    box-shadow: none;
+  }
+}
+
+// NOTE: There are intentionally NO theme-specific accent button classes
+// (e.g. .btn-nb-yellow). Themes must restyle the STANDARD Bootstrap button
+// classes so the same markup works across themes (swap theme.id, done). Need a
+// yellow CTA? Use `.btn-warning` ($warning is the acid-yellow accent). Need other
+// accents? Use `.btn-primary` / `.btn-success` / etc. The base `.btn` rule above
+// already gives every variant the neobrutalist border + offset shadow + press.