feat(card-container): add visual container atom

docs/COMPONENTS.en.md

@@ -9,7 +9,7 @@
 These rules are system-wide and non-negotiable. Every component must comply with all of them.
 
 **Rule 1 — `backdrop-filter: blur` only on floating elements.**
-Only elements that literally float above page content (navbar, mobile sidebar, modal backdrops, sticky bars) use `backdrop-filter`. Content cards are opaque — they use `background: #0B131E`. `blur` signals "I am floating"; opaque signals "I am content". Never apply `backdrop-filter` to feature cards, release cards, pipeline cards, or any card that lives in normal document flow.
+Only elements that literally float above page content (navbar, mobile sidebar, modal backdrops, sticky bars, or an explicitly floating `CardContainer` with `backdropBlur` enabled) use `backdrop-filter`. Content cards are opaque — they use `background: #0B131E`. `blur` signals "I am floating"; opaque signals "I am content". Never apply `backdrop-filter` to feature cards, release cards, pipeline cards, or any card that lives in normal document flow. `CardContainer` defaults to `backdropBlur="none"`; `backdropBlur="sm" | "md" | "lg"` is only for floating/glass treatments above other content.
 
 **Rule 2 — Never animate gradient background directly. Use `::before` opacity instead.**
 A `linear-gradient` cannot be transitioned by the browser. Instead, place the hover gradient on a `::before` pseudo-element with `opacity: 0`, then transition only `opacity` to `1` on hover. This runs on the GPU compositor and produces a smooth fade. The background property on the element itself remains static or uses only simple `background-color` transitions.
@@ -638,24 +638,35 @@ z-index: 1;
 
 ### 3.10 Card — Frosted
 
-Used only for truly floating elements: navbar, sticky bars, mobile sidebar, modal overlays.
+Used only for explicitly floating CardContainer glass surfaces. Normal document-flow cards stay opaque.
 
 ```css
-background: rgba(6, 12, 19, 0.75); /* --color-navbar-dark */
-backdrop-filter: blur(16px);
--webkit-backdrop-filter: blur(16px);
-border: 1px solid rgba(255, 255, 255, 0.06);
+background: rgba(6, 12, 19, 0.38); /* --color-card-backdrop-dark */
+backdrop-filter: blur(20px);
+-webkit-backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 0, 54, 0.5); /* --color-red-tint-border */
 border-radius: 8px; /* or 12px for larger panels */
 ```
 
 **Light mode:**
 
 ```css
-background: rgba(255, 255, 255, 0.7); /* --color-navbar-light */
-backdrop-filter: blur(16px);
--webkit-backdrop-filter: blur(16px);
+background: rgba(255, 255, 255, 0.32); /* --color-card-backdrop-light */
+backdrop-filter: blur(20px);
+-webkit-backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 0, 54, 0.5); /* --color-red-tint-border */
+```
+
+**CardContainer backdropBlur levels:**
+
+```css
+backdropBlur="sm"; /* --blur-card-sm: blur(10px) */
+backdropBlur="md"; /* --blur-card-md: blur(20px) */
+backdropBlur="lg"; /* --blur-card-lg: blur(36px) */
 ```
 
+Use these only when the card is visually floating above other content. Leave `backdropBlur="none"` for normal content cards.
+
 **Sticky CTA bar specific (floats below navbar after scroll):**
 
 ```css
@@ -709,15 +720,10 @@ box-shadow: 0 4px 30px rgba(255, 0, 54, 0.1);
 
 ```css
 /* Dark */
-background: rgba(
-  27,
-  27,
-  29,
-  0.6
-); /* reference; DESIGN.md spec: rgba(6,12,19,0.75) */
+background: rgba(6, 12, 19, 0.75); /* --color-navbar-dark */
 backdrop-filter: blur(16px);
 -webkit-backdrop-filter: blur(16px);
-border-bottom: 1px solid #1a1a1a; /* --ifm-color-emphasis-200 */
+border-bottom: 1px solid #172230; /* --color-border-dark */
 position: sticky;
 top: 0;
 z-index: 300; /* --z-navbar */
@@ -726,7 +732,7 @@ z-index: 300; /* --z-navbar */
 **Light mode:**
 
 ```css
-background: rgba(255, 255, 255, 0.7);
+background: rgba(255, 255, 255, 0.7); /* --color-navbar-light */
 backdrop-filter: blur(16px);
 -webkit-backdrop-filter: blur(16px);
 ```
@@ -1260,6 +1266,13 @@ Note: buttons ARE the exception — their `background` gradient transition is pe
   background: rgba(6, 12, 19, 0.75);
   backdrop-filter: blur(16px);
 }
+
+/* ✅ CardContainer backdropBlur is allowed only when the card is floating */
+.floatingGlassCard {
+  background: rgba(6, 12, 19, 0.38);
+  border-color: rgba(255, 0, 54, 0.5);
+  backdrop-filter: blur(20px); /* CardContainer backdropBlur="md" */
+}
 ```
 
 Blur on content cards creates a visual hierarchy confusion: it signals "floating" when the card is grounded content. It also has significant GPU cost on long pages with many cards.

docs/COMPONENTS.md

@@ -9,7 +9,7 @@
 These rules are system-wide and non-negotiable. Every component must comply with all of them.
 
 **Rule 1 — `backdrop-filter: blur` only on floating elements.**
-Only elements that literally float above page content (navbar, mobile sidebar, modal backdrops, sticky bars) use `backdrop-filter`. Content cards are opaque — they use `background: #0B131E`. `blur` signals "I am floating"; opaque signals "I am content". Never apply `backdrop-filter` to feature cards, release cards, pipeline cards, or any card that lives in normal document flow.
+Only elements that literally float above page content (navbar, mobile sidebar, modal backdrops, sticky bars, or an explicitly floating `CardContainer` with `backdropBlur` enabled) use `backdrop-filter`. Content cards are opaque — they use `background: #0B131E`. `blur` signals "I am floating"; opaque signals "I am content". Never apply `backdrop-filter` to feature cards, release cards, pipeline cards, or any card that lives in normal document flow. `CardContainer` defaults to `backdropBlur="none"`; `backdropBlur="sm" | "md" | "lg"` is only for floating/glass treatments above other content.
 
 **Rule 2 — Never animate gradient background directly. Use `::before` opacity instead.**
 A `linear-gradient` cannot be transitioned by the browser. Instead, place the hover gradient on a `::before` pseudo-element with `opacity: 0`, then transition only `opacity` to `1` on hover. This runs on the GPU compositor and produces a smooth fade. The background property on the element itself remains static or uses only simple `background-color` transitions.
@@ -638,24 +638,35 @@ z-index: 1;
 
 ### 3.10 Card — Frosted
 
-Used only for truly floating elements: navbar, sticky bars, mobile sidebar, modal overlays.
+Used only for explicitly floating CardContainer glass surfaces. Normal document-flow cards stay opaque.
 
 ```css
-background: rgba(6, 12, 19, 0.75); /* --color-navbar-dark */
-backdrop-filter: blur(16px);
--webkit-backdrop-filter: blur(16px);
-border: 1px solid rgba(255, 255, 255, 0.06);
+background: rgba(6, 12, 19, 0.38); /* --color-card-backdrop-dark */
+backdrop-filter: blur(20px);
+-webkit-backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 0, 54, 0.5); /* --color-red-tint-border */
 border-radius: 8px; /* or 12px for larger panels */
 ```
 
 **Light mode:**
 
 ```css
-background: rgba(255, 255, 255, 0.7); /* --color-navbar-light */
-backdrop-filter: blur(16px);
--webkit-backdrop-filter: blur(16px);
+background: rgba(255, 255, 255, 0.32); /* --color-card-backdrop-light */
+backdrop-filter: blur(20px);
+-webkit-backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 0, 54, 0.5); /* --color-red-tint-border */
+```
+
+**CardContainer backdropBlur levels:**
+
+```css
+backdropBlur="sm"; /* --blur-card-sm: blur(10px) */
+backdropBlur="md"; /* --blur-card-md: blur(20px) */
+backdropBlur="lg"; /* --blur-card-lg: blur(36px) */
 ```
 
+Use these only when the card is visually floating above other content. Leave `backdropBlur="none"` for normal content cards.
+
 **Sticky CTA bar specific (floats below navbar after scroll):**
 
 ```css
@@ -709,15 +720,10 @@ box-shadow: 0 4px 30px rgba(255, 0, 54, 0.1);
 
 ```css
 /* Dark */
-background: rgba(
-  27,
-  27,
-  29,
-  0.6
-); /* reference; DESIGN.md spec: rgba(6,12,19,0.75) */
+background: rgba(6, 12, 19, 0.75); /* --color-navbar-dark */
 backdrop-filter: blur(16px);
 -webkit-backdrop-filter: blur(16px);
-border-bottom: 1px solid #1a1a1a; /* --ifm-color-emphasis-200 */
+border-bottom: 1px solid #172230; /* --color-border-dark */
 position: sticky;
 top: 0;
 z-index: 300; /* --z-navbar */
@@ -726,7 +732,7 @@ z-index: 300; /* --z-navbar */
 **Light mode:**
 
 ```css
-background: rgba(255, 255, 255, 0.7);
+background: rgba(255, 255, 255, 0.7); /* --color-navbar-light */
 backdrop-filter: blur(16px);
 -webkit-backdrop-filter: blur(16px);
 ```
@@ -1260,6 +1266,13 @@ Note: buttons ARE the exception — their `background` gradient transition is pe
   background: rgba(6, 12, 19, 0.75);
   backdrop-filter: blur(16px);
 }
+
+/* ✅ CardContainer backdropBlur is allowed only when the card is floating */
+.floatingGlassCard {
+  background: rgba(6, 12, 19, 0.38);
+  border-color: rgba(255, 0, 54, 0.5);
+  backdrop-filter: blur(20px); /* CardContainer backdropBlur="md" */
+}
 ```
 
 Blur on content cards creates a visual hierarchy confusion: it signals "floating" when the card is grounded content. It also has significant GPU cost on long pages with many cards.

docs/DESIGN.en.md

@@ -71,6 +71,7 @@ The brand color. Two values depending on the mode:
 | `background-surface` | `#0B131E` | — | Solid cards, code blocks |
 | `background-surface-raised` | `#0F1824` | — | Table headers, subtle emphasis |
 | `navbar-bg` | `rgba(6,12,19,0.75)` | `rgba(255,255,255,0.7)` | Navbar with backdrop blur |
+| `card-backdrop-bg` | `rgba(6,12,19,0.38)` | `rgba(255,255,255,0.32)` | Floating CardContainer with `backdropBlur` |
 | `sidebar-mobile-bg` | `rgba(6,12,19,1.0)` | `#ffffff` | Mobile sidebar |
 | `dropdown-bg` | `#0B131E` | `#ffffff` | Dropdown menus |
 
@@ -184,8 +185,8 @@ Unlike a shadow-based elevation system, Stack-and-Flow uses an **opacity and blu
 |-------|------|-------------|-----|
 | **Base** | Opaque | `background: #060C13` + subtle grid | Page canvas |
 | **Raised** | Opaque | `background: #0B131E` + `border: 1px solid #172230` | Solid cards, code blocks, dropdowns |
-| **Frosted** | Translucent | `background: rgba(6,12,19,0.75)` + `backdrop-filter: blur(16px)` | Navbar, floating overlays |
-| **Frosted Light** | Translucent | `background: rgba(255,255,255,0.7)` + `backdrop-filter: blur(16px)` | Navbar in light mode |
+| **Frosted** | Translucent | `background: rgba(6,12,19,0.38)` + `border: rgba(255,0,54,0.5)` + `backdrop-filter: blur(20px)` | `CardContainer backdropBlur="md"` when floating above content |
+| **Frosted Light** | Translucent | `background: rgba(255,255,255,0.32)` + `border: rgba(255,0,54,0.5)` + `backdrop-filter: blur(20px)` | `CardContainer backdropBlur="md"` in light mode when floating above content |
 | **Tinted** | Tinted translucent | `background: rgba(255,0,54,0.06–0.15)` | Secondary buttons, hover states, active menus |
 | **Overlay** | Dark translucent | `background: rgba(0,0,0,0.6)` + `backdrop-filter: blur(4px)` | Modal backgrounds, sidebar backdrop |
 
@@ -198,12 +199,12 @@ border: 1px solid #172230;
 border-radius: 8px;
 ```
 
-**Frosted card** — use for elements that float above content (navbar, tooltips, popovers):
+**Frosted card** — use only when `CardContainer` floats above content (`backdropBlur="sm|md|lg"`):
 ```css
-background: rgba(6, 12, 19, 0.75);
-backdrop-filter: blur(16px);
--webkit-backdrop-filter: blur(16px);
-border: 1px solid rgba(255, 255, 255, 0.06);
+background: rgba(6, 12, 19, 0.38);
+backdrop-filter: blur(20px); /* md; sm=10px, lg=36px */
+-webkit-backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 0, 54, 0.5);
 border-radius: 8px;
 ```
 
@@ -216,7 +217,7 @@ border-radius: 8px;
 
 ### Blur rule
 
-Only elements that literally float above others (navbar, mobile sidebar, modals, tooltips) use `backdrop-filter`. Content cards do not — they are opaque. This distinction is intentional: blur means “I am floating,” opaque means “I am content.”
+Only elements that literally float above others (navbar, mobile sidebar, modals, tooltips, or a `CardContainer` used as a floating surface) use `backdrop-filter`. Content cards do not — they are opaque. This distinction is intentional: blur means “I am floating,” opaque means “I am content.” In `CardContainer`, keep `backdropBlur="none"` for normal-flow cards and use `sm`, `md`, or `lg` only for glass/floating surfaces.
 
 ---
 

docs/DESIGN.md

@@ -71,6 +71,7 @@ El color de marca. Dos valores según el modo:
 | `background-surface` | `#0B131E` | — | Cards sólidas, code blocks |
 | `background-surface-raised` | `#0F1824` | — | Headers de tabla, énfasis sutil |
 | `navbar-bg` | `rgba(6,12,19,0.75)` | `rgba(255,255,255,0.7)` | Navbar con backdrop-blur |
+| `card-backdrop-bg` | `rgba(6,12,19,0.38)` | `rgba(255,255,255,0.32)` | CardContainer flotante con `backdropBlur` |
 | `sidebar-mobile-bg` | `rgba(6,12,19,1.0)` | `#ffffff` | Sidebar mobile |
 | `dropdown-bg` | `#0B131E` | `#ffffff` | Menus desplegables |
 
@@ -184,8 +185,8 @@ A diferencia de un sistema de elevación con sombras, Stack-and-Flow usa un **si
 |-------|------|-------------|-----|
 | **Base** | Opaco | `background: #060C13` + grid sutil | Canvas de página |
 | **Raised** | Opaco | `background: #0B131E` + `border: 1px solid #172230` | Cards sólidas, code blocks, dropdowns |
-| **Frosted** | Semitransparente | `background: rgba(6,12,19,0.75)` + `backdrop-filter: blur(16px)` | Navbar, overlays flotantes |
-| **Frosted Light** | Semitransparente | `background: rgba(255,255,255,0.7)` + `backdrop-filter: blur(16px)` | Navbar en light mode |
+| **Frosted** | Semitransparente | `background: rgba(6,12,19,0.38)` + `border: rgba(255,0,54,0.5)` + `backdrop-filter: blur(20px)` | `CardContainer backdropBlur="md"` cuando flota sobre contenido |
+| **Frosted Light** | Semitransparente | `background: rgba(255,255,255,0.32)` + `border: rgba(255,0,54,0.5)` + `backdrop-filter: blur(20px)` | `CardContainer backdropBlur="md"` en light mode cuando flota sobre contenido |
 | **Tinted** | Semitransparente colored | `background: rgba(255,0,54,0.06–0.15)` | Botones secondary, hover states, menús activos |
 | **Overlay** | Semitransparente oscuro | `background: rgba(0,0,0,0.6)` + `backdrop-filter: blur(4px)` | Fondos de modal, sidebar backdrop |
 
@@ -198,12 +199,12 @@ border: 1px solid #172230;
 border-radius: 8px;
 ```
 
-**Card frosted** — usa para elementos que flotan sobre contenido (navbar, tooltips, popovers):
+**Card frosted** — usá solo cuando el `CardContainer` flota sobre contenido (`backdropBlur="sm|md|lg"`):
 ```css
-background: rgba(6, 12, 19, 0.75);
-backdrop-filter: blur(16px);
--webkit-backdrop-filter: blur(16px);
-border: 1px solid rgba(255, 255, 255, 0.06);
+background: rgba(6, 12, 19, 0.38);
+backdrop-filter: blur(20px); /* md; sm=10px, lg=36px */
+-webkit-backdrop-filter: blur(20px);
+border: 1px solid rgba(255, 0, 54, 0.5);
 border-radius: 8px;
 ```
 
@@ -216,7 +217,7 @@ border-radius: 8px;
 
 ### Regla de blur
 
-Solo los elementos que literalmente flotan sobre otros (navbar, mobile sidebar, modals, tooltips) usan `backdrop-filter`. Los cards de contenido no lo usan — son opacos. Esta distinción es intencional: el blur implica "estoy flotando", el opaco implica "soy contenido".
+Solo los elementos que literalmente flotan sobre otros (navbar, mobile sidebar, modals, tooltips o un `CardContainer` usado como superficie flotante) usan `backdrop-filter`. Los cards de contenido no lo usan — son opacos. Esta distinción es intencional: el blur implica "estoy flotando", el opaco implica "soy contenido". En `CardContainer`, mantené `backdropBlur="none"` para cards en flujo normal y usá `sm`, `md` o `lg` solo para superficies glass/floating.
 
 ---
 

src/components/atoms/button/useButton.ts

@@ -1,12 +1,12 @@
-import { type MouseEvent, type RefObject, useRef } from 'react';
+import { type ComponentProps, type MouseEvent, useRef } from 'react';
 import { useRipple } from '@/hooks/useRipple';
 import { cn } from '@/lib/utils';
 import { type ButtonEmphasis, type ButtonProps, buttonVariants } from './types';
 
 type UseButtonReturn = Omit<ButtonProps, 'onClick'> & {
   ariaLabel: string;
   ariaPressed: ButtonProps['aria-pressed'];
-  buttonRef: RefObject<HTMLButtonElement | null>;
+  buttonRef: ComponentProps<'button'>['ref'];
   className: string;
   contentClassName: string;
   disabled: boolean;