# Contrast Orb

> A picture of contrast in light and dark: an orb cut into a light half and a dark half, with letters on each.

- Name: `contrast-orb`
- Status: beta
- Categories: contrast, theme, dark mode, accessibility
- Files: the install writes `contrast-orb.tsx`, and any part files named `contrast-orb-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- Gallery: https://arbokui.com/illustrations/contrast-orb
- Registry item: https://arbokui.com/r/contrast-orb.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the illustration. It also adds every component it uses:

   ```bash
   npx shadcn@latest add @arbokui/contrast-orb
   ```

## Use it for

- A feature section about readable color, like a theme checked for contrast in light and dark.
- Put it in a Feature Grid item's \`illustration\`, or a Bento Card's \`preview\`.
- Keep \`sample\` to two or three letters, so it fits each half.
- Write \`label\` as one sentence that says what the picture shows. Screen readers hear it in place of the drawing.

## Avoid it for

- A real light and dark switch. Use the mode control in your app.
- Proof of contrast. A picture only sets the mood. Show the checked numbers in text.

## Props

- `sample`: `string`. Default `"Aa"`. The letters on each half.
- `label`: `string`. Default `a sentence about the orb`. What the picture says, read out in its place.
- `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. The color of the moon on the ring and its glow.
- `pattern`: `boolean`. Default `true`. A field of dots behind the orb.
- `className`: `string`. Extra classes on the root.

## Accessibility

- The root is one image, named by \`label\`. The drawing and its letters are hidden from screen readers.
- Nothing inside takes focus.
- On hover the moon's glow fades up. It is a fade, so it stays with reduced motion, and it stops when motion is off.

## Examples

### The default orb

```tsx
<ContrastOrb />
```

### In your brand color

```tsx
<ContrastOrb tone="brand" label="Every color pair is checked in light and dark." />
```