V9 Component Agent Skill

Scaffold a V9 Component

Create a new v9 component named $ARGUMENTS using the repo's Nx generators.

Steps

Adding a component to an existing package

Use the react-component generator:

yarn nx g @fluentui/workspace-plugin:react-component --name $ARGUMENTS --project <project-name>

Where <project-name> is the Nx project (e.g., react-button). This generates all required files: component, types, hook, styles, render, index barrel, and conformance test.

Creating a new package + component

Use the react-library generator first, then add the component:

# Create the package (will prompt for owner team)
yarn create-package

# Or non-interactively:
yarn nx g @fluentui/workspace-plugin:react-library --name <package-name> --owner "<team>"

# Then add the component inside it:
yarn nx g @fluentui/workspace-plugin:react-component --name $ARGUMENTS --project <package-name>

After scaffolding

• Review generated files against docs/architecture/component-patterns.md and fill in component-specific logic.

• Add styles in use${ARGUMENTS}Styles.styles.ts using design tokens:

   import { makeStyles } from '@griffel/react';
   import { tokens } from '@fluentui/react-theme';

• Create a default story at the appropriate stories package location if not generated.

• Update API docs after adding exports:

   yarn nx run <project>:generate-api

Critical Rules

• Always use ForwardRefComponent with React.forwardRef — never React.FC
• Always use design tokens from @fluentui/react-theme — never hardcoded colors/spacing/typography
• Always preserve user className as the LAST argument in mergeClasses()
• Use _unstable suffix on exported hooks: use$ARGUMENTS_unstable, use${ARGUMENTS}Styles_unstable, render${ARGUMENTS}_unstable
• Guard any window/document/navigator access with canUseDOM() from @fluentui/react-utilities
• Do not add dependencies on other Tier 3 component packages (see docs/architecture/layers.md)

Available Generators Reference

| Generator | Command | Purpose |

| --------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------- |

| react-component | yarn nx g @fluentui/workspace-plugin:react-component | Add component to existing package |

| react-library | yarn nx g @fluentui/workspace-plugin:react-library | Create new v9 package |

| recipe-generator | yarn nx g @fluentui/workspace-plugin:recipe-generator | Create a v9 recipe |

| prepare-initial-release | yarn nx g @fluentui/workspace-plugin:prepare-initial-release | Prepare package for release (compat/preview/stable) |

| bundle-size-configuration | yarn nx g @fluentui/workspace-plugin:bundle-size-configuration | Setup bundle-size tracking |

| cypress-component-configuration | yarn nx g @fluentui/workspace-plugin:cypress-component-configuration | Setup Cypress component tests |