@fragments-sdk/ui 0.12.0 → 0.14.0

package/src/components/Box/Box.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Box } from '.';
 
 export default defineFragment({
@@ -32,6 +32,7 @@ export default defineFragment({
       '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',
     ],
     accessibility: [
       'Choose semantic as prop values for proper document structure',
@@ -189,6 +190,7 @@ export default defineFragment({
       'color: primary|secondary|tertiary|accent|inverse - text color',
       'width/minWidth/maxWidth: string|number - sizing',
       'height/minHeight/maxHeight: string|number - sizing',
+      'All standard HTMLElement props are forwarded to the rendered element',
     ],
     scenarioTags: [
       'layout.container',

package/src/components/Box/Box.test.tsx

@@ -40,4 +40,18 @@ describe('Box', () => {
     const { container } = render(<Box>Accessible</Box>);
     await expectNoA11yViolations(container);
   });
+
+  it('forwards DOM props and event handlers', () => {
+    const onClick = vi.fn();
+    render(
+      <Box data-testid="box" id="box-id" aria-label="Box label" onClick={onClick}>
+        Content
+      </Box>
+    );
+    const el = screen.getByTestId('box');
+    el.click();
+    expect(el).toHaveAttribute('id', 'box-id');
+    expect(el).toHaveAttribute('aria-label', 'Box label');
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
 });

package/src/components/Box/index.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import styles from './Box.module.scss';
 
-export interface BoxProps {
+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';
@@ -95,6 +95,7 @@ const BoxRoot = React.forwardRef<HTMLElement, BoxProps>(
       maxHeight,
       className,
       style,
+      ...htmlProps
     },
     ref
   ) {
@@ -136,7 +137,12 @@ const BoxRoot = React.forwardRef<HTMLElement, BoxProps>(
     const mergedStyle = hasSizing ? { ...sizingStyle, ...style } : style;
 
     return (
-      <Component ref={ref as React.Ref<never>} className={classes} style={mergedStyle}>
+      <Component
+        ref={ref as React.Ref<never>}
+        {...htmlProps}
+        className={classes}
+        style={mergedStyle}
+      >
         {children}
       </Component>
     );

package/src/components/Breadcrumbs/Breadcrumbs.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Breadcrumbs } from '.';
 
 export default defineFragment({
@@ -30,6 +30,7 @@ export default defineFragment({
       'Keep labels short and descriptive',
       'Use maxItems to collapse long paths, keeping first and last visible',
       'The separator defaults to "/" but can be customized',
+      'Use the label prop to customize the nav landmark name (defaults to "Breadcrumb")',
     ],
     accessibility: [
       'Uses <nav aria-label="Breadcrumb"> for landmark navigation',
@@ -54,6 +55,11 @@ export default defineFragment({
       type: 'number',
       description: 'Maximum visible items before collapsing middle items with ellipsis',
     },
+    label: {
+      type: 'string',
+      description: 'Custom aria-label for the breadcrumb nav landmark',
+      default: '"Breadcrumb"',
+    },
   },
 
   relations: [
@@ -65,6 +71,7 @@ export default defineFragment({
     propsSummary: [
       'separator: ReactNode - custom separator (default "/")',
       'maxItems: number - collapse middle items with ellipsis',
+      'label: string - nav landmark label (default "Breadcrumb")',
       'Breadcrumbs.Item href: string - makes item a link',
       'Breadcrumbs.Item current: boolean - marks current page',
       'Breadcrumbs.Item icon: ReactNode - icon before label',
@@ -158,5 +165,16 @@ export default defineFragment({
         </Breadcrumbs>
       ),
     },
+    {
+      name: 'Custom Landmark Label',
+      description: 'Override the nav landmark label for screen readers',
+      render: () => (
+        <Breadcrumbs label="Documentation breadcrumbs">
+          <Breadcrumbs.Item href="#">Docs</Breadcrumbs.Item>
+          <Breadcrumbs.Item href="#">Components</Breadcrumbs.Item>
+          <Breadcrumbs.Item current>Breadcrumbs</Breadcrumbs.Item>
+        </Breadcrumbs>
+      ),
+    },
   ],
 });

package/src/components/Breadcrumbs/Breadcrumbs.test.tsx

@@ -13,6 +13,19 @@ describe('Breadcrumbs', () => {
     expect(screen.getByRole('navigation', { name: 'Breadcrumb' })).toBeInTheDocument();
   });
 
+  it('supports custom breadcrumb nav label and root props', () => {
+    render(
+      <Breadcrumbs label="Path" id="crumbs" data-testid="crumbs">
+        <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+        <Breadcrumbs.Item current>Page</Breadcrumbs.Item>
+      </Breadcrumbs>
+    );
+
+    const nav = screen.getByRole('navigation', { name: 'Path' });
+    expect(nav).toHaveAttribute('id', 'crumbs');
+    expect(nav).toHaveAttribute('data-testid', 'crumbs');
+  });
+
   it('marks current page with aria-current="page"', () => {
     render(
       <Breadcrumbs>

package/src/components/Breadcrumbs/index.tsx

@@ -13,6 +13,8 @@ export interface BreadcrumbsProps extends React.HTMLAttributes<HTMLElement> {
   separator?: React.ReactNode;
   /** Maximum visible items before collapsing middle items with ellipsis */
   maxItems?: number;
+  /** Accessible label for the breadcrumb nav landmark (default: "Breadcrumb") */
+  label?: string;
 }
 
 export interface BreadcrumbsItemProps extends React.HTMLAttributes<HTMLLIElement> {
@@ -44,7 +46,9 @@ function BreadcrumbsRoot({
   children,
   separator = '/',
   maxItems,
+  label = 'Breadcrumb',
   className,
+  'aria-label': ariaLabel,
   ...htmlProps
 }: BreadcrumbsProps) {
   const classes = [styles.root, className].filter(Boolean).join(' ');
@@ -64,7 +68,7 @@ function BreadcrumbsRoot({
 
   return (
     <BreadcrumbsSeparatorContext.Provider value={separator}>
-      <nav aria-label="Breadcrumb" className={classes} {...htmlProps}>
+      <nav {...htmlProps} aria-label={ariaLabel ?? label} className={classes}>
         <ol className={styles.list}>
           {items.map((item, index) => {
             const isFirst = index === 0;

package/src/components/Button/Button.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Button } from '.';
 
 export default defineFragment({
@@ -30,6 +30,8 @@ export default defineFragment({
       'Only one Primary button per section/form',
       'Use Danger variant for destructive actions',
       'Loading state should disable the button',
+      'When using asChild, pass interaction and accessibility props directly on Button (they are forwarded to the child element)',
+      'Use variant="icon" for the default icon-only action button, or combine icon={true} with another visual variant when needed',
     ],
     accessibility: [
       'Button text should describe the action',
@@ -46,9 +48,9 @@ export default defineFragment({
     },
     variant: {
       type: 'enum',
-      values: ['primary', 'secondary', 'ghost', 'danger', 'outlined', 'outline'],
+      values: ['primary', 'secondary', 'ghost', 'danger', 'outlined', 'outline', 'icon'],
       default: 'primary',
-      description: 'Visual style variant',
+      description: 'Visual style variant ("icon" is a convenience alias for ghost + icon-only layout)',
       constraints: ['Only one primary button per context'],
     },
     size: {
@@ -71,7 +73,7 @@ export default defineFragment({
     icon: {
       type: 'boolean',
       default: 'false',
-      description: 'Render as icon-only button (square aspect ratio)',
+      description: 'Render as icon-only button (square aspect ratio). Useful with any visual variant; variant="icon" is the default ghost icon-only shortcut.',
     },
     fullWidth: {
       type: 'boolean',
@@ -100,11 +102,13 @@ export default defineFragment({
 
   contract: {
     propsSummary: [
-      'variant: primary|secondary|ghost|danger|outlined|outline (default: primary)',
+      'variant: primary|secondary|ghost|danger|outlined|outline|icon (default: primary, icon = ghost + icon-only)',
       'size: sm|md|lg (default: md)',
       'disabled: boolean - disables interaction',
       'type: button|submit|reset (default: button)',
-      'onClick: () => void - action handler',
+      'onClick: (event) => void - action handler',
+      'asChild: boolean - composes styles/props onto a child element (links/router links)',
+      'icon: boolean - icon-only square layout (can be combined with visual variants)',
     ],
     scenarioTags: [
       'form.submit',
@@ -150,6 +154,15 @@ export default defineFragment({
       description: 'Bordered button with transparent background',
       render: () => <Button variant="outline">View Details</Button>,
     },
+    {
+      name: 'Icon',
+      description: 'Convenience icon-only button alias (ghost + square icon sizing)',
+      render: () => (
+        <Button variant="icon" aria-label="Add item">
+          <span aria-hidden>+</span>
+        </Button>
+      ),
+    },
     {
       name: 'Sizes',
       description: 'Available size options',
@@ -166,5 +179,14 @@ export default defineFragment({
       description: 'Non-interactive state',
       render: () => <Button disabled>Cannot Click</Button>,
     },
+    {
+      name: 'As Child',
+      description: 'Compose button styles onto another interactive element while preserving forwarded props',
+      render: () => (
+        <Button asChild variant="outlined" aria-label="Open billing settings">
+          <a href="#billing-settings">Billing Settings</a>
+        </Button>
+      ),
+    },
   ],
 });

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

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 .button {
   @include button-reset;
@@ -9,7 +9,7 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: var(--fui-space-1, $fui-space-1);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   white-space: nowrap;

package/src/components/Button/Button.test.tsx

@@ -51,6 +51,17 @@ describe('Button', () => {
     expect(screen.getByRole('button')).toHaveClass('outlined');
   });
 
+  it('resolves variant="icon" to a ghost icon-only button', () => {
+    render(
+      <Button variant="icon" aria-label="Icon action">
+        <span aria-hidden>+</span>
+      </Button>
+    );
+    const button = screen.getByRole('button', { name: 'Icon action' });
+    expect(button).toHaveClass('ghost');
+    expect(button).toHaveClass('icon');
+  });
+
   it('renders as child element when asChild is true', () => {
     render(
       <Button asChild>

package/src/components/Button/index.tsx

@@ -10,15 +10,15 @@ import styles from './Button.module.scss';
  */
 type ButtonBaseProps = {
   children: React.ReactNode;
-  /** Visual style variant. `"outline"` is an alias for `"outlined"`.
+  /** Visual style variant. `"outline"` is an alias for `"outlined"`. `"icon"` is a convenience alias for a ghost icon-only button.
    * @default "primary"
    * @see https://usefragments.com/components/button#variants */
-  variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'outlined' | 'outline';
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'outlined' | 'outline' | 'icon';
   /** Button size.
    * @default "md"
    * @see https://usefragments.com/components/button#sizes */
   size?: 'sm' | 'md' | 'lg';
-  /** Render as icon-only button (square aspect ratio) */
+  /** Render as icon-only button (square aspect ratio). Prefer `variant="icon"` for the default ghost icon button. */
   icon?: boolean;
   /** Make button full width of container */
   fullWidth?: boolean;
@@ -58,14 +58,22 @@ const ButtonRoot = React.forwardRef<
     ...rest
   } = props;
 
-  // Resolve alias: "outline" → "outlined"
-  const variant = variantProp === 'outline' ? 'outlined' : variantProp;
+  const iconOnly = icon || variantProp === 'icon';
+
+  // Resolve aliases:
+  // "outline" → "outlined"
+  // "icon" → visual "ghost" + icon-only sizing
+  const variant = variantProp === 'outline'
+    ? 'outlined'
+    : variantProp === 'icon'
+      ? 'ghost'
+      : variantProp;
 
   const classNames = [
     styles.button,
     styles[size],
     styles[variant],
-    icon && styles.icon,
+    iconOnly && styles.icon,
     fullWidth && styles.fullWidth,
     className,
   ]
@@ -74,7 +82,9 @@ const ButtonRoot = React.forwardRef<
 
   // asChild: merge button styling onto child element (e.g. Next.js Link)
   if (asChild && React.isValidElement(children)) {
+    const { as: _as, ...childProps } = rest as ButtonProps & { as?: 'a' | 'button' };
     return React.cloneElement(children as React.ReactElement<Record<string, unknown>>, {
+      ...childProps,
       className: [classNames, (children.props as Record<string, unknown>).className].filter(Boolean).join(' '),
       ref,
     });

package/src/components/ButtonGroup/ButtonGroup.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { ButtonGroup } from '.';
 import { Button } from '../Button';
 
@@ -32,6 +32,7 @@ export default defineFragment({
       'Use consistent button variants within a group',
       'Consider visual hierarchy - primary action should stand out',
       'Limit to 2-4 buttons per group for clarity',
+      'Pass role/aria-label/id/data-* directly to ButtonGroup when you need semantic grouping hooks',
     ],
     accessibility: [
       'Group provides semantic relationship between buttons',
@@ -75,6 +76,7 @@ export default defineFragment({
       'gap: none|xs|sm|md - spacing between buttons',
       'wrap: boolean - allow wrapping',
       'align: start|center|end - alignment',
+      'Pass-through DOM props supported on root (id, role, aria-*, data-*, handlers)',
     ],
     scenarioTags: [
       'layout.group',
@@ -143,7 +145,7 @@ export default defineFragment({
       name: 'Form Actions',
       description: 'Common pattern for form submit/cancel',
       render: () => (
-        <ButtonGroup align="end">
+        <ButtonGroup align="end" role="group" aria-label="Form actions">
           <Button variant="ghost">Cancel</Button>
           <Button variant="primary">Submit</Button>
         </ButtonGroup>

package/src/components/ButtonGroup/ButtonGroup.test.tsx

@@ -32,6 +32,16 @@ describe('ButtonGroup', () => {
     expect(container.firstElementChild).toHaveClass('wrap');
   });
 
+  it('forwards DOM props to the group root', () => {
+    render(
+      <ButtonGroup data-testid="group" role="group" aria-label="Actions">
+        <button>Save</button>
+      </ButtonGroup>
+    );
+    expect(screen.getByTestId('group')).toHaveAttribute('aria-label', 'Actions');
+    expect(screen.getByTestId('group')).toHaveAttribute('role', 'group');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(
       <ButtonGroup>

package/src/components/ButtonGroup/index.tsx

@@ -1,12 +1,11 @@
 import * as React from 'react';
 import styles from './ButtonGroup.module.scss';
 
-export interface ButtonGroupProps {
+export interface ButtonGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
   children: React.ReactNode;
   gap?: 'none' | 'xs' | 'sm' | 'md';
   wrap?: boolean;
   align?: 'start' | 'center' | 'end';
-  className?: string;
 }
 
 const ButtonGroupRoot = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
@@ -17,6 +16,7 @@ const ButtonGroupRoot = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
       wrap = false,
       align,
       className,
+      ...htmlProps
     },
     ref
   ) {
@@ -31,7 +31,7 @@ const ButtonGroupRoot = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
       .join(' ');
 
     return (
-      <div ref={ref} className={classes}>
+      <div ref={ref} {...htmlProps} className={classes}>
         {children}
       </div>
     );

package/src/components/Card/Card.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Card } from '.';
 
 export default defineFragment({
@@ -29,10 +29,10 @@ export default defineFragment({
       'Use consistent card variants within the same context',
       'Cards in a grid should have uniform sizing',
       'Use elevated variant sparingly for emphasis',
-      'Interactive cards should have clear hover states',
+      'If a card is clickable, provide clear hover/focus affordances and prefer explicit buttons/links inside the card',
     ],
     accessibility: [
-      'Interactive cards should use button or link semantics',
+      'Card is a semantic container (article/div/section); onClick does not automatically add button semantics',
       'Card titles should be appropriate heading levels',
     ],
   },
@@ -55,9 +55,11 @@ export default defineFragment({
       default: 'md',
       description: 'Internal padding size',
     },
-    onClick: {
-      type: 'function',
-      description: 'Click handler - makes card interactive',
+    as: {
+      type: 'enum',
+      values: ['article', 'div', 'section'],
+      default: 'article',
+      description: 'Semantic HTML element for the card root',
     },
   },
 
@@ -78,7 +80,8 @@ export default defineFragment({
     propsSummary: [
       'variant: default|outlined|outline|elevated (default: default)',
       'padding: none|sm|md|lg (default: md)',
-      'onClick: () => void - makes card interactive',
+      'as: article|div|section (default: article) - card root element',
+      'onClick: (event) => void - click handler on root (semantics unchanged)',
       'Sub-components: Card.Header, Card.Title, Card.Description, Card.Body, Card.Footer',
     ],
     scenarioTags: [
@@ -156,9 +159,9 @@ export default defineFragment({
     },
     {
       name: 'Interactive',
-      description: 'Clickable card',
+      description: 'Clickable card surface (root stays a semantic container)',
       render: () => (
-        <Card onClick={() => alert('Card clicked!')}>
+        <Card as="section" onClick={() => alert('Card clicked!')}>
           <Card.Header>
             <Card.Title>Click Me</Card.Title>
             <Card.Description>This card is interactive</Card.Description>
@@ -167,6 +170,18 @@ export default defineFragment({
         </Card>
       ),
     },
+    {
+      name: 'Section Root',
+      description: 'Use the as prop to match the surrounding document semantics',
+      render: () => (
+        <Card as="section" aria-labelledby="billing-card-title">
+          <Card.Header>
+            <Card.Title id="billing-card-title">Billing Summary</Card.Title>
+          </Card.Header>
+          <Card.Body>Section semantics can improve document structure for grouped content.</Card.Body>
+        </Card>
+      ),
+    },
     {
       name: 'With Footer',
       description: 'Card with header, body, and footer',

package/src/components/Card/Card.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 .card {
   @include surface-elevated;
@@ -30,15 +30,15 @@
 }
 
 .paddingSm {
-  padding: var(--fui-padding-container-sm, $fui-padding-container-sm);
+  padding: var(--fui-space-1, $fui-space-1);
 }
 
 .paddingMd {
-  padding: var(--fui-padding-container-md, $fui-padding-container-md);
+  padding: var(--fui-space-2, $fui-space-2);
 }
 
 .paddingLg {
-  padding: var(--fui-padding-container-lg, $fui-padding-container-lg);
+  padding: var(--fui-space-4, $fui-space-4);
 }
 
 // Interactive card (when onClick is provided)
@@ -64,7 +64,7 @@
 }
 
 .header {
-  margin-bottom: var(--fui-space-3, $fui-space-3);
+  margin-bottom: var(--fui-space-2, $fui-space-2);
 }
 
 .title {
@@ -92,8 +92,8 @@
   display: flex;
   align-items: center;
   gap: var(--fui-space-2, $fui-space-2);
-  margin-top: var(--fui-space-4, $fui-space-4);
-  padding-top: var(--fui-space-4, $fui-space-4);
+  margin-top: var(--fui-space-2, $fui-space-2);
+  padding-top: var(--fui-space-2, $fui-space-2);
   border-top: 1px solid var(--fui-border, $fui-border);
 }
 

package/src/components/Card/Card.test.tsx

@@ -8,10 +8,9 @@ describe('Card', () => {
     expect(screen.getByRole('article')).toBeInTheDocument();
   });
 
-  it('renders as <button> when onClick is provided', () => {
+  it('stays as <article> with interactive class when onClick is provided', () => {
     render(<Card onClick={() => {}}>Click me</Card>);
-    expect(screen.getByRole('button')).toBeInTheDocument();
-    expect(screen.queryByRole('article')).not.toBeInTheDocument();
+    expect(screen.getByRole('article')).toHaveClass('interactive');
   });
 
   it('applies variant classes', () => {
@@ -31,7 +30,7 @@ describe('Card', () => {
     const handleClick = vi.fn();
     const user = userEvent.setup();
     render(<Card onClick={handleClick}>Click me</Card>);
-    await user.click(screen.getByRole('button'));
+    await user.click(screen.getByRole('article'));
     expect(handleClick).toHaveBeenCalledTimes(1);
   });
 
@@ -54,7 +53,7 @@ describe('Card', () => {
 
   it('adds interactive class when onClick is provided', () => {
     render(<Card onClick={() => {}}>Content</Card>);
-    expect(screen.getByRole('button')).toHaveClass('interactive');
+    expect(screen.getByRole('article')).toHaveClass('interactive');
   });
 
   it('resolves variant="outline" to "outlined"', () => {