@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Box/Box.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Box",
-  "description": "Primitive layout component for applying spacing, backgrounds, and borders. A flexible container for building custom layouts.",
+  "description": "Applies spacing, background, border, and radius to any element.",
   "category": "layout",
-  "tags": [
-    "layout",
-    "container",
-    "spacing",
-    "primitive",
-    "box"
-  ],
+  "tags": ["layout", "container", "spacing", "primitive", "box"],
   "status": "stable",
   "sourcePath": "src/components/Box/index.tsx",
   "exportName": "Box",
@@ -54,122 +48,55 @@
       "description": "HTML element to render",
       "default": "div",
       "required": false,
-      "values": [
-        "div",
-        "section",
-        "article",
-        "aside",
-        "main",
-        "header",
-        "footer",
-        "nav",
-        "span"
-      ]
+      "values": ["div", "section", "article", "aside", "main", "header", "footer", "nav", "span"]
     },
     "padding": {
       "type": "enum",
       "description": "Padding on all sides",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "paddingX": {
       "type": "enum",
       "description": "Horizontal padding",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "paddingY": {
       "type": "enum",
       "description": "Vertical padding",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl"]
     },
     "margin": {
       "type": "enum",
       "description": "Margin on all sides",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "auto"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl", "auto"]
     },
     "marginX": {
       "type": "enum",
       "description": "Horizontal margin",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "auto"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl", "auto"]
     },
     "marginY": {
       "type": "enum",
       "description": "Vertical margin",
       "required": false,
-      "values": [
-        "none",
-        "xs",
-        "sm",
-        "md",
-        "lg",
-        "xl",
-        "auto"
-      ]
+      "values": ["none", "xs", "sm", "md", "lg", "xl", "auto"]
     },
     "background": {
       "type": "enum",
       "description": "Background color",
       "required": false,
-      "values": [
-        "none",
-        "primary",
-        "secondary",
-        "tertiary",
-        "elevated"
-      ]
+      "values": ["none", "primary", "secondary", "tertiary", "elevated"]
     },
     "rounded": {
       "type": "enum",
       "description": "Border radius",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg",
-        "full"
-      ]
+      "values": ["none", "sm", "md", "lg", "full"]
     },
     "border": {
       "type": "boolean",
@@ -205,60 +132,31 @@
       "type": "enum",
       "description": "Border color variant (requires border or directional border)",
       "required": false,
-      "values": [
-        "default",
-        "strong",
-        "accent",
-        "danger"
-      ]
+      "values": ["default", "strong", "accent", "danger"]
     },
     "shadow": {
       "type": "enum",
       "description": "Box shadow",
       "required": false,
-      "values": [
-        "none",
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["none", "sm", "md", "lg"]
     },
     "overflow": {
       "type": "enum",
       "description": "Overflow behavior",
       "required": false,
-      "values": [
-        "hidden",
-        "auto",
-        "scroll",
-        "visible"
-      ]
+      "values": ["hidden", "auto", "scroll", "visible"]
     },
     "color": {
       "type": "enum",
       "description": "Text color",
       "required": false,
-      "values": [
-        "primary",
-        "secondary",
-        "tertiary",
-        "accent",
-        "inverse"
-      ]
+      "values": ["primary", "secondary", "tertiary", "accent", "inverse"]
     },
     "display": {
       "type": "enum",
       "description": "Display type",
       "required": false,
-      "values": [
-        "none",
-        "block",
-        "inline",
-        "inline-block",
-        "flex",
-        "inline-flex",
-        "grid"
-      ]
+      "values": ["none", "block", "inline", "inline-block", "flex", "inline-flex", "grid"]
     },
     "width": {
       "type": "union",
@@ -303,23 +201,21 @@
   },
   "usage": {
     "when": [
-      "Applying consistent padding or margin to content sections",
-      "Creating bordered or elevated containers",
-      "Wrapping content with semantic HTML elements",
-      "Building custom layouts not covered by Stack or Grid"
+      "Padding or insetting a section of content",
+      "Bordered or elevated containers",
+      "Rendering a semantic element with design-system spacing"
     ],
     "whenNot": [
-      "Horizontal or vertical stacking (use Stack)",
-      "Grid-based layouts (use Grid)",
-      "Card-like containers with header/body/footer (use Card)",
-      "Simple text styling (use Text)"
+      "Spacing a row or column of siblings (use Stack)",
+      "Two-dimensional layouts (use Grid)",
+      "Header/body/footer surfaces (use Card)",
+      "Styling text alone (use Text)"
     ],
     "guidelines": [
-      "Use padding props instead of inline styles for consistency",
-      "Choose semantic HTML elements (section, article) where appropriate",
-      "Combine with Stack or Grid for complex layouts",
-      "Use background variants from the design system, not custom colors",
-      "Box forwards DOM props (id, role, aria-*, data-*, event handlers) to the rendered element"
+      "Use the padding and margin props, never inline styles",
+      "Set as=\"section\" or as=\"article\" so the markup stays semantic",
+      "Backgrounds come from the token scale — no custom colours",
+      "Reach for Stack or Grid before nesting Boxes for layout"
     ],
     "accessibility": [
       "Choose semantic as prop values for proper document structure",
@@ -330,43 +226,43 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic box with padding",
+      "description": "Padding, background, and radius in one element.",
       "code": "<Box padding=\"md\" background=\"secondary\" rounded=\"md\">\n  Content with padding and background\n</Box>"
     },
     {
       "name": "With Border",
-      "description": "Bordered container",
+      "description": "A hairline border instead of a filled background.",
       "code": "<Box padding=\"lg\" border rounded=\"md\">\n  Bordered content area\n</Box>"
     },
     {
       "name": "Directional Padding",
-      "description": "Different horizontal and vertical padding",
+      "description": "Horizontal and vertical padding set separately.",
       "code": "<Box paddingX=\"xl\" paddingY=\"sm\" background=\"tertiary\" rounded=\"sm\">\n  Wide horizontal padding, short vertical\n</Box>"
     },
     {
       "name": "Centered with Auto Margin",
-      "description": "Centered content using margin auto",
-      "code": "<Box padding=\"md\" marginX=\"auto\" background=\"elevated\" rounded=\"lg\" style={{ maxWidth: '300px' }}>\n  Centered content\n</Box>"
+      "description": "marginX=\"auto\" centres a fixed-width box in a wider parent.",
+      "code": "import { Box } from '@/components/Box';\n\n<Box width=\"100%\" border rounded=\"md\" padding=\"md\">\n  <Box padding=\"md\" marginX=\"auto\" width=\"240px\" background=\"elevated\" rounded=\"lg\">\n    Centred by auto margin\n  </Box>\n</Box>"
     },
     {
       "name": "Directional Borders",
-      "description": "Individual border sides",
+      "description": "Border on chosen sides only.",
       "code": "<Box padding=\"md\" borderTop borderBottom>\n  Top and bottom borders only\n</Box>"
     },
     {
       "name": "With Shadow",
-      "description": "Box with shadow elevation",
+      "description": "Shadow lifts the surface off the page.",
       "code": "<Box padding=\"lg\" rounded=\"md\" shadow=\"md\" background=\"primary\">\n  Elevated content with shadow\n</Box>"
     },
     {
       "name": "Overflow Hidden",
-      "description": "Content overflow clipped",
-      "code": "<Box padding=\"md\" overflow=\"hidden\" border rounded=\"md\" style={{ maxHeight: '60px' }}>\n  This box clips overflowing content. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n</Box>"
+      "description": "Content past the box's height is clipped, not scrolled.",
+      "code": "import { Box } from '@/components/Box';\n\n<Box padding=\"md\" overflow=\"hidden\" border rounded=\"md\" width=\"320px\" height=\"72px\">\n  This box clips its overflowing content. Lorem ipsum dolor sit amet, consectetur\n  adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna\n  aliqua, and this final sentence never becomes visible.\n</Box>"
     },
     {
       "name": "Text Colors",
-      "description": "Text color variants",
-      "code": "<Box padding=\"md\" display=\"flex\" style={{ gap: '16px' }}>\n  <Box color=\"primary\">Primary</Box>\n  <Box color=\"secondary\">Secondary</Box>\n  <Box color=\"tertiary\">Tertiary</Box>\n  <Box color=\"accent\">Accent</Box>\n</Box>"
+      "description": "Text colour tokens, from strongest to accent.",
+      "code": "import { Box } from '@/components/Box';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"md\">\n  <Box color=\"primary\">Primary</Box>\n  <Box color=\"secondary\">Secondary</Box>\n  <Box color=\"tertiary\">Tertiary</Box>\n  <Box color=\"accent\">Accent</Box>\n</Stack>"
     }
   ],
   "relations": [
@@ -404,15 +300,11 @@
       "height/minHeight/maxHeight: string|number - sizing",
       "All standard HTMLElement props are forwarded to the rendered element"
     ],
-    "a11yRules": [
-      "A11Y_SEMANTIC_HTML"
-    ]
+    "a11yRules": ["A11Y_SEMANTIC_HTML"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root"
-    ]
+    "subComponents": ["Root"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Box/index.tsx

@@ -1,26 +1,26 @@
-import * as React from 'react';
-import styles from './Box.module.scss';
+import * as React from "react";
+import styles from "./Box.module.scss";
 
-export interface BoxProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color'> {
+export interface BoxProps extends Omit<React.HTMLAttributes<HTMLElement>, "color"> {
   children?: React.ReactNode;
   /** HTML element to render */
-  as?: 'div' | 'section' | 'article' | 'aside' | 'main' | 'header' | 'footer' | 'nav' | 'span';
+  as?: "div" | "section" | "article" | "aside" | "main" | "header" | "footer" | "nav" | "span";
   /** Padding on all sides */
-  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  padding?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
   /** Horizontal padding (overrides padding) */
-  paddingX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  paddingX?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
   /** Vertical padding (overrides padding) */
-  paddingY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  paddingY?: "none" | "xs" | "sm" | "md" | "lg" | "xl";
   /** Margin on all sides */
-  margin?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'auto';
+  margin?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "auto";
   /** Horizontal margin (overrides margin) */
-  marginX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'auto';
+  marginX?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "auto";
   /** Vertical margin (overrides margin) */
-  marginY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'auto';
+  marginY?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "auto";
   /** Background color */
-  background?: 'none' | 'primary' | 'secondary' | 'tertiary' | 'elevated';
+  background?: "none" | "primary" | "secondary" | "tertiary" | "elevated";
   /** Border radius */
-  rounded?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  rounded?: "none" | "sm" | "md" | "lg" | "full";
   /** Border */
   border?: boolean;
   /** Top border */
@@ -32,15 +32,15 @@ export interface BoxProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color
   /** Right border */
   borderRight?: boolean;
   /** Border color variant */
-  borderColor?: 'default' | 'strong' | 'accent' | 'danger';
+  borderColor?: "default" | "strong" | "accent" | "danger";
   /** Box shadow */
-  shadow?: 'sm' | 'md' | 'lg' | 'none';
+  shadow?: "sm" | "md" | "lg" | "none";
   /** Overflow behavior */
-  overflow?: 'hidden' | 'auto' | 'scroll' | 'visible';
+  overflow?: "hidden" | "auto" | "scroll" | "visible";
   /** Text color */
-  color?: 'primary' | 'secondary' | 'tertiary' | 'accent' | 'inverse';
+  color?: "primary" | "secondary" | "tertiary" | "accent" | "inverse";
   /** Display type */
-  display?: 'block' | 'inline' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none';
+  display?: "block" | "inline" | "inline-block" | "flex" | "inline-flex" | "grid" | "none";
   /** Width (CSS value, e.g. "100%", "300px", 200) */
   width?: string | number;
   /** Min width */
@@ -61,93 +61,86 @@ export interface BoxProps extends Omit<React.HTMLAttributes<HTMLElement>, 'color
 
 /** Convert string | number to CSS value */
 function toCss(value: string | number): string {
-  return typeof value === 'number' ? `${value}px` : value;
+  return typeof value === "number" ? `${value}px` : value;
 }
 
-const BoxRoot = React.forwardRef<HTMLElement, BoxProps>(
-  function Box(
-    {
-      children,
-      as: Component = 'div',
-      padding,
-      paddingX,
-      paddingY,
-      margin,
-      marginX,
-      marginY,
-      background,
-      rounded,
-      border,
-      borderTop,
-      borderBottom,
-      borderLeft,
-      borderRight,
-      borderColor,
-      shadow,
-      overflow,
-      color,
-      display,
-      width,
-      minWidth,
-      maxWidth,
-      height,
-      minHeight,
-      maxHeight,
-      className,
-      style,
-      ...htmlProps
-    },
-    ref
-  ) {
-    const classes = [
-      styles.box,
-      padding && styles[`p-${padding}`],
-      paddingX && styles[`px-${paddingX}`],
-      paddingY && styles[`py-${paddingY}`],
-      margin && styles[`m-${margin}`],
-      marginX && styles[`mx-${marginX}`],
-      marginY && styles[`my-${marginY}`],
-      background && styles[`bg-${background}`],
-      rounded && styles[`rounded-${rounded}`],
-      border && styles.border,
-      borderTop && styles.borderTop,
-      borderBottom && styles.borderBottom,
-      borderLeft && styles.borderLeft,
-      borderRight && styles.borderRight,
-      borderColor && styles[`borderColor-${borderColor}`],
-      shadow && styles[`shadow-${shadow}`],
-      overflow && styles[`overflow-${overflow}`],
-      color && styles[`color-${color}`],
-      display && styles[`display-${display}`],
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ');
+const BoxRoot = React.forwardRef<HTMLElement, BoxProps>(function Box(
+  {
+    children,
+    as: Component = "div",
+    padding,
+    paddingX,
+    paddingY,
+    margin,
+    marginX,
+    marginY,
+    background,
+    rounded,
+    border,
+    borderTop,
+    borderBottom,
+    borderLeft,
+    borderRight,
+    borderColor,
+    shadow,
+    overflow,
+    color,
+    display,
+    width,
+    minWidth,
+    maxWidth,
+    height,
+    minHeight,
+    maxHeight,
+    className,
+    style,
+    ...htmlProps
+  },
+  ref
+) {
+  const classes = [
+    styles.box,
+    padding && styles[`p-${padding}`],
+    paddingX && styles[`px-${paddingX}`],
+    paddingY && styles[`py-${paddingY}`],
+    margin && styles[`m-${margin}`],
+    marginX && styles[`mx-${marginX}`],
+    marginY && styles[`my-${marginY}`],
+    background && styles[`bg-${background}`],
+    rounded && styles[`rounded-${rounded}`],
+    border && styles.border,
+    borderTop && styles.borderTop,
+    borderBottom && styles.borderBottom,
+    borderLeft && styles.borderLeft,
+    borderRight && styles.borderRight,
+    borderColor && styles[`borderColor-${borderColor}`],
+    shadow && styles[`shadow-${shadow}`],
+    overflow && styles[`overflow-${overflow}`],
+    color && styles[`color-${color}`],
+    display && styles[`display-${display}`],
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
 
-    // Build sizing styles only when props are provided
-    const sizingStyle: React.CSSProperties = {};
-    if (width != null) sizingStyle.width = toCss(width);
-    if (minWidth != null) sizingStyle.minWidth = toCss(minWidth);
-    if (maxWidth != null) sizingStyle.maxWidth = toCss(maxWidth);
-    if (height != null) sizingStyle.height = toCss(height);
-    if (minHeight != null) sizingStyle.minHeight = toCss(minHeight);
-    if (maxHeight != null) sizingStyle.maxHeight = toCss(maxHeight);
+  // Build sizing styles only when props are provided
+  const sizingStyle: React.CSSProperties = {};
+  if (width != null) sizingStyle.width = toCss(width);
+  if (minWidth != null) sizingStyle.minWidth = toCss(minWidth);
+  if (maxWidth != null) sizingStyle.maxWidth = toCss(maxWidth);
+  if (height != null) sizingStyle.height = toCss(height);
+  if (minHeight != null) sizingStyle.minHeight = toCss(minHeight);
+  if (maxHeight != null) sizingStyle.maxHeight = toCss(maxHeight);
 
-    const hasSizing = Object.keys(sizingStyle).length > 0;
-    const mergedStyle = hasSizing ? { ...sizingStyle, ...style } : style;
+  const hasSizing = Object.keys(sizingStyle).length > 0;
+  const mergedStyle = hasSizing ? { ...sizingStyle, ...style } : style;
 
-    return (
-      <Component
-        ref={ref as React.Ref<never>}
-        {...htmlProps}
-        className={classes}
-        style={mergedStyle}
-      >
-        {children}
-      </Component>
-    );
-  }
-);
+  return (
+    <Component ref={ref as React.Ref<never>} {...htmlProps} className={classes} style={mergedStyle}>
+      {children}
+    </Component>
+  );
+});
 
 export const Box = Object.assign(BoxRoot, {
   Root: BoxRoot,