@payfit/unity-components/skills/unity-layout/SKILL.md

---
name: unity-layout
description: >
  Load when composing page or component layouts with Unity Page, PageHeader,
  PageHeading, Flex, FlexItem, Grid, GridItem, or Text. Use it to choose the
  right layout primitive, preserve semantic typography, and replace removed
  responsive prop objects.
metadata:
  type: core
  library: '@payfit/unity-components'
  library_version: '2.x'
sources:
  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/page/Page.tsx'
  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/page/parts/PageHeader.tsx'
  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/page/parts/PageHeading.tsx'
  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/flex/Flex.tsx'
  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/grid/Grid.tsx'
  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/text/Text.tsx'
---

Compose structure with the layout and typography primitives exported by
`@payfit/unity-components`.

## Choose the primitive

- Use `Page`, `PageHeader`, and `PageHeading` for the main Unity page shell
  when an installed `Page` variant fits the application layout.
- Use `Flex` and `FlexItem` for one-dimensional rows or columns.
- Use `Grid` and `GridItem` when positioning content across rows and columns.
- Use `Text` for semantic Unity typography instead of styling a generic
  element with typography classes.
- Use component props for the base layout. Use `uy:` responsive utilities in
  `className` for breakpoint-specific changes; responsive prop objects were
  removed in Unity v1.

```tsx
import { Card, Flex, Grid, GridItem, Text } from '@payfit/unity-components'

export function PayslipSummary() {
  return (
    <Card>
      <Flex direction="col" gap="200">
        <Text variant="h3" asElement="h2">
          Payslip
        </Text>
        <Grid cols={12} className="uy:gap-200 uy:md:gap-300">
          <GridItem colSpan={6}>Gross</GridItem>
          <GridItem colSpan={6}>Net</GridItem>
        </Grid>
      </Flex>
    </Card>
  )
}
```

## Page containers

Use `Page` as the main Unity page shell when one of its installed variants
matches the application layout.

Before composing the surrounding layout, inspect the installed `Page`
implementation and its variants to understand the spacing, sizing, background,
border, and responsive behavior it already provides. These details belong to
the installed component version; do not infer them from memory or duplicate
them in an outer wrapper.

The parent of `Page` should normally define only the space available within the
application shell. Do not add redundant padding, margins, backgrounds,
borders, or arbitrary maximum widths around `Page`.

When only part of the page needs a width constraint, apply it to the relevant
content section, form, card, or grid instead of constraining the entire `Page`.

If the available `Page` variants do not fit the intended shell, confirm the
component API and inspect nearby usage before introducing a wrapper or custom
layout.

Read [references/patterns.md](references/patterns.md) for the supported layout
props and responsive composition examples.

## Common mistakes

### Use Flex for a two-dimensional layout

Use `Grid` when items need explicit row and column placement. Nested `Flex`
containers obscure the intended structure and make responsive changes harder.

### Pass responsive prop objects

Wrong:

```tsx
<Flex gap={{ initial: '100', md: '200' }} />
```

Correct:

```tsx
<Flex gap="100" className="uy:md:gap-200" />
```

### Use a generic element for semantic typography

Wrong:

```tsx
<div className="uy:typography-h1">Title</div>
```

Correct:

```tsx
<Text variant="h1">Title</Text>
```

Override `asElement` only when the document hierarchy requires a different
semantic element from the visual variant.

### Duplicate Page layout constraints

Do not treat `Page` as an unstyled `main` element. Inspect the installed
variant before adding an outer wrapper: duplicating its spacing, background,
border, or width constraints can compress the whole page unexpectedly.

## See also

- `unity-themes` — token lookup, `uy:` utilities, responsive and state
  modifiers, class merging, and typed variants.
- `unity-find-component` — choose a higher-level Unity component before
  composing a custom primitive.