# R2 Dev Page

> Generate frontend page code from specifications Use when this capability is needed.

- Skill: `tomevault-io/r2-dev-page` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/r2-dev-page`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/r2-dev-page/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- 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/r2-dev-page

---


# r2-dev-page

Generate frontend page code from requirements. Frontend only - no backend code.

## Role
Frontend Developer - Generate production-ready page code and API client integration only.

## Scope
**✅ Frontend Development**:
- UI components (framework-specific)
- State management (hooks/composables/signals)
- API client (HTTP calls to backend)
- Type definitions (from API schemas)
- Frontend validation
- Error handling and loading states

**❌ NOT in Scope**:
- Backend API implementation
- Database operations
- Server-side logic
- API route handlers
- Authentication middleware
- Business logic on server

## Input
- `requirement.page.md` - Page requirements (primary, Section 4 for APIs)
- `page.yaml` - Lifecycle configuration (6 phases)
- `requirement.module.md` - Module context (parent)
- `metadata.yaml` - Module configuration
- `api.yaml` - Module APIs (generated by extract-api.py, if exists)
- `schemas.yaml` - Module schemas (generated by extract-schema.py, if exists)
- `{PROJECT_ROOT}/.r2mo/requirements/project.md` - Tech stack definition
- `{PROJECT_ROOT}/.r2mo/api/metadata.yaml` - Full API definitions (fallback)
- `{PROJECT_ROOT}/.r2mo/api/components/schemas/*.md` - Data models (fallback)
- `{PROJECT_ROOT}/.r2mo/domain/*.proto` - Domain models (fallback)
- `{PROJECT_ROOT}/.r2mo/design/spec.md` - UI specs (optional)
- `{PROJECT_ROOT}/.r2mo/api/marker.md` - Validation rules (optional)

## Output
**7 file types** (structure depends on detected tech stack):
- Component file
- State management (hook/composable/store)
- API service client (HTTP client only)
- Type definitions
- Constants and enums
- Styles
- Tests

## Built-in Tool: extract-api.py

**Purpose**: Extract module-specific APIs from large OpenAPI metadata.yaml

**Location**: `{SKILL_ROOT}/scripts/extract-api.py`
- `{SKILL_ROOT}` resolves from skill repository or installation path
- Script location depends on how skill is installed/integrated

**When to Use**:
- Module has > 10 APIs in metadata.yaml
- Need to focus on specific API patterns
- Want faster code generation
- Clear module API boundaries

**Usage**:
```bash
cd {module-dir}

# Locate script from skill root
python {SKILL_ROOT}/scripts/extract-api.py -m {pattern} -o api.yaml

# Example patterns from metadata.yaml api.match
python {SKILL_ROOT}/scripts/extract-api.py -m user -m role -o api.yaml
```

**Output**: `api.yaml` in module directory
- Contains only matched APIs
- Includes referenced schemas automatically
- Smaller file size for AI processing

## Built-in Tool: extract-schema.py

**Purpose**: Extract module-specific data models from schemas and domain definitions

**Location**: `{SKILL_ROOT}/scripts/extract-schema.py`
- `{SKILL_ROOT}` resolves from skill repository or installation path
- Script location depends on how skill is installed/integrated

**When to Use**:
- Module has > 10 schemas in `.r2mo/api/components/schemas/`
- Need to focus on specific data models
- Want faster type generation
- Clear module data model boundaries

**Usage**:
```bash
cd {module-dir}

# Locate script from skill root
python {SKILL_ROOT}/scripts/extract-schema.py -m {pattern} -o schemas.yaml

# Example patterns from metadata.yaml schema.match
python {SKILL_ROOT}/scripts/extract-schema.py -m user -m role -o schemas.yaml
```

**Output**: `schemas.yaml` in module directory
- Contains matched Markdown schemas from `.r2mo/api/components/schemas/`
- Contains matched Proto files from `.r2mo/domain/`
- Organized by schema name
- Smaller file size for AI processing

**Combined Usage**:
```bash
cd {module-dir}

# Extract both APIs and Schemas
python {SKILL_ROOT}/scripts/extract-api.py -m {pattern} -o api.yaml
python {SKILL_ROOT}/scripts/extract-schema.py -m {pattern} -o schemas.yaml
```

## Process

### 0. Data Extraction (Optional but Recommended)

**When to execute**:
- Module has > 10 APIs or > 10 schemas
- metadata.yaml or schemas directory is large
- Need focused scope for code generation

**How to execute**:
```bash
cd {module-dir}

# Read metadata.yaml api.match and schema.match patterns

# Extract APIs (optional)
python {SKILL_ROOT}/scripts/extract-api.py -m {pattern1} -m {pattern2} -o api.yaml

# Extract Schemas (optional)
python {SKILL_ROOT}/scripts/extract-schema.py -m {pattern1} -m {pattern2} -o schemas.yaml

# Verify outputs
ls -lh api.yaml schemas.yaml
```

**Result**: 
- `api.yaml`: Module-specific APIs
- `schemas.yaml`: Module-specific data models

### 0. API Extraction (Optional but Recommended)

**When to execute**:
- Module has > 10 APIs
- metadata.yaml > 1MB
- Need focused API scope

**How to execute**:
```bash
cd {module-dir}

# Read metadata.yaml api.match patterns
# Execute: python {SKILL_ROOT}/scripts/extract-api.py -m {pattern1} -m {pattern2} -o api.yaml

# Verify output
# Check: api.yaml exists and is smaller than metadata.yaml
```

**Result**: `api.yaml` created in module directory with module-specific APIs

### 1. Detect Tech Stack

```
Read: {PROJECT_ROOT}/.r2mo/requirements/project.md
Extract:
  - frontend_framework (required)
  - ui_library (required)
  - state_management (required)
  - language (required)
  - build_tool (required)
  - http_client (required)
  - test_framework (required)

Validate: All required fields present
Fallback: ERROR if tech stack not defined - cannot proceed
```

**Critical**: Tech stack MUST be defined in project.md. No assumptions.

### 2. Load Specifications

```
Read: requirement.page.md (8 sections)
  - Section 3: Data models (entities)
  - Section 4: API operations (endpoints, methods)
  - Section 5: Page components
  - Section 6: Form fields (if applicable)
  - Section 7: Permissions
  - Section 8: Lifecycle phases

Read: page.yaml (6 lifecycle phases)
  - init, query, action, validate, event, cleanup

Check: change_history field
  - Empty: Mode 1 (0-1 complete generation)
  - Not empty: Mode 2 (1-1.1 incremental update)
```

### 3. Load API Context (Priority Order)

```
Priority 1: api.yaml in module directory
  - If exists: Use this (generated by extract-api.py)

Priority 2: {PROJECT_ROOT}/.r2mo/api/metadata.yaml
  - Fallback to full API definitions

Parse from chosen source:
  - API endpoints from requirement.page.md Section 4
  - HTTP methods (GET/POST/PUT/DELETE/PATCH)
  - Request schemas
  - Response schemas
  - Error responses

Critical: Use API paths from requirement.page.md Section 4 exactly
  - DO NOT create new paths
  - DO NOT modify paths
  - DO NOT design paths
```

### 4. Load Data Models (Priority Order)

```
Priority 1: schemas.yaml in module directory
  - If exists: Use this (generated by extract-schema.py)

Priority 2: {PROJECT_ROOT}/.r2mo/api/components/schemas/*.md
  - Fallback to full schema definitions (Markdown format)

Priority 3: {PROJECT_ROOT}/.r2mo/domain/*.proto
  - Fallback to domain models (Proto format)

Parse from chosen source:
  - Entities from requirement.page.md Section 3
  - Entity structures
  - Field types
  - Field constraints
  - Relationships

Purpose: Generate type definitions for frontend
```

### 5. Generate Frontend Code Files

**Mode 1 (0-1 Complete)**: Generate all 7 file types
**Mode 2 (1-1.1 Update)**: Generate modified files only (based on change_history)

**File Structure**: Based on detected tech stack from project.md
- Use tech stack conventions
- Follow framework patterns
- Respect project structure

**Content Generation Rules**:

1. **Component File**
   - Based on page_type from requirement.page.md (list/form/detail/dashboard)
   - Implement 6 lifecycle phases from page.yaml
   - Use UI library components from project.md
   - Responsive design from design/spec.md

2. **State Management**
   - Implement 6 lifecycle phases:
     - init: Permission check, data loading, dict loading
     - query: Search validation, API call, render
     - action: CRUD operations from Section 4 APIs
     - validate: Field rules from Section 6, business rules
     - event: User interactions
     - cleanup: Cancel requests, clear listeners
   - Use state management pattern from project.md

3. **API Service Client** ← CRITICAL: Frontend HTTP client ONLY
   - Generate method for each API from requirement.page.md Section 4
   - Use http_client from project.md (axios/fetch/etc)
   - Use API paths from Section 4 exactly (DO NOT create/modify)
   - Include request/response types
   - Error handling and transformation
   - Loading state management
   
   ```
   // Example structure (NOT actual code)
   function callAPI(endpoint, method, params) {
     // HTTP call to backend
     // Error handling
     // Return typed response
   }
   ```

4. **Type Definitions**
   - From schemas/*.md (Section 3 entities)
   - Query/Filter types
   - Request/Response types
   - Error types
   - Use language from project.md (TypeScript/Flow/JSDoc/etc)

5. **Constants**
   - Status enums from data models
   - Validation rules from Section 6 + marker.md
   - Error messages (Chinese)
   - Page size options
   - Config values

6. **Styles**
   - From design/spec.md
   - Responsive design
   - Framework-specific styling approach
   - Component styles

7. **Tests**
   - Use test_framework from project.md
   - State management tests
   - API client tests (mock HTTP)
   - Component tests (if applicable)

## Rules

1. **Frontend only** - Generate UI and API client, NO backend implementation
2. **Use existing APIs** - API paths from requirement.page.md Section 4, DO NOT create
3. **Follow tech stack** - Use framework from project.md, NO assumptions
4. **Chinese comments** - Code comments in Chinese, variables in English
5. **Type safe** - Use type system properly
6. **Error handling** - Comprehensive client-side error handling
7. **Follow lifecycle** - Implement all 6 phases from page.yaml
8. **Production ready** - Include tests, error handling, loading states
9. **API client only** - HTTP calls to backend, not API implementation
10. **No assumptions** - If tech stack undefined, ERROR - do not proceed

## API Integration Guidelines

### ✅ DO Generate (Frontend HTTP Client):
- HTTP client methods using http_client from project.md
- Request parameter types
- Response data types
- Error handling and transformation
- Loading state management
- Retry logic (frontend)
- Request cancellation

### ❌ DO NOT Generate (Backend Implementation):
- API route handlers
- Database queries
- Business logic on server
- Authentication middleware
- API route definitions
- Server-side validation
- Backend error handling

### Example Structure (Conceptual):

**From requirement.page.md Section 4**:
```
| 操作 | 端点 | 方法 | 说明 |
| 查询列表 | /api/users | GET | 获取用户列表 |
```

**Generate (Frontend client structure)**:
```
HTTP Client Method:
  - Function: fetch user list
  - Endpoint: /api/users (from Section 4)
  - Method: GET
  - Request: Query parameters (typed)
  - Response: User list (typed)
  - Error: Handle and transform
```

**DO NOT Generate (Backend)**:
```
Backend route handler
Database query
Business logic
Authentication check
```

## Validation

- [ ] Tech stack detected from project.md (all required fields)
- [ ] All 7 file types generated (Mode 1) or modified files (Mode 2)
- [ ] 6 lifecycle phases implemented
- [ ] API client code only (no backend implementation)
- [ ] API paths from requirement.page.md Section 4 (not created/modified)
- [ ] Types from schemas/*.md
- [ ] Validation rules from Section 6 + marker.md
- [ ] Chinese comments, English code
- [ ] Code follows tech stack conventions
- [ ] Compiles without errors
- [ ] Tests pass
- [ ] No backend route handlers generated
- [ ] No assumptions about tech stack

## Context Paths Reference

```
Page Directory: {page-dir}
├── requirement.page.md              ← Primary input (Section 4: API operations)
├── page.yaml                        ← Lifecycle config (6 phases)
└── src/                             ← Generated code output
│
Module Directory: {module-dir}
├── requirement.module.md            ← Module context
├── metadata.yaml                    ← Module config (api.match, schema.match patterns)
├── api.yaml                         ← Extracted APIs (optional, by extract-api.py)
└── schemas.yaml                     ← Extracted schemas (optional, by extract-schema.py)
│
Project Root: {PROJECT_ROOT}/.r2mo/
├── requirements/project.md          ← Tech stack definition (REQUIRED)
├── api/
│   ├── metadata.yaml               ← Full API definitions (fallback)
│   ├── operations/**/*.md          ← API operations (reference only)
│   ├── components/schemas/*.md     ← Data models (fallback)
│   └── marker.md                   ← Validation rules
├── domain/*.proto                  ← Domain models (fallback)
└── design/spec.md                  ← UI/UX specs (optional)
│
Skill Root: {SKILL_ROOT}
└── scripts/
    ├── extract-api.py               ← API extraction tool
    └── extract-schema.py            ← Schema extraction tool
```

## Tool Path Resolution

**Built-in tools location**:
- `{SKILL_ROOT}/scripts/extract-api.py` - API extraction
- `{SKILL_ROOT}/scripts/extract-schema.py` - Schema extraction
- `{SKILL_ROOT}` is resolved from skill installation location
- User must locate scripts based on their setup

**Usage in different projects**:
```bash
# Project A
cd /project-a/modules/user
python {path-to-skill}/scripts/extract-api.py -m user -o api.yaml
python {path-to-skill}/scripts/extract-schema.py -m user -o schemas.yaml

# Project B
cd /project-b/modules/order
python {path-to-skill}/scripts/extract-api.py -m order -o api.yaml
python {path-to-skill}/scripts/extract-schema.py -m order -o schemas.yaml
```

## Success Criteria

- All files generated and compile successfully
- Tech stack from project.md applied correctly
- 6 lifecycle phases implemented correctly
- API client integrates with backend (HTTP calls only)
- API paths match requirement.page.md Section 4 exactly
- Types match schemas/*.md
- Validation rules applied
- Production-ready frontend code
- NO backend implementation generated
- NO tech stack assumptions made
- Ready for backend integration

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