docs: update guides for ButtonGroup, DataTable flush, FilterPill forwardRef

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -23,7 +23,7 @@ Always read `COMPONENT_GUIDE.md` before building any UI feature. It contains dec
 - No inline styles except dynamic values (width from props, etc.)
 
 ### Components
-- `forwardRef` on all form controls (Input, Textarea, Select, Checkbox, Toggle, Label)
+- `forwardRef` on all form controls (Input, Textarea, Select, Checkbox, Toggle, Label, FilterPill)
 - Every component accepts a `className` prop
 - Semantic color variants: `'success' | 'warning' | 'error'` pattern
 - Barrel exports: `src/design-system/primitives/index.ts` and `src/design-system/composites/index.ts`

COMPONENT_GUIDE.md

@@ -73,6 +73,9 @@
 - Single user avatar → **Avatar**
 - Stacked user avatars → **AvatarGroup**
 
+### "I need to group buttons"
+- Connected button strip (toggle group, segmented control) → **ButtonGroup** (horizontal or vertical)
+
 ### "I need filtering"
 - Filter pill/chip → **FilterPill**
 - Full filter bar with search → **FilterBar**
@@ -148,12 +151,13 @@ URL-driven progressive filtering: /agents → /agents/:appId → /agents/:appId/
 | BarChart | composite | Categorical data comparison, optional stacking |
 | Breadcrumb | composite | Navigation path showing current location |
 | Button | primitive | Action trigger (primary, secondary, danger, ghost) |
+| ButtonGroup | primitive | Groups buttons into a connected strip with shared borders (horizontal/vertical) |
 | Card | primitive | Content container with optional accent border |
 | Checkbox | primitive | Boolean input with label |
 | CodeBlock | primitive | Syntax-highlighted code/JSON display |
 | Collapsible | primitive | Single expand/collapse section |
 | CommandPalette | composite | Full-screen search and command interface |
-| DataTable | composite | Sortable, paginated data table with row actions |
+| DataTable | composite | Sortable, paginated data table with row actions. Use `flush` prop when embedded inside a container that provides its own border/radius |
 | DateRangePicker | primitive | Date range selection with presets |
 | DateTimePicker | primitive | Single date/time input |
 | DetailPanel | composite | Slide-in side panel with tabs |
@@ -162,7 +166,7 @@ URL-driven progressive filtering: /agents → /agents/:appId → /agents/:appId/
 | EventFeed | composite | Chronological event log with severity |
 | FilterBar | composite | Search + filter controls for data views |
 | GroupCard | composite | Card with header, meta row, children, and optional footer/alert. Used for grouping instances by application. |
-| FilterPill | primitive | Individual filter chip (active/inactive) |
+| FilterPill | primitive | Individual filter chip (active/inactive), supports forwardRef |
 | FormField | primitive | Wrapper adding label, hint, error to any input |
 | InfoCallout | primitive | Inline contextual note with variant colors |
 | Input | primitive | Single-line text input with optional icon |