@jaimevalasek/aioson 1.5.1 → 1.6.0

package/template/.aioson/skills/design/glassmorphism-ui/references/motion.md

@@ -0,0 +1,355 @@
+# Motion — Glassmorphism UI
+
+Animation and transition specifications. Glass motion is defined by blur transitions, opacity shifts, and fluid easing — not bounce or spring.
+
+---
+
+## Principles
+
+- **Fluid**: movements smooth as a surface of water. Generous ease-out, never bounce, never overshoot.
+- **Layered**: animations respect the depth layers — elements closer to the user animate faster than those further away. Cards animate faster than the background gradient.
+- **Luminous**: opacity and blur transitions are first-class citizens (not just position/scale). The "frosting" of a surface appearing or disappearing is a core motion type.
+- **Effortless**: nothing should look like it is "trying". Natural movements, no dramatic entrances unless the product is explicitly theatrical (media player, landing hero).
+
+---
+
+## Timing Tokens
+
+```css
+--transition-fast:  120ms ease;
+--transition-base:  200ms ease;
+--transition-slow:  350ms cubic-bezier(0.16, 1, 0.3, 1);
+--transition-glass: backdrop-filter 300ms ease,
+                    background 300ms ease,
+                    border-color 300ms ease,
+                    box-shadow 300ms ease;
+--transition-hero:  600ms cubic-bezier(0.16, 1, 0.3, 1);
+```
+
+`cubic-bezier(0.16, 1, 0.3, 1)` is the smooth deceleration curve — fast start, elegant stop. Use it for entrances and meaningful state changes. Use `ease` for hover/micro-interactions.
+
+---
+
+## Entrance Animations
+
+### 1. Glass Fade In
+Card appears as if condensing from air — opacity and blur materialize simultaneously.
+
+```css
+@keyframes glass-fade-in {
+  from {
+    opacity: 0;
+    backdrop-filter: blur(0px);
+  }
+  to {
+    opacity: 1;
+    backdrop-filter: var(--glass-blur-md);
+  }
+}
+.glass-fade-in {
+  animation: glass-fade-in 400ms ease-out forwards;
+}
+```
+
+Use for: initial page load of glass cards, modal appearance.
+
+### 2. Float Up
+Card floats up and materializes — the primary entrance for dashboards and stagger lists.
+
+```css
+@keyframes float-up {
+  from {
+    opacity: 0;
+    transform: translateY(16px);
+    backdrop-filter: blur(0px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    backdrop-filter: var(--glass-blur-md);
+  }
+}
+.float-up {
+  animation: float-up 450ms cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+```
+
+Use for: dashboard cards on load, stagger card groups, stat cards appearing.
+
+### 3. Scale Materialize
+Element scales up from 95% and solidifies — for modals, dropdowns, and menus.
+
+```css
+@keyframes scale-materialize {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+    backdrop-filter: blur(0px);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+    backdrop-filter: var(--glass-blur-lg);
+  }
+}
+.scale-materialize {
+  animation: scale-materialize 350ms cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+```
+
+Use for: modal open, dropdown menu, context menu, tooltip appearance.
+
+### 4. Glass Slide
+Slides in from a direction and materializes — for drawers, panels, and side sheets.
+
+```css
+@keyframes glass-slide-right {
+  from {
+    opacity: 0;
+    transform: translateX(-20px);
+    backdrop-filter: blur(0px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+    backdrop-filter: var(--glass-blur-lg);
+  }
+}
+@keyframes glass-slide-up {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+    backdrop-filter: blur(0px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    backdrop-filter: var(--glass-blur-lg);
+  }
+}
+```
+
+Use for: sidebar opening (slide-right), bottom sheet (slide-up on mobile), toast notifications (slide-up from bottom-right).
+
+### 5. Orb Pulse
+Background decorative gradient orbs appear softly — for landing pages and auth pages.
+
+```css
+@keyframes orb-pulse {
+  from {
+    opacity: 0;
+    transform: scale(0.8);
+  }
+  to {
+    opacity: 0.45;
+    transform: scale(1);
+  }
+}
+.orb {
+  animation: orb-pulse 800ms ease-out forwards;
+}
+```
+
+Use for: decorative gradient blobs on landing pages, auth backgrounds. These should be slow and atmospheric.
+
+---
+
+## Glass-Specific Animations
+
+### 1. Blur Shift (nav on scroll)
+Navigation glass becomes more opaque and blurred as the user scrolls — structural, not decorative.
+
+```css
+/* Applied via JS, toggling a class based on scrollY */
+.nav-bar {
+  background: var(--glass-bg);
+  transition: var(--transition-glass);
+}
+.nav-bar.scrolled {
+  background: var(--glass-bg-hover);
+}
+.nav-bar.deep-scrolled {
+  background: var(--glass-bg-active);
+}
+```
+
+Breakpoints: `scrollY > 20` → scrolled, `scrollY > 80` → deep-scrolled.
+
+### 2. Opacity Frost (card hover)
+The card's glass becomes more opaque on hover — the primary hover behavior for all glass cards.
+
+```css
+.glass-card {
+  background: var(--glass-bg);
+  box-shadow: var(--shadow-sm), var(--shadow-inner);
+  transition: var(--transition-glass);
+}
+.glass-card:hover {
+  background: var(--glass-bg-hover);
+  box-shadow: var(--shadow-md), var(--shadow-inner);
+}
+```
+
+Duration: 200ms — fast enough to feel responsive, slow enough to feel smooth.
+
+### 3. Glow Pulse (featured/highlighted elements)
+Subtle accent glow pulsing for featured cards, stat heroes, and highlighted elements.
+
+```css
+@keyframes glow-pulse {
+  0%, 100% { box-shadow: var(--shadow-md), 0 0 20px rgba(124, 58, 237, 0.10); }
+  50%       { box-shadow: var(--shadow-md), 0 0 40px rgba(124, 58, 237, 0.20); }
+}
+.glass-card--glow {
+  animation: glow-pulse 2s ease-in-out infinite;
+}
+```
+
+Use sparingly — only for the 1 "hero" element per screen. Not for every card.
+
+### 4. Shimmer (skeleton loaders)
+Gradient light sweeping across glass surface — the loading state for glass components.
+
+```css
+@keyframes shimmer {
+  to { transform: translateX(100%); }
+}
+.skeleton {
+  position: relative;
+  overflow: hidden;
+  background: var(--glass-bg);
+}
+.skeleton::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    rgba(255, 255, 255, 0.10) 50%,
+    transparent 100%
+  );
+  transform: translateX(-100%);
+  animation: shimmer 1.5s infinite;
+}
+```
+
+### 5. Aurora Shift (animated background — landing only)
+Very slow color hue shift on the aurora gradient background.
+
+```css
+@keyframes aurora-shift {
+  0%   { filter: hue-rotate(0deg); }
+  50%  { filter: hue-rotate(15deg); }
+  100% { filter: hue-rotate(0deg); }
+}
+body[data-aurora] {
+  animation: aurora-shift 10s ease-in-out infinite;
+}
+```
+
+Constraint: only use on landing pages. Never inside apps or dashboards. Keep cycle slow (8-12s). Intensity very low (max 20deg hue rotation).
+
+---
+
+## Stagger
+
+When animating multiple cards into view simultaneously:
+
+- **Delay per item**: 50ms (between warm-craft at 60ms and clean-saas at 40ms)
+- **Maximum stagger group**: 6 items
+- **Default animation**: `float-up` with staggered delay
+- **Implementation**: CSS custom property or inline `animation-delay`
+
+```css
+.stagger-item:nth-child(1) { animation-delay: 0ms; }
+.stagger-item:nth-child(2) { animation-delay: 50ms; }
+.stagger-item:nth-child(3) { animation-delay: 100ms; }
+.stagger-item:nth-child(4) { animation-delay: 150ms; }
+.stagger-item:nth-child(5) { animation-delay: 200ms; }
+.stagger-item:nth-child(6) { animation-delay: 250ms; }
+```
+
+---
+
+## Hover States (summary)
+
+| Element | Hover behavior | Duration |
+|---------|---------------|----------|
+| Glass Card | `glass-bg` → `glass-bg-hover` + `shadow-sm` → `shadow-md` | 200ms |
+| Primary Button | `brightness(1.05)` + `shadow-sm` → `shadow-md` | 120ms |
+| Glass Button | `glass-bg` → `glass-bg-hover` | 120ms |
+| Nav items (sidebar) | `transparent` → `glass-bg-hover` | 150ms |
+| Nav links (website) | `text-secondary` → `text-heading` | 150ms |
+| Logo cloud | `grayscale opacity-50` → `color opacity-100` | 200ms |
+| Links | underline opacity `0` → `1` | 150ms |
+| Images in glass frame | `scale(1)` → `scale(1.02)` inside `overflow: hidden` | 300ms |
+
+---
+
+## Scroll Animations (websites only)
+
+### Parallax Orbs
+Background gradient orbs move at a slower rate than the scroll:
+```css
+/* Applied via JS with requestAnimationFrame */
+.orb {
+  transform: translateY(calc(var(--scroll-y) * 0.3px));
+}
+```
+Multiplier: 0.3-0.5 (orbs move at 30-50% of scroll speed).
+
+### Section Reveal
+Glass cards and sections fade up as they enter the viewport:
+```javascript
+const observer = new IntersectionObserver(
+  (entries) => entries.forEach(e => {
+    if (e.isIntersecting) e.target.classList.add('float-up');
+  }),
+  { threshold: 0.1 }
+);
+document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
+```
+Threshold: 0.1 — triggers when 10% of element is visible.
+
+### Nav Frost (scroll-triggered)
+Navigation glass increases opacity as scroll position increases — see Blur Shift above.
+
+---
+
+## Page Transitions
+
+| Transition | In | Out |
+|-----------|-----|-----|
+| Route change (SPA) | `glass-fade-in` 350ms + `float-up` 350ms | `opacity` 0, 200ms |
+| Modal open | `scale-materialize` 300ms | `opacity + scale(0.97)` 150ms |
+| Bottom sheet open | `glass-slide-up` 350ms | `glass-slide-up` reversed 250ms |
+| Tab content | `opacity 0→1` 200ms | `opacity 1→0` 150ms |
+| Toast in | `glass-slide-up` 350ms | `opacity 1→0 + translateY(8px)` 200ms |
+| Dropdown open | `scale-materialize` 200ms | `opacity 1→0 + scale(0.97)` 150ms |
+
+---
+
+## Reduced Motion
+
+**Mandatory**: always respect `prefers-reduced-motion: reduce`.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+Specific overrides for glass:
+- No animated shimmer on skeletons — use static `glass-bg`
+- No `glow-pulse` — use static `shadow-glow`
+- No `aurora-shift` — use static gradient
+- No parallax orbs — orbs stay fixed
+- Glass effects (blur, opacity, borders) remain — they are static visual properties, not animations
+- Hover states: instant transitions (no 200ms transitions — snap immediately)

package/template/.aioson/skills/design/glassmorphism-ui/references/patterns.md

@@ -0,0 +1,198 @@
+# Patterns — Glassmorphism UI
+
+Page composition patterns for apps and dashboards. The substrate always comes first.
+
+---
+
+## The Substrate Rule
+
+Every layout starts with the gradient background applied to the root container (body, html, or `#app`). This is the "glass substrate" — the gradient that makes the glass visible.
+
+```css
+body {
+  min-height: 100vh;
+  background: var(--bg-gradient);
+  background-attachment: fixed;   /* gradient stays fixed as content scrolls */
+}
+```
+
+`background-attachment: fixed` is recommended so the gradient doesn't scroll with the content. Cards will then float over a stable gradient substrate, which looks far more polished.
+
+---
+
+## App Shell
+
+The standard layout for apps, dashboards, and admin panels.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  GRADIENT BACKGROUND (body, fixed attachment)                    │
+│                                                                  │
+│  ┌──────────────┐  ┌──────────────────────────────────────────┐ │
+│  │ GLASS SIDEBAR│  │ GLASS TOP BAR (sticky, blur-lg)          │ │
+│  │ 256px        │  │ Page title / breadcrumb + actions        │ │
+│  │ blur-lg      │  ├──────────────────────────────────────────┤ │
+│  │ border-right │  │ CONTENT AREA (padding 24px)              │ │
+│  │ glass-border │  │                                          │ │
+│  │              │  │  Glass cards floating over               │ │
+│  │ Logo         │  │  gradient substrate                      │ │
+│  │ Nav groups   │  │                                          │ │
+│  │ Nav items    │  │                                          │ │
+│  │              │  │                                          │ │
+│  │ User footer  │  │                                          │ │
+│  └──────────────┘  └──────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Key decisions:
+- Sidebar: `position: fixed`, `backdrop-filter: blur(24px)` — gradient shows through
+- Top bar: `position: sticky`, `top: 0`, `backdrop-filter: blur(24px)` — inside content area, not full width
+- Content: `margin-left: 256px`, `padding: 24px`, `min-height: 100vh`
+- Cards in content: glass cards with `backdrop-filter: blur(16px)` — 2nd glass layer over substrate
+
+---
+
+## Page Patterns
+
+### 1. Dashboard Page
+
+```
+Content layout (top to bottom):
+  ├─ Page header: title + date range selector + export button
+  ├─ Stat cards row: 4 glass stat cards, equal width, 24px gap
+  │    Each: metric label + large number (optionally gradient text) + trend badge
+  ├─ Primary chart: full-width glass card, area/line chart with gradient fill
+  ├─ Secondary row: 2 columns
+  │    Left (60%): detailed chart or data table (glass card)
+  │    Right (40%): donut/distribution chart or top-N list (glass card)
+  └─ Bottom section: glass table with full data
+```
+
+Accent moments:
+- Hero insight: 1 stat gets gradient text, slightly larger font
+- Chart fills: accent gradient (violet → blue), semi-transparent area fills
+- Table: glass card container, row hover with glass-bg-hover
+
+### 2. Detail Page
+
+```
+Content layout:
+  ├─ Glass header card (radius-2xl): avatar/logo + name + status badge + action buttons
+  ├─ Tab bar (glass strip): Properties / Activity / Settings / Relations
+  └─ Tab content (glass cards per section):
+       Properties: 2-column grid of label-value pairs
+       Activity: timeline list (glass card, items with glass-border dividers)
+       Settings: form groups in glass cards
+       Relations: linked records grid (mini glass cards)
+```
+
+### 3. List Page
+
+```
+Content layout:
+  ├─ Glass filter bar (sticky): search input + filter chips + sort dropdown + count badge
+  ├─ Glass table card (full width):
+  │    Header: sticky, border-bottom glass-border, column labels text-xs uppercase text-muted
+  │    Rows: 48px height, hover glass-bg-hover, checkbox left, actions on hover right
+  │    Inline actions: appear on row hover (ghost buttons: edit, view, delete)
+  └─ Glass pagination bar: page info + prev/next glass buttons + page size selector
+```
+
+Scrolling: table scrolls horizontally on mobile (never collapses to cards — see anti-patterns).
+
+### 4. Settings Page
+
+```
+Content layout (two-column):
+  Left (240px): glass sub-navigation
+    ├─ Nav groups: Profile / Security / Notifications / Billing / Integrations
+    └─ Glass sidebar style (blur-md, border-right glass-border)
+  Right (main): glass form cards per section
+    ├─ Section card: glass card with section title + divider + form fields
+    ├─ Form fields: labeled inputs, helper text, inline validation
+    └─ Save/cancel footer: sticky within card or at page bottom
+```
+
+### 5. Auth Page (login / signup / forgot password)
+
+```
+Layout: full-viewport gradient background
+  Optional: 2-3 decorative gradient orbs (200-400px, absolute positioned, blur-xl, opacity 0.4)
+
+Centered glass card (hero variant):
+  max-width: 420px
+  border-radius: var(--radius-3xl)
+  backdrop-filter: var(--glass-blur-lg)
+  padding: var(--space-10)
+
+  Inside:
+    Logo: 40px, centered, mb-8
+    Title: text-2xl weight-bold text-heading, centered
+    Subtitle: text-sm text-secondary, centered, mb-8
+    Form: email input + password input + forgot link
+    CTA: primary button full-width (accent-gradient)
+    Divider: "or continue with"
+    Social buttons: glass buttons (Google, GitHub, etc.)
+    Footer link: "Don't have an account? Sign up"
+```
+
+Orb placement example: top-right violet orb (300px), bottom-left blue orb (250px), centered faint pink orb (400px). All with extreme blur to look like soft light.
+
+### 6. Onboarding (multi-step)
+
+```
+Layout: full-viewport gradient background
+
+Step progress (glass strip): centered at top
+  Step indicators: numbered circles (active: accent-gradient fill, completed: accent border + check, pending: glass-border)
+  Connector lines: glass-border, accent-gradient when completed
+
+Centered glass card:
+  max-width: 560px, radius-3xl, blur-lg, padding-10
+  Inside:
+    Step title: text-2xl weight-bold
+    Step description: text-sm text-secondary
+    Step content: varies (form, selection grid, confirmation)
+    Navigation: back (ghost) + next (primary gradient) buttons
+    Step count: text-xs text-muted, centered below card
+
+Background gradient shifts subtly between steps (hue rotation 10-15 degrees — very subtle).
+```
+
+---
+
+## Responsive
+
+### Breakpoints
+- `< 768px`: mobile layout (bottom tab bar, no sidebar)
+- `768px – 1024px`: tablet layout (collapsible sidebar or icon-only)
+- `> 1024px`: desktop layout (full sidebar)
+
+### Mobile layout
+- Sidebar → **glass bottom tab bar** (not hamburger menu)
+- Bottom tab bar: `position: fixed`, `bottom: 0`, `left: 0`, `right: 0`, `height: 64px`
+  - Glass surface: `background: var(--glass-bg-active)` + `backdrop-filter: var(--glass-blur-lg)`
+  - Border top: `1px solid var(--glass-border)`
+  - 4-5 icon + label tabs, active with accent color
+  - Safe area padding: `padding-bottom: env(safe-area-inset-bottom)` for iOS notch
+
+### Glass adjustments by breakpoint
+- Mobile: use `blur-sm` (8px) for cards (performance), `blur-md` (16px) only for bottom sheet
+- Tablet: use `blur-md` (16px) for cards
+- Desktop: full `blur-md` (16px) for cards, `blur-lg` (24px) for sidebar/nav
+
+### Background gradient on mobile
+Simplify to 2-3 color stops (fewer is faster):
+```css
+@media (max-width: 768px) {
+  body {
+    background: linear-gradient(135deg, #F0EEF6 0%, #D8E0F0 100%);
+  }
+}
+```
+
+### Content adjustments
+- Stat cards: 2 columns on mobile (instead of 4)
+- Tables: horizontal scroll (never collapse to card list)
+- Sidebar hidden on mobile, accessible via bottom tab bar
+- Modal: full-screen on mobile with `border-radius: radius-3xl radius-3xl 0 0` and slides up