@usefragments/ui 1.0.0

package/src/components/Chip/Chip.contract.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Chip",
+  "description": "Interactive pill-shaped element for filtering, selecting, and tagging. Supports single and multi-select via Chip.Group.",
+  "category": "forms",
+  "tags": [
+    "chip",
+    "tag",
+    "filter",
+    "selection",
+    "multi-select",
+    "action"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Chip/index.tsx",
+  "exportName": "Chip",
+  "propsSummary": [
+    "children: node (required)",
+    "variant: filled|outlined|outline|soft (default: filled)",
+    "size: xs|sm|md|lg (default: md)",
+    "selected: boolean (default: false)",
+    "icon: node",
+    "avatar: node",
+    "onRemove: function",
+    "value: string",
+    "disabled: boolean (default: false)",
+    "onClick: function"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Chip label text",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style variant",
+      "default": "filled",
+      "required": false,
+      "values": [
+        "filled",
+        "outlined",
+        "outline",
+        "soft"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Chip size",
+      "default": "md",
+      "required": false,
+      "values": [
+        "xs",
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "selected": {
+      "type": "boolean",
+      "description": "Whether the chip is in a selected state",
+      "default": "false",
+      "required": false
+    },
+    "icon": {
+      "type": "node",
+      "description": "Icon element rendered before the label",
+      "required": false
+    },
+    "avatar": {
+      "type": "node",
+      "description": "Avatar element rendered before the label",
+      "required": false
+    },
+    "onRemove": {
+      "type": "function",
+      "description": "Makes chip removable. Called when X is clicked.",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "description": "Value identifier used by Chip.Group for selection tracking",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "",
+      "default": "false",
+      "required": false
+    },
+    "onClick": {
+      "type": "function",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Filtering content by categories or tags",
+      "Multi-select scenarios like choosing interests or skills",
+      "Toggling options in a compact pill-shaped control",
+      "Displaying removable user-applied filters"
+    ],
+    "whenNot": [
+      "Display-only status labels (use Badge)",
+      "Navigation between views (use Tabs)",
+      "Binary on/off state (use Switch)",
+      "Primary call-to-action (use Button)"
+    ],
+    "guidelines": [
+      "Keep chip labels short (1-3 words)",
+      "Use Chip.Group for multi-select sets with shared state",
+      "Use onRemove only when users should be able to dismiss the chip",
+      "Pair avatar chips with user-related selections (assignees, reviewers)",
+      "Provide an explicit value on Chip when using non-string/custom JSX children inside Chip.Group"
+    ],
+    "accessibility": [
+      "Chips are buttons and use aria-pressed for selection state",
+      "Chip.Group is a grouping wrapper; add role/aria-label when needed for assistive context",
+      "Remove buttons include descriptive aria-label with chip text",
+      "Disabled chips are properly excluded from interaction"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic filled chip",
+      "code": "<Chip>Default</Chip>"
+    },
+    {
+      "name": "Outline",
+      "description": "Chip with border using the \"outline\" alias for \"outlined\"",
+      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip variant=\"outline\">Outline</Chip>\n  <Chip variant=\"outline\" selected>Outline Selected</Chip>\n</div>"
+    },
+    {
+      "name": "Selected",
+      "description": "Chip in selected state across variants",
+      "code": "<div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>\n  <Chip selected>Filled</Chip>\n  <Chip variant=\"outlined\" selected>Outlined</Chip>\n  <Chip variant=\"soft\" selected>Soft</Chip>\n</div>"
+    },
+    {
+      "name": "With Avatar",
+      "description": "Chip with a leading avatar image",
+      "code": "<Chip avatar={<img src=\"https://i.pravatar.cc/32?u=chip\" alt=\"\" />}>\n  Jane Doe\n</Chip>"
+    },
+    {
+      "name": "With Remove",
+      "description": "Removable chip with dismiss button",
+      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip onRemove={() => {}}>React</Chip>\n  <Chip onRemove={() => {}}>TypeScript</Chip>\n  <Chip onRemove={() => {}}>SCSS</Chip>\n</div>"
+    },
+    {
+      "name": "Chip Group",
+      "description": "Multi-select chip set with shared state",
+      "code": "<Chip.Group defaultValue={['react']}>\n  <Chip value=\"react\">React</Chip>\n  <Chip value=\"vue\">Vue</Chip>\n  <Chip value=\"angular\">Angular</Chip>\n  <Chip value=\"svelte\">Svelte</Chip>\n</Chip.Group>"
+    },
+    {
+      "name": "Chip Group with Custom Labels",
+      "description": "Use explicit values when chip labels are custom JSX",
+      "code": "<Chip.Group aria-label=\"Assignees\">\n  <Chip value=\"jane\">\n    <span>Jane Doe</span>\n  </Chip>\n  <Chip value=\"sam\">\n    <span>Sam Lee</span>\n  </Chip>\n</Chip.Group>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Chip in disabled state",
+      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip disabled>Disabled</Chip>\n  <Chip disabled selected>Disabled Selected</Chip>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Badge",
+      "relationship": "sibling",
+      "note": "Badge is display-only; Chip is interactive"
+    },
+    {
+      "component": "ToggleGroup",
+      "relationship": "alternative",
+      "note": "Use ToggleGroup for mutually exclusive options"
+    },
+    {
+      "component": "Button",
+      "relationship": "alternative",
+      "note": "Use Button for primary actions, Chip for selection/filtering"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - chip label (required)",
+      "variant: filled|outlined|outline|soft - visual style",
+      "size: sm|md - chip size",
+      "selected: boolean - selection state",
+      "icon/avatar: ReactNode - leading visual",
+      "onRemove: () => void - makes chip removable",
+      "value: string - identifier for Chip.Group",
+      "Chip.Group forwards DOM props (id, role, aria-*, data-*, handlers)",
+      "Chip.Group: non-string chip labels should set an explicit value"
+    ],
+    "a11yRules": [
+      "A11Y_CHIP_SELECTION",
+      "A11Y_CHIP_DISMISS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Group"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:54.270Z"
+  }
+}

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

@@ -0,0 +1,265 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.chip {
+  @include button-reset;
+  @include interactive-base;
+
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  line-height: 1;
+  white-space: nowrap;
+  user-select: none;
+}
+
+.withRemove {
+  border-top-right-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+// Sizes
+.xs {
+  min-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 {
+  min-height: var(--fui-button-height-sm, $fui-button-height-sm);
+  padding: 0 var(--fui-space-2, $fui-space-2);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.md {
+  min-height: var(--fui-button-height-md, $fui-button-height-md);
+  padding: 0 var(--fui-space-3, $fui-space-3);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+}
+
+.lg {
+  min-height: var(--fui-button-height-lg, $fui-button-height-lg);
+  padding: 0 var(--fui-space-4, $fui-space-4);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+// Variants
+.filled {
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  color: var(--fui-text-primary, $fui-text-primary);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+
+  &.selected {
+    background-color: var(--fui-color-accent, $fui-color-accent);
+    color: var(--fui-color-on-accent, $fui-color-on-accent);
+
+    &:hover:not(:disabled) {
+      background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    }
+
+    &:active:not(:disabled) {
+      background-color: var(--fui-color-accent-active, $fui-color-accent-active);
+    }
+  }
+}
+
+.outlined {
+  background-color: transparent;
+  color: var(--fui-text-primary, $fui-text-primary);
+  border: 1px solid var(--fui-border, $fui-border);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    border-color: var(--fui-border-strong, $fui-border-strong);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+
+  &.selected {
+    background-color: var(--fui-color-accent, $fui-color-accent);
+    color: var(--fui-color-on-accent, $fui-color-on-accent);
+    border-color: var(--fui-color-accent, $fui-color-accent);
+
+    &:hover:not(:disabled) {
+      background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+      border-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    }
+
+    &:active:not(:disabled) {
+      background-color: var(--fui-color-accent-active, $fui-color-accent-active);
+      border-color: var(--fui-color-accent-active, $fui-color-accent-active);
+    }
+  }
+}
+
+.soft {
+  background-color: var(--fui-color-info-bg, $fui-color-info-bg);
+  color: var(--fui-color-info-text, $fui-color-info-text);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+
+  &.selected {
+    background-color: var(--fui-color-accent, $fui-color-accent);
+    color: var(--fui-color-on-accent, $fui-color-on-accent);
+
+    &:hover:not(:disabled) {
+      background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+    }
+
+    &:active:not(:disabled) {
+      background-color: var(--fui-color-accent-active, $fui-color-accent-active);
+    }
+  }
+}
+
+// Avatar slot
+.avatar {
+  display: flex;
+  align-items: center;
+  margin-left: calc(-1 * var(--fui-space-1, $fui-space-1));
+
+  img {
+    width: var(--fui-icon-md, $fui-icon-md);
+    height: var(--fui-icon-md, $fui-icon-md);
+    border-radius: var(--fui-radius-full, $fui-radius-full);
+    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);
+      height: var(--fui-icon-sm, $fui-icon-sm);
+    }
+  }
+}
+
+// Icon slot
+.icon {
+  display: flex;
+  align-items: center;
+}
+
+// Remove button
+.removableChip {
+  display: inline-flex;
+  align-items: stretch;
+}
+
+.remove {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0 var(--fui-space-1, $fui-space-1);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: 1;
+  border-top-right-radius: var(--fui-radius-full, $fui-radius-full);
+  border-bottom-right-radius: var(--fui-radius-full, $fui-radius-full);
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+  background-color: transparent;
+  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);
+  }
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+}
+
+// Match remove button visuals to chip variant/state so the compound control
+// remains visually coherent across seeds/themes.
+.filled + .remove {
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.outlined + .remove {
+  background-color: transparent;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.soft + .remove {
+  background-color: var(--fui-color-info-bg, $fui-color-info-bg);
+  color: var(--fui-color-info-text, $fui-color-info-text);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.selected + .remove {
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-color-on-accent, $fui-color-on-accent);
+  border-left-color: transparent;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+
+  &:active:not(:disabled) {
+    background-color: var(--fui-color-accent-active, $fui-color-accent-active);
+  }
+}
+
+// Chip.Group
+.group {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--fui-space-2, $fui-space-2);
+}

package/src/components/Chip/Chip.stories.tsx

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Chip } from '.';
+
+/**
+ * Interactive pill-shaped element for filtering, selecting, and tagging.
+ * Supports selected state, removable chips via onRemove, and multi-select
+ * sets through Chip.Group.
+ */
+const meta = {
+  title: 'Forms/Chip',
+  component: Chip,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Interactive pill for filtering, selecting, and tagging.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['filled', 'outlined', 'outline', 'soft'],
+      description: 'Visual style variant',
+    },
+    size: {
+      control: 'select',
+      options: ['xs', 'sm', 'md', 'lg'],
+      description: 'Chip size',
+    },
+    selected: { control: 'boolean', description: 'Selection state' },
+    disabled: { control: 'boolean' },
+  },
+  args: { variant: 'filled', size: 'md', children: 'Default' },
+} satisfies Meta<typeof Chip>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { children: 'Default' },
+};
+
+export const Outline: Story = {
+  args: { variant: 'outline', children: 'Outline' },
+};
+
+export const Selected: Story = {
+  args: { variant: 'soft', selected: true, children: 'Selected' },
+};
+
+export const Removable: Story = {
+  args: { children: 'TypeScript', onRemove: () => {} },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, selected: true, children: 'Disabled' },
+};
+
+export const Group: Story = {
+  render: () => (
+    <Chip.Group defaultValue={['react']}>
+      <Chip value="react">React</Chip>
+      <Chip value="vue">Vue</Chip>
+      <Chip value="angular">Angular</Chip>
+      <Chip value="svelte">Svelte</Chip>
+    </Chip.Group>
+  ),
+};