@payfit/unity-components 2.55.13 → 2.55.15

package/skills/unity-data-table/references/patterns.md

@@ -0,0 +1,237 @@
+# Unity DataTable patterns
+
+### Define columns with the column helper and ColumnMeta
+
+ColumnMeta drives accessibility (`isRowHeader`), keyboard navigation
+(`isFocusable: false` for cells whose children are themselves focusable like
+checkboxes), `helperText` (renders a tooltip next to the header), and
+`headerClassName` (required when `layout="fixed"`).
+
+```tsx
+import { Badge } from '@payfit/unity-components'
+import { createColumnHelper } from '@tanstack/react-table'
+
+const columnHelper = createColumnHelper<Employee>()
+
+export const employeeColumns = [
+  columnHelper.accessor('name', {
+    id: 'employee',
+    header: 'Employee',
+    enableSorting: true,
+    meta: { isRowHeader: true, headerClassName: 'uy:w-[260px]' },
+  }),
+  columnHelper.accessor('status', {
+    header: 'Status',
+    enableColumnFilter: true,
+    filterFn: 'arrIncludesSome',
+    cell: info => {
+      const status = info.getValue()
+      return (
+        <Badge variant={status === 'active' ? 'success' : 'neutral'}>
+          {status}
+        </Badge>
+      )
+    },
+    meta: { helperText: 'Active employees can sign in.' },
+  }),
+  columnHelper.display({
+    id: 'actions',
+    header: '',
+    cell: ({ row }) => <RowMenu row={row.original} />,
+    meta: { isFocusable: false },
+  }),
+]
+```
+
+### Server-side pagination
+
+`manualPagination: true` disables Tanstack's internal slicing. Pass only the
+current page's slice as `data` and supply `pageCount`.
+
+```tsx
+import { useMemo, useState } from 'react'
+
+import { getCoreRowModel, useReactTable } from '@tanstack/react-table'
+
+export function ServerTable({ totalCount, fetchPage }: Props) {
+  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 20 })
+  const { data: pageRows = [] } = useQuery({
+    queryKey: ['employees', pagination],
+    queryFn: () => fetchPage(pagination.pageIndex, pagination.pageSize),
+  })
+
+  const columns = useMemo(() => employeeColumns, [])
+  const data = useMemo(() => pageRows, [pageRows])
+
+  const table = useReactTable({
+    data,
+    columns,
+    manualPagination: true,
+    pageCount: Math.ceil(totalCount / pagination.pageSize),
+    state: { pagination },
+    onPaginationChange: setPagination,
+    getCoreRowModel: getCoreRowModel(),
+  })
+
+  return (
+    <DataTableRoot>
+      <DataTable table={table}>
+        {row => (
+          <TableRow key={row.id}>
+            {row.getVisibleCells().map(cell => (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            ))}
+          </TableRow>
+        )}
+      </DataTable>
+    </DataTableRoot>
+  )
+}
+```
+
+### Filtering with FilterToolbar
+
+`FilterToolbar.onChange` emits `SerializableAppliedFilter[]`. Map that onto
+`table.setColumnFilters` / `table.setGlobalFilter`. `renderControl` takes any
+control — it is a render function on purpose so you can drop in date pickers,
+multi-selects, text fields, etc.
+
+```tsx
+import type { FilterDef } from '@payfit/unity-components'
+
+import { FilterToolbar, Select, SelectItem } from '@payfit/unity-components'
+import { getFilteredRowModel } from '@tanstack/react-table'
+
+const filterDefs: FilterDef[] = [
+  {
+    id: 'status',
+    label: 'Status',
+    renderControl: (value, onChange) => (
+      <Select selectedKey={value as string} onSelectionChange={onChange}>
+        <SelectItem id="active">Active</SelectItem>
+        <SelectItem id="inactive">Inactive</SelectItem>
+      </Select>
+    ),
+    renderLabel: value => String(value),
+  },
+]
+
+export function FilteredTable() {
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+
+  const table = useReactTable({
+    data,
+    columns,
+    state: { columnFilters, pagination },
+    onColumnFiltersChange: setColumnFilters,
+    onPaginationChange: setPagination,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+  })
+
+  return (
+    <>
+      <FilterToolbar
+        filterDefs={filterDefs}
+        onChange={applied =>
+          setColumnFilters(applied.map(f => ({ id: f.id, value: f.value })))
+        }
+      />
+      <DataTableRoot>
+        <DataTable table={table}>
+          {row => (
+            <TableRow key={row.id}>
+              {row.getVisibleCells().map(cell => (
+                <TableCell key={cell.id}>
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </TableCell>
+              ))}
+            </TableRow>
+          )}
+        </DataTable>
+      </DataTableRoot>
+    </>
+  )
+}
+```
+
+### Bulk actions with row selection
+
+`DataTableBulkActions` lives next to `DataTable` inside `DataTableRoot`.
+It auto-shows when rows are selected and provides the F6 focus trap. Use a
+display column with `meta.isFocusable: false` for the checkbox.
+
+```tsx
+import {
+  CheckboxStandalone,
+  DataTable,
+  DataTableBulkActions,
+  DataTableRoot,
+} from '@payfit/unity-components'
+
+const checkboxColumn = columnHelper.display({
+  id: 'select',
+  header: ({ table }) => (
+    <CheckboxStandalone
+      isSelected={table.getIsAllPageRowsSelected()}
+      isIndeterminate={table.getIsSomePageRowsSelected()}
+      onChange={value => table.toggleAllPageRowsSelected(value)}
+      slot="selection"
+    >
+      Select all
+    </CheckboxStandalone>
+  ),
+  cell: ({ row }) => (
+    <CheckboxStandalone
+      isSelected={row.getIsSelected()}
+      onChange={value => row.toggleSelected(value)}
+      slot="selection"
+    >
+      Select row
+    </CheckboxStandalone>
+  ),
+  enableSorting: false,
+  meta: { isFocusable: false },
+})
+
+export function BulkTable() {
+  const [rowSelection, setRowSelection] = useState({})
+  const columns = useMemo(() => [checkboxColumn, ...employeeColumns], [])
+  const table = useReactTable({
+    data,
+    columns,
+    state: { rowSelection, pagination },
+    onRowSelectionChange: setRowSelection,
+    onPaginationChange: setPagination,
+    enableRowSelection: true,
+    getCoreRowModel: getCoreRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+  })
+
+  return (
+    <DataTableRoot>
+      <DataTable table={table}>
+        {row => (
+          <TableRow key={row.id} isSelected={row.getIsSelected()}>
+            {row.getVisibleCells().map(cell => (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            ))}
+          </TableRow>
+        )}
+      </DataTable>
+      <DataTableBulkActions
+        table={table}
+        actions={[
+          { id: 'archive', label: 'Archive', onAction: rows => archive(rows) },
+          { id: 'delete', label: 'Delete', onAction: rows => remove(rows) },
+        ]}
+      />
+    </DataTableRoot>
+  )
+}
+```

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