website refactor

apps/website/ui/Layout.tsx

@@ -1,4 +1,16 @@
 import React, { ReactNode } from 'react';
+import { Box } from './primitives/Box';
+import { Grid } from './primitives/Grid';
+import { Stack } from './primitives/Stack';
+
+/**
+ * WARNING: DO NOT VIOLATE THE PURPOSE OF THIS COMPONENT.
+ * 
+ * Layout is a high-level component for page or section layouts.
+ * It should use Grid or Stack primitives internally.
+ * 
+ * If you need a specific layout pattern, create a new component.
+ */
 
 interface LayoutProps {
   children: ReactNode;
@@ -25,39 +37,33 @@ export function Layout({
   items = 'start',
   justify = 'start'
 }: LayoutProps) {
-  const baseClasses = [padding, gap, className];
-  
   if (grid) {
-    const gridColsMap = {
+    return (
-      1: 'grid-cols-1',
+      <Grid 
-      2: 'grid-cols-2',
+        cols={gridCols as any} 
-      3: 'grid-cols-3',
+        className={`${padding} ${gap} ${className}`}
-      4: 'grid-cols-4'
+      >
-    };
+        {children}
-    baseClasses.push('grid', gridColsMap[gridCols]);
+      </Grid>
-  } else if (flex) {
+    );
-    baseClasses.push('flex');
-    if (flexCol) baseClasses.push('flex-col');
-    
-    const itemsMap = {
-      start: 'items-start',
-      center: 'items-center',
-      end: 'items-end',
-      stretch: 'items-stretch'
-    };
-    baseClasses.push(itemsMap[items]);
-    
-    const justifyMap = {
-      start: 'justify-start',
-      center: 'justify-center',
-      end: 'justify-end',
-      between: 'justify-between',
-      around: 'justify-around'
-    };
-    baseClasses.push(justifyMap[justify]);
   }
   
-  const classes = baseClasses.filter(Boolean).join(' ');
+  if (flex) {
+    return (
+      <Stack 
+        direction={flexCol ? 'col' : 'row'} 
+        align={items} 
+        justify={justify} 
+        className={`${padding} ${gap} ${className}`}
+      >
+        {children}
+      </Stack>
+    );
+  }
   
-  return <div className={classes}>{children}</div>;
+  return (
-}
+    <Box className={`${padding} ${gap} ${className}`}>
+      {children}
+    </Box>
+  );
+}

apps/website/ui/primitives/Box.tsx

@@ -1,5 +1,17 @@
 import React, { forwardRef, ForwardedRef, ElementType, ComponentPropsWithoutRef } from 'react';
 
+/**
+ * WARNING: DO NOT VIOLATE THE PURPOSE OF THIS PRIMITIVE.
+ * 
+ * Box is a basic container primitive for spacing, sizing and basic styling.
+ * 
+ * - DO NOT add layout props (flex, grid, gap) - use Stack or Grid instead.
+ * - DO NOT add positioning props (absolute, top, zIndex) - create a specific component.
+ * - DO NOT add animation props - create a specific component.
+ * 
+ * If you need more complex behavior, create a specific component in apps/website/components.
+ */
+
 type Spacing = 0 | 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 14 | 16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 52 | 56 | 60 | 64 | 72 | 80 | 96;
 
 interface ResponsiveSpacing {
@@ -8,13 +20,20 @@ interface ResponsiveSpacing {
   lg?: Spacing;
 }
 
+export type ResponsiveValue<T> = {
+  base?: T;
+  sm?: T;
+  md?: T;
+  lg?: T;
+  xl?: T;
+  '2xl'?: T;
+};
+
 export interface BoxProps<T extends ElementType> {
   as?: T;
   children?: React.ReactNode;
   className?: string;
-  center?: boolean;
+  // Spacing
-  fullWidth?: boolean;
-  fullHeight?: boolean;
   m?: Spacing | ResponsiveSpacing;
   mt?: Spacing | ResponsiveSpacing;
   mb?: Spacing | ResponsiveSpacing;
@@ -29,220 +48,70 @@ export interface BoxProps<T extends ElementType> {
   pr?: Spacing | ResponsiveSpacing;
   px?: Spacing | ResponsiveSpacing;
   py?: Spacing | ResponsiveSpacing;
-  display?: 'block' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none' | ResponsiveValue<'block' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none'>;
+  // Sizing
-  flexDirection?: 'row' | 'row-reverse' | 'col' | 'col-reverse' | ResponsiveValue<'row' | 'row-reverse' | 'col' | 'col-reverse'>;
-  alignItems?: 'start' | 'center' | 'end' | 'stretch' | 'baseline' | ResponsiveValue<'start' | 'center' | 'end' | 'stretch' | 'baseline'>;
-  justifyContent?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | ResponsiveValue<'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'>;
-  flexWrap?: 'wrap' | 'nowrap' | 'wrap-reverse';
-  flexShrink?: number;
-  flexGrow?: number;
-  flex?: number | string;
-  alignSelf?: 'auto' | 'start' | 'end' | 'center' | 'stretch' | 'baseline';
-  gridCols?: number | string;
-  responsiveGridCols?: {
-    base?: number | string;
-    md?: number | string;
-    lg?: number | string;
-  };
-  gap?: Spacing | ResponsiveSpacing;
-  colSpan?: number | string;
-  responsiveColSpan?: {
-    base?: number | string;
-    md?: number | string;
-    lg?: number | string;
-  };
-  position?: 'relative' | 'absolute' | 'fixed' | 'sticky';
-  top?: Spacing | string;
-  bottom?: Spacing | string;
-  left?: Spacing | string;
-  right?: Spacing | string;
-  overflow?: 'visible' | 'hidden' | 'scroll' | 'auto';
-  maxWidth?: string | ResponsiveValue<string>;
-  minWidth?: string | ResponsiveValue<string>;
-  maxHeight?: string | ResponsiveValue<string>;
-  minHeight?: string | ResponsiveValue<string>;
-  zIndex?: number;
   w?: string | ResponsiveValue<string>;
   h?: string | ResponsiveValue<string>;
   width?: string;
   height?: string;
+  maxWidth?: string | ResponsiveValue<string>;
+  minWidth?: string | ResponsiveValue<string>;
+  maxHeight?: string | ResponsiveValue<string>;
+  minHeight?: string | ResponsiveValue<string>;
+  // Display
+  display?: 'block' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none' | ResponsiveValue<'block' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none'>;
+  // Basic Styling
   rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
   border?: boolean;
-  borderTop?: boolean;
-  borderBottom?: boolean;
-  borderLeft?: boolean;
-  borderRight?: boolean;
   borderColor?: string;
   bg?: string;
   color?: string;
   shadow?: string;
-  hoverBorderColor?: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  transition?: any;
-  cursor?: 'pointer' | 'default' | 'wait' | 'text' | 'move' | 'not-allowed';
-  lineClamp?: 1 | 2 | 3 | 4 | 5 | 6;
-  inset?: string;
-  bgOpacity?: number;
   opacity?: number;
-  blur?: 'none' | 'sm' | 'md' | 'lg' | 'xl';
+  // Flex/Grid Item props
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  flex?: number | string;
-  animate?: any;
+  flexShrink?: number;
-  translateX?: string;
+  flexGrow?: number;
-  textAlign?: 'left' | 'center' | 'right' | 'justify';
+  alignSelf?: 'auto' | 'start' | 'end' | 'center' | 'stretch' | 'baseline';
-  hoverScale?: boolean;
-  group?: boolean;
-  groupHoverBorderColor?: string;
-  groupHoverTextColor?: string;
-  groupHoverScale?: boolean;
-  groupHoverOpacity?: number;
-  groupHoverWidth?: 'full' | '0' | 'auto';
-  fontSize?: string;
-  fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
-  transform?: string;
-  borderWidth?: string;
-  hoverTextColor?: string;
-  hoverBg?: string;
-  borderStyle?: 'solid' | 'dashed' | 'dotted' | 'none';
-  ring?: string;
-  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
-  aspectRatio?: string;
-  visibility?: 'visible' | 'hidden' | 'collapse';
-  pointerEvents?: 'auto' | 'none';
   order?: number | string | ResponsiveValue<number | string>;
-  hideScrollbar?: boolean;
+  // Events
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  whileHover?: any;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  whileTap?: any;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  initial?: any;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  exit?: any;
   onMouseEnter?: React.MouseEventHandler<T>;
   onMouseLeave?: React.MouseEventHandler<T>;
   onClick?: React.MouseEventHandler<T>;
-  onSubmit?: React.FormEventHandler<T>;
   style?: React.CSSProperties;
-  hoverColor?: string;
+  id?: string;
-  maskImage?: string;
+  role?: string;
-  webkitMaskImage?: string;
+  tabIndex?: number;
-  backgroundSize?: string;
-  backgroundPosition?: string;
-  backgroundColor?: string;
-  insetY?: Spacing | string;
-  letterSpacing?: string;
-  lineHeight?: string;
-  backgroundImage?: string;
 }
 
-export type ResponsiveValue<T> = {
-  base?: T;
-  sm?: T;
-  md?: T;
-  lg?: T;
-  xl?: T;
-  '2xl'?: T;
-};
-
 export const Box = forwardRef(<T extends ElementType = 'div'>(
   { 
     as, 
     children, 
     className = '', 
-    center = false,
-    fullWidth = false,
-    fullHeight = false,
     m, mt, mb, ml, mr, mx, my,
     p, pt, pb, pl, pr, px, py,
+    w, h, width, height,
+    maxWidth, minWidth, maxHeight, minHeight,
     display,
-    flexDirection,
-    alignItems,
-    justifyContent,
-    flexWrap,
-    position,
-    top,
-    bottom,
-    left,
-    right,
-    overflow,
-    maxWidth,
-    minWidth,
-    maxHeight,
-    minHeight,
-    zIndex,
-    gridCols,
-    responsiveGridCols,
-    colSpan,
-    responsiveColSpan,
-    gap,
-    w,
-    h,
-    width,
-    height,
     rounded,
     border,
-    borderTop,
-    borderBottom,
-    borderLeft,
-    borderRight,
     borderColor,
     bg,
     color,
     shadow,
+    opacity,
     flex,
     flexShrink,
     flexGrow,
     alignSelf,
-    hoverBorderColor,
-    transition,
-    cursor,
-    lineClamp,
-    inset,
-    bgOpacity,
-    opacity,
-    blur,
-    animate,
-    translateX,
-    textAlign,
-    hoverScale,
-    group,
-    groupHoverBorderColor,
-    groupHoverTextColor,
-    groupHoverScale,
-    groupHoverOpacity,
-    groupHoverWidth,
-    fontSize,
-    fontWeight,
-    transform,
-    borderWidth,
-    hoverTextColor,
-    hoverBg,
-    borderStyle,
-    ring,
-    objectFit,
-    aspectRatio,
-    visibility,
-    pointerEvents,
     order,
-    hideScrollbar,
-    whileHover,
-    whileTap,
-    initial,
-    exit,
     onMouseEnter,
     onMouseLeave,
     onClick,
-    onSubmit,
+    style: styleProp,
-    hoverColor,
+    id,
-    maskImage,
+    role,
-    webkitMaskImage,
+    tabIndex,
-    backgroundSize,
-    backgroundPosition,
-    backgroundColor,
-    insetY,
-    letterSpacing,
-    lineHeight,
-    backgroundImage,
     ...props 
   }: BoxProps<T> & ComponentPropsWithoutRef<T>,
   ref: ForwardedRef<HTMLElement>
@@ -284,57 +153,7 @@ export const Box = forwardRef(<T extends ElementType = 'div'>(
     return prefix ? `${prefix}-${value}` : String(value);
   };
 
-  const getFlexDirectionClass = (value: BoxProps<ElementType>['flexDirection']) => {
-    if (!value) return '';
-    if (typeof value === 'object') {
-      const classes = [];
-      if (value.base) classes.push(`flex-${value.base}`);
-      if (value.sm) classes.push(`sm:flex-${value.sm}`);
-      if (value.md) classes.push(`md:flex-${value.md}`);
-      if (value.lg) classes.push(`lg:flex-${value.lg}`);
-      if (value.xl) classes.push(`xl:flex-${value.xl}`);
-      if (value['2xl']) classes.push(`2xl:flex-${value['2xl']}`);
-      return classes.join(' ');
-    }
-    return `flex-${value}`;
-  };
-
-  const getAlignItemsClass = (value: BoxProps<ElementType>['alignItems']) => {
-    if (!value) return '';
-    const map: Record<string, string> = { start: 'items-start', center: 'items-center', end: 'items-end', stretch: 'items-stretch', baseline: 'items-baseline' };
-    if (typeof value === 'object') {
-      const classes = [];
-      if (value.base) classes.push(map[value.base]);
-      if (value.sm) classes.push(`sm:${map[value.sm]}`);
-      if (value.md) classes.push(`md:${map[value.md]}`);
-      if (value.lg) classes.push(`lg:${map[value.lg]}`);
-      if (value.xl) classes.push(`xl:${map[value.xl]}`);
-      if (value['2xl']) classes.push(`2xl:${map[value['2xl']]}`);
-      return classes.join(' ');
-    }
-    return map[value];
-  };
-
-  const getJustifyContentClass = (value: BoxProps<ElementType>['justifyContent']) => {
-    if (!value) return '';
-    const map: Record<string, string> = { start: 'justify-start', center: 'justify-center', end: 'justify-end', between: 'justify-between', around: 'justify-around', evenly: 'justify-evenly' };
-    if (typeof value === 'object') {
-      const classes = [];
-      if (value.base) classes.push(map[value.base]);
-      if (value.sm) classes.push(`sm:${map[value.sm]}`);
-      if (value.md) classes.push(`md:${map[value.md]}`);
-      if (value.lg) classes.push(`lg:${map[value.lg]}`);
-      if (value.xl) classes.push(`xl:${map[value.xl]}`);
-      if (value['2xl']) classes.push(`2xl:${map[value['2xl']]}`);
-      return classes.join(' ');
-    }
-    return map[value];
-  };
-
   const classes = [
-    center ? 'flex items-center justify-center' : '',
-    fullWidth ? 'w-full' : '',
-    fullHeight ? 'h-full' : '',
     getSpacingClass('m', m),
     getSpacingClass('mt', mt),
     getSpacingClass('mb', mb),
@@ -355,71 +174,19 @@ export const Box = forwardRef(<T extends ElementType = 'div'>(
     getResponsiveClasses('min-w', minWidth),
     getResponsiveClasses('max-h', maxHeight),
     getResponsiveClasses('min-h', minHeight),
+    getResponsiveClasses('', display),
     rounded ? `rounded-${rounded}` : '',
     border ? 'border' : '',
-    borderStyle ? `border-${borderStyle}` : '',
-    borderTop ? 'border-t' : '',
-    borderBottom ? 'border-b' : '',
-    borderLeft ? 'border-l' : '',
-    borderRight ? 'border-r' : '',
     borderColor ? borderColor : '',
-    ring ? ring : '',
+    bg ? bg : '',
-    bg ? bg : (backgroundColor ? (backgroundColor.startsWith('bg-') ? backgroundColor : `bg-${backgroundColor}`) : ''),
     color ? color : '',
-    hoverColor ? `hover:${hoverColor}` : '',
     shadow ? shadow : '',
     flex !== undefined ? `flex-${flex}` : '',
     flexShrink !== undefined ? `flex-shrink-${flexShrink}` : '',
     flexGrow !== undefined ? `flex-grow-${flexGrow}` : '',
     alignSelf !== undefined ? `self-${alignSelf}` : '',
-    flexWrap ? `flex-${flexWrap}` : '',
-    hoverBorderColor ? `hover:${hoverBorderColor}` : '',
-    hoverTextColor ? `hover:${hoverTextColor}` : '',
-    hoverBg ? `hover:${hoverBg}` : '',
-    transition ? 'transition-all' : '',
-    lineClamp ? `line-clamp-${lineClamp}` : '',
-    inset ? `inset-${inset}` : '',
-    insetY !== undefined && spacingMap[insetY as string | number] ? `inset-y-${spacingMap[insetY as string | number]}` : '',
-    bgOpacity !== undefined ? `bg-opacity-${bgOpacity * 100}` : '',
     opacity !== undefined ? `opacity-${opacity * 100}` : '',
-    blur ? `blur-${blur}` : '',
-    animate ? `animate-${animate}` : '',
-    translateX ? `translate-x-${translateX}` : '',
-    textAlign ? `text-${textAlign}` : '',
-    hoverScale ? 'hover:scale-[1.02]' : '',
-    group ? 'group' : '',
-    groupHoverBorderColor ? `group-hover:border-${groupHoverBorderColor}` : '',
-    groupHoverTextColor ? `group-hover:text-${groupHoverTextColor}` : '',
-    groupHoverScale ? 'group-hover:scale-[1.02]' : '',
-    groupHoverOpacity !== undefined ? `group-hover:opacity-${groupHoverOpacity * 100}` : '',
-    groupHoverWidth ? `group-hover:w-${groupHoverWidth}` : '',
-    fontSize ? `text-${fontSize}` : '',
-    fontWeight ? `font-${fontWeight}` : '',
-    getResponsiveClasses('', display),
-    getFlexDirectionClass(flexDirection),
-    getAlignItemsClass(alignItems),
-    getJustifyContentClass(justifyContent),
-    gridCols ? `grid-cols-${gridCols}` : '',
-    responsiveGridCols?.base ? `grid-cols-${responsiveGridCols.base}` : '',
-    responsiveGridCols?.md ? `md:grid-cols-${responsiveGridCols.md}` : '',
-    responsiveGridCols?.lg ? `lg:grid-cols-${responsiveGridCols.lg}` : '',
-    colSpan ? `col-span-${colSpan}` : '',
-    responsiveColSpan?.base ? `col-span-${responsiveColSpan.base}` : '',
-    responsiveColSpan?.md ? `md:col-span-${responsiveColSpan.md}` : '',
-    responsiveColSpan?.lg ? `lg:col-span-${responsiveColSpan.lg}` : '',
-    getSpacingClass('gap', gap),
     getResponsiveClasses('order', order),
-    position ? position : '',
-    top !== undefined && spacingMap[top as string | number] ? `top-${spacingMap[top as string | number]}` : '',
-    bottom !== undefined && spacingMap[bottom as string | number] ? `bottom-${spacingMap[bottom as string | number]}` : '',
-    left !== undefined && spacingMap[left as string | number] ? `left-${spacingMap[left as string | number]}` : '',
-    right !== undefined && spacingMap[right as string | number] ? `right-${spacingMap[right as string | number]}` : '',
-    overflow ? `overflow-${overflow}` : '',
-    visibility ? visibility : '',
-    zIndex !== undefined ? `z-${zIndex}` : '',
-    cursor ? `cursor-${cursor}` : '',
-    pointerEvents ? `pointer-events-${pointerEvents}` : '',
-    hideScrollbar ? 'scrollbar-hide' : '',
     className
   ].filter(Boolean).join(' ');
 
@@ -430,25 +197,7 @@ export const Box = forwardRef(<T extends ElementType = 'div'>(
     ...(typeof minWidth === 'string' ? { minWidth } : {}),
     ...(typeof maxHeight === 'string' ? { maxHeight } : {}),
     ...(typeof minHeight === 'string' ? { minHeight } : {}),
-    ...(fontSize ? { fontSize } : {}),
+    ...(styleProp || {})
-    ...(transform ? { transform } : {}),
-    ...(borderWidth ? { borderWidth } : {}),
-    ...(objectFit ? { objectFit } : {}),
-    ...(aspectRatio ? { aspectRatio } : {}),
-    ...(maskImage ? { maskImage } : {}),
-    ...(webkitMaskImage ? { WebkitMaskImage: webkitMaskImage } : {}),
-    ...(backgroundSize ? { backgroundSize } : {}),
-    ...(backgroundPosition ? { backgroundPosition } : {}),
-    ...(backgroundImage ? { backgroundImage } : {}),
-    ...(letterSpacing ? { letterSpacing } : {}),
-    ...(lineHeight ? { lineHeight } : {}),
-    ...(top !== undefined && !spacingMap[top as string | number] ? { top } : {}),
-    ...(bottom !== undefined && !spacingMap[bottom as string | number] ? { bottom } : {}),
-    ...(left !== undefined && !spacingMap[left as string | number] ? { left } : {}),
-    ...(right !== undefined && !spacingMap[right as string | number] ? { right } : {}),
-    ...(insetY !== undefined && !spacingMap[insetY as string | number] ? { top: insetY, bottom: insetY } : {}),
-    ...(hideScrollbar ? { scrollbarWidth: 'none', msOverflowStyle: 'none', '&::-webkit-scrollbar': { display: 'none' } } : {}),
-    ...((props as Record<string, unknown>).style as object || {})
   };
 
   return (
@@ -456,16 +205,13 @@ export const Box = forwardRef(<T extends ElementType = 'div'>(
       ref={ref as React.ForwardedRef<HTMLElement>} 
       className={classes} 
       onClick={onClick}
-      onSubmit={onSubmit}
       onMouseEnter={onMouseEnter}
       onMouseLeave={onMouseLeave}
-      whileHover={whileHover}
+      style={style}
-      whileTap={whileTap}
+      id={id}
-      initial={initial}
+      role={role}
-      animate={animate}
+      tabIndex={tabIndex}
-      exit={exit}
       {...props} 
-      style={style as React.CSSProperties}
     >
       {children}
     </Tag>

apps/website/ui/primitives/Grid.tsx

@@ -1,12 +1,41 @@
 import React, { ReactNode } from 'react';
-import { Box, BoxProps } from './Box';
+import { Box, BoxProps, ResponsiveValue } from './Box';
 
-export interface GridProps extends Omit<BoxProps<'div'>, 'children' | 'display'> {
+/**
+ * WARNING: DO NOT VIOLATE THE PURPOSE OF THIS PRIMITIVE.
+ * 
+ * Grid is for CSS Grid-based layouts.
+ * 
+ * - DO NOT add positioning props (absolute, top, zIndex).
+ * - DO NOT add flex props.
+ * - DO NOT add background/border props unless it's a specific styled grid.
+ * 
+ * If you need a more specific layout, create a new component in apps/website/components.
+ */
+
+export interface GridProps {
   children: ReactNode;
   cols?: 1 | 2 | 3 | 4 | 5 | 6 | 12;
   mdCols?: 1 | 2 | 3 | 4 | 5 | 6 | 12;
   lgCols?: 1 | 2 | 3 | 4 | 5 | 6 | 12;
   gap?: 0 | 1 | 2 | 3 | 4 | 6 | 8 | 12 | 16;
+  className?: string;
+  // Spacing
+  m?: number;
+  mt?: number;
+  mb?: number;
+  ml?: number;
+  mr?: number;
+  p?: number;
+  pt?: number;
+  pb?: number;
+  pl?: number;
+  pr?: number;
+  px?: number;
+  py?: number;
+  // Sizing
+  w?: string | ResponsiveValue<string>;
+  h?: string | ResponsiveValue<string>;
 }
 
 export function Grid({ 

apps/website/ui/primitives/GridItem.tsx

@@ -1,6 +1,17 @@
 import React from 'react';
 import { Box } from './Box';
 
+/**
+ * WARNING: DO NOT VIOLATE THE PURPOSE OF THIS PRIMITIVE.
+ * 
+ * GridItem is for items inside a Grid container.
+ * 
+ * - DO NOT add positioning props (absolute, top, zIndex).
+ * - DO NOT add background/border props.
+ * 
+ * If you need a more specific layout, create a new component in apps/website/components.
+ */
+
 export interface GridItemProps {
   children: React.ReactNode;
   colSpan?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;

apps/website/ui/primitives/Stack.tsx

@@ -1,6 +1,18 @@
 import React, { ReactNode, ElementType } from 'react';
 import { Box, BoxProps, ResponsiveValue } from './Box';
 
+/**
+ * WARNING: DO NOT VIOLATE THE PURPOSE OF THIS PRIMITIVE.
+ * 
+ * Stack is for flexbox-based layouts (stacking elements).
+ * 
+ * - DO NOT add positioning props (absolute, top, zIndex).
+ * - DO NOT add grid props.
+ * - DO NOT add background/border props unless it's a specific styled stack.
+ * 
+ * If you need a more specific layout, create a new component in apps/website/components.
+ */
+
 type Spacing = 0 | 0.5 | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 14 | 16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 52 | 56 | 60 | 64 | 72 | 80 | 96;
 
 interface ResponsiveGap {
@@ -20,7 +32,8 @@ interface ResponsiveSpacing {
   '2xl'?: Spacing;
 }
 
-export interface StackProps<T extends ElementType> extends Omit<BoxProps<T>, 'children' | 'className' | 'gap'> {
+export interface StackProps<T extends ElementType> {
+  as?: T;
   children: ReactNode;
   className?: string;
   direction?: 'row' | 'col' | { base?: 'row' | 'col'; md?: 'row' | 'col'; lg?: 'row' | 'col' };
@@ -28,7 +41,7 @@ export interface StackProps<T extends ElementType> extends Omit<BoxProps<T>, 'ch
   align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline' | ResponsiveValue<'start' | 'center' | 'end' | 'stretch' | 'baseline'>;
   justify?: 'start' | 'center' | 'end' | 'between' | 'around' | ResponsiveValue<'start' | 'center' | 'end' | 'between' | 'around'>;
   wrap?: boolean;
-  center?: boolean;
+  // Spacing (allowed for layout)
   m?: Spacing | ResponsiveSpacing;
   mt?: Spacing | ResponsiveSpacing;
   mb?: Spacing | ResponsiveSpacing;
@@ -41,11 +54,21 @@ export interface StackProps<T extends ElementType> extends Omit<BoxProps<T>, 'ch
   pr?: Spacing | ResponsiveSpacing;
   px?: Spacing | ResponsiveSpacing;
   py?: Spacing | ResponsiveSpacing;
+  // Sizing (allowed for layout)
+  w?: string | ResponsiveValue<string>;
+  h?: string | ResponsiveValue<string>;
+  minWidth?: string | ResponsiveValue<string>;
+  maxWidth?: string | ResponsiveValue<string>;
+  minHeight?: string | ResponsiveValue<string>;
+  maxHeight?: string | ResponsiveValue<string>;
+  // Basic styling (sometimes needed for containers)
   rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+  // Flex item props
+  flex?: number | string;
+  flexGrow?: number;
+  flexShrink?: number;
+  alignSelf?: 'auto' | 'start' | 'end' | 'center' | 'stretch' | 'baseline';
   style?: React.CSSProperties;
-  role?: string;
-  'aria-label'?: string;
-  'aria-live'?: 'polite' | 'assertive' | 'off';
 }
 
 export function Stack<T extends ElementType = 'div'>({ 
@@ -56,10 +79,14 @@ export function Stack<T extends ElementType = 'div'>({
   align,
   justify,
   wrap = false,
-  center = false,
   m, mt, mb, ml, mr,
   p, pt, pb, pl, pr, px, py,
+  w, h, minWidth, maxWidth, minHeight, maxHeight,
   rounded,
+  flex,
+  flexGrow,
+  flexShrink,
+  alignSelf,
   as,
   ...props
 }: StackProps<T>) {
@@ -150,16 +177,58 @@ export function Stack<T extends ElementType = 'div'>({
     className
   ].filter(Boolean).join(' ');
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const getAlignItemsClass = (value: StackProps<ElementType>['align']) => {
-  const { alignItems, justifyContent, ...restProps } = props as any;
+    if (!value) return '';
+    const map: Record<string, string> = { start: 'items-start', center: 'items-center', end: 'items-end', stretch: 'items-stretch', baseline: 'items-baseline' };
+    if (typeof value === 'object') {
+      const classes = [];
+      if (value.base) classes.push(map[value.base]);
+      if (value.sm) classes.push(`sm:${map[value.sm]}`);
+      if (value.md) classes.push(`md:${map[value.md]}`);
+      if (value.lg) classes.push(`lg:${map[value.lg]}`);
+      if (value.xl) classes.push(`xl:${map[value.xl]}`);
+      if (value['2xl']) classes.push(`2xl:${map[value['2xl']]}`);
+      return classes.join(' ');
+    }
+    return map[value];
+  };
+
+  const getJustifyContentClass = (value: StackProps<ElementType>['justify']) => {
+    if (!value) return '';
+    const map: Record<string, string> = { start: 'justify-start', center: 'justify-center', end: 'justify-end', between: 'justify-between', around: 'justify-around' };
+    if (typeof value === 'object') {
+      const classes = [];
+      if (value.base) classes.push(map[value.base]);
+      if (value.sm) classes.push(`sm:${map[value.sm]}`);
+      if (value.md) classes.push(`md:${map[value.md]}`);
+      if (value.lg) classes.push(`lg:${map[value.lg]}`);
+      if (value.xl) classes.push(`xl:${map[value.xl]}`);
+      if (value['2xl']) classes.push(`2xl:${map[value['2xl']]}`);
+      return classes.join(' ');
+    }
+    return map[value];
+  };
+
+  const layoutClasses = [
+    getAlignItemsClass(align),
+    getJustifyContentClass(justify)
+  ].filter(Boolean).join(' ');
 
   return (
     <Box 
       as={as} 
-      className={classes} 
+      className={`${classes} ${layoutClasses}`}
-      alignItems={center ? 'center' : (align || alignItems)} 
+      w={w}
-      justifyContent={center ? 'center' : (justify || justifyContent)} 
+      h={h}
-      {...restProps}
+      minWidth={minWidth}
+      maxWidth={maxWidth}
+      minHeight={minHeight}
+      maxHeight={maxHeight}
+      flex={flex}
+      flexGrow={flexGrow}
+      flexShrink={flexShrink}
+      alignSelf={alignSelf}
+      {...props}
     >
       {children}
     </Box>

apps/website/ui/primitives/Surface.tsx

@@ -1,7 +1,18 @@
 import React, { ReactNode, ElementType, ComponentPropsWithoutRef } from 'react';
-import { Box, BoxProps } from './Box';
+import { Box, BoxProps, ResponsiveValue } from './Box';
 
-export interface SurfaceProps<T extends ElementType = 'div'> extends Omit<BoxProps<T>, 'children' | 'className' | 'display'> {
+/**
+ * WARNING: DO NOT VIOLATE THE PURPOSE OF THIS PRIMITIVE.
+ * 
+ * Surface is a styled container with background, border, and shadow.
+ * 
+ * - DO NOT add layout props (flex, grid, gap) - use Stack or Grid instead.
+ * - DO NOT add positioning props (absolute, top, zIndex).
+ * 
+ * If you need a more specific layout, create a new component in apps/website/components.
+ */
+
+export interface SurfaceProps<T extends ElementType = 'div'> {
   as?: T;
   children: ReactNode;
   variant?: 'default' | 'muted' | 'dark' | 'glass' | 'gradient-blue' | 'gradient-gold' | 'gradient-purple' | 'gradient-green' | 'discord' | 'discord-inner';
@@ -9,8 +20,11 @@ export interface SurfaceProps<T extends ElementType = 'div'> extends Omit<BoxPro
   border?: boolean;
   padding?: number;
   className?: string;
-  display?: 'block' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none';
   shadow?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'discord' | string;
+  // Sizing
+  w?: string | ResponsiveValue<string>;
+  h?: string | ResponsiveValue<string>;
+  maxWidth?: string | ResponsiveValue<string>;
 }
 
 export function Surface<T extends ElementType = 'div'>({ 
@@ -21,8 +35,8 @@ export function Surface<T extends ElementType = 'div'>({
   border = false,
   padding = 0,
   className = '',
-  display,
   shadow = 'none',
+  w, h, maxWidth,
   ...props 
 }: SurfaceProps<T> & ComponentPropsWithoutRef<T>) {
   const variantClasses: Record<string, string> = {
@@ -75,12 +89,11 @@ export function Surface<T extends ElementType = 'div'>({
     border ? 'border border-border-gray' : '',
     paddingClasses[padding] || 'p-0',
     shadowClasses[shadow],
-    display ? display : '',
     className
   ].filter(Boolean).join(' ');
 
   return (
-    <Box as={as} className={classes} {...props}>
+    <Box as={as} className={classes} w={w} h={h} maxWidth={maxWidth} {...props}>
       {children}
     </Box>
   );