# Core/TopNav - Design

## Properties

### Logo

The logo is required for all top navigation bars. It should link to the home page or main dashboard of the application.

### Navigation items

Navigation items represent the main sections of the application. They should be concise and clearly labeled. Use `TopNav.Item` for each navigation link.

### Actions

Actions are optional elements placed on the right side of the navigation bar. Common actions include search, notifications, user profile, and settings. Use `TopNav.Actions` to group these elements.

## Best Practices

### Navigation clarity

**Do**

<img className="w-full" src="images/guidelines/topnav/bestpractices-clarity-do.png" alt="Clear navigation labels" />

<p>
  Do use clear, descriptive labels for navigation items.
</p>

**Don't**

<img className="w-full" src="images/guidelines/topnav/bestpractices-clarity-dont.png" alt="Unclear navigation labels" />

<p>
  Don't use vague or ambiguous labels that don't clearly indicate the destination.
</p>

### Action overload

**Do**

<img className="w-full" src="images/guidelines/topnav/bestpractices-actions-do.png" alt="Reasonable number of actions" />

<p>
  Do limit the number of actions to the most essential ones.
</p>

**Don't**

<img className="w-full" src="images/guidelines/topnav/bestpractices-actions-dont.png" alt="Too many actions" />

<p>
  Don't overcrowd the actions area with too many buttons or icons.
</p>

## Accessibility

### Landmark

The top navigation uses `role="banner"` to identify it as the site-wide header landmark. This helps screen reader users quickly navigate to the main application header.

### Banner

The `TopNav` component is wrapped in a `<header>` element with `role="banner"`, which is the appropriate semantic HTML for site-wide navigation headers.

### Keyboard interaction

| Key               | Function                                                                         |
| ----------------- | -------------------------------------------------------------------------------- |
| `Tab`             | Moves focus through interactive elements in the navigation bar in logical order. |
| `Enter` / `Space` | Activates focused links or buttons.                                              |
| `Escape`          | Closes any open dropdowns or menus within the navigation.                        |

### Targets

All interactive elements in the top navigation meet the minimum 24×24 CSS pixel target size requirement for WCAG 2.2 Level AA compliance.