Shared Component Names, Different Web and Native APIs

When a team moves a web screen into a React Native app, familiar component names can hide a practical problem: a button call that works in the browser may not compile on mobile. Shared vocabulary and design tokens can help a product stay recognizable, but they do not make the packages interchangeable.

OTF publishes separate web and React Native packages. Some component names overlap, and both packages use the OTF token system; props, events, and rendering follow each platform. Before porting a call site, confirm that the destination package provides the component and use the API documented for that package.

What to share, and what to adaptCopy Anchor Link

Cross-platform consistency means that users recognize the product and teams can make coordinated design decisions. It does not require identical component implementations or props.

It helps to separate the design decision from the implementation. “This is the secondary action” can be a shared decision. How a web button handles clicks and focus, or how a native button handles presses and accessibility, belongs to the implementation for that platform.

Compare the target package before copying a call siteCopy Anchor Link

OTF's web and native Buttons illustrate why an import change alone is not a safe port. Their variant names and interaction handlers differ:

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

<Button variant="outline" onClick={save}>Save</Button>

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

<Button variant="outlined" onPress={save}>Save</Button>

Treat these as package-specific examples. A shared component name does not guarantee that all components are available in both packages, that variant strings match, or that other props map one-to-one. For each target, check the component's own documentation for supported props and behavior.

Start a port by listing what the screen must do: submit, cancel, validate input, show a loading state, announce an error, or support keyboard and screen-reader use. Then build those behaviors using the destination package's component API. For a form control, for example, compare value and change handling, keyboard behavior, validation state, and accessibility labels instead of copying the web JSX and changing only the import.

Use design tokens as shared decisionsCopy Anchor Link

The OTF token package supports both web and native styling. On web, its stylesheet exposes CSS variables; the native package can consume the token configuration through OTFProvider. The integration is different on each target, even when the chosen theme is shared.

// Web: load the token stylesheet in the app entry point
import '@otfdashkit/tokens/web.css'

// Native: wrap the app with the native provider
import { OTFProvider } from '@otfdashkit/ui-native'

export default function App() {
  return (
    <OTFProvider defaultTheme="ocean-teal">
      <AppScreens />
    </OTFProvider>
  )
}

A common token helps coordinate values such as color and spacing. It does not promise that the same value will produce identical pixels on the browser and on every device. Native controls, font metrics, system insets, text scaling, and platform conventions all affect rendering. Review the screen in its target runtime after changing a theme or component.

For a real migration, record which decisions are shared and which are intentionally platform-specific. This lets the team coordinate a new brand color without pretending that focus, press, safe-area, and accessibility behavior should be implemented identically.

A practical workflow for moving a screenCopy Anchor Link

Use this checklist for each screen rather than treating a matching component name as proof that a call site is portable:

1. Inventory the behavior. Record the screen's controls, user actions, loading and error states, validation, and accessibility requirements.
2. Inspect the destination package. Confirm that each component is exported and read its target-specific API, examples, and variants.
3. Translate the interaction. Use browser events for web and native press or input conventions for React Native. Check the component docs instead of guessing a replacement prop.
4. Apply shared design intent. Use the token system where it fits, then confirm the target runtime's theme and layout behavior.
5. Verify on the target. Check focus, touch, keyboard, disabled states, error feedback, text scaling, and safe areas in the actual browser or device class.
6. Write down exceptions. Document any component that lacks a counterpart or needs a different interaction so the next port does not repeat the investigation.

This makes review more precise. A reviewer can ask whether the intended design language is present while still evaluating web and native behavior against their own conventions. The code stays honest about what is shared and what has to be adapted.

Give coding agents a platform-specific briefCopy Anchor Link

An AI coding agent can speed up a port, but it needs the correct context. Tell it which package and target it is editing. Ask it to inspect the destination component docs and nearby examples before changing code. Name the behavior to preserve and the token or theme to use. Ask it to report a missing component or prop rather than inventing one.

A useful task brief might say:

Port this settings screen to React Native.
Use @otfdashkit/ui-native and inspect its component examples first.
Keep the same user actions and token choices.
Adapt event handlers and props to the native APIs.
List any component or behavior without a documented native counterpart.

That prompt gives the agent a concrete target and makes gaps visible before they become code review surprises. Shared names and tokens provide context; package documentation and target testing supply the implementation details.

Choose the package for the screenCopy 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. Check the OTF component catalog for current package coverage and the native patterns documentation for examples of larger mobile flows.

The useful outcome is coordinated design work with platform-specific code that can be reviewed on its own merits. Teams can recognize related components and use common token choices without assuming a universal API. For a broader view of where shared structure helps and where adaptation remains, read the one codebase, three platforms guide and the shared component names guide. When you are choosing a starting point for a new product, browse the OTF templates.

SourcesCopy Anchor Link

• OTF component catalog — web and native package coverage.
• OTF native patterns documentation — native UI patterns and examples.
• React Native — getting started — React Native project and platform conventions.