[formulus & formulus-formplayer] components and tokens

[IamLRBA]

Component

• formulus (React Native mobile app)
• formulus-formplayer (React web app)
• synkronus (Go backend server)
• synkronus-cli (Command-line utility)
• Documentation
• synkronus-portal

Goal

Adopt shared ODE design tokens and where feasible, shared ODE components in Formulus and Formulus-formplayer so that both apps align with the synkronus-portal and the rest of the ODE design system.

Problem Statement

1. Formulus (React Native)

• Does not depend on @ode/components or @ode/tokens.

• Uses a local Button in src/components/common/Button.tsx (TouchableOpacity + Text + StyleSheet) with variants primary/secondary/tertiary and sizes.

• All other buttons across the app (WelcomeScreen, SyncScreen, SettingsScreen, SyncStatusButtons, QRScannerModal, SignatureCaptureModal, FormManagementScreen, ObservationDetailScreen, etc.) are ad-hoc TouchableOpacity + Text with screen-specific StyleSheet styles.

• Colors come from hand-maintained src/theme/colors.ts, which comments “Based on @ode/tokens package” but copies hex values (e.g. primary #4F7F4E, secondary #E9B85B) instead of importing the token package. Any token change requires manual sync.

• Result: Formulus buttons and UI look different from the portal and are not driven by a single token source.

2. Formulus-formplayer (React web)

• Depends on @ode/tokens only (not @ode/components).

• Uses MUI for all UI primitives: Button, IconButton, TextField, etc., from @mui/material.

• Tokens are consumed via src/theme/tokens-adapter.ts (reads @ode/tokens/dist/json/tokens.json) and src/theme/theme.ts, which builds a MUI theme (palette, typography, spacing, shape, component overrides) from those tokens. So colors and many design values are ODE-aligned, but components are Material-UI.

• Buttons are therefore MUI’s Material Design 3 style (e.g. pill shape from tokens.border.radius.full, contained/outlined variants) rather than the ODE Button (outline + fading border, hover fill).

• Result: Formplayer looks consistent with ODE colors but not with ODE component visuals (e.g. buttons).

Why it matters
Users who use Formulus/formplayer see different button shapes, spacing, and behaviors. Theming and design updates require changes in multiple codebases and formats (portal components, formplayer MUI theme, Formulus local colors and styles).

Proposed Solution

1. Formulus

• Introduce a dependency on @ode/tokens and consume tokens (e.g. via the package’s React Native build output or a small adapter that reads the JSON and exposes values to StyleSheet).

• Replace the hand-maintained colors.ts with token-driven values (or a thin wrapper that maps tokens to the same structure).

• Option A: Add @ode/components (react-native) and use its Button, Input, etc. where they exist and fit the app.

• Option B: Keep the current Formulus Button and key screens but refactor their styles to use token values (spacing, colors, radii) so at least values are shared even if the component implementations stay local for now.

• Prefer one path (A or B) and break into smaller tasks (e.g. “Tokens in Formulus”, “Replace colors.ts with tokens”, “Adopt ODE Button in Formulus”).

2. Formulus-formplayer

• Keep using @ode/tokens (already in place).

• Decide whether to (a) keep MUI and only tighten token usage and theme consistency, or (b) gradually replace MUI Button/inputs with @ode/components/react-web where it reduces divergence from the plan and is feasible with the form-renderer stack.

• If (b), create a follow-up plan (e.g. replace buttons first, then inputs) and document any constraints (e.g. JSON Forms / MUI integration).

Alternatives Considered

• Replace all MUI in formplayer with ODE components in one go: High risk and effort; phased replacement or “theme-only” alignment is safer.

Success Criteria

• Formulus: Uses @ode/tokens (or a derived build) as the source of color/spacing/typography values; no long-term reliance on a hand-copied colors.ts for brand/semantic colors.
• Formulus: Documented decision and plan for adopting @ode/components react-native or for keeping local components with token-driven styles.
• Formulus-formplayer: Documented decision on MUI vs ODE components for buttons/inputs; if keeping MUI, theme is fully token-driven and consistent with portal tokens.
• Buttons and key UI elements in Formulus and formplayer are visually and behaviorally closer to the rest of ODE (or explicitly documented as intentionally different with rationale).
• No regressions in functionality, accessibility, or performance in either app.