# App Grid

Canonical: https://socra.design/composed-components/app-grid

Open an app from a stable grid of recognizable icons and names.

The host supplies apps, destinations, icons and authorized activity. App Grid owns equal responsive tracks, bounded labels, accessible names and link states.

Status: ready. The specimen uses published @socra/web-ui 0.0.482. The producer passed its full Chromium and WebKit gates. Catalog browser acceptance and production adoption are tracked on issue_01m4e6431kgsk730ygf5z03xnj.

Library: @socra/web-ui

## Anatomy

- AppGrid is a named list. Its equal tracks respond to the available width without consumer layout styles.
- AppGridItem receives a full name, a recognizable non-interactive icon and a host-approved href.
- Names wrap within two lines; guidance and activity captions wrap in full. The full name remains the link’s accessible name and native tooltip; full guidance remains its accessible description.
- A canonical BadgeCount shows current authorized activity, visually capped at 99+. The accessible description retains the complete count.
- Optional description supplies brief availability or Account guidance. Loading or unavailable activity shares the caption area while preserving equal tracks and allowing rows to grow for complete guidance.
- A missing destination or disabled item remains visible as an unavailable link with no href or keyboard stop.

## States

- **Rest:** Apps retain equal geometry whether their names are short, long or unbroken.
- **Hover:** Available links use the shared neutral hover treatment.
- **Focus:** Tab reaches available links in reading order with a visible focus treatment.
- **Pressed:** Enter or pointer activation follows the host-provided native destination.
- **Selected:** An app launcher opens a destination; it does not expose a selected state.
- **Disabled:** Unavailable destinations cannot navigate or receive keyboard focus. Their explanation remains readable.
- **Loading:** Loading activity hides previous badge counts while keeping the app link usable.
- **Error:** Unavailable activity is described without implying zero unread items or disabling a valid app destination.

## Motion

The shared loading spinner honors reduced motion. Activity updates preserve the name, icon and tile geometry.

## Usage

- Keep app availability separate from activity loading. A failed count should not stop someone opening an authorized app.
- Supply only current, authorized counts. Presentation cannot establish access or selected Account context.
- Use recognizable app icons. The host owns product identity; the grid does not maintain a product-name enumeration.

## Avoid

- Do not invent destinations or unread counts. Missing destinations stay unavailable and unknown counts stay absent.
- Do not repair tile geometry in a consumer. Responsive layout, badges and long-content behavior belong to this shared contract.

## Tokens


## Example

```tsx
import { appGrid } from '@socra/web-ui';
import BookIcon from '@socra/ui-web-icon/BookIcon';

<appGrid.AppGrid label="Your apps">
  <appGrid.AppGridItem name="Atlas" icon={<BookIcon size="inherit" />} href="/atlas" unreadCount={8} />
  <appGrid.AppGridItem name="Research" icon={<BookIcon size="inherit" />} href="/research" activity="loading" />
  <appGrid.AppGridItem name="Archive" icon={<BookIcon size="inherit" />} description="A destination is not available yet." />
</appGrid.AppGrid>
```