@maccesar/aiskills 1.12.0 → 1.16.0

package/skills/refactoring-ui/references/06-dark-mode.md

@@ -0,0 +1,117 @@
+# Dark Mode
+
+> **Scope note**: *Refactoring UI* was written before dark mode was an industry default and does not address it explicitly. **However**, the book's HSL chapter (in `03-visual-treatment.md`) — handpicking shades by hue/saturation/lightness, not deriving them via `lighten()`/`darken()` — is exactly the foundation dark mode needs. This file extends those principles to a second color mode.
+
+---
+
+## Don't Invert — Rebuild
+
+Inverting a light theme produces a "negative" image: muddy colors, weird text contrast, accents that lose punch. Dark mode is its own design pass.
+
+The bookkeeping change: every color token now has a **mode pair**. Plan for it from the start, even if you only ship light first.
+
+```css
+:root {
+  --bg-canvas: hsl(220 14% 96%);
+  --bg-surface: hsl(0 0% 100%);
+  --text-primary: hsl(220 13% 18%);
+  --text-secondary: hsl(220 9% 46%);
+  --border: hsl(220 13% 91%);
+  --brand-500: hsl(217 91% 60%);
+}
+
+:root[data-theme='dark'] {
+  --bg-canvas: hsl(220 13% 10%);
+  --bg-surface: hsl(220 13% 14%);
+  --text-primary: hsl(220 14% 96%);
+  --text-secondary: hsl(220 9% 65%);
+  --border: hsl(220 13% 22%);
+  --brand-500: hsl(217 91% 65%);   /* nudged lighter for dark bg */
+}
+```
+
+## Dark Backgrounds Aren't Black
+
+Pure `#000` reads as a hole in the screen. Pull the lightness up to ~8–12%, keep a small amount of saturation, and lean slightly warm or cool depending on your brand.
+
+| Backdrop | Lightness | Notes |
+|---|---|---|
+| App canvas (outermost) | 8–12% | Lowest layer — slightly tinted, not pure black |
+| Surface (cards, panels) | 12–16% | One step above canvas — implies "raised" without a shadow |
+| Elevated surface (modals, popovers) | 16–22% | Highest layer — even lighter |
+
+The trick: in dark mode, **lighter = closer to the viewer**, the opposite of light mode. A higher elevation doesn't get a darker shadow — it gets a lighter surface.
+
+## Text Contrast in Dark Mode
+
+Pure white text on a near-black background is *too much* contrast — the text vibrates and reading becomes tiring at length.
+
+- Primary text: ~96% lightness (slightly off-white) — e.g., `hsl(220 14% 96%)`
+- Secondary text: ~65% lightness — significantly muted compared to light mode's secondary
+- Tertiary / placeholder: ~45–50%
+
+WCAG ratios still apply (4.5:1 small text, 3:1 large), and slightly off-white still passes against a near-black canvas with room to spare.
+
+## Accent Colors Usually Need a Lightness Bump
+
+A brand color tuned for white backgrounds often looks too dark and dim against a dark canvas. Most palettes need the accent **lightness raised 5–10%** for the dark variant.
+
+Test against both backgrounds. If the brand color fails contrast in dark mode, derive a lighter variant rather than swapping for an unrelated color — keeps brand identity coherent.
+
+## Shadows: Mostly Gone, Sometimes Inverted
+
+Shadows are made of light obstruction. On a dark canvas, the absence of light is the canvas itself — a dark shadow on dark background is invisible.
+
+Options:
+
+1. **Skip shadows entirely**: use lighter surfaces and tinted borders to communicate elevation
+2. **Top highlight**: an inset top border (lighter color) to show that the element catches the imagined light source, with no shadow below
+3. **Very soft dark shadow**: works only when the element is on a lighter surface (e.g., a dropdown over the canvas) — large blur, low opacity
+
+A `box-shadow: 0 2px 4px rgba(0,0,0,0.3)` that was crisp in light mode is invisible on a `hsl(220 13% 10%)` canvas. Recheck every shadow when adding dark mode.
+
+## Images and Photos in Dark Mode
+
+Photos with bright backgrounds (typically light themes) "blow out" against a dark canvas — they pop too hard. Two tactics:
+
+- **Lower image brightness slightly** in dark mode (e.g., `filter: brightness(0.9)`) — only for decorative/hero images, never for content the user is reading
+- **Frame with a subtle border** — separates the bright rectangle from the dark canvas without dimming the photo
+
+Same principle for video posters and avatar images.
+
+## SVG Icons and Logos
+
+Single-color icons should be currentColor-driven so they pick up the mode's text color:
+
+```html
+<svg fill="currentColor" ...>
+```
+
+Multi-color logos need a dark variant. Don't fake it with `filter: invert()` — colors land in the wrong hue and brand recognition suffers.
+
+## Theme Toggle: Three Defaults
+
+1. **Match system preference** (`prefers-color-scheme`) — best first-paint experience
+2. **Respect explicit user override** — store in `localStorage`; persists across sessions
+3. **Apply before first paint** — set the theme class on `<html>` from a tiny inline script in `<head>` BEFORE any rendering, to avoid a flash of the wrong theme
+
+```html
+<script>
+  (function () {
+    var stored = localStorage.getItem('theme');
+    var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    var theme = stored || (prefersDark ? 'dark' : 'light');
+    document.documentElement.dataset.theme = theme;
+  })();
+</script>
+```
+
+## Anti-Patterns
+
+- ❌ Pure black (`#000`) for the canvas — feels like a void, hurts at length
+- ❌ Pure white text — vibrates against dark bg, tiring to read
+- ❌ `filter: invert(1)` to "do" dark mode — produces wrong hues, breaks images
+- ❌ Same brand color in both modes without checking contrast — fails WCAG silently
+- ❌ Keeping every shadow from light mode unchanged — invisible against dark bg
+- ❌ Theme toggle applied AFTER first paint — flash of opposite theme on every load
+- ❌ Inverting photos and screenshots — colors shift unnaturally, recognition suffers

package/skills/refactoring-ui/references/07-component-patterns.md

@@ -0,0 +1,181 @@
+# Component Patterns: Modals, Forms, Tables
+
+> **Scope note**: *Refactoring UI* covers button tiers and label patterns directly (see `02-page-mechanics.md`), but does not have dedicated chapters for modals, forms, or tables. This file applies the book's principles — hierarchy through weight/color, generous spacing, grouping by proximity, finishing with restraint — to these three common components.
+
+---
+
+## Modals
+
+### When to Use a Modal
+
+- A focused decision that **blocks** the current task (confirm destructive action, complete a required step)
+- Short content that doesn't deserve a full page
+- Multi-step flows that should preserve the underlying context (the page behind the modal)
+
+When **not** to use a modal:
+
+- Anything the user might want to consult while doing the surrounding task — modals trap them
+- Long content that scrolls — make it a page
+- Anything that needs to be linkable — modals are stateless to the URL by default
+
+### Layout
+
+| Element | Rule |
+|---|---|
+| Width | Fixed pixel max (`max-width: 480px` typical) — never percentage |
+| Vertical position | Anchored ~10–15% from the top of viewport, not centered — feels more stable |
+| Backdrop | Semi-opaque dark overlay (~50–70% opacity) — darkens the page enough to focus attention |
+| Padding | Generous — modal content is usually short; tight padding feels cramped |
+| Close affordance | "Cancel" button in the footer AND an `×` in the top corner — keyboard users use Esc |
+
+### Focus and Keyboard
+
+Three keyboard requirements, all non-negotiable:
+
+1. **Focus moves into the modal on open** — typically to the first interactive element, or the close button if the modal is informational
+2. **Focus traps inside the modal** — Tab/Shift+Tab cycle through modal elements only, never leaking to the page behind
+3. **Esc closes the modal** AND focus returns to the element that opened it
+
+These are the table-stakes of accessibility for modals. Libraries like `focus-trap` or `@radix-ui/react-dialog` solve them — don't roll your own unless you must.
+
+### Button Order
+
+The primary action sits on the **right** in left-to-right UIs:
+
+```
+[ Cancel ]   [ Save changes ]
+```
+
+Destructive primary actions get an extra confirmation (a typed confirmation, or a secondary modal). Don't bury a destructive button next to a safe one.
+
+## Forms
+
+### Label Placement
+
+Top-aligned labels are the default for almost every form:
+
+- Fastest to scan top-to-bottom
+- Work on narrow screens without reflow
+- Easier to localize (labels grow in length across languages)
+
+Left-aligned labels look formal but force the user's eye to zig-zag and break on mobile. Reserve for dense data-entry screens where users repeatedly fill the same form.
+
+### Validation Timing
+
+- **On blur** for individual fields — show the error after the user leaves the field, not while they're typing
+- **On submit** for fields they haven't touched yet
+- **On change** ONLY for fields where the answer is binary and visible (e.g., a password strength meter, a username availability check)
+
+Inline validation while the user is mid-typing reads as the form fighting them.
+
+### Error Display
+
+A field in error state should have:
+
+- A color change (red border, but not the *only* signal)
+- A short message **below** the field, in the same color as the border
+- An icon at the start of the message — color is not enough (≈8% of males can't distinguish red from green)
+- The field's normal label and placeholder stay legible — don't replace them with the error
+
+### Spacing Within a Form
+
+Apply the Law of Proximity from `02-page-mechanics.md`:
+
+```
+[Label]
+[Input]
+ (small gap, ~8px)
+[Helper text]
+
+(large gap, ~24-32px to the next field group)
+
+[Label]
+[Input]
+```
+
+Label sits closer to its own input than to anything else. Each field group is clearly separated from the next.
+
+### Button Placement
+
+- **Single primary button** at the bottom left or center — never aligned right unless the form sits inside a modal (modals follow the modal rule)
+- **Secondary "Cancel"** to the left of the primary
+- Disable the submit button only when there are concrete errors — disabling it preemptively because the user "hasn't typed everything yet" leaves them guessing
+
+### Required vs Optional
+
+If most fields are required, mark only the **optional** ones — less noise overall. If most are optional, mark the required ones with `*`. Either system is fine — pick one and stay consistent.
+
+## Tables
+
+### Density Tiers
+
+Pick a row density based on the user's job:
+
+| Tier | Row height | Use |
+|---|---|---|
+| Comfortable | 56–64px | Marketing tables, dashboards seen occasionally |
+| Default | 40–48px | Most app tables |
+| Compact | 28–36px | Operator dashboards (CRM, admin, finance) where rows are scanned in bulk |
+
+Don't go below 28px unless the data is genuinely homogeneous — eye fatigue scales with row count, not just total height.
+
+### Alignment by Data Type
+
+| Data type | Alignment | Reason |
+|---|---|---|
+| Text (names, labels) | Left | Default reading direction |
+| Numbers (counts, money, percentages) | Right | Digits and decimals line up; magnitudes are scannable |
+| Dates | Left or right consistent | Pick one and stick — comparing dates is easier with consistent alignment |
+| Status / chips | Center inside their own column | Visually balanced when the chip is the only content |
+| Actions (icons, kebabs) | Right | Out of the way of the data |
+
+### Column Headers
+
+Mirror the column's content alignment. A right-aligned numeric column gets a right-aligned header.
+
+Sortable columns get an indicator (arrow up/down) AND show the active sort with stronger contrast — color alone isn't enough.
+
+### Sticky Headers
+
+For tables that scroll vertically inside their container, the header should stick. Two ways:
+
+1. `position: sticky; top: 0;` on the `<thead>` — easiest, works inside scrollable containers
+2. A second fixed header rendered above the scroll area — needed when the table itself scrolls in `<body>` (not its own container)
+
+Sticky headers must have a solid (opaque) background, otherwise rows scrolling behind them show through.
+
+### Row Hover and Selection
+
+- Subtle row hover background (one shade-step on neutrals) — helps the eye track across wide tables
+- Selection: a left-edge accent stripe **plus** a tinted background — selection should be obvious without screaming
+- Don't animate row hover — adds latency to bulk scanning
+
+### Empty Tables
+
+Apply the empty-state rule from `04-polish.md`: don't just show "No data" centered in a blank rectangle. The empty state communicates what could go there and offers a way to start.
+
+## Anti-Patterns
+
+### Modals
+
+- ❌ Centering vertically — feels unanchored
+- ❌ No close affordance — Esc users can escape, mouse users get stuck
+- ❌ Modals over modals (nested) — confusing back-stack
+- ❌ Destructive action as primary button without confirmation step
+- ❌ No focus trap — Tab leaks to the page behind
+
+### Forms
+
+- ❌ Placeholder as the only label — vanishes on focus, accessibility regression
+- ❌ Inline validation on keystroke — fights the user
+- ❌ Disabling the submit button without explaining why
+- ❌ Red asterisks on every field — visual noise
+- ❌ Forms wider than ~600px — eye tracking degrades
+
+### Tables
+
+- ❌ Centered text columns — slow to scan
+- ❌ Left-aligned numeric columns — magnitudes hide
+- ❌ Translucent sticky header — rows show through
+- ❌ Row dividers AND row hover background — over-decorated
+- ❌ A single fixed column width for every column — wastes space; let content determine width within sensible min/max