arkaos 5.4.0 → 5.5.0

package/departments/dev/skills/css-native/references/modern-css.md

@@ -0,0 +1,465 @@
+# Modern CSS — Browser Support, Fallbacks & Progressive Enhancement
+
+> Last verified: March 2026
+
+---
+
+## Browser Support Tables
+
+### Scroll-Driven Animations (`animation-timeline`)
+
+| Browser | Version | Status |
+|---|---|---|
+| Chrome | 115+ | Supported |
+| Edge | 115+ | Supported |
+| Firefox | 128+ | Supported (shipped July 2024) |
+| Safari | 18.4+ | Supported (shipped early 2025) |
+
+**Global coverage**: ~90%+ (as of March 2026)
+
+### View Transitions API
+
+| Feature | Chrome | Edge | Firefox | Safari |
+|---|---|---|---|---|
+| Same-document (`startViewTransition`) | 111+ | 111+ | 133+ | 18+ |
+| Cross-document (`@view-transition`) | 126+ | 126+ | Not yet | 18.2+ |
+| `view-transition-class` | 125+ | 125+ | Not yet | 18.2+ |
+
+**Note**: Cross-document view transitions are an Interop 2026 focus area — Firefox support expected to land in 2026.
+
+### @starting-style
+
+| Browser | Version | Status |
+|---|---|---|
+| Chrome | 117+ | Supported |
+| Edge | 117+ | Supported |
+| Firefox | 129+ | Supported |
+| Safari | 17.5+ | Supported |
+
+**Global coverage**: ~93%+ — Baseline Newly Available (2024)
+
+### CSS Anchor Positioning
+
+| Browser | Version | Status |
+|---|---|---|
+| Chrome | 125+ | Supported |
+| Edge | 125+ | Supported |
+| Firefox | Nightly | In development (Interop 2026) |
+| Safari | 26+ | Supported (shipped 2026) |
+
+**Note**: Anchor positioning is an Interop 2026 focus area. Firefox expected to ship stable support in 2026.
+
+### Container Queries
+
+| Feature | Chrome | Edge | Firefox | Safari |
+|---|---|---|---|---|
+| Size queries (`@container`) | 105+ | 105+ | 110+ | 16+ |
+| Container-relative units (`cqw`, `cqh`) | 105+ | 105+ | 110+ | 16+ |
+| Style queries (`@container style()`) | 111+ | 111+ | Not yet | 18+ |
+
+**Global coverage (size queries)**: ~95%+
+
+---
+
+## Fallback Patterns
+
+### Scroll-Driven Animations
+
+```css
+/* Base: no scroll animation, element is always visible */
+.reveal {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* Progressive enhancement for supporting browsers */
+@supports (animation-timeline: scroll()) {
+  .reveal {
+    animation: reveal-up linear both;
+    animation-timeline: view();
+    animation-range: entry 10% entry 90%;
+  }
+
+  @keyframes reveal-up {
+    from {
+      opacity: 0;
+      transform: translateY(2rem);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+}
+```
+
+**Strategy**: Content is always visible by default. Scroll animation is purely decorative enhancement. Never hide content behind a scroll-driven animation without fallback.
+
+### View Transitions (Same-Document)
+
+```js
+function navigate(updateFn) {
+  // Fallback: just update the DOM instantly
+  if (!document.startViewTransition) {
+    updateFn();
+    return;
+  }
+
+  document.startViewTransition(() => updateFn());
+}
+```
+
+```css
+/* Only apply transition styles if supported */
+@supports (view-transition-name: none) {
+  .hero { view-transition-name: hero; }
+
+  ::view-transition-old(hero) {
+    animation: fade-scale-out 250ms ease-out both;
+  }
+  ::view-transition-new(hero) {
+    animation: fade-scale-in 300ms ease-in both;
+  }
+}
+```
+
+### View Transitions (Cross-Document)
+
+```css
+/* This rule is safely ignored by browsers that don't support it */
+@view-transition {
+  navigation: auto;
+}
+
+/* Guard transition-specific styles */
+@supports (view-transition-name: none) {
+  .page-header { view-transition-name: header; }
+  .main-content { view-transition-name: content; }
+
+  ::view-transition-group(header) {
+    animation-duration: 300ms;
+  }
+  ::view-transition-group(content) {
+    animation-duration: 250ms;
+  }
+}
+```
+
+**Strategy**: Pages load normally in unsupported browsers. The `@view-transition` rule is unknown and ignored — no breakage.
+
+### @starting-style
+
+```css
+/* Broad support — but guard with @supports for very old browsers */
+.popover {
+  opacity: 1;
+  transform: scale(1);
+  transition: opacity 200ms ease, transform 200ms ease;
+}
+
+/* @starting-style is baseline — this works in all modern browsers */
+.popover {
+  @starting-style {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+
+/* For the display transition, check discrete support */
+@supports (transition-behavior: allow-discrete) {
+  .popover {
+    transition: opacity 200ms ease, transform 200ms ease,
+                display 200ms allow-discrete, overlay 200ms allow-discrete;
+  }
+
+  .popover:not(:popover-open) {
+    opacity: 0;
+    transform: scale(0.95);
+    display: none;
+  }
+}
+```
+
+**Strategy**: `@starting-style` itself is well-supported. The main concern is `transition-behavior: allow-discrete` for `display`/`overlay` transitions. Guard that part specifically.
+
+### Anchor Positioning
+
+```css
+/* Feature detection for anchor positioning */
+@supports (anchor-name: --a) {
+  .trigger { anchor-name: --trigger; }
+
+  .tooltip {
+    position: fixed;
+    position-anchor: --trigger;
+    position-area: top center;
+    margin-bottom: 0.5rem;
+
+    position-try-fallbacks: --bottom;
+  }
+
+  @position-try --bottom {
+    position-area: bottom center;
+    margin-top: 0.5rem;
+  }
+}
+
+/* Fallback for unsupported browsers: manual absolute positioning */
+@supports not (anchor-name: --a) {
+  .tooltip-wrapper {
+    position: relative;
+  }
+
+  .tooltip {
+    position: absolute;
+    bottom: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    margin-bottom: 0.5rem;
+  }
+}
+```
+
+**Strategy**: Use `@supports (anchor-name: --a)` to detect. Provide a classic `position: absolute` fallback. For JS-heavy apps, Floating UI remains a solid fallback.
+
+### Container Queries
+
+```css
+/* Container queries are baseline — safe for production */
+.card-wrapper {
+  container-type: inline-size;
+  container-name: card;
+}
+
+/* Size queries: well supported */
+@container card (min-width: 400px) {
+  .card { flex-direction: row; }
+}
+
+/* Style queries: Chrome/Edge/Safari only — use with care */
+@supports (container-type: inline-size) {
+  /* Size queries are safe — 95%+ coverage */
+}
+
+/* Style queries: progressive enhancement only */
+@container style(--theme: dark) {
+  .card { background: oklch(0.2 0.02 250); }
+}
+/* Fallback: use a class or media query for unsupported browsers */
+```
+
+---
+
+## Progressive Enhancement Strategies
+
+### Strategy 1: Layered Animation (Recommended)
+
+Build in layers — each layer adds richness but nothing breaks without it.
+
+```css
+/* Layer 0: Content is visible, no animation */
+.section-title {
+  opacity: 1;
+}
+
+/* Layer 1: Simple transition (universally supported) */
+.section-title {
+  transition: opacity 400ms ease, transform 400ms ease;
+}
+.section-title.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+
+/* Layer 2: Scroll-driven (modern browsers only) */
+@supports (animation-timeline: scroll()) {
+  .section-title {
+    animation: reveal linear both;
+    animation-timeline: view();
+    animation-range: entry 0% entry 80%;
+    /* Remove the JS-toggled class approach */
+    transition: none;
+  }
+
+  @keyframes reveal {
+    from { opacity: 0; transform: translateY(1.5rem); }
+    to   { opacity: 1; transform: translateY(0); }
+  }
+}
+```
+
+### Strategy 2: View Transition as Enhancement
+
+```js
+// Router integration example (works with any framework)
+async function navigateTo(url) {
+  const response = await fetch(url);
+  const html = await response.text();
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(html, 'text/html');
+
+  const updateDOM = () => {
+    document.title = doc.title;
+    document.querySelector('main').replaceWith(
+      doc.querySelector('main')
+    );
+  };
+
+  if (document.startViewTransition) {
+    document.startViewTransition(updateDOM);
+  } else {
+    updateDOM();
+  }
+}
+```
+
+```css
+/* Cross-document: progressive by nature */
+@view-transition { navigation: auto; }
+
+/* Reduce motion: respect user preferences */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation-duration: 0.01ms !important;
+  }
+}
+```
+
+### Strategy 3: @starting-style + Popover API
+
+Full native modal with enter/exit animation, zero JavaScript.
+
+```html
+<button popovertarget="menu">Open</button>
+
+<div id="menu" popover>
+  <p>Menu content</p>
+</div>
+```
+
+```css
+[popover] {
+  /* Open state */
+  opacity: 1;
+  transform: translateY(0) scale(1);
+  transition: opacity 250ms ease, transform 250ms ease,
+              display 250ms allow-discrete, overlay 250ms allow-discrete;
+
+  /* Entry animation */
+  @starting-style {
+    opacity: 0;
+    transform: translateY(-0.5rem) scale(0.97);
+  }
+}
+
+/* Exit animation */
+[popover]:not(:popover-open) {
+  opacity: 0;
+  transform: translateY(-0.5rem) scale(0.97);
+}
+```
+
+### Strategy 4: Anchor + Popover Combo (Animated Tooltip)
+
+```html
+<button anchor="tip" popovertarget="tip">Hover me</button>
+
+<div id="tip" popover="hint" anchor="trigger">
+  Tooltip content
+</div>
+```
+
+```css
+[popover="hint"] {
+  position: fixed;
+  position-anchor: --trigger;
+  position-area: top center;
+  margin-bottom: 0.5rem;
+
+  /* Animation */
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 150ms ease, transform 150ms ease,
+              display 150ms allow-discrete, overlay 150ms allow-discrete;
+
+  @starting-style {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+
+  position-try-fallbacks: --bottom, --left, --right;
+}
+
+@position-try --bottom {
+  position-area: bottom center;
+  margin-top: 0.5rem;
+}
+@position-try --left {
+  position-area: left center;
+  margin-right: 0.5rem;
+}
+@position-try --right {
+  position-area: right center;
+  margin-left: 0.5rem;
+}
+
+/* Respect reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  [popover="hint"] {
+    transition-duration: 0.01ms;
+  }
+}
+```
+
+---
+
+## Accessibility Checklist
+
+```css
+/* ALWAYS include this in any project with animations */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+For scroll-driven animations specifically:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .reveal {
+    animation: none;
+    opacity: 1;
+    transform: none;
+  }
+}
+```
+
+---
+
+## Performance Notes
+
+| Property | Rendering Cost | GPU Composited |
+|---|---|---|
+| `transform` | Low | Yes |
+| `opacity` | Low | Yes |
+| `filter` / `backdrop-filter` | Medium | Yes |
+| `clip-path` | Medium | Yes (in most browsers) |
+| `background` (gradients) | Medium | No — repaint |
+| `width` / `height` | High | No — reflow + repaint |
+| `top` / `left` / `right` / `bottom` | High | No — reflow + repaint |
+| `box-shadow` | High | No — repaint |
+
+Best practices:
+- Use `will-change` sparingly and only on elements about to animate — never `will-change: transform` on 50 elements
+- Prefer `translate`, `scale`, `rotate` individual properties over `transform` shorthand when only one axis changes (allows independent transitions)
+- For scroll-driven animations, the browser automatically optimizes — no `will-change` needed
+- Test with Chrome DevTools > Rendering > "Highlight areas outside the compositing layers" to verify GPU compositing

package/departments/dev/skills/framer-motion/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: dev/framer-motion
+description: >
+  Framer Motion for React: AnimatePresence exit animations, layout
+  animations with stable keys, variant propagation and orchestration,
+  gestures, and motion values that update without re-render — plus the
+  decision rule for when NOT to use it.
+  TRIGGER: "framer motion", "motion for React", "AnimatePresence", "layout
+  animation", "anima este componente React", "exit animation", "/dev
+  framer-motion".
+  SKIP: the same effect achievable in pure CSS (scroll-driven, view
+  transitions, entry effects) -> dev/css-native (zero dependency beats a
+  library); generative canvas work -> dev/canvas-generative.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
+metadata:
+  origin: community
+  source: https://github.com/AThevon/genjutsu
+  license: MIT
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Framer Motion — `/dev framer-motion`
+
+> **Agent:** Diana (Frontend Dev) | **Framework:** Framer Motion (genjutsu)
+
+> Package: `motion` (v11+, formerly `framer-motion`). Import: `import { motion, AnimatePresence } from "motion/react"`
+
+## When to use Framer Motion vs alternatives
+
+| Criteria | Framer Motion | GSAP | Native CSS |
+|---------|--------------|------|-----------|
+| Layout animations | Excellent (layoutId) | Manual | Impossible |
+| Exit animations | AnimatePresence | Timeline reverse | Limited (display) |
+| Gestures (drag, hover) | Native, declarative | Draggable plugin | Basic |
+| Scroll-driven | useScroll + useTransform | ScrollTrigger (more powerful) | scroll-timeline |
+| Complex orchestration | Variants + propagation | Timeline (more flexible) | @keyframes |
+| Bundle size | ~50kb tree-shaken | ~30kb core | 0kb |
+| React integration | Native, component-first | Refs + useGSAP | className toggle |
+
+**Rule**: Framer Motion for React UI interactions (modals, toasts, reorder, shared layout). GSAP for complex timelines, cinematic scroll-driven, SVG morphing.
+
+## AnimatePresence — Exit animations
+
+```tsx
+<AnimatePresence mode="wait">
+  {isVisible && (
+    <motion.div
+      key="unique-key"        // REQUIRED — identifies the component
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      exit={{ opacity: 0 }}
+    />
+  )}
+</AnimatePresence>
+```
+
+- `mode="wait"` — waits for exit to finish before enter (page transitions)
+- `mode="sync"` — exit and enter simultaneously
+- `mode="popLayout"` — removes from flow immediately (good for lists)
+- `onExitComplete` — callback when all exit animations are finished
+
+## Layout animations
+
+```tsx
+// Shared layout — the element "slides" between two positions
+<motion.div layoutId="highlight" className={activeTab === id ? "active" : ""} />
+
+// Auto layout — animates position/size when layout changes
+<motion.div layout>
+  {isExpanded && <motion.p layout>Additional content</motion.p>}
+</motion.div>
+
+// layout="position" — animates position only (not size)
+// layout="size" — animates size only
+// layout="preserve-aspect" — preserves the ratio during the transition
+```
+
+## Variants — Propagation and orchestration
+
+```tsx
+const container = {
+  hidden: { opacity: 0 },
+  show: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.08,
+      delayChildren: 0.2,
+      staggerDirection: 1,    // 1 = normal, -1 = reverse
+    },
+  },
+};
+
+const item = {
+  hidden: { opacity: 0, y: 20 },
+  show: { opacity: 1, y: 0 },
+};
+
+<motion.ul variants={container} initial="hidden" animate="show">
+  {items.map((i) => (
+    <motion.li key={i.id} variants={item} />
+  ))}
+</motion.ul>
+```
+
+Variants **automatically propagate** to motion children — no need for `initial`/`animate` on children.
+
+## Gestures
+
+```tsx
+<motion.div
+  whileHover={{ scale: 1.05 }}
+  whileTap={{ scale: 0.95 }}
+  whileFocus={{ borderColor: "#3b82f6" }}
+  // Drag
+  drag               // true = x+y, "x" = horizontal only, "y" = vertical only
+  dragConstraints={{ left: -100, right: 100, top: -50, bottom: 50 }}
+  dragElastic={0.2}  // 0 = rigid, 1 = free (default 0.35)
+  dragSnapToOrigin   // returns to initial position
+  onDragEnd={(e, info) => {
+    if (info.offset.x > 100) handleSwipe("right");
+  }}
+/>
+```
+
+## Motion values — Reactive without re-render
+
+```tsx
+const x = useMotionValue(0);
+const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0]);
+const background = useTransform(x, [-200, 200], ["#ff0000", "#00ff00"]);
+
+// Spring-based smoothing
+const smoothX = useSpring(x, { stiffness: 300, damping: 30 });
+
+// Scroll tracking
+const { scrollY, scrollYProgress } = useScroll();
+const parallaxY = useTransform(scrollYProgress, [0, 1], [0, -300]);
+
+// Element-scoped scroll
+const ref = useRef(null);
+const { scrollYProgress } = useScroll({
+  target: ref,
+  offset: ["start end", "end start"],
+});
+```
+
+**Motion values do NOT trigger React re-renders** — they update the DOM directly via `style`.
+
+## Do Not
+
+### Do not setState in callbacks without a guard
+
+```tsx
+// BAD — infinite re-render if animate depends on state
+onUpdate={(latest) => setPosition(latest.x)}
+
+// GOOD — guard or useMotionValueEvent
+const x = useMotionValue(0);
+useMotionValueEvent(x, "change", (latest) => {
+  if (latest > threshold) onThresholdReached();
+});
+```
+
+### Do not use layout animation without a stable key
+
+```tsx
+// BAD — key changes every render, breaks layout tracking
+<motion.div layout key={Math.random()} />
+
+// GOOD — stable key derived from data
+<motion.div layout key={item.id} />
+```
+
+### Do not forget the unique key on AnimatePresence
+
+```tsx
+// BAD — no key, exit animation does not trigger
+<AnimatePresence>
+  {isOpen && <motion.div exit={{ opacity: 0 }} />}
+</AnimatePresence>
+
+// GOOD — unique key for each conditional child
+<AnimatePresence>
+  {isOpen && <motion.div key="modal" exit={{ opacity: 0 }} />}
+</AnimatePresence>
+```
+
+### Do not wrap an already animated component with motion.div
+
+```tsx
+// BAD — double animation, transform conflicts
+<motion.div animate={{ x: 100 }}>
+  <motion.div animate={{ x: -50 }}>Content</motion.div>
+</motion.div>
+
+// GOOD — single animation level per transform axis
+<motion.div animate={{ x: 100 }}>
+  <motion.div animate={{ opacity: 0.5 }}>Content</motion.div>
+</motion.div>
+
+// GOOD — use variants to coordinate parent/child
+<motion.div variants={parent} animate="active">
+  <motion.div variants={child} />
+</motion.div>
+```
+
+## Deep dive
+
+| Need | Reference |
+|---|---|
+| Full API reference — motion props (animation, gestures, drag, layout, lifecycle), AnimatePresence modes, transition configuration and ease presets, and the hooks (`useMotionValue`, `useTransform`, `useSpring`, `useScroll`) | `references/api.md` |
+
+## Output
+
+The motion-wrapped React component(s) with stable keys, variants where
+parent/child coordinate, and gesture guards — plus the reason Framer
+Motion was the right tier for this effect rather than CSS.