Product adoption

Products consume Simal UI as a private, tagged git dependency. The package is the source of truth for tokens and generic controls; products own domain composition and workflow language.

Import decision

Do not import a file below an export path. Do not copy a shared component into a consumer to make a one-off fix; fix it here, add the regression story/test, tag a release, then update the consumer.

Consumer boundary

A healthy consumer:

• imports shared controls directly from @simal/ui or @simal/ui/nativewindui;
• has no competing src/ui tree;
• scans the package source with Tailwind's @source directive;
• enables Metro package exports;
• pins single instances of React, React Native, Expo, uniwind, Tailwind, reanimated, gesture handler, safe-area context, and SVG;
• keeps domain components inside the owning feature;
• promotes only generic, repeated primitives back to this package.

Promotion workflow

When a product discovers a reusable gap:

1. Write the product behavior first and identify the domain-free seam.
2. Open a Simal UI change with a component specification and Storybook states.
3. Add active behavior tests and visual baselines.
4. Build the design-system site and review the generated API page.
5. Tag a Simal UI release.
6. Update the product's pinned tag and replace the local implementation.
7. Run the product's export and E2E checks; package success does not prove the consumer's Tailwind and Metro wiring.

Current product audit

simal-transport already consumes both public surfaces throughout its screens and has no src/ui directory. Its feature-local components are mostly domain composition, which is the intended boundary. Generic defects discovered there should still be repaired upstream—for example, the Material TextField clear affordance belongs in Simal UI because every consumer receives the same broken interaction.

Use the design-system Storybook for isolated component work and the product's mock E2E for workflow verification. Neither replaces the other.