Cross-platform UI

How ContractSpec keeps React and React Native components compatible by splitting responsibility across shared runtime models, platform primitives, resolver aliases, and the composed design-system layer.

What cross-platform means here

The shared rendering story is layered: the core package owns models and resolver helpers, the React packages own hook APIs, the UI kits own raw primitives, and the design-system owns the higher-level product surfaces that pair web and mobile implementations.

import {
  defaultTokens,
  mapTokensForPlatform,
  withPlatformUI,
} from '@contractspec/lib.design-system';

const nativeTokens = mapTokensForPlatform('native', defaultTokens);

const ui = withPlatformUI({
  tokens: defaultTokens,
  platform: 'web',
});

// ui is a lightweight config object for design-system consumers.
// nativeTokens is the mapped token shape for a native renderer.

Resolver and alias setup

Teach the bundler what “web” and “native” mean before you try to share component code. These helpers are public from the root @contractspec/lib.presentation-runtime-core entrypoint.

import { withPresentationTurbopackAliases } from '@contractspec/lib.presentation-runtime-core';

/** @type {import('next').NextConfig} */
const nextConfig = withPresentationTurbopackAliases({
  turbopack: {
    resolveAlias: {
      fs: { browser: 'browserify-fs' },
    },
  },
});

export default nextConfig;

import { withPresentationWebpackAliases } from '@contractspec/lib.presentation-runtime-core';

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => withPresentationWebpackAliases(config),
};

export default nextConfig;

const { getDefaultConfig } = require('expo/metro-config');
const {
  withPresentationMetroAliases,
} = require('@contractspec/lib.presentation-runtime-core');

const projectRoot = __dirname;
const config = getDefaultConfig(projectRoot);

module.exports = withPresentationMetroAliases(config);

How the remapping works

The helpers are intentionally asymmetric because Turbopack patches the Next config object, Webpack mutates a resolver config, and Metro maps modules at request time for native platforms.

Layout primitives

VStack, HStack, and Box are the closest thing to a shared layout vocabulary, but their defaults and a few props still differ across the web and native packages.

import { Box, HStack, VStack } from '@contractspec/lib.ui-kit-web/ui/stack';

export function AccountSummaryHeader() {
  return (
    <VStack gap="lg" align="stretch" className="w-full">
      <HStack gap="sm" align="center" justify="between" wrap="wrap">
        <Box gap="xs" align="center" justify="start" wrap="nowrap">
          <StatusDot />
          <Title />
        </Box>
        <Actions />
      </HStack>
      <Filters />
    </VStack>
  );
}

// In native-only files, swap the import to:
// @contractspec/lib.ui-kit/ui/stack
//
// On web-only pages, VStack / HStack / Box also support:
// <VStack as="section">...</VStack>

Rendering patterns

Keep the controller stable, then decide whether the final surface should be a raw web primitive, a raw native primitive, or a composed design-system wrapper.

import { DataTable as DesignSystemTable } from '@contractspec/lib.design-system';
import { DataTable as NativeTable } from '@contractspec/lib.ui-kit/ui/data-table';
import { DataTable as WebTable } from '@contractspec/lib.ui-kit-web/ui/data-table';
import { useContractTable } from '@contractspec/lib.presentation-runtime-react';

export function useAccountsController(data, columns) {
  return useContractTable({
    data,
    columns,
    selectionMode: 'single',
    initialState: {
      sorting: [{ id: 'arr', desc: true }],
      pagination: { pageIndex: 0, pageSize: 5 },
    },
  });
}

export function WebAccounts({ controller }) {
  return <WebTable controller={controller} />;
}

export function NativeAccounts({ controller }) {
  return <NativeTable controller={controller} />;
}

export function ProductAccounts({ controller }) {
  return (
    <DesignSystemTable
      controller={controller}
      title="Accounts"
      description="Same controller, composed ContractSpec shell."
    />
  );
}

// If the table is spec-driven instead of hand-authored,
// swap useContractTable for useDataViewTable.

Gotchas and boundaries

• withPresentationNextAliases no longer exists. Use withPresentationTurbopackAliases for the default Next.js path or withPresentationWebpackAliases for explicit webpack fallback.
• Prefer root runtime imports when alias helpers matter. Metro remaps the root @contractspec/lib.presentation-runtime-react package, not arbitrary deep hook subpaths.
• Metro only rewrites @contractspec/lib.ui-kit-web/ui/* imports. Router-specific web packages and other web-only helpers still need platform-aware imports.
• presentation-runtime-core is headless. It owns models and config helpers, not rendered React components.
• design-system compatibility comes from paired .tsx / .mobile.tsx implementations and token helpers such as withPlatformUI and mapTokensForPlatform.
• Stack primitives are similar across platforms, but the prop surface is not identical. Stay inside the common subset for shared renderers.
• Alias helpers solve module resolution only. They do not replace app-level monorepo watchFolders, Expo Router setup, or other Next configuration.

Customer markdown kit

Copy these markdown snippets into your own AGENTS.md, LLM guide, README, or engineering playbook when you want to enforce the same cross-surface rules across customer projects.

# Cross-Surface Rendering Policy

- Import runtime bundler helpers from `@contractspec/lib.presentation-runtime-core` root only.
- Use `withPresentationTurbopackAliases` for default Next.js projects.
- Use `withPresentationWebpackAliases` only when the app explicitly opts into webpack.
- Use `withPresentationMetroAliases` for Expo and Metro builds.
- Prefer `@contractspec/lib.design-system` for shared product-facing surfaces.
- Use `@contractspec/lib.ui-kit-web` only for web-specific primitive lanes.
- Use `@contractspec/lib.ui-kit` only for native-specific primitive lanes.
- Keep shared layout code inside the common `VStack` / `HStack` / `Box` subset.
- Do not use removed `withPresentationNextAliases`.
- Treat `.tsx` / `.mobile.tsx` pairs as the standard design-system compatibility boundary.

# Cross-Surface Rendering Checklist

1. Configure the bundler aliases before sharing any UI code.
2. Choose the controller layer:
   - use `useContractTable` for app-owned rows and columns
   - use `useDataViewTable` for DataViewSpec-driven tables
3. Choose the renderer lane:
   - web primitive: `@contractspec/lib.ui-kit-web`
   - native primitive: `@contractspec/lib.ui-kit`
   - shared product surface: `@contractspec/lib.design-system`
4. Verify mirrored `.tsx` / `.mobile.tsx` implementations where the design-system owns the surface.
5. In shared layout code, set `gap`, `align`, `justify`, and `wrap` explicitly.
6. Check docs and examples for root imports and current helper names before copying them into product code.