@payfit/unity-components
Version:
131 lines (100 loc) • 4.33 kB
Markdown
---
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.