@payfit/unity-themes 2.56.0 → 2.56.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payfit/unity-themes",
-  "version": "2.56.0",
+  "version": "2.56.2",
   "main": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
   "style": "./dist/css/unity.css",
@@ -71,8 +71,8 @@
     "vitest": "4.1.10",
     "@payfit/hr-app-eslint": "0.0.0-use.local",
     "@payfit/hr-apps-tsconfigs": "0.0.0-use.local",
-    "@payfit/vite-configs": "0.0.0-use.local",
-    "@payfit/storybook-config": "0.0.0-use.local"
+    "@payfit/storybook-config": "0.0.0-use.local",
+    "@payfit/vite-configs": "0.0.0-use.local"
   },
   "peerDependencies": {
     "@fontsource/inter": "5.0.19",

package/skills/unity-themes/SKILL.md

@@ -2,11 +2,18 @@
 name: unity-themes
 description: >
   Use when selecting a Unity design token, resolving a token reference or CSS
-  variable, or writing uy: utility classes. Search the canonical token catalog
-  first and use the generated class blueprints only for class syntax.
+  variable, writing responsive or state-based uy: utilities, merging classes,
+  or defining typed style variants. Search the canonical token catalog first
+  and use Unity's uyMerge, uyTv, and cn helpers instead of raw alternatives.
 metadata:
   type: core
   library: '@payfit/unity-themes'
+sources:
+  - 'PayFit/hr-apps:libs/shared/unity/themes/src/agent-references/tokens-catalog.json'
+  - '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'
 ---
 
 ## Source order
@@ -34,7 +41,9 @@ jq '.tokens[] | select(.name | test("border-neutral"; "i"))' \
 4. Preserve token references. Inspect `values.legacy` and `values.rebrand` to understand theme-specific resolution, and inspect `references` when explaining an alias.
 5. For classes, use the generated `src/storybook-mcp` blueprint for the relevant family and substitute only a catalog-confirmed token name. Do not enumerate or invent the complete class space.
 6. Prefer semantic tokens for product UI. Use primitives only when the intent has no semantic equivalent or the user explicitly asks for a raw palette value.
-7. Keep the `uy:` prefix on every Unity utility class and use `uyMerge`/`uyTv` from `@payfit/unity-themes` when composing classes or variants.
+7. Keep the `uy:` prefix on every Unity utility class.
+8. Use `uyMerge` when external classes may collide with internal ones, `uyTv`
+   for typed component variants, and `cn` for ad-hoc conditional strings.
 
 ```tsx
 <div className="uy:bg-surface-primary uy:text-content-primary" />
@@ -43,3 +52,60 @@ jq '.tokens[] | select(.name | test("border-neutral"; "i"))' \
 Never assume that a plausible Tailwind name exists. If it is not represented by the catalog or an applicable blueprint, keep searching or state that no confirmed class was found.
 
 Prefer semantic tokens over primitive values and use the `uy:` prefix for Tailwind utilities. Do not invent utility names or expand the full class space; consult the catalog and use the semantic family that matches the element's role.
+
+## Utility conventions
+
+- Prefix every class and modifier with `uy:`, for example
+  `uy:md:gap-200` and `uy:data-[hovered=true]:bg-surface-primary-hover`.
+- Prefer a component's exposed `data-*` state over a raw pseudo-class when the
+  component manages that state.
+- Import `uyMerge`, `uyTv`, `VariantProps`, and `cn` from
+  `@payfit/unity-themes`; raw `tailwind-merge` and `tailwind-variants` are not
+  configured for Unity tokens.
+- Use `uyTv` for a reusable component API with variant axes. Use `cn` for a
+  small conditional class expression.
+
+Read [references/patterns.md](references/patterns.md) for focused examples of
+responsive and state modifiers, class merging, conditional classes, and typed
+variants.
+
+## Common mistakes
+
+### Omit the uy: prefix
+
+Bare Tailwind classes are absent from Unity's prefixed stylesheet and silently
+produce no styling.
+
+```tsx
+// Wrong
+<div className="flex gap-4" />
+
+// Correct
+<div className="uy:flex uy:gap-200" />
+```
+
+### Guess a plausible token name
+
+```tsx
+// Wrong: standard Tailwind-looking names are not Unity tokens.
+<div className="uy:bg-primary-500 uy:text-gray-900" />
+
+// Correct: both names are confirmed by tokens-catalog.json.
+<div className="uy:bg-surface-primary uy:text-content-primary" />
+```
+
+### Import unconfigured helpers
+
+```tsx
+// Wrong
+import { twMerge } from 'tailwind-merge'
+import { tv } from 'tailwind-variants'
+
+// Correct
+import { uyMerge, uyTv } from '@payfit/unity-themes'
+```
+
+## See also
+
+- `unity-layout` — choose and compose `Flex`, `Grid`, and semantic `Text`
+  primitives from `@payfit/unity-components`.

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

@@ -0,0 +1,79 @@
+# Unity theme styling patterns
+
+## Responsive and state modifiers
+
+Keep the `uy:` prefix before the complete Tailwind modifier chain.
+
+```tsx
+<div className="uy:grid uy:grid-cols-1 uy:md:grid-cols-2 uy:lg:grid-cols-3" />
+```
+
+When a Unity component exposes managed state through `data-*`, target that
+state rather than the native pseudo-class.
+
+```tsx
+import { ListViewItem } from '@payfit/unity-components'
+;<ListViewItem className="uy:data-[hovered=true]:bg-surface-primary-hover" />
+```
+
+## Merge external classes with uyMerge
+
+`uyMerge` knows Unity's custom class groups and token families.
+
+```tsx
+import { uyMerge } from '@payfit/unity-themes'
+
+uyMerge('uy:p-100', 'uy:p-200')
+// => 'uy:p-200'
+
+uyMerge('uy:bg-surface-primary', 'uy:bg-surface-danger')
+// => 'uy:bg-surface-danger'
+```
+
+## Define typed variants with uyTv
+
+Use `uyTv` for reusable component variants and derive public 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 uy:text-content-inverted',
+      danger: 'uy:bg-surface-danger uy:text-content-inverted',
+      neutral: 'uy:bg-surface-neutral uy:text-content-neutral',
+    },
+    size: {
+      sm: 'uy:typography-body-small',
+      md: 'uy:typography-body',
+    },
+  },
+  defaultVariants: { intent: 'info', size: 'md' },
+})
+
+export type CalloutVariantProps = VariantProps<typeof callout>
+```
+
+## Compose conditional classes with cn
+
+Use `cn` for local boolean conditions, not for a reusable multi-axis variant
+API.
+
+```tsx
+import { cn } from '@payfit/unity-themes'
+
+function Row({ isActive }: { isActive: boolean }) {
+  return (
+    <div
+      className={cn(
+        'uy:flex uy:items-center uy:px-200 uy:py-100',
+        isActive && 'uy:bg-surface-primary',
+      )}
+    />
+  )
+}
+```