# newhereicanlearn — Design Reference

> This describes the design system as it currently exists in the codebase — it is
> descriptive, not aspirational. It exists so future edits to templates/CSS reuse
> existing tokens and conventions instead of drifting from them.

## Overview

Built on **Bootstrap 5.3.2** with **Font Awesome 6.4.2** and **Bootstrap Icons 1.10.5**
loaded from CDN. Light/dark theme is driven entirely by CSS custom properties toggled
via the `data-bs-theme` attribute on `<html>` (see `static/js/theme-toggle.js`).
Custom CSS is intentionally small: `static/css/main.css` (site-wide) and
`static/css/reader.css` (Reader page only).

## Colors

All colors are defined as CSS custom properties in `static/css/main.css`, with a light
(default) set and a dark override under `[data-bs-theme="dark"]`.

| Token | Light | Dark |
|---|---|---|
| `--primary-color` | `#3498db` (blue) | `#00FFFF` (neon cyan) |
| `--secondary-color` | `#2980b9` | `#39FF14` (neon green) |
| `--background-color` | `#f8f9fa` | `#0D0D0D` |
| `--text-color` | `#333` | `#EDEDED` |
| `--border-color` | `#ddd` | `#333` |
| `--hover-color` | `#f1f7fc` | `#1A1A1A` |
| `--header-bg` | `#f2f6f9` | `#1A1A1A` |
| `--active-icon-color` | `#3498db` | `#00FFFF` |

Dark mode isn't just an inverted palette — it leans into a "neon" aesthetic (glowing
box-shadows on `.table-card`, `.navbar`, and text-shadow on `.card-title`), whereas
light mode is a flat, shadow-free blue theme.

Rule: **new UI should read colors from these variables**, not introduce new hex values.

## Typography

- Body font stack: `'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', sans-serif`
  (`main.css:31`) — no custom webfont is loaded.
- Otherwise relies on Bootstrap 5's default type scale (headings, `.lead`, etc.).
- Explicit overrides:
  - `.card-title` — 18px, weight 600, colored `--primary-color`.
  - `.panel-header h2` (Reader page) — 1rem, weight 600, colored `--primary-color`.
- Monospace (Reader's markdown editor) uses `'Courier New', monospace` (`reader.css:40`),
  not the design's regular font stack.

## Layout & Spacing

- Page content sits in Bootstrap's `.container` (from `base.html`), or `.container-narrow`
  (max-width 800px, `main.css:182`) for narrower reading contexts.
- `.dashboard-grid` — CSS grid, `repeat(auto-fit, minmax(500px, 1fr))`, 25px gap — used for
  card-based dashboard layouts.
- `#panels` (Reader page) — two-column CSS grid (`1fr 1fr`), collapsing to one column
  under 768px.
- Spacing is ad hoc (no documented 4px/8px base unit) — mostly Bootstrap's default spacing
  utilities plus one-off `padding`/`gap` values in `main.css`/`reader.css`.

## Components

- **Navbar** — rounded (`border-radius: 8px`), themed background (`--header-bg`), gets a
  colored box-shadow glow in dark mode (`main.css:105`). Active nav link marked via
  `.active-icon` on the icon only.
- **Cards** — `.table-card` (container) + `.card-header` + `.card-title` pattern used for
  dashboard-style content blocks; flat shadow in light mode, neon glow in dark mode.
- **Tables** — DataTables (jQuery + `jquery.dataTables` + `dataTables.bootstrap5`) for all
  sortable/searchable tables. Custom sort-arrow indicators (`▲`/`▼`) replace the default
  DataTables sort icons (`main.css:126-148`).
- **Buttons** — standard Bootstrap variants, plus `#themeToggle`
  (`btn btn-outline-secondary btn-sm`) for the light/dark switch.
- **Reader split-pane** (`reader.css`) — `.panel-card` / `.panel-header` / `#md-editor` /
  `#md-preview` / `#toolbar` implement a two-pane markdown editor+preview; preview styles
  (`h1`-`h6`, `code`, `pre`, `table`, `blockquote`, `img`) are scoped under `#md-preview`.
- **Flash messages** — Bootstrap `.alert` + `.alert-dismissible`, category mapped so
  `error` renders as `alert-danger`.
- **Form utility classes** (CSP hardening) — `.visually-hidden-input`, `.required-mark`,
  `.textarea-resizable`, `.card-title-wrap` exist specifically to replace inline
  `style=` attributes that were removed for CSP compliance. New form markup should use
  these (or add a new utility class) rather than reintroducing `style=`.

## Icons

- **Font Awesome** (`fa-solid`, `fa-brands`) — used throughout the navbar
  (`fa-user`, `fa-headphones`, `fa-youtube`, `fa-globe`, `fa-chart-bar`,
  `fa-magnifying-glass`, `fa-book-open`, etc.).
- **Bootstrap Icons** (`bi-*`) — used only for the theme toggle (`bi-sun-fill` /
  swapped to a moon icon by `theme-toggle.js`).

Both libraries are loaded on every page. This is a known duplication (see below), not
a deliberate two-system design.

## Motion

Two explicit transitions exist in the codebase:
- `.transition-icon` — 0.4s transform/opacity transition, with a `.spin` variant
  (360° rotation) used when the theme toggle switches icons.
- DataTables sort arrows — 0.3s opacity fade-in when a column becomes sorted.

No global motion/easing tokens are defined; Bootstrap's default component transitions
(collapse, alert dismiss, etc.) apply elsewhere.

## Accessibility

Already in place — preserve these when editing templates:
- Skip-to-content link (`<a href="#main-content" class="visually-hidden-focusable">`)
  as the first element in `<body>`.
- `aria-label` on the navbar toggle button and the theme toggle button.
- `aria-hidden="true"` on all decorative icons (nav icons, theme toggle icon).
- `main` landmark (`id="main-content"`) wraps page content.

## Known Inconsistencies (not fixed — flagged for later)

- `.text-purple` (`#6f42c1`), `.text-pink` (`#d63384`), `.text-brown` (`#8B4513`) in
  `main.css:15-17` are raw hex values, not tied to a CSS variable/token.
- Footer text color `#888` (`main.css:113`) is hardcoded rather than using
  `--text-color` or a dedicated muted-text token — it also doesn't adapt between
  light/dark mode.
- Both Font Awesome and Bootstrap Icons are loaded site-wide for a total of two icon
  fonts — no single icon system has been chosen.
- `templates/base.html` sets `og:site_name` twice (lines 51 and 59); the first value
  has trailing whitespace baked into the content string.

## Do's and Don'ts

**Do**
- Read colors from the existing CSS custom properties (`--primary-color`, etc.).
- Add both a light and a dark value whenever introducing a new color token.
- Reuse the existing utility classes (`.container-narrow`, `.card-title-wrap`, etc.)
  before adding inline styles.
- Keep `aria-label`/`aria-hidden` on interactive icons and buttons.

**Don't**
- Don't hardcode new hex colors in templates or CSS — use a variable, or add one.
- Don't reintroduce inline `style="..."` attributes — this site was deliberately
  cleaned up for CSP compliance; add a utility class instead.
- Don't add a third icon library — pick from Font Awesome or Bootstrap Icons
  (Font Awesome for content/nav icons, Bootstrap Icons is currently only used for the
  theme toggle).