opencodekit 0.18.8 → 0.18.10

package/dist/template/.opencode/skill/frontend-design/references/animation/motion-core.md

@@ -1,171 +1,181 @@
-# Motion Core (formerly Framer Motion)
+# Motion Core (motion/react)
 
 **Import**: `import { motion, AnimatePresence } from 'motion/react'`
 
-## Basic Animation
+## Motion Principles
 
-```tsx
-// Simple animate on mount
-<motion.div
-  initial={{ opacity: 0, y: 20 }}
-  animate={{ opacity: 1, y: 0 }}
-  transition={{ duration: 0.6 }}
-/>
+- Animate for clarity, not decoration
+- Use motion to explain state change and hierarchy
+- Prefer subtle distance (`8-16px`) and opacity shifts
+- Use consistent timing/easing system across the app
 
-// Shorthand (no transition object)
-<motion.div animate={{ scale: 1.1 }} />
-```
+## Timing System
 
-## Variants (Recommended Pattern)
+| Use Case                      | Duration   |
+| ----------------------------- | ---------- |
+| Instant feedback (hover/tap)  | 100-150ms  |
+| State changes (menus/toggles) | 200-300ms  |
+| Layout transitions            | 300-500ms  |
+| Large entrances               | 500-800ms  |
 
-```tsx
-const variants = {
-  hidden: { opacity: 0, y: 20 },
-  visible: { opacity: 1, y: 0 }
-};
+**Rule**: exit duration = ~75% of enter duration.
 
-<motion.div
-  variants={variants}
-  initial="hidden"
-  animate="visible"
-/>
-```
+## Easing System
 
-## Gestures
+Use exponential easing by default:
 
 ```tsx
-<motion.button
-  whileHover={{ scale: 1.05 }}
-  whileTap={{ scale: 0.95 }}
-  whileFocus={{ outline: '2px solid blue' }}
-/>
+const EASING_ENTER = [0.16, 1, 0.3, 1];
+const EASING_EXIT = [0.4, 0, 1, 1];
+```
 
-// Drag
+Avoid bounce/elastic easings for product UI.
+
+## Performance Rules
+
+Animate only compositor-friendly properties:
+
+- `transform`
+- `opacity`
+
+Avoid animating:
+
+- `width`, `height`
+- `top`, `left`
+- `margin`, `padding`
+
+## Basic Pattern
+
+```tsx
 <motion.div
-  drag
-  dragConstraints={{ left: 0, right: 300 }}
-  dragElastic={0.2}
+  initial={{ opacity: 0, y: 12 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.3, ease: [0.16, 1, 0.3, 1] }}
 />
 ```
 
-## Layout Animations
+## Variants Pattern (Recommended)
 
 ```tsx
-// Automatic layout animation
-<motion.div layout />
-
-// Shared layout
-<motion.div layoutId="shared-element" />
+const card = {
+  hidden: { opacity: 0, y: 12 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    transition: { duration: 0.3, ease: [0.16, 1, 0.3, 1] },
+  },
+};
 
-// Layout with spring
-<motion.div layout transition={{ type: 'spring', stiffness: 300 }} />
+<motion.div variants={card} initial="hidden" animate="visible" />
 ```
 
+Use variants for shared timing and maintainability.
+
 ## Exit Animations (AnimatePresence)
 
 ```tsx
-import { AnimatePresence } from 'motion/react';
-
-<AnimatePresence>
-  {isVisible && (
+<AnimatePresence mode="wait">
+  {open && (
     <motion.div
-      key="modal"
-      initial={{ opacity: 0 }}
-      animate={{ opacity: 1 }}
-      exit={{ opacity: 0 }}
+      key="panel"
+      initial={{ opacity: 0, y: 8 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, y: 4 }}
+      transition={{ duration: 0.22, ease: [0.4, 0, 1, 1] }}
     />
   )}
 </AnimatePresence>
 ```
 
-## Stagger Children
+Always provide stable `key` values for exiting elements.
+
+## Stagger Patterns
 
 ```tsx
 const container = {
   hidden: { opacity: 0 },
   visible: {
     opacity: 1,
-    transition: { staggerChildren: 0.1 }
-  }
+    transition: {
+      staggerChildren: 0.05,
+      delayChildren: 0.05,
+    },
+  },
 };
 
 const item = {
-  hidden: { opacity: 0, y: 20 },
-  visible: { opacity: 1, y: 0 }
+  hidden: { opacity: 0, y: 8 },
+  visible: { opacity: 1, y: 0 },
 };
-
-<motion.ul variants={container} initial="hidden" animate="visible">
-  {items.map(i => <motion.li key={i} variants={item} />)}
-</motion.ul>
 ```
 
-## Transition Types
-
-```tsx
-// Spring (default for physical properties)
-transition={{ type: 'spring', stiffness: 300, damping: 20 }}
+Cap total stagger windows to ~500ms.
 
-// Tween
-transition={{ type: 'tween', duration: 0.5, ease: 'easeInOut' }}
+## Layout Animations
 
-// Inertia (for drag)
-transition={{ type: 'inertia', velocity: 50 }}
+```tsx
+<motion.div layout />
 ```
 
-## Common Easing
+Use `layout` for reordering and size changes. Add spring only when needed:
 
 ```tsx
-ease: 'linear'
-ease: 'easeIn' | 'easeOut' | 'easeInOut'
-ease: 'circIn' | 'circOut' | 'circInOut'
-ease: 'backIn' | 'backOut' | 'backInOut'
-ease: [0.4, 0, 0.2, 1]  // cubic-bezier
+<motion.div layout transition={{ type: 'spring', stiffness: 320, damping: 28 }} />
 ```
 
-## useAnimate Hook
+## Gestures
 
 ```tsx
-import { useAnimate } from 'motion/react';
-
-function Component() {
-  const [scope, animate] = useAnimate();
-  
-  const handleClick = async () => {
-    await animate(scope.current, { x: 100 });
-    await animate(scope.current, { scale: 1.2 });
-  };
-  
-  return <div ref={scope} onClick={handleClick} />;
-}
+<motion.button
+  whileHover={{ scale: 1.02 }}
+  whileTap={{ scale: 0.98 }}
+  transition={{ duration: 0.12 }}
+/>
 ```
 
-## Motion Values
+Keep gesture amplitudes subtle (`0.98-1.03`).
 
-```tsx
-import { useMotionValue, useTransform } from 'motion/react';
+## Height Expand/Collapse (No height animation)
 
-const x = useMotionValue(0);
-const opacity = useTransform(x, [0, 100], [1, 0]);
+Use CSS grid technique:
+
+```css
+.accordion-content {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 280ms cubic-bezier(0.16, 1, 0.3, 1);
+}
 
-<motion.div style={{ x, opacity }} drag="x" />
+.accordion-content[data-open='true'] {
+  grid-template-rows: 1fr;
+}
+
+.accordion-inner {
+  overflow: hidden;
+}
 ```
 
-## Integration with Tailwind
+## Reduced Motion (Mandatory)
 
-```tsx
-// Motion handles animation, Tailwind handles styling
-<motion.div
-  className="bg-blue-500 rounded-lg p-4"
-  whileHover={{ scale: 1.05 }}
-  transition={{ type: 'spring' }}
-/>
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
 ```
 
-## Validation Checklist
+For motion/react, switch spatial movement to opacity-only when reduced motion is enabled.
+
+## Quick Checklist
 
-- [ ] Import from `motion/react` (not `framer-motion`)
-- [ ] Use variants for complex animations
-- [ ] Wrap conditional renders with `AnimatePresence`
-- [ ] Add `key` prop to animated elements in `AnimatePresence`
-- [ ] Use `layout` for automatic layout animations
-- [ ] Prefer `whileHover`/`whileTap` over CSS `:hover`
+- [ ] Uses `motion/react` import
+- [ ] Timing follows 100/300/500ms system
+- [ ] Exponential easing, no bounce/elastic
+- [ ] Animates only `transform` and `opacity`
+- [ ] Uses `AnimatePresence` for exit states
+- [ ] Includes reduced motion support
+- [ ] Stagger windows stay under 500ms

package/dist/template/.opencode/skill/frontend-design/references/design/color-system.md

@@ -0,0 +1,111 @@
+# Color System — OKLCH Deep Guide
+
+## Why OKLCH Over HSL
+
+HSL is **not perceptually uniform** — `hsl(60, 100%, 50%)` (yellow) appears far brighter than `hsl(240, 100%, 50%)` (blue) at the same lightness. OKLCH fixes this: equal lightness steps _look_ equal.
+
+```css
+/* HSL: looks inconsistent */
+--blue: hsl(240, 70%, 50%);
+--green: hsl(120, 70%, 50%); /* Appears much brighter */
+
+/* OKLCH: looks consistent */
+--blue: oklch(0.55 0.22 264);
+--green: oklch(0.55 0.18 145); /* Same perceived brightness */
+```
+
+## Two-Layer Token Architecture
+
+**Layer 1 — Primitives** (raw values, never used directly in components):
+
+```css
+@theme {
+  --blue-100: oklch(0.95 0.03 264);
+  --blue-300: oklch(0.75 0.1 264);
+  --blue-500: oklch(0.55 0.22 264);
+  --blue-700: oklch(0.4 0.18 264);
+  --blue-900: oklch(0.25 0.12 264);
+}
+```
+
+**Layer 2 — Semantic** (what components reference; redefine for dark mode):
+
+```css
+@theme {
+  --color-primary: var(--blue-500);
+  --color-primary-hover: var(--blue-700);
+  --color-surface: var(--neutral-50);
+  --color-surface-elevated: var(--neutral-0);
+  --color-text: var(--neutral-900);
+  --color-text-muted: var(--neutral-600);
+  --color-border: var(--neutral-200);
+}
+
+/* Dark mode: redefine ONLY semantic layer */
+@media (prefers-color-scheme: dark) {
+  @theme {
+    --color-primary: var(--blue-300);
+    --color-primary-hover: var(--blue-100);
+    --color-surface: var(--neutral-900);
+    --color-surface-elevated: var(--neutral-800);
+    --color-text: var(--neutral-100);
+    --color-text-muted: var(--neutral-400);
+    --color-border: var(--neutral-700);
+  }
+}
+```
+
+## Tinted Neutrals
+
+Never use pure gray (`chroma: 0`). Add `chroma: 0.01` hinted toward brand hue — barely visible but creates subconscious cohesion:
+
+```css
+@theme {
+  /* Brand hue: 264 (blue) — neutrals subtly tinted */
+  --neutral-0: oklch(1 0.005 264);
+  --neutral-50: oklch(0.97 0.01 264);
+  --neutral-100: oklch(0.93 0.01 264);
+  --neutral-200: oklch(0.87 0.01 264);
+  --neutral-400: oklch(0.7 0.01 264);
+  --neutral-600: oklch(0.5 0.01 264);
+  --neutral-800: oklch(0.25 0.01 264);
+  --neutral-900: oklch(0.16 0.01 264);
+}
+```
+
+## Dark Mode Rules
+
+Dark mode is **not** inverted light mode:
+
+| Aspect  | Light Mode                   | Dark Mode                                            |
+| ------- | ---------------------------- | ---------------------------------------------------- |
+| Depth   | Shadows create elevation     | Lighter surfaces create elevation                    |
+| Base    | `oklch(0.97+ …)`             | `oklch(0.15-0.18 …)` — NOT pure black                |
+| Accents | Full saturation              | Desaturate 10-20% to reduce glare                    |
+| Text    | Dark on light, high contrast | Light on dark, slightly reduced contrast for comfort |
+| Borders | Darker than surface          | Lighter than surface                                 |
+
+```css
+/* Dark surface elevation via lightness, not shadows */
+--surface-0: oklch(0.15 0.01 264); /* Base */
+--surface-1: oklch(0.18 0.01 264); /* Cards */
+--surface-2: oklch(0.22 0.01 264); /* Modals */
+--surface-3: oklch(0.26 0.01 264); /* Tooltips */
+```
+
+## 60-30-10 Rule
+
+Applied to **visual weight**, not pixel count:
+
+- 60% dominant (background, surface colors)
+- 30% secondary (text, icons, subtle accents)
+- 10% accent (CTAs, highlights, active states)
+
+Accent works _because_ it's rare — overuse kills its power.
+
+## Common Mistakes
+
+- **Alpha as palette**: Heavy `rgba()` / transparency means incomplete palette — define explicit overlay colors per context
+- **Gray text on colored background**: Use a darker shade of the background color or apply the text color at reduced opacity
+- **Same accent everywhere**: If everything is "primary blue," nothing stands out
+- **Ignoring contrast in dark mode**: WCAG 4.5:1 for body text, 3:1 for large text and UI components

package/dist/template/.opencode/skill/frontend-design/references/design/interaction.md

@@ -0,0 +1,149 @@
+# Interaction Design
+
+## The 8 Interactive States
+
+Every interactive element must design for ALL of these:
+
+| State    | When                  | Visual Treatment                              |
+| -------- | --------------------- | --------------------------------------------- |
+| Default  | Resting               | Base appearance                               |
+| Hover    | Cursor over (desktop) | Subtle shift — color, shadow, or translate    |
+| Focus    | Keyboard navigation   | `:focus-visible` ring (NOT `:focus`)          |
+| Active   | Being pressed/clicked | Compressed/depressed feedback                 |
+| Disabled | Not available         | Reduced opacity (0.5) + `cursor: not-allowed` |
+| Loading  | Processing            | Spinner or skeleton, disable interaction      |
+| Error    | Validation failed     | Red border + error message below              |
+| Success  | Action completed      | Green confirmation, brief                     |
+
+## Focus Management
+
+```css
+/* Remove default focus for mouse, show for keyboard */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+```
+
+**Focus ring rules:**
+
+- 2-3px thick
+- Offset from element edge
+- 3:1 minimum contrast against adjacent colors
+- Consistent style across ALL interactive elements
+
+## Native Dialog + Inert
+
+Use `<dialog>` with the `inert` attribute — eliminates complex focus-trapping JS:
+
+```html
+<dialog id="modal">
+  <form method="dialog">
+    <h2>Confirm action</h2>
+    <button value="cancel">Cancel</button>
+    <button value="confirm">Confirm</button>
+  </form>
+</dialog>
+
+<main id="content">…</main>
+
+<script>
+  const modal = document.getElementById("modal");
+  modal.showModal();
+  document.getElementById("content").inert = true;
+</script>
+```
+
+## Popover API
+
+For tooltips, dropdowns, and popovers — light-dismiss, proper stacking, accessible by default:
+
+```html
+<button popovertarget="menu">Options</button>
+<div id="menu" popover>
+  <button>Edit</button>
+  <button>Delete</button>
+</div>
+```
+
+No z-index wars. No portal wrappers. Built-in light dismiss.
+
+## Form Validation Timing
+
+- **Validate on blur**, not on keystroke (exception: password strength meters)
+- Show errors below the field, not in toast/alert
+- Inline validation: red border + message appears when field loses focus and is invalid
+- Clear error when user starts correcting
+
+## Loading Patterns
+
+| Pattern          | Use When                          | Why                                    |
+| ---------------- | --------------------------------- | -------------------------------------- |
+| Skeleton screens | Page/component loading            | Previews content shape, feels faster   |
+| Inline spinner   | Button action processing          | Keeps context, shows progress          |
+| Progress bar     | Known duration (upload, download) | Sets expectations                      |
+| Optimistic UI    | Low-stakes actions (like, toggle) | Update immediately, sync in background |
+
+**Avoid**: Full-page spinners, blocking modals for non-destructive actions.
+
+## Undo Over Confirmation
+
+Users click through confirmation dialogs mindlessly. Prefer undo:
+
+```
+❌ "Are you sure you want to delete?" → [Cancel] [Delete]
+✅ Item deleted. [Undo] (5 second window)
+```
+
+Exception: irreversible actions with severe consequences (account deletion, payment).
+
+## Touch Target Expansion
+
+Visual size can be small; tap target must be 44x44px minimum:
+
+```css
+.icon-button {
+  width: 24px;
+  height: 24px;
+  position: relative;
+}
+
+.icon-button::before {
+  content: "";
+  position: absolute;
+  inset: -10px; /* Expands tap area to 44x44 */
+}
+```
+
+## Scroll Behavior
+
+```css
+html {
+  scroll-behavior: smooth;
+  scroll-padding-top: 80px; /* Account for sticky header */
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+}
+```
+
+## Z-Index Scale
+
+Named semantic layers prevent z-index wars:
+
+```css
+@theme {
+  --z-dropdown: 10;
+  --z-sticky: 20;
+  --z-modal-backdrop: 30;
+  --z-modal: 40;
+  --z-toast: 50;
+  --z-tooltip: 60;
+}
+```

package/dist/template/.opencode/skill/frontend-design/references/design/typography-rules.md

@@ -0,0 +1,106 @@
+# Typography Rules
+
+## Core Principles
+
+Typography carries hierarchy before color or decoration. Prioritize readability, rhythm, and intent.
+
+- Use a single type scale ratio across the interface
+- Keep body text highly readable before styling display text
+- Limit font families: one display + one body (optional mono for code/data)
+- Use weight and size for hierarchy before using color
+
+## Fluid Type with clamp()
+
+Use fluid sizing for responsive typography without breakpoint jumps:
+
+```css
+@theme {
+  --text-xs: clamp(0.75rem, 0.72rem + 0.15vw, 0.8125rem);
+  --text-sm: clamp(0.875rem, 0.84rem + 0.2vw, 0.9375rem);
+  --text-base: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
+  --text-lg: clamp(1.25rem, 1.15rem + 0.5vw, 1.5rem);
+  --text-xl: clamp(1.5rem, 1.35rem + 0.75vw, 2rem);
+}
+```
+
+Never use fixed `px` for body text.
+
+## Modular Scale
+
+Pick one ratio and stick to it:
+
+- **1.25** (major third) for practical UI
+- **1.333** (perfect fourth) for editorial styles
+
+Limit to 5-7 text sizes. Too many sizes destroys rhythm.
+
+## Line Length and Rhythm
+
+- Body measure: `max-width: 65ch`
+- Comfortable line height: `1.45-1.7` for body text
+- Tight headings: `1.05-1.25`
+- Keep spacing tied to text rhythm (4pt system)
+
+```css
+.article {
+  font-size: var(--text-base);
+  line-height: 1.6;
+  max-width: 65ch;
+}
+```
+
+## Font Selection
+
+Avoid default AI fingerprints:
+
+- Banned as primary display fonts: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, Space Grotesk, system-ui
+
+Preferred directions:
+
+- Sans: Instrument Sans, Plus Jakarta Sans, Outfit, Onest, Figtree, Urbanist
+- Editorial serif: Fraunces, Newsreader
+
+## OpenType Features
+
+Use OpenType intentionally:
+
+```css
+.data-table {
+  font-variant-numeric: tabular-nums;
+}
+
+.recipe {
+  font-variant-numeric: diagonal-fractions;
+}
+
+.abbrev {
+  font-variant-caps: all-small-caps;
+  letter-spacing: 0.04em;
+}
+```
+
+## Dark Mode Typography
+
+Light-on-dark text appears heavier. Adjust:
+
+- Increase line height by `+0.05` to `+0.1`
+- Reduce font weight if text feels too dense
+- Avoid pure white text; use slightly tinted near-white
+
+```css
+@media (prefers-color-scheme: dark) {
+  body {
+    line-height: 1.65;
+    color: oklch(0.93 0.01 264);
+  }
+}
+```
+
+## Quick Audit Checklist
+
+- [ ] Body text uses `rem` or `em`, not `px`
+- [ ] Type scale uses one ratio (1.25 or 1.333)
+- [ ] Body lines capped around 65ch
+- [ ] Headings and body have distinct line-height behavior
+- [ ] OpenType features used for data/fractions/abbreviations where relevant
+- [ ] Dark mode typography adjusted (not just color-inverted)