Components: Generate Scrollbar

Summary

Generate Scrollbar with its canonical contract, implementation, tests, stories, platform validation, and explicit package export so scroll position can be represented consistently. Generation alone cannot resolve this task: the web-authored overflow model must be retargeted and the Windows/macOS native-versus-composed implementation boundary decided first.

Observed. scrollbar is entry scrollbar in the canonical catalog and has no
implementation in packages/agentic/components. Upstream describes it as: Visual indicator reflecting current scroll position and the proportion of visible content inside an overflowing container. Covers orientation, thumb anatomy, and an implicit-track model where the scroll container's overflow lane substitutes for a rendered track.

Goal

Generate the scrollbar component in
packages/agentic/components/src/components against the
canonical Fluent Flex spec, with the colocated coverage, stories, and platform
validation the package requires, and export it explicitly from
src/index.ts.

Stage

Stage 3 (production). Wave 4 - platform or native decision required.

Why it matters

Observed. The canonical catalog has 50 components and the agentic library has
generated 18. scrollbar is one of the 32 in the gap, enumerated in
the missing-components index.

Inferred. It cannot be resolved by generation alone. Leaving it undecided keeps the catalog reconciliation permanently incomplete.

Observed current state

Canonical spec and source

Field	Value
Canonical spec	plugins/components/skills/scrollbar/SKILL.md with usage.md, web/tokens.yaml, web/accessibility.md, and web/interaction.md, at x3-design/fluent-design @ d334acf
Upstream tier	atom
Upstream catalog key	scrollbar in component-map.yaml
Local staged spec	packages/agentic/components/specs/scrollbar - SPEC.md, usage.md, interaction.md, accessibility.md, tokens.yaml, blockers.md
Local implementation	None. No src/components/scrollbar directory exists

Closest existing FURN or V1 implementation

• No scrollbar exists in any FURN catalog.

Note on platform canon. Where a legacy package has platform-specific files, the
desktop path (.win32, .windows, .macos, or the unsuffixed cross-platform file)
is the compatibility reference. .ios, .android, and .mobile variants are not
treated as the cross-platform canonical implementation.

Local dependencies

• No generated agentic component is required as a direct dependency.

Known blockers

Observed (blockers.md, blocker class C in the index).

Recorded as blocked because the spec depends on native scroll-container behavior and live scroll metrics; React Native's public ScrollView API exposes only showsVerticalScrollIndicator, showsHorizontalScrollIndicator, indicatorStyle, and scrollIndicatorInsets, and does not expose the tokenized thumb thickness, radius, or overlay fade behavior the spec describes; and the show/hide and drag-to-scroll behavior needs scroll-start, scroll-idle, and pointer-capture hooks that would require a native host component.

Reassessment.

Fully valid. Nothing has changed. The blocker file itself lists the three prerequisites: a public API for the scroll source and live metrics, a native or platform-specific scrollbar host, and updated spec props matching the supported platform API. Inferred: this is a native-work decision, not a generation task.

Scope

• The first deliverable is a decision, not an implementation: implement with a native host component per platform, ship a reduced React Native approximation with the spec retargeted, or decline the component and record the rationale in the catalog reconciliation.
• If native work is chosen, it follows the Windows Fabric native component reference and inherits the risks catalogued in focus-zone.md, which would be the repository's first Windows Fabric native component.
• Record the decision, its rationale, and its consequences in
  the missing-components index catalog reconciliation, whichever way it
  goes. Declining is an acceptable outcome; leaving it unrecorded is not.

If, and only if, the decision is to implement, the remaining scope is the standard
generation scope:

• Ingest or promote the spec into the component directory in the generated shape
  (SPEC.md plus a spec/ folder), per
  spec-ingestion-and-generation.md.
• Establish the public contract first: variants, slots, native props, accessibility,
  interaction states, and platform behavior.
• Implement the required file structure from
  src/components/AGENTS.md:
  scrollbar.types.ts, scrollbar.styles.ts, use*.ts, use*Styles.ts, render*.tsx, and
  the assembly module with a displayName.
• Style from Flex tokens first and record genuine token gaps rather than substituting
  unrelated values.
• Export the component, its public types, and the state, style, and render stages
  explicitly from src/index.ts under component-qualified unstable names.

Out of scope

• Changing the contract of an existing generated component, unless this task explicitly
  calls for it above; raise it as its own item.
• Building shared infrastructure owned by another task: overlay hosting
  (popover), roving focus (focus-zone.md), spec
  ingestion (spec-ingestion-and-generation.md),
  or the coverage contract (component-test-strategy.md).
• Migrating any legacy FURN consumer onto this component.
• Mobile platform support; the applicable upstream companion is web, retargeted to
  React Native for Windows and macOS.

Deliverables

• src/components/scrollbar/ implementing the full required file structure.
• SPEC.md and a spec/ companion folder with provenance recording the upstream path,
  SHA, and ingestion date.
• Colocated scrollbar.test.tsx, scrollbar.types.test.ts, and scrollbar.stories.tsx.
• Snapshot coverage where the visual contract is state-dependent, or a recorded
  exemption.
• Explicit exports from src/index.ts, with src/index.test.ts updated.
• A changeset, per the repository's version management rules.
• A recorded readiness level with its supporting evidence.

Required coverage, stories, and platform validation

Runtime and type coverage:

• Only meaningful once the decision is made. If implemented: both orientations, thumb geometry against the content ratio, show and hide behavior, and drag-to-scroll, each validated on macOS and on Windows Fabric because the underlying scroll behavior differs.
• User style and handler forwarding, and that user styles are applied after component
  styles.
• Compile-time slot acceptance and any mutually exclusive props.

Stories: a typed Meta titled Components/Scrollbar, an args-driven Default, a
grouped Overview when the contract has several axes, one focused story per variant
axis, and an interactive story for each stateful axis. Self-driving axes expose
default<State> as the control; externally driven selection is owned by the story with
React.useState. Identity-changing axes are not exposed as controls.

Platform validation: the component's stories render and behave correctly on macOS
and on React Native Windows Fabric through apps/storybook,
including hover, pressed, disabled, focus, optional-slot, and constrained-content
scenarios. Add a stable root testID if the component joins the automated smoke set.

Acceptance criteria

• The implement, approximate, or decline decision is made and recorded, with its rationale.
• The decision explicitly addresses what upstream says this component exists to provide, so the trade-off being accepted is visible.
• The catalog reconciliation in the missing-components index reflects the outcome.

If the decision is to implement, the standard generation criteria also apply:

• src/components/scrollbar exists with the required file structure and a displayName.
• Every variant axis in the component's SPEC.md is implemented, or a deviation is recorded in the spec.
• The component styles from Flex tokens, with any genuine token gap recorded rather than approximated.
• Focus feedback renders through FocusVisual; no outline* props and no React Native Windows native focus visuals are introduced.
• State precedence is explicit: disabled wins over pressed, which wins over hovered.
• Every stateful axis is classified as self-driving or externally driven, and both paths are covered.
• Runtime, type, and story coverage satisfy the package coverage contract.
• The component, its public types, and its pipeline stages are exported explicitly from src/index.ts, and src/index.test.ts covers them.
• The component's stories render on macOS and on React Native Windows Fabric.
• yarn workspace @fluentui-react-native/components format, lint, build, and test pass, and the Storybook bundle succeeds for both desktop platforms.
• A readiness level is recorded with its supporting evidence.
• A changeset is included.

Dependencies and ordering

• Not a beta blocker. This task must reach a recorded decision before production, but it does not gate the beta catalog.
• If native work is chosen, blocked by focus-zone.md, which establishes the repository's first React Native Windows Fabric native component and its build, autolinking, and CI path.
• Gated by component-test-strategy.md: the component must satisfy the coverage contract on arrival rather than being retrofitted.
• Gated by readiness-model.md: the target readiness level must be stated before the work starts.
• Consumes the Infrastructure workstream (storybook-e2e.md) for automated macOS and Windows Fabric validation; until it lands, platform validation is manual.

Risks and open decisions

1. Declining is a legitimate outcome. The upstream spec explicitly says the thumb should mirror native scrolling, which is arguably already what React Native's built-in indicators do.
2. A native scrollbar host is a large amount of platform work for a component whose value over the platform default is mostly tokenized appearance.

Evidence and references

• Upstream spec: plugins/components/skills/scrollbar/SKILL.md and
  components-index/SKILL.md
  at x3-design/fluent-design @ d334acf.
• Local staged spec and blocker record: packages/agentic/components/specs/scrollbar.
• Canonical implementations to follow: src/components/button
  for a styled higher-order component and src/primitives/icon
  for a primitive.
• Authoring rules: src/components/AGENTS.md and the
  agentic component authoring skill.
• Workstream context: Components README and
  the missing-components index.

Sources retrieved 2026-08-20.

Start with packages/agentic/components/specs/scrollbar/blockers.md and the canonical scrollbar SKILL.md, then review the missing-components index and the Windows Fabric native component reference. Decide whether to implement natively, retarget to a reduced approximation, or decline; record the rationale and consequences in issue 4273. If implementation is chosen, use src/components/AGENTS.md and validate the required tests and stories on macOS and Windows Fabric.