# UDS Components

## MCP tool usage

- Always fetch components type definition using the UDS MCP server
- Always fetch the possible components from UDS using the UDS MCP server
- Before using any component, fetch its type definition and documentation examples via the MCP server
- Use `get_components` to retrieve the full list of exported UDS components
- Use `get_component_documentation_examples` with a component name (e.g., "tooltip", "toast") to fetch usage docs and examples
- Use `get_documentation` with path "core-concepts/elevation" for detailed elevation guidance

## Never rebuild existing UDS primitives

- Before building ANY custom tooltip, toast, notification, popover, dropdown, select, dialog, modal, drawer, sheet, accordion, tabs, alert, snackbar, or banner, call `get_components` first to check if UDS already exports it
- If a matching component exists, use it and call `get_component_documentation_examples` to learn its API
- Never recreate functionality that UDS provides — only create custom components when UDS doesn't offer the needed functionality

## Use UDS components instead of raw HTML

- Always use UDS UI library components instead of raw HTML tags
- Use `<Text>` instead of `<p>`, `<span>`, `<h1>`–`<h6>`
- Use `<Button>` instead of `<button>`
- Use `<Input>` instead of `<input>`
- Use `<Checkbox>` instead of `<input type="checkbox">`
- Use `<Radio>` instead of `<input type="radio">`
- Use `<Switch>` instead of custom toggle components
- Use `<Link>` instead of `<a>`
- Use `<Icon>` instead of SVG elements
- Use `<Tooltip>`, `<TooltipTrigger>`, `<TooltipContent>` instead of custom tooltip implementations
- Use `createToast()` from `@yahoo/uds` instead of custom toast/notification components

## Box constraints

- `<Box>` has `display="flex"` by default — use `<VStack>` for vertical stacking, `<HStack>` for horizontal, or `<div>` for simple containers
- Always set an explicit `display` prop on every `<Box>` (`display="block"` or `display="flex"`). Omitting it causes broken UI.
- `<Box>` does NOT have a `gap` prop — use `rowGap` or `columnGap` instead. Only `<HStack>` and `<VStack>` have `gap`.
- Every `<Box>` with `flexDirection="column"` must have `rowGap` specified. Every `<Box>` with `flexDirection="row"` must have `columnGap` specified if spacing between children is needed. The `spacing` prop is for padding only, not gaps.

## HStack and VStack constraints

- Always set `alignItems` and `justifyContent` on every `<HStack>` and `<VStack>` — never rely on default flex behavior
- Flexbox alignment values must use full CSS syntax: `"flex-start"` not `"start"`, `"flex-end"` not `"end"`
- Valid `justifyContent` values: `"flex-start"` | `"flex-end"` | `"center"` | `"space-between"` | `"space-around"` | `"space-evenly"`
- Valid `alignItems` values: `"flex-start"` | `"flex-end"` | `"center"` | `"baseline"` | `"stretch"`

## Styling rules

- Box, HStack, and VStack provide TypeScript props for all styling — prefer using props (`backgroundColor`, `spacing`, `borderRadius`, etc.) over Tailwind `className` for UDS design tokens
- Never override styling properties on components that use `size` and `variant` props (Button, IconButton, Chip, Badge, Avatar, Radio, Checkbox, Menu, Divider, Switch) with Tailwind classes — always use only the available `size` and `variant` options
- When placing fixed-size components (Button, IconButton, Chip, Badge, Avatar) in a horizontal flex container, add `className="shrink-0"` to prevent them from being compressed
