Shared Component Names, Different Web and Native APIs in OTF

If a web button call stops compiling after a mobile port, the problem is often an assumption: that a familiar component name means its props can move unchanged between packages. In OTF's web and React Native libraries, some component names overlap and the design-token system is shared, while each package keeps the props and rendering conventions for its platform.

That distinction gives a team a useful shared vocabulary without promising a universal component interface. Before porting a screen, check the target package's component docs and adapt the call site to its API.

What cross-platform consistency meansCopy Anchor Link

Consistency is a product goal: users should recognize the same visual language and teams should be able to find corresponding building blocks. It does not require one implementation or one prop signature for browser and native UI.

The important distinction is between reusing a concept and reusing a call site. A Button may exist in both packages, but code written for a browser is not automatically valid in React Native.

Compare the target package before copying a call siteCopy Anchor Link

The two packages expose platform-specific APIs. For example, the web Button supports a web variant and browser event handler, while the native Button uses native variant names and press handling:

// Web
import { Button } from '@otfdashkit/ui'

<Button variant="outline" onClick={startCheckout}>Continue</Button>

// React Native
import { Button } from '@otfdashkit/ui-native'

<Button variant="outlined" onPress={startCheckout}>Continue</Button>

These examples show why copying props mechanically can fail: even a similar variant can have a different name, and interaction handlers follow the platform. They are examples of package APIs, not a promise that every web component has a native counterpart or that every prop has a one-to-one replacement.

OTF's catalog lists 240+ components across the two packages: 150+ web components and 85+ native components. That is a combined count. It does not mean each package contains all 240+ components. Confirm that the target package exports the component and read its own API before using it.

A practical port starts with the user interaction, not the old JSX. Ask what the control does, then implement that behavior using the target package's documented props. For a button, that means checking its available native or web variants, handler, disabled state, and content composition. For a form field, check input value and change conventions, keyboard behavior, validation state, and accessibility labels.

Keep design tokens aligned without assuming identical pixelsCopy Anchor Link

Shared design tokens help teams carry color, spacing, radius, and theme intent across platforms. The web package uses CSS-oriented styling, while native components render through React Native conventions. A token can provide the same design value while platform layout, font metrics, system controls, and accessibility settings affect the final result.

Treat the token system as a shared source for design decisions, not a guarantee that screenshots will match pixel for pixel. After a token or component change, inspect the result on each target that matters to the product. This catches differences that a shared color value alone cannot resolve.

When you are setting up both packages, install the web, native, and token packages you need:

npm install @otfdashkit/ui @otfdashkit/ui-native @otfdashkit/tokens

Then configure each target in its own way. The web app consumes the package's web styles and conventions; the native app uses its React Native package and provider. Keep platform-specific setup visible in the project so another engineer or coding agent can identify which package and API a screen uses.

A safe workflow for moving a screenCopy Anchor Link

Use a small, repeatable review for each screen rather than assuming an import change will finish the port:

1. Inventory the behavior. List the components, user actions, validation, loading states, and accessibility needs in the existing screen.
2. Check the destination package. Confirm each component exists and read its platform-specific props and variants.
3. Adapt interactions deliberately. Translate browser events to native press or input behavior where required; do not copy event props by name.
4. Apply shared design intent. Use the shared token system where appropriate, then review platform rendering and system insets.
5. Verify the target. Run the screen on the device or browser you support and check focus, touch, keyboard, disabled states, and error feedback.
6. Record the differences. Leave a short note or test that explains any intentional platform-specific behavior.

This review is especially useful when an AI coding agent is doing the port. Ask it to inspect the destination package's documentation and existing examples first. Tell it which target it is editing, which behaviors must remain, and which shared design tokens to use. Have it report any prop or component that does not exist in the target package instead of inventing a substitute.

Plan shared work around boundariesCopy Anchor Link

A cross-platform team can share several useful decisions without forcing every implementation into a single interface:

• Keep a recognizable component vocabulary where the packages overlap.
• Use shared design tokens to coordinate colors and other design values.
• Keep platform-specific props, handlers, composition, and rendering explicit.
• Test both targets when a shared token or product behavior changes.

That boundary makes review clearer. A designer can ask whether a token change preserves the product's visual intent on both targets. An engineer can review a native event handler as native code rather than pretending it is a browser event. An AI agent can be asked to follow the correct package's conventions instead of guessing from a similar component name.

For more on how platform-specific component layers fit into a mobile app, see the shared component names and platform APIs guide and browse the OTF templates to choose a starting point.

Choose the package for the screen you are buildingCopy Anchor Link

Use @otfdashkit/ui for a web interface and @otfdashkit/ui-native for a React Native interface. Use @otfdashkit/tokens when you need the shared design-token package. The names help you locate related components; they do not promise identical props, rendering, or feature coverage.

React Native documents its native rendering model and platform-specific behavior in its getting started guide. Expo documents the project and tooling options for building React Native apps in its official documentation. Check those platform sources alongside the OTF package docs when deciding how a screen should behave.

SourcesCopy Anchor Link

• React Native — getting started — React Native's project and platform model.
• Expo documentation — Expo's React Native project and tooling guides.

Related guidesCopy Anchor Link

• Read shared component names with different web and native APIs.
• Browse OTF templates.