docs: add headless component authoring skill by dmytrokirpa · Pull Request #36502 · microsoft/fluentui

Dmytro Kirpa (dmytrokirpa) · 2026-08-03T18:01:32Z

Summary

add a Copilot skill for authoring and extending headless v9 component primitives
document base-hook, data-attribute, packaging, bundle-size, test, Storybook, CSS Module, and accessibility requirements
define a two-PR gh stack workflow separating component-package base APIs from the dependent headless package
register the skill for Copilot and Claude entry points

Validation

verified all documented headless library, stories, and docsite Nx targets exist
verified installed gh stack and Beachball flags used by the workflow
checked skill metadata, mirror pointer, portable paths, and diff formatting

No Beachball change file is required because this change does not modify a published package.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 806b7b8e-562f-4b2a-b4f5-b9d06fc6131f

github-actions · 2026-08-03T18:04:17Z

📊 Bundle size report

✅ No changes found

github-actions · 2026-08-03T18:05:15Z

Pull request demo site: URL

Victor Genaev (mainframev) · 2026-08-06T07:58:17Z

+6. Record every inventory row as implemented, intentionally excluded with a
+   source-backed reason, or unresolved. Trace implemented rows through:
+   `types/exports -> hook/context -> rendered DOM/slots -> test or story`.
+7. Plan the change as two stacked PRs before editing:


if we need regression test for styled hook, then it should be 3 separate PRs, do you think we should have that covered by skill too?

I think this should be a mandatory preflight

Victor Genaev (mainframev) · 2026-08-06T08:00:06Z

+- When adding a new v9 base hook, follow the repository-enforced signature:
+  `useComponentNameBase_unstable(props, ref?)`, with an explicitly typed
+  `props` parameter and `ref` typed as `React.Ref<...>`.
+- Keep base hooks free of Tabster and other forbidden focus/keyboard runtimes.


should we mention that icons should not be part of base hooks & bundleIcon on module level?

we have all of these as part of harness now, wondering if agent would recover when failing lint/verify-bundle task

wondering if this would do the job most determinstically:

- Generate new control via `nx .....` - Make sure `lint` targets and `verify-bundle-isolation` are passing

Victor Genaev (mainframev) · 2026-08-06T08:02:07Z

+State attributes are the supported CSS targeting contract.
+
+- Presence state: emit `''` when true and omit when false.
+- Boolean-valued state: emit `'true'` or `'false'` when both values are


should not it also following presence / absence approach?

confused what is our pattern ? we agreed on absence api for boolean but I saw in Victor Genaev (@mainframev) we are doing true :D ?

Victor Genaev (mainframev) · 2026-08-06T08:11:12Z

+6. Add a default story plus stories for important behavioral states.
+7. Exercise the primary interaction instead of rendering only static variants.
+   Interactive stories should drive the real component behavior and assert the
+   resulting role/ARIA/data state in a `play` function. Cover the inverse action


AFAIR we do not use play functions, that was probably migrated from the 1JS skill, right?

from CompoundButton PR:

Victor Genaev (mainframev) · 2026-08-06T08:15:25Z

+  --package @fluentui/react-<name> --type minor \
+  --message "feat(react-<name>): expose headless base APIs"
+
+# top branch, after editing only the headless library and stories


we should correct a bit these examples with beachball instructions as we following zero based semver for headless until we are stable

Victor Genaev (mainframev) · 2026-08-06T08:17:35Z

+  `yarn beachball change` form; never create or edit them manually.
+- After generation, inspect the new JSON file and verify it contains exactly the
+  owning package and no inherited package from another stack layer.
+- New public base exports and new headless primitives are normally `minor`


here we should also correct it, it will be correct later when headless will become stable

Victor Genaev (mainframev) · 2026-08-06T13:56:21Z

+
+### Renderer and Context
+
+- Re-export or alias the upstream unstable renderer when its slot structure is


maybe some examples needed, I see that for CompoundButton it created it in a following format, instead of one line re-export:

import { renderCompoundButton_unstable } from '@fluentui/react-button'; /** * Renders a CompoundButton component. */ export const renderCompoundButton = renderCompoundButton_unstable;

Victor Genaev (mainframev) · 2026-08-06T14:08:01Z

+# top branch, after editing only the headless library and stories
+yarn beachball change --no-commit --branch master \
+  --package @fluentui/react-headless-components-preview --type minor \
+  --message "feat(react-headless-components-preview): add <ComponentName>"


Suggested change

--message "feat(react-headless-components-preview): add <ComponentName>"

--message "feat: add <ComponentName>"

I think we can omit the package scope in message as change file has packageName

Victor Genaev (mainframev) · 2026-08-07T19:33:27Z

+### Component-Package PR
+
+- Inspect `packages/react-components/react-<name>/library/bundle-size/`.
+- Every new public runtime export must be referenced by a bundle fixture. Named


with the skill running for a component it created fixtures for base hooks, probably we should explicitly mention that bundle fixture should be added to components only

Copilot

Pull request overview

Adds guidance for authoring and extending headless Fluent UI v9 components.

Changes:

Documents implementation, testing, packaging, and accessibility requirements.
Defines stacked-PR and validation workflows.
Registers the skill for Copilot and Claude.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
`AGENTS.md`	Registers the new slash command.
`.agents/skills/headless-component/SKILL.md`	Defines the authoring workflow and requirements.
`.claude/skills/headless-component/SKILL.md`	Adds the Claude skill pointer.

Suppressed comments (3)

.agents/skills/headless-component/SKILL.md:467

Headless and v9 stories intentionally keep interaction assertions in tests rather than Storybook play functions. Requiring play here would make generated stories violate that convention; keep the story interactive/demonstrable and put the role, ARIA, data-state, and inverse-action assertions in unit or Cypress coverage.

7. Exercise the primary interaction instead of rendering only static variants.
   Interactive stories should drive the real component behavior and assert the
   resulting role/ARIA/data state in a `play` function. Cover the inverse action
   too; if the behavior requires a real browser primitive unavailable to the
   Storybook test runner, cover it in Cypress and keep the story demonstrable.

.agents/skills/headless-component/SKILL.md:571

This preview package is currently 0.2.4 and follows zero-semver: new headless components have shipped as patches (for example TagPicker and MenuButton in library/CHANGELOG.md:12-28). minor would incorrectly advance 0.2.x to 0.3.0 for a normal additive primitive.

yarn beachball change --no-commit --branch master \
  --package @fluentui/react-headless-components-preview --type minor \
  --message "feat(react-headless-components-preview): add <ComponentName>"

.agents/skills/headless-component/SKILL.md:591

This rule incorrectly assigns minor to new primitives in the 0.x headless preview package. Keep minor for new exports in stable v9 component packages, but use patch for additive headless-preview APIs under its zero-semver policy; otherwise future skill runs will create the wrong release bump.

- New public base exports and new headless primitives are normally `minor`
  changes. Use `patch` only when correcting an existing contract without adding
  public API, and never use `major` without explicit approval.

+7. Plan the change as two stacked PRs before editing:
+   - **bottom PR — component package:** base hook/types/renderer/context exports
+     and their package-local tests, API docs, bundle-size coverage, manifest
+     updates, and change file
+   - **top PR — headless package:** stable headless primitive, `data-*`


Martin Hochel (Hotell) · 2026-08-10T09:00:50Z

+# bottom branch, after editing only the component package
+yarn beachball change --no-commit --branch master \
+  --package @fluentui/react-<name> --type minor \
+  --message "feat(react-<name>): expose headless base APIs"


Martin Hochel (Hotell) · 2026-08-10T08:52:01Z

+6. Record every inventory row as implemented, intentionally excluded with a
+   source-backed reason, or unresolved. Trace implemented rows through:
+   `types/exports -> hook/context -> rendered DOM/slots -> test or story`.
+7. Plan the change as two stacked PRs before editing:


I think this should be a mandatory preflight

Martin Hochel (Hotell) · 2026-08-10T08:54:03Z

+Add `*.cy.tsx` integration coverage when behavior depends on real browser focus,
+Tabster, positioning, portals, native popovers, or nested trigger composition.
+
+## Implementation


should we just wire a generator for this ?

Martin Hochel (Hotell) · 2026-08-10T08:55:09Z

+- When adding a new v9 base hook, follow the repository-enforced signature:
+  `useComponentNameBase_unstable(props, ref?)`, with an explicitly typed
+  `props` parameter and `ref` typed as `React.Ref<...>`.
+- Keep base hooks free of Tabster and other forbidden focus/keyboard runtimes.


we have all of these as part of harness now, wondering if agent would recover when failing lint/verify-bundle task

Martin Hochel (Hotell) · 2026-08-10T08:56:57Z

+- When adding a new v9 base hook, follow the repository-enforced signature:
+  `useComponentNameBase_unstable(props, ref?)`, with an explicitly typed
+  `props` parameter and `ref` typed as `React.Ref<...>`.
+- Keep base hooks free of Tabster and other forbidden focus/keyboard runtimes.


wondering if this would do the job most determinstically:

- Generate new control via `nx .....` - Make sure `lint` targets and `verify-bundle-isolation` are passing

Martin Hochel (Hotell) · 2026-08-10T08:58:04Z

+State attributes are the supported CSS targeting contract.
+
+- Presence state: emit `''` when true and omit when false.
+- Boolean-valued state: emit `'true'` or `'false'` when both values are


confused what is our pattern ? we agreed on absence api for boolean but I saw in Victor Genaev (@mainframev) we are doing true :D ?

Martin Hochel (Hotell) · 2026-08-10T09:00:50Z

+# bottom branch, after editing only the component package
+yarn beachball change --no-commit --branch master \
+  --package @fluentui/react-<name> --type minor \
+  --message "feat(react-<name>): expose headless base APIs"


Martin Hochel (Hotell) · 2026-08-10T09:02:40Z

+| Skill                | Command                    | Purpose                                                                   |
+| -------------------- | -------------------------- | ------------------------------------------------------------------------- |
+| `v9-component`       | `/v9-component Name`       | Scaffold a new v9 component with all required files                       |
+| `headless-component` | `/headless-component Name` | Author an unstyled v9 primitive with state attributes, tests, and stories |


if we have this we should consider to disable model invocation on the headless skill completely

docs: add headless component authoring skill

b2bb0cb

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 806b7b8e-562f-4b2a-b4f5-b9d06fc6131f

Dmytro Kirpa (dmytrokirpa) requested a review from a team as a code owner August 3, 2026 18:01

Dmytro Kirpa (dmytrokirpa) self-assigned this Aug 3, 2026

Tudor Popa (tudorpopams) requested review from Martin Hochel (Hotell), PaulGMardling, Victor Genaev (mainframev), Paolo Aliprandi (paolo-aliprandi) and Tudor Popa (tudorpopams) August 4, 2026 12:07

Dmytro Kirpa (dmytrokirpa) added 2 commits August 4, 2026 17:11

Merge branch 'master' into dmytrokirpa/headless-component-skill

b41305b

Merge branch 'master' into dmytrokirpa/headless-component-skill

6da99ab

Victor Genaev (mainframev) reviewed Aug 6, 2026

View reviewed changes

Victor Genaev (mainframev) reviewed Aug 7, 2026

View reviewed changes

Dmytro Kirpa (dmytrokirpa) requested a balanced review from Copilot August 7, 2026 20:56

Copilot started reviewing on behalf of Dmytro Kirpa (dmytrokirpa) August 7, 2026 20:57 View session

Copilot AI reviewed Aug 7, 2026

View reviewed changes

Martin Hochel (Hotell) reviewed Aug 10, 2026

View reviewed changes


		### Renderer and Context

		- Re-export or alias the upstream unstable renderer when its slot structure is

	--message "feat(react-headless-components-preview): add <ComponentName>"
	--message "feat: add <ComponentName>"

Uh oh!

Conversation

Dmytro Kirpa (dmytrokirpa) commented Aug 3, 2026

Summary

Validation

Uh oh!

github-actions Bot commented Aug 3, 2026

📊 Bundle size report

Uh oh!

github-actions Bot commented Aug 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Victor Genaev (mainframev) Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Victor Genaev (mainframev) Aug 6, 2026 •

edited

Loading