@payfit/unity-components 2.55.23 → 2.56.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payfit/unity-components",
-  "version": "2.55.23",
+  "version": "2.56.1",
   "module": "./dist/esm/index.js",
   "type": "module",
   "sideEffects": false,
@@ -96,7 +96,7 @@
     "tailwind-variants": "3.2.2",
     "usehooks-ts": "3.1.1",
     "zod": "4.4.3",
-    "@payfit/unity-illustrations": "2.55.23"
+    "@payfit/unity-illustrations": "2.56.1"
   },
   "peerDependencies": {
     "@hookform/devtools": "^4",
@@ -108,8 +108,8 @@
     "react-hook-form": "^7",
     "react-router-dom": "^5",
     "zod": "^3 || ^4",
-    "@payfit/unity-icons": "2.55.23",
-    "@payfit/unity-themes": "2.55.23"
+    "@payfit/unity-icons": "2.56.1",
+    "@payfit/unity-themes": "2.56.1"
   },
   "devDependencies": {
     "@figma/code-connect": "1.4.9",
@@ -159,10 +159,10 @@
     "@payfit/hr-apps-tsconfigs": "0.0.0-use.local",
     "@payfit/storybook-addon-console-errors": "0.0.0-use.local",
     "@payfit/storybook-config": "0.0.0-use.local",
-    "@payfit/unity-icons": "2.55.23",
-    "@payfit/unity-illustrations": "2.55.23",
-    "@payfit/unity-themes": "2.55.23",
-    "@payfit/vite-configs": "0.0.0-use.local"
+    "@payfit/unity-illustrations": "2.56.1",
+    "@payfit/unity-themes": "2.56.1",
+    "@payfit/vite-configs": "0.0.0-use.local",
+    "@payfit/unity-icons": "2.56.1"
   },
   "peerDependenciesMeta": {
     "@hookform/devtools": {

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

@@ -30,13 +30,21 @@ rg -i -C 2 'dialog|confirmation|modal' \
 
 ## Standard operating procedure
 
-1. Extract the user's intent and expand it into synonyms, interaction patterns, and adjacent component terms.
-2. Search the complete catalog; do not stop at the first slice or plausible hit.
-3. Rank candidates by intent fit, description, keywords, tags, section, and related entries.
-4. Return the best match first. Mention an alternative only when the evidence is genuinely ambiguous.
-5. Search `libs/shared/unity/components/src` to confirm implementation details or locate nearby source.
-6. Inspect Storybook stories only for props, API details, or usage examples after a likely component has been identified. When the Storybook MCP is available, use its curated component manifest or matching Storybook entry as a complementary source for rendered examples; the canonical JSON catalog remains the source of truth for discovery.
-7. Walk the decision tree below before creating a custom primitive.
+1. Build an inventory of distinct interface needs from all task inputs,
+   including the primary workflow, surrounding controls, navigation, status
+   information, and secondary actions. Do not silently omit peripheral UI.
+2. Expand every identified need into synonyms, interaction patterns, and
+   adjacent component terms.
+3. Search the complete catalog for every inventory item; do not stop after
+   finding components for the primary workflow or at the first plausible hit.
+4. Rank candidates by intent fit, description, keywords, tags, section, and related entries.
+5. Return the best match first. Mention an alternative only when the evidence is genuinely ambiguous.
+6. Search `libs/shared/unity/components/src` to confirm implementation details or locate nearby source.
+7. Inspect Storybook stories only for props, API details, or usage examples after a likely component has been identified. When the Storybook MCP is available, use its curated component manifest or matching Storybook entry as a complementary source for rendered examples; the canonical JSON catalog remains the source of truth for discovery.
+8. Walk the decision tree below for every identified need before creating a custom primitive.
+9. Before implementation, perform a coverage check: every inventoried
+   interface need must map to a Unity component, an explicit React Aria
+   fallback, or a deliberate omission requested by the user.
 
 ## Decision Tree
 
@@ -131,6 +139,9 @@ import it into a new module.
   text. `IconButton` / `CircularIconButton` for icon-only actions
   (requires `aria-label`). `RawLinkButton` renders as an anchor but styled
   like a button — use when the action navigates.
+- `Search` vs `TextField`: use `Search` for query, lookup, and filtering
+  controls with search affordances and clearing behavior. Use `TextField` for
+  general textual data entry.
 - `Menu` vs `Popover`: `Menu` is a list of actionable items keyed by
   keyboard (Enter/Arrow). `Popover` is a free-form floating panel and
   requires a `title`.
@@ -144,22 +155,12 @@ import it into a new module.
   for "this section failed to load." `Alert` is an inline banner that
   coexists with surrounding content.
 
-## Icon Source Convention
+## Icon selection
 
-`Icon` takes a typed `src` prop of type `UnityIcon` — a literal union of
-PascalCase names with a `Filled` or `Outlined` suffix (~310 values, from
-`@payfit/unity-icons`). Strings outside that union are a type error. Do
-not cast to `UnityIcon`; the cast bypasses the sprite-id guard and the
-icon silently renders empty.
-
-```tsx
-import type { UnityIcon } from '@payfit/unity-icons'
-
-import { Icon } from '@payfit/unity-components'
-
-const icon: UnityIcon = 'MagnifyingGlassOutlined'
-;<Icon src={icon} size={20} />
-```
+Choose the component here (`Icon`, `IconButton`, a prefix/suffix icon, and so
+on), then use `unity-icons` to select an exact sprite name, type shared icon
+props, or migrate a Midnight icon. Do not duplicate or guess the icon catalog
+from the Components package.
 
 ## Forms Notice
 
@@ -259,37 +260,11 @@ that the `*Field` components handle.
 
 Source: libs/shared/unity/components/src/components/form-field/FormField.tsx; index.ts:205-223
 
-### HIGH Pass an untyped string to Icon src and guess the name
-
-Wrong:
-
-```tsx
-<Icon src="search" size={20} />
-<Icon src="trash-filled" />
-const name: string = 'trash'
-<Icon src={name as UnityIcon} />
-```
-
-Correct:
-
-```tsx
-import { Icon } from '@payfit/unity-components'
-import type { UnityIcon } from '@payfit/unity-icons'
-<Icon src="MagnifyingGlassOutlined" size={20} />
-<Icon src="TrashFilled" />
-type Props = { icon: UnityIcon }
-```
-
-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)
-
 ## See also
 
 - 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-icons` — select and type the exact icon after choosing the component
 - `unity-tanstack-form` — the only supported form authoring path

package/skills/unity-layout/SKILL.md

@@ -0,0 +1,130 @@
+---
+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.

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

@@ -0,0 +1,59 @@
+# Unity layout patterns
+
+## Flex for one dimension
+
+Use `Flex` for a row or column and `FlexItem` for item-level growth or
+alignment.
+
+```tsx
+import { Flex, FlexItem } from '@payfit/unity-components'
+;<Flex direction="row" gap="200" justify="between" align="center">
+  <FlexItem grow="1">Left</FlexItem>
+  <FlexItem>Right</FlexItem>
+</Flex>
+```
+
+`Flex` exposes `asElement`, `inline`, `direction`, `isReversed`, `wrap`,
+`gap`, `gapX`, `gapY`, `justify`, `align`, `alignContent`, and `className`.
+
+## Grid for two dimensions
+
+Use `Grid` when content needs row and column placement. Position a `GridItem`
+with either `area` or the column props; do not combine the two strategies.
+
+```tsx
+import { Grid, GridItem } from '@payfit/unity-components'
+;<Grid cols={12} className="uy:gap-200">
+  <GridItem colSpan={8}>Main</GridItem>
+  <GridItem colSpan={4}>Aside</GridItem>
+</Grid>
+```
+
+`Grid` exposes `asElement`, `inline`, `cols`, `rows`, `areas`, `flow`,
+`justifyItems`, `alignItems`, and `className`.
+
+## Responsive layout
+
+Set the default through props, then apply breakpoint changes with `uy:`
+utilities. Read `unity-themes` before choosing utility or token names.
+
+```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" />
+```
+
+## Semantic typography
+
+`Text` selects a semantic element from its variant and supports an explicit
+`asElement` override.
+
+```tsx
+import { Text } from '@payfit/unity-components'
+
+<Text variant="h1" color="content.primary">Title</Text>
+<Text variant="body" color="content.neutral">Description</Text>
+<Text variant="h1" asElement="h2">Visual h1, semantic h2</Text>
+```

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

@@ -184,3 +184,5 @@ Source: no Unity equivalent for Midnight transition helpers
   `Popover`, `Menu`
 - `unity-tanstack-form` — replacement path for RHF forms in the migrated
   screen
+- `unity-icons` — select and type replacements for Midnight icons
+- `unity-illustrations` — select, load, and describe replacement artwork

package/skills/unity-migrate-from-midnight/references/midnight-component-map.md

@@ -143,14 +143,14 @@ look like a link.
 
 ## Media
 
-| Midnight       | Unity                                                               | Note                                                                    |
-| -------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `Avatar`       | `Avatar`                                                            | `type` → `variant` (circle/square)                                      |
-| `AvatarGroup`  | —                                                                   | No equivalent (planned)                                                 |
-| `Icon`         | `Icon` (`@payfit/unity-icons`)                                      | Pass typed `src: UnityIcon` string literal — do not cast `as UnityIcon` |
-| `Illustration` | `Illustration` / `LazyIllustration` (`@payfit/unity-illustrations`) | `LazyIllustration` for animated assets                                  |
-| `Image`        | native `<img>`                                                      | No Unity equivalent                                                     |
-| `Svg`          | native `<svg>` (or `Icon` if it's an icon)                          | No Unity equivalent for arbitrary SVGs                                  |
+| Midnight       | Unity                                                               | Note                                                        |
+| -------------- | ------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `Avatar`       | `Avatar`                                                            | `type` → `variant` (circle/square)                          |
+| `AvatarGroup`  | —                                                                   | No equivalent (planned)                                     |
+| `Icon`         | `Icon` (`@payfit/unity-icons`)                                      | Select and type the target with `unity-icons`               |
+| `Illustration` | `Illustration` / `LazyIllustration` (`@payfit/unity-illustrations`) | Select loading and accessibility with `unity-illustrations` |
+| `Image`        | native `<img>`                                                      | No Unity equivalent                                         |
+| `Svg`          | native `<svg>` (or `Icon` if it's an icon)                          | No Unity equivalent for arbitrary SVGs                      |
 
 ## Misc
 
@@ -173,8 +173,8 @@ Unity primitive.
 | `v2/Box`          | `Flex` / `Grid`                                                     | Same guidance as v1 `Box`                                     |
 | `v2/Flex`         | `Flex`                                                              | Drop the `v2/` namespace; same props                          |
 | `v2/Grid`         | `Grid`                                                              | Drop the `v2/` namespace                                      |
-| `v2/Icon`         | `Icon` (`@payfit/unity-icons`)                                      | Same target as v1 `Icon`                                      |
-| `v2/Illustration` | `Illustration` / `LazyIllustration` (`@payfit/unity-illustrations`) | Same target as v1 `Illustration`                              |
+| `v2/Icon`         | `Icon` (`@payfit/unity-icons`)                                      | Select and type the target with `unity-icons`                 |
+| `v2/Illustration` | `Illustration` / `LazyIllustration` (`@payfit/unity-illustrations`) | Select loading and accessibility with `unity-illustrations`   |
 | `v2/Image`        | native `<img>`                                                      | —                                                             |
 | `v2/PageLayout`   | `AppLayout` / `Page`                                                | `AppLayout` for the app shell; `Page` for the content surface |
 | `v2/Stack`        | `Flex` (with `direction` + `gap`)                                   | —                                                             |

package/skills/unity-overlays/SKILL.md

@@ -223,5 +223,7 @@ Source: components/promo-dialog/PromoDialog.tsx:230-236 (console.error guard)
 - `unity-migrate-from-midnight` — the disabled+tooltip trap is the most
   common Midnight-era pattern that Unity blocks; the migration skill covers
   the rewrite.
-- `unity-layout-and-styling` — overlay content uses the same `uy:` utility
-  classes (Flex/Grid, spacing, `uy:data-[hovered=true]:…`).
+- `unity-layout` — compose overlay content with Flex and Grid.
+- `unity-themes` — apply spacing and component-owned `data-*` state styles.
+- `unity-illustrations` — select and load the artwork required by
+  `PromoDialogHero`.

package/skills/unity-tanstack-form/SKILL.md

@@ -252,5 +252,6 @@ Source: TanstackTextField.tsx; TanstackFormField.tsx and its parts
 ## See also
 
 - `unity-migrate-from-midnight` — forms migrated off Midnight typically came with React Hook Form; that skill explains the Tanstack-only replacement path.
-- `unity-layout-and-styling` — form layouts use Flex/Grid and `uy:*` utilities for spacing and responsive behavior.
+- `unity-layout` — compose form layouts with Flex and Grid.
+- `unity-themes` — use `uy:*` spacing and responsive utilities.
 - `unity-navigation` — when a form posts via a route action or links to a sibling step, use the router-aware `Link` from `@payfit/unity-components/integrations/tanstack-router`.

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

@@ -1,274 +0,0 @@
----
-name: unity-layout-and-styling
-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.
-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'
-  - '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`.
-
-## Token lookup SOP
-
-Before adding a token-based utility, search the canonical [Unity token catalog](../../../themes/src/agent-references/tokens-catalog.json).
-Use its exact `name` and `cssVariable`, then consult the generated theme
-blueprints under `../../../themes/src/storybook-mcp/` for common class
-patterns. Do not infer token names from raw DTCG paths or standard Tailwind
-conventions when the catalog can provide the transformed name.
-
-## 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
-
-- 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.
-
-Read [references/patterns.md](references/patterns.md) for implementation
-examples.
-
-## 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: 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: 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-layout-and-styling/references/patterns.md

@@ -1,139 +0,0 @@
-# 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" />
-```