# Component Catalog

The full design system at a glance: tokens, partials, and themed UI patterns. Every snippet is copy-paste ready.

## Design tokens

Defined in `src/styles/variables.scss` . SCSS color tokens drive Bootstrap's `--bs-*` custom properties. Layout/motion/radius/shadow scales live as CSS custom properties on `:root` — reference them via `var(--token-name)` .

### Color palette

Change a hex in `variables.scss` and Bootstrap regenerates every themed component.

--bs-primary
#20a8d8
--bs-success
#4dbd74
--bs-info
#63c2de
--bs-warning
#ffc107
--bs-danger
#f86c6b
--bs-secondary
#6c757d
--bs-dark
#272c33
--sidebar-bg
layout

### Radius scale

Corner-rounding tokens. Use `--radius-md` for cards and inputs, `--radius-lg` for modals and large surfaces, `--radius-pill` for tags.

sm
md
lg
xl
pill
circle

### Shadow scale

Layered elevation system. Cards default to `--shadow-sm` with a hover lift to `--shadow-md` . Modals/dropdowns use `--shadow-lg` .

xs
sm
md
lg
xl

### Motion scale

Three durations for interactive feedback.

`--transition-fast` | `150ms ease` | buttons, links, inputs
`--transition-base` | `200ms ease` | cards, layout shifts
`--transition-slow` | `300ms ease` | overlays, sidebar collapse
`--focus-ring` | `0 0 0 0.2rem rgba(32, 168, 216, 0.25)` — used on every interactive element's focus state

### stat-card

Colored summary card with a mini sparkline.

#### 10,468

Members online

#### 2,341

Sales today

    {{> stat-card color="primary" value="10,468" label="Members online"
        chartId="widgetChart1" chartValues="65,59,84,84,51,55,40"}}

Prop | Notes
--- | ---
`color` | `primary` , `danger` , `warning` , `success` , `info`
`value` | The big stat (e.g. "10,468")
`label` | Caption under the value
`chartId` | Unique DOM id for the canvas (consumed by widgets.js)
`chartValues` | Optional. Comma-separated numbers. Falls back to a built-in default keyed by render order.

### icon-stat-card

Compact stat with a circular icon — for sidebars and footers.
Total Profit

##### 1,012

New Customer

##### 961

Active Projects

##### 770

    {{> icon-stat-card color="success" icon="fa-dollar-sign"
        label="Total Profit" value="1,012"}}

### social-card

Social media card with brand background and two stats.

#### 40k

Friends

#### 450

Feeds

#### 40+

Contacts

#### 250

Feeds

    {{> social-card brand="facebook" iconClass="fab fa-facebook fa-3x"
        primaryValue="40k"  primaryLabel="Friends"
        secondaryValue="450" secondaryLabel="Feeds"}}

Brands: `facebook` , `twitter` , `x` , `linkedin` , `google` , `instagram` . Pass `iconHtml` instead of `iconClass` for inline SVG.

### Auth page shell

Used by login, register, and forgot-password pages. See `page-login.html` for a full example.

    <body class="auth-page">
      <main class="auth-card">
        <header class="auth-hero">
          <img class="auth-logo" src="...">
          <h1 class="auth-title">Welcome Back</h1>
          <p class="auth-subtitle">Sign in to your account</p>
        </header>
        <div class="auth-body">
          <form>
            <div class="form-floating">...</div>
            <button type="submit" class="auth-btn">Sign In</button>
            <div class="auth-divider">Or continue with</div>
            <div class="auth-social-row">
              <a href="#" class="auth-social-btn">...</a>
            </div>
          </form>
        </div>
        <footer class="auth-footer">...</footer>
      </main>
    </body>

Class | Purpose
--- | ---
`.auth-page` | Body class — gradient background, centers the card
`.auth-card` | The white card container with shadow
`.auth-hero` | Gradient header above the form (logo, title, subtitle)
`.auth-icon-circle` | Alternative to a logo — used on the forgot-password page
`.auth-body` | Form area
`.auth-btn` | Full-width brand-gradient submit button
`.auth-divider` | Text divider with horizontal lines
`.auth-social-row` | Container for `.auth-social-btn` social-login buttons
`.auth-message.is-success` `.auth-message.is-error` | Inline status message. Add `.is-visible` to show.
`.auth-password-strength` | Strength meter. Add `.is-weak` / `.is-medium` / `.is-strong` on the `.strength-fill` child.
`.auth-footer` | Footer area for cross-page links

### Error page shell

404, 500, etc. See `error-404.html` .

    <body class="error-page">
      <main class="error-card">
        <div class="error-illustration"><i class="fas fa-search"></i></div>
        <div class="error-number">404</div>
        <h1 class="error-title">Page Not Found</h1>
        <p class="error-message">...</p>

        <div class="error-suggestions">
          <h5>Things to try</h5>
          <ul><li>...</li></ul>
        </div>

        <div class="error-actions">
          <a href="/" class="btn-error btn-error-primary">Back home</a>
          <button class="btn-error btn-error-secondary">Go back</button>
        </div>
      </main>
    </body>

### Cards

Default `.card` ships rounded with hover lift; theme variants and helpers below.

#### Themed background variants

##### .bg-primary

Brand-primary surface.

##### .bg-success

Positive accent surface.

#### `.icon-circle` — colored circle for inline stats

#### Helpers

`.card-stretch` | min-height: 500px — keep cards in a row visually aligned
`.row-stretch` | min-height: 500px on a flex row
`.progress-thin` | 4px-tall progress bar — for inline metric strips

### Buttons

Bootstrap variants with the themed focus ring, plus `.btn-social` .

#### Theme buttons

#### `.btn-social.btn-{network}` — branded social buttons

Available networks: `facebook, x, twitter, linkedin, tiktok, youtube, discord, slack,` `snapchat, whatsapp, telegram, reddit, pinterest, twitch, github,` `spotify, instagram`

### Forms

Standard Bootstrap inputs picked up by the new theme. For declarative validation, mark with `data-validate` — the `FormValidator` component reads `data-rules` attributes on each field.
Email address
Select
Valid input
Required field

    <form data-validate>
      <input name="email" data-rules="required|email">
      <input name="age"   data-rules="required|numeric|min:18">
    </form>

### Layout & data attributes

Drop-in attributes that auto-wire components.

Attribute | What happens
--- | ---
`<table data-table>` | Sortable headers, search input, pagination
`<canvas data-chart="line|bar|pie|doughnut|radar|polarArea|area">` | Renders a Chart.js chart. Pass `data-labels` , `data-values` , `data-datasets` , `data-colors` . See `charts-chartjs.html` .
`<form data-validate>` | FormValidator reads `data-rules` on fields
`data-page="..."` | Drives sidebar active-state highlighting
`data-breadcrumb data-breadcrumb-title="..." data-breadcrumb-path="A|B|C"` | Renders the breadcrumb bar above the content area
`<div data-partial="sidebar" data-partial-replace="true">` | Runtime-injects the sidebar partial
`data-theme-toggle` | Element toggles light/dark via `ThemeManager.bindToggle()`

### Adding a new partial

1. Drop a new file in `src/components/your-partial.html` .
2. Use `{{prop}}` for HTML-escaped output, `{{{prop}}}` for raw HTML (inline SVG, etc.).
3. Reference it from any page: `{{> your-partial prop1="x" prop2="y"}}` .
4. If your partial has multi-line calls, add the consuming HTML to `.prettierignore` — Prettier reflows whitespace inside attribute values.
5. Add an entry to this catalog so it stays discoverable.

Theming: reference colors via `var(--bs-primary)` etc., never hardcode hexes. Use `--radius-*` / `--shadow-*` / `--transition-*` tokens for shape and motion.

Components that own page DOM (charts, tables, forms) should self-register in `App.COMPONENT_REGISTRY` with a CSS selector — see `src/scripts/app.js` .