# Aether UI — Design System Style Guidelines
> **Version:** 1.0 (2026-03-06)
> **Author:** One Sky IT / Scott Idem
> **Scope:** All Aether SvelteKit frontend components
> **Related:** `AE__UI_Component_Patterns.md`, `ae-firefly.css`, `documentation/AE__Components.md`

---

## 1. Design Philosophy

**"Shiny serenity, like a firefly."**

The Aether UI is calm, focused, and softly luminous. It must be immediately readable under conference-room lighting, at a glance, by presenters who are nervous and in a hurry. Staff in the Speaker Ready Room need scan-speed identity confirmation. Remote presenters uploading files from home need a clear, unambiguous interface that doesn't waste their time.

Core principles:
- **Identity first.** The user's first question is always *"Am I in the right place?"* Answer it with the hero card — name, time, room — before anything else is shown.
- **Progressive disclosure.** Admin fields (codes, IDs, passcodes) are hidden unless `edit_mode` is active.
- **Theme-aware always.** Zero hardcoded colors. Every background, border, and text color must respond to light/dark mode and the active theme via CSS variables.
- **Transitions, not pops.** Every interactive state change is smoothed with `transition-colors duration-200`.
- **Section 508 / WCAG 2.1 AA** compliance is non-negotiable. Contrast ratios, focus indicators, ARIA labels, and screen-reader regions are required everywhere.

---

## 2. The AE_Firefly Theme

**App default since 2026-03-06.** Set in `ae_stores.ts` as `theme_name = 'AE_Firefly'`.
File: `src/ae-firefly.css` | Activated by: `data-theme="AE_Firefly"`

| Role | Palette Name | Hue | Use Case |
|---|---|---|---|
| **Primary** | Luminescent Teal | ~184° | Primary actions, date/time chips, focus rings, anchor links |
| **Secondary** | Warm Amber-Gold | ~90° | Secondary actions, copy/email buttons, soft highlights |
| **Tertiary** | Night-Sky Indigo | ~277° | Location/room chips, depth accents |
| **Surface** | Moonlit Slate | ~215–233° | All backgrounds — off-white (light) → midnight slate (dark) |
| **Warning** | Amber semantic | n/a | Disabled/inactive records, "no results" states, code badges |
| **Success** | Green semantic | n/a | Active/complete states, file count badges |
| **Error** | Red semantic | n/a | Errors, disabled-presenter states |

### Contrast Guarantees
- Body text (`surface-950` on `surface-50`): > 15:1 in light mode ✓
- Primary buttons: ≥ 3:1 for interactive component threshold ✓
- Designed using OKLCH perceptual lightness — not HSL estimates

---

## 3. Color Token Rules

### ✅ Always Use Theme Tokens

**Backgrounds / surfaces:**
```
bg-surface-50-900      ← card faces (light: near-white, dark: deep slate)
bg-surface-100-900     ← inner sections, code blocks, secondary panels
bg-surface-50-950      ← page-level containers
bg-surface-200-800     ← skeleton pulse placeholders, dividers
```

**Borders:**
```
border-surface-200-800  ← standard card/panel borders
border-primary-500      ← focus rings (via focus-visible:ring)
border-warning-500      ← warning/caution interactive zones
border-surface-500/20   ← subtle section dividers
```

**Primary color accents (teal):**
```
bg-primary-500/10       ← tinted chip background (time chips)
text-primary-700 dark:text-primary-300  ← chip text with auto dark mode
hover:text-primary-500  ← link hover color
```

**Tertiary color accents (indigo):**
```
bg-tertiary-500/10      ← tinted chip background (room/location chips)
text-tertiary-700 dark:text-tertiary-300
```

**Skeleton presets:**
```
preset-tonal-warning    ← "no results", disabled rows, code tag badges
preset-tonal-primary    ← primary action buttons
preset-tonal-surface    ← neutral/secondary actions, status badges
preset-tonal-success    ← success states, file count badges
preset-tonal-error      ← error/blocked states
preset-filled-*-500     ← solid-fill buttons (hover state for tonal)
```

**Warning/error semantic backgrounds:**
```
bg-warning-100 border border-warning-300  ← inline warning banners
bg-error-100 border border-error-300      ← inline error banners
```

---

### ❌ Never Use These

| Forbidden | Reason | Replace With |
|---|---|---|
| `bg-gray-*` | Fixed color, breaks dark mode | `bg-surface-*` tokens |
| `bg-neutral-*` | Same — fixed hue | `bg-surface-*` tokens |
| `bg-white` | Light-mode only | `bg-surface-50-900` |
| `text-gray-*` | Breaks dark mode | `opacity-60` on inherited text |
| `text-neutral-*` | Same | `opacity-*` |
| `border-gray-*` | Non-theme border | `border-surface-200-800` |
| `bg-yellow-*`, `text-yellow-*` | Bypasses warning semantic | `preset-tonal-warning` |
| `bg-red-*`, `text-red-*` | Bypasses error semantic | `bg-error-100` / `preset-tonal-error` |
| `bg-white dark:bg-gray-800` | Manual light/dark pair | Let theme tokens handle it — remove entirely |
| `text-gray-600 dark:text-gray-400` | Manual light/dark pair | `opacity-60` |
| `rounded-container-token` | Skeleton v3 class | `rounded-xl` |
| `variant-soft-*` | Skeleton v3 class | `preset-tonal-*` |
| `variant-ghost-*` | Skeleton v3 class | `preset-ghost-*` |
| `variant-ringed-*` | Skeleton v3 class | `preset-outlined-*` |
| `variant-filled-*` | Skeleton v3 class | `preset-filled-*` |
| `preset-filled-surface-300-700` | v3 dual-shade notation | `bg-surface-200-800` or `bg-surface-100-900` |
| `preset-filled-surface-400-600` | v3 dual-shade notation | `bg-surface-100-900` |
| `overflow-x-scroll` | Forces scrollbar visible | `overflow-x-auto` |

---

## 4. Skeleton v3 → v4 Migration Reference

The app uses **Skeleton v4**. v3 classes produce wrong or zero styling and must be updated on sight.

| Skeleton v3 | Skeleton v4 Equivalent |
|---|---|
| `variant-soft-primary` | `preset-tonal-primary` |
| `variant-soft-secondary` | `preset-tonal-secondary` |
| `variant-soft-warning` | `preset-tonal-warning` |
| `variant-soft-success` | `preset-tonal-success` |
| `variant-ghost-success` | `preset-ghost-success` |
| `variant-ghost-warning` | `preset-ghost-warning` |
| `variant-ringed-warning` | `preset-outlined-warning` |
| `variant-filled-primary` | `preset-filled-primary` |
| `variant-filled-warning` | `preset-filled-warning` |
| `rounded-container-token` | `rounded-xl` |
| `rounded-token` | `rounded-md` |
| `card` (standalone) | `card preset-tonal-surface` or surface div pattern |
| `badge` (standalone) | `badge preset-tonal-surface` |
| `chip` | `badge preset-tonal-*` |

---

## 5. Transitions & Animation

All interactive state changes must be smoothed — no hard pops.

| Element | Classes |
|---|---|
| Table row | `transition-colors duration-200` on `<tr>` |
| List item card | `transition-colors duration-200` on `<li>` |
| Link hover | `transition-colors duration-200` on `<a>` |
| Info chips | `transition-colors duration-200` on `<span>` |
| QR code toggle (size) | `transition-all duration-500` on `<img>` |
| Collapsible sections | Use Skeleton `Accordion` or CSS `transition-all` — don't add custom unless needed |
| Buttons | Handled automatically by Skeleton preset classes |

---

## 6. Loading / Skeleton States

When `liveQuery` data is still resolving, show pulse placeholders instead of nothing:

```svelte
<!-- Title placeholder -->
<div class="h-7 w-2/3 bg-surface-200-800 animate-pulse rounded"></div>

<!-- Chip/pill placeholder -->
<div class="h-5 w-1/2 bg-surface-200-800 animate-pulse rounded-full"></div>

<!-- Icon placeholder -->
<div class="h-5 w-5 bg-surface-200-800 animate-pulse rounded-full"></div>
```

Always wrap in `{#if $lq__obj}{...}{:else}...skeleton...{/if}` — **never** show real content structure before data exists.

---

## 7. Dark Mode Rules

- **Never write `dark:` overrides for background or text colors.** The Firefly theme handles both modes through CSS variables. Writing `dark:bg-gray-800` or `dark:text-gray-400` bypasses the theme and breaks if the user switches themes.
- **Exception allowed:** `dark:text-primary-300` and `dark:text-tertiary-300` in info chips are intentional — they reference theme variables that gracefully degrade.
- **Exception allowed:** `dark:border-surface-700` in fine-grained border work when `border-surface-200-800` isn't strong enough.

---

## 8. Accessibility (Section 508 / WCAG 2.1 AA)

| Requirement | Implementation |
|---|---|
| Decorative icons | `aria-hidden="true"` on all `<span class="fas ...">` |
| Icon-only buttons | `aria-label="..."` or `title="..."` + visible context |
| Async content regions | `role="status" aria-live="polite"` on loading/empty sections |
| Focus indicators | `focus-visible:ring-2 focus-visible:ring-primary-500` on custom interactive elements |
| Interactive dialogs | `aria-haspopup="dialog"` on trigger buttons |
| Form inputs | Visible `<label>` linked via `for` / `id`, or explicit `aria-label` |
| Color-only information | Always pair color coding with icon or text — never color alone |
| Minimum touch target | 44×44px effective hit area for all tap targets |

---

## 9. Debug Code — Remove Before Committing

These patterns are breakpoint debuggers added during development. **Never commit them:**

```html
<!-- Breakpoint border debugger — REMOVE before commit -->
sm:border-l-red-400 md:border-l-yellow-400 lg:border-l-gray-100
sm:dark:border-l-red-600 md:dark:border-l-yellow-600 lg:dark:border-l-gray-700
```

Also flag on code review:
- `console.log(...)` that isn't behind a `log_lvl` guard
- `border-dashed border-y-transparent border-r-transparent` left on production components
- `overflow-x-scroll` (should be `overflow-x-auto`)

---

## 10. QR Code Pattern — Critical Bug Prevention

The async QR generation code uses a boolean `true` as a loading placeholder:

```typescript
$events_sess.pres_mgmt.session_qr_url[$lq__obj.id] = true;   // ← loading
// ... async ...
$events_sess.pres_mgmt.session_qr_url[$lq__obj.id] = result; // ← URL string
```

**Always gate display on `typeof ... === 'string'`**, not just truthy:

```svelte
<!-- ✅ Correct -->
{#if typeof $events_sess.pres_mgmt.session_qr_url?.[$lq__obj.id] === 'string'}

<!-- ❌ Wrong — renders broken <img src="true"> during load -->
{#if $events_sess.pres_mgmt.session_qr_url[$lq__obj.id]}
```

---

## 11. Tailwind Utility Usage Notes

- **`opacity-*` for muted text**: Use `opacity-60` (secondary) or `opacity-40` (tertiary/hint) instead of `text-gray-*`. This works in any theme and both modes.
- **`/` opacity modifier**: `bg-primary-500/10` is preferred over separate `opacity-10` — it targets only the background.
- **`text-sm leading-relaxed`**: Standard for body-level descriptive text in cards.
- **`tracking-wide uppercase`**: Use for section label/eyebrow text with `opacity-40`.
- **`whitespace-pre-wrap`**: Required for any `<pre>` or `<p>` displaying user-entered multi-line text (preserves breaks without horizontal overflow).