Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
38 changes: 38 additions & 0 deletions .changeset/crisp-falcons-teach.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
"@uifabricshared/foundation-compose": patch
"@fluentui-react-native/notification": patch
"@uifabricshared/theming-ramp": patch
"@fluentui-react-native/persona-coin": patch
"@fluentui-react-native/radio-group": patch
"@fluentui-react-native/dropdown": patch
"@fluentui-react-native/android-theme": patch
"@fluentui-react-native/default-theme": patch
"@fluentui-react-native/theming-utils": patch
"@fluentui-react-native/separator": patch
"@fluentui-react-native/experimental-shimmer": patch
"@fluentui-react-native/spinner": patch
"@fluentui-react-native/theme-tokens": patch
"@fluentui-react-native/checkbox": patch
"@fluentui-react-native/drawer": patch
"@fluentui-react-native/experimental-shadow": patch
"@fluentui-react-native/framework": patch
"@fluentui-react-native/apple-theme": patch
"@fluentui-react-native/theme-types": patch
"@fluentui-react-native/win32-theme": patch
"@fluentui-react-native/components": patch
"@fluentui-react-native/divider": patch
"@fluentui-react-native/tablist": patch
"@fluentui-react-native/avatar": patch
"@fluentui-react-native/button": patch
"@fluentui-react-native/switch": patch
"@fluentui-react-native/badge": patch
"@fluentui-react-native/input": patch
"@fluentui-react-native/chip": patch
"@fluentui-react-native/menu": patch
"@fluentui-react-native/text": patch
"@fluentui-react-native/theme": patch
"@fluentui-react-native/design": patch
"@fluentui-react-native/tokens": patch
---

Updating path references to components and design packages
14 changes: 7 additions & 7 deletions .github/skills/agentic-component-authoring/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
---
name: agentic-component-authoring
description: Generate or update Fluent UI React Native components in packages/agentic-components. Use for component APIs, slots, state hooks, token styling, render functions, tests, stories, and spec-driven component work.
description: Generate or update Fluent UI React Native components in packages/agentic/components. Use for component APIs, slots, state hooks, token styling, render functions, tests, stories, and spec-driven component work.
license: MIT
---

# Agentic component authoring

Build components in `packages/agentic-components` as React Native adaptations of the Fluent UI v9 component pattern.
Build components in `packages/agentic/components` as React Native adaptations of the Fluent UI v9 component pattern.
This skill is the workflow router. Load only the references needed for the current change instead of placing every
authoring rule in one always-loaded instruction file.

## Choose the component kind

- Higher-order components live in `src/components`. Read the
[higher-order component instructions](../../../packages/agentic-components/src/components/AGENTS.md).
[higher-order component instructions](../../../packages/agentic/components/src/components/AGENTS.md).
- Primitive components live in `src/primitives`. Read the
[primitive instructions](../../../packages/agentic-components/src/primitives/AGENTS.md).
[primitive instructions](../../../packages/agentic/components/src/primitives/AGENTS.md).
- If the change spans multiple components, repeated helpers, or shared dependency boundaries, read the
[package-wide optimization guidance](../agentic-component-optimization/SKILL.md) and
[`packages/agentic-components/src/AGENTS.md`](../../../packages/agentic-components/src/AGENTS.md). Do not run a
[`packages/agentic/components/src/AGENTS.md`](../../../packages/agentic/components/src/AGENTS.md). Do not run a
whole-package audit for a tiny single-component edit.
- Work on the Storybook application, native projects, bundling, or CocoaPods belongs to the
[agentic Storybook development skill](../agentic-storybook-development/SKILL.md), not this component workflow.
Expand All @@ -44,8 +44,8 @@ its immediate neighbors. Keep the component's colocated `SPEC.md` and companion
spec. Use the package-wide optimization guidance only when the change clearly involves repeated patterns or shared
dependency boundaries.
2. Inspect the closest canonical implementation. Use
[`components/button`](../../../packages/agentic-components/src/components/button) for a styled higher-order component
and [`primitives/icon`](../../../packages/agentic-components/src/primitives/icon) for a direct primitive.
[`components/button`](../../../packages/agentic/components/src/components/button) for a styled higher-order component
and [`primitives/icon`](../../../packages/agentic/components/src/primitives/icon) for a direct primitive.
3. Establish the public contract before implementation: variants, slots, native props, accessibility, interaction
states, and platform behavior.
4. Implement in dependency order: types and slots, state and accessibility, styles and slot props, pure rendering,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

Use this reference for `render<Component>.tsx`, `<component>.ts`, slot ordering, conditional structure, display names,
and package exports. The canonical examples are
[`renderButton.tsx`](../../../../packages/agentic-components/src/components/button/renderButton.tsx) and
[`button.ts`](../../../../packages/agentic-components/src/components/button/button.ts).
[`renderButton.tsx`](../../../../packages/agentic/components/src/components/button/renderButton.tsx) and
[`button.ts`](../../../../packages/agentic/components/src/components/button/button.ts).

## Keep render functions pure

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Use this reference for `<Component>StateProps`, `use<Component>.ts`, defaults, interaction hooks, accessibility, derived
state, and slot construction. The canonical example is
[`useButton.ts`](../../../../packages/agentic-components/src/components/button/useButton.ts).
[`useButton.ts`](../../../../packages/agentic/components/src/components/button/useButton.ts).

## State hook responsibilities

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

Use this reference for `<component>.styles.ts`, `use<Component>Styles.ts`, token mapping, theme caching, state precedence, and
slot prop application. The canonical examples are
[`button.styles.ts`](../../../../packages/agentic-components/src/components/button/button.styles.ts) and
[`useButtonStyles.ts`](../../../../packages/agentic-components/src/components/button/useButtonStyles.ts).
[`button.styles.ts`](../../../../packages/agentic/components/src/components/button/button.styles.ts) and
[`useButtonStyles.ts`](../../../../packages/agentic/components/src/components/button/useButtonStyles.ts).

## Resolve values from the correct token source

Consult
[`flex-token-map.yaml`](../../../../packages/agentic-design/src/tokens/mappings/flex-token-map.yaml) before choosing a
[`flex-token-map.yaml`](../../../../packages/agentic/design/src/tokens/mappings/flex-token-map.yaml) before choosing a
value.

- Read semantic colors from `useThemeState().tokens.color`.
Expand All @@ -35,16 +35,16 @@ Never create a style factory inside a hook or render function.

Reuse the design package's `@fluentui-react-native/design/styling` submodule:

- [`getStateStyleFactory`](../../../../packages/agentic-design/src/styling/branchedStyle.ts) lazily flattens and caches
- [`getStateStyleFactory`](../../../../packages/agentic/design/src/styling/branchedStyle.ts) lazily flattens and caches
one theme-independent state definition.
- [`getThemedStateStyleFactory`](../../../../packages/agentic-design/src/styling/branchedStyle.ts) resolves and caches
- [`getThemedStateStyleFactory`](../../../../packages/agentic/design/src/styling/branchedStyle.ts) resolves and caches
one flattened definition per `ThemeState`.
- [`getThemedColorStyleFactory`](../../../../packages/agentic-design/src/styling/colorStyles.ts) converts semantic
- [`getThemedColorStyleFactory`](../../../../packages/agentic/design/src/styling/colorStyles.ts) converts semantic
color keys and delegates its hierarchy and caching to `getThemedStateStyleFactory`.

These are the canonical Button mechanisms and cache plain resolved style objects in `state.themeStyles`. Do not wrap them
in another `StyleSheet.create` cache. Use
[`themedStyleSheetFactory`](../../../../packages/agentic-design/src/useThemeState.ts) only when a component genuinely
[`themedStyleSheetFactory`](../../../../packages/agentic/design/src/useThemeState.ts) only when a component genuinely
needs a complete theme-only `StyleSheet.create` result that is not represented by a branched state definition.

Every theme factory may depend only on `ThemeState` values such as tokens and high contrast. Props, interaction state,
Expand Down
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Tests and stories

Use this reference for runtime coverage, type coverage, visual snapshots, Storybook CSF, and validation. Canonical examples
are [`button.test.tsx`](../../../../packages/agentic-components/src/components/button/button.test.tsx),
[`button.stories.tsx`](../../../../packages/agentic-components/src/components/button/button.stories.tsx), and
[`icon.stories.tsx`](../../../../packages/agentic-components/src/primitives/icon/icon.stories.tsx).
are [`button.test.tsx`](../../../../packages/agentic/components/src/components/button/button.test.tsx),
[`button.stories.tsx`](../../../../packages/agentic/components/src/components/button/button.stories.tsx), and
[`icon.stories.tsx`](../../../../packages/agentic/components/src/primitives/icon/icon.stories.tsx).

## Runtime tests

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Use this reference when defining or changing a component's public API, slots, resolved state, native prop exposure, or
package exports. The canonical higher-order example is
[`button.types.ts`](../../../../packages/agentic-components/src/components/button/button.types.ts).
[`button.types.ts`](../../../../packages/agentic/components/src/components/button/button.types.ts).

## Separate the public contract from render-only structure

Expand Down Expand Up @@ -65,13 +65,13 @@ props that no later stage uses.

Primitives should define the smallest slot-compatible acceptance contract. For mutually exclusive sources, use a union
with `never` on incompatible fields, as
[`IconProps`](../../../../packages/agentic-components/src/primitives/icon/icon.types.ts) does for image, font, and SVG
[`IconProps`](../../../../packages/agentic/components/src/primitives/icon/icon.types.ts) does for image, font, and SVG
sources. Verify the primitive remains assignable to `SlotProp<typeof Primitive>` with a committed type test.

## Exports

Export each component and its composition pipeline explicitly from
[`src/index.ts`](../../../../packages/agentic-components/src/index.ts):
[`src/index.ts`](../../../../packages/agentic/components/src/index.ts):

- the component and its public props, slots, variants, and resolved state type
- the state hook as `use<Component>_unstable`
Expand Down
12 changes: 6 additions & 6 deletions .github/skills/agentic-component-optimization/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: agentic-component-optimization
description: Analyze and optimize packages/agentic-components as a whole when repeated patterns, dependency direction, or extraction boundaries cross components.
description: Analyze and optimize packages/agentic/components as a whole when repeated patterns, dependency direction, or extraction boundaries cross components.
license: MIT
---

Expand All @@ -12,11 +12,11 @@ primitive or helper should exist at all.

## Read first

1. Read `packages/agentic-components/AGENTS.md` and `packages/agentic-components/src/AGENTS.md`.
1. Read `packages/agentic/components/AGENTS.md` and `packages/agentic/components/src/AGENTS.md`.
2. Read the relevant component or primitive `AGENTS.md` file and the colocated `SPEC.md` files for the affected area.
3. Inspect the canonical implementations:
- `packages/agentic-components/src/components/button`
- `packages/agentic-components/src/primitives/icon`
- `packages/agentic/components/src/components/button`
- `packages/agentic/components/src/primitives/icon`

## Audit checklist

Expand All @@ -25,8 +25,8 @@ primitive or helper should exist at all.
- Production source may depend only on React / React Native native components, `@fluentui-react-native/design`, and
`@fluentui-react-native/framework-base`.
- Generalizable non-styling hooks belong in `framework-base/src/hooks`.
- Styling helpers belong in `agentic-design/src/styling`.
- Component-library-specific non-public types, constants, and helpers belong in `packages/agentic-components/src/common`.
- Styling helpers belong in `agentic/design/src/styling`.
- Component-library-specific non-public types, constants, and helpers belong in `packages/agentic/components/src/common`.

### 2. Repetition and ownership

Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ This is the **FluentUI React Native** repository, a monorepo containing React Na

**Slots**: The slot pattern is used to compose higher-order components. A slot represents an inner component (actual entry in the render tree). For example, a Button might have slots for `root`, `icon`, and `content`. This allows advanced customization scenarios. Components wrapping a single native component typically have one slot.

**Tokens**: Design tokens handle styling and customization. Tokens are design-time values set via theme or component customization (e.g., "brandColor"). Tokens can also be props (specified via "TokensThatAreAlsoProps"). This system enables simpler customization and better memoization. For Flex token authoring, use `packages/agentic-design/src/tokens/mappings/flex-token-map.yaml` as the canonical mapping from generic CSS and Fluent token sources to grouped React Native Flex token paths. When mapping an agentic component to an existing V1 component, use the Win32, macOS, or Windows implementation as the canonical compatibility reference; do not use iOS as the cross-platform canonical value unless the work explicitly targets iOS.
**Tokens**: Design tokens handle styling and customization. Tokens are design-time values set via theme or component customization (e.g., "brandColor"). Tokens can also be props (specified via "TokensThatAreAlsoProps"). This system enables simpler customization and better memoization. For Flex token authoring, use `packages/agentic/design/src/tokens/mappings/flex-token-map.yaml` as the canonical mapping from generic CSS and Fluent token sources to grouped React Native Flex token paths. When mapping an agentic component to an existing V1 component, use the Win32, macOS, or Windows implementation as the canonical compatibility reference; do not use iOS as the cross-platform canonical value unless the work explicitly targets iOS.

**Theme-specific styles**: Cache `StyleSheet.create` results that depend only on `ThemeState` with a module-scoped getter created by `themedStyleSheetFactory`. Treat them as immutable, and apply props, interaction state, and user styles separately so the cached sheet is safe to share between component instances.

Expand Down
2 changes: 1 addition & 1 deletion apps/storybook/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"repository": {
"type": "git",
"url": "https://github.com/microsoft/fluentui-react-native.git",
"directory": "packages/agentic-components/storybook"
"directory": "packages/agentic/components/storybook"
},
"scripts": {
"start": "rnx-cli start",
Expand Down
2 changes: 1 addition & 1 deletion apps/storybook/src/main.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import type { StorybookConfig } from '@storybook/react-native';
*/
const main: StorybookConfig = {
stories: [
'../../../packages/agentic-components/src/**/*.stories.?(ts|tsx)',
'../../../packages/agentic/components/src/**/*.stories.?(ts|tsx)',
'../../../packages/native/Callout/src/**/*.stories.?(ts|tsx)',
],
addons: [],
Expand Down
4 changes: 2 additions & 2 deletions apps/storybook/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,13 @@
"path": "../../packages/native/Callout/tsconfig.json"
},
{
"path": "../../packages/agentic-components/tsconfig.json"
"path": "../../packages/agentic/components/tsconfig.json"
},
{
"path": "../../packages/theming/default-theme/tsconfig.json"
},
{
"path": "../../packages/agentic-design/tsconfig.json"
"path": "../../packages/agentic/design/tsconfig.json"
},
{
"path": "../../packages/components/FocusZone/tsconfig.json"
Expand Down
2 changes: 1 addition & 1 deletion apps/tester-core/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
"path": "../../packages/theming/default-theme/tsconfig.json"
},
{
"path": "../../packages/agentic-design/tsconfig.json"
"path": "../../packages/agentic/design/tsconfig.json"
},
{
"path": "../../packages/components/Divider/tsconfig.json"
Expand Down
8 changes: 4 additions & 4 deletions docs/pages/Theming/CustomTheme.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ There are two ways to make a custom theme: you can tack onto an existing one usi

### Extending an existing `ThemeReference`

We have a concept of `ThemeRecipes` which allow for layering of partial theme objects to create the ultimately desired theme. `ThemeRecipes` are functions which take a `Theme` and spit out a [`PartialTheme`](../../../packages/agentic-design/src/theming/types/Theme.types.ts), which is then deep merged into the base theme object.
We have a concept of `ThemeRecipes` which allow for layering of partial theme objects to create the ultimately desired theme. `ThemeRecipes` are functions which take a `Theme` and spit out a [`PartialTheme`](../../../packages/agentic/design/src/theming/types/Theme.types.ts), which is then deep merged into the base theme object.

You can extend one of our default themes by creating a `ThemeReference` using the default theme as the base theme, and then add your customization as a `ThemeRecipe`:

Expand All @@ -35,7 +35,7 @@ const theme = new ThemeReference(createDefaultTheme(),

### `ThemeReference` from scratch

You can create your own `ThemeReference` and pass it into the `ThemeProvider`. To create a `ThemeReference` you'll need to create a new instance of `ThemeReference`. You can find the type definition [here](../../../packages/agentic-design/src/theming/themeReference.ts).
You can create your own `ThemeReference` and pass it into the `ThemeProvider`. To create a `ThemeReference` you'll need to create a new instance of `ThemeReference`. You can find the type definition [here](../../../packages/agentic/design/src/theming/themeReference.ts).

## Theme property customization

Expand All @@ -46,7 +46,7 @@ There's two ways to customize a FURN theme's properties:

### Changing theme tokens directly

Theme tokens can be overridden directly. You can specify different values for theme entries and add to the set of colors. You can see what can be overridden by looking at the [Theme type definition](../../../packages/agentic-design/src/theming/types/Theme.types.ts).
Theme tokens can be overridden directly. You can specify different values for theme entries and add to the set of colors. You can see what can be overridden by looking at the [Theme type definition](../../../packages/agentic/design/src/theming/types/Theme.types.ts).

This approach is useful if you need the customizations to be applied to all components.

Expand Down Expand Up @@ -161,7 +161,7 @@ interface Theme {
}
```

<font size=1>(Taken from the [`Theme` type definition](../../../packages/agentic-design/src/theming/types/Theme.types.ts).)</font>
<font size=1>(Taken from the [`Theme` type definition](../../../packages/agentic/design/src/theming/types/Theme.types.ts).)</font>

NOTE: If you would prefer to customize one instance of a FURN component instead, use [the customize API](../../../packages/framework/composition/README.md).

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/Theming/Tokens/Basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ export const defaultNotificationTokens: TokenSettings<NotificationTokens, Theme>

Notes about alias color tokens:

- Different platforms can have different sets of alias tokens; however, the entire set of alias tokens are all defined in the same interface. See [Color.types.ts](../../../../packages/agentic-design/src/theming/types/Color.types.ts#L861) for this interface and which platforms define which alias tokens.
- Different platforms can have different sets of alias tokens; however, the entire set of alias tokens are all defined in the same interface. See [Color.types.ts](../../../../packages/agentic/design/src/theming/types/Color.types.ts#L861) for this interface and which platforms define which alias tokens.
- As a result, if an alias token is referenced that does not exist for that platform, there won't be any compile-time or run-time errors. Instead, the color shown will default to black.

Special case: if accessing a specific color, you can find it in the `globalTokens.color` property.
Expand Down
Loading
Loading