@gv-tech/design-system 2.3.0 → 2.5.0

package/docs/architecture-pivot.md

@@ -0,0 +1,165 @@
+# ADR: Cross-Platform Design System via Unified Monorepo
+
+**Date:** 2026-02-17  
+**Status:** Accepted  
+**Author(s):** Garcia Ventures Engineering
+
+> See [update-plan.md](./update-plan.md) for the actionable Phase 0/1 migration plan with PR checklists.
+
+---
+
+## Context
+
+The GV Tech Design System (`@gv-tech/design-system`) currently ships as a **single Vite-based package** with platform-conditional file extensions (`.web.tsx` / `.native.tsx`). While this allowed rapid prototyping of React Native support—seven components now have functional native implementations—the single-package approach has revealed scaling issues:
+
+- **Token duplication risk**: both platforms reference the same `src/theme/tokens.ts` file but with no formal contract guaranteeing they stay in sync.
+- **No shared component contracts**: props, variants, and sizes are redefined independently in each platform file. Drift is inevitable.
+- **Build coupling**: the Vite library build is web-focused; native outputs rely on Metro's file extension resolution, not a shared build pipeline.
+- **Testing isolation**: there's no way to run native-specific tests in CI without a full RN environment; web tests cannot validate API parity.
+
+## Decision
+
+**Adopt Option 1 — One cross-platform design system with platform-specific implementations** — structured as an **Nx + Yarn workspaces monorepo**.
+
+### Architecture
+
+```text
+gvtech-design/                       (Nx workspace root)
+├── packages/
+│   ├── design-tokens/               Shared tokens (colors, spacing, radii, typography, shadows)
+│   │   └── src/
+│   │       ├── palette.ts           Primitive color palette
+│   │       ├── theme.ts             Semantic token mappings (light/dark)
+│   │       ├── spacing.ts           Spacing scale
+│   │       ├── typography.ts        Font families, sizes, weights
+│   │       ├── shadows.ts           Elevation / shadow definitions
+│   │       └── index.ts             Barrel export
+│   │
+│   ├── ui-core/                     Shared types, contracts, headless logic
+│   │   └── src/
+│   │       ├── contracts/           Component contracts (props, variants, sizes)
+│   │       │   ├── button.ts
+│   │       │   ├── text.ts
+│   │       │   ├── input.ts
+│   │       │   ├── card.ts
+│   │       │   ├── checkbox.ts
+│   │       │   ├── radio.ts
+│   │       │   ├── dialog.ts
+│   │       │   └── toast.ts
+│   │       ├── types/               Shared utility types
+│   │       └── index.ts
+│   │
+│   ├── ui-web/                      Web implementation (shadcn + Radix + Tailwind)
+│   │   └── src/components/
+│   │       ├── button.tsx
+│   │       ├── input.tsx
+│   │       └── ...
+│   │
+│   └── ui-native/                   React Native implementation (RN Reusables + NativeWind)
+│       └── src/components/
+│           ├── button.tsx
+│           ├── input.tsx
+│           └── ...
+│
+├── apps/
+│   └── ui-playground/               Extended playground (web + native parity views)
+│
+├── nx.json                          (task runner + caching)
+├── package.json                     (Yarn workspaces root)
+```
+
+### Key Principles
+
+| Principle                 | Detail                                                                                                                                          |
+| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Single token source**   | All tokens come from `design-tokens`. No per-platform forks without explicit approval.                                                          |
+| **Matched API surface**   | Component names, props, variants, and sizes are defined in `ui-core` contracts and implemented identically on both platforms wherever possible. |
+| **Documented divergence** | Platform-specific UX differences (e.g., Dialog → BottomSheet on native) must preserve semantic intent and be documented with "diff notes."      |
+| **Own the code**          | Native components may start from React Native Reusables patterns but must live in our repo, wired to our tokens and contracts.                  |
+| **Incremental migration** | The existing single-package structure continues to work during the transition. Packages are extracted incrementally.                            |
+
+## Consequences
+
+### Positive
+
+- Tokens are a single source of truth — changes propagate to both platforms automatically.
+- Component contracts prevent API drift and enable parity testing.
+- Nx task graph + caching accelerate CI/CD for affected packages only.
+- Playground can show side-by-side parity views with diff notes.
+
+### Negative / Risks
+
+- **Migration overhead**: extracting from a single package into a monorepo requires careful phasing.
+- **Build complexity**: two build targets (Vite for web, Metro/Expo for native) must be orchestrated.
+- **Team learning curve**: Nx workspace conventions and package boundaries.
+
+### Mitigations
+
+- Phase 1 focuses on extracting `design-tokens` and `ui-core` first (lowest risk, highest value).
+- Existing components continue to work via the current package during migration.
+- Documentation (this ADR + phase tracker) ensures alignment.
+
+## Current State Reference
+
+| Aspect                      | Status                                                                         |
+| :-------------------------- | :----------------------------------------------------------------------------- |
+| Components with native impl | 7 of 49+ (Button, Input, Label, Badge, Accordion, Alert, Avatar)               |
+| Remaining native components | Placeholder only ("not yet implemented")                                       |
+| Token location              | `src/theme/tokens.ts` (palette + semantic themes)                              |
+| Build system                | Vite (multi-entry library build)                                               |
+| Existing RN deps            | `react-native`, `nativewind`, `react-native-reanimated`, `@rn-primitives/slot` |
+
+---
+
+## Open Decisions (Team Input Required)
+
+### 1. Token Source Format
+
+| Option                           | Pros                                            | Cons                                          |
+| :------------------------------- | :---------------------------------------------- | :-------------------------------------------- |
+| **TS-first** (current approach)  | Type safety, IDE completion, direct import      | Requires build step for non-TS consumers      |
+| **JSON-first**                   | Universal (Style Dictionary compatible)         | Loses TS types, needs codegen for type safety |
+| **TS-first + JSON build output** | Best of both — TS as source, JSON/CSS generated | Slightly more build config                    |
+
+> **Recommendation:** TS-first with generated JSON/CSS outputs. This preserves the current workflow while enabling future integrations (Figma plugins, Style Dictionary).
+
+### 2. React Native Styling Approach
+
+| Option                         | Pros                                                       | Cons                                         |
+| :----------------------------- | :--------------------------------------------------------- | :------------------------------------------- |
+| **NativeWind** (current)       | Tailwind class syntax consistency with web, already in use | Tied to Tailwind version, some edge cases    |
+| **StyleSheet + token imports** | Pure RN, no extra deps                                     | Class name parity lost, more boilerplate     |
+| **Tamagui / Unistyles**        | Cross-platform styling                                     | Additional abstraction layer, learning curve |
+
+> **Recommendation:** Stay with NativeWind — it's already in use, provides className parity with web, and maps directly to shared tokens.
+
+### 3. Expo vs Bare React Native
+
+This affects Nx executor configuration, dev loop, and native module linking. **Team should specify.**
+
+### 4. Phase 1 Component List
+
+Proposed first set (7 components):
+
+| Component            | Web Status  | Native Status  | Priority Rationale                                            |
+| :------------------- | :---------- | :------------- | :------------------------------------------------------------ |
+| **Button**           | ✅ Complete | ✅ Complete    | Core interaction — already done                               |
+| **Text**             | ✅ Complete | 🆕 New         | Foundation for typography                                     |
+| **Input**            | ✅ Complete | ✅ Complete    | Core form element — already done                              |
+| **Checkbox / Radio** | ✅ Complete | ❌ Placeholder | Core form elements                                            |
+| **Card**             | ✅ Complete | ✅ Complete\*  | Layout primitive — native exists but needs contract alignment |
+| **Dialog / Sheet**   | ✅ Complete | ❌ Placeholder | Critical overlay pattern (maps to BottomSheet on native)      |
+| **Toast**            | ✅ Complete | ❌ Placeholder | Feedback pattern                                              |
+
+> [!NOTE]
+> Button, Input, and Card already have native implementations. They will be migrated to use `ui-core` contracts rather than rewritten.
+
+---
+
+## References
+
+- [Nx Workspace Docs](https://nx.dev/docs/reference/create-nx-workspace)
+- [Nx Dependency Graph](https://nx.dev/docs/features/explore-graph)
+- [React Native Reusables](https://rnr-docs.vercel.app/)
+- [Yarn Workspaces Monorepo Guide](https://www.premieroctet.com/blog/en/yarn-monorepo)
+- Prior art: `docs/universal-implementation.md`

package/docs/native-setup-decision.md

@@ -0,0 +1,57 @@
+# ADR: Adopting Expo for Native Development & Playground
+
+**Date:** 2026-02-19  
+**Status:** Accepted  
+**Author(s):** Garcia Ventures Engineering
+
+---
+
+## Context
+
+As part of the [Architecture Pivot](./architecture-pivot.md), we must decide on the infrastructure for developing, testing, and demonstrating the React Native implementation of the GV Tech Design System (`@gv-tech/ui-native`).
+
+The choice between the **Expo SDK** and the **Bare React Native CLI** affects:
+
+1. The developer experience (DX) for contributors.
+2. The ease of testing components on physical devices.
+3. The complexity of CI/CD pipelines (native build orchestration).
+4. The onboarding process for library consumers.
+
+## Decision
+
+We will adopt an **Expo-compatible strategy**, specifically utilizing the **Expo SDK** and **Continuous Native Generation (CNG)** for the playground and internal development.
+
+### Implementation Details
+
+| Aspect             | Decision                                                                                                                 |
+| :----------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| **Playground App** | Built with Expo to enable instant QR-code testing via Expo Go or Development Builds.                                     |
+| **Native Library** | Developed as a standard React Native library that remains 100% compatible with "Bare" projects.                          |
+| **Tooling**        | Utilize `@nx/expo` for workspace orchestration and EAS (Expo Application Services) for automated native builds.          |
+| **Testing**        | **Vitest** (Unified). Native components are tested via `react-native-web` shims in Vitest, eliminating Babel/Jest bloat. |
+
+## Rationale
+
+1. **Lower Friction (DX):** Expo eliminates the need for developers to manually manage `/ios` and `/android` directories, Gradle files, or CocoaPods. Most contributors won't need Xcode or Android Studio to work on UI components.
+2. **Instant Feedback:** The ability to share a QR code for a "Development Build" allows stakeholders to test new components on real devices without installing binaries.
+3. **CI/CD Efficiency:** Nx supports Expo natively, allowing us to cache build outputs and run tests in a headless environment without the massive overhead of "Bare" native builds.
+4. **Market Alignment:** In 2026, Expo is the industry standard for starting new React Native projects. Supporting it ensures we cater to the majority of our consumers while still maintaining "Bare" compatibility.
+
+## Consequences
+
+### Positive
+
+- **Faster Onboarding:** New developers can start contributing to `ui-native` in minutes.
+- **Unified CI:** Native linting and testing can be easily integrated into our existing CI workflows.
+- **Improved Stability:** Expo SDK provides a stable, versioned platform for dependencies like `react-native-reanimated` and `react-native-svg`.
+
+### Negative / Risks
+
+- **Ejecting:** If we ever require a native dependency that has no Expo Config Plugin, we would need to maintain a custom plugin or utilize `prebuild` to customize native code. _Mitigation: We will prioritize components that use universal primitives and established plugins._
+- **Bundle Size:** Some Expo SDK modules include extra code. _Mitigation: Since we are a library, this only affects the playground app; consumers only pay for what they import._
+
+## References
+
+- [Architecture Pivot ADR](./architecture-pivot.md)
+- [Expo Continuous Native Generation (CNG)](https://docs.expo.dev/workflow/continuous-native-generation/)
+- [Nx Expo Guide](https://nx.dev/recipes/expo)

package/docs/phase-1-tracker.md

@@ -0,0 +1,144 @@
+# Phase 1 Tracker — Cross-Platform Design System
+
+**Started:** 2026-02-17  
+**Updated:** 2026-02-19
+**Status:** 🟢 Phase 1 Complete — Tests Passing, Docs & Playground Polish In Progress
+
+> See [update-plan.md](./update-plan.md) for the actionable Phase 0 PR checklist and Phase 1 migration steps.
+
+---
+
+## Phase 1 Deliverables
+
+### Infrastructure
+
+| Task                            | Status  | Owner | Notes                                                        |
+| :------------------------------ | :------ | :---- | :----------------------------------------------------------- |
+| Initialize Nx workspace         | ✅ Done |       | Nx 22.5.1 + Yarn workspaces enabled                          |
+| Create `packages/design-tokens` | ✅ Done |       | palette, theme, spacing, typography, shadows, radii all live |
+| Create `packages/ui-core`       | ✅ Done |       | 51 contract source files covering all Phase 1 components     |
+| Create `packages/ui-web`        | ✅ Done |       | 46 components with tests — all tests passing                 |
+| Create `packages/ui-native`     | ✅ Done |       | 27+ real implementations — all tests passing                 |
+| Create `apps/playground-web`    | ✅ Done |       | Full doc site live on Cloudflare Pages                       |
+| Create `apps/native-playground` | ✅ Done |       | Expo app scaffolded with core component showcase             |
+| Configure Nx caching            | ✅ Done |       | `nx.json` + CI cache restore steps                           |
+| CI/CD pipeline updates          | ✅ Done |       | Nx cache steps in test + build jobs                          |
+
+> **Release tooling:** release-please remains the orchestrator through Phase 0/1. Nx Release is a future option to evaluate after Phase 1. See [update-plan.md](./update-plan.md) and [release-tooling-evaluation.md](./release-tooling-evaluation.md).
+
+### Component Parity
+
+> **Legend:** ✅ Real implementation | 🚫 Not yet implemented (stub) | ⬜ Not started
+
+| Component           | Contract | Web (`ui-web`) | Native (`ui-native`) | Tests (web) | Tests (native) | Notes                                         |
+| :------------------ | :------- | :------------- | :------------------- | :---------- | :------------- | :-------------------------------------------- |
+| **Accordion**       | ✅       | ✅             | ✅                   | ✅          | ⬜             | Reanimated animated trigger                   |
+| **Alert**           | ✅       | ✅             | ✅                   | ✅          | ⬜             | Variants: default, destructive, warning, info |
+| **Alert Dialog**    | ✅       | ✅             | ✅                   | ✅          | ⬜             | Uses Dialog primitives + Reanimated           |
+| **Aspect Ratio**    | ✅       | ✅             | 🚫                   | ✅          | —              | Web-only concept                              |
+| **Avatar**          | ✅       | ✅             | ✅                   | ✅          | ⬜             | `@rn-primitives/avatar`                       |
+| **Badge**           | ✅       | ✅             | ✅                   | ✅          | ⬜             | Variants aligned with web                     |
+| **Breadcrumb**      | —        | ✅             | 🚫                   | ✅          | —              | Navigation-heavy, web-first                   |
+| **Button**          | ✅       | ✅             | ✅                   | ✅          | ✅             | All variants + sizes; Pressable               |
+| **Calendar**        | —        | ✅             | 🚫                   | ✅          | —              | Complex date picker; no RN primitive          |
+| **Card**            | ✅       | ✅             | ✅                   | ✅          | ✅             | Full sub-components                           |
+| **Carousel**        | —        | ✅             | 🚫                   | ✅          | —              | Embla-based; no RN equivalent yet             |
+| **Chart**           | —        | ✅             | 🚫                   | ✅          | —              | recharts web-only                             |
+| **Checkbox**        | ✅       | ✅             | ✅                   | ✅          | ✅             | Platform-specific size/stroke                 |
+| **Collapsible**     | ✅       | ✅             | ✅                   | ✅          | ✅             | `@rn-primitives/collapsible`                  |
+| **Command**         | —        | ✅             | 🚫                   | ✅          | —              | cmdk-based; no RN equivalent                  |
+| **Context Menu**    | —        | ✅             | 🚫                   | ✅          | —              | Pointer-only interaction                      |
+| **Dialog**          | ✅       | ✅             | ✅                   | ✅          | ✅             | `@rn-primitives/dialog` + Reanimated          |
+| **Drawer**          | —        | ✅             | 🚫                   | ✅          | —              | Uses vaul; no RN equivalent yet               |
+| **Dropdown Menu**   | —        | ✅             | 🚫                   | ✅          | —              | Pointer-triggered interaction                 |
+| **Form**            | —        | ✅             | 🚫                   | ✅          | —              | react-hook-form; web-first                    |
+| **Hover Card**      | —        | ✅             | 🚫                   | ✅          | —              | Hover interaction; not applicable native      |
+| **Input**           | ✅       | ✅             | ✅                   | ✅          | ✅             | TextInput with contract alignment             |
+| **Label**           | ✅       | ✅             | ✅                   | ✅          | ⬜             | nativeID + onPress pattern                    |
+| **Menubar**         | —        | ✅             | 🚫                   | ✅          | —              | Desktop navigation pattern                    |
+| **Navigation Menu** | —        | ✅             | 🚫                   | ✅          | —              | Web navigation pattern                        |
+| **Pagination**      | —        | ✅             | 🚫                   | ✅          | —              | Cursor-based; alternative on native           |
+| **Popover**         | —        | ✅             | 🚫                   | ✅          | —              | No RN primitive yet                           |
+| **Progress**        | —        | ✅             | 🚫                   | ✅          | —              | No RN primitive yet                           |
+| **Radio Group**     | ✅       | ✅             | ✅                   | ✅          | ✅             | `@rn-primitives/radio-group`                  |
+| **Resizable**       | —        | ✅             | 🚫                   | ✅          | —              | Drag-based; not native pattern                |
+| **Scroll Area**     | —        | ✅             | 🚫                   | ✅          | —              | Native scroll is built-in                     |
+| **Search**          | —        | ✅             | ✅                   | ✅          | ⬜             | Command palette pattern                       |
+| **Select**          | ✅       | ✅             | ✅                   | ✅          | ⬜             | Fully typed complex native impl               |
+| **Separator**       | ✅       | ✅             | ✅                   | ✅          | ⬜             | `@rn-primitives/separator`                    |
+| **Sheet**           | ✅       | ✅             | ✅                   | ✅          | ✅             | SlideInRight animation                        |
+| **Skeleton**        | ✅       | ✅             | ✅                   | ✅          | ✅             | Reanimated pulsing opacity                    |
+| **Slider**          | —        | ✅             | 🚫                   | ✅          | —              | No Expo-compatible RN primitive yet           |
+| **Sonner**          | —        | ✅             | 🚫                   | ✅          | —              | Web toast library; use Toast on native        |
+| **Switch**          | ✅       | ✅             | ✅                   | ✅          | ⬜             | `@rn-primitives/switch`                       |
+| **Table**           | ✅       | ✅             | ✅                   | ✅          | ⬜             | View/Text-based layout                        |
+| **Tabs**            | ✅       | ✅             | ✅                   | ✅          | ⬜             | `@rn-primitives/tabs` + TextClassContext      |
+| **Text**            | ✅       | ✅             | ✅                   | ✅          | ✅             | Typography scale with variants                |
+| **Textarea**        | ✅       | ✅             | ✅                   | ✅          | ✅             | TextInput with multiline + autoGrow           |
+| **Theme Toggle**    | —        | ✅             | ✅                   | ✅          | ⬜             | Dark/light/system                             |
+| **Toast**           | ✅       | ✅             | ✅                   | ✅          | ✅             | `@rn-primitives/toast` + Reanimated           |
+| **Toggle**          | ✅       | ✅             | ✅                   | ✅          | ⬜             | Pressable toggle state                        |
+| **Toggle Group**    | ✅       | ✅             | ✅                   | ✅          | ⬜             | Multi/single selection                        |
+| **Tooltip**         | ✅       | ✅             | ✅                   | ✅          | ⬜             | `@rn-primitives/tooltip` + Reanimated         |
+
+### Playground
+
+| Task                                                | Status       | Notes                                                           |
+| :-------------------------------------------------- | :----------- | :-------------------------------------------------------------- |
+| `playground-web` documentation site                 | ✅ Complete  | Full doc site with Web + Native tabs, sidebar, search           |
+| Green dot indicator for native-available components | ✅ Complete  | Validated — only real implementations show the dot              |
+| Native tab only shown for real implementations      | ✅ Complete  | `doc-routes.tsx` + `docs.ts` aligned with actual code           |
+| `native-playground` Expo app scaffolded             | ✅ Complete  | Basic showcase: Button, Card, Input, Checkbox, RadioGroup, Text |
+| Expand `native-playground` with all real components | ⬜ Next Step | Add Accordion, Alert, Dialog, Sheet, Toast, etc.                |
+| "Diff notes" section per component                  | ⬜ Next Step | Document intentional platform differences per component         |
+| Side-by-side parity note in web doc pages           | ⬜ Next Step | Link from web → native tab where native exists                  |
+
+---
+
+## Definition of Done
+
+- [x] Tokens imported from `design-tokens` by both `ui-web` and `ui-native` (no duplication)
+- [x] 27+ core components have real native implementations with contracts matching `ui-core`
+- [x] All `ui-web` tests passing (46 components)
+- [x] All `ui-native` tests passing (12 components with test files)
+- [x] Playground shows native tab only for components with real implementations
+- [ ] Native playground demonstrates all 27 real native components
+- [ ] Platform divergence registry complete (diff notes per component)
+- [ ] Sub-package publishing configured in release-please
+
+---
+
+## Key Decisions
+
+| Decision               | Selected Approach                     | Status      |
+| :--------------------- | :------------------------------------ | :---------- |
+| Token source format    | TS-first + JSON outputs               | ✅ Accepted |
+| RN styling approach    | NativeWind (already in use)           | ✅ Accepted |
+| Expo vs Bare RN        | **Expo (SDK + CNG)**                  | ✅ Accepted |
+| Phase 1 component set  | Exceeded: 27+ real (vs 7 planned)     | ✅ Complete |
+| Release tooling        | release-please (stays as-is)          | ✅ Accepted |
+| Nx release migration   | Deferred — evaluate post Phase 1      | 🟡 Pending  |
+| Sub-package publishing | Root `@gv-tech/design-system` for now | 🟡 Pending  |
+
+> See [native-setup-decision.md](./native-setup-decision.md) for the Expo decision rationale.
+
+---
+
+## Next Steps (Priority Order)
+
+1. **Expand `native-playground`** — Add Accordion, Alert Dialog, Alert, Avatar, Badge, Dialog, Sheet, Skeleton, Switch, Table, Tabs, Toast, Toggle, Tooltip, etc.
+2. **Complete platform divergence registry** — Document intentional differences per component in `universal-implementation.md`
+3. **Native test coverage** — Add test files for the 15+ native components that don't have tests yet
+4. **Sub-package publishing** — Add `@gv-tech/ui-web`, `@gv-tech/ui-native`, `@gv-tech/ui-core`, `@gv-tech/design-tokens` to release-please manifests
+5. **`private: true` at root** — Once sub-packages are the primary publish targets (Decision C from update-plan.md)
+6. **Nx Release evaluation** — Assess whether Nx Release adds value over release-please for the monorepo
+
+---
+
+## Weekly Status
+
+| Week       | Focus                                | Completed                                                                  | Blockers |
+| :--------- | :----------------------------------- | :------------------------------------------------------------------------- | :------- |
+| 2026-02-17 | Documentation, ADR, initial planning | Architecture docs created                                                  | —        |
+| 2026-02-17 | Phase 0 — Nx + Workspaces setup      | Yarn workspaces, Nx 22.5.1, nx.json, CI cache, all checks passing          | —        |
+| 2026-02-19 | Phase 1 complete — Tests green       | All 46 web + 12 native tests passing; playground live; docs/routes aligned | —        |

package/docs/release-tooling-evaluation.md

@@ -0,0 +1,67 @@
+# ADR: Release Orchestration — Release-Please vs. Nx Release
+
+**Date:** 2026-02-19  
+**Status:** Evaluation (Deferred to Post-Phase 1)  
+**Author(s):** Garcia Ventures Engineering
+
+## Context
+
+As the GV Tech Design System transitions to a monorepo architecture with multiple packages (`@gv-tech/ui-web`, `@gv-tech/ui-native`, `@gv-tech/ui-core`, `@gv-tech/design-tokens`), we must choose an orchestration tool to handle versioning, changelog generation, and npm publishing.
+
+Currently, the project uses **release-please**, which was inherited from the single-package architecture.
+
+## Options
+
+### 1. Release-Please (Status Quo)
+
+A "Pull Request-first" tool by Google that parses Conventional Commits to maintain an automated release PR.
+
+- **Pros:**
+  - **Low Friction:** Already integrated and working.
+  - **Visible Workflow:** Releases are "staged" in a visible GitHub PR.
+  - **Independent Versions:** Natively supports different versions for different packages.
+- **Cons:**
+  - **Workspace Unaware:** Does not understand internal package dependencies. Bumping `ui-core` does not automatically update the version of `ui-core` listed in `ui-native/package.json`.
+  - **GitHub Locked:** Deeply tied to GitHub Actions and PR events.
+  - **Complex Manifests:** Multi-package configuration in `release-please-config.json` can become verbose.
+
+### 2. Nx Release (Proposed)
+
+A "Task-first" tool built into the Nx ecosystem that uses the project graph to orchestrate releases.
+
+- **Pros:**
+  - **Dependency Sync:** Automatically updates internal package versions when their dependencies change.
+  - **Lock-step Support:** Simplifies keeping all design system packages on the same version (e.g., all 3.2.0), which is often preferred for design systems.
+  - **Local Dry-Runs:** Command-line testing (`nx release --dry-run`) allows verification without pushing to Git.
+  - **Task Graph Integration:** Leverages the Nx cache and task graph for builds during the release process.
+- **Cons:**
+  - **Active vs. Passive:** Requires triggering a command (e.g., via `workflow_dispatch` or on merge) rather than automatically maintaining a PR.
+  - **Learning Curve:** New configuration format (`nx.json` additions) compared to the familiar `release-please` config.
+
+## Comparison Table
+
+| Feature                | Release-Please          | Nx Release                          |
+| :--------------------- | :---------------------- | :---------------------------------- |
+| **Control Point**      | GitHub Pull Request     | CLI Command                         |
+| **Monorepo Awareness** | Low (path-based)        | High (graph-based)                  |
+| **Dependency Sync**    | Manual / External       | Automatic                           |
+| **Local Testing**      | Requires push/PR        | Local Dry-Run                       |
+| **Versioning Goal**    | Independent per package | Flexible (Lock-step or Independent) |
+
+## Decision
+
+**We will continue to use Release-Please through the completion of Phase 1.**
+
+The transition to a multi-package monorepo is already a significant architectural shift. Introducing a new release orchestrator simultaneously increases the risk of delivery delays. Once Phase 1 is stable and the sub-packages are successfully publishing, we will evaluate a migration to **Nx Release** to benefit from **Lock-step versioning** and **automatic dependency synchronization**.
+
+## Consequences
+
+- **Short-term:** Developers must manually ensure that internal `workspace:*` dependencies are correctly handled (or use Yarn's workspace protocol which handles this during local development).
+- **Long-term:** If we choose to move to Lock-step versioning (standardizing all packages on one version), Nx Release will significantly reduce the maintenance overhead.
+- **Maintenance:** The `release-please-config.json` and `.release-please-manifest.json` files must be kept in sync as new packages are added.
+
+## References
+
+- [Nx Release Documentation](https://nx.dev/features/manage-releases)
+- [Release-Please Monorepo Guide](https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md)
+- [update-plan.md](./update-plan.md)

package/docs/universal-implementation.md

@@ -0,0 +1,195 @@
+# Universal Component Implementation Guide
+
+> [!IMPORTANT]
+> **Architectural Pivot (2026-02-17):** This project is transitioning from a single-package design system to an **Nx monorepo** with shared packages. See [architecture-pivot.md](./architecture-pivot.md) for the full ADR and [phase-1-tracker.md](./phase-1-tracker.md) for Phase 1 scope.
+
+This document outlines the current state of web/native component parity and serves as the reference for the platform divergence registry.
+
+---
+
+## Architecture Overview
+
+```text
+packages/
+  design-tokens/    ← palette, theme, spacing, typography, shadows, radii
+  ui-core/          ← Shared component contracts (props, variants, sizes)
+  ui-web/           ← Web implementation (shadcn + Radix + Tailwind)
+  ui-native/        ← React Native implementation (RN Reusables + NativeWind)
+apps/
+  playground-web/   ← Full documentation site — Web + Native tabs
+  native-playground/ ← Expo app for on-device component testing
+```
+
+Key rules:
+
+- **No token forks** without explicit approval — tokens come from `design-tokens`.
+- **Matched API surface** across platforms (component names, props, variants, sizes).
+- **Documented divergence** for platform-specific UX differences.
+- **Own the code** — native components live in our repo, wired to our tokens/contracts.
+
+---
+
+## Component Parity Matrix (Current State)
+
+> **Last updated:** 2026-02-19 | ✅ Real | 🚫 Stub (not yet implemented)
+
+### Forms
+
+| Component        | Web | Native | Notes                                                     |
+| :--------------- | :-: | :----: | :-------------------------------------------------------- |
+| **Button**       | ✅  |   ✅   | Pressable + all variants; `onPress` replaces `onClick`    |
+| **Checkbox**     | ✅  |   ✅   | `@rn-primitives/checkbox`; size/stroke differ by platform |
+| **Form**         | ✅  |   🚫   | react-hook-form; web-first pattern                        |
+| **Input**        | ✅  |   ✅   | RN `TextInput`; no `onChange`, uses `onChangeText`        |
+| **Label**        | ✅  |   ✅   | Uses `nativeID` + `onPress` instead of `htmlFor`          |
+| **Radio Group**  | ✅  |   ✅   | `@rn-primitives/radio-group`                              |
+| **Select**       | ✅  |   ✅   | Complex native impl; fully typed                          |
+| **Slider**       | ✅  |   🚫   | No Expo-compatible RN primitive available                 |
+| **Switch**       | ✅  |   ✅   | `@rn-primitives/switch`                                   |
+| **Textarea**     | ✅  |   ✅   | `TextInput multiline`; `textAlignVertical="top"`          |
+| **Toggle**       | ✅  |   ✅   | Pressable with active state                               |
+| **Toggle Group** | ✅  |   ✅   | Multi/single selection modes                              |
+
+### Data Display
+
+| Component       | Web | Native | Notes                                                  |
+| :-------------- | :-: | :----: | :----------------------------------------------------- |
+| **Accordion**   | ✅  |   ✅   | `@rn-primitives/accordion` + Reanimated chevron        |
+| **Alert**       | ✅  |   ✅   | Variants: default, destructive, warning, info          |
+| **Avatar**      | ✅  |   ✅   | `@rn-primitives/avatar`                                |
+| **Badge**       | ✅  |   ✅   | Text wrapped in View; NativeWind variant classes       |
+| **Calendar**    | ✅  |   🚫   | Complex date picker; no RN primitive                   |
+| **Card**        | ✅  |   ✅   | View/Text-based; full sub-components                   |
+| **Carousel**    | ✅  |   🚫   | Embla-based; no comparable RN lib yet                  |
+| **Chart**       | ✅  |   🚫   | recharts (web-only SVG); consider victory-native later |
+| **Collapsible** | ✅  |   ✅   | `@rn-primitives/collapsible`                           |
+| **Skeleton**    | ✅  |   ✅   | Reanimated pulsing opacity (vs CSS animation)          |
+| **Table**       | ✅  |   ✅   | View/Text-based rows; no HTML table                    |
+| **Text**        | ✅  |   ✅   | Typography scale; `variant` prop shared                |
+
+### Feedback
+
+| Component        | Web | Native | Notes                                              |
+| :--------------- | :-: | :----: | :------------------------------------------------- |
+| **Alert Dialog** | ✅  |   ✅   | `@rn-primitives/alert-dialog` + Reanimated overlay |
+| **Dialog**       | ✅  |   ✅   | `@rn-primitives/dialog` + Reanimated fade          |
+| **Hover Card**   | ✅  |   🚫   | Hover interaction; not applicable on touch         |
+| **Popover**      | ✅  |   🚫   | No `@rn-primitives/popover` yet                    |
+| **Progress**     | ✅  |   🚫   | No `@rn-primitives/progress` yet                   |
+| **Sheet**        | ✅  |   ✅   | SlideInRight/Left Reanimated; side prop supported  |
+| **Skeleton**     | ✅  |   ✅   | See Data Display above                             |
+| **Sonner**       | ✅  |   🚫   | Web toast library; use `Toast` on native           |
+| **Toast**        | ✅  |   ✅   | `@rn-primitives/toast` + FadeInUp animation        |
+| **Tooltip**      | ✅  |   ✅   | `@rn-primitives/tooltip` + FadeIn/FadeOut          |
+
+### Navigation
+
+| Component           | Web | Native | Notes                                          |
+| :------------------ | :-: | :----: | :--------------------------------------------- |
+| **Breadcrumb**      | ✅  |   🚫   | Navigation-heavy; alternative: Text links      |
+| **Command**         | ✅  |   🚫   | cmdk-based; no RN equivalent                   |
+| **Context Menu**    | ✅  |   🚫   | Right-click/long-press; consider ActionSheet   |
+| **Drawer**          | ✅  |   🚫   | vaul-based; Sheet covers the pattern on native |
+| **Dropdown Menu**   | ✅  |   🚫   | Pointer-triggered; no RN primitive yet         |
+| **Menubar**         | ✅  |   🚫   | Desktop navigation pattern                     |
+| **Navigation Menu** | ✅  |   🚫   | Web navigation pattern                         |
+| **Pagination**      | ✅  |   🚫   | Alternative: infinite scroll on native         |
+| **Search**          | ✅  |   ✅   | Command palette pattern                        |
+| **Sheet**           | ✅  |   ✅   | See Feedback above                             |
+| **Tabs**            | ✅  |   ✅   | `@rn-primitives/tabs` + TextClassContext       |
+
+### Layout
+
+| Component        | Web | Native | Notes                                             |
+| :--------------- | :-: | :----: | :------------------------------------------------ |
+| **Aspect Ratio** | ✅  |   🚫   | CSS `aspect-ratio`; RN View handles this natively |
+| **Resizable**    | ✅  |   🚫   | Drag-based; not a native interaction pattern      |
+| **Scroll Area**  | ✅  |   🚫   | Native scroll is built-in via `ScrollView`        |
+| **Separator**    | ✅  |   ✅   | `@rn-primitives/separator`                        |
+
+### Utilities
+
+| Component        | Web | Native | Notes                            |
+| :--------------- | :-: | :----: | :------------------------------- |
+| **Theme Toggle** | ✅  |   ✅   | Dark/light/system; ThemeProvider |
+
+---
+
+## Platform Divergence Registry
+
+Document intentional platform differences here. Each entry explains the _semantic intent_ that's preserved across platforms.
+
+| Component        | Web Behavior                      | Native Behavior                        | Semantic Intent                                                 |
+| :--------------- | :-------------------------------- | :------------------------------------- | :-------------------------------------------------------------- |
+| **Button**       | `onClick` handler                 | `onPress` handler (Pressable)          | "User activates an action" — same semantics, different events   |
+| **Input**        | `onChange` → `event.target.value` | `onChangeText` → `string`              | "User enters text" — simpler callback on native                 |
+| **Label**        | `htmlFor` associates with input   | `nativeID` + `onPress` toggle          | "Label identifies a form control" — native uses ID association  |
+| **Checkbox**     | Browser-native checkbox input     | `@rn-primitives/checkbox` Pressable    | "Binary selection toggle"                                       |
+| **Dialog**       | `<Dialog>` Radix overlay          | `@rn-primitives/dialog` modal          | "Modal surface — blocking overlay for focused interaction"      |
+| **Sheet**        | Radix Dialog side panel           | SlideInRight/Left Reanimated animation | "Supplemental content panel" — side-anchored drawer             |
+| **Toast**        | `sonner` toast library            | `@rn-primitives/toast` + Reanimated    | "Transient feedback — dismissible notification"                 |
+| **Skeleton**     | CSS `animate-pulse` opacity       | Reanimated `withRepeat`/`withTiming`   | "Loading placeholder" — same visual, different animation engine |
+| **Tooltip**      | Radix hover tooltip               | `@rn-primitives/tooltip` + FadeIn      | "Contextual help text" — triggered by long-press on native      |
+| **Table**        | HTML `<table>` / `<tr>` / `<td>`  | `View` rows + `Text` cells             | "Tabular data display"                                          |
+| **Text**         | `<span>` / `<p>` with `cn()`      | RN `<Text>` with `variant` prop        | "Typographic content" — variant system shared                   |
+| **Accordion**    | Radix + CSS height animation      | Reanimated chevron + content           | "Expandable content section"                                    |
+| **Drawer (web)** | vaul bottom sheet                 | Use `Sheet` on native                  | "Modal panel from screen edge" — Sheet semantically equivalent  |
+| **Scroll Area**  | Custom scrollbar overlay          | Use RN `ScrollView` directly           | "Scrollable content region" — native ScrollView is built-in     |
+| **Sonner**       | Web-only animated toast library   | Use `Toast` on native                  | "Notification toasts" — Toast package covers native             |
+| **Popover**      | Radix floating portal             | _Not yet implemented_                  | "Floating contextual content"                                   |
+| **Progress**     | CSS progress bar                  | _Not yet implemented_                  | "Task completion indicator"                                     |
+
+---
+
+## Per-Component Migration Checklist
+
+### For existing components (ensuring contract alignment)
+
+1. **Contract** — Verify props/variants/sizes match `packages/ui-core/src/contracts/`
+2. **Web** — Confirm web component imports from `@gv-tech/ui-core` contracts
+3. **Native** — Confirm native component imports same contract + uses `@gv-tech/design-tokens`
+4. **Tests** — Web tests passing; add native test if not present
+5. **Playground** — Native tab wired in `doc-routes.tsx`; diff notes added to this registry
+
+### For new native components
+
+1. Check `@rn-primitives` for a matching primitive
+2. If no primitive exists, assess: is this interaction pattern appropriate for native?
+3. If yes, build from RN primitives (`View`, `Text`, `Pressable`, `TextInput`)
+4. Wire Reanimated for any animations
+5. Add to `ui-native/src/index.ts` and `docs.ts` platforms
+
+---
+
+## Outstanding Issues & Next Steps
+
+### 1. Native Test Coverage
+
+12 of 27+ native components have test files. Remaining components that need tests:
+
+- Accordion, Alert, Alert Dialog, Avatar, Badge, Label, Search, Select, Separator, Switch, Table, Tabs, Theme Toggle, Toggle, Toggle Group, Tooltip
+
+### 2. Native Playground Expansion
+
+`apps/native-playground/src/app/App.tsx` currently demos: Button, Card, Input, Checkbox, RadioGroup, Text, Badge. Add:
+
+- Accordion, Alert, AlertDialog, Avatar, Badge, Collapsible, Dialog, Select, Separator, Sheet, Skeleton, Switch, Table, Tabs, Toast, Toggle, Tooltip
+
+### 3. Token Expansion (Design Tokens)
+
+`packages/design-tokens` exports palette, theme, spacing, typography, shadows, and radii. Next:
+
+- Add a tokens reference page to the playground (showing all raw values)
+- Ensure `ui-native` consumes `design-tokens` directly (no duplication)
+
+### 4. Sub-Package Publishing
+
+Currently only `@gv-tech/design-system` (root) is published. Phase 2 should add:
+
+- `@gv-tech/ui-web`
+- `@gv-tech/ui-native`
+- `@gv-tech/ui-core`
+- `@gv-tech/design-tokens`
+
+> [!TIP]
+> During the transition period, the existing root package continues to work. The monorepo migration is additive — existing imports won't break until explicitly migrated.