Generated button + updated component authoring skill and instructions (#4176)

* add fluent style slot behaviors

* update component types and slot implementations

* fix bugs around slot types and jsx spreading

* remove extra file from this branch

* clean up slot types

* update instructions and fix typing issues with usePressableState

* consolidate on useSlot and useOptionalSlot

* consolidate old and new slot patterns into a core set of APIs

* sanitize exports and mark internal only routines more clearly

* add changeset

* add v0 and v1 instruction files

* move button spec into the button component directory

* initial button seeding

* rename button from tsx to ts

* colocate the SPEC.md file with the component

* first draft with the agent driven build

* move Icon to primitives rather than components to distinguish patterns

* update structure of flex tokens to optimize usage

* combine mappings into new yaml file and update instructions

* update lockfile and metro config

* fix flex style mapping error

* work in progress changes for styling

* more modifications for component building

* in progress changes

* rework of the color/style factory helpers

* apply branchedStyle helpers to components

* rework styles with new instructions

* add change file

* fix storybook build, optimize instructions

* update storybook guidance and add stories

* fix styling bugs and enhance Icon stories

* restructure authoring skill to use sub-references

Author: JasonVMo

.changeset/calm-pumas-group.md

@@ -0,0 +1,5 @@
+---
+"@fluentui-react-native/design": minor
+---
+
+Group Flex tokens by category and remove category prefixes from individual token names

.changeset/few-zebras-love.md

@@ -0,0 +1,8 @@
+---
+"@uifabricshared/foundation-compose": patch
+"@fluentui-react-native/framework": patch
+"@fluentui-react-native/design": patch
+"@fluentui-react-native/framework-base": patch
+---
+
+Updated packages with agent instructions and type fixes

.github/skills/agentic-component-authoring/SKILL.md

@@ -0,0 +1,53 @@
+---
+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.
+license: MIT
+---
+
+# Agentic component authoring
+
+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).
+- Primitive components live in `src/primitives`. Read the
+  [primitive instructions](../../../packages/agentic-components/src/primitives/AGENTS.md).
+- 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.
+
+## Load focused references
+
+| Work                                                                                | Reference                                                        |
+| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Public props, slots, state types, native prop exposure, or exports                  | [Types and slots](references/types-and-slots.md)                 |
+| Defaults, derived state, interaction hooks, accessibility, or slot construction     | [State and accessibility](references/state-and-accessibility.md) |
+| Tokens, style factories, theme caching, state precedence, or slot style application | [Styles and tokens](references/styles-and-tokens.md)             |
+| Pure slot rendering, component assembly, or display names                           | [Rendering and assembly](references/rendering.md)                |
+| Runtime tests, type tests, snapshots, Storybook stories, or validation              | [Tests and stories](references/tests-and-stories.md)             |
+
+A new higher-order component normally needs every reference. A focused fix should load only the affected reference and
+its immediate neighbors. Keep the component's colocated `SPEC.md` and companion files authoritative for its contract.
+
+## Workflow
+
+1. Read the repository and package instructions, the component `SPEC.md`, and every companion file referenced by the
+   spec.
+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.
+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,
+   component assembly, and explicit exports.
+5. Preserve the specification. Record a genuine token or platform gap rather than substituting an unrelated value or
+   web-only behavior.
+6. Add focused tests and stories that exercise the public API and the resolved native output.
+7. Run the smallest declared validation command while iterating. Finish with package format, lint, build, and tests; run
+   the Storybook bundle for story changes and the root build when public types, manifests, or project references change.
+
+Do not divide one component implementation into separate sub-agent or sub-skill phases. Its types, state, styling, and
+rendering form one contract and should remain in one implementation context.

.github/skills/agentic-component-authoring/references/rendering.md

@@ -0,0 +1,72 @@
+# Rendering and assembly
+
+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).
+
+## Keep render functions pure
+
+The render function receives resolved state and returns the final element tree.
+
+- Add `/** @jsxImportSource @fluentui-react-native/framework-base */` when rendering slot components.
+- Do not call hooks.
+- Do not read themes or tokens.
+- Do not create styles.
+- Do not reinterpret defaults or accessibility.
+- Do not mutate slot props.
+
+All those decisions belong to earlier stages.
+
+## Render slot functions directly
+
+Capitalize local optional slot variables when that improves readability. Render required roots through the state slot:
+
+```tsx
+return <state.root>{content}</state.root>;
+```
+
+Keep slot order visible in JSX. Button renders its active icon before or after content according to `iconPosition`.
+Avoid array construction or opaque helper loops when direct JSX makes the public ordering contract clearer.
+
+## Resolve conditional structure from state
+
+The render function may select among already-resolved slots and compose conditional layout:
+
+- Button chooses `selectedIcon` when selected and falls back to `icon`.
+- Toggle content uses the private container, hidden ghost, and visible label.
+- Ordinary content renders without that wrapper.
+
+Do not create missing slots in the render stage. If a structural element can exist, represent it in the state type and
+construct it in the state hook.
+
+Components that own children should render only their declared slots. Do not spread native `children` into the tree and
+let consumers bypass slot order.
+
+## Assemble the component in one small file
+
+`<component>.ts` should show the pipeline without embedding stage logic:
+
+```ts
+export const Component = (props: ComponentProps) => {
+  const state = useComponent_unstable(props);
+  useApplyStyles_unstable(state);
+  return renderComponent_unstable(state);
+};
+```
+
+Set `displayName` for diagnostics and Storybook metadata. Keep unstable stage functions named consistently so tests and
+future composition work can identify them. Do not wrap the component in memoization or another boundary without measured
+need and repository precedent.
+
+After assembly, update the package public surface according to the
+[types and slots export rules](types-and-slots.md#exports).
+
+## Review checklist
+
+- Render contains JSX and conditional structure only.
+- Slot order matches the spec.
+- Optional and replacement slots fall back intentionally.
+- State-only structure does not leak into public props.
+- The assembly file is a readable state -> styles -> render pipeline.
+- `displayName` is present and the public surface follows the types and slots export rules.

.github/skills/agentic-component-authoring/references/state-and-accessibility.md

@@ -0,0 +1,98 @@
+# State and accessibility
+
+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).
+
+## State hook responsibilities
+
+The state hook owns:
+
+1. Destructuring component-owned props while preserving unhandled native props.
+2. Applying behavioral defaults.
+3. Deriving facts needed by accessibility, styles, and rendering.
+4. Validating development-time usage.
+5. Reading theme state.
+6. Configuring the native interaction hook.
+7. Constructing required and optional slots.
+8. Returning one complete resolved state object.
+
+Do not resolve token styles or render elements in this hook.
+
+## Preserve raw presence before applying defaults
+
+Derive presence-sensitive behavior from raw props. Button computes `hasContent`, `hasIcon`, and `hasSelectedIcon` before
+constructing slots. It uses those values to derive `iconOnly`, while `selected !== undefined` determines whether toggle
+semantics are enabled even when `selected` is false.
+
+Apply context-sensitive defaults only after those facts are known. Button defaults shape to `circle` for icon-only use
+and `rounded` otherwise.
+
+## Merge accessibility deliberately
+
+Start with consumer-provided accessibility state, then apply component-owned semantics:
+
+```ts
+accessibilityState: {
+  ...accessibilityState,
+  disabled,
+  ...(isToggle && { checked: selected }),
+}
+```
+
+The component must own its role and state semantics while preserving unrelated consumer values such as `busy`.
+
+- Set the native role explicitly.
+- Keep disabled state, focusability, and interaction behavior consistent.
+- Prefer a consumer-provided `accessible` or `focusable` value only when it does not violate the component contract.
+- Add selected or checked semantics only when the corresponding behavior is enabled.
+- Use action-oriented accessible names for icon-only controls.
+
+Button warns in development when an icon-only instance lacks an `accessibilityLabel`. Put warnings in an effect so
+render remains free of observable side effects, and make the dependency list match every value used by the warning.
+
+## Use framework interaction and slot hooks
+
+Interactive roots should use the framework state hook, such as `usePressableState`, so hovered, pressed, and focused
+state is normalized and user handlers are forwarded.
+
+Construct slots after native props are resolved:
+
+- `useSlot` for the required root.
+- `useOptionalSlot` for optional public slots.
+- `useOptionalSlot` for private state-only slots when their condition is active.
+
+Pass `null` for a slot that must not exist. Do not create a placeholder slot and hide it later with styles.
+
+Button constructs its hidden Semibold content and content container only when toggle behavior and visible content require
+them. This keeps ordinary buttons free of the extra structure.
+
+## Return stable resolved state
+
+Return:
+
+- slot functions
+- required variant values
+- derived state
+- preserved user styles
+- theme state
+- interaction state
+
+Keep property ordering intentional so later spreads cannot silently replace component-owned values. If two state sources
+can share a key, assign the final owned value explicitly after spreading.
+
+## Platform behavior
+
+Keep platform-specific native imports out of shared files when React Native forks expose incompatible types. Put fork
+imports in platform files or redeclare a small platform-neutral contract. Surface unsupported platform behavior rather
+than silently pretending it succeeded.
+
+## Review checklist
+
+- Defaults match the spec and depend on already-derived facts.
+- Omitted controlled props retain their meaning.
+- User native handlers and unrelated accessibility state are preserved.
+- Disabled, focusable, and selected semantics agree.
+- Icon-only or unlabeled usage is diagnosed consistently.
+- Optional slots exist only when their render condition is active.
+- The hook contains no token style selection and no JSX rendering.

.github/skills/agentic-component-authoring/references/styles-and-tokens.md

@@ -0,0 +1,139 @@
+# Styles and tokens
+
+Use this reference for `<component>.styles.ts`, `useApplyStyles.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
+[`useApplyStyles.ts`](../../../../packages/agentic-components/src/components/button/useApplyStyles.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
+value.
+
+- Read semantic colors from `useThemeState().tokens.color`.
+- Read grouped categories from `tokens.borderRadius`, `tokens.spacing`, `tokens.strokeWidth`, `tokens.fontFamily`,
+  `tokens.fontSize`, `tokens.fontWeight`, `tokens.lineHeight`, and `tokens.shadow`.
+- Prefer Flex tokens for every mapped semantic value.
+- Import named global tokens only when Flex has no equivalent, such as current Button icon dimensions or a true zero.
+- Record a genuine token gap in the component spec. Do not replace it with a nearby token or numeric literal.
+
+## Build styles in layers
+
+Use four layers:
+
+1. A module-scoped `StyleSheet` for structural values that do not depend on theme, props, or state.
+2. Module-scoped state factories for theme-independent state selectors.
+3. Module-scoped themed factories for token-derived styles.
+4. Per-instance style arrays that select cached objects and place user styles last.
+
+Never create a style factory inside a hook or render function.
+
+Reuse the package's existing factory utilities:
+
+- [`getStateStyleFactory`](../../../../packages/agentic-components/src/utils/branchedStyle.ts) lazily flattens and caches
+  one theme-independent state definition.
+- [`getThemedStateStyleFactory`](../../../../packages/agentic-components/src/utils/branchedStyle.ts) resolves and caches
+  one flattened definition per `ThemeState`.
+- [`getThemedColorStyleFactory`](../../../../packages/agentic-components/src/utils/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
+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,
+and user styles must remain outside the cache so one component instance cannot leak into another.
+
+## Declare state hierarchy and precedence
+
+Represent related axes as ordered hierarchy levels. Each level contains mutually exclusive states in priority order.
+Button colors use:
+
+```ts
+[['primary', 'secondary', 'outline', 'subtle'], ['selected'], ['disabled', 'pressed', 'hovered']];
+```
+
+This means appearance is the base branch, selected refines it, and interaction is the final refinement. Put interaction
+states in `disabled`, `pressed`, `hovered` order so the first active state has the required priority.
+
+Use `getThemedStateStyleFactory` for token-derived hierarchy definitions and `getStateStyleFactory` for
+theme-independent definitions. Use `getThemedColorStyleFactory` for semantic background, border, and foreground colors;
+it automatically resolves `tokens.color.hover` and `tokens.color.pressed` for inherited semantic keys.
+
+An interaction may intentionally switch semantic keys. Button Subtle is transparent at rest but explicitly selects
+`backgroundNeutralSubtle` inside hovered and pressed branches. Button Outline uses `strokeNeutralLoud`, whose hover and
+pressed token values provide visible stroke feedback. Do not assume a token named `Transparent` will produce visible
+interaction states; verify the resolved token maps.
+
+Build the state source from resolved state without hiding precedence in conditionals. Button pushes appearance, selected,
+disabled, pressed, and hovered values, then lets the declared hierarchy select the winner.
+
+## Group related layout axes
+
+Combine axes that produce one coherent style object. Button selects size, shape, and content layout from one root style
+hierarchy:
+
+```ts
+[
+  ['small', 'medium', 'large'],
+  ['rounded', 'square', 'circle'],
+  ['withContent', 'iconOnly'],
+];
+```
+
+Use separate factories for independent concerns such as typography, focus, and content visibility. This keeps unrelated
+state branches from multiplying into one large definition.
+
+Destructure only the token groups needed by a factory:
+
+```ts
+({ borderRadius, spacing, strokeWidth }: FlexTokens) => ...
+```
+
+Validate token values when their generated type is wider than the React Native style property. Button validates its gap
+token before assigning it to `ViewStyle['gap']`.
+
+## Apply slot props in one stage
+
+`useApplyStyles.ts` should select styles and call `attachSlotProps`; it should not create factories.
+
+Compose root styles in this order:
+
+1. structural style
+2. resolved layout or variant style
+3. semantic colors
+4. focus or other conditional styles
+5. user style
+
+Derive dependent slot props from the same resolved values. Button applies foreground color and size to both icon slots,
+marks decorative icons inaccessible, and applies typography plus foreground color to content.
+
+Preserve consumer slot behavior unless the component owns it. Button no longer forces `numberOfLines`; its content and
+toggle container use `flexShrink` so constrained labels can wrap. A consumer can still request truncation through the
+content slot.
+
+## Selected text without layout shift
+
+When selected text changes weight:
+
+- Render an inaccessible Semibold ghost that reserves width and height.
+- Overlay the visible label.
+- Keep the ghost and container state-only.
+- Apply the same wrapping constraints to both labels.
+
+Button uses theme-independent visibility selectors for the hidden and overlaid styles and token-derived typography for
+the actual font metrics.
+
+## Review checklist
+
+- Every value comes from Flex or a documented token gap.
+- Structural, themed, instance, and user styles are separated.
+- Every factory is module-scoped and theme-safe.
+- State hierarchy makes precedence explicit.
+- Hover and pressed values are verified, not inferred from token names.
+- Independent concerns use independent factories.
+- User styles are last.
+- Slot props share resolved color and size values consistently.
+- Constrained text can wrap unless truncation is an explicit public choice.