oh-my-customcode 0.57.0 → 0.58.0

package/templates/guides/impeccable-design/color-and-contrast.md

@@ -0,0 +1,278 @@
+# Color and Contrast
+
+> Reference: Impeccable Design Language — https://github.com/pbakaus/impeccable (Apache 2.0)
+
+---
+
+## OKLCH: The Preferred Color Model
+
+OKLCH (Oklab Lightness, Chroma, Hue) is a perceptually uniform color space. Unlike HSL, equal numeric changes in OKLCH produce equal perceived differences — making it the right tool for generating accessible, harmonious palettes programmatically.
+
+### Structure
+
+```
+oklch(lightness% chroma hue)
+```
+
+| Channel | Range | Description |
+|---------|-------|-------------|
+| `lightness` | 0%–100% | Perceived brightness |
+| `chroma` | 0–0.4 (approx) | Color saturation/vividness |
+| `hue` | 0–360 | Color angle (red=25, yellow=90, green=145, cyan=200, blue=250, purple=310) |
+
+### Why not HSL?
+
+HSL's lightness channel is not perceptually uniform. A blue at `hsl(250, 70%, 50%)` and a yellow at `hsl(60, 70%, 50%)` have the same numeric lightness but very different perceived brightness. This makes HSL palettes that "look right" on the screen require constant manual tuning.
+
+OKLCH fixes this: a blue at `oklch(50% 0.15 250)` and a yellow at `oklch(50% 0.15 90)` appear equally bright.
+
+### Browser support
+
+OKLCH is supported in all modern browsers (Chrome 111+, Firefox 113+, Safari 15.4+). For legacy support, provide an HSL fallback:
+
+```css
+color: hsl(250, 60%, 40%); /* fallback */
+color: oklch(40% 0.15 250); /* modern */
+```
+
+---
+
+## Chroma Constraints
+
+### Reduce chroma near white and black extremes
+
+At very high or very low lightness values, maximum chroma cannot be rendered — the color clips to the display gamut. Reduce chroma as lightness approaches 0% or 100%:
+
+| Lightness range | Max chroma (approx) |
+|-----------------|---------------------|
+| 10%–20% | 0.04–0.08 |
+| 20%–40% | 0.08–0.20 |
+| 40%–60% | 0.15–0.35 |
+| 60%–80% | 0.10–0.25 |
+| 80%–95% | 0.03–0.10 |
+
+Check rendered output with [OKLCH.com](https://oklch.com/) — the gamut boundary is shown visually.
+
+---
+
+## Neutrals: Tinted, Not Pure Gray
+
+Pure grays (chroma 0) appear cold and disconnected from the UI's color palette. Tinting neutrals with a low-chroma version of the brand hue creates cohesion.
+
+### Formula
+
+Use the brand hue with chroma 0.01–0.02 for neutrals:
+
+```css
+:root {
+  /* Brand hue: 250 (blue) */
+  --neutral-900: oklch(12% 0.01 250);
+  --neutral-800: oklch(20% 0.01 250);
+  --neutral-700: oklch(30% 0.01 250);
+  --neutral-600: oklch(40% 0.01 250);
+  --neutral-500: oklch(50% 0.01 250);
+  --neutral-400: oklch(60% 0.01 250);
+  --neutral-300: oklch(72% 0.01 250);
+  --neutral-200: oklch(84% 0.01 250);
+  --neutral-100: oklch(93% 0.01 250);
+  --neutral-50:  oklch(97% 0.01 250);
+}
+```
+
+### Temperature
+
+| Hue angle | Temperature | Effect |
+|-----------|-------------|--------|
+| ~60° | Warm | Approachable, editorial |
+| ~250° | Cool | Technical, precise, professional |
+
+Warm neutrals (cream, off-white) suit consumer and lifestyle products. Cool neutrals suit developer tools, dashboards, and data products.
+
+---
+
+## Palette Architecture
+
+### Components
+
+| Component | Count | Purpose |
+|-----------|-------|---------|
+| Primary | 1 color, 3–5 shades | Brand identity, CTAs, interactive elements |
+| Neutral | 9–11 shades | Backgrounds, borders, text |
+| Semantic | 4 colors (success, warning, danger, info), 2–3 shades each | State communication |
+| Surface | 2–3 variants | Background layering (base, raised, overlay) |
+
+### Primary palette (5 shades)
+
+```css
+:root {
+  --primary-50:  oklch(95% 0.05 250);  /* tint, hover backgrounds */
+  --primary-200: oklch(80% 0.10 250);  /* light states */
+  --primary-500: oklch(55% 0.20 250);  /* primary action */
+  --primary-700: oklch(38% 0.18 250);  /* pressed, dark variant */
+  --primary-900: oklch(22% 0.12 250);  /* text on light bg */
+}
+```
+
+### Semantic palette
+
+```css
+:root {
+  /* Success */
+  --success-light: oklch(92% 0.06 145);
+  --success:       oklch(50% 0.18 145);
+  --success-dark:  oklch(35% 0.15 145);
+
+  /* Warning */
+  --warning-light: oklch(93% 0.08 85);
+  --warning:       oklch(65% 0.20 85);
+  --warning-dark:  oklch(45% 0.18 85);
+
+  /* Danger */
+  --danger-light:  oklch(93% 0.06 25);
+  --danger:        oklch(50% 0.20 25);
+  --danger-dark:   oklch(35% 0.18 25);
+
+  /* Info */
+  --info-light:    oklch(93% 0.05 230);
+  --info:          oklch(52% 0.18 230);
+  --info-dark:     oklch(38% 0.16 230);
+}
+```
+
+---
+
+## The 60-30-10 Rule
+
+Visual weight should be distributed to create hierarchy without chaos:
+
+| Proportion | Role | Example |
+|------------|------|---------|
+| 60% | Dominant (neutral backgrounds) | Page background, card surfaces |
+| 30% | Secondary (supporting) | Sidebar, navigation, secondary panels |
+| 10% | Accent (brand, CTAs) | Buttons, links, highlights, icons |
+
+Violating this ratio — for example, a 40% brand-color background — overwhelms the interface and makes it harder to identify interactive elements.
+
+---
+
+## WCAG Contrast Requirements
+
+Contrast ratio is calculated between foreground and background luminance. Use a contrast checker to verify all text/background combinations.
+
+### Minimum ratios
+
+| Element | WCAG AA | WCAG AAA |
+|---------|---------|----------|
+| Body text (< 18px / < 14px bold) | 4.5:1 | 7:1 |
+| Large text (≥ 18px / ≥ 14px bold) | 3:1 | 4.5:1 |
+| UI components (borders, icons, input outlines) | 3:1 | 4.5:1 |
+
+### Practical targets
+
+- Body text: aim for 7:1 (AAA) — the difference in effort is minimal and accessibility is significantly better
+- Large headings: 4.5:1 minimum
+- Placeholder text: WCAG requires 4.5:1; placeholders are not exempt despite their decorative role
+- Disabled elements: WCAG exempts disabled controls from contrast requirements, but aim for 3:1 as a courtesy
+
+### Anti-patterns
+
+| Anti-pattern | Problem | Fix |
+|--------------|---------|-----|
+| Light gray text on white | Classic failure — looks designed, fails AA | Use `oklch(45% 0.01 250)` on white for safe gray |
+| Gray text on colored background | Double unpredictability — two variables affecting contrast | Test with a contrast checker, not by eye |
+| Red on green | Colorblind failure (deuteranopia/protanopia) | Add pattern or icon; do not rely on color alone |
+| Blue on red | Chromatic aberration causes vibration | Add lightness contrast; avoid hue-only contrast |
+| Yellow on white | Low contrast despite perceived brightness | Yellow on white fails AA unless very dark yellow |
+| Thin text over images | Impossible to guarantee; background varies | Add text shadow, overlay panel, or blur backdrop |
+
+### Testing tools
+
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- Chrome DevTools: Elements panel → Accessibility → Contrast
+- Firefox DevTools: Accessibility panel
+- Polypane: Built-in contrast checking across all breakpoints
+
+---
+
+## No Pure Gray or Black
+
+Pure grays (`oklch(N% 0 0)` or `#808080`) read as cold and disconnected. Tinted grays integrate into the palette.
+
+### Rule: chroma 0.005–0.01 minimum
+
+```css
+/* WRONG: pure gray */
+color: oklch(50% 0 0);
+
+/* CORRECT: tinted neutral */
+color: oklch(50% 0.01 250);
+```
+
+### No pure black
+
+`#000000` or `oklch(0% 0 0)` is rarely appropriate. High contrast without tint creates harshness. Instead:
+
+```css
+/* WRONG */
+--text-primary: #000000;
+
+/* CORRECT: near-black with subtle tint */
+--text-primary: oklch(12% 0.01 250);
+```
+
+---
+
+## Dark Mode
+
+Dark mode is NOT a color inversion. Inversion breaks contrast relationships and produces garish results. Instead, dark mode requires thoughtfully redesigned color relationships.
+
+### Principles
+
+**Lighter surfaces indicate depth.** In light mode, shadows indicate elevation. In dark mode, lighter backgrounds indicate elevation:
+
+| Elevation | Light mode | Dark mode |
+|-----------|-----------|-----------|
+| Page background | Lightest | Darkest |
+| Card | +shadow | Slightly lighter |
+| Modal/overlay | +deeper shadow | Lighter still |
+| Tooltip | Darkest shadow | Lightest surface |
+
+**Slightly desaturated accents.** Saturated colors are harder to look at on dark backgrounds for extended periods. Reduce chroma by 0.02–0.04:
+
+```css
+@media (prefers-color-scheme: dark) {
+  --primary-500: oklch(62% 0.16 250); /* was 0.20 in light mode */
+}
+```
+
+**Dark gray, never pure black.** Use 12–18% lightness for the base background:
+
+```css
+@media (prefers-color-scheme: dark) {
+  --surface-base:    oklch(14% 0.01 250); /* main background */
+  --surface-raised:  oklch(18% 0.01 250); /* cards */
+  --surface-overlay: oklch(22% 0.01 250); /* modals */
+}
+```
+
+**Redefine semantic tokens, do not invert them.** Semantic tokens exist precisely for this purpose:
+
+```css
+:root {
+  --text-body:    oklch(25% 0.01 250);
+  --text-muted:   oklch(50% 0.01 250);
+  --bg-base:      oklch(98% 0.01 250);
+}
+
+@media (prefers-color-scheme: dark) {
+  --text-body:    oklch(90% 0.01 250);
+  --text-muted:   oklch(65% 0.01 250);
+  --bg-base:      oklch(14% 0.01 250);
+}
+```
+
+### Dark mode testing
+
+- DevTools: Rendering panel → Emulate CSS media feature prefers-color-scheme
+- Test WCAG contrast ratios in dark mode independently — they differ from light mode
+- Test with vision emulation filters (protanopia, deuteranopia, achromatopsia) in DevTools

package/templates/guides/impeccable-design/index.yaml

@@ -0,0 +1,12 @@
+name: impeccable-design
+description: AI design language reference — typography, color, motion, and UX writing for production-grade UI
+source:
+  type: external
+  origin: github
+  url: https://github.com/pbakaus/impeccable
+  license: Apache-2.0
+documents:
+  - typography.md
+  - color-and-contrast.md
+  - motion-design.md
+  - ux-writing.md

package/templates/guides/impeccable-design/motion-design.md

@@ -0,0 +1,390 @@
+# Motion Design
+
+> Reference: Impeccable Design Language — https://github.com/pbakaus/impeccable (Apache 2.0)
+
+---
+
+## The 100/300/500 Rule
+
+Animation duration should match the conceptual weight of the change. Too fast and users miss feedback; too slow and the interface feels sluggish.
+
+### Duration tiers
+
+| Tier | Duration | Use cases |
+|------|----------|-----------|
+| Feedback | 100–150ms | Button press, checkbox toggle, hover state, ripple |
+| State change | 200–300ms | Dropdown open, tooltip appear, tab switch, accordion |
+| Structural | 300–500ms | Page transition, modal open, sidebar expand |
+| Entry / onboarding | 500–800ms | Hero animations, first-run sequences, loading complete |
+
+### Exit animations are shorter
+
+Elements leaving the screen should animate out at roughly 75% of their entrance duration. The user's attention has already moved on:
+
+```css
+.modal-enter { animation-duration: 300ms; }
+.modal-exit  { animation-duration: 225ms; } /* 75% of 300ms */
+
+.dropdown-enter { animation-duration: 200ms; }
+.dropdown-exit  { animation-duration: 150ms; }
+```
+
+---
+
+## Easing Functions
+
+Generic browser easings (`ease`, `ease-in`, `ease-out`, `ease-in-out`) are functional but imprecise. Custom cubic-bezier curves produce more polished results.
+
+### The three essential curves
+
+**Ease-out** — for elements appearing on screen (entering, expanding):
+```css
+/* Fast start, gentle landing */
+animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
+```
+
+**Ease-in** — for elements leaving screen (exiting, collapsing):
+```css
+/* Gradual acceleration, fast exit */
+animation-timing-function: cubic-bezier(0.7, 0, 0.84, 0);
+```
+
+**Ease-in-out** — for bidirectional transitions (sliding between states):
+```css
+/* Symmetrical: slow start, fast middle, slow end */
+animation-timing-function: cubic-bezier(0.65, 0, 0.35, 1);
+```
+
+### Exponential curves (more expressive)
+
+| Curve | CSS | Character |
+|-------|-----|-----------|
+| Quart-out | `cubic-bezier(0.25, 1, 0.5, 1)` | Smooth default, good for most UI |
+| Quint-out | `cubic-bezier(0.22, 1, 0.36, 1)` | Dramatic, large structural changes |
+| Expo-out | `cubic-bezier(0.16, 1, 0.3, 1)` | Snappy, high-energy feedback |
+
+### CSS custom properties for easing tokens
+
+```css
+:root {
+  --ease-out:     cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in:      cubic-bezier(0.7, 0, 0.84, 0);
+  --ease-in-out:  cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-spring:  cubic-bezier(0.25, 1, 0.5, 1);
+}
+```
+
+### Anti-pattern: bounce and elastic
+
+Bounce and elastic easings were popular in the early 2010s. They now read as amateurish and dated. They also perform poorly for accessibility (vestibular disorders). Do not use them:
+
+```css
+/* WRONG: dated, amateurish */
+animation-timing-function: cubic-bezier(0.34, 1.56, 0.64, 1); /* overshoot */
+
+/* CORRECT: expo-out is energetic without bouncing */
+animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
+```
+
+---
+
+## Performance: Only Animate transform and opacity
+
+Layout-triggering properties (`width`, `height`, `top`, `left`, `margin`, `padding`) force the browser to recalculate layout on every frame — expensive and jank-prone. Only `transform` and `opacity` skip layout and paint, running entirely on the GPU compositor.
+
+### Safe properties
+
+```css
+/* CORRECT: compositor-only, 60fps */
+.panel { transform: translateX(-100%); opacity: 0; }
+.panel.open { transform: translateX(0); opacity: 1; }
+```
+
+### Avoid layout-triggering animations
+
+```css
+/* WRONG: triggers layout recalculation every frame */
+.panel { left: -300px; }
+.panel.open { left: 0; }
+
+/* WRONG: forces paint */
+.card { background-color: #fff; }
+.card:hover { background-color: #f5f5f5; } /* fine for hover, bad inside keyframes */
+```
+
+### Animating height with CSS grid
+
+Animating `height: 0` to `height: auto` is a common requirement (accordion, expand/collapse) that cannot use `transform` directly. The cleanest CSS-only solution uses `grid-template-rows`:
+
+```css
+.accordion-content {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 250ms var(--ease-out);
+}
+
+.accordion-content.open {
+  grid-template-rows: 1fr;
+}
+
+.accordion-content > div {
+  overflow: hidden; /* required for 0fr to clip content */
+}
+```
+
+---
+
+## Staggered Animations
+
+Staggering applies progressively increasing delays to a list of elements, creating a wave effect. It communicates that items belong together while adding visual interest.
+
+### CSS custom properties approach
+
+```css
+.list-item {
+  animation: fade-up 300ms var(--ease-out) both;
+  animation-delay: calc(var(--i) * 50ms);
+}
+```
+
+Set `--i` on each element:
+
+```html
+<li class="list-item" style="--i: 0">First</li>
+<li class="list-item" style="--i: 1">Second</li>
+<li class="list-item" style="--i: 2">Third</li>
+```
+
+Or set it in JavaScript:
+
+```js
+document.querySelectorAll('.list-item').forEach((el, i) => {
+  el.style.setProperty('--i', i);
+});
+```
+
+### Cap total stagger duration at 500ms
+
+A list of 20 items staggered at 50ms each takes 1000ms to complete — too long. Cap the maximum total delay:
+
+```css
+animation-delay: calc(min(var(--i), 8) * 50ms); /* max 400ms total */
+```
+
+Or limit at the last item: stagger interval × item count should not exceed 500ms.
+
+---
+
+## Accessibility: prefers-reduced-motion
+
+Approximately 35% of adults over 40 have vestibular disorders that can be triggered by parallax, sliding transitions, and spinning elements. The `prefers-reduced-motion` media query is not optional.
+
+### User statistics
+
+This is not a fringe case. `prefers-reduced-motion: reduce` affects a significant portion of users — including those who enable it for performance reasons on low-power devices.
+
+### Replace spatial motion with crossfades
+
+The principle: preserve the informational purpose of the animation while removing the vestibular trigger.
+
+```css
+@keyframes slide-in {
+  from { transform: translateY(20px); opacity: 0; }
+  to   { transform: translateY(0);    opacity: 1; }
+}
+
+@keyframes fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+.panel {
+  animation: slide-in 300ms var(--ease-out);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .panel {
+    animation: fade-in 150ms linear; /* shorter, opacity-only */
+  }
+}
+```
+
+### Preserve functional animations
+
+Some animations communicate state changes that users need (progress bars, loading spinners, form validation). These should be preserved even for reduced-motion users — reduce their speed and intensity, do not eliminate them:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    /* Slow down, keep the spin so user knows loading is happening */
+    animation-duration: 2s;
+  }
+
+  .progress-bar {
+    /* Shorten transition but keep it */
+    transition-duration: 50ms;
+  }
+}
+```
+
+### Global reset approach
+
+A pragmatic approach for existing codebases:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+This is a blunt instrument. Prefer targeted overrides where functional animations need preservation.
+
+---
+
+## Perceived Performance
+
+Animation can make interfaces feel faster even when task completion time is identical. These techniques exploit how the brain perceives wait time.
+
+### The 80ms threshold
+
+Users perceive delays under 80ms as instantaneous. Responses between 80–100ms feel slightly delayed but acceptable. Above 200ms, users consciously notice the wait.
+
+Design principle: use the delay budget wisely. If a backend call takes 300ms, an optimistic UI update at 0ms prevents the user from ever perceiving the delay.
+
+### Active vs passive waiting
+
+A spinner saying "Loading..." is passive waiting — the user is frozen. A progress bar, animated skeleton screen, or optimistic UI update is active — the user feels progress is happening.
+
+- Skeleton screens reduce perceived wait time by 10–30% compared to blank space
+- Content that appears progressively (top to bottom) feels faster than all-at-once reveals
+
+### Preemptive transitions
+
+Start a transition before the user's action completes. Hover states that begin animating at hover start (not click) make actions feel faster:
+
+```css
+.button {
+  transition: background-color 150ms var(--ease-out),
+              transform 100ms var(--ease-out);
+}
+
+.button:hover {
+  /* Animate on hover, not just on click */
+  background-color: var(--primary-600);
+  transform: translateY(-1px);
+}
+
+.button:active {
+  transform: translateY(0);
+  transition-duration: 50ms;
+}
+```
+
+### Optimistic UI
+
+Update the UI immediately on user action, then sync with the server. Show the final state first and roll back only on error:
+
+```js
+// Optimistic update pattern
+async function toggleLike(postId) {
+  // 1. Update UI immediately
+  setLiked(true);
+  setCount(prev => prev + 1);
+
+  try {
+    // 2. Sync with server
+    await api.like(postId);
+  } catch {
+    // 3. Roll back on failure
+    setLiked(false);
+    setCount(prev => prev - 1);
+    showError('Could not save — please try again');
+  }
+}
+```
+
+---
+
+## Performance Implementation
+
+### will-change: use on trigger, not permanently
+
+`will-change` promotes an element to its own GPU layer. Overuse wastes GPU memory and can slow rendering:
+
+```css
+/* WRONG: always promoted, wastes GPU memory */
+.card { will-change: transform; }
+
+/* CORRECT: promote only when animation is about to happen */
+.card:hover { will-change: transform; }
+
+/* Or in JS: add/remove on animation start/end */
+el.addEventListener('mouseenter', () => el.style.willChange = 'transform');
+el.addEventListener('animationend', () => el.style.willChange = 'auto');
+```
+
+### Intersection Observer for scroll animations
+
+Never use scroll event listeners for animation triggers — they fire on every scroll event and block the main thread. Use `IntersectionObserver`:
+
+```js
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      entry.target.classList.add('animate-in');
+      observer.unobserve(entry.target); // stop observing once triggered
+    }
+  });
+}, { threshold: 0.1 });
+
+document.querySelectorAll('.animate-on-scroll').forEach(el => observer.observe(el));
+```
+
+### Motion tokens
+
+Centralize all durations and easings as tokens to enable systematic changes and theming:
+
+```css
+:root {
+  /* Duration */
+  --duration-fast:      100ms;
+  --duration-normal:    200ms;
+  --duration-slow:      350ms;
+  --duration-deliberate: 500ms;
+
+  /* Easing */
+  --ease-out:    cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in:     cubic-bezier(0.7, 0, 0.84, 0);
+  --ease-inout:  cubic-bezier(0.65, 0, 0.35, 1);
+
+  /* Reduce motion override */
+  --duration-motion-safe: 200ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --duration-motion-safe: 0.01ms;
+  }
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-pattern | Problem | Fix |
+|--------------|---------|-----|
+| Animating everything | Dilutes meaning; users stop noticing what's important | Reserve motion for state changes that need emphasis |
+| Feedback animation > 500ms | Feels broken; user re-clicks, creates double-trigger bugs | Keep feedback under 200ms |
+| No reduced-motion support | Triggers vestibular disorders for ~35% of adults over 40 | Always implement `prefers-reduced-motion` |
+| Bounce and elastic easing | Dated, amateurish, vestibular risk | Use expo-out for energy |
+| `left`/`top`/`height` in keyframes | Triggers layout recalc every frame, causes jank | Use `transform` + `opacity` only |
+| Stagger > 500ms total | Users wait for the list to finish before acting | Cap at 500ms total stagger |
+| `will-change` on static elements | Wastes GPU memory, can slow render | Apply only during/before animation |
+| Scroll listener for animations | Blocks main thread, causes jank | Use `IntersectionObserver` |