arkaos 5.3.0 → 5.5.0

package/departments/dev/skills/canvas-generative/references/genjutsu.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Thevon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/departments/dev/skills/css-native/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: dev/css-native
+description: >
+  Zero-dependency animation and visual techniques in modern CSS:
+  scroll-driven animations (scroll and view progress timelines,
+  animation-range), the View Transitions API for SPA and MPA,
+  @starting-style entry effects, anchor positioning, and container
+  queries — each with browser-support fallbacks.
+  TRIGGER: "scroll-driven CSS", "view transitions", "anima sem biblioteca",
+  "CSS puro", "animation-range", "@starting-style", "entry animation sem
+  JS", "/dev css-native".
+  SKIP: React-idiomatic springs, gestures, and exit animations of a
+  component leaving the React tree (unmount) -> dev/framer-motion —
+  enter/exit that only toggles display or visibility on a persistent
+  element stays here (@starting-style + transition-behavior);
+  generative canvas art -> dev/canvas-generative; turning a video into
+  a scroll site -> dev/animated-website.
+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 -->
+
+# CSS Native — `/dev css-native`
+
+> **Agent:** Diana (Frontend Dev) | **Framework:** modern CSS (scroll-driven, view transitions) (genjutsu)
+
+## When to Use CSS Native vs Library
+
+| Situation | Decision |
+|---|---|
+| < 3 animations on the page | CSS native |
+| Scroll-driven reveal/parallax | CSS native (`animation-timeline`) |
+| Enter/exit from `display: none` | CSS native (`@starting-style` + `transition-behavior: allow-discrete`) |
+| Tooltip/popover positioning | CSS native (anchor positioning) |
+| Page transitions (MPA or SPA) | CSS native (View Transitions API) |
+| Complex multi-step timeline (5+ tweens) | GSAP |
+| Stagger across dynamic list (unknown count) | GSAP or Framer Motion |
+| Physics-based spring with interruption | Framer Motion |
+| Morph between SVG shapes | GSAP MorphSVG |
+
+Rule of thumb: if you can express it in a `@keyframes` + one `animation-timeline`, stay in CSS. The moment you need imperative control, sequence coordination, or runtime values — reach for a library.
+
+---
+
+## Scroll-Driven Animations
+
+### Scroll Progress Timeline
+
+Animate based on scroll position of a container.
+
+```css
+.progress-bar {
+  animation: grow-width linear both;
+  animation-timeline: scroll(root block);
+}
+
+@keyframes grow-width {
+  from { transform: scaleX(0); }
+  to   { transform: scaleX(1); }
+}
+```
+
+- `scroll(<scroller> <axis>)` — scroller: `nearest` | `root` | `self`, axis: `block` | `inline` | `x` | `y`
+- Default: `scroll(nearest block)`
+
+### View Progress Timeline
+
+Animate as an element enters/exits the scrollport.
+
+```css
+.reveal {
+  animation: fade-in linear both;
+  animation-timeline: view();
+  animation-range: entry 0% entry 100%;
+}
+
+@keyframes fade-in {
+  from { opacity: 0; transform: translateY(2rem); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+```
+
+### animation-range
+
+Controls which segment of the timeline drives the animation.
+
+```css
+/* Named ranges: cover | contain | entry | exit | entry-crossing | exit-crossing */
+animation-range: entry 0% entry 100%;    /* animate during entry only */
+animation-range: contain 0% contain 100%; /* animate while fully visible */
+animation-range: entry 25% exit 75%;      /* custom start/end */
+```
+
+Use the [Scroll-driven Animations tool](https://scroll-driven-animations.style/tools/view-timeline/ranges/) to visualize ranges interactively.
+
+---
+
+## View Transitions API
+
+### Same-Document (SPA)
+
+```js
+document.startViewTransition(() => {
+  // Update the DOM synchronously
+  updateContent();
+});
+```
+
+```css
+/* Control the transition animation */
+::view-transition-old(root) {
+  animation: fade-out 200ms ease-out;
+}
+::view-transition-new(root) {
+  animation: fade-in 300ms ease-in;
+}
+
+/* Named transitions for specific elements */
+.hero-image { view-transition-name: hero; }
+
+::view-transition-group(hero) {
+  animation-duration: 400ms;
+  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+### Cross-Document (MPA)
+
+```css
+/* Both pages need this */
+@view-transition { navigation: auto; }
+
+/* Outgoing page */
+.card { view-transition-name: card-detail; }
+
+/* Incoming page */
+.detail-hero { view-transition-name: card-detail; }
+```
+
+### view-transition-class (group styling)
+
+```css
+.card { view-transition-class: card; }
+
+::view-transition-group(*.card) {
+  animation-duration: 350ms;
+  animation-timing-function: var(--ease-spring);
+}
+```
+
+---
+
+## @starting-style
+
+Native enter animations from `display: none` — no JS timing hacks.
+
+```css
+.dialog {
+  opacity: 1;
+  transform: translateY(0);
+  transition: opacity 300ms ease, transform 300ms ease,
+              display 300ms allow-discrete;
+
+  @starting-style {
+    opacity: 0;
+    transform: translateY(-1rem);
+  }
+}
+
+.dialog[hidden] {
+  opacity: 0;
+  transform: translateY(-1rem);
+  display: none;
+}
+```
+
+Key rules:
+- `transition-behavior: allow-discrete` (or shorthand `allow-discrete` in the transition) enables transitioning `display` and `overlay`
+- `@starting-style` block defines the "from" state when the element first renders
+- Combine with `[popover]` and `<dialog>` for native modals with zero JS animation code
+
+---
+
+## Anchor Positioning
+
+CSS-native positioning of tooltips, popovers, and floating UI relative to a trigger.
+
+```css
+.trigger {
+  anchor-name: --my-trigger;
+}
+
+.tooltip {
+  position: fixed;
+  position-anchor: --my-trigger;
+  position-area: top center;
+  margin-bottom: 0.5rem;
+
+  /* Fallback if no space on top */
+  position-try-fallbacks: --bottom;
+}
+
+@position-try --bottom {
+  position-area: bottom center;
+  margin-top: 0.5rem;
+}
+```
+
+Combine with `@starting-style` for animated tooltips:
+
+```css
+.tooltip[popover]:popover-open {
+  opacity: 1;
+  transform: scale(1);
+  transition: opacity 150ms ease, transform 150ms ease,
+              display 150ms allow-discrete, overlay 150ms allow-discrete;
+
+  @starting-style {
+    opacity: 0;
+    transform: scale(0.96);
+  }
+}
+```
+
+---
+
+## Container Queries + Contextual Animations
+
+Adapt animations to the component's container size, not the viewport.
+
+```css
+.card-container {
+  container-type: inline-size;
+  container-name: card;
+}
+
+@container card (min-width: 400px) {
+  .card-content {
+    animation: slide-in-right 400ms var(--ease-out-expo);
+  }
+}
+
+@container card (max-width: 399px) {
+  .card-content {
+    animation: fade-in 300ms ease;
+  }
+}
+```
+
+Container-relative units in keyframes:
+
+```css
+@keyframes slide-in-right {
+  from { transform: translateX(10cqw); opacity: 0; }
+  to   { transform: translateX(0); opacity: 1; }
+}
+```
+
+---
+
+## Advanced Visual Techniques
+
+### clip-path Transitions
+
+```css
+.reveal {
+  clip-path: inset(0 100% 0 0);
+  transition: clip-path 600ms cubic-bezier(0.77, 0, 0.175, 1);
+}
+.reveal.visible {
+  clip-path: inset(0 0 0 0);
+}
+```
+
+Shape morphing: transition between `circle()`, `ellipse()`, `polygon()`, `inset()` — as long as the function type and point count match.
+
+### backdrop-filter
+
+```css
+.glass {
+  background: oklch(0.98 0.01 250 / 0.6);
+  backdrop-filter: blur(12px) saturate(1.8);
+  -webkit-backdrop-filter: blur(12px) saturate(1.8); /* Safari */
+}
+```
+
+### mix-blend-mode
+
+```css
+.overlay-text {
+  mix-blend-mode: difference;
+  color: white; /* inverts over any background */
+}
+```
+
+### Mesh Gradients (approximated)
+
+```css
+.mesh {
+  background:
+    radial-gradient(at 20% 30%, oklch(0.7 0.2 310) 0%, transparent 50%),
+    radial-gradient(at 80% 60%, oklch(0.6 0.18 250) 0%, transparent 50%),
+    radial-gradient(at 50% 80%, oklch(0.75 0.15 170) 0%, transparent 50%),
+    oklch(0.15 0.02 280);
+}
+```
+
+### conic-gradient Effects
+
+```css
+.spinner {
+  background: conic-gradient(from 0deg, transparent 0%, oklch(0.7 0.15 250) 100%);
+  border-radius: 50%;
+  mask: radial-gradient(farthest-side, transparent calc(100% - 4px), black calc(100% - 4px));
+  animation: spin 1s linear infinite;
+}
+```
+
+---
+
+## Do Not
+
+| BAD | GOOD | Why |
+|---|---|---|
+| `transition: all 300ms` | `transition: opacity 300ms, transform 300ms` | `all` triggers transitions on every property change, causes unexpected animations, and prevents browser optimization |
+| Animate `width`, `height`, `top`, `left` | Animate `transform`, `opacity`, `clip-path`, `filter` | Layout-triggering properties force reflow on every frame — composite-only properties run on GPU |
+| Scroll-driven animations without fallback | `@supports (animation-timeline: scroll()) { ... }` | Firefox only added support in v128+, older Safari versions lack support |
+| `@starting-style` without `transition-behavior` | Always pair with `allow-discrete` for display/overlay | Without it, `display: none` transitions are skipped entirely |
+| Anchor positioning without `position-try-fallbacks` | Always define fallback positions | Element clips out of viewport if primary position has no space |
+| `animation-fill-mode: forwards` on scroll-driven | Use `both` for scroll-driven animations | `forwards` can lock the element in its final state even when scrolling back |
+
+---
+
+## Deep dive
+
+| Need | Reference |
+|---|---|
+| Browser-support tables, fallback patterns and progressive-enhancement strategies for scroll-driven animations, View Transitions, `@starting-style`, anchor positioning and container queries (plus accessibility and performance notes) | `references/modern-css.md` |
+
+## Output
+
+The CSS (and minimal HTML hooks) implementing the effect with
+progressive-enhancement fallbacks from `references/modern-css.md`, and a
+note of the browser floor it degrades gracefully below.

package/departments/dev/skills/css-native/references/genjutsu.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Thevon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.