diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..01211ef
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+AppleVLC is a VLC Media Player skin implementing Apple Human Interface Guidelines (HIG) design principles. It creates a macOS-style interface with superellipse corners, SF Symbols-inspired icons, and Apple color palette.
+
+## Build Commands
+
+```bash
+# Generate all PNG assets (buttons, sliders, background)
+python3 generate_assets_v3.py
+
+# Package skin as .vlt file (zip archive)
+zip -r AppleVLC.vlt theme.xml images/ fonts/
+
+# Install skin to VLC
+cp AppleVLC.vlt ~/.local/share/vlc/skins2/
+
+# Test skin with VLC
+vlc --intf skins2 --skins2-last ~/.local/share/vlc/skins2/AppleVLC.vlt
+```
+
+## Architecture
+
+### File Structure
+- `theme.xml` - VLC Skins2 XML definition (layout, controls, bitmaps, fonts)
+- `generate_assets_v3.py` - Python/PIL script generating all PNG assets
+- `images/` - Generated PNG files with alpha transparency
+- `fonts/` - TTF fonts (LiberationSans)
+- `AppleVLC.vlt` - Final packaged skin (zip format)
+
+### VLC Skins2 Key Concepts
+
+**Bitmap declarations require `alphacolor`:**
+```xml
+
+```
+
+**Button states:** Each button needs 3 images: `_up`, `_down`, `_over`
+
+**Checkbox states:** 6 images: `_off_up/down/over` and `_on_up/down/over`
+
+**Window dragging:** Use `action="move"` on background Image
+
+**Text variables:**
+- `$N` - Track name
+- `$T` / `$D` - Current time / Duration
+- `$B` - Audio bitrate (kb/s)
+- `$V` - Volume percentage
+
+**VLC Actions:**
+- `vlc.play()`, `vlc.pause()`, `vlc.stop()`
+- `playlist.previous()`, `playlist.next()`
+- `playlist.setRandom(true/false)`, `playlist.setLoop(true/false)`, `playlist.setRepeat(true/false)`
+
+### Design Constants (Apple HIG)
+
+```python
+APPLE = {
+ 'blue': (0, 122, 255, 255), # Primary action color
+ 'bg_primary': (242, 242, 247, 255), # Window background
+ 'win_close': (255, 95, 87, 255), # macOS red
+ 'win_min': (255, 189, 46, 255), # macOS yellow
+ 'win_max': (39, 201, 63, 255), # macOS green
+}
+```
+
+**Touch targets:** Minimum 44px for all interactive controls
+
+### Workflow
+
+1. Edit `generate_assets_v3.py` to modify icons/colors
+2. Run `python3 generate_assets_v3.py` to regenerate PNGs
+3. Edit `theme.xml` to modify layout/controls
+4. Package with `zip -r AppleVLC.vlt theme.xml images/ fonts/`
+5. Test with VLC using skins2 interface
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..3cbb4d6
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,205 @@
+# Guía de Desarrollo - AppleVLC Skin
+
+## Lecciones Aprendidas y Errores a Evitar
+
+### 1. Validación XML Estricta
+
+VLC Skins2 usa un DTD estricto. **SIEMPRE** verificar que los atributos sean válidos.
+
+#### Atributos NO válidos encontrados:
+```xml
+
+
+
+
+
+```
+
+#### Corrección:
+```xml
+
+
+
+```
+
+### 2. Acciones Válidas en VLC Skins2
+
+#### Acciones que SÍ funcionan:
+```
+vlc.play() vlc.pause() vlc.stop()
+vlc.quit() vlc.minimize() vlc.fullscreen()
+vlc.mute() vlc.volumeUp() vlc.volumeDown()
+
+playlist.next() playlist.previous()
+playlist.setRandom(true/false)
+playlist.setLoop(true/false)
+playlist.setRepeat(true/false)
+
+dialogs.popup() # Menú contextual
+windowName.show() windowName.hide()
+```
+
+#### Acciones que NO funcionan:
+```
+dialogs.equalizer() # NO EXISTE
+dialogs.extended() # NO EXISTE
+dialogs.playlist() # NO EXISTE
+vlc.setLoop() # NO EXISTE (usar playlist.setLoop)
+```
+
+### 3. Márgenes y Posicionamiento
+
+#### Problema encontrado:
+Elementos aparecían cortados o fuera del fondo.
+
+#### Solución:
+- **Siempre** dejar mínimo 20px de margen en todos los bordes
+- Calcular posiciones desde el margen, no desde 0
+- Fórmula: `elemento_x = margen + offset_deseado`
+
+```xml
+
+
+
+
+
+```
+
+### 4. Sombras en VLC Skins
+
+#### Problema:
+Las sombras difusas NO funcionan correctamente en VLC Skins2. Aparecen como bordes negros sólidos en lugar de sombras suaves.
+
+#### Solución:
+- **NO usar sombras** en los assets PNG
+- Usar bordes sutiles con alpha bajo: `rgba(0,0,0,0.08)`
+- El fondo debe ser limpio sin efectos de sombra
+
+```python
+# INCORRECTO - sombra que no funciona
+shadow = img.filter(ImageFilter.GaussianBlur(10))
+
+# CORRECTO - borde sutil
+draw.rounded_rectangle([0,0,w-1,h-1], radius=20,
+ outline=(0,0,0,20), width=1)
+```
+
+### 5. Checkbox vs Button para Estados
+
+#### Usar Checkbox cuando:
+- El control tiene dos estados persistentes (on/off)
+- Ejemplos: Shuffle, Repeat, Mute
+
+```xml
+
+```
+
+#### Usar Button cuando:
+- Es una acción momentánea
+- Ejemplos: Play, Stop, Next, Previous
+
+### 6. Variables de Texto VLC
+
+```
+$N - Nombre del track (título)
+$T - Tiempo actual (0:00:00)
+$D - Duración total
+$B - Bitrate (kb/s)
+$S - Sample rate (kHz)
+$V - Volumen (%)
+$F - Nombre del archivo
+$P - Posición (%)
+```
+
+### 7. Visibilidad Condicional
+
+```xml
+
+
+
+
+
+
+
+
+
+```
+
+### 8. Estructura de Slider
+
+```xml
+
+
+
+
+
+```
+
+- `points`: Define inicio y fin del recorrido del knob
+- `thickness`: Área clickeable vertical
+- El knob debe posicionarse ~7px arriba del track para centrado visual
+
+### 9. Generación de Assets PNG
+
+#### Requisitos:
+- Canal alpha real (RGBA)
+- `alphacolor="#FF00FF"` en theme.xml para compatibilidad
+- Tamaño exacto según uso (44x44 para botones, etc.)
+
+```python
+# Crear imagen con alpha
+img = Image.new('RGBA', (44, 44), (0, 0, 0, 0))
+
+# Guardar con alpha
+img.save('button.png', 'PNG')
+```
+
+### 10. Empaquetado del Skin
+
+```bash
+# El .vlt es simplemente un ZIP
+zip -r AppleVLC.vlt theme.xml images/ fonts/
+
+# Verificar contenido
+unzip -l AppleVLC.vlt
+```
+
+### 11. Testing y Debugging
+
+```bash
+# Ejecutar VLC con skin específica
+vlc -I skins2 --skins2-last /ruta/AppleVLC.vlt
+
+# Ver errores en terminal
+vlc -I skins2 --skins2-last /ruta/AppleVLC.vlt 2>&1 | grep -E "(error|warning)"
+
+# Forzar cierre si se cuelga
+pkill -9 vlc
+```
+
+### 12. Referencia DTD
+
+El DTD oficial está en:
+`http://www.videolan.org/vlc/skins2-0.dtd`
+
+Elementos principales válidos:
+- Theme, ThemeInfo, Bitmap, Font, Window, Layout
+- Button, Checkbox, Image, Text, Slider, Video, Playtree
+
+## Checklist Pre-Release
+
+- [ ] Verificar que theme.xml valida contra el DTD
+- [ ] Probar todos los botones y controles
+- [ ] Verificar que no hay elementos cortados
+- [ ] Probar con audio y video
+- [ ] Verificar estados hover/down en todos los botones
+- [ ] Probar shuffle, repeat, repeat one
+- [ ] Verificar slider de tiempo y volumen
+- [ ] Probar minimizar y cerrar ventana
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b74013d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# AppleVLC - VLC Media Player Skin
+
+Skin moderna para VLC Media Player inspirada en Apple Human Interface Guidelines.
+
+## Características
+
+- **Diseño limpio**: Fondo con esquinas redondeadas (superelipse/squircle) estilo Apple
+- **Controles intuitivos**: Botones de 44px siguiendo las guías de Apple para touch targets
+- **Información completa**: Título, tiempo, bitrate y sample rate visibles
+- **Controles de ventana**: Solo cerrar y minimizar (sin maximizar, al estilo macOS)
+- **Estados visuales**: Hover con tinte azul Apple (#007AFF), estados disabled
+- **Iconos secundarios**: Color gris sistema (#8E8E93) para jerarquía visual
+
+## Controles Disponibles
+
+### Fila Principal
+- Stop, Playlist, Shuffle, Previous, Play/Pause, Next, Repeat All, Repeat One, Fullscreen
+
+### Fila Inferior
+- Volume (con slider), Equalizer, A-B Loop, Speed
+
+### Ventanas Adicionales
+- Video Window (640x480, redimensionable)
+- Playlist Window (320x400)
+- Fullscreen Controller
+
+## Instalación
+
+1. Copiar `AppleVLC.vlt` a `~/.local/share/vlc/skins2/`
+2. En VLC: Herramientas → Preferencias → Interfaz → Usar skin personalizado
+3. Seleccionar AppleVLC.vlt
+4. Reiniciar VLC
+
+O ejecutar directamente:
+```bash
+vlc -I skins2 --skins2-last /ruta/a/AppleVLC.vlt
+```
+
+## Estructura del Proyecto
+
+```
+PielVLC/
+├── AppleVLC.vlt # Skin empaquetada (ZIP)
+├── theme.xml # Definición de la interfaz
+├── generate_assets_v3.py # Script para generar PNGs
+├── images/ # Assets PNG generados
+├── fonts/ # Fuentes Liberation Sans
+└── DEVELOPMENT.md # Guía de desarrollo
+```
+
+## Especificaciones Técnicas
+
+- **Dimensiones**: 500x225 px (ventana principal)
+- **Márgenes**: 20-30px en todos los bordes
+- **Track slider**: 8px de altura, 440px de ancho
+- **Volume slider**: 6px de altura, 80px de ancho
+- **Colores**:
+ - Fondo: #F5F5F7 (Apple Light Gray)
+ - Texto primario: #000000
+ - Texto secundario: #3C3C43
+ - Iconos secundarios: #8E8E93
+ - Acento: #007AFF (Apple Blue)
+ - Borde sutil: rgba(0,0,0,0.08)
+
+## Regenerar Assets
+
+```bash
+python3 generate_assets_v3.py
+zip -r AppleVLC.vlt theme.xml images/ fonts/
+```
+
+## Requisitos
+
+- VLC 3.0+ con soporte skins2
+- Python 3 + Pillow (solo para regenerar assets)
+
+## Autor
+
+Claude Code - Anthropic
+
+## Licencia
+
+MIT License