v0-rails/instructions.md

Convert React/JSX + Tailwind UI code from v0.dev to Rails ViewComponent classes and ERB templates with automatic slot detection, icon handling, and route generation

# v0-rails Improvement Instructions

## Overview of Issues

Based on experience integrating v0-rails with a Rails application, we've identified several areas for improvement that would enhance the conversion process and reduce manual intervention:

## 1. Documentation vs. Implementation Alignment

**Issue:** The README documentation mentions options that aren't actually implemented in the current version.

**Improvements:**

- Align command line options in the documentation with the actual implementation
- Ensure all advertised features in the README are actually implemented
- Implement missing features like `--source-map`, `--maintain-hierarchy`, etc.
- Add version information to help command to clarify which features are available in the current version

## 2. Component Conversion Quality

**Issue:** Component conversion has multiple warnings and requires significant manual editing afterwards.

**Improvements:**

- Better handling of complex JSX structures and components with multiple root elements
- Enhanced icon component detection and SVG conversion
- Improved handling of component attributes and props, especially for variants/sizes
- Support for nested components (composition) with proper component nesting in Rails ViewComponent

## 3. Icon Handling

**Issue:** Icon components were not properly converted and required manual SVG implementation.

**Improvements:**

- Automatically detect and convert icon components to SVG elements
- Provide option to create a centralized icon component system for Rails
- Support for common icon libraries (Heroicons, Lucide, etc.)
- Maintain icon naming conventions and accessibility features

## 4. Button and Interactive Element Conversion

**Issue:** Button variants and interactive elements lost their styling properties during conversion.

**Improvements:**

- Parse and maintain variant/size properties for interactive elements
- Generate appropriate Rails helper methods for repeated UI patterns
- Add Stimulus controllers for interactive elements automatically
- Convert React event handlers to appropriate Stimulus actions

## 5. Rails Integration

**Issue:** The components are converted but not fully integrated with Rails architecture.

**Improvements:**

- Create proper ViewComponent parameter initialization
- Generate preview classes for ViewComponent
- Add tests for converted components
- Support for view_component namespacing and Rails conventions
- Properly handle component slots and render blocks

## 6. Tailwind Configuration

**Issue:** Manual Tailwind configuration was required to support the component styles.

**Improvements:**

- Automatically add necessary Tailwind theme variables based on component needs
- Generate complete Tailwind configuration with proper colors and design tokens
- Add container configurations automatically
- Support shadcn themes and styling systems

## 7. Controller/Route Generation

**Issue:** The package didn't create controllers and routes as advertised.

**Improvements:**

- Implement the advertised `--generate-controllers-from-structure` option
- Properly map page components to Rails routes
- Generate controllers that match the v0/Next.js page structure
- Create proper route mappings that respect dynamic segments

## 8. Error Handling and Diagnostics

**Issue:** Errors and warnings during conversion weren't very informative.

**Improvements:**

- Provide more detailed error messages during conversion
- Add diagnostic options to help troubleshoot conversion issues
- Create detailed logs of what was converted and what needs attention
- Add a report option that summarizes all conversions and potential issues

## 9. Feature Implementation Priorities

These features from the README should be prioritized for implementation:

1. `--source-map` and `--maintain-hierarchy` - Keep original component structure
2. Controller and route generation from structure
3. Slot detection and handling
4. Enhanced ERB conversion with proper Rails syntax
5. Proper handling of component composition

## 10. Testing and Validation

**Improvements:**

- Add validation of generated components to ensure they render properly
- Create test fixtures for common v0 component patterns
- Add integration tests with Rails applications
- Provide a verification step that checks generated components against original designs

By implementing these improvements, v0-rails would become much more effective at automatically converting v0 components to Rails ViewComponents with minimal manual intervention required.