@payfit/unity-components 2.35.4 → 2.35.5

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

@@ -0,0 +1,400 @@
+---
+name: unity-layout-and-styling
+description: >
+  Compose layouts and apply styles in @payfit/unity-components. Flex (1D)
+  and Grid (12-col 2D). Every utility class MUST use the uy: prefix
+  (uy:flex, uy:gap-100). Modifier order is uy:md:gap-200, uy:hover:bg-…,
+  uy:data-[hovered=true]:bg-… (preferred when components expose state
+  attributes). Merge classes with uyMerge, build variants with uyTv,
+  conditional class strings with cn/classNames/clsx — all from
+  @payfit/unity-themes. Use <Text variant> for typography. Verify token
+  names exist in the @theme block; do not hallucinate (uy:bg-primary-500
+  is NOT a Unity token).
+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'
+  - 'PayFit/hr-apps:libs/shared/unity/components/src/components/text/Text.tsx'
+  - 'PayFit/hr-apps:libs/shared/unity/themes/src/utils/tailwind-merge.ts'
+  - 'PayFit/hr-apps:libs/shared/unity/themes/src/utils/tailwind-variants.ts'
+  - 'PayFit/hr-apps:libs/shared/unity/themes/src/utils/cn.ts'
+  - 'PayFit/hr-apps:libs/shared/unity/themes/src/scripts/build.ts'
+---
+
+Layout primitives, the `uy:` utility-class system, and the variant/merge tools
+used inside `@payfit/unity-components`.
+
+## Setup
+
+```tsx
+import { Card, Flex, Grid, Text } from '@payfit/unity-components'
+
+export function PayslipSummary() {
+  return (
+    <Card>
+      <Flex direction="col" gap="200" className="uy:p-300">
+        <Text variant="h3" asElement="h2">
+          Payslip
+        </Text>
+        <Grid cols={12} className="uy:gap-200 uy:md:gap-300">
+          <Flex direction="col" className="uy:col-span-12 uy:md:col-span-6">
+            <Text variant="overline">Gross</Text>
+            <Text variant="bodyLargeStrong">€ 4,200.00</Text>
+          </Flex>
+          <Flex direction="col" className="uy:col-span-12 uy:md:col-span-6">
+            <Text variant="overline">Net</Text>
+            <Text variant="bodyLargeStrong">€ 3,150.00</Text>
+          </Flex>
+        </Grid>
+      </Flex>
+    </Card>
+  )
+}
+```
+
+## Core 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" />
+```
+
+## Common Mistakes
+
+### CRITICAL Use bare Tailwind classes without uy: prefix
+
+Wrong:
+
+```tsx
+<Flex className="flex gap-4 p-3"> … </Flex>
+```
+
+Correct:
+
+```tsx
+<Flex gap="100" className="uy:p-300">
+  {' '}
+  …{' '}
+</Flex>
+```
+
+Unity CSS is built with `prefix(uy)`; bare classes are not in the compiled stylesheet and produce no styling.
+
+Source: themes/src/scripts/build.ts:298 (prefix(uy) import)
+
+### HIGH Pass responsive prop objects (v0.x style)
+
+Wrong:
+
+```tsx
+<Flex gap={{ initial: '100', md: '200' }} />
+```
+
+Correct:
+
+```tsx
+<Flex gap="100" className="uy:md:gap-200" />
+```
+
+v1.x removed the responsive prop-object API. Use className with uy:md: et al.
+
+Source: components/flex/Flex.tsx:33; themes/docs/files/MIGRATION-v1.md
+
+### HIGH Import twMerge from tailwind-merge directly
+
+Wrong:
+
+```tsx
+import { twMerge } from 'tailwind-merge'
+
+twMerge('uy:p-100', 'uy:p-200')
+```
+
+Correct:
+
+```tsx
+import { uyMerge } from '@payfit/unity-themes'
+
+uyMerge('uy:p-100', 'uy:p-200') // → 'uy:p-200'
+```
+
+The unconfigured twMerge has no knowledge of Unity tokens; class conflicts on uy:bg-surface-primary-default vs uy:bg-surface-danger-default are not resolved.
+
+Source: themes/src/utils/tailwind-merge.ts:1-7,75-77
+
+### HIGH Import tv from tailwind-variants directly
+
+Wrong:
+
+```tsx
+import { tv } from 'tailwind-variants'
+export const button = tv({ base: 'uy:px-200', variants: {...} })
+```
+
+Correct:
+
+```tsx
+import { uyTv } from '@payfit/unity-themes'
+export const button = uyTv({ base: 'uy:px-200', variants: {...} })
+```
+
+tv() is unconfigured; uyTv pre-applies the Unity twMergeConfig so variant conflict resolution understands Unity tokens.
+
+Source: themes/src/utils/tailwind-variants.ts:48-51
+
+### MEDIUM Use <div> + typography class instead of <Text>
+
+Wrong:
+
+```tsx
+<div className="uy:typography-h1 uy:text-content-primary">Title</div>
+```
+
+Correct:
+
+```tsx
+<Text variant="h1" color="content.primary">
+  Title
+</Text>
+```
+
+`<Text variant="h1">` auto-selects the correct semantic element (h1) and applies the Unity typography variant; `<div>` loses the semantics and the variant API.
+
+Source: components/text/Text.tsx:60-104,137-139
+
+### MEDIUM Use uy:hover: when component exposes data-\* state
+
+Wrong:
+
+```tsx
+<ListViewItem className="uy:hover:bg-surface-primary-hover" />
+```
+
+Correct:
+
+```tsx
+<ListViewItem className="uy:data-[hovered=true]:bg-surface-primary-hover" />
+```
+
+Some Unity components manage state via data-hovered, data-selected, etc. `uy:data-[hovered=true]:` targets the component-managed state and avoids drift.
+
+Source: themes/src/scripts/build.ts:303-307 (custom-variant for data attrs)
+
+### HIGH Hallucinate token names that look plausible but do not exist
+
+Wrong:
+
+```tsx
+<div className="uy:bg-primary-500 uy:text-gray-900 uy:border-blue-600" />
+```
+
+Correct:
+
+```tsx
+// Use Unity's semantic token names (verify against the live class index
+// in themes docs or the @theme block in dist/css/unity.css):
+<div className="uy:bg-surface-primary-default uy:text-content-primary uy:border-surface-primary-active" />
+```
+
+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)
+
+### MEDIUM Reach for cn() to compose variant classes when uyTv fits
+
+Wrong:
+
+```tsx
+import { cn } from '@payfit/unity-themes'
+
+function Pill({
+  size,
+  color,
+}: {
+  size: 'sm' | 'lg'
+  color: 'primary' | 'danger'
+}) {
+  return (
+    <span
+      className={cn(
+        'uy:inline-flex uy:items-center',
+        size === 'sm' && 'uy:px-100 uy:text-xs',
+        size === 'lg' && 'uy:px-200 uy:text-sm',
+        color === 'primary' && 'uy:bg-surface-primary-default',
+        color === 'danger' && 'uy:bg-surface-danger-default',
+      )}
+    />
+  )
+}
+```
+
+Correct:
+
+```tsx
+import type { VariantProps } from '@payfit/unity-themes'
+
+import { uyTv } from '@payfit/unity-themes'
+
+const pill = uyTv({
+  base: 'uy:inline-flex uy:items-center',
+  variants: {
+    size: { sm: 'uy:px-100 uy:text-xs', lg: 'uy:px-200 uy:text-sm' },
+    color: {
+      primary: 'uy:bg-surface-primary-default',
+      danger: 'uy:bg-surface-danger-default',
+    },
+  },
+})
+type PillProps = VariantProps<typeof pill>
+function Pill(props: PillProps) {
+  return <span className={pill(props)} />
+}
+```
+
+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
+
+## See also
+
+- `unity-find-component` — the decision tree's "React Aria + uy: classes" branch
+  when no Unity component fits.
+- `unity-contribute-component` — `uyTv` is the contributor's variant tool.
+- `unity-themes-tokens-and-docs` — token discipline if you need a new token
+  rather than reusing an existing one.

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

@@ -0,0 +1,190 @@
+---
+name: unity-migrate-from-midnight
+description: >
+  Migrate a legacy screen from @payfit/midnight to Unity. Component
+  equivalency map (Button, Box→Flex, Modal→Dialog, Link→RawLink,
+  Heading→Text). Prop renames (visual→color; onClick→onPress).
+  A11y deltas Unity enforces (tooltip-on-disabled-control is rejected at
+  the library level). RHF was used in Midnight-era code; replace with
+  Tanstack Form (see unity-tanstack-form). Full ~85-row component map
+  in references/midnight-component-map.md.
+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'
+  - 'PayFit/hr-apps:AGENTS.md'
+---
+
+Convert a legacy `@payfit/midnight` screen to Unity. The table below
+covers the highest-traffic mappings; the exhaustive ~85-row map lives
+in `references/midnight-component-map.md`. When a Midnight component is
+not in either, fall through to `unity-find-component`.
+
+## Equivalency Map (high-traffic)
+
+| Midnight               | Unity                                        | Notes                                                                |
+| ---------------------- | -------------------------------------------- | -------------------------------------------------------------------- |
+| `Button`               | `Button`                                     | Prop renames apply (see below)                                       |
+| `Box`                  | `Flex` (or `Grid` for 2D)                    | No 1:1 layout box; use `Flex` with `direction`/`gap`/`align`         |
+| `Modal`                | `Dialog` + `DialogContent` + `DialogActions` | Use `PromoDialog` for marketing dialogs (requires `PromoDialogHero`) |
+| `Link`                 | `RawLink` (base) or `Link` (tanstack-router) | Pick the router-aware one when navigating inside the app             |
+| `Heading`              | `Text` with `variant="heading*"`             | No dedicated `Heading`; typography is a `Text` variant               |
+| `Badge`                | `Badge`                                      | `color` → `variant`; Unity Badge is the chip with intent colors      |
+| `Pill`                 | `Pill`                                       | Unity Pill is numeric-only with fewer colors; same indicator intent  |
+| `transition('smooth')` | `uy:transition-*` / `uy:duration-*` classes  | No JS helper; use TailwindCSS utilities                              |
+
+For everything else, see `references/midnight-component-map.md`. When a
+target is unclear, switch to `unity-find-component` rather than
+guessing. Do not invent Unity component names from Midnight ones.
+
+## Prop renames
+
+Confirmed renames from `Button.tsx` and the React Aria base classes Unity
+extends:
+
+| Midnight          | Unity            | Mechanism                                              |
+| ----------------- | ---------------- | ------------------------------------------------------ |
+| `visual="danger"` | `color="danger"` | Color/intent prop renamed on `Button`, `Pill`, `Alert` |
+| `onClick={fn}`    | `onPress={fn}`   | React Aria press events (touch/keyboard parity)        |
+| `disabled`        | `isDisabled`     | React Aria boolean convention                          |
+
+Do not auto-extend this table. If a prop is not listed, look at the Unity
+component source — many props are unchanged and adding speculative
+renames produces silent default behavior.
+
+## Accessibility deltas
+
+Unity enforces several WCAG rules that Midnight allowed:
+
+- **Tooltip on disabled control — rejected at the library level.**
+  `Tooltip` ignores or removes the trigger when the wrapped control is
+  disabled, because disabled controls are not focusable and therefore the
+  tooltip is unreachable by keyboard or screen reader. See the
+  `## Common Mistakes` entry below for the replacement.
+- **Dialog focus management.** Unity `Dialog` traps focus, restores it on
+  close, and requires an accessible title. Midnight `Modal` was looser
+  about both.
+- **Autocomplete keyboard navigation.** Unity `Autocomplete` follows the
+  ARIA combobox pattern (Arrow keys, Home/End, Escape to dismiss). If
+  Midnight code relied on click-only interactions, those still work, but
+  do not strip the keyboard handlers when porting.
+
+## Forms
+
+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`.
+
+## Common Mistakes
+
+### CRITICAL Wrap disabled button in Tooltip (Midnight-era pattern)
+
+Wrong:
+
+```tsx
+<Tooltip title="Disabled because …">
+  <Button isDisabled>Submit</Button>
+</Tooltip>
+```
+
+Correct:
+
+```tsx
+<Button isDisabled>Submit</Button>
+<Text variant="bodySmall" color="content.neutral.low">
+  Disabled because …
+</Text>
+// Or, if you must explain inline, gate the tooltip on enabled state:
+{isDisabled
+  ? <Button isDisabled>Submit</Button>
+  : <Tooltip title="…"><Button>Submit</Button></Tooltip>}
+```
+
+Midnight allowed `Tooltip` on disabled buttons; Unity enforces the WCAG
+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)
+
+### HIGH Assume Midnight props map 1:1 to Unity
+
+Wrong:
+
+```tsx
+<Button visual="danger" onClick={handleDelete}>
+  Delete
+</Button>
+```
+
+Correct:
+
+```tsx
+<Button color="danger" onPress={handleDelete}>
+  Delete
+</Button>
+```
+
+`visual` is the Midnight intent prop and `color` is the Unity one; `onClick`
+still type-checks on the underlying DOM node but bypasses React Aria's
+touch and keyboard press handling, so keyboard activations silently no-op.
+
+Source: libs/shared/unity/components/src/components/button/Button.tsx
+
+### MEDIUM Leave Midnight + Unity side-by-side in the same screen
+
+Wrong:
+
+```tsx
+import { Button } from '@payfit/midnight'
+import { Dialog } from '@payfit/unity-components'
+```
+
+Correct:
+
+```tsx
+import { Button, Dialog } from '@payfit/unity-components'
+```
+
+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
+
+### MEDIUM Port Midnight transition utility instead of using uy: classes
+
+Wrong:
+
+```tsx
+import { transition } from '@payfit/midnight'
+<Flex transition={transition('smooth')}>
+```
+
+Correct:
+
+```tsx
+<Flex className="uy:transition-all uy:duration-200 uy:ease-out">
+```
+
+Unity has no JS transition helper; the migration target is TailwindCSS 4
+transition utilities under the `uy:` prefix, and porting the Midnight
+function leaves a dead import that the new theme tokens never honor.
+
+Source: no Unity equivalent for Midnight transition helpers
+
+## See also
+
+- `references/midnight-component-map.md` — exhaustive Midnight → Unity
+  map (v1 + v2 surfaces, ~85 rows, grouped by category)
+- `unity-find-component` — decision tree for any Midnight component
+  still ambiguous after consulting the full map
+- `unity-overlays` — full a11y constraints for `Dialog`, `Tooltip`,
+  `Popover`, `Menu`
+- `unity-tanstack-form` — replacement path for RHF forms in the migrated
+  screen