@yahoo/uds 0.4.5 → 0.5.0

package/cli/README.md

@@ -46,7 +46,7 @@ uds sync --id [id] --outFile [path]
 uds sync --id [id]
 ```
 
-#### Enviornment variables
+#### Environment variables
 
 Alternatively, you can use environment variables instead of flags.
 
@@ -86,7 +86,20 @@ For more information about safelisting classes in Tailwind, visit the [official
 uds purge
 ```
 
-#### Enviornment variables
+#### Flags
+
+| Flag     | Description                 | Default            | Required |
+| -------- | --------------------------- | ------------------ | -------- |
+| `output` | Output path of the safelist | ./dist/safelist.ts |          |
+| `config` | UDS config                  | ./uds.config.ts    |          |
+
+**Example:**
+
+```shell
+uds purge --output output/dir
+```
+
+#### Environment variables
 
 | Variable                        | Description                                 | Default | Required |
 | ------------------------------- | ------------------------------------------- | ------- | -------- |

package/cli/codemods/remapProps.ts

@@ -0,0 +1,65 @@
+import path from 'node:path';
+
+import { green, print, red } from 'bluebun';
+import { IndentationText, Project, SyntaxKind } from 'ts-morph';
+
+interface RemapPropsOptions {
+  /** Properties to remap values for */
+  properties: string[];
+  /** Mapping of old value to new value */
+  oldToNewMap: Record<string, string>;
+}
+
+/**
+ * Remap props from old to new values.
+ * For example, a UDS component with a prop of `spacing="6"` should be updated to `spacing="4"`.
+ */
+export async function remapProps({ properties, oldToNewMap }: RemapPropsOptions) {
+  const workspaceDir = Bun.env.PWD;
+  const srcDir = path.join(workspaceDir, 'tsconfig.json');
+  const project = new Project({
+    tsConfigFilePath: srcDir,
+    manipulationSettings: { indentationText: IndentationText.TwoSpaces },
+  });
+
+  const sourceFiles = project.getSourceFiles(`${workspaceDir}/**/*.{ts,tsx}`);
+
+  for (const sourceFile of sourceFiles) {
+    const jsxOpeningElement = sourceFile.getDescendantsOfKind(SyntaxKind.JsxOpeningElement);
+    const jsxSelfClosingElement = sourceFile.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement);
+    const jsxElements = [...jsxOpeningElement, ...jsxSelfClosingElement];
+    for (const jsxElement of jsxElements) {
+      const identifier = jsxElement.getFirstChildByKind(SyntaxKind.Identifier);
+      const symbol = identifier?.getSymbol();
+      const isUdsComponent = symbol?.getDeclarations().some((declaration) => {
+        const importDeclaration = declaration.getFirstAncestorByKind(SyntaxKind.ImportDeclaration);
+        return importDeclaration?.getModuleSpecifierValue().startsWith('@yahoo/uds');
+      });
+
+      if (isUdsComponent) {
+        const attributes = jsxElement.getAttributes();
+        for (const attribute of attributes) {
+          const propIdentifier = attribute.getFirstChildByKind(SyntaxKind.Identifier);
+          const propName = propIdentifier?.getText();
+
+          if (propName && properties.includes(propName)) {
+            const oldValue = attribute
+              .getFirstChildByKind(SyntaxKind.StringLiteral)
+              ?.getLiteralValue();
+            const newValue = oldValue ? oldToNewMap[oldValue] : undefined;
+
+            if (newValue) {
+              const oldLog = red(`${propName}=${oldValue}`);
+              const newLog = green(`${propName}=${newValue}`);
+              const relativePath = sourceFile.getFilePath().replace(Bun.env.PWD, '');
+              print(`${relativePath} ${oldLog} -> ${newLog}`);
+              attribute.set({ name: propName, initializer: `"${newValue}"` });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  await project.save();
+}

package/cli/commands/codemod/spacingProps.ts

@@ -0,0 +1,52 @@
+import { spinStart, spinStop } from 'bluebun';
+
+import { remapProps } from '../../codemods/remapProps';
+
+export default {
+  name: 'spacingProps',
+  description: `Migrate spacing props from old to new values.`,
+  run: async () => {
+    spinStart('Running codemod...');
+
+    await remapProps({
+      properties: [
+        'spacing',
+        'spacingHorizontal',
+        'spacingVertical',
+        'spacingBottom',
+        'spacingEnd',
+        'spacingStart',
+        'spacingTop',
+        'offset',
+        'offsetHorizontal',
+        'offsetVertical',
+        'offsetBottom',
+        'offsetEnd',
+        'offsetStart',
+        'offsetTop',
+        'gap',
+        'columnGap',
+        'rowGap',
+      ],
+      oldToNewMap: {
+        '1': 'px',
+        '2': '0.5',
+        '3': '1',
+        '4': '2',
+        '5': '3',
+        '6': '4',
+        '7': '6',
+        '8': '8',
+        '9': '10',
+        '10': '12',
+        '11': '14',
+        '12': '16',
+        /** So typescript will fail for this replacement */
+        '13': 'THIS VALUE DOES NOT EXIST. PLEASE REMOVE.',
+        '14': '20',
+      },
+    });
+
+    spinStop('Codemod complete! Peek the diff and commit your changes!');
+  },
+};

package/cli/preload.ts

@@ -1,8 +1,8 @@
-import { jest, mock } from 'bun:test';
+import { mock, spyOn } from 'bun:test';
 
-const mockFastGlob = jest.fn().mockResolvedValue(['/pages/PageA.tsx', '/pages/PageB.tsx']);
-
-mock.module('fast-glob', () => ({ __esModule: true, default: mockFastGlob }));
+spyOn(global.Bun.Glob.prototype, 'scan').mockImplementation(() => {
+  return ['/pages/PageA.tsx', '/pages/PageB.tsx'] as unknown as AsyncIterableIterator<string>;
+});
 
 mock.module('@yahoo/uds/tailwind/purger', () => ({
   componentsDependencies: {
@@ -11,15 +11,19 @@ mock.module('@yahoo/uds/tailwind/purger', () => ({
     HStack: ['Box'],
   },
   componentToVariants: {
-    Button: ['color'],
-    HStack: ['alignItems', 'justifyContent'],
-    Icon: ['color'],
+    Button: [['color', ['accent']]],
+    HStack: [
+      ['alignItems', ['flex-start']],
+      ['justifyContent', ['flex-start']],
+    ],
+    Icon: [['color', ['accent']]],
     Text: ['fontSize', 'fontFamily'],
     Pressable: ['display'],
   },
   variantsList: ['color', 'alignItems', 'justifyContent', 'display', 'fontSize', 'fontFamily'],
   variantToTailwindClass: {
-    color: 'text-accent text-alert text-black text-brand text-positive text-warning text-white',
+    color:
+      'container text-accent text-alert text-black text-brand text-positive text-warning text-white',
     alignItems: 'items-start items-end items-center items-stretch items-baseline',
     justifyContent:
       'justify-start justify-end justify-center justify-between justify-around justify-evenly',

package/cli/utils/purgeCSS.test.ts

@@ -9,10 +9,11 @@ import {
   getUsedProps,
   isUDSComponent,
   parseFiles,
+  scanGetStylesReferences,
 } from './purgeCSS';
 
 const PAGE_A_CODE = `
-import { HStack, Button } from '@yahoo/uds';
+import { HStack, Button, getStyles } from '@yahoo/uds';
 
 const functionWithProp = () => {
   const vars = {
@@ -27,10 +28,20 @@ const functionWithProp = () => {
 
 const AnotherComponent = () => {
   const propsList = functionWithProp();
-  return <HStack test="test" {...propsList}>meow</HStack>
+
+  const classNames = getStyles({
+    borderStartColor: 'primary'
+  });
+
+  return <HStack testProp="testValue" classNames={classNames} {...propsList}>meow</HStack>
 }
 
 const PageA = () => {
+  const justifyContent = 'justify-start';
+  const classNames = getStyles({
+    justifyContent
+  });
+
   return (
     <div>
       <HStack />
@@ -56,7 +67,7 @@ const PageB = () => {
 `;
 
 const FILES = ['/pages/PageA.tsx', '/pages/PageB.tsx'];
-const IMPORTED_UDS_COMPONENTS = ['HStack', 'Button', 'Spinner'];
+const IMPORTED_UDS_COMPONENTS = ['HStack', 'Button', 'getStyles', 'Spinner'];
 
 describe('purgeCSS', () => {
   const project = new Project();
@@ -85,24 +96,23 @@ describe('purgeCSS', () => {
   });
 
   describe('getTailwindSafelist', () => {
-    it('returns the tailwind classes corresponding to the props on a component', () => {
+    it('returns the tailwind classes required for all the components', () => {
+      project.createSourceFile(FILES[0], PAGE_A_CODE, {
+        overwrite: true,
+      });
+      project.createSourceFile(FILES[1], PAGE_B_CODE, {
+        overwrite: true,
+      });
+
       const res = getTailwindSafelist(project, IMPORTED_UDS_COMPONENTS);
 
       expect(res).toEqual([
         'container',
         'fill',
-        '',
         'items-start',
-        'items-end',
         'items-center',
-        'items-stretch',
-        'items-baseline',
         'justify-start',
-        'justify-end',
         'justify-center',
-        'justify-between',
-        'justify-around',
-        'justify-evenly',
         'text-accent',
         'text-alert',
         'text-black',
@@ -110,6 +120,13 @@ describe('purgeCSS', () => {
         'text-positive',
         'text-warning',
         'text-white',
+        'text-transparent',
+        'text-muted',
+        'text-on-color',
+        'text-primary',
+        'text-secondary',
+        'text-tertiary',
+        'border-s-primary',
       ]);
     });
   });
@@ -148,12 +165,13 @@ describe('purgeCSS', () => {
       const usedProps = getUsedProps(project, 'HStack');
 
       expect(usedProps).toEqual([
-        'test',
-        'color',
-        'isActive',
-        'flexGrow',
-        'alignItems',
-        'justifyContent',
+        ['testProp', ['testValue']],
+        ['classNames', []],
+        ['color', []],
+        ['isActive', []],
+        ['flexGrow', ['1']],
+        ['alignItems', ['center']],
+        ['justifyContent', ['center']],
       ]);
     });
   });
@@ -169,4 +187,23 @@ describe('purgeCSS', () => {
       ]);
     });
   });
+
+  describe('scanGetStylesReferences', () => {
+    it('should scan the project for getStyles references and return the used variants', () => {
+      project.createSourceFile(FILES[0], PAGE_A_CODE, {
+        overwrite: true,
+      });
+      project.createSourceFile(FILES[1], PAGE_B_CODE, {
+        overwrite: true,
+      });
+
+      const res = scanGetStylesReferences(project);
+
+      const expectedResult = new Map();
+      expectedResult.set('borderStartColor', new Set(['primary']));
+      expectedResult.set('justifyContent', new Set([]));
+
+      expect(res).toEqual(expectedResult);
+    });
+  });
 });

package/cli/utils/purgeCSS.ts

@@ -5,9 +5,11 @@ import {
   componentToTwClasses,
   componentToVariants,
   variantsList,
-  variantToTailwindClass,
 } from '@yahoo/uds/tailwind/purger';
-import { findReferencesAsJsxElements, getUsedPropsInReference } from '@yahoo/uds/tailwind/tsMorph';
+import {
+  findReferencesAsJsxElements,
+  getUsedPropsInReference,
+} from '@yahoo/uds/tailwind/purger/utils';
 import {
   ColorModeConfig,
   DARK_COLOR_MODE_CLASSNAME,
@@ -17,6 +19,7 @@ import {
   ScaleModeConfig,
   SMALL_SCALE_MODE_CLASSNAME,
   UniversalTokensConfig,
+  variants,
   XLARGE_SCALE_MODE_CLASSNAME,
   XSMALL_SCALE_MODE_CLASSNAME,
   XXLARGE_SCALE_MODE_CLASSNAME,
@@ -24,8 +27,18 @@ import {
 } from '@yahoo/uds/tokens';
 import { print, spinStart, spinStop } from 'bluebun';
 import { BunFile } from 'bun';
-import FastGlob from 'fast-glob';
-import { JsxOpeningElement, JsxSelfClosingElement, Project, ts } from 'ts-morph';
+import { uniq } from 'lodash-es';
+import {
+  CallExpression,
+  JsxOpeningElement,
+  JsxSelfClosingElement,
+  Node,
+  Project,
+  SyntaxKind,
+  ts,
+} from 'ts-morph';
+
+import packageJson from '../../package.json';
 
 const scaleModeToClass: { [key in keyof ScaleModeConfig]: string } = {
   large: LARGE_SCALE_MODE_CLASSNAME,
@@ -49,9 +62,8 @@ type Files = string[];
 export const getFiles = async (): Promise<Files> => {
   const workspaceDir = Bun.env.PWD;
   const srcDir = path.join(workspaceDir, '/src/');
-  const files = await FastGlob(`${srcDir}/**/*.{jsx,tsx}`);
-
-  return files;
+  const glob = new Bun.Glob('**/*.{jsx,tsx}');
+  return Array.fromAsync(glob.scan({ cwd: srcDir, absolute: true }));
 };
 
 /**
@@ -125,23 +137,34 @@ export const parseFiles = (project: Project, files: Files): ImportsList => {
 export const getTailwindSafelist = (project: Project, componentList: string[]): SafeList => {
   const safeList: SafeList = [];
   const validVariants = new Set<string>(variantsList);
-  const usedProps = new Set<string>();
+  // we track the prop name and which values have been used
+  const usedProps = new Map<string, Set<string>>();
   componentList.forEach((component: string) => {
     if (isUDSComponent(component)) {
       // get the TW classes relevant for each prop
       // these classes are used internally in UDS,
       // they either have been initialized or used by other UDS components
-      componentToVariants[component].forEach((prop: string) => {
-        if (validVariants.has(prop) && !usedProps.has(prop)) {
-          usedProps.add(prop);
+      componentToVariants[component].forEach(([propName, usedValues]) => {
+        if (validVariants.has(propName)) {
+          const options: Set<string> = usedProps.get(propName) ?? new Set();
+          usedValues.forEach((val) => options.add(val));
+          usedProps.set(propName, options);
         }
       });
 
       // scan the project for used props and
       // get the corresponding css for those used props
-      getUsedProps(project, component).forEach((prop: string) => {
-        if (validVariants.has(prop) && !usedProps.has(prop)) {
-          usedProps.add(prop);
+      getUsedProps(project, component).forEach(([propName, usedValues]) => {
+        if (validVariants.has(propName)) {
+          // This means that an expression has been used (Ex: `<Button size={getSize()} />`)
+          // so we need to add all possible options for that prop
+          if (usedValues.length === 0) {
+            usedValues = Object.keys(variants[propName as keyof typeof variants]);
+          }
+
+          const options: Set<string> = usedProps.get(propName) ?? new Set();
+          usedValues.forEach((val) => options.add(val));
+          usedProps.set(propName, options);
         }
       });
 
@@ -150,11 +173,20 @@ export const getTailwindSafelist = (project: Project, componentList: string[]):
     }
   });
 
-  for (const prop of usedProps) {
-    safeList.push(...variantToTailwindClass[prop].replaceAll('\\', '').split(' '));
+  for (const [propName, usedValues] of usedProps) {
+    usedValues.forEach((option) => {
+      safeList.push((variants[propName as never][option] as string)?.replaceAll('\\', ''));
+    });
+  }
+
+  for (const [variant, variantOptions] of scanGetStylesReferences(project)) {
+    variantOptions.forEach((option) => {
+      safeList.push((variants[variant as never][option] as string)?.replaceAll('\\', ''));
+    });
   }
 
-  return safeList;
+  // Return a deduped list and strip out any empty strings
+  return uniq(safeList.filter(Boolean));
 };
 
 /**
@@ -163,12 +195,13 @@ export const getTailwindSafelist = (project: Project, componentList: string[]):
  * @example
  * const usedProps = getUsedProps(project, 'HStack');
  */
-export const getUsedProps = (project: Project, component: string) => {
+export const getUsedProps = (project: Project, component: string): Array<[string, string[]]> => {
   const references: (JsxOpeningElement | JsxSelfClosingElement)[] = [];
-  references.push(...findNamedImportReferences(project, '@yahoo/uds', component));
-  references.push(...findNamedImportReferences(project, '@yahoo/uds/experimental', component));
+  references.push(...findNamedImportReferences(project, packageJson.name, component));
+  references.push(
+    ...findNamedImportReferences(project, `${packageJson.name}/experimental`, component),
+  );
 
-  // for each reference find the used/references props
   const usedProps = references.map((reference) => getUsedPropsInReference(reference)).flat();
 
   return usedProps;
@@ -234,6 +267,96 @@ export const getClassesForEnabledThemesAndScales = (): string[] => {
   return classes;
 };
 
+/**
+ * Scan the source code for all `getStyles` references
+ *
+ * Note: This currently only works if we are passing a literal object to getStyles.
+ *
+ * Explanation: They we are able to enfer what css to include is by looking at the properties of the object passed.
+ * If something other than an object is passed, we can fallback on the Type, but that would require handling
+ * a lot of edge cases (function return type, spread operator, ternary, ...) and each one of these cases will
+ * most likely have a sub case. Falling back to the Type will complicate the code a lot is error prone as there
+ * is only so much info we can get out of the types as the Users are free to use `any` on their project which will
+ * provide no value for us. Hence why having a literal object passed is the best and probably the only sane way
+ * to go about this.
+ */
+export const scanGetStylesReferences = (project: Project): Map<string, Set<string>> => {
+  // Find all the references for `getStyles`
+  const references: CallExpression[] = [];
+  for (const sourceFile of project.getSourceFiles()) {
+    for (const importDeclaration of sourceFile.getImportDeclarations()) {
+      if (importDeclaration.getModuleSpecifierValue() === packageJson.name) {
+        for (const namedImport of importDeclaration.getNamedImports()) {
+          if (namedImport.getName() === 'getStyles') {
+            const identifier = namedImport.getFirstDescendantByKindOrThrow(
+              ts.SyntaxKind.Identifier,
+            );
+
+            for (const reference of identifier.findReferencesAsNodes()) {
+              const node = reference.getFirstAncestor((node) => {
+                return Node.isCallExpression(node);
+              });
+
+              if (node) {
+                references.push(node as CallExpression);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const usedProps = new Map<string, Set<string>>();
+  for (const reference of references) {
+    // TODO: handle the throw, tell users to not use something other than an object when calling `getStyles`
+    const objectLiteralExpression = reference.getFirstChildByKindOrThrow(
+      SyntaxKind.ObjectLiteralExpression,
+    );
+    const propertyAssignments = objectLiteralExpression.getDescendantsOfKind(
+      SyntaxKind.PropertyAssignment,
+    ); // PropertyAssignment is { property: 'test' }
+    const shorthandPropertyAssignments = objectLiteralExpression.getDescendantsOfKind(
+      SyntaxKind.ShorthandPropertyAssignment,
+    ); // ShorthandPropertyAssignment is { property }
+    // TODO: handle spread assignment
+    propertyAssignments.forEach((propertyAssigment) => {
+      const identifier = propertyAssigment.getFirstChildByKind(SyntaxKind.Identifier)?.getText();
+      // check if we are assigning a string
+      const stringLiteral = propertyAssigment
+        .getFirstChildByKind(SyntaxKind.StringLiteral)
+        ?.getLiteralText();
+      if (identifier && !stringLiteral) {
+        // this means an expression has been used
+        // so we add all the possibilites
+        const isvalidVariant = !!variants[identifier as keyof typeof variants];
+        const fallback = isvalidVariant
+          ? Object.keys(variants[identifier as keyof typeof variants])
+          : [];
+        usedProps.set(identifier, new Set(fallback));
+      }
+      if (identifier && stringLiteral) {
+        let options: Set<string>;
+        if (usedProps.has(identifier)) {
+          options = usedProps.get(identifier)!;
+        } else {
+          options = new Set();
+        }
+        options.add(stringLiteral);
+        usedProps.set(identifier, options);
+      }
+    });
+    shorthandPropertyAssignments.forEach((propertyAssigment) => {
+      const identifier = propertyAssigment.getFirstChildByKind(SyntaxKind.Identifier)?.getText();
+      if (identifier) {
+        usedProps.set(identifier, new Set());
+      }
+    });
+  }
+
+  return usedProps;
+};
+
 type PurgeOptions = {
   config?: string;
   output?: string;

package/dist/{Image.native-CfDCpWe_.d.cts → Image.native-Dy2tsvOP.d.ts}

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { b as UniversalPressableProps, c as UniversalIconButtonProps, d as UniversalImageProps } from './types-Dk8fLx7L.cjs';
+import { b as UniversalPressableProps, c as UniversalIconButtonProps, d as UniversalImageProps } from './types-at8CTkly.js';
 import { View, PressableProps as PressableProps$1, StyleProp, ViewStyle } from 'react-native';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ImageProps as ImageProps$1 } from 'expo-image';
@@ -14,17 +14,18 @@ declare const Pressable: react.ForwardRefExoticComponent<PressableProps & react.
 interface IconButtonProps extends PressableProps, UniversalIconButtonProps {
 }
 /**
- * An icon button element that can be used to trigger an action.
- * @example
- ```tsx
-  import { IconButton } from "@yahoo/uds";
-
-  export function IconButtonDemo() {
-    return (
-      <IconButton variant="accent-outline" color="primary" name="close" onPress={console.log} />
-    )
-  }
- ```
+ * An icon button is essentially an interactive icon. They should be used to
+ * display an icon which, when clicked, allows the user to trigger an action.
+ * Icon buttons provide additional features such hover states, focus states, and
+ * pressable functionality.
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { IconButton } from "@yahoo/uds";
+ * import { AddFolder } from "@yahoo/uds-icons";
+ *
+ * <IconButton name={AddFolder} color="primary" variant="accent" iconVariant="outline" />
+ * ```
  */
 declare const IconButton: react.ForwardRefExoticComponent<IconButtonProps & react.RefAttributes<View>>;
 

package/dist/{Image.native-nwk5tr_f.d.ts → Image.native-DyqCXXic.d.cts}

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { b as UniversalPressableProps, c as UniversalIconButtonProps, d as UniversalImageProps } from './types-Dk8fLx7L.js';
+import { b as UniversalPressableProps, c as UniversalIconButtonProps, d as UniversalImageProps } from './types-at8CTkly.cjs';
 import { View, PressableProps as PressableProps$1, StyleProp, ViewStyle } from 'react-native';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ImageProps as ImageProps$1 } from 'expo-image';
@@ -14,17 +14,18 @@ declare const Pressable: react.ForwardRefExoticComponent<PressableProps & react.
 interface IconButtonProps extends PressableProps, UniversalIconButtonProps {
 }
 /**
- * An icon button element that can be used to trigger an action.
- * @example
- ```tsx
-  import { IconButton } from "@yahoo/uds";
-
-  export function IconButtonDemo() {
-    return (
-      <IconButton variant="accent-outline" color="primary" name="close" onPress={console.log} />
-    )
-  }
- ```
+ * An icon button is essentially an interactive icon. They should be used to
+ * display an icon which, when clicked, allows the user to trigger an action.
+ * Icon buttons provide additional features such hover states, focus states, and
+ * pressable functionality.
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { IconButton } from "@yahoo/uds";
+ * import { AddFolder } from "@yahoo/uds-icons";
+ *
+ * <IconButton name={AddFolder} color="primary" variant="accent" iconVariant="outline" />
+ * ```
  */
 declare const IconButton: react.ForwardRefExoticComponent<IconButtonProps & react.RefAttributes<View>>;
 

package/dist/{VStack-D-py89Ge.d.cts → VStack-BjW120vC.d.cts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { Ref } from 'react';
-import { g as UniversalBoxProps, h as UniversalPressableProps, i as UniversalTextProps, j as UniversalStackProps } from './types-Diou6f1Q.cjs';
+import { aH as UniversalBoxProps, aK as UniversalIconProps, aL as UniversalPressableProps, aN as UniversalTextProps, g as UniversalStackProps } from './types-Cy3fKMaw.cjs';
 
 type DivProps = React.HTMLAttributes<HTMLDivElement>;
 interface BoxProps extends UniversalBoxProps, DivProps {
@@ -23,6 +23,29 @@ interface BoxProps extends UniversalBoxProps, DivProps {
  */
 declare const Box: react.ForwardRefExoticComponent<BoxProps & react.RefAttributes<HTMLDivElement>>;
 
+type SVGElementProps = Omit<React.HTMLAttributes<SVGSVGElement>, 'color'>;
+interface IconProps extends UniversalIconProps, SVGElementProps {
+}
+/**
+ * Icons are small symbols for actions or other items. They are available in
+ * three different sizes: `sm`, `md`, and `lg`. Each size also supports an
+ * outline and fill variant. Icons can be colored using the `color` prop.
+ *
+ * The component is available in the `@yahoo/uds` package but is meant to be used
+ * with the assets in `@yahoo/uds-icons`. You will need both packages to use icons.
+ * A separate package provides modularity from the core library, better
+ * versioning strategies, and tree shakeability.
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { Icon } from '@yahoo/uds';
+ * import { AddFolder } from '@yahoo/uds-icons';
+ *
+ * <Icon name={AddFolder} variant="fill" size="sm" />
+ * ```
+ */
+declare const Icon: react.ForwardRefExoticComponent<IconProps & react.RefAttributes<SVGSVGElement>>;
+
 type HtmlButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'name'>;
 interface PressableProps extends UniversalPressableProps, HtmlButtonProps {
 }
@@ -100,4 +123,4 @@ type VStackProps = UniversalStackProps & DivProps;
  **/
 declare const VStack: react.ForwardRefExoticComponent<UniversalStackProps & DivProps & react.RefAttributes<HTMLDivElement>>;
 
-export { Box as B, type DivProps as D, Pressable as P, Text as T, VStack as V, type BoxProps as a, type PressableProps as b, type TextProps as c, type VStackProps as d };
+export { Box as B, type DivProps as D, Icon as I, Pressable as P, Text as T, VStack as V, type BoxProps as a, type IconProps as b, type PressableProps as c, type TextProps as d, type VStackProps as e };