@payfit/unity-illustrations 1.0.0 → 1.1.0

package/dist/esm/components/illustration/Illustration.d.ts

@@ -1,5 +1,5 @@
+import { VariantProps } from '@payfit/unity-themes';
 import { ImgHTMLAttributes } from 'react';
-import { VariantProps } from 'tailwind-variants';
 import { UnityIllustrationAsset } from '../../generated/illustrationAssets.js';
 export declare const illustratedPicture: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "uy:object-contain uy:aspect-auto", {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "uy:object-contain uy:aspect-auto", unknown, unknown, undefined>>;
 export declare const illustratedIcon: import('tailwind-variants').TVReturnType<{
@@ -21,25 +21,34 @@ export declare const illustratedIcon: import('tailwind-variants').TVReturnType<{
         lg: string;
     };
 }, undefined, "uy:object-contain uy:aspect-square", unknown, unknown, undefined>>;
-export interface IllustrationPropsBase extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'children'> {
+interface IllustrationPropsCore extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'children' | 'alt'> {
     /**
      * The illustration asset to render. Must be imported from @payfit/unity-illustrations
      */
     src: UnityIllustrationAsset;
-    /** Accessible name for the illustration */
+}
+interface NonDecorativeIllustrationProps extends IllustrationPropsCore {
+    /** Whether this is decorative (hidden from screen readers) */
+    isDecorative?: false | undefined;
+    /** Accessible name for the illustration - required when not decorative */
     alt: string;
     /** Optional description for complex illustrations */
     description?: string;
+}
+interface DecorativeIllustrationProps extends IllustrationPropsCore {
     /** Whether this is decorative (hidden from screen readers) */
-    isDecorative?: boolean;
+    isDecorative: true;
+    /** Accessible name for the illustration - optional when decorative */
+    alt?: string;
 }
-export interface IllustratedPictureProps extends IllustrationPropsBase, VariantProps<typeof illustratedPicture> {
+export type IllustrationPropsBase = NonDecorativeIllustrationProps | DecorativeIllustrationProps;
+export type IllustratedPictureProps = IllustrationPropsBase & VariantProps<typeof illustratedPicture> & {
     /**
      * The illustration variant. It can be a regular picture or an illustrated icon
      */
     variant: 'picture';
-}
-export interface IllustratedIconProps extends IllustrationPropsBase, VariantProps<typeof illustratedIcon> {
+};
+export type IllustratedIconProps = IllustrationPropsBase & VariantProps<typeof illustratedIcon> & {
     /**
      * The illustration variant. It can be a regular picture or an illustrated icon
      */
@@ -48,7 +57,7 @@ export interface IllustratedIconProps extends IllustrationPropsBase, VariantProp
      * The size of the illustration. It only applies to illustrated icons
      */
     size: VariantProps<typeof illustratedIcon>['size'];
-}
+};
 export type IllustrationProps = IllustratedPictureProps | IllustratedIconProps;
 /**
  * Renders illustrations from the Unity design system with consistent styling and accessibility features.
@@ -78,3 +87,4 @@ export type IllustrationProps = IllustratedPictureProps | IllustratedIconProps;
  * See the [usage documentation](https://unity-illustrations.payfit.io/?path=/docs/introduction-usage--docs) for complete examples and best practices.
  */
 export declare const Illustration: import('react').ForwardRefExoticComponent<IllustrationProps & import('react').RefAttributes<HTMLImageElement>>;
+export {};

package/dist/esm/components/illustration/Illustration.js

@@ -1,9 +1,9 @@
 import { jsx as c } from "react/jsx-runtime";
 import { forwardRef as m } from "react";
-import { tv as a } from "tailwind-variants";
-const y = a({
+import { uyTv as o } from "@payfit/unity-themes";
+const y = o({
   base: "uy:object-contain uy:aspect-auto"
-}), p = a({
+}), d = o({
   base: "uy:object-contain uy:aspect-square",
   variants: {
     size: {
@@ -12,40 +12,39 @@ const y = a({
       lg: "uy:size-12"
     }
   }
-}), d = m(
+}), p = m(
   ({
     src: r,
-    alt: i,
-    description: o,
-    isDecorative: t = !1,
-    variant: n,
-    className: s,
-    ...e
-  }, l) => {
-    const u = n === "picture" ? y({ className: s }) : p({
-      className: s,
-      size: e.size
-    });
+    alt: s,
+    isDecorative: i = !1,
+    variant: a,
+    className: e,
+    ...t
+  }, n) => {
+    const u = a === "picture" ? y({ className: e }) : d({
+      className: e,
+      size: t.size
+    }), l = i ? t.description : void 0;
     return /* @__PURE__ */ c(
       "img",
       {
-        ref: l,
+        ref: n,
         src: r.url,
-        alt: t ? "" : i,
-        title: t ? void 0 : i,
+        alt: i ? "" : s,
+        title: i ? void 0 : s,
         className: u,
-        role: t ? "presentation" : "img",
-        "aria-hidden": t,
-        "aria-description": o,
+        role: i ? "presentation" : "img",
+        "aria-hidden": i,
+        "aria-description": l,
         loading: "lazy",
-        ...e
+        ...t
       }
     );
   }
 );
-d.displayName = "Illustration";
+p.displayName = "Illustration";
 export {
-  d as Illustration,
-  p as illustratedIcon,
+  p as Illustration,
+  d as illustratedIcon,
   y as illustratedPicture
 };

package/dist/esm/components/lazy-illustration/LazyIllustration.d.ts

@@ -9,7 +9,7 @@ import { IllustratedIconProps, IllustratedPictureProps } from '../illustration/I
  * @property {UnityIllustrationName} name - The name of the illustration to load dynamically.
  *   This must be one of the valid illustration names from the Unity illustration library.
  * @property {'picture' | 'icon'} variant - The illustration variant. It can be a regular picture or an illustrated icon.
- * @property {string} alt - Accessible name for the illustration.
+ * @property {string} alt - Accessible name for the illustration (required when isDecorative is false or undefined).
  * @property {string} [description] - Optional description for complex illustrations.
  * @property {boolean} [isDecorative] - Whether this is decorative (hidden from screen readers).
  * @property {'sm' | 'md' | 'lg'} [size] - The size of the illustration. Required when variant is 'icon'.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payfit/unity-illustrations",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "module": "./dist/esm/index.js",
   "type": "module",
   "sideEffects": false,
@@ -25,37 +25,33 @@
     "dist",
     "src"
   ],
+  "dependencies": {
+    "svgo": "3.3.2"
+  },
   "devDependencies": {
     "@payfit/code-pushup-tools": "0.0.0-use.local",
     "@payfit/hr-app-eslint": "0.0.0-use.local",
     "@payfit/hr-apps-tsconfigs": "0.0.0-use.local",
-    "@payfit/unity-themes": "1.0.0",
+    "@payfit/unity-themes": "1.1.0",
     "@payfit/vite-configs": "0.0.0-use.local",
-    "@storybook/addon-a11y": "9.1.3",
-    "@storybook/addon-docs": "9.1.3",
-    "@storybook/addon-links": "9.1.3",
-    "@storybook/react-vite": "9.1.3",
+    "@storybook/addon-a11y": "9.1.5",
+    "@storybook/addon-docs": "9.1.5",
+    "@storybook/addon-links": "9.1.5",
+    "@storybook/react-vite": "9.1.5",
     "@storybook/test-runner": "0.23.0",
     "@types/react": "18.3.18",
     "@types/react-dom": "18.3.5",
     "react": "18.3.1",
     "react-dom": "18.3.1",
-    "storybook": "9.1.3",
+    "storybook": "9.1.5",
     "svgo": "3.3.2",
     "tailwindcss": "4.1.11",
     "tsx": "4.17.0",
     "vite": "6.3.5"
   },
   "peerDependencies": {
-    "@payfit/unity-themes": "1.0.0",
-    "react": "^18",
-    "react-dom": "^18",
-    "svgo": "3.3.2",
-    "tailwind-variants": "2.1.0"
-  },
-  "peerDependenciesMeta": {
-    "svgo": {
-      "optional": true
-    }
+    "@payfit/unity-themes": "1.1.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
   }
 }

package/src/components/illustration/Illustration.stories.tsx

@@ -66,7 +66,73 @@ const meta = {
     },
   },
   argTypes: {
-    src: { control: 'select' },
+    src: {
+      control: 'select',
+      description:
+        'The illustration asset to render. Must be imported from @payfit/unity-illustrations',
+      table: {
+        type: { summary: 'UnityIllustrationAsset' },
+        category: 'Required',
+      },
+      type: { name: 'other', required: true, value: 'UnityIllustrationAsset' },
+    },
+    variant: {
+      control: 'select',
+      options: ['picture', 'icon'],
+      description:
+        'The illustration variant. It can be a regular picture or an illustrated icon',
+      table: {
+        type: { summary: "'picture' | 'icon'" },
+        category: 'Required',
+      },
+      type: { name: 'enum', required: true, value: ['picture', 'icon'] },
+    },
+    alt: {
+      control: 'text',
+      description:
+        'Accessible name for the illustration. Required when isDecorative is `true`',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accessibility',
+      },
+    },
+    description: {
+      control: 'text',
+      description:
+        'Optional description for complex illustrations. Active only when isDecorative is `true`',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accessibility',
+      },
+    },
+    isDecorative: {
+      control: 'boolean',
+      description:
+        'Whether the illustration is decorative (hidden from screen readers). When `true`, `alt` becomes optional',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Accessibility',
+      },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'The size of the illustration. Only applies to icon variant',
+      if: { arg: 'variant', eq: 'icon' },
+      table: {
+        type: { summary: "'sm' | 'md' | 'lg'" },
+        category: 'Icon Variant',
+      },
+    },
+    className: {
+      control: 'text',
+      description: 'Additional CSS classes for styling',
+      table: {
+        type: { summary: 'string' },
+        category: 'Styling',
+      },
+    },
   },
 } satisfies Meta<typeof Illustration>
 
@@ -79,6 +145,7 @@ export const Primary: Story = {
     variant: 'picture',
     src: Binoculars,
     className: 'uy:size-[150px]',
+    alt: 'Binoculars illustration',
   },
 }
 
@@ -106,32 +173,66 @@ export const IllustratedIcon: Story = {
   render: function Render(args) {
     return (
       <div className="uy:grid uy:grid-cols-3 uy:items-center uy:gap-200">
-        <Illustration {...args} variant="icon" size="sm" src={FAQ} />
-        <Illustration {...args} variant="icon" size="md" src={FAQ} />
-        <Illustration {...args} variant="icon" size="lg" src={FAQ} />
+        <Illustration
+          {...args}
+          variant="icon"
+          size="sm"
+          src={FAQ}
+          alt="FAQ icon small"
+        />
+        <Illustration
+          {...args}
+          variant="icon"
+          size="md"
+          src={FAQ}
+          alt="FAQ icon medium"
+        />
+        <Illustration
+          {...args}
+          variant="icon"
+          size="lg"
+          src={FAQ}
+          alt="FAQ icon large"
+        />
         <Illustration
           {...args}
           variant="icon"
           size="sm"
           src={FAQWithBackground}
+          alt="FAQ with background icon small"
         />
         <Illustration
           {...args}
           variant="icon"
           size="md"
           src={FAQWithBackground}
+          alt="FAQ with background icon medium"
         />
         <Illustration
           {...args}
           variant="icon"
           size="lg"
           src={FAQWithBackground}
+          alt="FAQ with background icon large"
         />
       </div>
     )
   },
 }
 
+/**
+ * You can make the illustration decorative by setting the `isDecorative` prop to `true`.
+ * When `isDecorative` is `true`, `alt` becomes optional. Screen readers will ignore the illustration and not read the `alt` or the `description` attributes. Use this when the illustration is purely decorative or visual appeal, and does not provide any information.
+ */
+export const IsDecorative: Story = {
+  args: {
+    variant: 'picture',
+    src: VisuallyImpaired,
+    className: 'uy:size-[50vmin]',
+    isDecorative: true,
+  },
+}
+
 /**
  * You can create responsive layouts where illustrations adapt to different viewport sizes
  * by combining responsive Tailwind classes with the illustration component (with media and container queries). Use Unity theme

package/src/components/illustration/Illustration.tsx

@@ -1,17 +1,17 @@
 import { forwardRef } from 'react'
 
+import type { VariantProps } from '@payfit/unity-themes'
 import type { ImgHTMLAttributes } from 'react'
-import type { VariantProps } from 'tailwind-variants'
 
 import type { UnityIllustrationAsset } from '../../generated/illustrationAssets'
 
-import { tv } from 'tailwind-variants'
+import { uyTv } from '@payfit/unity-themes'
 
-export const illustratedPicture = tv({
+export const illustratedPicture = uyTv({
   base: 'uy:object-contain uy:aspect-auto',
 })
 
-export const illustratedIcon = tv({
+export const illustratedIcon = uyTv({
   base: 'uy:object-contain uy:aspect-square',
   variants: {
     size: {
@@ -22,41 +22,56 @@ export const illustratedIcon = tv({
   },
 })
 
-export interface IllustrationPropsBase
-  extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'children'> {
+interface IllustrationPropsCore
+  extends Omit<
+    ImgHTMLAttributes<HTMLImageElement>,
+    'src' | 'children' | 'alt'
+  > {
   /**
    * The illustration asset to render. Must be imported from @payfit/unity-illustrations
    */
   src: UnityIllustrationAsset
-  /** Accessible name for the illustration */
+}
+
+interface NonDecorativeIllustrationProps extends IllustrationPropsCore {
+  /** Whether this is decorative (hidden from screen readers) */
+  isDecorative?: false | undefined
+  /** Accessible name for the illustration - required when not decorative */
   alt: string
   /** Optional description for complex illustrations */
   description?: string
-  /** Whether this is decorative (hidden from screen readers) */
-  isDecorative?: boolean
 }
 
-export interface IllustratedPictureProps
-  extends IllustrationPropsBase,
-    VariantProps<typeof illustratedPicture> {
-  /**
-   * The illustration variant. It can be a regular picture or an illustrated icon
-   */
-  variant: 'picture'
+interface DecorativeIllustrationProps extends IllustrationPropsCore {
+  /** Whether this is decorative (hidden from screen readers) */
+  isDecorative: true
+  /** Accessible name for the illustration - optional when decorative */
+  alt?: string
 }
 
-export interface IllustratedIconProps
-  extends IllustrationPropsBase,
-    VariantProps<typeof illustratedIcon> {
-  /**
-   * The illustration variant. It can be a regular picture or an illustrated icon
-   */
-  variant: 'icon'
-  /**
-   * The size of the illustration. It only applies to illustrated icons
-   */
-  size: VariantProps<typeof illustratedIcon>['size']
-}
+export type IllustrationPropsBase =
+  | NonDecorativeIllustrationProps
+  | DecorativeIllustrationProps
+
+export type IllustratedPictureProps = IllustrationPropsBase &
+  VariantProps<typeof illustratedPicture> & {
+    /**
+     * The illustration variant. It can be a regular picture or an illustrated icon
+     */
+    variant: 'picture'
+  }
+
+export type IllustratedIconProps = IllustrationPropsBase &
+  VariantProps<typeof illustratedIcon> & {
+    /**
+     * The illustration variant. It can be a regular picture or an illustrated icon
+     */
+    variant: 'icon'
+    /**
+     * The size of the illustration. It only applies to illustrated icons
+     */
+    size: VariantProps<typeof illustratedIcon>['size']
+  }
 
 export type IllustrationProps = IllustratedPictureProps | IllustratedIconProps
 
@@ -92,7 +107,6 @@ export const Illustration = forwardRef<HTMLImageElement, IllustrationProps>(
     {
       src,
       alt,
-      description,
       isDecorative: decorative = false,
       variant,
       className,
@@ -108,6 +122,10 @@ export const Illustration = forwardRef<HTMLImageElement, IllustrationProps>(
             size: (props as IllustratedIconProps).size,
           })
 
+    const description = decorative
+      ? (props as NonDecorativeIllustrationProps).description
+      : undefined
+
     return (
       <img
         ref={ref}

package/src/components/lazy-illustration/LazyIllustration.stories.tsx

@@ -24,6 +24,69 @@ const meta = {
         'VisuallyImpaired',
         'Library',
       ],
+      description:
+        'The name of the illustration to load dynamically. This must be one of the valid illustration names from the Unity illustration library',
+      table: {
+        type: { summary: 'UnityIllustrationName' },
+        category: 'Required',
+      },
+    },
+    variant: {
+      control: 'select',
+      options: ['picture', 'icon'],
+      description:
+        'The illustration variant. It can be a regular picture or an illustrated icon',
+      table: {
+        type: { summary: "'picture' | 'icon'" },
+        category: 'Required',
+      },
+    },
+    alt: {
+      control: 'text',
+      description:
+        'Accessible name for the illustration. Required when isDecorative is `true`',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accessibility',
+      },
+    },
+    // @ts-expect-error - Typescript can't handle the union type properly, but the prop exist
+    description: {
+      control: 'text',
+      description:
+        'Optional description for complex illustrations. Active only when isDecorative is `true`',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accessibility',
+      },
+    },
+    isDecorative: {
+      control: 'boolean',
+      description:
+        'Whether the illustration is decorative (hidden from screen readers). When `true`, `alt` becomes optional',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Accessibility',
+      },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'The size of the illustration. Only applies to icon variant',
+      if: { arg: 'variant', eq: 'icon' },
+      table: {
+        type: { summary: "'sm' | 'md' | 'lg'" },
+        category: 'Icon Variant',
+      },
+    },
+    className: {
+      control: 'text',
+      description: 'Additional CSS classes for styling',
+      table: {
+        type: { summary: 'string' },
+        category: 'Styling',
+      },
     },
   },
 } satisfies Meta<typeof LazyIllustration>
@@ -55,6 +118,7 @@ export const IllustratedPicture: Story = {
     variant: 'picture',
     name: 'VisuallyImpaired',
     className: 'uy:size-[50vmin]',
+    alt: 'Visually impaired person illustration',
   },
 }
 

package/src/components/lazy-illustration/LazyIllustration.tsx

@@ -25,7 +25,7 @@ import {
  * @property {UnityIllustrationName} name - The name of the illustration to load dynamically.
  *   This must be one of the valid illustration names from the Unity illustration library.
  * @property {'picture' | 'icon'} variant - The illustration variant. It can be a regular picture or an illustrated icon.
- * @property {string} alt - Accessible name for the illustration.
+ * @property {string} alt - Accessible name for the illustration (required when isDecorative is false or undefined).
  * @property {string} [description] - Optional description for complex illustrations.
  * @property {boolean} [isDecorative] - Whether this is decorative (hidden from screen readers).
  * @property {'sm' | 'md' | 'lg'} [size] - The size of the illustration. Required when variant is 'icon'.
@@ -116,7 +116,10 @@ export const LazyIllustration = forwardRef<
     return <div className={clsx} />
   }
 
-  return <Illustration ref={ref} src={illustration} {...props} />
+  // Handle the discriminated union by using type assertion
+  // This is safe because LazyIllustrationProps inherits from IllustrationProps (excluding src and name)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return <Illustration ref={ref} src={illustration} {...(props as any)} />
 })
 
 LazyIllustration.displayName = 'LazyIllustration'

package/src/generated/illustrationAssets.ts

@@ -6,7 +6,7 @@
 // - Images: 0
 // - Animated: 0
 // - Size optimization: 5682.0KB → 3460.7KB (-39.1%)
-// - Generated: 2025-08-27T12:34:59.297Z
+// - Generated: 2025-09-16T10:01:56.890Z
 //
 
 // Re-export shared types