From 1135fa38260eb1026cc3bb6cfaca855910ecca00 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 20 Mar 2026 12:48:05 +0000
Subject: [PATCH 1/5] refactor: comprehensively refactor media components

- Remove SbMediaWrapper entirely; inline spacing/width logic directly
  into SbImage, SbVideo, and SbSlideshow using Box
- Image: use AspectRatio component when aspectRatio prop is provided,
  remove wrapperStyle/wrapperClassName props, simplify copyright rendering
- Video: use AspectRatio component, consolidate YouTube/Vimeo render
  paths into a single branch, remove wrapperStyle/wrapperClassName,
  simplify copyright rendering, strip AI-generated emoji JSDoc
- CopyrightLabel: merge inline-white and inline-black into a single
  block differing only in color, reducing duplication
- Tighten aspectRatio prop type on Image to match AspectRatio/Video

https://claude.ai/code/session_01DLAMCPXYx7Z9kuqQ5RKLNM
---
 .../src/components/image/SbImage.tsx          |  48 +--
 .../media-wrapper/SbMediaWrapper.tsx          |  44 ---
 .../src/components/media-wrapper/index.ts     |   2 -
 .../src/components/slideshow/SbSlideshow.tsx  |  24 +-
 .../src/components/video/SbVideo.tsx          |  60 +--
 packages/storyblok-ui/src/index.ts            |   4 -
 .../copyright-label/copyright-label.tsx       |  65 +---
 packages/ui/src/components/image/image.tsx    | 250 ++++---------
 packages/ui/src/components/video/video.tsx    | 352 +++---------------
 9 files changed, 172 insertions(+), 677 deletions(-)
 delete mode 100644 packages/storyblok-ui/src/components/media-wrapper/SbMediaWrapper.tsx
 delete mode 100644 packages/storyblok-ui/src/components/media-wrapper/index.ts

diff --git a/packages/storyblok-ui/src/components/image/SbImage.tsx b/packages/storyblok-ui/src/components/image/SbImage.tsx
index ae630ea4..2b1340b0 100644
--- a/packages/storyblok-ui/src/components/image/SbImage.tsx
+++ b/packages/storyblok-ui/src/components/image/SbImage.tsx
@@ -2,13 +2,14 @@
 
 import type { StoryblokRichTextProps } from "@httpjpg/storyblok-richtext";
 import { getProcessedImage } from "@httpjpg/storyblok-utils";
-import { Image } from "@httpjpg/ui";
+import { Box, Image } from "@httpjpg/ui";
 import { memo } from "react";
 import { css } from "styled-system/css";
 import { useStoryblokEditable } from "../../lib/use-storyblok-editable";
+import { mapSpacingToToken } from "../../lib/spacing-utils";
+import { mapWidthToToken } from "../../lib/token-mapping";
 import type { StoryblokImage } from "../../types";
 import { SbCaption } from "../caption";
-import { SbMediaWrapper } from "../media-wrapper";
 
 // Predefine all responsive width classes so Panda generates them at build time
 const RESPONSIVE_WIDTH_CLASSES = {
@@ -48,13 +49,8 @@ export interface SbImageProps {
   };
 }
 
-// Default image width for Storyblok image service when aspect ratio is specified
 const DEFAULT_IMAGE_WIDTH = 1200;
 
-/**
- * Storyblok Image Component
- * Optimized image with Storyblok image service
- */
 export const SbImage = memo(function SbImage({ blok }: SbImageProps) {
   const {
     image,
@@ -78,8 +74,6 @@ export const SbImage = memo(function SbImage({ blok }: SbImageProps) {
     return null;
   }
 
-  // Process image with Storyblok image service (or return external URL as-is)
-  // Calculate dimensions based on aspect ratio
   let cropDimensions = "";
   if (aspectRatio) {
     const parts = aspectRatio.split("/");
@@ -87,7 +81,6 @@ export const SbImage = memo(function SbImage({ blok }: SbImageProps) {
       const [widthRatio, heightRatio] = parts.map((part) =>
         Number(part.trim()),
       );
-      // Validate that both ratios are valid positive finite numbers
       if (
         widthRatio > 0 &&
         heightRatio > 0 &&
@@ -109,20 +102,12 @@ export const SbImage = memo(function SbImage({ blok }: SbImageProps) {
     "",
   );
 
-  // Generate blur placeholder if blurOnLoad is enabled
   const blurDataURL = blurOnLoad
-    ? getProcessedImage(
-        image.filename,
-        "20x0", // Small width for blur placeholder
-        image.focus || "",
-        "",
-      )
+    ? getProcessedImage(image.filename, "20x0", image.focus || "", "")
     : undefined;
 
-  // Use copyright from custom field first, fallback to image copyright
   const finalCopyright = copyright || image.copyright || "";
 
-  // Calculate width based on imageWidth value
   const calculatedWidth =
     imageWidth === "original" || imageWidth === "auto"
       ? "auto"
@@ -133,11 +118,14 @@ export const SbImage = memo(function SbImage({ blok }: SbImageProps) {
           : "auto";
 
   return (
-    <SbMediaWrapper
-      spacingTop={spacingTop}
-      spacingBottom={spacingBottom}
-      width={width}
-      editable={editableProps}
+    <Box
+      css={{
+        mt: mapSpacingToToken(spacingTop),
+        mb: mapSpacingToToken(spacingBottom),
+        width: mapWidthToToken(width),
+        mx: width === "container" || width === "narrow" ? "auto" : undefined,
+      }}
+      {...editableProps}
     >
       <div
         className={
@@ -153,18 +141,14 @@ export const SbImage = memo(function SbImage({ blok }: SbImageProps) {
           copyrightPosition={copyrightPosition}
           blurOnLoad={blurOnLoad}
           blurDataURL={blurDataURL}
-          css={{
-            width: "100%",
-            maxWidth: "100%",
-            height: isFullHeight ? "100vh" : "auto",
-            objectFit: aspectRatio ? "cover" : "none",
-            aspectRatio: aspectRatio || undefined,
-          }}
+          aspectRatio={aspectRatio}
+          objectFit={aspectRatio ? "cover" : "none"}
+          css={isFullHeight ? { height: "100vh" } : undefined}
           loading={isLoadingEager ? "eager" : "lazy"}
         />
       </div>
 
       {caption && <SbCaption data={caption} />}
-    </SbMediaWrapper>
+    </Box>
   );
 });
diff --git a/packages/storyblok-ui/src/components/media-wrapper/SbMediaWrapper.tsx b/packages/storyblok-ui/src/components/media-wrapper/SbMediaWrapper.tsx
deleted file mode 100644
index 0db72779..00000000
--- a/packages/storyblok-ui/src/components/media-wrapper/SbMediaWrapper.tsx
+++ /dev/null
@@ -1,44 +0,0 @@
-/**
- * SbMediaWrapper component for Storyblok media components
- * Provides consistent spacing and width constraints
- */
-
-import { Box } from "@httpjpg/ui";
-import type { ReactNode } from "react";
-import { memo } from "react";
-import { mapSpacingToToken } from "../../lib/spacing-utils";
-import { mapWidthToToken } from "../../lib/token-mapping";
-
-export interface SbMediaWrapperProps {
-  children: ReactNode;
-  spacingTop?: string;
-  spacingBottom?: string;
-  width?: string;
-  editable?: Record<string, unknown>;
-}
-
-/**
- * SbMediaWrapper component
- * Wraps media components with consistent spacing and layout
- */
-export const SbMediaWrapper = memo(function SbMediaWrapper({
-  children,
-  spacingTop,
-  spacingBottom,
-  width,
-  editable,
-}: SbMediaWrapperProps) {
-  return (
-    <Box
-      css={{
-        mt: mapSpacingToToken(spacingTop),
-        mb: mapSpacingToToken(spacingBottom),
-        width: mapWidthToToken(width),
-        mx: width === "container" || width === "narrow" ? "auto" : undefined,
-      }}
-      {...editable}
-    >
-      {children}
-    </Box>
-  );
-});
diff --git a/packages/storyblok-ui/src/components/media-wrapper/index.ts b/packages/storyblok-ui/src/components/media-wrapper/index.ts
deleted file mode 100644
index e9881e3b..00000000
--- a/packages/storyblok-ui/src/components/media-wrapper/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export type { SbMediaWrapperProps } from "./SbMediaWrapper";
-export { SbMediaWrapper } from "./SbMediaWrapper";
diff --git a/packages/storyblok-ui/src/components/slideshow/SbSlideshow.tsx b/packages/storyblok-ui/src/components/slideshow/SbSlideshow.tsx
index f2026ac3..1bb64940 100644
--- a/packages/storyblok-ui/src/components/slideshow/SbSlideshow.tsx
+++ b/packages/storyblok-ui/src/components/slideshow/SbSlideshow.tsx
@@ -1,10 +1,11 @@
 "use client";
 
-import { Slideshow } from "@httpjpg/ui";
+import { Box, Slideshow } from "@httpjpg/ui";
 import { memo } from "react";
 import { useStoryblokEditable } from "../../lib/use-storyblok-editable";
+import { mapSpacingToToken } from "../../lib/spacing-utils";
+import { mapWidthToToken } from "../../lib/token-mapping";
 import type { StoryblokImage } from "../../types";
-import { SbMediaWrapper } from "../media-wrapper";
 
 export interface SbSlideshowProps {
   blok: {
@@ -39,10 +40,6 @@ export interface SbSlideshowProps {
   };
 }
 
-/**
- * Storyblok Slideshow Component
- * Carousel/slideshow of images
- */
 export const SbSlideshow = memo(function SbSlideshow({
   blok,
 }: SbSlideshowProps) {
@@ -67,11 +64,14 @@ export const SbSlideshow = memo(function SbSlideshow({
   }
 
   return (
-    <SbMediaWrapper
-      spacingTop={spacingTop}
-      spacingBottom={spacingBottom}
-      width={width}
-      editable={editableProps}
+    <Box
+      css={{
+        mt: mapSpacingToToken(spacingTop),
+        mb: mapSpacingToToken(spacingBottom),
+        width: mapWidthToToken(width),
+        mx: width === "container" || width === "narrow" ? "auto" : undefined,
+      }}
+      {...editableProps}
     >
       <Slideshow
         images={images.map((img) => ({
@@ -88,6 +88,6 @@ export const SbSlideshow = memo(function SbSlideshow({
         animation={animation}
         animationDelay={animationDelay}
       />
-    </SbMediaWrapper>
+    </Box>
   );
 });
diff --git a/packages/storyblok-ui/src/components/video/SbVideo.tsx b/packages/storyblok-ui/src/components/video/SbVideo.tsx
index 99e6e31a..2ad6f582 100644
--- a/packages/storyblok-ui/src/components/video/SbVideo.tsx
+++ b/packages/storyblok-ui/src/components/video/SbVideo.tsx
@@ -3,12 +3,13 @@
 import { ConsentPlaceholder, hasVendorConsent } from "@httpjpg/consent";
 import type { StoryblokRichTextProps } from "@httpjpg/storyblok-richtext";
 import type { VideoSource } from "@httpjpg/ui";
-import { Video as VideoComponent } from "@httpjpg/ui";
+import { Box, Video as VideoComponent } from "@httpjpg/ui";
 import { memo, useEffect, useState } from "react";
 import { useStoryblokEditable } from "../../lib/use-storyblok-editable";
+import { mapSpacingToToken } from "../../lib/spacing-utils";
+import { mapWidthToToken } from "../../lib/token-mapping";
 import type { StoryblokVideoAsset } from "../../types";
 import { SbCaption } from "../caption";
-import { SbMediaWrapper } from "../media-wrapper";
 
 export interface SbVideoProps {
   blok: {
@@ -33,10 +34,6 @@ export interface SbVideoProps {
   };
 }
 
-/**
- * Storyblok Video Component
- * Supports native videos, YouTube and Vimeo embeds
- */
 export const SbVideo = memo(function SbVideo({ blok }: SbVideoProps) {
   const {
     source = "native",
@@ -58,7 +55,6 @@ export const SbVideo = memo(function SbVideo({ blok }: SbVideoProps) {
     spacingBottom,
   } = blok;
 
-  // Determine video source
   let videoSrc = "";
   if (source === "native") {
     videoSrc = video?.filename || videoUrl || "";
@@ -70,11 +66,8 @@ export const SbVideo = memo(function SbVideo({ blok }: SbVideoProps) {
 
   const editableProps = useStoryblokEditable(blok);
 
-  // Track consent state and re-render on changes
-  // Start with false to avoid hydration mismatch (server has no cookies)
   const [hasConsent, setHasConsent] = useState(false);
 
-  // Check consent client-side only to avoid SSR/client mismatch
   useEffect(() => {
     if (source === "youtube") {
       setHasConsent(hasVendorConsent("youtube"));
@@ -103,40 +96,26 @@ export const SbVideo = memo(function SbVideo({ blok }: SbVideoProps) {
     return null;
   }
 
-  // Check consent for external video providers
-  if (source === "youtube" && !hasConsent) {
-    return (
-      <SbMediaWrapper
-        spacingTop={spacingTop}
-        spacingBottom={spacingBottom}
-        width={width}
-        editable={editableProps}
-      >
-        <ConsentPlaceholder vendor="YouTube" height="400px" />
-      </SbMediaWrapper>
-    );
-  }
+  const wrapperCss = {
+    mt: mapSpacingToToken(spacingTop),
+    mb: mapSpacingToToken(spacingBottom),
+    width: mapWidthToToken(width),
+    mx: width === "container" || width === "narrow" ? "auto" : undefined,
+  };
 
-  if (source === "vimeo" && !hasConsent) {
+  if ((source === "youtube" || source === "vimeo") && !hasConsent) {
     return (
-      <SbMediaWrapper
-        spacingTop={spacingTop}
-        spacingBottom={spacingBottom}
-        width={width}
-        editable={editableProps}
-      >
-        <ConsentPlaceholder vendor="Vimeo" height="400px" />
-      </SbMediaWrapper>
+      <Box css={wrapperCss} {...editableProps}>
+        <ConsentPlaceholder
+          vendor={source === "youtube" ? "YouTube" : "Vimeo"}
+          height="400px"
+        />
+      </Box>
     );
   }
 
   return (
-    <SbMediaWrapper
-      spacingTop={spacingTop}
-      spacingBottom={spacingBottom}
-      width={width}
-      editable={editableProps}
-    >
+    <Box css={wrapperCss} {...editableProps}>
       <VideoComponent
         src={videoSrc}
         source={source as VideoSource}
@@ -148,14 +127,11 @@ export const SbVideo = memo(function SbVideo({ blok }: SbVideoProps) {
         muted={muted}
         copyright={copyright}
         copyrightPosition={copyrightPosition}
-        css={{
-          width: "100%",
-        }}
       />
 
       {caption?.content && caption.content.length > 0 && (
         <SbCaption data={caption} />
       )}
-    </SbMediaWrapper>
+    </Box>
   );
 });
diff --git a/packages/storyblok-ui/src/index.ts b/packages/storyblok-ui/src/index.ts
index 3210f9e0..b5440c87 100644
--- a/packages/storyblok-ui/src/index.ts
+++ b/packages/storyblok-ui/src/index.ts
@@ -40,10 +40,6 @@ export {
   SbMarquee,
   type SbMarqueeProps,
 } from "./components/marquee";
-export {
-  SbMediaWrapper,
-  type SbMediaWrapperProps,
-} from "./components/media-wrapper";
 export {
   SbMissing,
   type SbMissingProps,
diff --git a/packages/ui/src/components/copyright-label/copyright-label.tsx b/packages/ui/src/components/copyright-label/copyright-label.tsx
index 3e3480c6..1503e2f6 100644
--- a/packages/ui/src/components/copyright-label/copyright-label.tsx
+++ b/packages/ui/src/components/copyright-label/copyright-label.tsx
@@ -10,42 +10,11 @@ export type CopyrightPosition =
   | "inline-white";
 
 export interface CopyrightLabelProps {
-  /**
-   * Copyright text (without © symbol, will be added automatically)
-   */
   text: string;
-  /**
-   * Position variant
-   * @default "below"
-   */
   position?: CopyrightPosition;
-  /**
-   * Custom styles using Panda CSS SystemStyleObject
-   */
   css?: SystemStyleObject;
 }
 
-/**
- * CopyrightLabel component - Displays copyright information
- *
- * A reusable component for displaying copyright notices in various positions.
- * Automatically adds the © symbol to the text.
- *
- * @example
- * ```tsx
- * // Below content
- * <CopyrightLabel text="John Doe" position="below" />
- *
- * // Overlay at bottom
- * <CopyrightLabel text="Jane Smith" position="overlay" />
- *
- * // Inline white (for dark images/slideshows)
- * <CopyrightLabel text="Photographer" position="inline-white" />
- *
- * // Inline black (for bright images)
- * <CopyrightLabel text="Photographer Name" position="inline-black" />
- * ```
- */
 export function CopyrightLabel({
   text,
   position = "below",
@@ -55,7 +24,6 @@ export function CopyrightLabel({
     return null;
   }
 
-  // Overlay position (e.g., for videos)
   if (position === "overlay") {
     return (
       <Box
@@ -82,35 +50,7 @@ export function CopyrightLabel({
     );
   }
 
-  // Inline black position (vertical on right side, for bright images)
-  if (position === "inline-black") {
-    return (
-      <Box
-        css={{
-          position: "absolute",
-          right: 2,
-          bottom: 2,
-          px: 1,
-          py: 2,
-          fontFamily: "sans",
-          fontSize: "sm",
-          opacity: 0.7,
-          color: "black",
-          writingMode: "vertical-rl",
-          transform: "rotate(180deg)",
-          whiteSpace: "nowrap",
-          zIndex: 10,
-          pointerEvents: "none",
-          ...cssProp,
-        }}
-      >
-        © {text}
-      </Box>
-    );
-  }
-
-  // Inline white position (vertical on right side, for dark images)
-  if (position === "inline-white") {
+  if (position === "inline-white" || position === "inline-black") {
     return (
       <Box
         css={{
@@ -122,7 +62,7 @@ export function CopyrightLabel({
           fontFamily: "sans",
           fontSize: "sm",
           opacity: 0.7,
-          color: "white",
+          color: position === "inline-white" ? "white" : "black",
           writingMode: "vertical-rl",
           transform: "rotate(180deg)",
           whiteSpace: "nowrap",
@@ -137,7 +77,6 @@ export function CopyrightLabel({
     );
   }
 
-  // Below position (default)
   return (
     <Box
       css={{
diff --git a/packages/ui/src/components/image/image.tsx b/packages/ui/src/components/image/image.tsx
index 5be60229..d140b36f 100644
--- a/packages/ui/src/components/image/image.tsx
+++ b/packages/ui/src/components/image/image.tsx
@@ -4,84 +4,23 @@ import type { ImgHTMLAttributes } from "react";
 import { forwardRef, useEffect, useRef, useState } from "react";
 import { css, cx } from "styled-system/css";
 import type { SystemStyleObject } from "styled-system/types";
+import { AspectRatio } from "../aspect-ratio";
 import { Box } from "../box/box";
 import { CopyrightLabel, type CopyrightPosition } from "../copyright-label";
 
-/**
- * Image component props
- */
 export interface ImageProps
   extends Omit<ImgHTMLAttributes<HTMLImageElement>, "css"> {
-  /**
-   * Image source URL
-   */
   src: string;
-  /**
-   * Alt text for accessibility
-   */
   alt: string;
-  /**
-   * Copyright text
-   */
   copyright?: string;
-  /**
-   * Copyright position
-   * @default "inline-white"
-   */
   copyrightPosition?: CopyrightPosition;
-  /**
-   * Enable blur-up loading effect
-   * @default false
-   */
   blurOnLoad?: boolean;
-  /**
-   * Low-quality image placeholder (LQIP) for blur effect
-   */
   blurDataURL?: string;
-  /**
-   * Object fit
-   * @default "cover"
-   */
   objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down";
-  /**
-   * Aspect ratio (e.g., "16/9", "1/1", "4/3")
-   */
-  aspectRatio?: string;
-  /**
-   * Custom styles for the wrapper
-   */
-  wrapperStyle?: React.CSSProperties;
-  /**
-   * Custom class name for the wrapper
-   */
-  wrapperClassName?: string;
-  /**
-   * Custom styles using Panda CSS SystemStyleObject
-   */
+  aspectRatio?: "1/1" | "4/3" | "3/4" | "16/9" | "9/16" | "21/9";
   css?: SystemStyleObject;
 }
 
-/**
- * Image component with copyright and blur loading
- *
- * Supports:
- * - Copyright text (inline, below, or overlay)
- * - Blur-up loading effect for better UX
- * - Object fit options
- * - Fully styled with Panda CSS
- *
- * @example
- * ```tsx
- * <Image
- *   src="https://example.com/image.jpg"
- *   alt="Description"
- *   copyright="© 2025 Photographer Name"
- *   copyrightPosition="inline"
- *   blurOnLoad
- *   blurDataURL="/blur.jpg"
- * />
- * ```
- */
 export const Image = forwardRef<HTMLDivElement, ImageProps>(
   (
     {
@@ -93,8 +32,6 @@ export const Image = forwardRef<HTMLDivElement, ImageProps>(
       blurDataURL,
       objectFit = "cover",
       aspectRatio,
-      wrapperStyle,
-      wrapperClassName,
       className,
       style,
       css: cssProp,
@@ -110,11 +47,14 @@ export const Image = forwardRef<HTMLDivElement, ImageProps>(
     const containerRef = useRef<HTMLDivElement>(null);
     const currentSrcRef = useRef<string>("");
 
+    const mergeRef = (node: HTMLDivElement | null) => {
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+      containerRef.current = node;
+    };
+
     const handleLoad = (e: React.SyntheticEvent<HTMLImageElement>) => {
-      // Only set loaded if we're loading the high-res image
-      if (blurOnLoad && currentSrcRef.current === src) {
-        setHighResLoaded(true);
-      }
+      if (blurOnLoad && currentSrcRef.current === src) setHighResLoaded(true);
       setIsLoaded(true);
       onLoad?.(e);
     };
@@ -124,7 +64,6 @@ export const Image = forwardRef<HTMLDivElement, ImageProps>(
       setHighResLoaded(true);
     };
 
-    // Intersection Observer for lazy loading with blur effect
     useEffect(() => {
       if (!blurOnLoad) {
         setIsInView(true);
@@ -143,20 +82,15 @@ export const Image = forwardRef<HTMLDivElement, ImageProps>(
             }
           });
         },
-        {
-          rootMargin: "50px", // Start loading slightly before image enters viewport
-        },
+        { rootMargin: "50px" },
       );
 
       observer.observe(container);
-
       return () => observer.disconnect();
     }, [blurOnLoad]);
 
-    // Check if image is already loaded (e.g., from cache)
     useEffect(() => {
       if (!isInView) return;
-
       const img = imgRef.current;
       if (img?.complete && img.naturalHeight !== 0 && img.src === src) {
         setIsLoaded(true);
@@ -164,119 +98,85 @@ export const Image = forwardRef<HTMLDivElement, ImageProps>(
       }
     }, [isInView, src]);
 
-    // Calculate aspect ratio padding (must be inline - truly dynamic calculation)
-    const dynamicAspectRatio = aspectRatio
-      ? (() => {
-          const [width, height] = aspectRatio.split("/").map(Number);
-          return { aspectRatio: `${width} / ${height}`, width: "100%" };
-        })()
-      : undefined;
-
     const showBlur = blurOnLoad && !highResLoaded && blurDataURL;
-    const showCopyrightInside =
-      copyright &&
-      (copyrightPosition === "inline-white" ||
-        copyrightPosition === "inline-black" ||
-        copyrightPosition === "overlay");
+    const showCopyrightInside = copyright && copyrightPosition !== "below";
 
-    // Don't render if no src provided
-    if (!src) {
-      return null;
-    }
+    if (!src) return null;
 
-    return (
+    const mediaContent = (
       <>
-        <Box
-          ref={(node: HTMLDivElement | null) => {
-            // Handle multiple refs
-            if (typeof ref === "function") {
-              ref(node);
-            } else if (ref) {
-              ref.current = node;
+        {showBlur && (
+          <img
+            src={blurDataURL}
+            alt=""
+            aria-hidden="true"
+            className={css({
+              position: "absolute",
+              inset: 0,
+              width: "100%",
+              height: "100%",
+              objectFit: "cover",
+              filter: "blur(20px)",
+              transform: "scale(1.1)",
+              transition: "opacity 0.3s ease-in-out",
+            })}
+            style={{ opacity: highResLoaded ? 0 : 1 }}
+          />
+        )}
+        <img
+          ref={(node) => {
+            if (node) {
+              imgRef.current = node;
+              currentSrcRef.current = isInView ? src : blurDataURL || src;
             }
-            containerRef.current = node;
           }}
+          src={isInView ? src : blurDataURL || src}
+          alt={alt}
           className={cx(
             css({
-              position: "relative",
+              width: "100%",
+              height: "100%",
               display: "block",
-              overflow: "hidden",
               boxSizing: "border-box",
-              ...cssProp,
+              transition: "opacity 0.3s ease-in-out",
             }),
-            wrapperClassName,
-          )}
-          style={{ ...wrapperStyle, ...dynamicAspectRatio }}
-        >
-          {/* Blur placeholder */}
-          {showBlur && (
-            <img
-              src={blurDataURL}
-              alt=""
-              aria-hidden="true"
-              className={css({
-                position: "absolute",
-                inset: 0,
-                width: "100%",
-                height: "100%",
-                objectFit: "cover",
-                filter: "blur(20px)",
-                transform: "scale(1.1)",
-                transition: "opacity 0.3s ease-in-out",
-              })}
-              style={{ opacity: highResLoaded ? 0 : 1 }}
-            />
+            className,
           )}
+          style={{
+            objectFit,
+            ...style,
+            opacity: blurOnLoad && !highResLoaded ? 0 : 1,
+          }}
+          onLoad={handleLoad}
+          onError={handleError}
+          {...props}
+        />
+        {showCopyrightInside && (
+          <CopyrightLabel text={copyright} position={copyrightPosition} />
+        )}
+      </>
+    );
 
-          {/* Main image */}
-          <img
-            ref={(node) => {
-              if (node) {
-                imgRef.current = node;
-                // Track current src for load detection
-                const imgSrc = isInView ? src : blurDataURL || src;
-                currentSrcRef.current = imgSrc;
-              }
-            }}
-            src={isInView ? src : blurDataURL || src}
-            alt={alt}
-            className={cx(
-              css({
-                width: "100%",
-                height: "100%",
-                display: "block",
-                boxSizing: "border-box",
-                transition: "opacity 0.3s ease-in-out",
-              }),
-              className,
-            )}
-            style={{
-              objectFit,
-              ...style,
-              opacity: blurOnLoad && !highResLoaded ? 0 : 1,
+    return (
+      <>
+        {aspectRatio ? (
+          <AspectRatio ref={mergeRef} ratio={aspectRatio} css={cssProp}>
+            {mediaContent}
+          </AspectRatio>
+        ) : (
+          <Box
+            ref={mergeRef}
+            css={{
+              position: "relative",
+              display: "block",
+              overflow: "hidden",
+              boxSizing: "border-box",
+              ...cssProp,
             }}
-            onLoad={handleLoad}
-            onError={handleError}
-            {...props}
-          />
-
-          {/* Copyright inline white (vertical on right side) */}
-          {showCopyrightInside && copyrightPosition === "inline-white" && (
-            <CopyrightLabel text={copyright} position="inline-white" />
-          )}
-
-          {/* Copyright overlay (bottom gradient) */}
-          {showCopyrightInside && copyrightPosition === "overlay" && (
-            <CopyrightLabel text={copyright} position="overlay" />
-          )}
-
-          {/* Copyright inline black */}
-          {showCopyrightInside && copyrightPosition === "inline-black" && (
-            <CopyrightLabel text={copyright} position="inline-black" />
-          )}
-        </Box>
-
-        {/* Copyright below image */}
+          >
+            {mediaContent}
+          </Box>
+        )}
         {copyright && copyrightPosition === "below" && (
           <CopyrightLabel text={copyright} position="below" />
         )}
diff --git a/packages/ui/src/components/video/video.tsx b/packages/ui/src/components/video/video.tsx
index 1fa9a044..e2ca2c1a 100644
--- a/packages/ui/src/components/video/video.tsx
+++ b/packages/ui/src/components/video/video.tsx
@@ -4,87 +4,27 @@ import type { VideoHTMLAttributes } from "react";
 import { forwardRef, useEffect, useRef, useState } from "react";
 import { css, cx } from "styled-system/css";
 import type { SystemStyleObject } from "styled-system/types";
-import { Box } from "../box/box";
+import { AspectRatio } from "../aspect-ratio";
 import { CopyrightLabel, type CopyrightPosition } from "../copyright-label";
 import { VideoControls } from "./video-controls";
 
-/**
- * Video source types
- */
 export type VideoSource = "native" | "youtube" | "vimeo";
 
-/**
- * Video component props
- */
 export interface VideoProps
   extends Omit<VideoHTMLAttributes<HTMLVideoElement>, "css" | "src"> {
-  /**
-   * Video source URL or ID
-   * - For native: direct video URL
-   * - For YouTube: video ID or full URL
-   * - For Vimeo: video ID or full URL
-   */
   src: string;
-  /**
-   * Video source type
-   * @default "native"
-   */
   source?: VideoSource;
-  /**
-   * Poster image URL (only for native videos)
-   */
   poster?: string;
-  /**
-   * Show custom controls
-   * @default true
-   */
   controls?: boolean;
-  /**
-   * Autoplay video
-   * @default false
-   */
   autoPlay?: boolean;
-  /**
-   * Loop video
-   * @default false
-   */
   loop?: boolean;
-  /**
-   * Mute video
-   * @default false
-   */
   muted?: boolean;
-  /**
-   * Aspect ratio preset or custom value
-   * @default "16/9"
-   */
   aspectRatio?: "1/1" | "4/3" | "16/9" | "21/9" | "9/16" | number;
-  /**
-   * Copyright text
-   */
   copyright?: string;
-  /**
-   * Copyright position
-   * @default "inline"
-   */
   copyrightPosition?: CopyrightPosition;
-  /**
-   * Custom styles for the wrapper
-   */
-  wrapperStyle?: React.CSSProperties;
-  /**
-   * Custom class name for the wrapper
-   */
-  wrapperClassName?: string;
-  /**
-   * Custom styles using Panda CSS SystemStyleObject
-   */
   css?: SystemStyleObject;
 }
 
-/**
- * Extract YouTube video ID from URL
- */
 function getYouTubeId(url: string): string {
   if (url.length === 11 && !url.includes("/") && !url.includes("?")) {
     return url;
@@ -95,71 +35,12 @@ function getYouTubeId(url: string): string {
   return match && match[7].length === 11 ? match[7] : url;
 }
 
-/**
- * Extract Vimeo video ID from URL
- */
 function getVimeoId(url: string): string {
-  if (/^\d+$/.test(url)) {
-    return url;
-  }
-  const regExp = /vimeo\.com\/(?:video\/)?(\d+)/;
-  const match = url.match(regExp);
+  if (/^\d+$/.test(url)) return url;
+  const match = url.match(/vimeo\.com\/(?:video\/)?(\d+)/);
   return match ? match[1] : url;
 }
 
-/**
- * Video component - Multi-source video player with custom controls
- *
- * A versatile video component that supports native HTML5 videos, YouTube embeds,
- * and Vimeo embeds. Features custom controls, copyright display, and responsive
- * aspect ratios using Panda CSS.
- *
- * **Supported Sources:**
- * - Native HTML5 videos with custom controls (play/pause, seek, volume)
- * - YouTube embeds with configurable player options
- * - Vimeo embeds with configurable player options
- *
- * **Features:**
- * - 🎬 Custom video controls with progress bar and volume
- * - 📐 Responsive aspect ratios (16/9, 4/3, 1/1, 21/9, 9/16, custom)
- * - ©️ Copyright text support (below or overlay)
- * - 🎨 Fully styled with Panda CSS
- * - ♿️ Accessible controls with ARIA labels
- *
- * @example
- * ```tsx
- * // Native HTML5 video with custom controls
- * <video
- *   src="https://example.com/video.mp4"
- *   poster="https://example.com/poster.jpg"
- *   controls
- *   copyright="© 2025 Creator Name"
- * />
- * ```
- *
- * @example
- * ```tsx
- * // YouTube embed
- * <video
- *   src="dQw4w9WgXcQ"
- *   source="youtube"
- *   aspectRatio="16/9"
- *   controls
- * />
- * ```
- *
- * @example
- * ```tsx
- * // Vimeo embed with autoplay
- * <video
- *   src="123456789"
- *   source="vimeo"
- *   autoPlay
- *   muted
- *   loop
- * />
- * ```
- */
 export const Video = forwardRef<HTMLDivElement, VideoProps>(
   (
     {
@@ -173,8 +54,6 @@ export const Video = forwardRef<HTMLDivElement, VideoProps>(
       aspectRatio = "16/9",
       copyright,
       copyrightPosition = "inline-white",
-      wrapperStyle,
-      wrapperClassName,
       className,
       style,
       css: cssProp,
@@ -185,136 +64,57 @@ export const Video = forwardRef<HTMLDivElement, VideoProps>(
     const videoRef = useRef<HTMLVideoElement>(null);
     const [isLoading, setIsLoading] = useState(true);
 
-    // Check if video is already loaded (e.g., from cache)
     useEffect(() => {
       const video = videoRef.current;
       if (video?.readyState !== undefined && video.readyState >= 2) {
-        // HAVE_CURRENT_DATA or better
         setIsLoading(false);
       }
     }, []);
 
-    // Render YouTube embed
-    if (source === "youtube") {
-      const videoId = getYouTubeId(src);
-      const embedUrl = `https://www.youtube.com/embed/${videoId}?autoplay=${autoPlay ? 1 : 0}&loop=${loop ? 1 : 0}&mute=${muted ? 1 : 0}&controls=${controls ? 1 : 0}`;
-
-      const ratioValue =
-        typeof aspectRatio === "number" ? `${aspectRatio}` : aspectRatio;
-
-      return (
-        <>
-          <Box
-            ref={ref}
-            className={cx(wrapperClassName)}
-            css={{
-              position: "relative",
-              w: "100%",
-              overflow: "hidden",
-              ...cssProp,
-            }}
-            style={{ aspectRatio: ratioValue, ...wrapperStyle }}
-          >
-            {/* Loading skeleton */}
-            <Box
-              className={css({
-                position: "absolute",
-                inset: 0,
-                w: "100%",
-                h: "100%",
-                bg: "linear-gradient(90deg, #f0f0f0 0%, #e0e0e0 50%, #f0f0f0 100%)",
-                backgroundSize: "200% 100%",
-                animation: "shimmer 1.5s ease-in-out infinite",
-                zIndex: 1,
-                opacity: isLoading ? 1 : 0,
-                transition: "opacity 0.5s ease-in-out",
-                pointerEvents: isLoading ? "auto" : "none",
-              })}
-            />
-
-            <iframe
-              src={embedUrl}
-              title="YouTube video player"
-              allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-              allowFullScreen
-              onLoad={() => setIsLoading(false)}
-              className={css({
-                position: "absolute",
-                inset: 0,
-                w: "100%",
-                h: "100%",
-                border: "none",
-                opacity: isLoading ? 0 : 1,
-                transition: "opacity 0.5s ease-in-out",
-              })}
-            />
-
-            {/* Copyright inline white (vertical on right side) */}
-            {copyright && copyrightPosition === "inline-white" && (
-              <CopyrightLabel text={copyright} position="inline-white" />
-            )}
-
-            {/* Copyright overlay (bottom gradient) */}
-            {copyright && copyrightPosition === "overlay" && (
-              <CopyrightLabel text={copyright} position="overlay" />
-            )}
-
-            {/* Copyright inline black */}
-            {copyright && copyrightPosition === "inline-black" && (
-              <CopyrightLabel text={copyright} position="inline-black" />
-            )}
-          </Box>
-
-          {/* Copyright below video */}
-          {copyright && copyrightPosition === "below" && (
-            <CopyrightLabel text={copyright} position="below" />
-          )}
-        </>
-      );
-    }
+    const ratio =
+      typeof aspectRatio === "number" ? aspectRatio : aspectRatio;
+
+    const showCopyrightInside = copyright && copyrightPosition !== "below";
+
+    const skeleton = (
+      <div
+        className={css({
+          position: "absolute",
+          inset: 0,
+          w: "100%",
+          h: "100%",
+          bg: "linear-gradient(90deg, #f0f0f0 0%, #e0e0e0 50%, #f0f0f0 100%)",
+          backgroundSize: "200% 100%",
+          animation: "shimmer 1.5s ease-in-out infinite",
+          zIndex: 1,
+          opacity: isLoading ? 1 : 0,
+          transition: "opacity 0.5s ease-in-out",
+          pointerEvents: isLoading ? "auto" : "none",
+        })}
+      />
+    );
 
-    // Render Vimeo embed
-    if (source === "vimeo") {
-      const videoId = getVimeoId(src);
-      const embedUrl = `https://player.vimeo.com/video/${videoId}?autoplay=${autoPlay ? 1 : 0}&loop=${loop ? 1 : 0}&muted=${muted ? 1 : 0}&controls=${controls ? 1 : 0}`;
+    if (source === "youtube" || source === "vimeo") {
+      const embedUrl =
+        source === "youtube"
+          ? `https://www.youtube.com/embed/${getYouTubeId(src)}?autoplay=${autoPlay ? 1 : 0}&loop=${loop ? 1 : 0}&mute=${muted ? 1 : 0}&controls=${controls ? 1 : 0}`
+          : `https://player.vimeo.com/video/${getVimeoId(src)}?autoplay=${autoPlay ? 1 : 0}&loop=${loop ? 1 : 0}&muted=${muted ? 1 : 0}&controls=${controls ? 1 : 0}`;
 
-      const ratioValue =
-        typeof aspectRatio === "number" ? `${aspectRatio}` : aspectRatio;
+      const title =
+        source === "youtube" ? "YouTube video player" : "Vimeo video player";
+      const allow =
+        source === "youtube"
+          ? "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          : "autoplay; fullscreen; picture-in-picture";
 
       return (
         <>
-          <Box
-            ref={ref}
-            className={cx(wrapperClassName)}
-            css={{
-              position: "relative",
-              w: "100%",
-              overflow: "hidden",
-              ...cssProp,
-            }}
-            style={{ aspectRatio: ratioValue, ...wrapperStyle }}
-          >
-            {/* Loading skeleton */}
-            <Box
-              className={css({
-                position: "absolute",
-                inset: 0,
-                w: "100%",
-                h: "100%",
-                bg: "linear-gradient(90deg, #f0f0f0 0%, #e0e0e0 50%, #f0f0f0 100%)",
-                backgroundSize: "200% 100%",
-                animation: "shimmer 1.5s ease-in-out infinite",
-                zIndex: 1,
-                opacity: isLoading ? 1 : 0,
-                transition: "opacity 0.5s ease-in-out",
-                pointerEvents: isLoading ? "auto" : "none",
-              })}
-            />
-
+          <AspectRatio ref={ref} ratio={ratio} css={cssProp}>
+            {skeleton}
             <iframe
               src={embedUrl}
-              title="Vimeo video player"
-              allow="autoplay; fullscreen; picture-in-picture"
+              title={title}
+              allow={allow}
               allowFullScreen
               onLoad={() => setIsLoading(false)}
               className={css({
@@ -327,24 +127,10 @@ export const Video = forwardRef<HTMLDivElement, VideoProps>(
                 transition: "opacity 0.5s ease-in-out",
               })}
             />
-
-            {/* Copyright inline white (vertical on right side) */}
-            {copyright && copyrightPosition === "inline-white" && (
-              <CopyrightLabel text={copyright} position="inline-white" />
+            {showCopyrightInside && (
+              <CopyrightLabel text={copyright} position={copyrightPosition} />
             )}
-
-            {/* Copyright overlay (bottom gradient) */}
-            {copyright && copyrightPosition === "overlay" && (
-              <CopyrightLabel text={copyright} position="overlay" />
-            )}
-
-            {/* Copyright inline black */}
-            {copyright && copyrightPosition === "inline-black" && (
-              <CopyrightLabel text={copyright} position="inline-black" />
-            )}
-          </Box>
-
-          {/* Copyright below video */}
+          </AspectRatio>
           {copyright && copyrightPosition === "below" && (
             <CopyrightLabel text={copyright} position="below" />
           )}
@@ -352,41 +138,17 @@ export const Video = forwardRef<HTMLDivElement, VideoProps>(
       );
     }
 
-    // Render native video with custom controls
-    const ratioValue =
-      typeof aspectRatio === "number" ? `${aspectRatio}` : aspectRatio;
-
     return (
       <>
-        <Box
+        <AspectRatio
           ref={ref}
-          className={cx(wrapperClassName)}
+          ratio={ratio}
           css={{
-            position: "relative",
-            w: "100%",
-            overflow: "hidden",
             background: "linear-gradient(135deg, #f5f5f5 0%, #e0e0e0 100%)",
             ...cssProp,
           }}
-          style={{ aspectRatio: ratioValue, ...wrapperStyle }}
         >
-          {/* Loading skeleton */}
-          <Box
-            className={css({
-              position: "absolute",
-              inset: 0,
-              w: "100%",
-              h: "100%",
-              bg: "linear-gradient(90deg, #f0f0f0 0%, #e0e0e0 50%, #f0f0f0 100%)",
-              backgroundSize: "200% 100%",
-              animation: "shimmer 1.5s ease-in-out infinite",
-              zIndex: 1,
-              opacity: isLoading ? 1 : 0,
-              transition: "opacity 0.5s ease-in-out",
-              pointerEvents: isLoading ? "auto" : "none",
-            })}
-          />
-
+          {skeleton}
           <video
             ref={videoRef}
             src={src}
@@ -412,27 +174,11 @@ export const Video = forwardRef<HTMLDivElement, VideoProps>(
             style={style}
             {...props}
           />
-
-          {/* Custom controls */}
           <VideoControls videoRef={videoRef} show={controls} />
-
-          {/* Copyright inline white (vertical on right side) */}
-          {copyright && copyrightPosition === "inline-white" && (
-            <CopyrightLabel text={copyright} position="inline-white" />
-          )}
-
-          {/* Copyright overlay (bottom gradient) */}
-          {copyright && copyrightPosition === "overlay" && (
-            <CopyrightLabel text={copyright} position="overlay" />
-          )}
-
-          {/* Copyright inline black */}
-          {copyright && copyrightPosition === "inline-black" && (
-            <CopyrightLabel text={copyright} position="inline-black" />
+          {showCopyrightInside && (
+            <CopyrightLabel text={copyright} position={copyrightPosition} />
           )}
-        </Box>
-
-        {/* Copyright below video */}
+        </AspectRatio>
         {copyright && copyrightPosition === "below" && (
           <CopyrightLabel text={copyright} position="below" />
         )}

From 7eccd5dae4500bdab6b29edde3af1b039ad3613a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 20 Mar 2026 13:13:53 +0000
Subject: [PATCH 2/5] fix: add "3/4" to AspectRatio ratio type

Image accepts "3/4" as an aspect ratio (used by SbImage), so
AspectRatio needs to include it in its ratio union type.

https://claude.ai/code/session_01DLAMCPXYx7Z9kuqQ5RKLNM
---
 packages/ui/src/components/aspect-ratio/aspect-ratio.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx b/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx
index 9128d9da..157119b0 100644
--- a/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx
+++ b/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx
@@ -15,7 +15,7 @@ export interface AspectRatioProps
    * Aspect ratio preset or custom value
    * @default "16/9"
    */
-  ratio?: "1/1" | "4/3" | "16/9" | "21/9" | "9/16" | number;
+  ratio?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16" | number;
   /**
    * Custom styles using Panda CSS SystemStyleObject
    */

From e920d4fc65496bcbd732932a19835072eaf090c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 20 Mar 2026 13:50:45 +0000
Subject: [PATCH 3/5] fix: tighten Slideshow aspectRatio type to match
 Image/Video union

Slideshow typed aspectRatio as string which caused a type error when
passed to Image's strict union type. Align all three sites (sub-props
interface, component props, Video cast removal) to the same union.

https://claude.ai/code/session_01DLAMCPXYx7Z9kuqQ5RKLNM
---
 packages/ui/src/components/slideshow/slideshow.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/ui/src/components/slideshow/slideshow.tsx b/packages/ui/src/components/slideshow/slideshow.tsx
index ae9a402b..9d50bd38 100644
--- a/packages/ui/src/components/slideshow/slideshow.tsx
+++ b/packages/ui/src/components/slideshow/slideshow.tsx
@@ -72,7 +72,7 @@ const SWIPER_CREATIVE_EFFECT = {
 interface SlideshowVideoSlideProps {
   videoUrl: string;
   videoPoster?: string;
-  aspectRatio: string;
+  aspectRatio: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16";
 }
 
 function SlideshowVideoSlide({
@@ -85,7 +85,7 @@ function SlideshowVideoSlide({
     <VideoComponent
       src={videoUrl}
       poster={videoPoster}
-      aspectRatio={aspectRatio as "16/9" | "4/3" | "1/1" | "21/9" | "9/16"}
+      aspectRatio={aspectRatio}
       autoPlay
       muted
       loop
@@ -162,7 +162,7 @@ export interface SlideshowProps {
    * Aspect ratio for images
    * @default "16/9"
    */
-  aspectRatio?: string;
+  aspectRatio?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16";
   /**
    * Autoplay delay in milliseconds
    * @default 7000

From 15b060ab8db5e10b9a1b4a0a35c419412df996c6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 20 Mar 2026 13:55:05 +0000
Subject: [PATCH 4/5] fix: add "3/4" to Video aspectRatio type

Slideshow passes "3/4" to Video, which was missing it from its union.
Aligns with AspectRatio and Image types.

https://claude.ai/code/session_01DLAMCPXYx7Z9kuqQ5RKLNM
---
 packages/ui/src/components/video/video.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/src/components/video/video.tsx b/packages/ui/src/components/video/video.tsx
index e2ca2c1a..7ecce00f 100644
--- a/packages/ui/src/components/video/video.tsx
+++ b/packages/ui/src/components/video/video.tsx
@@ -19,7 +19,7 @@ export interface VideoProps
   autoPlay?: boolean;
   loop?: boolean;
   muted?: boolean;
-  aspectRatio?: "1/1" | "4/3" | "16/9" | "21/9" | "9/16" | number;
+  aspectRatio?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16" | number;
   copyright?: string;
   copyrightPosition?: CopyrightPosition;
   css?: SystemStyleObject;

From 057fc79d623876f15a3d40373049d5c6e3d6c82f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 20 Mar 2026 14:13:08 +0000
Subject: [PATCH 5/5] refactor: grid/grid-item system, unify spacing, fix
 aspectRatio types
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Widen aspectRatio to string/string|number across AspectRatio, Image, Video, Slideshow — removes repeated type errors from CMS-driven values
- Refactor Grid: module-level GRID_COLUMNS_MAP, add as/columnsMd/columnsLg props, responsive columns via CSS custom properties
- Export GRID_COLUMNS_MAP and GridColumns from ui package index
- Refactor SbGrid to use Grid from @httpjpg/ui instead of reimplementing CSS; unify spacing fields (spacingTop/spacingBottom/paddingTop/paddingBottom)
- Refactor SbGridItem: extract pure helper functions, clean buildResponsiveStyles
- sync-components: add Storyblok tab panels to grid/grid-item schemas, extract COL_SPAN_OPTIONS constant, align spacing field names

https://claude.ai/code/session_01DLAMCPXYx7Z9kuqQ5RKLNM
---
 .../storyblok-sync/scripts/sync-components.ts | 182 ++++++++++------
 .../src/components/grid-item/SbGridItem.tsx   | 145 ++++++-------
 .../src/components/grid/SbGrid.tsx            | 203 ++++++++----------
 .../components/aspect-ratio/aspect-ratio.tsx  |   2 +-
 packages/ui/src/components/grid/grid.tsx      | 167 ++++++--------
 packages/ui/src/components/grid/index.ts      |   4 +-
 packages/ui/src/components/image/image.tsx    |   2 +-
 .../ui/src/components/slideshow/slideshow.tsx |   4 +-
 packages/ui/src/components/video/video.tsx    |   2 +-
 9 files changed, 347 insertions(+), 364 deletions(-)

diff --git a/packages/storyblok-sync/scripts/sync-components.ts b/packages/storyblok-sync/scripts/sync-components.ts
index bf28c5c8..82e30d64 100755
--- a/packages/storyblok-sync/scripts/sync-components.ts
+++ b/packages/storyblok-sync/scripts/sync-components.ts
@@ -341,6 +341,22 @@ async function getSbContainerComponent(): Promise<StoryblokComponent> {
   };
 }
 
+const COL_SPAN_OPTIONS = [
+  { name: "1", value: "1" },
+  { name: "2", value: "2" },
+  { name: "3", value: "3" },
+  { name: "4", value: "4" },
+  { name: "5", value: "5" },
+  { name: "6", value: "6" },
+  { name: "7", value: "7" },
+  { name: "8", value: "8" },
+  { name: "9", value: "9" },
+  { name: "10", value: "10" },
+  { name: "11", value: "11" },
+  { name: "12", value: "12" },
+  { name: "Full", value: "full" },
+];
+
 async function getSbGridComponent(): Promise<StoryblokComponent> {
   const layoutGroupUuid = await getComponentGroupUuid("Layout");
 
@@ -353,48 +369,89 @@ async function getSbGridComponent(): Promise<StoryblokComponent> {
     icon: "block-grid",
     color: "#4a5568",
     schema: {
+      // ── Tab: Content ────────────────────────────────────────────────────────
+      "tab-content": {
+        type: "tab",
+        display_name: "Content",
+        pos: 0,
+      },
       items: {
         type: "bloks",
         display_name: "Grid Items",
         required: true,
         restrict_components: true,
         component_whitelist: [],
+        pos: 1,
+      },
+      // ── Tab: Layout ─────────────────────────────────────────────────────────
+      "tab-layout": {
+        type: "tab",
+        display_name: "Layout",
+        pos: 10,
       },
       columns: {
         type: "option",
         display_name: "Columns",
         source: "internal",
         datasource_slug: "grid-columns",
+        pos: 11,
       },
       columnsMd: {
         type: "option",
         display_name: "Columns (Tablet)",
         source: "internal",
         datasource_slug: "grid-columns",
+        pos: 12,
       },
       columnsLg: {
         type: "option",
         display_name: "Columns (Desktop)",
         source: "internal",
         datasource_slug: "grid-columns",
+        pos: 13,
+      },
+      boundingWidth: {
+        type: "option",
+        display_name: "Width",
+        default_value: "full",
+        options: [
+          { name: "Full Width", value: "full" },
+          { name: "Container", value: "container" },
+        ],
+        pos: 14,
+      },
+      isList: {
+        type: "boolean",
+        display_name: "Render as List (<ul>)",
+        default_value: "false",
+        pos: 15,
+      },
+      // ── Tab: Gap & Alignment ─────────────────────────────────────────────────
+      "tab-gaps": {
+        type: "tab",
+        display_name: "Gap & Alignment",
+        pos: 20,
       },
       gap: {
         type: "option",
         display_name: "Gap",
         source: "internal",
         datasource_slug: "spacing-options",
+        pos: 21,
       },
       rowGap: {
         type: "option",
         display_name: "Row Gap",
         source: "internal",
         datasource_slug: "spacing-options",
+        pos: 22,
       },
       columnGap: {
         type: "option",
         display_name: "Column Gap",
         source: "internal",
         datasource_slug: "spacing-options",
+        pos: 23,
       },
       alignItems: {
         type: "option",
@@ -405,6 +462,7 @@ async function getSbGridComponent(): Promise<StoryblokComponent> {
           { name: "End", value: "end" },
           { name: "Stretch", value: "stretch" },
         ],
+        pos: 24,
       },
       justifyItems: {
         type: "option",
@@ -415,6 +473,7 @@ async function getSbGridComponent(): Promise<StoryblokComponent> {
           { name: "End", value: "end" },
           { name: "Stretch", value: "stretch" },
         ],
+        pos: 25,
       },
       justifyContent: {
         type: "option",
@@ -427,6 +486,7 @@ async function getSbGridComponent(): Promise<StoryblokComponent> {
           { name: "Space Around", value: "space-around" },
           { name: "Space Evenly", value: "space-evenly" },
         ],
+        pos: 26,
       },
       autoFlow: {
         type: "option",
@@ -437,44 +497,41 @@ async function getSbGridComponent(): Promise<StoryblokComponent> {
           { name: "Row Dense", value: "row dense" },
           { name: "Column Dense", value: "column dense" },
         ],
+        pos: 27,
       },
-      boundingWidth: {
-        type: "option",
-        display_name: "Width",
-        default_value: "full",
-        options: [
-          { name: "Full Width", value: "full" },
-          { name: "Container", value: "container" },
-        ],
+      // ── Tab: Spacing ─────────────────────────────────────────────────────────
+      "tab-spacing": {
+        type: "tab",
+        display_name: "Spacing",
+        pos: 30,
       },
-      isList: {
-        type: "boolean",
-        display_name: "Render as List",
-        default_value: "false",
-      },
-      pt: {
+      spacingTop: {
         type: "option",
-        display_name: "Padding Top",
+        display_name: "Spacing Top",
         source: "internal",
         datasource_slug: "spacing-options",
+        pos: 31,
       },
-      pb: {
+      spacingBottom: {
         type: "option",
-        display_name: "Padding Bottom",
+        display_name: "Spacing Bottom",
         source: "internal",
         datasource_slug: "spacing-options",
+        pos: 32,
       },
-      mt: {
+      paddingTop: {
         type: "option",
-        display_name: "Margin Top",
+        display_name: "Padding Top",
         source: "internal",
         datasource_slug: "spacing-options",
+        pos: 33,
       },
-      mb: {
+      paddingBottom: {
         type: "option",
-        display_name: "Margin Bottom",
+        display_name: "Padding Bottom",
         source: "internal",
         datasource_slug: "spacing-options",
+        pos: 34,
       },
     },
   };
@@ -492,97 +549,90 @@ async function getSbGridItemComponent(): Promise<StoryblokComponent> {
     icon: "block-square",
     color: "#4a5568",
     schema: {
+      // ── Tab: Content ────────────────────────────────────────────────────────
+      "tab-content": {
+        type: "tab",
+        display_name: "Content",
+        pos: 0,
+      },
       content: {
         type: "bloks",
         display_name: "Content",
         required: false,
         restrict_components: true,
         component_whitelist: [],
+        pos: 1,
+      },
+      // ── Tab: Column ──────────────────────────────────────────────────────────
+      "tab-column": {
+        type: "tab",
+        display_name: "Column",
+        pos: 10,
       },
       colSpan: {
         type: "option",
         display_name: "Column Span",
-        options: [
-          { name: "1", value: "1" },
-          { name: "2", value: "2" },
-          { name: "3", value: "3" },
-          { name: "4", value: "4" },
-          { name: "5", value: "5" },
-          { name: "6", value: "6" },
-          { name: "7", value: "7" },
-          { name: "8", value: "8" },
-          { name: "9", value: "9" },
-          { name: "10", value: "10" },
-          { name: "11", value: "11" },
-          { name: "12", value: "12" },
-          { name: "Full", value: "full" },
-        ],
+        options: COL_SPAN_OPTIONS,
+        pos: 11,
       },
       colSpanMd: {
         type: "option",
         display_name: "Column Span (Tablet)",
-        options: [
-          { name: "1", value: "1" },
-          { name: "2", value: "2" },
-          { name: "3", value: "3" },
-          { name: "4", value: "4" },
-          { name: "5", value: "5" },
-          { name: "6", value: "6" },
-          { name: "7", value: "7" },
-          { name: "8", value: "8" },
-          { name: "9", value: "9" },
-          { name: "10", value: "10" },
-          { name: "11", value: "11" },
-          { name: "12", value: "12" },
-          { name: "Full", value: "full" },
-        ],
+        options: COL_SPAN_OPTIONS,
+        pos: 12,
       },
       colSpanLg: {
         type: "option",
         display_name: "Column Span (Desktop)",
-        options: [
-          { name: "1", value: "1" },
-          { name: "2", value: "2" },
-          { name: "3", value: "3" },
-          { name: "4", value: "4" },
-          { name: "5", value: "5" },
-          { name: "6", value: "6" },
-          { name: "7", value: "7" },
-          { name: "8", value: "8" },
-          { name: "9", value: "9" },
-          { name: "10", value: "10" },
-          { name: "11", value: "11" },
-          { name: "12", value: "12" },
-          { name: "Full", value: "full" },
-        ],
+        options: COL_SPAN_OPTIONS,
+        pos: 13,
+      },
+      // ── Tab: Row ─────────────────────────────────────────────────────────────
+      "tab-row": {
+        type: "tab",
+        display_name: "Row",
+        pos: 20,
       },
       rowSpan: {
         type: "number",
         display_name: "Row Span",
+        pos: 21,
       },
       rowSpanMd: {
         type: "number",
         display_name: "Row Span (Tablet)",
+        pos: 22,
       },
       rowSpanLg: {
         type: "number",
         display_name: "Row Span (Desktop)",
+        pos: 23,
+      },
+      // ── Tab: Position ────────────────────────────────────────────────────────
+      "tab-position": {
+        type: "tab",
+        display_name: "Position",
+        pos: 30,
       },
       colStart: {
         type: "number",
         display_name: "Column Start",
+        pos: 31,
       },
       colEnd: {
         type: "number",
         display_name: "Column End",
+        pos: 32,
       },
       rowStart: {
         type: "number",
         display_name: "Row Start",
+        pos: 33,
       },
       rowEnd: {
         type: "number",
         display_name: "Row End",
+        pos: 34,
       },
     },
   };
diff --git a/packages/storyblok-ui/src/components/grid-item/SbGridItem.tsx b/packages/storyblok-ui/src/components/grid-item/SbGridItem.tsx
index 457aac21..20695889 100644
--- a/packages/storyblok-ui/src/components/grid-item/SbGridItem.tsx
+++ b/packages/storyblok-ui/src/components/grid-item/SbGridItem.tsx
@@ -23,11 +23,57 @@ export interface SbGridItemProps {
   };
 }
 
-/**
- * Storyblok Grid Item Component
- * Individual grid cell with precise control over positioning and spanning
- * Use inside SbGrid for editorial-style layouts with asymmetric compositions
- */
+function parseColSpan(
+  value?: string,
+): 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | "full" | undefined {
+  if (!value) return undefined;
+  if (value === "full") return "full";
+  const num = Number.parseInt(value, 10);
+  if (Number.isNaN(num) || num < 1 || num > 12) return undefined;
+  return num as 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+}
+
+function parseRowSpan(value?: string): number | undefined {
+  if (!value) return undefined;
+  const num = Number.parseInt(value, 10);
+  return !Number.isNaN(num) && num >= 1 ? num : undefined;
+}
+
+function parsePosition(value?: string): number | undefined {
+  if (!value) return undefined;
+  const num = Number.parseInt(value, 10);
+  return Number.isNaN(num) ? undefined : num;
+}
+
+function colSpanToCss(value: string): string {
+  return value === "full" ? "1 / -1" : `span ${parseColSpan(value) ?? 1}`;
+}
+
+function buildResponsiveStyles(uid: string, blok: SbGridItemProps["blok"]): string {
+  const { colSpanMd, colSpanLg, rowSpanMd, rowSpanLg } = blok;
+  const rules: string[] = [];
+
+  if (colSpanMd || rowSpanMd) {
+    const declarations: string[] = [];
+    if (colSpanMd) declarations.push(`grid-column:${colSpanToCss(colSpanMd)}`);
+    if (rowSpanMd) declarations.push(`grid-row:span ${parseRowSpan(rowSpanMd) ?? 1}`);
+    rules.push(
+      `@media(min-width:768px){[data-sb-grid-item="${uid}"]{${declarations.join(";")}}}`
+    );
+  }
+
+  if (colSpanLg || rowSpanLg) {
+    const declarations: string[] = [];
+    if (colSpanLg) declarations.push(`grid-column:${colSpanToCss(colSpanLg)}`);
+    if (rowSpanLg) declarations.push(`grid-row:span ${parseRowSpan(rowSpanLg) ?? 1}`);
+    rules.push(
+      `@media(min-width:1024px){[data-sb-grid-item="${uid}"]{${declarations.join(";")}}}`
+    );
+  }
+
+  return rules.join("");
+}
+
 export const SbGridItem = memo(function SbGridItem({ blok }: SbGridItemProps) {
   const {
     content,
@@ -44,91 +90,22 @@ export const SbGridItem = memo(function SbGridItem({ blok }: SbGridItemProps) {
   } = blok;
 
   const editableProps = useStoryblokEditable(blok);
-
-  // Parse column span (supports "full" value)
-  const parseColSpan = (
-    value?: string,
-  ): 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | "full" | undefined => {
-    if (!value) {
-      return undefined;
-    }
-    if (value === "full") {
-      return "full";
-    }
-    const num = Number.parseInt(value, 10);
-    if (Number.isNaN(num) || num < 1 || num > 12) {
-      return undefined;
-    }
-    return num as 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
-  };
-
-  // Parse row span (numeric only, no "full")
-  const parseRowSpan = (value?: string): number | undefined => {
-    if (!value) {
-      return undefined;
-    }
-    const num = Number.parseInt(value, 10);
-    return Number.isNaN(num) || num < 1 ? undefined : num;
-  };
-
-  const parsePosition = (value?: string): number | undefined => {
-    if (!value) {
-      return undefined;
-    }
-    const num = Number.parseInt(value, 10);
-    return Number.isNaN(num) ? undefined : num;
-  };
-
-  // Parse base span values
-  const baseColSpan = parseColSpan(colSpan);
-  const baseRowSpan = parseRowSpan(rowSpan);
-
-  // Build responsive styles only when we have responsive values
   const hasPositioning = colStart || colEnd || rowStart || rowEnd;
-
-  // Build inline styles for responsive grid positioning via style tag
-  const responsiveStyles =
-    colSpanMd || colSpanLg || rowSpanMd || rowSpanLg ? (
-      <style
-        // biome-ignore lint/security/noDangerouslySetInnerHtml: Safe - controlled values for responsive grid styles
-        dangerouslySetInnerHTML={{
-          __html: `
-        ${
-          colSpanMd || rowSpanMd
-            ? `
-          @media (min-width: 768px) {
-            [data-sb-grid-item="${blok._uid}"] {
-              ${colSpanMd ? `grid-column: ${colSpanMd === "full" ? "1 / -1" : `span ${parseColSpan(colSpanMd)}`};` : ""}
-              ${rowSpanMd ? `grid-row: span ${parseRowSpan(rowSpanMd)};` : ""}
-            }
-          }
-        `
-            : ""
-        }
-        ${
-          colSpanLg || rowSpanLg
-            ? `
-          @media (min-width: 1024px) {
-            [data-sb-grid-item="${blok._uid}"] {
-              ${colSpanLg ? `grid-column: ${colSpanLg === "full" ? "1 / -1" : `span ${parseColSpan(colSpanLg)}`};` : ""}
-              ${rowSpanLg ? `grid-row: span ${parseRowSpan(rowSpanLg)};` : ""}
-            }
-          }
-        `
-            : ""
-        }
-      `,
-        }}
-      />
-    ) : null;
+  const hasResponsive = colSpanMd || colSpanLg || rowSpanMd || rowSpanLg;
+  const responsiveCss = hasResponsive ? buildResponsiveStyles(blok._uid, blok) : null;
 
   return (
     <>
-      {responsiveStyles}
+      {responsiveCss && (
+        <style
+          // biome-ignore lint/security/noDangerouslySetInnerHtml: controlled values — grid span/position strings
+          dangerouslySetInnerHTML={{ __html: responsiveCss }}
+        />
+      )}
       <GridItem
         {...editableProps}
-        colSpan={hasPositioning ? undefined : baseColSpan}
-        rowSpan={hasPositioning ? undefined : baseRowSpan}
+        colSpan={hasPositioning ? undefined : parseColSpan(colSpan)}
+        rowSpan={hasPositioning ? undefined : parseRowSpan(rowSpan)}
         colStart={parsePosition(colStart)}
         colEnd={parsePosition(colEnd)}
         rowStart={parsePosition(rowStart)}
diff --git a/packages/storyblok-ui/src/components/grid/SbGrid.tsx b/packages/storyblok-ui/src/components/grid/SbGrid.tsx
index 4e557512..85cf6b01 100644
--- a/packages/storyblok-ui/src/components/grid/SbGrid.tsx
+++ b/packages/storyblok-ui/src/components/grid/SbGrid.tsx
@@ -1,10 +1,10 @@
 "use client";
 
 import { type BlokItem, DynamicRender } from "@httpjpg/storyblok-utils";
+import { type GridColumns, type GridProps, Grid, GRID_COLUMNS_MAP } from "@httpjpg/ui";
 import type { SbBlokData } from "@storyblok/react/rsc";
 import { memo } from "react";
 import { css } from "styled-system/css";
-import type { SystemStyleObject } from "styled-system/types";
 import { mapSpacingToToken } from "../../lib/spacing-utils";
 import { useStoryblokEditable } from "../../lib/use-storyblok-editable";
 
@@ -24,18 +24,66 @@ export interface SbGridProps {
     autoFlow?: string;
     boundingWidth?: "container" | "full";
     isList?: boolean;
-    pt?: string;
-    pb?: string;
-    mt?: string;
-    mb?: string;
+    spacingTop?: string;
+    spacingBottom?: string;
+    paddingTop?: string;
+    paddingBottom?: string;
   };
 }
 
-/**
- * Storyblok Grid Component
- * Enhanced responsive grid layout with editorial-style controls
- * Supports flexible column configurations, gaps, alignment, and advanced layout options
- */
+function parseColumns(value?: string): GridColumns | undefined {
+  if (!value) return undefined;
+  if (value.toLowerCase().includes("auto")) return "auto";
+  const num = Number.parseInt(value, 10);
+  if (num >= 1 && num <= 12) return num as GridColumns;
+  return undefined;
+}
+
+function parseFlow(value?: string): GridProps["flow"] | undefined {
+  const v = value?.toLowerCase().replace(/\s+/g, "-");
+  if (
+    v === "row" ||
+    v === "column" ||
+    v === "row-dense" ||
+    v === "column-dense"
+  ) {
+    return v;
+  }
+  return undefined;
+}
+
+function parseAlign(
+  value?: string,
+): "start" | "center" | "end" | "stretch" | undefined {
+  const v = value?.toLowerCase() as
+    | "start"
+    | "center"
+    | "end"
+    | "stretch"
+    | undefined;
+  if (v === "start" || v === "center" || v === "end" || v === "stretch") {
+    return v;
+  }
+  return undefined;
+}
+
+function parseJustifyContent(
+  value?: string,
+): GridProps["justifyContent"] | undefined {
+  const v = value?.toLowerCase().replace(/\s+/g, "-") as
+    | GridProps["justifyContent"]
+    | undefined;
+  const valid = [
+    "start",
+    "center",
+    "end",
+    "space-between",
+    "space-around",
+    "space-evenly",
+  ];
+  return v && valid.includes(v) ? v : undefined;
+}
+
 export const SbGrid = memo(function SbGrid({ blok }: SbGridProps) {
   const {
     items,
@@ -51,10 +99,10 @@ export const SbGrid = memo(function SbGrid({ blok }: SbGridProps) {
     autoFlow,
     boundingWidth = "full",
     isList = false,
-    pt,
-    pb,
-    mt,
-    mb,
+    spacingTop,
+    spacingBottom,
+    paddingTop,
+    paddingBottom,
   } = blok;
 
   const editableProps = useStoryblokEditable(blok);
@@ -63,121 +111,56 @@ export const SbGrid = memo(function SbGrid({ blok }: SbGridProps) {
     return null;
   }
 
-  // Normalize Storyblok values to CSS values (lowercase, spaces to hyphens)
-  const normalizeValue = (value?: string) =>
-    value?.toLowerCase().replace(/\s+/g, "-");
-
-  // Use specific row/column gaps if provided, otherwise use uniform gap
-  const effectiveRowGap = rowGap || gap;
-  const effectiveColumnGap = columnGap || gap;
-
-  // Static mapping for grid columns - required for Panda CSS static analysis
-  const GRID_COLUMNS_MAP = {
-    1: "repeat(1, 1fr)" as const,
-    2: "repeat(2, 1fr)" as const,
-    3: "repeat(3, 1fr)" as const,
-    4: "repeat(4, 1fr)" as const,
-    5: "repeat(5, 1fr)" as const,
-    6: "repeat(6, 1fr)" as const,
-    7: "repeat(7, 1fr)" as const,
-    8: "repeat(8, 1fr)" as const,
-    9: "repeat(9, 1fr)" as const,
-    10: "repeat(10, 1fr)" as const,
-    11: "repeat(11, 1fr)" as const,
-    12: "repeat(12, 1fr)" as const,
-    auto: "repeat(auto-fit, minmax(200px, 1fr))" as const,
-  };
-
-  // Parse column values to numbers for mapping
-  const parseColumns = (
-    value?: string,
-  ): 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | "auto" => {
-    if (!value) {
-      return 1;
-    }
-    if (value.toLowerCase().includes("auto")) {
-      return "auto";
-    }
-    const match = value.match(/(\d+)/);
-    if (match) {
-      const num = Number.parseInt(match[1], 10);
-      if (num >= 1 && num <= 12) {
-        return num as 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
-      }
-    }
-    return 1;
-  };
-
-  const baseColumns = parseColumns(columns);
-  const mdColumns = columnsMd ? parseColumns(columnsMd) : undefined;
-  const lgColumns = columnsLg ? parseColumns(columnsLg) : undefined;
-
-  // Use CSS custom properties for responsive columns (cleaner than dangerouslySetInnerHTML)
-  const inlineStyles: React.CSSProperties = {
-    ...(mdColumns &&
-      ({ "--grid-columns-md": GRID_COLUMNS_MAP[mdColumns] } as any)),
-    ...(lgColumns &&
-      ({ "--grid-columns-lg": GRID_COLUMNS_MAP[lgColumns] } as any)),
-  };
+  const parsedColumns = parseColumns(columns) ?? 12;
+  const parsedColumnsMd = parseColumns(columnsMd);
+  const parsedColumnsLg = parseColumns(columnsLg);
 
-  const gridStyles: SystemStyleObject = {
-    display: "grid",
-    gridTemplateColumns: GRID_COLUMNS_MAP[baseColumns],
-    gap:
-      effectiveRowGap || effectiveColumnGap
-        ? undefined
-        : mapSpacingToToken(gap),
-    rowGap: effectiveRowGap ? mapSpacingToToken(effectiveRowGap) : undefined,
-    columnGap: effectiveColumnGap
-      ? mapSpacingToToken(effectiveColumnGap)
-      : undefined,
-    alignItems: alignItems ? (normalizeValue(alignItems) as any) : undefined,
-    justifyItems: justifyItems
-      ? (normalizeValue(justifyItems) as any)
-      : undefined,
-    justifyContent: justifyContent
-      ? (normalizeValue(justifyContent) as any)
-      : undefined,
-    gridAutoFlow: autoFlow ? (normalizeValue(autoFlow) as any) : undefined,
-    pt: pt ? mapSpacingToToken(pt) : undefined,
-    pb: pb ? mapSpacingToToken(pb) : undefined,
-    mt: mt ? mapSpacingToToken(mt) : undefined,
-    mb: mb ? mapSpacingToToken(mb) : undefined,
-    maxWidth: boundingWidth === "container" ? "breakpoint-xl" : undefined,
-    mx: boundingWidth === "container" ? "auto" : undefined,
-    // Use CSS custom properties in media queries
-    ...(mdColumns && {
-      md: { gridTemplateColumns: "var(--grid-columns-md)" as any },
-    }),
-    ...(lgColumns && {
-      lg: { gridTemplateColumns: "var(--grid-columns-lg)" as any },
-    }),
+  const gridProps: Partial<GridProps> = {
+    columns: parsedColumns,
+    columnsMd: parsedColumnsMd,
+    columnsLg: parsedColumnsLg,
+    gap: gap ? mapSpacingToToken(gap) : "4",
+    rowGap: rowGap ? mapSpacingToToken(rowGap) : undefined,
+    columnGap: columnGap ? mapSpacingToToken(columnGap) : undefined,
+    align: parseAlign(alignItems),
+    justify: parseAlign(justifyItems),
+    justifyContent: parseJustifyContent(justifyContent),
+    flow: parseFlow(autoFlow),
+    css: {
+      mt: spacingTop ? mapSpacingToToken(spacingTop) : undefined,
+      mb: spacingBottom ? mapSpacingToToken(spacingBottom) : undefined,
+      pt: paddingTop ? mapSpacingToToken(paddingTop) : undefined,
+      pb: paddingBottom ? mapSpacingToToken(paddingBottom) : undefined,
+      maxWidth: boundingWidth === "container" ? "breakpoint-xl" : undefined,
+      mx: boundingWidth === "container" ? "auto" : undefined,
+    },
   };
 
   if (isList) {
     return (
-      <ul
+      <Grid
+        as="ul"
+        {...gridProps}
         {...editableProps}
-        className={css({
-          ...gridStyles,
+        css={{
+          ...gridProps.css,
           listStyle: "none",
-        })}
-        style={inlineStyles}
+        }}
       >
         {items.map((item) => (
           <li key={item._uid}>
             <DynamicRender data={[item as BlokItem]} />
           </li>
         ))}
-      </ul>
+      </Grid>
     );
   }
 
   return (
-    <div {...editableProps} className={css(gridStyles)} style={inlineStyles}>
+    <Grid {...gridProps} {...editableProps}>
       {items.map((item) => (
         <DynamicRender key={item._uid} data={[item as BlokItem]} />
       ))}
-    </div>
+    </Grid>
   );
 });
diff --git a/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx b/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx
index 157119b0..8993335e 100644
--- a/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx
+++ b/packages/ui/src/components/aspect-ratio/aspect-ratio.tsx
@@ -15,7 +15,7 @@ export interface AspectRatioProps
    * Aspect ratio preset or custom value
    * @default "16/9"
    */
-  ratio?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16" | number;
+  ratio?: string | number;
   /**
    * Custom styles using Panda CSS SystemStyleObject
    */
diff --git a/packages/ui/src/components/grid/grid.tsx b/packages/ui/src/components/grid/grid.tsx
index 2d6d0797..1d76a23c 100644
--- a/packages/ui/src/components/grid/grid.tsx
+++ b/packages/ui/src/components/grid/grid.tsx
@@ -1,49 +1,53 @@
 "use client";
 
-import type { HTMLAttributes, ReactNode } from "react";
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
 import { forwardRef } from "react";
 import { css, cx } from "styled-system/css";
 import type { SystemStyleObject } from "styled-system/types";
 
-export interface GridProps extends HTMLAttributes<HTMLDivElement> {
-  /**
-   * Grid content
-   */
+export type GridColumns =
+  | 1
+  | 2
+  | 3
+  | 4
+  | 5
+  | 6
+  | 7
+  | 8
+  | 9
+  | 10
+  | 11
+  | 12
+  | "auto";
+
+// Module-level constant — values are string literals so Panda CSS can extract them
+export const GRID_COLUMNS_MAP: Record<GridColumns, string> = {
+  1: "repeat(1, 1fr)",
+  2: "repeat(2, 1fr)",
+  3: "repeat(3, 1fr)",
+  4: "repeat(4, 1fr)",
+  5: "repeat(5, 1fr)",
+  6: "repeat(6, 1fr)",
+  7: "repeat(7, 1fr)",
+  8: "repeat(8, 1fr)",
+  9: "repeat(9, 1fr)",
+  10: "repeat(10, 1fr)",
+  11: "repeat(11, 1fr)",
+  12: "repeat(12, 1fr)",
+  auto: "repeat(auto-fit, minmax(200px, 1fr))",
+};
+
+export interface GridProps extends Omit<HTMLAttributes<HTMLElement>, "css"> {
   children: ReactNode;
-  /**
-   * Number of columns (1-12)
-   * @default 12
-   */
-  columns?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | "auto";
-  /**
-   * Gap between items (Panda spacing token)
-   * @default "4"
-   */
+  as?: "div" | "ul";
+  columns?: GridColumns;
+  columnsMd?: GridColumns;
+  columnsLg?: GridColumns;
   gap?: string | number;
-  /**
-   * Row gap (Panda spacing token)
-   * If not set, uses gap value
-   */
   rowGap?: string | number;
-  /**
-   * Column gap (Panda spacing token)
-   * If not set, uses gap value
-   */
   columnGap?: string | number;
-  /**
-   * Alignment of items
-   * @default "stretch"
-   */
   align?: "start" | "center" | "end" | "stretch";
-  /**
-   * Justification of items in their grid areas (justifyItems)
-   * @default "stretch"
-   */
   justify?: "start" | "center" | "end" | "stretch";
-  /**
-   * Justification of grid tracks within the grid container (justify-content)
-   * Use for distributing space between/around columns
-   */
   justifyContent?:
     | "start"
     | "center"
@@ -51,53 +55,19 @@ export interface GridProps extends HTMLAttributes<HTMLDivElement> {
     | "space-between"
     | "space-around"
     | "space-evenly";
-  /**
-   * Auto-flow direction
-   * @default "row"
-   */
   flow?: "row" | "column" | "row-dense" | "column-dense";
-  /**
-   * Full width
-   * @default false
-   */
   fullWidth?: boolean;
-  /**
-   * Additional Panda CSS styles
-   */
   css?: SystemStyleObject;
 }
 
-/**
- * Grid component - CSS Grid layout system
- *
- * A powerful 12-column grid system with token-based gaps and full control.
- * Perfect for magazine-style brutalist layouts.
- * Use with GridItem for advanced positioning and spanning.
- *
- * @example
- * ```tsx
- * <Grid columns={12} gap={4}>
- *   <GridItem colSpan={6}>Half width</GridItem>
- *   <GridItem colSpan={6}>Half width</GridItem>
- * </Grid>
- *
- * // Auto-fit responsive grid
- * <Grid columns="auto" gap={6} rowGap={8}>
- *   {items.map(item => <Box key={item.id}>{item.content}</Box>)}
- * </Grid>
- *
- * // Dense packing
- * <Grid columns={4} flow="row-dense" gap={2}>
- *   <GridItem colSpan={2}>Wide</GridItem>
- *   <GridItem>Normal</GridItem>
- * </Grid>
- * ```
- */
-export const Grid = forwardRef<HTMLDivElement, GridProps>(
+export const Grid = forwardRef<HTMLElement, GridProps>(
   (
     {
+      as: Tag = "div",
       children,
       columns = 12,
+      columnsMd,
+      columnsLg,
       gap = "4",
       rowGap,
       columnGap,
@@ -107,48 +77,51 @@ export const Grid = forwardRef<HTMLDivElement, GridProps>(
       flow = "row",
       fullWidth = false,
       className,
+      style,
       css: cssProp,
       ...props
     },
     ref,
   ) => {
-    // Static mapping for grid columns - required for Panda CSS static analysis
-    const GRID_COLUMNS_MAP = {
-      1: "repeat(1, 1fr)" as const,
-      2: "repeat(2, 1fr)" as const,
-      3: "repeat(3, 1fr)" as const,
-      4: "repeat(4, 1fr)" as const,
-      5: "repeat(5, 1fr)" as const,
-      6: "repeat(6, 1fr)" as const,
-      7: "repeat(7, 1fr)" as const,
-      8: "repeat(8, 1fr)" as const,
-      9: "repeat(9, 1fr)" as const,
-      10: "repeat(10, 1fr)" as const,
-      11: "repeat(11, 1fr)" as const,
-      12: "repeat(12, 1fr)" as const,
-      auto: "repeat(auto-fit, minmax(200px, 1fr))" as const,
-    };
-
-    const gridTemplateColumns = GRID_COLUMNS_MAP[columns];
-
     const styles = css({
       display: "grid",
-      gridTemplateColumns,
+      gridTemplateColumns: GRID_COLUMNS_MAP[columns],
       gap: rowGap || columnGap ? undefined : gap,
-      rowGap: rowGap || gap,
-      columnGap: columnGap || gap,
+      rowGap: rowGap ?? gap,
+      columnGap: columnGap ?? gap,
       alignItems: align,
       justifyItems: justify,
-      justifyContent: justifyContent,
+      justifyContent,
       gridAutoFlow: flow,
       w: fullWidth ? "full" : undefined,
+      ...(columnsMd && {
+        md: { gridTemplateColumns: "var(--grid-cols-md)" as any },
+      }),
+      ...(columnsLg && {
+        lg: { gridTemplateColumns: "var(--grid-cols-lg)" as any },
+      }),
       ...cssProp,
     });
 
+    const inlineStyle: CSSProperties = {
+      ...style,
+      ...(columnsMd && ({
+        "--grid-cols-md": GRID_COLUMNS_MAP[columnsMd],
+      } as CSSProperties)),
+      ...(columnsLg && ({
+        "--grid-cols-lg": GRID_COLUMNS_MAP[columnsLg],
+      } as CSSProperties)),
+    };
+
     return (
-      <div ref={ref} className={cx(styles, className)} {...props}>
+      <Tag
+        ref={ref as any}
+        className={cx(styles, className)}
+        style={inlineStyle}
+        {...props}
+      >
         {children}
-      </div>
+      </Tag>
     );
   },
 );
diff --git a/packages/ui/src/components/grid/index.ts b/packages/ui/src/components/grid/index.ts
index 84f7891c..80002346 100644
--- a/packages/ui/src/components/grid/index.ts
+++ b/packages/ui/src/components/grid/index.ts
@@ -1,4 +1,4 @@
-export type { GridProps } from "./grid";
-export { Grid } from "./grid";
+export type { GridColumns, GridProps } from "./grid";
+export { Grid, GRID_COLUMNS_MAP } from "./grid";
 export type { GridItemProps } from "./grid-item";
 export { GridItem } from "./grid-item";
diff --git a/packages/ui/src/components/image/image.tsx b/packages/ui/src/components/image/image.tsx
index d140b36f..af28fe75 100644
--- a/packages/ui/src/components/image/image.tsx
+++ b/packages/ui/src/components/image/image.tsx
@@ -17,7 +17,7 @@ export interface ImageProps
   blurOnLoad?: boolean;
   blurDataURL?: string;
   objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down";
-  aspectRatio?: "1/1" | "4/3" | "3/4" | "16/9" | "9/16" | "21/9";
+  aspectRatio?: string;
   css?: SystemStyleObject;
 }
 
diff --git a/packages/ui/src/components/slideshow/slideshow.tsx b/packages/ui/src/components/slideshow/slideshow.tsx
index 9d50bd38..ad3e0ddd 100644
--- a/packages/ui/src/components/slideshow/slideshow.tsx
+++ b/packages/ui/src/components/slideshow/slideshow.tsx
@@ -72,7 +72,7 @@ const SWIPER_CREATIVE_EFFECT = {
 interface SlideshowVideoSlideProps {
   videoUrl: string;
   videoPoster?: string;
-  aspectRatio: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16";
+  aspectRatio: string;
 }
 
 function SlideshowVideoSlide({
@@ -162,7 +162,7 @@ export interface SlideshowProps {
    * Aspect ratio for images
    * @default "16/9"
    */
-  aspectRatio?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16";
+  aspectRatio?: string;
   /**
    * Autoplay delay in milliseconds
    * @default 7000
diff --git a/packages/ui/src/components/video/video.tsx b/packages/ui/src/components/video/video.tsx
index 7ecce00f..11d94a17 100644
--- a/packages/ui/src/components/video/video.tsx
+++ b/packages/ui/src/components/video/video.tsx
@@ -19,7 +19,7 @@ export interface VideoProps
   autoPlay?: boolean;
   loop?: boolean;
   muted?: boolean;
-  aspectRatio?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | "9/16" | number;
+  aspectRatio?: string | number;
   copyright?: string;
   copyrightPosition?: CopyrightPosition;
   css?: SystemStyleObject;