@gv-tech/design-system 2.3.0 → 2.5.0

package/.agent/skills/dogfood-components/SKILL.md

@@ -11,24 +11,24 @@ Use this skill whenever you are modifying the documentation site structure, head
 
 ### 1. Analysis
 
-- **Identify Ad-hoc UI**: Look for custom HTML, Tailwind classes, or static elements in the docs site (`src/App.tsx`, `src/components/docs/`, `src/pages/`) that replicate component functionality.
-- **Check Library availability**: Verify if a corresponding component exists in `src/components/ui/` (e.g., Breadcrumbs, Tabs, Alerts, Badges).
+- **Identify Ad-hoc UI**: Look for custom HTML or static elements in the docs site (`src/App.tsx`, `src/components/docs/CombinedDocsLayout.tsx`, `src/pages/`) that replicate component functionality.
+- **Check Library availability**: Verify if a corresponding component exists in `@gv-tech/ui-web` (e.g., Breadcrumbs, Tabs, Alerts, Badges).
 
 ### 2. Implementation
 
-- **Prioritize Library Components**: Replace custom implementations with components from `@/components/ui/`.
+- **Prioritize Library Components**: Replace custom implementations with components from `@gv-tech/ui-web`.
 - **Pass Real State**: Connect these components to the documentation's state (e.g., using `activeItem` with `Breadcrumb` or `Tabs`).
 - **Consistent Styling**: Use the same variants and props that we recommend to our users.
 
 ### 3. Validation
 
 - **Functional Check**: Ensure the component behaves correctly within the documentation context (e.g., navigation links work).
-- **Visual Check**: Use browser subagents to verify the component renders with the correct theme and layout in the docs.
+- **Visual Check**: Verify the component renders with the correct theme and layout in the docs.
 
 ## Checklist
 
 - [ ] Identified custom UI elements that can be replaced.
-- [ ] Used components from `src/components/ui/` instead of ad-hoc HTML/CSS.
+- [ ] Used components from `@gv-tech/ui-web` instead of ad-hoc HTML/CSS.
 - [ ] Component is correctly wired to relevant documentation state.
 - [ ] Verified that navigation and interaction remains functional.
-- [ ] `yarn lint` and `npx tsc --noEmit` pass.
+- [ ] `yarn validate` passes successfully.

package/.agent/skills/maintain-component/SKILL.md

@@ -5,38 +5,73 @@ description: Guidelines for creating or updating UI components, ensuring tests a
 
 # Component Maintenance Skill
 
-Use this skill whenever you are tasked with creating a new UI component or modifying an existing one in the `gvtech-design` library.
+Use this skill whenever you are tasked with creating a new UI component or modifying an existing one in the `gvtech-design` library. All components must follow the monorepo-based architecture to support Web, React Native, and shared contracts.
+
+## Architecture Standards
+
+Components are split across three primary packages:
+
+1. **`@gv-tech/ui-core`**: Shared contracts/interfaces.
+   - Location: `packages/ui-core/src/contracts/[name].ts`
+   - Role: Defines the "Truth" of what a component's API should be.
+2. **`@gv-tech/ui-web`**: Web (DOM/Radix) implementation.
+   - Location: `packages/ui-web/src/[name].tsx`
+   - Tests: `packages/ui-web/src/[name].test.tsx`
+3. **`@gv-tech/ui-native`**: React Native (NativeWind) implementation.
+   - Location: `packages/ui-native/src/[name].tsx`
 
 ## Workflow
 
-### 1. Preparation
+### 1. Contract Definition (Core)
+
+- Always start by defining or updating the base props in `packages/ui-core/src/contracts/[name].ts`.
+- Export these props from `packages/ui-core/src/index.ts`.
+- **CRITICAL**: Use specific types. Avoid `any`. Use `unknown` or specific interfaces for extension.
+
+### 2. Platform Implementation
 
-- **Audit**: Identify the component file (`src/components/ui/`), its documentation page (`src/pages/components/`), and its test file (`src/components/ui/*.test.tsx`).
-- **Plan**: Ensure the requested changes will be reflected in all three areas.
+- **Web**:
+  - Build the implementation in `packages/ui-web/src/[name].tsx`.
+  - Import contracts from `@gv-tech/ui-core`.
+  - Import internal utilities (like `cn`) from `./lib/utils` (relative).
+  - Export the component and its types from `packages/ui-web/src/index.ts`.
+- **Native**:
+  - Build the implementation in `packages/ui-native/src/[name].tsx`.
+  - If not yet implemented, provide a "Not implemented" shim.
+  - Import internal utilities from `./lib/utils` (relative).
+  - Export the component from `packages/ui-native/src/index.ts`.
 
-### 2. Implementation
+### 3. Documentation & Registry
 
-- **Component Code**: Apply changes to the component in `src/components/ui/`.
-- **Tests**:
-  - Create or update the test suite in `src/components/ui/[component].test.tsx`.
-  - Use `vitest` and `@testing-library/react`.
-  - Ensure 100% pass rate.
-- **Documentation**:
-  - Update the corresponding page in `src/pages/components/`.
-  - **CRITICAL**: Ensure the `PropsTable` is updated to reflect any changes to the component's API.
-  - Add or update usage examples in `ComponentShowcase`.
+- **Documentation Implementation**:
+  - Create/Update web-specific docs in `src/pages/web/[ComponentName]Docs.tsx`.
+  - Create/Update native-specific docs in `src/pages/native/[ComponentName]Docs.tsx`.
+  - **Structure**: Documentation files should **not** use `ComponentSection` (this is now handled by the layout). They should return a React Fragment `<>...</>` containing `ComponentShowcase` and implementations.
+  - **Register in App.tsx**:
+    - Add the new route to `src/App.tsx`.
+    - Use `<CombinedDocsLayout />` and pass the `title`, `description`, `web`, and `native` implementations as props.
+  - **Context**: Ensure `PropsTable` matches the `ui-core` contract and covers both platforms if they differ.
+- **Registry**: Run `yarn build:registry` to update the component JSON files in `public/registry`.
 
-### 3. Verification
+### 4. Verification
 
-- **Linting**: Run `yarn lint` to ensure no new lint errors are introduced.
-- **Testing**: Run `yarn test [component].test.tsx` to verify the component's logic.
-- **Type Checking**: Run `npx tsc --noEmit` to catch TypeScript errors.
+- **Full Suite**: Run `yarn validate` from the root. This runs:
+  - `sync-tokens`: Ensures design tokens are updated.
+  - `lint`: Checks project-wide ESLint (no `any`, no unused vars).
+  - `tsc`: Verifies TypeScript types across all workspaces.
+  - `test`: Runs Vitest across all packages.
+  - `build`: Verifies Vite/Nx build status.
 
 ## Checklist
 
-- [ ] Component code updated/created.
-- [ ] Test suite updated/created and passing.
-- [ ] Documentation page updated/created.
-- [ ] `PropsTable` accurately reflects the current API.
-- [ ] `yarn lint` passes.
-- [ ] `npx tsc --noEmit` passes.
+- [ ] Contract updated in `packages/ui-core/src/contracts/`.
+- [ ] Props exported from `packages/ui-core/src/index.ts`.
+- [ ] Web implementation updated in `packages/ui-web/src/`.
+- [ ] Native implementation/shim updated in `packages/ui-native/src/`.
+- [ ] Exported via `index.ts` in respective packages.
+- [ ] Web docs updated in `src/pages/web/` (without `ComponentSection`).
+- [ ] Native docs updated in `src/pages/native/` (without `ComponentSection`).
+- [ ] Route registered in `src/App.tsx` using `CombinedDocsLayout` with `title` and `description`.
+- [ ] `yarn build:registry` run to update public registry.
+- [ ] `yarn validate` passes successfully (Green state).
+- [ ] **Strict**: No `any` types used in new/modified code.

package/.agent/workflows/native-playground.md

@@ -0,0 +1,93 @@
+---
+description: Running the native playground on an Android emulator
+---
+
+# Native Playground — Local Development
+
+This workflow starts the Expo dev server for `apps/native-playground` and connects it to a local Android emulator.
+
+## Prerequisites
+
+- Android Studio installed (at `/snap/bin/android-studio`)
+- At least one AVD configured. Available AVDs:
+  - `Pixel_9` (recommended)
+  - `Medium_Phone_API_36.0`
+- Yarn dependencies installed (`yarn install` from repo root)
+
+---
+
+## Step 1: Boot the Android Emulator
+
+Open a terminal and start the emulator (leave it running in the background):
+
+```bash
+$ANDROID_HOME/emulator/emulator -avd Pixel_9 &
+```
+
+Wait for the emulator to fully boot to the home screen (~30–60 seconds).
+
+> **Tip:** You can also launch the emulator from Android Studio → Device Manager → ▶ Run.
+
+---
+
+## Step 2: Start the Expo Dev Server
+
+// turbo
+From the **monorepo root**, run:
+
+```bash
+yarn native:android
+```
+
+This runs `npx nx run native-playground:start --android`, which:
+
+1. Starts the Metro bundler (NativeWind + Nx monorepo-aware)
+2. Detects the running emulator
+3. Installs Expo Go (or the dev client) on the emulator automatically
+4. Opens the playground app
+
+---
+
+## Alternative Commands
+
+| Command                                    | Description                                                        |
+| ------------------------------------------ | ------------------------------------------------------------------ |
+| `yarn native`                              | Start Expo with interactive picker (QR + emulator options)         |
+| `yarn native:android`                      | Start and immediately open on Android emulator                     |
+| `yarn native:clear`                        | Start Android with cleared Metro cache (fixes stale bundle issues) |
+| `npx nx run native-playground:run-android` | Full native build (slower, no Expo Go)                             |
+
+---
+
+## Monorepo Hot Reload
+
+Changes to `packages/ui-native` will automatically hot-reload in the emulator because `metro.config.js` uses `withNxMetro`, which watches all monorepo workspace packages.
+
+If hot reload stops working, run `yarn native:clear` to reset the bundler cache.
+
+---
+
+## Troubleshooting
+
+**Emulator not detected:**
+
+```bash
+adb devices   # should list the emulator
+adb kill-server && adb start-server  # restart ADB if needed
+```
+
+**Metro can't resolve monorepo packages:**
+
+```bash
+yarn install  # re-link workspace packages
+yarn native:clear  # clear bundler cache
+```
+
+**`ANDROID_HOME` not set:**
+
+```bash
+export ANDROID_HOME=$HOME/Android/Sdk
+export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools
+```
+
+Add these to your `~/.zshrc` for persistence.

package/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ["20", "22", "24"]
+        node: ["22", "24"]
     steps:
       - uses: actions/checkout@v6
       - name: Use Node.js ${{ matrix.node }}
@@ -42,6 +42,15 @@ jobs:
       - name: Install dependencies
         run: yarn install
 
+      - name: Restore Nx Cache
+        uses: actions/cache@v4
+        with:
+          path: .nx/cache
+          key: ${{ runner.os }}-nx-${{ matrix.node }}-${{ hashFiles('yarn.lock') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-nx-${{ matrix.node }}-${{ hashFiles('yarn.lock') }}-
+            ${{ runner.os }}-nx-${{ matrix.node }}-
+
       - name: Format
         run: yarn format:ci
 
@@ -66,6 +75,15 @@ jobs:
       - name: Install dependencies
         run: yarn install --immutable
 
+      - name: Restore Nx Cache
+        uses: actions/cache@v4
+        with:
+          path: .nx/cache
+          key: ${{ runner.os }}-nx-24-${{ hashFiles('yarn.lock') }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-nx-24-${{ hashFiles('yarn.lock') }}-
+            ${{ runner.os }}-nx-24-
+
       - name: Build Library
         run: yarn build
 

package/.github/workflows/release-please.yml

@@ -29,11 +29,11 @@ jobs:
         run: echo "If a release PR is created, review and merge it to create a tag/release."
 
       - name: Checkout Code
-        if: ${{ steps.release.outputs.release_created }}
+        if: ${{ steps.release.outputs.releases_created }}
         uses: actions/checkout@v6
 
       - name: Use Node.js 24
-        if: ${{ steps.release.outputs.release_created }}
+        if: ${{ steps.release.outputs.releases_created }}
         uses: actions/setup-node@v6
         with:
           node-version: 24
@@ -41,13 +41,39 @@ jobs:
           cache: "yarn"
 
       - name: Install dependencies
-        if: ${{ steps.release.outputs.release_created }}
+        if: ${{ steps.release.outputs.releases_created }}
         run: yarn install --immutable
 
       - name: Build
-        if: ${{ steps.release.outputs.release_created }}
+        if: ${{ steps.release.outputs.releases_created }}
         run: yarn build
 
       - name: Publish to npm
-        if: ${{ steps.release.outputs.release_created }}
-        run: npm publish --provenance
+        if: ${{ steps.release.outputs.releases_created }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          # Iterate over each released package path
+          echo '${{ steps.release.outputs.paths_released }}' | jq -r '.[]' | while read -r path; do
+            echo "--- Publishing package at: $path ---"
+            cd "$path"
+            
+            # Skip if the package is private
+            if jq -e '.private == true' package.json > /dev/null; then
+              echo "Skipping private package: $(jq -r '.name' package.json)"
+              cd - > /dev/null
+              continue
+            fi
+            
+            # Build the package if a build script exists
+            if jq -e '.scripts.build' package.json > /dev/null; then
+              echo "Building $(jq -r '.name' package.json)..."
+              yarn build
+            fi
+            
+            # Publish to npm
+            echo "Publishing $(jq -r '.name' package.json)..."
+            npm publish --provenance --access public
+            
+            cd - > /dev/null
+          done

package/.release-please-manifest.json

@@ -1,3 +1,9 @@
 {
-  ".": "2.3.0"
+  ".": "2.5.0",
+  "packages/ui-web": "0.1.0",
+  "packages/ui-native": "0.1.0",
+  "packages/ui-core": "0.1.0",
+  "packages/design-tokens": "0.1.0",
+  "apps/playground-web": "0.1.0",
+  "apps/native-playground": "0.1.0"
 }

package/.tool-versions

@@ -1 +1 @@
-nodejs 22.21.1
+nodejs 24.13.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.5.0](https://github.com/Garcia-Ventures/gvtech-design/compare/design-system-v2.4.0...design-system-v2.5.0) (2026-02-20)
+
+
+### Features
+
+* **universal:** pivot to monorepo architecture and stabilize react native support ([#63](https://github.com/Garcia-Ventures/gvtech-design/issues/63)) ([3458938](https://github.com/Garcia-Ventures/gvtech-design/commit/3458938c17bdfc7a7f5eea0053b7bf1786a571fa))
+
+## [2.4.0](https://github.com/Garcia-Ventures/gvtech-design/compare/design-system-v2.3.0...design-system-v2.4.0) (2026-02-16)
+
+
+### Features
+
+* Implement mobile sidebar and improve responsive styling and accessibility for documentation and UI components. ([9fafda0](https://github.com/Garcia-Ventures/gvtech-design/commit/9fafda0a890595b7a343aea161325e25bd7d0224))
+* Introduce automated design token synchronization and granular component exports for the design system. ([068f010](https://github.com/Garcia-Ventures/gvtech-design/commit/068f010a43a8ae12edd1e89a693345d1e7679bb5))
+
 ## [2.3.0](https://github.com/Garcia-Ventures/gvtech-design/compare/design-system-v2.2.0...design-system-v2.3.0) (2026-02-13)
 
 

package/apps/native-playground/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0](https://github.com/Garcia-Ventures/gvtech-design/compare/native-playground-v0.0.1...native-playground-v0.1.0) (2026-02-20)
+
+
+### Features
+
+* **universal:** pivot to monorepo architecture and stabilize react native support ([#63](https://github.com/Garcia-Ventures/gvtech-design/issues/63)) ([3458938](https://github.com/Garcia-Ventures/gvtech-design/commit/3458938c17bdfc7a7f5eea0053b7bf1786a571fa))

package/apps/native-playground/app.json

@@ -0,0 +1,37 @@
+{
+  "expo": {
+    "name": "NativePlayground",
+    "slug": "native-playground",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/images/icon.png",
+    "scheme": "native-playground",
+    "userInterfaceStyle": "automatic",
+    "newArchEnabled": true,
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "foregroundImage": "./assets/images/adaptive-icon.png",
+        "backgroundColor": "#ffffff"
+      },
+      "edgeToEdgeEnabled": true
+    },
+    "web": {
+      "bundler": "metro",
+      "favicon": "./assets/images/favicon.png"
+    },
+    "plugins": [
+      [
+        "expo-splash-screen",
+        {
+          "image": "./assets/images/splash-icon.png",
+          "imageWidth": 200,
+          "resizeMode": "contain",
+          "backgroundColor": "#ffffff"
+        }
+      ]
+    ]
+  }
+}

package/apps/native-playground/babel.config.js

@@ -0,0 +1,6 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [['babel-preset-expo', { jsxImportSource: 'nativewind' }], 'nativewind/babel'],
+  };
+};

package/apps/native-playground/eas.json

@@ -0,0 +1,25 @@
+{
+  "build": {
+    "production": {
+      "android": {
+        "buildType": "app-bundle"
+      }
+    },
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal",
+      "ios": {
+        "simulator": true
+      },
+      "android": {
+        "buildType": "apk"
+      }
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

package/apps/native-playground/index.js

@@ -0,0 +1,8 @@
+import { registerRootComponent } from 'expo';
+
+import App from './src/app/App';
+
+// registerRootComponent calls AppRegistry.registerComponent('main', () => App);
+// It also ensures that whether you load the app in Expo Go or in a native build,
+// the environment is set up appropriately
+registerRootComponent(App);

package/apps/native-playground/metro.config.js

@@ -0,0 +1,26 @@
+const { withNxMetro } = require('@nx/expo');
+const { getDefaultConfig } = require('@expo/metro-config');
+const { mergeConfig } = require('metro-config');
+const { withNativeWind } = require('nativewind/metro');
+
+const defaultConfig = getDefaultConfig(__dirname);
+const { assetExts, sourceExts } = defaultConfig.resolver;
+
+const customConfig = {
+  cacheVersion: 'native-playground',
+  transformer: {
+    babelTransformerPath: require.resolve('react-native-svg-transformer'),
+  },
+  resolver: {
+    assetExts: assetExts.filter((ext) => ext !== 'svg'),
+    sourceExts: [...sourceExts, 'cjs', 'mjs', 'svg'],
+  },
+};
+
+const config = withNxMetro(mergeConfig(defaultConfig, customConfig), {
+  debug: false,
+  extensions: [],
+  watchFolders: [],
+});
+
+module.exports = withNativeWind(config, { input: './src/global.css' });

package/apps/native-playground/nativewind-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="nativewind/types" />

package/apps/native-playground/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "native-playground",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "eas-build-post-install": "cd ../../ && node tools/scripts/eas-build-post-install.mjs . apps/native-playground"
+  },
+  "dependencies": {
+    "@expo/metro-config": "*",
+    "expo": "*",
+    "expo-splash-screen": "*",
+    "expo-status-bar": "*",
+    "expo-system-ui": "*",
+    "metro-config": "*",
+    "metro-resolver": "*",
+    "nativewind": "4.1.23",
+    "react": "*",
+    "react-native": "*",
+    "react-native-svg": "*",
+    "react-native-svg-transformer": "*",
+    "react-native-web": "*"
+  }
+}

package/apps/native-playground/project.json

@@ -0,0 +1,15 @@
+{
+  "name": "native-playground",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "apps/native-playground/src",
+  "projectType": "application",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "echo 'Skip build for playground'"
+      }
+    }
+  }
+}