Platform matrix
What Simal UI guarantees on iOS, Android, and web, and how each surface is verified.
Simal UI supports iOS, Android, and React Native Web from one public package. The public API and semantic meaning stay stable; platform treatment may differ when native behavior is better than visual sameness.
Current playground coverage
| Surface | Interactive playground | Automated visual evidence | Device evidence |
|---|---|---|---|
| Web | Embedded Storybook on every component page | Every story, light and dark, Playwright baselines | Product web E2E |
| iOS | Component API and platform-specific source | Shared stories compile through the package | Required in consuming-app simulator/device QA |
| Android | Component API and Material implementation | Shared stories compile through the package | Required in consuming-app emulator/device QA |
The browser preview is not a native simulator
The embedded demo is React Native Web. It proves API composition, tokens, responsive behavior, browser accessibility, and web interaction. It does not prove UIKit or Android rendering. Native results must be reported separately.
Platform rules
- Use
.ios.tsx,.android.tsx,.native.tsx, and.web.tsxwhen interaction or control chrome should follow the platform. - Do not hide materially different behavior inside
Platform.OSbranches. File-level splits are inspectable, testable, and survive the package boundary. - A shared file means the same implementation is intentional on all surfaces.
- A platform-only component must say so in its Storybook description and API page. It must not fail silently when imported on an unsupported surface.
Variant evidence
Every visual or behavioral variant belongs in Storybook once. The specification for that story records whether the expected result is:
- identical on all platforms;
- shared semantics with native control treatment;
- web-only;
- native-only; or
- awaiting device verification.
The release gate is the evidence matrix below:
| Change | Web Storybook | Web DOM/a11y | iOS | Android |
|---|---|---|---|---|
| Token or typography | Light + dark baseline | Computed contrast | Consumer smoke test | Consumer smoke test |
| Shared layout primitive | Responsive stories | Overflow + target sizes | Simulator/device | Emulator/device |
| Form control | All states and variants | Keyboard, focus, name, error | Native interaction | Native interaction |
| Platform split | Web variant | Web contract | iOS-specific test | Android-specific test |
| Overlay/sheet | Open/closed/error | Focus/modal semantics | Gesture + keyboard | Back button + keyboard |
Native playground direction
The current Storybook is deliberately web-hosted so documentation, live demos, and pixel baselines share one deterministic runtime. The next native expansion should be an Expo development client that reuses the same CSF stories for iOS and Android rather than creating a second catalogue. Until that runner exists, component pages must label native-only behavior and product PRs must include simulator/emulator evidence for native changes.