implement-native-component

Implement native components and modules

Use this skill directly for native work, or as an overlay when a v0, v1, or agentic change touches a native boundary. The native components and modules reference defines ownership and qualification rules (R-NATIVE-001 through R-NATIVE-003).

Workflow

1. Classify the work:
   • native kind: view component, TurboModule, or native service;
   • target platforms and renderers: macOS Paper or Fabric, React Native Windows Fabric, Win32 host-provided views, iOS, or Android;
   • the JavaScript wrapper's generation and public compatibility, using the classification guide;
   • native registration names and entrypoints that must not change.
2. Choose ownership. New modern native code belongs in native-core (R-NATIVE-001); maintain existing native wrappers, such as experimental packages, where they live. For native-core work, start from its package instructions and read the relevant native-core references; for a wrapper in another package, read that package's sources and documentation instead.
3. Load only the platform references the work needs:
   • React Native Windows Fabric views: Windows Fabric;
   • any iOS or macOS Swift, Objective-C, header, podspec, or bridge-manager change: Apple native authoring and Office integration (R-APPLE-001 through R-APPLE-007), plus native-core's native layout and Swift interoperability notes for native-core work;
   • focus targets or native focus visuals: common focus authoring and its platform file;
   • accessibility actions: framework-base accessibility reference;
   • the JavaScript wrapper: the agentic skill, v0 recipe, or v1 recipe.
4. Implement with the TypeScript specification, codegen configuration, native props, events, commands, and registration kept consistent. Preserve public APIs and registration names (R-NATIVE-002) and keep fork imports in platform files (R-REPO-002).
5. Validate the affected boundary with declared scripts (R-VALID-001), running focused package tests while iterating (R-VALID-004): package build, test, and lint; native-core yarn codegen:windows --check when Windows specs change and yarn test:apple-integration when its macOS native code changes; native builds through the owning app, such as yarn storybook build --macos or --windows from apps/storybook; and runtime evidence through Storybook smoke or wdio story tests. macOS Storybook commands default to Fabric: add --paper to prep, build, run, or smoke for Paper, and rerun prep when switching renderers. Desktop Storybook does not build iOS: validate iOS-only changes through the owning iOS host, such as FluentTester's iOS app in apps/fluent-tester. Apple changes also need the module and bridging-header checks in R-APPLE-007. Run Pod operations only as the permissions reference allows.
6. Report each platform and renderer as passed, failed, skipped, not run, or unsupported, with reasons (R-NATIVE-003).
7. Finish with yarn clean-lage-cache and then yarn lage buildci (R-VALID-003).

Storybook application or toolchain failures that are not caused by the native change belong to the Storybook skill.

Native overlay checklist

Use this checklist for implementation and review:

• TypeScript specification, native props, events, and commands agree; generated code was regenerated by its declared command rather than edited by hand.
• Registration names, autolinking, and entrypoints are unchanged unless requested; consuming apps depend directly on native-core.
• Native view lookup and UI mutation run on the platform's UI thread.
• iOS and macOS changes follow the Apple and Office rules: qualified <React/...> headers, guarded Swift import React, no generated Swift header in an RCT_EXTERN_MODULE file, generated-type-free Paper bridges, main-queue dispatch, and strict warnings (R-APPLE-001 through R-APPLE-006). Module and bridging-header validation ran, or the unrun mode is reported (R-APPLE-007).
• Native resources, observers, and pending work are released on unmount, cancellation, or failure.
• Each export works on every host its entrypoint promises; platform-only APIs use the narrowest entrypoint.
• Podspecs, Windows projects, and package files include every new native source.
• Accessibility actions and focus targets are qualified by invoking the native action or target, not by JavaScript events alone.
• Evidence states which platforms and renderers ran; JavaScript-only results are not native qualification (R-NATIVE-003).