@payfit/unity-components 2.55.14 → 2.55.15

package/skills/unity-find-component/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: unity-find-component
 description: >
-  Load before choosing or creating Unity UI. Use it to map a UI need to an
-  existing @payfit/unity-components export, then fall back to React Aria plus
-  uy: classes only when Unity has no fit.
-type: core
-library: '@payfit/unity-components'
-library_version: '2.x'
+  Load when selecting a Unity component is unclear or before creating a custom
+  UI primitive that may already exist in @payfit/unity-components. Use it to
+  find the existing component, then fall back to React Aria plus uy: classes
+  only when Unity has no fit.
+metadata:
+  type: core
+  library: '@payfit/unity-components'
+  library_version: '2.x'
 sources:
   - 'PayFit/hr-apps:libs/shared/unity/components/src/index.ts'
   - 'PayFit/hr-apps:libs/shared/unity/icons/src/components/icon/parts/IconSprite.tsx'
@@ -18,100 +20,12 @@ sources:
 Routing skill for selecting a Unity component before writing UI code. Walk
 the catalog, then the decision tree, then the commonly-confused pairs.
 
-## Quick Reference
-
-All exports come from a single entry: `@payfit/unity-components`. There are
-no sub-paths for runtime components; the only sub-paths are
-`@payfit/unity-components/integrations/tanstack-router` (router-aware
-navigation) and `@payfit/unity-components/i18n/<locale>.json` (message
-bundles). Names below are grouped by purpose.
-
-### Layout
-
-`Flex`, `FlexItem`, `Grid`, `GridItem`, `Card`, `CardTitle`,
-`CardContent`, `SelectableCard...`, `NavigationCard`, `NavigationCardGroup`,
-`Page`, `PageHeader`, `PageHeading`, `AppLayout`, `AppMenu`,
-`FunnelLayout`, `FunnelPage`, `FunnelBody`, `FunnelSidebar`, `FunnelTopBar`,
-`FunnelPageHeader`, `FunnelPageContent`, `FunnelPageFooter`,
-`FunnelPageActions`, `FunnelBackButton`.
-
-### Navigation
-
-Router-agnostic (base entry): `RawLink`, `RawNavItem`, `RawBreadcrumbLink`,
-`RawPaginationLink`, `RawPaginationPrevious`, `RawPaginationNext`, `RawTab`,
-`Nav`, `NavGroup`, `Breadcrumbs`, `Breadcrumb`, `Pagination`,
-`PaginationContent`, `PaginationItem`, `PaginationEllipsis`, `Tabs`,
-`TabList`, `TabPanel`, `SkipLinks`, `TaskMenu`, `RawTask`, `RawSubTask`,
-`TaskGroup`, `ListView`, `RawListViewItem`, `ListViewSection`,
-`ListViewItemLabel`, `ListViewItemText`.
-
-Router-aware (from
-`@payfit/unity-components/integrations/tanstack-router`): `Link`,
-`NavItem`, `BreadcrumbLink`, `PaginationLink`, `Tab`.
-
-### Form fields (Tanstack Form — current)
-
-Bound via `form.AppField` then `field.<Name>`: `TextField`, `SelectField`,
-`NumberField`, `CheckboxField`, `CheckboxGroupField`, `DatePickerField`,
-`DateRangePickerField`, `MultiSelectField`, `RadioButtonGroupField`,
-`SelectableButtonGroupField`, `SelectableCardCheckboxGroupField`,
-`SelectableCardRadioGroupField`, `ToggleSwitchField`,
-`ToggleSwitchGroupField`, `PasswordField`.
-
-### Form primitives (no form state)
-
-`Input`, `NumberInput`, `Select`, `SelectButton`, `SelectOption`,
-`SelectOptionGroup`, `SelectOptionHelper`, `MultiSelect`,
-`MultiSelectOption`, `MultiSelectOptGroup`, `Checkbox`, `CheckboxStandalone`,
-`CheckboxGroup`, `RadioButtonGroup`, `RadioButton`, `RadioButtonHelper`,
-`TextArea`, `ToggleSwitch`, `ToggleSwitchGroup`, `SegmentedButtonGroup`,
-`ToggleButton`, `SelectableButtonGroup`, `SelectableButton`, `Search`,
-`PhoneNumberInput`, `DatePicker`, `DateCalendar`, `DateRangePicker`,
-`DateRangeCalendar`, `Autocomplete`, `AutocompleteItem`,
-`AutocompleteItemGroup`, `Fieldset`, `FieldGroup`, `Label`, `FormField`,
-`FormControl`, `FormLabel`, `FormHelperText`, `FormFeedbackText`.
-
-### Buttons and actions
-
-`Button`, `IconButton`, `CircularIconButton`, `RawLinkButton`, `Actionable`,
-`ActionBar`, `ActionBarRoot`, `ActionBarButton`, `ActionBarIconButton`,
-`FloatingActionBar`, `Anchor`.
-
-### Overlays
-
-Modal: `Dialog`, `DialogContent`, `DialogTitle`, `DialogActions`,
-`DialogButton`, `PromoDialog`, `PromoDialogHero`, `PromoDialogTitle`,
-`PromoDialogSubtitle`, `PromoDialogContent`, `PromoDialogActions`,
-`SidePanel`, `SidePanelHeader`, `SidePanelContent`, `SidePanelFooter`,
-`BottomSheet`, `BottomSheetHeader`, `BottomSheetContent`,
-`BottomSheetFooter`.
-
-Non-modal: `Tooltip`, `DefinitionTooltip`, `Popover`, `Menu`, `MenuTrigger`,
-`MenuContent`, `MenuHeader`, `RawMenuItem`, `MenuSeparator`.
-
-### Content and data
-
-`Text`, `Icon`, `Pill`, `Badge`, `Alert`, `AlertTitle`, `AlertContent`,
-`AlertActions`, `Avatar`, `AvatarFallback`, `AvatarIcon`, `AvatarImage`,
-`AvatarPair`, `DataTable`, `DataTableRoot`, `DataTableBulkActions`,
-`Table`, `TableBody`, `TableHeader`, `TableColumnHeader`, `TableRow`,
-`TableCell`, `TableEmptyState`, `TablePagination`, `Filter`,
-`FilterToolbar`, `Carousel`, `CarouselHeader`, `CarouselContent`,
-`CarouselSlide`, `CarouselNav`, `Collapsible`, `CollapsibleTitle`,
-`CollapsibleContent`, `Timeline`, `TimelineStep`, `TimelineStepHeader`,
-`TimelineStepDescription`.
-
-### Status and loading
-
-`Spinner`, `ProgressBar`, `FullPageLoader`, `EmptyState`, `EmptyStateIcon`,
-`EmptyStateContent`, `EmptyStateActions`, `EmptyStateGetStarted`,
-`EmptyStateWaitingForData`, `EmptyStateGoodJob`,
-`EmptyStateUpgradeRequired`, `EmptyStateNoSearchResults`,
-`EmptyStateUseDesktop`, `ErrorState`, `ToastManager`, `toast`.
-
-### Semantic and brand
-
-`PayFitBrand`, `PayFitPreprod`.
+## Component Catalog
+
+Inspect the current exports in `src/index.ts`, then use the decision tree below.
+For a categorized catalog of commonly used exports, read
+[references/component-catalog.md](references/component-catalog.md) only when
+component discovery requires it.
 
 ## Decision Tree
 
@@ -241,8 +155,8 @@ const icon: UnityIcon = 'MagnifyingGlassOutlined'
 Tanstack Form (`useTanstackUnityForm`) is the only supported form system.
 The React Hook Form path — `useUnityForm` plus the legacy `TextField` /
 `SelectField` / `NumberField` etc. RHF wrappers exported from the same
-index — is deprecated and scheduled for removal after the rebrand. Do not
-author new code with `useUnityForm`. See `unity-tanstack-form`.
+index — is deprecated. Do not author new code with `useUnityForm`. See
+`unity-tanstack-form`.
 
 ## Common Mistakes
 
@@ -308,7 +222,7 @@ import { Button, Dialog } from '@payfit/unity-components'
 Midnight is deprecated; new screens that import it cannot match the Unity
 theme tokens and will require a migration pass later anyway.
 
-Source: AGENTS.md "Do NOT use (deprecated)"; maintainer interview
+Source: AGENTS.md "Do NOT use (deprecated)"
 
 ### MEDIUM Combine Input + FormField when \*Field exists
 
@@ -359,11 +273,12 @@ The `UnityIcon` literal union encodes the exact sprite ids; lowercase or
 kebab-case strings have no matching `<symbol id>` in the injected sprite,
 so `<use href="#search">` resolves to nothing and the SVG renders empty.
 
-Source: libs/shared/unity/icons/src/components/icon/parts/IconSprite.tsx; generated/index.ts (UnityIcon type); maintainer interview
+Source: libs/shared/unity/icons/src/components/icon/parts/IconSprite.tsx; generated/index.ts (UnityIcon type)
 
 ## See also
 
-- `unity-setup-feature-plugin` — required before any Unity import will work
+- For projects not yet configured for Unity, use the repository's
+  `@payfit/nx-tools:setup-unity` generator
 - `unity-migrate-from-midnight` — when Level 3 fallback hits a Midnight
   screen, follow this skill to replace it
 - `unity-tanstack-form` — the only supported form authoring path

package/skills/unity-find-component/references/component-catalog.md

@@ -0,0 +1,94 @@
+# Unity component catalog
+
+All exports come from a single entry: `@payfit/unity-components`. There are
+no sub-paths for runtime components; the only sub-paths are
+`@payfit/unity-components/integrations/tanstack-router` (router-aware
+navigation) and `@payfit/unity-components/i18n/<locale>.json` (message
+bundles). Names below are grouped by purpose.
+
+### Layout
+
+`Flex`, `FlexItem`, `Grid`, `GridItem`, `Card`, `CardTitle`,
+`CardContent`, `SelectableCard...`, `NavigationCard`, `NavigationCardGroup`,
+`Page`, `PageHeader`, `PageHeading`, `AppLayout`, `AppMenu`,
+`FunnelLayout`, `FunnelPage`, `FunnelBody`, `FunnelSidebar`, `FunnelTopBar`,
+`FunnelPageHeader`, `FunnelPageContent`, `FunnelPageFooter`,
+`FunnelPageActions`, `FunnelBackButton`.
+
+### Navigation
+
+Router-agnostic (base entry): `RawLink`, `RawNavItem`, `RawBreadcrumbLink`,
+`RawPaginationLink`, `RawPaginationPrevious`, `RawPaginationNext`, `RawTab`,
+`Nav`, `NavGroup`, `Breadcrumbs`, `Breadcrumb`, `Pagination`,
+`PaginationContent`, `PaginationItem`, `PaginationEllipsis`, `Tabs`,
+`TabList`, `TabPanel`, `SkipLinks`, `TaskMenu`, `RawTask`, `RawSubTask`,
+`TaskGroup`, `ListView`, `RawListViewItem`, `ListViewSection`,
+`ListViewItemLabel`, `ListViewItemText`.
+
+Router-aware (from
+`@payfit/unity-components/integrations/tanstack-router`): `Link`,
+`NavItem`, `BreadcrumbLink`, `PaginationLink`, `Tab`.
+
+### Form fields (Tanstack Form — current)
+
+Bound via `form.AppField` then `field.<Name>`: `TextField`, `SelectField`,
+`NumberField`, `CheckboxField`, `CheckboxGroupField`, `DatePickerField`,
+`DateRangePickerField`, `MultiSelectField`, `RadioButtonGroupField`,
+`SelectableButtonGroupField`, `SelectableCardCheckboxGroupField`,
+`SelectableCardRadioGroupField`, `ToggleSwitchField`,
+`ToggleSwitchGroupField`, `PasswordField`.
+
+### Form primitives (no form state)
+
+`Input`, `NumberInput`, `Select`, `SelectButton`, `SelectOption`,
+`SelectOptionGroup`, `SelectOptionHelper`, `MultiSelect`,
+`MultiSelectOption`, `MultiSelectOptGroup`, `Checkbox`, `CheckboxStandalone`,
+`CheckboxGroup`, `RadioButtonGroup`, `RadioButton`, `RadioButtonHelper`,
+`TextArea`, `ToggleSwitch`, `ToggleSwitchGroup`, `SegmentedButtonGroup`,
+`ToggleButton`, `SelectableButtonGroup`, `SelectableButton`, `Search`,
+`PhoneNumberInput`, `DatePicker`, `DateCalendar`, `DateRangePicker`,
+`DateRangeCalendar`, `Autocomplete`, `AutocompleteItem`,
+`AutocompleteItemGroup`, `Fieldset`, `FieldGroup`, `Label`, `FormField`,
+`FormControl`, `FormLabel`, `FormHelperText`, `FormFeedbackText`.
+
+### Buttons and actions
+
+`Button`, `IconButton`, `CircularIconButton`, `RawLinkButton`, `Actionable`,
+`ActionBar`, `ActionBarRoot`, `ActionBarButton`, `ActionBarIconButton`,
+`FloatingActionBar`, `Anchor`.
+
+### Overlays
+
+Modal: `Dialog`, `DialogContent`, `DialogTitle`, `DialogActions`,
+`DialogButton`, `PromoDialog`, `PromoDialogHero`, `PromoDialogTitle`,
+`PromoDialogSubtitle`, `PromoDialogContent`, `PromoDialogActions`,
+`SidePanel`, `SidePanelHeader`, `SidePanelContent`, `SidePanelFooter`,
+`BottomSheet`, `BottomSheetHeader`, `BottomSheetContent`,
+`BottomSheetFooter`.
+
+Non-modal: `Tooltip`, `DefinitionTooltip`, `Popover`, `Menu`, `MenuTrigger`,
+`MenuContent`, `MenuHeader`, `RawMenuItem`, `MenuSeparator`.
+
+### Content and data
+
+`Text`, `Icon`, `Pill`, `Badge`, `Alert`, `AlertTitle`, `AlertContent`,
+`AlertActions`, `Avatar`, `AvatarFallback`, `AvatarIcon`, `AvatarImage`,
+`AvatarPair`, `DataTable`, `DataTableRoot`, `DataTableBulkActions`,
+`Table`, `TableBody`, `TableHeader`, `TableColumnHeader`, `TableRow`,
+`TableCell`, `TableEmptyState`, `TablePagination`, `Filter`,
+`FilterToolbar`, `Carousel`, `CarouselHeader`, `CarouselContent`,
+`CarouselSlide`, `CarouselNav`, `Collapsible`, `CollapsibleTitle`,
+`CollapsibleContent`, `Timeline`, `TimelineStep`, `TimelineStepHeader`,
+`TimelineStepDescription`.
+
+### Status and loading
+
+`Spinner`, `ProgressBar`, `FullPageLoader`, `EmptyState`, `EmptyStateIcon`,
+`EmptyStateContent`, `EmptyStateActions`, `EmptyStateGetStarted`,
+`EmptyStateWaitingForData`, `EmptyStateGoodJob`,
+`EmptyStateUpgradeRequired`, `EmptyStateNoSearchResults`,
+`EmptyStateUseDesktop`, `ErrorState`, `ToastManager`, `toast`.
+
+### Semantic and brand
+
+`PayFitBrand`, `PayFitPreprod`.

package/skills/unity-layout-and-styling/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Load when composing Unity layouts or styling with uy: Tailwind utilities.
   Use it for Flex/Grid/Text choices, class merging/variants, and validating
   Unity token names before adding styles.
-type: core
-library: '@payfit/unity-components, @payfit/unity-themes'
-library_version: '2.x'
+metadata:
+  type: core
+  library: '@payfit/unity-components, @payfit/unity-themes'
+  library_version: '2.x'
 sources:
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/flex/Flex.tsx'
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/grid/Grid.tsx'
@@ -50,143 +51,15 @@ export function PayslipSummary() {
 
 ## Core Patterns
 
-### Flex for 1D, Grid for 2D
+- Use `Flex` for one-dimensional layout and `Grid` for two-dimensional layout.
+- Express responsiveness and interaction states with `uy:` variants.
+- Use `uyTv` for typed component variants, `uyMerge` when merging external
+  classes, and `cn` for simple conditional strings.
+- Use `Text` variants for typography and prefer exposed `data-*` states over
+  raw hover selectors when components provide them.
 
-`Flex` is for one-dimensional rows/columns; `Grid` is for the 12-column (or 6-column)
-two-dimensional layout. Each exposes layout props; everything else goes via
-`className` with `uy:` utilities.
-
-```tsx
-import { Flex, FlexItem, Grid, GridItem } from '@payfit/unity-components'
-
-// Flex props: asElement, inline, direction, isReversed, wrap,
-//             gap, gapX, gapY, justify, align, alignContent, className
-<Flex direction="row" gap="200" justify="between" align="center">
-  <FlexItem grow="1">Left</FlexItem>
-  <FlexItem>Right</FlexItem>
-</Flex>
-
-// Grid props: asElement, inline, cols (6 | 12), rows, areas, flow,
-//             justifyItems, alignItems, className
-// GridItem positions via colSpan/colStart/colEnd OR area (mutually exclusive)
-<Grid cols={12} className="uy:gap-200">
-  <GridItem colSpan={8}>Main</GridItem>
-  <GridItem colSpan={4}>Aside</GridItem>
-</Grid>
-```
-
-### Responsive classes via uy:md:
-
-There is no responsive prop-object API. Responsive behavior is driven by
-TailwindCSS v4 modifiers on `className`.
-
-```tsx
-<Flex gap="100" className="uy:md:gap-200 uy:lg:gap-300">
-  <span>Item</span>
-</Flex>
-
-<Grid cols={12} className="uy:grid-cols-1 uy:md:grid-cols-2 uy:lg:grid-cols-3" />
-```
-
-### Variants with uyTv
-
-`uyTv` from `@payfit/unity-themes` is the pre-configured tailwind-variants
-factory. It applies the Unity `twMergeConfig` so variant collisions resolve
-against Unity tokens. Export the variant function and derive its typed props
-with `VariantProps`.
-
-```tsx
-import type { VariantProps } from '@payfit/unity-themes'
-
-import { uyTv } from '@payfit/unity-themes'
-
-export const callout = uyTv({
-  base: 'uy:inline-flex uy:items-center uy:gap-100 uy:rounded-100 uy:px-200 uy:py-100',
-  variants: {
-    intent: {
-      info: 'uy:bg-surface-primary-default uy:text-content-inverted-default',
-      danger: 'uy:bg-surface-danger-default uy:text-content-inverted-default',
-      neutral: 'uy:bg-surface-neutral-default uy:text-content-neutral-default',
-    },
-    size: {
-      sm: 'uy:typography-body-small',
-      md: 'uy:typography-body',
-    },
-  },
-  defaultVariants: { intent: 'info', size: 'md' },
-})
-
-export type CalloutVariantProps = VariantProps<typeof callout>
-```
-
-### Class merging with uyMerge
-
-`uyMerge` is `tailwind-merge` configured with Unity's class groups. Use it
-whenever an external `className` may collide with internal classes.
-
-```tsx
-import { uyMerge } from '@payfit/unity-themes'
-
-uyMerge('uy:p-100', 'uy:p-200') // → 'uy:p-200'
-uyMerge('uy:bg-surface-primary-default', 'uy:bg-surface-danger-default')
-// → 'uy:bg-surface-danger-default'
-uyMerge('uy:p-100', 'uy:px-200', 'uy:py-300') // p, px, py don't collide
-```
-
-### Conditional classes with cn / classNames / clsx
-
-`cn`, `classNames`, and `clsx` are aliases for the same Unity-configured helper
-in `@payfit/unity-themes`. Use them for ad-hoc conditional strings — not for
-component-scoped variant APIs.
-
-```tsx
-import { cn } from '@payfit/unity-themes'
-
-function Row({
-  isActive,
-  className,
-}: {
-  isActive: boolean
-  className?: string
-}) {
-  return (
-    <div
-      className={cn(
-        'uy:flex uy:items-center uy:px-200 uy:py-100',
-        isActive && 'uy:bg-surface-primary-default',
-        className,
-      )}
-    />
-  )
-}
-```
-
-### Typography with `<Text>`
-
-Use `<Text variant=...>` instead of a `<div>` + typography class. `Text`
-picks a semantic element from the variant (e.g. `variant="h1"` → `<h1>`),
-applies the typography variant, and exposes `color`, `isTruncated`,
-`lineClamp`, and `maxWidthCh`.
-
-```tsx
-import { Text } from '@payfit/unity-components'
-
-<Text variant="h1" color="content.primary">Title</Text>
-<Text variant="body" color="content.neutral">Description</Text>
-// Override the semantic element when needed:
-<Text variant="h1" asElement="h2">Visual h1, semantic h2</Text>
-```
-
-### Data-attribute pseudo-states
-
-Several Unity components expose internal state via `data-hovered`,
-`data-pressed`, `data-focus-visible`, etc. Target the component-owned state
-attribute rather than the native CSS pseudo-state.
-
-```tsx
-import { ListViewItem } from '@payfit/unity-components'
-;<ListViewItem className="uy:data-[hovered=true]:bg-surface-primary-hover" />
-```
+Read [references/patterns.md](references/patterns.md) for implementation
+examples.
 
 ## Common Mistakes
 
@@ -327,7 +200,7 @@ Correct:
 
 Agents generate names that match standard Tailwind conventions but are not in the Unity token set; the class is absent from the compiled stylesheet, the element silently renders with no style.
 
-Source: maintainer interview; themes/dist/css/unity.css (@theme block enumerates valid tokens)
+Source: themes/dist/css/unity.css (@theme block enumerates valid tokens)
 
 ### MEDIUM Reach for cn() to compose variant classes when uyTv fits
 
@@ -382,7 +255,7 @@ function Pill(props: PillProps) {
 
 cn() / classNames / clsx are for ad-hoc conditional class strings; component-scoped variant APIs with multiple axes (size × color × intent) belong in `uyTv`, which gives a typed `VariantProps` signature and pre-applied conflict resolution.
 
-Source: maintainer interview; themes/src/utils/tailwind-variants.ts
+Source: themes/src/utils/tailwind-variants.ts
 
 ## See also
 

package/skills/unity-layout-and-styling/references/patterns.md

@@ -0,0 +1,139 @@
+# Unity layout and styling patterns
+
+### Flex for 1D, Grid for 2D
+
+`Flex` is for one-dimensional rows/columns; `Grid` is for the 12-column (or 6-column)
+two-dimensional layout. Each exposes layout props; everything else goes via
+`className` with `uy:` utilities.
+
+```tsx
+import { Flex, FlexItem, Grid, GridItem } from '@payfit/unity-components'
+
+// Flex props: asElement, inline, direction, isReversed, wrap,
+//             gap, gapX, gapY, justify, align, alignContent, className
+<Flex direction="row" gap="200" justify="between" align="center">
+  <FlexItem grow="1">Left</FlexItem>
+  <FlexItem>Right</FlexItem>
+</Flex>
+
+// Grid props: asElement, inline, cols (6 | 12), rows, areas, flow,
+//             justifyItems, alignItems, className
+// GridItem positions via colSpan/colStart/colEnd OR area (mutually exclusive)
+<Grid cols={12} className="uy:gap-200">
+  <GridItem colSpan={8}>Main</GridItem>
+  <GridItem colSpan={4}>Aside</GridItem>
+</Grid>
+```
+
+### Responsive classes via uy:md:
+
+There is no responsive prop-object API. Responsive behavior is driven by
+TailwindCSS v4 modifiers on `className`.
+
+```tsx
+<Flex gap="100" className="uy:md:gap-200 uy:lg:gap-300">
+  <span>Item</span>
+</Flex>
+
+<Grid cols={12} className="uy:grid-cols-1 uy:md:grid-cols-2 uy:lg:grid-cols-3" />
+```
+
+### Variants with uyTv
+
+`uyTv` from `@payfit/unity-themes` is the pre-configured tailwind-variants
+factory. It applies the Unity `twMergeConfig` so variant collisions resolve
+against Unity tokens. Export the variant function and derive its typed props
+with `VariantProps`.
+
+```tsx
+import type { VariantProps } from '@payfit/unity-themes'
+
+import { uyTv } from '@payfit/unity-themes'
+
+export const callout = uyTv({
+  base: 'uy:inline-flex uy:items-center uy:gap-100 uy:rounded-100 uy:px-200 uy:py-100',
+  variants: {
+    intent: {
+      info: 'uy:bg-surface-primary-default uy:text-content-inverted-default',
+      danger: 'uy:bg-surface-danger-default uy:text-content-inverted-default',
+      neutral: 'uy:bg-surface-neutral-default uy:text-content-neutral-default',
+    },
+    size: {
+      sm: 'uy:typography-body-small',
+      md: 'uy:typography-body',
+    },
+  },
+  defaultVariants: { intent: 'info', size: 'md' },
+})
+
+export type CalloutVariantProps = VariantProps<typeof callout>
+```
+
+### Class merging with uyMerge
+
+`uyMerge` is `tailwind-merge` configured with Unity's class groups. Use it
+whenever an external `className` may collide with internal classes.
+
+```tsx
+import { uyMerge } from '@payfit/unity-themes'
+
+uyMerge('uy:p-100', 'uy:p-200') // → 'uy:p-200'
+uyMerge('uy:bg-surface-primary-default', 'uy:bg-surface-danger-default')
+// → 'uy:bg-surface-danger-default'
+uyMerge('uy:p-100', 'uy:px-200', 'uy:py-300') // p, px, py don't collide
+```
+
+### Conditional classes with cn / classNames / clsx
+
+`cn`, `classNames`, and `clsx` are aliases for the same Unity-configured helper
+in `@payfit/unity-themes`. Use them for ad-hoc conditional strings — not for
+component-scoped variant APIs.
+
+```tsx
+import { cn } from '@payfit/unity-themes'
+
+function Row({
+  isActive,
+  className,
+}: {
+  isActive: boolean
+  className?: string
+}) {
+  return (
+    <div
+      className={cn(
+        'uy:flex uy:items-center uy:px-200 uy:py-100',
+        isActive && 'uy:bg-surface-primary-default',
+        className,
+      )}
+    />
+  )
+}
+```
+
+### Typography with `<Text>`
+
+Use `<Text variant=...>` instead of a `<div>` + typography class. `Text`
+picks a semantic element from the variant (e.g. `variant="h1"` → `<h1>`),
+applies the typography variant, and exposes `color`, `isTruncated`,
+`lineClamp`, and `maxWidthCh`.
+
+```tsx
+import { Text } from '@payfit/unity-components'
+
+<Text variant="h1" color="content.primary">Title</Text>
+<Text variant="body" color="content.neutral">Description</Text>
+// Override the semantic element when needed:
+<Text variant="h1" asElement="h2">Visual h1, semantic h2</Text>
+```
+
+### Data-attribute pseudo-states
+
+Several Unity components expose internal state via `data-hovered`,
+`data-pressed`, `data-focus-visible`, etc. Target the component-owned state
+attribute rather than the native CSS pseudo-state.
+
+```tsx
+import { ListViewItem } from '@payfit/unity-components'
+;<ListViewItem className="uy:data-[hovered=true]:bg-surface-primary-hover" />
+```

package/skills/unity-migrate-from-midnight/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Load when replacing @payfit/midnight UI with Unity. Use it to choose Unity
   equivalents, avoid obsolete Midnight patterns, and route unclear component
   mappings to unity-find-component.
-type: lifecycle
-library: '@payfit/unity-components'
-library_version: '2.x'
+metadata:
+  type: lifecycle
+  library: '@payfit/unity-components'
+  library_version: '2.x'
 sources:
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/tooltip/Tooltip.tsx'
   - 'PayFit/hr-apps:libs/shared/unity/components/src/components/button/Button.tsx'
@@ -71,10 +72,9 @@ Unity enforces several WCAG rules that Midnight allowed:
 
 Midnight-era screens commonly use React Hook Form. When porting, replace
 the form with `useTanstackUnityForm` and the Tanstack-bound `*Field`
-components (`TextField`, `SelectField`, `NumberField`, etc.). The legacy
-RHF `useUnityForm` + `*Field` wrappers in the same package index are
-deprecated and will be removed after the rebrand — do not pause on the
-RHF intermediate step. See `unity-tanstack-form`.
+components (`TextField`, `SelectField`, `NumberField`, etc.). The legacy RHF
+`useUnityForm` + `*Field` wrappers in the same package index are deprecated.
+Do not pause on the RHF intermediate step. See `unity-tanstack-form`.
 
 ## Common Mistakes
 
@@ -106,7 +106,7 @@ rule that disabled controls must not have tooltips because they are not
 keyboard-focusable, so the tooltip is unreachable — Unity's `Tooltip`
 component rejects this pairing at the library level.
 
-Source: libs/shared/unity/components/src/components/tooltip/Tooltip.tsx; maintainer interview (Unity enforces)
+Source: libs/shared/unity/components/src/components/tooltip/Tooltip.tsx
 
 ### HIGH Assume Midnight props map 1:1 to Unity
 
@@ -151,7 +151,7 @@ Midnight and Unity ship divergent theme tokens — colors, spacing, and
 typography differ — so a mixed screen renders with mismatched scales and
 the visual regression lands silently because both stylesheets are valid.
 
-Source: AGENTS.md migration awareness; maintainer interview
+Source: AGENTS.md migration awareness
 
 ### MEDIUM Port Midnight transition utility instead of using uy: classes