@fragments-sdk/ui 0.14.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -230,18 +230,26 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@fragments-sdk/core": "0.2.0"
+    "@fragments-sdk/core": "0.3.0"
   },
   "files": [
     "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/test/",
+    "!src/**/*.fragment.tsx",
+    "!src/**/*.block.ts",
+    "!src/blocks/",
+    "!src/assets/*.svg",
     "dist",
     "fragments.json"
   ],
   "scripts": {
-    "dev": "node ../../packages/cli/dist/bin.js dev",
-    "build": "node ../../packages/cli/dist/bin.js build && vite build && tsc -p tsconfig.build.json",
+    "cli:ensure": "test -f ../../packages/cli/dist/bin.js || pnpm --filter @fragments-sdk/cli build",
+    "dev": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js dev",
+    "build": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js build && vite build && tsc -p tsconfig.build.json",
     "lint": "eslint src",
-    "validate": "node ../../packages/cli/dist/bin.js validate",
+    "validate": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js validate",
     "test": "vitest run"
   },
   "module": "dist/index.js"

package/src/components/BentoGrid/BentoGrid.module.scss

@@ -157,3 +157,23 @@
     border-color: var(--fui-text-primary, $fui-text-primary);
   }
 }
+
+// ============================================
+// Subgrid — item children align to parent tracks
+// ============================================
+
+.subgridRows {
+  display: grid;
+  grid-template-rows: subgrid;
+}
+
+.subgridColumns {
+  display: grid;
+  grid-template-columns: subgrid;
+}
+
+.subgridBoth {
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-template-columns: subgrid;
+}

package/src/components/BentoGrid/index.tsx

@@ -34,6 +34,14 @@ export interface BentoGridItemProps extends React.HTMLAttributes<HTMLDivElement>
   colSpan?: SpanValue | ResponsiveSpan;
   /** Rows to span — number for all breakpoints, object for per-breakpoint */
   rowSpan?: SpanValue | ResponsiveSpan;
+  /**
+   * Enable CSS subgrid so children align to parent grid tracks.
+   * - `true` or `"rows"` — children align to parent row tracks
+   * - `"columns"` — children align to parent column tracks
+   * - `"both"` — children align to both row and column tracks
+   * Requires the item to span multiple rows/columns for visible effect.
+   */
+  subgrid?: boolean | 'rows' | 'columns' | 'both';
 }
 
 // ============================================
@@ -101,12 +109,19 @@ export const BentoGrid = React.forwardRef<HTMLDivElement, BentoGridProps>(
 // BentoGrid.Item Sub-component
 // ============================================
 
+const subgridClasses: Record<string, string> = {
+  rows: styles.subgridRows,
+  columns: styles.subgridColumns,
+  both: styles.subgridBoth,
+};
+
 const BentoGridItem = React.forwardRef<HTMLDivElement, BentoGridItemProps>(
   function BentoGridItem(
     {
       children,
       colSpan,
       rowSpan,
+      subgrid,
       className,
       style,
       ...htmlProps
@@ -123,7 +138,11 @@ const BentoGridItem = React.forwardRef<HTMLDivElement, BentoGridItemProps>(
       ? ({ ...(spanVars as unknown as React.CSSProperties), ...style } as React.CSSProperties)
       : style;
 
-    const classes = [styles.item, className].filter(Boolean).join(' ');
+    const subgridClass = subgrid
+      ? subgridClasses[subgrid === true ? 'rows' : subgrid]
+      : undefined;
+
+    const classes = [styles.item, subgridClass, className].filter(Boolean).join(' ');
 
     return (
       <div ref={ref} {...htmlProps} className={classes} style={inlineStyle}>

package/src/components/Button/Button.module.scss

@@ -17,6 +17,10 @@
 }
 
 // Sizes
+// Note: Button padding intentionally diverges from the control-size mixin
+// (md: space-3 vs mixin's space-4, lg: space-4 vs mixin's space-5).
+// Buttons need tighter horizontal padding than inputs for visual balance,
+// since button text is typically shorter than input content.
 .sm {
   min-height: var(--fui-button-height-sm, $fui-button-height-sm);
   padding: 0 var(--fui-space-2, $fui-space-2);
@@ -138,6 +142,20 @@
 // Accessibility: High Contrast Mode
 // ============================================
 
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .button {
+    transition: none;
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
 @media (prefers-contrast: more) {
   .secondary {
     border-width: 2px;

package/src/components/Button/index.tsx

@@ -10,7 +10,7 @@ import styles from './Button.module.scss';
  */
 type ButtonBaseProps = {
   children: React.ReactNode;
-  /** Visual style variant. `"outline"` is an alias for `"outlined"`. `"icon"` is a convenience alias for a ghost icon-only button.
+  /** Visual style variant. `"outline"` is an alias for `"outlined"`. `"icon"` is a convenience alias for an outlined icon-only button.
    * @default "primary"
    * @see https://usefragments.com/components/button#variants */
   variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'outlined' | 'outline' | 'icon';
@@ -18,7 +18,7 @@ type ButtonBaseProps = {
    * @default "md"
    * @see https://usefragments.com/components/button#sizes */
   size?: 'sm' | 'md' | 'lg';
-  /** Render as icon-only button (square aspect ratio). Prefer `variant="icon"` for the default ghost icon button. */
+  /** Render as icon-only button (square aspect ratio). Prefer `variant="icon"` for the default outlined icon button. */
   icon?: boolean;
   /** Make button full width of container */
   fullWidth?: boolean;
@@ -62,11 +62,11 @@ const ButtonRoot = React.forwardRef<
 
   // Resolve aliases:
   // "outline" → "outlined"
-  // "icon" → visual "ghost" + icon-only sizing
+  // "icon" → visual "outlined" + icon-only sizing
   const variant = variantProp === 'outline'
     ? 'outlined'
     : variantProp === 'icon'
-      ? 'ghost'
+      ? 'outlined'
       : variantProp;
 
   const classNames = [

package/src/components/Chart/index.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import * as React from 'react';
+import { mergeAriaIds } from '../../utils/aria';
 import styles from './Chart.module.scss';
 import '../../styles/globals.scss';
 
@@ -76,10 +77,6 @@ function loadChartDeps() {
   }
 }
 
-function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
-  const merged = ids.filter(Boolean).join(' ').trim();
-  return merged.length > 0 ? merged : undefined;
-}
 
 // ============================================
 // Context

package/src/components/Checkbox/Checkbox.module.scss

@@ -5,7 +5,7 @@
 .wrapper {
   display: inline-flex;
   align-items: center;
-  gap: var(--fui-space-1, $fui-space-1);
+  gap: var(--fui-space-2, $fui-space-2);
   cursor: pointer;
   font-family: var(--fui-font-sans, $fui-font-sans);
 
@@ -65,7 +65,7 @@
 .sm {
   width: 0.875rem;
   height: 0.875rem;
-  border-radius: var(--fui-space-0-75, $fui-space-0-75);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
 }
 
 .md {
@@ -137,8 +137,38 @@
   font-size: var(--fui-font-size-base, $fui-font-size-base);
 }
 
-.description {
+.helper {
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   color: var(--fui-text-secondary, $fui-text-secondary);
   line-height: var(--fui-line-height-normal, $fui-line-height-normal);
 }
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .checkbox {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &[data-checked],
+    &[data-indeterminate] {
+      border-color: var(--fui-color-accent, $fui-color-accent);
+    }
+
+    &[data-invalid] {
+      border-color: var(--fui-color-danger, $fui-color-danger);
+    }
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .indicator {
+    transition: none;
+  }
+}

package/src/components/Checkbox/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { Checkbox as BaseCheckbox } from '@base-ui/react/checkbox';
+import { mergeAriaIds } from '../../utils/aria';
 import styles from './Checkbox.module.scss';
 
 // ============================================
@@ -32,7 +33,9 @@ export interface CheckboxProps extends Omit<React.HTMLAttributes<HTMLLabelElemen
   size?: 'sm' | 'md' | 'lg';
   /** Label text */
   label?: string;
-  /** Description text below the label */
+  /** Helper text shown below the label */
+  helperText?: string;
+  /** @deprecated Use helperText instead. Description text below the label. */
   description?: string;
   /** Name attribute for form submission */
   name?: string;
@@ -52,11 +55,6 @@ export interface CheckboxProps extends Omit<React.HTMLAttributes<HTMLLabelElemen
   'aria-describedby'?: string;
 }
 
-function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
-  const merged = ids.filter(Boolean).join(' ').trim();
-  return merged.length > 0 ? merged : undefined;
-}
-
 // ============================================
 // Icons
 // ============================================
@@ -111,6 +109,7 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
       required = false,
       size = 'md',
       label,
+      helperText,
       description,
       name,
       value,
@@ -125,10 +124,11 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
     },
     ref
   ) {
+    const resolvedHelperText = helperText ?? description;
     const generatedId = React.useId();
     const checkboxId = id ?? `checkbox-${generatedId}`;
     const labelId = label ? `${checkboxId}-label` : undefined;
-    const descriptionId = description ? `${checkboxId}-description` : undefined;
+    const descriptionId = resolvedHelperText ? `${checkboxId}-description` : undefined;
 
     const checkboxClasses = [
       styles.checkbox,
@@ -147,7 +147,7 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
     const handleCheckedChange = onChange ?? onCheckedChange;
 
     // If no label/description, render just the checkbox
-    if (!label && !description) {
+    if (!label && !resolvedHelperText) {
       const iconOnlyHtmlProps = htmlProps as unknown as Record<string, unknown>;
       return (
         <BaseCheckbox.Root
@@ -179,7 +179,7 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
         {...htmlProps}
         className={wrapperClasses}
         data-disabled={disabled || undefined}
-        data-has-description={description ? true : undefined}
+        data-has-description={resolvedHelperText ? true : undefined}
       >
         <BaseCheckbox.Root
           ref={ref}
@@ -203,8 +203,8 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
         </BaseCheckbox.Root>
         <div className={[styles.content, contentClassName].filter(Boolean).join(' ')}>
           <span id={labelId} className={labelClasses}>{label}</span>
-          {description && (
-            <span id={descriptionId} className={styles.description}>{description}</span>
+          {resolvedHelperText && (
+            <span id={descriptionId} className={styles.helper}>{resolvedHelperText}</span>
           )}
         </div>
       </label>

package/src/components/Chip/Chip.module.scss

@@ -22,6 +22,13 @@
 }
 
 // Sizes
+.xs {
+  height: var(--fui-target-size-min, $fui-target-size-min);
+  padding: 0 var(--fui-space-1, $fui-space-1);
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  gap: var(--fui-space-0-5, $fui-space-0-5);
+}
+
 .sm {
   height: var(--fui-button-height-sm, $fui-button-height-sm);
   padding: 0 var(--fui-space-2, $fui-space-2);
@@ -137,6 +144,13 @@
     object-fit: cover;
   }
 
+  .xs & {
+    img {
+      width: var(--fui-icon-sm, $fui-icon-sm);
+      height: var(--fui-icon-sm, $fui-icon-sm);
+    }
+  }
+
   .sm & {
     img {
       width: var(--fui-icon-sm, $fui-icon-sm);
@@ -176,6 +190,11 @@
   border: 1px solid transparent;
   border-left-color: var(--fui-border, $fui-border);
 
+  .xs & {
+    font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+    padding: 0 var(--fui-space-0-5, $fui-space-0-5);
+  }
+
   .sm & {
     font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   }

package/src/components/Chip/index.tsx

@@ -15,7 +15,7 @@ export interface ChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonEle
   variant?: 'filled' | 'outlined' | 'outline' | 'soft';
   /** Chip size.
    * @default "md" */
-  size?: 'sm' | 'md' | 'lg';
+  size?: 'xs' | 'sm' | 'md' | 'lg';
   /** Whether the chip is selected */
   selected?: boolean;
   /** Icon element rendered before the label */

package/src/components/ColorPicker/ColorPicker.module.scss

@@ -1,10 +1,8 @@
 @use '../../tokens/variables' as *;
 @use '../../tokens/mixins' as *;
 
-.wrapper {
-  display: flex;
-  flex-direction: column;
-}
+// Form field wrapper (label + helper + error)
+@include form-field-wrapper;
 
 // Size variants
 .sizeSm {
@@ -13,8 +11,8 @@
   }
 
   .swatch {
-    width: $fui-touch-sm;
-    height: $fui-touch-sm;
+    width: var(--fui-input-height-sm, $fui-input-height-sm);
+    height: var(--fui-input-height-sm, $fui-input-height-sm);
   }
 
   .hexInput {
@@ -37,7 +35,7 @@
   }
 
   .swatch {
-    width: 48px;
+    width: var(--fui-input-height-lg, $fui-input-height-lg);
     height: var(--fui-input-height-lg, $fui-input-height-lg);
   }
 
@@ -50,11 +48,6 @@
   }
 }
 
-.label {
-  @include label-text;
-  margin-bottom: var(--fui-space-1, $fui-space-1);
-}
-
 .inputWrapper {
   display: flex;
   gap: var(--fui-space-2, $fui-space-2);
@@ -65,7 +58,7 @@
   @include button-reset;
   @include interactive-base;
   @include min-target-size;
-  width: var(--fui-target-size-comfortable, $fui-target-size-comfortable);
+  width: var(--fui-input-height, $fui-input-height);
   height: var(--fui-input-height, $fui-input-height);
   border: 1px solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
@@ -133,7 +126,23 @@
   }
 }
 
-.description {
-  @include helper-text;
-  margin-top: var(--fui-space-1, $fui-space-1);
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .swatch {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .swatch {
+    transition: none;
+  }
 }

package/src/components/ColorPicker/index.tsx

@@ -36,8 +36,14 @@ export interface ColorPickerProps extends Omit<React.HTMLAttributes<HTMLDivEleme
   defaultValue?: string;
   /** Called with new color value when changed */
   onChange?: (color: string) => void;
+  /** Alias for onChange (Radix convention) */
+  onValueChange?: (color: string) => void;
   /** Helper text below the picker */
+  helperText?: string;
+  /** @deprecated Use helperText instead. */
   description?: string;
+  /** Show error styling */
+  error?: boolean;
   /** Disable the color picker */
   disabled?: boolean;
   /** Size variant */
@@ -52,8 +58,11 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(
       label,
       value,
       defaultValue = '#000000',
-      onChange,
+      onChange: onChangeProp,
+      onValueChange,
+      helperText,
       description,
+      error = false,
       disabled = false,
       size = 'md',
       showInput = true,
@@ -62,6 +71,7 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(
     },
     ref
   ) {
+    const resolvedHelperText = helperText ?? description;
     loadColorfulDeps();
     const [internalValue, setInternalValue] = React.useState(defaultValue);
     const [inputValue, setInputValue] = React.useState(value ?? defaultValue);
@@ -74,6 +84,8 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(
       }
     }, [value]);
 
+    const onChange = onChangeProp ?? onValueChange;
+
     const handleChange = (color: string) => {
       setInternalValue(color);
       setInputValue(color);
@@ -103,11 +115,16 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(
       className,
     ].filter(Boolean).join(' ');
 
+    const helperClasses = [styles.helper, error && styles.helperError]
+      .filter(Boolean)
+      .join(' ');
+
     return (
       <Field.Root
         ref={ref}
         {...htmlProps}
         disabled={disabled}
+        invalid={error}
         className={wrapperClasses}
       >
         {label && <Field.Label className={styles.label}>{label}</Field.Label>}
@@ -145,9 +162,9 @@ const ColorPickerRoot = React.forwardRef<HTMLDivElement, ColorPickerProps>(
             />
           )}
         </div>
-        {description && (
-          <Field.Description className={styles.description}>
-            {description}
+        {resolvedHelperText && (
+          <Field.Description className={helperClasses}>
+            {resolvedHelperText}
           </Field.Description>
         )}
       </Field.Root>