# Feature Grid

> A grid of feature cells split by thin lines, each with a title, a description, and a picture above or below.

- Name: `feature-grid`
- Status: beta
- Categories: features, grid, marketing, illustrations
- Files: the install writes `feature-grid.tsx`, and any part files named `feature-grid-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- Gallery: https://arbokui.com/website/feature-grid
- Registry item: https://arbokui.com/r/feature-grid.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 website component. It also adds every component it uses:

   ```bash
   npx shadcn@latest add @arbokui/feature-grid
   ```

## Use it for

- The feature section of a landing page, under a Headline: three cells, then two wider ones.
- Give each cell an \`illustration\`. The Illustrations, like Stacked Blocks or Code Key, are made for it. Add each one by its name, like \`npx shadcn@latest add @arbokui/stacked-blocks\`, since this install does not bring them.
- Set \`span="half"\` on two cells for a row of two. Cells are a third wide by default.
- Set \`illustrationFirst\` when the picture should sit above the words, like a wide cell in the second row.
- Keep each description to two lines at 1280px. The pictures carry the rest.

## Avoid it for

- Soft cards with gaps between them. Use Bento Grid.
- Screenshots as pictures. Build them from parts, so they stay sharp and follow the theme.
- More than six cells. Split them under two Headlines.

## Props

- `title`: `ReactNode`. FeatureGridItem. What the feature is. It is an h3.
- `description`: `ReactNode`. FeatureGridItem. What it does, in a sentence or two.
- `illustration`: `ReactNode`. FeatureGridItem. A picture of the feature. It fills the room the words leave.
- `illustrationFirst`: `boolean`. Default `false`. FeatureGridItem. Put the picture above the words.
- `span`: `"third" | "half" | "full"`. Default `"third"`. FeatureGridItem. How much of a row the cell takes, from 48rem of the grid's width.
- `className`: `string`. Extra classes on the root. On FeatureGrid it holds the container query.
- `FeatureGrid`: `ComponentProps<"div">`. Part. The grid: one column when narrow, six tracks from 48rem of its own width. Put FeatureGridItems inside.

## Accessibility

- Each title is an h3, so put the grid under an h2, like a Headline.
- The Illustrations are each one image with a label, so screen readers hear a sentence per picture.
- Keep pictures free of real buttons, so nothing inside them takes focus.
- The lines between cells are outlines, so they still show in forced colors.

## Examples

### Three cells, then two, after adding the five Illustrations

```tsx
<FeatureGrid>
  <FeatureGridItem title="Each part explains itself" description="Notes on when to use each part." illustration={<StackedBlocks />} />
  <FeatureGridItem title="Checked in light and dark" description="Color pairs are tested for contrast." illustration={<ContrastOrb />} />
  <FeatureGridItem title="One theme for every part" description="Color, type, and motion from one set of tokens." illustration={<ThemeLayers />} />
  <FeatureGridItem span="half" illustrationFirst title="A size budget for each part" description="The check fails when one goes over." illustration={<SpeedGauge />} />
  <FeatureGridItem span="half" illustrationFirst title="The code is yours" description="Change anything you like." illustration={<CodeKey />} />
</FeatureGrid>
```

### Words only

```tsx
<FeatureGrid>
  <FeatureGridItem span="half" title="Checked" description="Color pairs are tested for contrast." />
  <FeatureGridItem span="half" title="Yours" description="Plain source files you can change." />
</FeatureGrid>
```