# Maintain Component

> Guidelines for creating or updating UI components, ensuring tests and documentation stay in sync. Use when this capability is needed.

- Skill: `tomevault-io/maintain-component` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/maintain-component`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/maintain-component/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/maintain-component

---


# 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. 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. 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

- **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`.

### 3. Documentation & Registry

- **Documentation Implementation**:
  - Create/Update web-specific docs in `apps/playground-web/src/pages/web/[ComponentName]Docs.tsx`.
  - Create/Update native-specific docs in `apps/playground-web/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 `apps/playground-web/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 `bun build:registry` to update the component JSON files in `public/registry`.

### 4. Verification

- **Full Suite**: Run `bun 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

- [ ] 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 `apps/playground-web/src/pages/web/` (without `ComponentSection`).
- [ ] Native docs updated in `apps/playground-web/src/pages/native/` (without `ComponentSection`).
- [ ] Route registered in `apps/playground-web/src/App.tsx` using `CombinedDocsLayout` with `title` and `description`.
- [ ] `bun build:registry` run to update public registry.
- [ ] `bun validate` passes successfully (Green state).
- [ ] **Strict**: No `any` types used in new/modified code.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/garcia-ventures) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->