# UI Component Contract V2

This document defines the shared component structure for pages migrated to
`body.ua-design-v2`.

## Page Structure

Use this page shape for migrated admin pages:

```html
<div class="content-wrapper ua-extracted-page">
  <section class="content">
    <div class="ua-page-v2">
      <header class="ua-page-head">
        <div class="ua-page-title">
          <h1>Page title</h1>
          <p>Short operational context.</p>
        </div>
        <div class="ua-page-actions">
          <a class="btn btn-outline-light">Secondary</a>
          <button class="btn btn-primary">Primary</button>
        </div>
      </header>

      <div class="ua-page-toolbar">
        <div class="ua-page-filters">...</div>
        <div class="ua-toolbar-actions">...</div>
      </div>

      <section class="ua-panel-v2">
        <div class="ua-panel-head">...</div>
        <div class="ua-panel-body">...</div>
      </section>
    </div>
  </section>
</div>
```

## Button Placement

- Page-level actions go in `.ua-page-actions` inside `.ua-page-head`.
- Filter/search controls go in `.ua-page-toolbar`, `.ua-page-filters`, or
  `.ua-filterbar`.
- Row actions go in `.ua-row-actions` inside the table row action column.
- Form submit actions go in `.ua-form-actions`.
- Modal actions go in `.ua-modal-foot`.
- Avoid placing the main page action in different locations across pages unless
  the workflow requires a bottom completion action.

## Forms

- Use `.ua-form-grid` or `.ua-fields-grid`.
- Use `.ua-field` for a normal field.
- Use span helpers when needed:
  - `.ua-span-2`
  - `.ua-span-3`
  - `.ua-span-4`
  - `.ua-span-6`
  - `.ua-span-8`
  - `.ua-span-12` or `.ua-full`
- Form colors, radius, height, padding, and focus state must come from design
  tokens, not page-specific CSS.

## Tables

- Wrap tables with `.ua-table-wrap`.
- Use `.ua-table` for migrated tables when possible.
- Keep row-level actions in `.ua-row-actions`.
- Table row height comes from `--ua-ds-table-row-h`.

## Cards And Panels

- Use `.ua-panel-v2` for main page sections.
- Use `.ua-card-v2` for repeated card items.
- Use `.ua-panel-head` / `.ua-card-head` and `.ua-panel-body` / `.ua-card-body`.

## Menus

- Use `.ua-menu-list` for menu containers when building new custom menus.
- Use `.ua-menu-item` for menu rows.
- Menus must be RTL, right aligned, and translucent in V2.

## Tabs

- Use `.ua-tabs-v2` for tab rails.
- Use `.ua-tab-v2` and `.is-active` for active state.

## Alerts And Modals

- Use `.ua-alert` for neutral shared alert styling.
- Use `.ua-modal-v2` for custom modal content.
- Use `.ua-modal-foot` for modal action placement.

## Migration Rule

When moving a page to V2, first change structure/classes to this contract, then
remove page-specific color/radius/spacing CSS only after visual QA passes.
