@payfit/unity-components

This skill targets the current workspace Unity v3 API. Legacy examples are migration context.

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.

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 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:

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

Correct:

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

Use a generic element for semantic typography#

Wrong:

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

Correct:

<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.