diff --git a/docs/TABLE_REFACTORING_PLAN.md b/docs/TABLE_REFACTORING_PLAN.md
new file mode 100644
index 0000000..2208edb
--- /dev/null
+++ b/docs/TABLE_REFACTORING_PLAN.md
@@ -0,0 +1,71 @@
+# Plan de Refactoring: table.zig
+
+**Fecha:** 2025-12-11
+**Motivo:** Archivo de 1770 líneas, difícil de manejar en sesiones de edición
+
+## Estado Actual
+
+```
+src/widgets/table.zig  (~1770 líneas)
+├── Tipos (Column, TableConfig, TableColors, SortDirection, etc.)
+├── TableState (estado completo con ~50 campos)
+├── TableResult (resultado de interacción)
+├── Funciones de renderizado (drawHeaders, drawRows, drawScrollbar)
+├── handleKeyboard (navegación, edición, búsqueda)
+├── API pública (table, tableRect, tableEx)
+└── Tests
+```
+
+## Estructura Propuesta
+
+```
+src/widgets/table/
+├── table.zig      # Re-exports + API pública (table, tableRect, tableEx)
+├── types.zig      # Column, TableConfig, TableColors, SortDirection, RowState
+├── state.zig      # TableState, TableResult
+├── keyboard.zig   # handleKeyboard, startsWithIgnoreCase
+├── render.zig     # drawHeaders, drawRows, drawCell, drawScrollbar
+└── tests.zig      # Todos los tests
+```
+
+## Estimación de Líneas por Archivo
+
+| Archivo | Contenido | Líneas Est. |
+|---------|-----------|-------------|
+| types.zig | Enums, configs, column def | ~150 |
+| state.zig | TableState, TableResult | ~400 |
+| keyboard.zig | Input handling | ~250 |
+| render.zig | Drawing functions | ~500 |
+| table.zig | API pública + re-exports | ~200 |
+| tests.zig | Unit tests | ~250 |
+
+## Orden de Extracción
+
+1. **types.zig** - Sin dependencias internas
+2. **state.zig** - Depende de types.zig
+3. **keyboard.zig** - Depende de types.zig, state.zig
+4. **render.zig** - Depende de types.zig, state.zig
+5. **table.zig** - Orquesta todo, re-exporta API pública
+6. **tests.zig** - Al final, importa todo
+
+## Dependencias Externas (se mantienen)
+
+- `../core/context.zig` - Context
+- `../core/command.zig` - Command
+- `../core/layout.zig` - Layout, Rect
+- `../core/style.zig` - Style, Color
+- `../core/input.zig` - Input
+
+## Compatibilidad
+
+La API pública NO cambia:
+```zig
+const table = @import("widgets").table;
+// Sigue funcionando igual:
+table.table(ctx, &state, &columns, getCellData);
+table.tableRect(ctx, rect, &state, &columns, getCellData, onEdit, validate, config, colors);
+```
+
+## Rollback
+
+Si hay problemas, el commit anterior tiene table.zig completo y funcional.