# Hover Design System

> Hover's design system for building consistent product UI. Built on React and
> Chakra UI v2, with design tokens, components, hooks, and patterns. All imports
> come from `@hoverinc/design-system-react-web`. Never import directly from
> `@chakra-ui/react`.

> **Working in React Native?** This file documents the web build only — see
> the [React Native artifact](/llms-rn.txt) instead.

## Setup

- Package: `@hoverinc/design-system-react-web`
- Icons: `@hoverinc/icons`
- Theme: `@hoverinc/blueprint-theme`

```tsx
import { DesignSystemProvider } from '@hoverinc/design-system-react-web';

function App() {
  return (
    <DesignSystemProvider>
      <YourApp />
    </DesignSystemProvider>
  );
}
```

| Import path                                    | Purpose                                           |
| ---------------------------------------------- | ------------------------------------------------- |
| `@hoverinc/design-system-react-web`            | Components, hooks, types                          |
| `@hoverinc/design-system-react-web/foundation` | Foundation theme tokens                           |
| `@hoverinc/design-system-react-web/brand`      | Brand-specific components (Button, Link, Spinner) |
| `@hoverinc/design-system-react-web/chakra`     | Raw Chakra re-exports (avoid unless necessary)    |

## Design Tokens

Use string token keys as prop values — never raw pixel or hex values.

- Spacing: `padding="400"` (16px), `gap="300"` (12px)
- Sizes: `width="500"` (64px), `height="400"` (48px)
- Colors: prefer semantic tokens (for example `color="textPrimary"`)
- Shadows: `boxShadow="distance200"`
- Border radius: `borderRadius="500"` (8px)

Prefer semantic color tokens first (for text, surfaces, borders, status UI). Use
scale tokens like `primary.100`/`primary.600` only when a semantic token is not
available. Available color scales: `primary`, `neutral`, `success`, `warning`,
`danger`. Brand colors: `brandNavy`, `brandGreen`, `brandBrown`, `brandRed`,
`brandTan`, `brandOrange`, `brandYellow`, `brandPurple`.

For the full token reference, read `/llms/foundation.md`.

## Style Props

Prefer verbose prop names over shorthand:

| Prefer                      | Avoid           |
| --------------------------- | --------------- |
| `padding`                   | `p`             |
| `paddingX` / `paddingY`     | `px` / `py`     |
| `margin`, `marginTop`, etc. | `m`, `mt`, etc. |
| `width` / `height`          | `w` / `h`       |
| `backgroundColor`           | `bg`            |
| `borderRadius`              | `rounded`       |

## Components

### Layout

`Box`, `Flex`, `Grid`, `SimpleGrid`, `Stack`, `HStack`, `VStack`, `Center`,
`Container`, `Spacer`, `Wrap`, `AspectRatio`

### Forms

`Button`, `IconButton`, `Field`, `TextInput`, `PasswordInput`, `SearchInput`,
`Select`, `Textarea`, `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`,
`RadioButton`, `RadioButtonGroup`, `CheckButton`, `CheckButtonGroup`,
`TileCheckbox`, `TileRadio`, `Toggle`, `Slider`, `PinInput`, `Editable`

### Overlays

`Sheet`, `Popover`, `PopoverButton`, `Tooltip`, `Menu`, `MenuButton`,
`MenuItem`, `FilterMenu`, `LoadingOverlay`, `LoadingState`

These overlays are deprecated and strongly discouraged: `Modal`, `Dialog`,
`Drawer`,

### Feedback

`Progress`, `FauxProgress`, `Loader`, `Spinner`, `Skeleton`, `Alert`, `Toast`

### Data Display

`Accordion`, `Badge`, `Tag`, `Table`, `List`, `Tile`, `Gallery`

### Typography

`Heading`, `Body`, `Code`, `Blockquote`

### Navigation

`Tabs`, `Breadcrumb`, `Link`, `LinkOverlay`

### Media

`Icon`, `Pictogram`, `Avatar`, `AvatarGroup`, `Image`, `Logo`

### Utility

`Portal`, `Fade`, `ScaleFade`, `Slide`, `SlideFade`, `Hide`, `Show`,
`ForceMode`, `VisuallyHidden`

## Hooks

| Hook                          | Purpose                                          |
| ----------------------------- | ------------------------------------------------ |
| `useDisclosure`               | Boolean open/close state (modals, drawers, etc.) |
| `useToast` / `useCustomToast` | Show toast notifications                         |
| `useBreakpointValue`          | Responsive values based on viewport              |
| `useColorMode`                | Access/toggle light/dark mode                    |
| `useTheme`                    | Access theme object                              |
| `useField`                    | Field-level form utilities                       |
| `useIsMotionReduced`          | Check prefers-reduced-motion                     |
| `useMediaQuery`               | Match CSS media queries                          |
| `useBoolean`                  | Boolean state helpers                            |
| `useClipboard`                | Copy to clipboard                                |

## Common Patterns

### Responsive values

Use device breakpoints only: `base`, `tablet`, `desktop`. Prefer `tablet` for
responsive overrides. Use `desktop` only as a last resort for layouts that
cannot be solved at `base` + `tablet`. Do not use generic aliases like `md` or
`lg`. In rare cases that need finer control, use explicit `width*` breakpoints
(for example `width350`) instead of `md`/`lg`.

```tsx
<Box padding={{ base: '200', tablet: '400' }}>Responsive padding</Box>
```

### Disclosure (open/close state)

```tsx
const { isOpen, onOpen, onClose } = useDisclosure();
<Button onClick={onOpen}>Open</Button>
<Sheet isOpen={isOpen} onClose={onClose} header="Title">...</Sheet>
```

## Common Mistakes to Avoid

- Don't import from `@chakra-ui/react` — always use
  `@hoverinc/design-system-react-web`
- Don't use raw pixel values — use token strings (`"400"` not `"16px"`)
- Don't use shorthand style props — use `padding` not `p`, `marginX` not `mx`
- Don't default to scale colors like `primary.100` — prefer semantic color
  tokens first
- Don't use `md`/`lg` responsive keys — use `base`, `tablet`, `desktop` (or
  `width*` keys for rare fine-grained layouts)
- Don't use `leftIcon`/`rightIcon` on Button — use `iconBefore`/`iconAfter`
- Don't use `colorScheme` — use the `color` prop
- Don't forget `label` on `IconButton` — required for accessibility
- Don't nest `DesignSystemProvider` — it's a no-op
- Don't use fontSize tokens directly - use size prop on Body and Heading instead

## Detailed References

- [Foundation](/llms/foundation.md): Foundation overview
- [Responsive Breakpoints](/llms/foundation/tokens/breakpoints.md): Responsive breakpoint tokens for media queries etc.
- [Color](/llms/foundation/tokens/color.md): Color tokens
- [Favicon](/llms/foundation/tokens/favicon.md): Favicon
- [Grids](/llms/foundation/tokens/grids.md): Grids
- [Icons](/llms/foundation/tokens/icons.md): Icon usage and available icons
- [Layers](/llms/foundation/tokens/layers.md): Layer style tokens
- [Logo](/llms/foundation/tokens/logos.md): Logo usage and variants
- [Radius](/llms/foundation/tokens/radius.md): Border tokens
- [Shadow](/llms/foundation/tokens/shadow.md): Shadow and outline tokens
- [Size tokens](/llms/foundation/tokens/size.md): Size tokens
- [Spacing tokens](/llms/foundation/tokens/space.md): Spacing tokens
- [Typography](/llms/foundation/tokens/typography.md): Typography tokens
- [Components](/llms/components.md): Components overview
- [Accordion](/llms/components/data-display/accordion.md): Accordion component
- [Badge](/llms/components/data-display/badge.md): Badge component
- [Gallery](/llms/components/data-display/gallery.md): Image gallery component that displays image thumbnails in a grid and full size images in a modal.
- [List](/llms/components/data-display/list.md): List is used to display list items.
- [Table](/llms/components/data-display/table.md): A Table used to organize and display data efficiently. It renders a `<table>` element by default.
- [Tile](/llms/components/data-display/tile.md): A Tile used to display things like paint or material swatches, or anything that requires an image with subtext.
- [Alert](/llms/components/feedback/alert.md): Alert component
- [Faux Progress](/llms/components/feedback/faux-progress.md): Faux Progress is used to display the progress status for a task that takes a long time. This differs from the default Progress component because we simulate progress given a duration.
- [Loader](/llms/components/feedback/loader.md): A loading indicator is used to convey the state of action that is processing or waiting a result.
- [LoadingOverlay](/llms/components/feedback/loading-overlay.md): A modal loading overlay that blocks all user interaction while displaying a spinner.
- [LoadingState](/llms/components/feedback/loading-state.md): A loading overlay that blocks user interaction on a specific element while displaying a spinner.
- [Progress](/llms/components/feedback/progress.md): Progress is used to display the progress status for a task that takes a long time or consists of several steps.
- [Skeleton](/llms/components/feedback/skeleton.md): A loading state for a component to display an animated placeholder in place of the component, to convey data is being fetched and prevent layout shift.
- [Toast](/llms/components/feedback/toast.md): Toasts are used to show alerts on top of an overlay, usually used to give feedback to users after an action has taken place.

- [BinaryButton](/llms/components/forms/binary-button.md): Selectable tile button
- [Buttons](/llms/components/forms/button.md): Use buttons to let users perform key actions tied to what they see—submitting a form, opening a modal, or editing content.
- [CheckButton](/llms/components/forms/check-button.md): Selectable button for multiple selection
- [Checkbox](/llms/components/forms/checkbox.md): Checkbox component
- [Dropdown](/llms/components/forms/dropdown.md): An accessible, custom alternative to the native Select component
- [Field](/llms/components/forms/field.md): A comprehensive input field component for React Native with label, validation, and addon support
- [IconButton](/llms/components/forms/icon-button.md): Button component that uses an icon for its label
- [PinInput](/llms/components/forms/pin-input.md): Pin Input component for entering a sequence of digits
- [RadioButton](/llms/components/forms/radio-button.md): Selectable button for single selection
- [Radio](/llms/components/forms/radio.md): Radio component
- [SearchInput](/llms/components/forms/search-input.md): Search field with optional toggleable UI and clear button behaviors
- [Select](/llms/components/forms/select.md): Select component
- [Slider](/llms/components/forms/slider.md): Select component
- [TextInput](/llms/components/forms/text-input.md): Text Input component
- [Textarea](/llms/components/forms/textarea.md): Textarea component
- [Toggle](/llms/components/forms/toggle.md): A toggle component to set on or off state
- [Avatar](/llms/components/media/avatar.md): Display photo of a user, or their initials, on a background
- [Icon](/llms/components/media/icon.md): Display an icon using system colors and sizing
- [Pictogram](/llms/components/media/pictogram.md): Display larger iconography, called pictograms, using system colors and sizing
- [Aspect Ratio](/llms/components/layout/aspect-ratio.md): AspectRatio component is used to embed responsive videos and maps, etc.
- [Box](/llms/components/layout/box.md): Box is the most abstract component on top of which all other Chakra UI components are built. By default, it renders a `div` element
- [Center](/llms/components/layout/center.md): Center is a layout component that centers its child within itself.
- [Container](/llms/components/layout/container.md): Containers are used to constrain a content's width to the current breakpoint, while keeping it fluid.
- [Flex](/llms/components/layout/flex.md): Flex is Box with display set to flex and comes with helpful style shorthand. It renders a `div` element.
- [Grid](/llms/components/layout/grid.md): A responsive grid layout component for React Native
- [PageContainer](/llms/components/layout/page-container.md): PageContainer sets a standardized max width and horizontal padding for page content.
- [SimpleGrid](/llms/components/layout/simple-grid.md): SimpleGrid provides a friendly interface to create responsive grid layouts with ease.
- [Stack](/llms/components/layout/stack.md): Stack is a layout component used to group elements together and apply a space between them.
- [Menu](/llms/components/overlay/menu.md): An accessible dropdown menu for the common dropdown menu button design pattern. Menu uses roving tabIndex for focus management.
- [Popover](/llms/components/overlay/popover.md): Popover is a non-modal dialog that floats around a trigger.
- [Sheet](/llms/components/overlay/sheet.md): A responsive overlay component optimized for mobile devices
- [Tooltip](/llms/components/overlay/tooltip.md): Tooltip component
- [Breadcrumb](/llms/components/navigation/breadcrumb.md): Breadcrumbs is a navigation pattern that helps users understand the hierarchy of a website.
- [Link Overlay](/llms/components/navigation/link-overlay.md): Link overlay is a semantic component used to wrap elements (cards, blog posts, articles, etc.) in a link.
- [Link](/llms/components/navigation/link.md): A link component that renders a native anchor tag with system styles.
- [Tabs](/llms/components/navigation/tabs.md): A React component that helps you build accessible tabs, by providing keyboard interactions and ARIA attributes described in the WAI-ARIA Tab Panel Design Pattern.
- [FocusLock](/llms/components/other/focus-lock.md): Lock focus to a particular element in the document
- [Portal](/llms/components/other/portal.md): Renders a component outside the current DOM hierarchy.
- [RemoveScroll](/llms/components/other/remove-scroll.md): Disable document scroll when a component is mounted
- [Visually Hidden](/llms/components/other/visually-hidden.md): VisuallyHidden is a common technique used in web accessibility to hide content from the visual client, but keep it readable for screen readers.
- [Body](/llms/components/typography/body.md): A typography primitiving for displaying text and paragraphs in an interface.
- [Code](/llms/components/typography/code.md): A typography primitiving for displaying inline code snippets with a monospace font.
- [Heading](/llms/components/typography/heading.md): A typography primitive for ensuring consistent heading styles and hierarchy
- [Drawer (Deprecated)](/llms/engineering/deprecated/drawer.md): Drawer component
- [Modal (Deprecated)](/llms/engineering/deprecated/modal.md): Modal component
- [Getting Started with Bootstrap](/llms/engineering/getting-started/bootstrap.md): A guide for installing and using the Hover Design System Bootstrap theme
- [Getting Started with React Native](/llms/engineering/getting-started/react-native.md): A guide for installing and setting up Hover Design System in React Native projects
- [Getting Started with React](/llms/engineering/getting-started/react.md): A guide for installing and setting up Blueprint in React projects
- [Stripe Integration](/llms/engineering/integrations/stripe.md): Integrating Stripe payments with the design system
- [Design System Provider](/llms/engineering/provider/design-system-provider.md): The root provider that injects the theme and other global configurations.
- [useBoolean](/llms/engineering/hooks/use-boolean.md): React hook to manage boolean (on - off) states
- [useBreakpointValue](/llms/engineering/hooks/use-breakpoint-value.md): React hook for getting the value for the current breakpoint from the provided responsive values object.
- [useClipboard](/llms/engineering/hooks/use-clipboard.md): useClipboard is a custom hook that handles copying content to clipboard.
- [useConst](/llms/engineering/hooks/use-const.md): React hook to initialize and return a constant value
- [useControllableState](/llms/engineering/hooks/use-controllable-state.md): React hook to handle controlled vs uncontrolled component scenarios
- [useDimensions](/llms/engineering/hooks/use-dimensions.md): React hook to measure dimensions of the referenced element
- [useDisclosure](/llms/engineering/hooks/use-disclosure.md): React hook to handle common open and close scenarios in UI components
- [useIsMotionReduced](/llms/engineering/hooks/use-is-motion-reduced.md): React hook to detect animation preference
- [useLatestCallback](/llms/engineering/hooks/use-latest-callback.md): A version of React's useCallback that always has the latest render scope
- [useMediaQuery](/llms/engineering/hooks/use-media-query.md): React hook to detect media queries
- [useMergeRefs](/llms/engineering/hooks/use-merge-refs.md): React hook that merges react refs into a single memoized function
- [useTheme](/llms/engineering/hooks/use-theme.md): React hook to get access to theme by reading from theme context
- [useZoom](/llms/engineering/hooks/use-zoom.md): A hook for adding scroll-based zoom functionality to an image element.
- [CSS Variables](/llms/engineering/styled-system/css-variables.md): CSS variables automatically generated from the system theme
- [Custom Styles](/llms/engineering/styled-system/custom-styles.md): Conventions for applying custom styles to system components
- [System Factory](/llms/engineering/styled-system/factory.md): Using the system factory and elements
- [Gradient](/llms/engineering/styled-system/gradient.md): Learn how to use gradients in Chakra UI. Gradients are a way to transition between two or more colors.
- [Motion](/llms/engineering/styled-system/motion.md): Motion tokens for animations, transitions
- [Style Props](/llms/engineering/styled-system/style-props.md): Learn how to use style props in Chakra UI. Style props are a way to alter the style of a component by simply passing props to it
- [The `sx` Prop](/llms/engineering/styled-system/the-sx-prop.md): The sx prop lets you style components inline, using your theme tokens.
- [Data Display](/llms/patterns/data-display.md): Patterns
- [Feedback](/llms/patterns/feedback.md): Patterns
- [Forms](/llms/patterns/forms.md): Patterns
- [Layout](/llms/patterns/layout.md): Patterns
- [Media](/llms/patterns/media.md): Patterns
- [Navigation](/llms/patterns/navigation.md): Patterns
- [Overlay](/llms/patterns/overlay.md): Patterns
- [Typography](/llms/patterns/typography.md): Patterns