fn_registry/.claude/commands/extract-design.md

# /extract-design — Mejorar @fn_library con exports de Claude Design

Eres un agente mejorador del design system. Tu trabajo es analizar un export "standalone" de Claude Design (`sources/frontend_designs/*.html`), identificar componentes nuevos o mejoras sobre `@fn_library`, aplicarlos al registry y propagarlos al espejo público `subrepos/fn-design-system` (GitHub + Gitea).

**Objetivo:** cada diseño exportado debería dejar el registry un poco mejor que antes. Lo que Claude Design inventó para cubrir un hueco hoy → componente reutilizable del registry mañana.

---

## Argumento

`$ARGUMENTS` — ruta al `.html` en `sources/frontend_designs/`. Si no se proporciona:
1. Lista los `.html` bajo `sources/frontend_designs/` ordenados por fecha.
2. Muestra fecha + nombre + tamaño.
3. Pregunta cuál procesar. Default: el más reciente.

---

## PASO 0 — Validar input

```bash
ls -lht sources/frontend_designs/*.html 2>/dev/null
```

Si no existe el fichero, abortar. Si existe, leer las primeras líneas para confirmar que es un export de Claude Design (`__bundler/manifest`, `__bundler/template` en el HTML).

---

## PASO 1 — Decodificar el bundle

Ejecutar el extractor:

```bash
python3 .claude/scripts/extract_design_bundle.py \
  "sources/frontend_designs/<NOMBRE>.html" \
  "sources/frontend_designs/<NOMBRE>_extracted/"
```

Esperado: directorio con `app.jsx`, `fn_library_emu.jsx`, `charts_emu.jsx`, `data.jsx` + fuentes woff2 + `manifest.json`.

Si falta alguno de los 4 `.jsx` clave, inspeccionar por UUID; puede que Claude Design haya usado estructura distinta. Reportar al usuario.

---

## PASO 2 — Inventariar el diseño

Leer `app.jsx` y listar **todos los componentes React definidos** (funciones que empiezan con mayúscula o usan `function Xxx(`). Categorizar:

### 2a. Componentes del export que YA existen en `@fn_library`
- Grep el barrel: `cat frontend/functions/ui/index.ts | grep "^export"`.
- Para cada componente del export, ver si aparece en el barrel. Registrar coincidencias.

### 2b. Componentes nuevos (no existen en el registry)
Componentes React del `app.jsx` cuyo nombre no aparece en el barrel. Estos son **candidatos a extracción**.

### 2c. Uso de variantes / props no documentadas
Leer `fn_library_emu.jsx` del export y comparar API con tus `.tsx` reales:

```bash
# Comprobar componentes específicos si el export los usa con props nuevas
sqlite3 registry.db "SELECT id, signature, props FROM functions WHERE id = 'alert_ts_ui';"
```

Anotar discrepancias (variantes faltantes, props nuevas, tipos distintos).

### 2d. Datos/patrones reutilizables en `data.jsx`
- RNG determinista (mulberry32) → candidato a `frontend/functions/core/rng_seeded_ts_core` o `python/functions/core/`.
- Helpers tipo `statusBadge()` → documentar como receta, no como componente.

---

## PASO 3 — Consultar el registry para evitar duplicados

Para cada componente candidato del paso 2b, búsqueda FTS5 antes de proponerlo:

```bash
sqlite3 registry.db "SELECT id, kind, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'name:<CANDIDATO>* OR description:<PALABRAS_CLAVE>') ORDER BY name;"
```

Si encuentras algo similar que pueda ser mejorado en lugar de duplicado, márcalo como **mejora** a ese existente.

---

## PASO 4 — Presentar el diagnóstico al usuario

Muestra en tablas separadas:

### 🟢 Componentes nuevos candidatos

| # | Nombre propuesto | Dominio | Líneas | Reutilizable en | API |
|---|---|---|---|---|---|
| 1 | `funnel_chart_ts_ui` | ui | ~35 | CRM, analytics, funnels genéricos | `(data: Array<{stage, value}>, variant?) → JSX` |

### 🟡 Mejoras a componentes existentes

| # | Componente | Mejora | Tipo | Riesgo |
|---|---|---|---|---|
| A | `alert_ts_ui` | Añadir variantes `success`, `warning`, `info` | Expandir enum | Bajo — no rompe API |
| B | `data_table_ts_ui` | Prop `density: 'compact'|'cozy'|'roomy'` | Añadir prop opcional | Bajo |

### 🔵 Patrones a documentar (no componente)

| Patrón | Dónde registrar |
|---|---|
| `statusBadge` helper | `DESIGN_SYSTEM.md` sección "patterns" |

**Esperar confirmación.** El usuario responde con sintaxis `1,2,A,B` (o `all`, o `nuevos only`, o descarta algunos). Si dice `all`, aplica todo lo listado.

---

## PASO 5 — Aplicar mejoras aprobadas

### 5a. Para componentes nuevos (candidatos 🟢)

Por cada aprobado:

1. **Leer código** del `app.jsx` / `fn_library_emu.jsx` / `charts_emu.jsx` del export.
2. **Adaptar al stack real del registry:**
   - Cambiar elementos SVG/HTML planos por primitivas de `@mantine/core` cuando corresponda (`Paper`, `Stack`, `Group`, `Text`).
   - Cambiar `style={{...}}` por props Mantine (`p`, `m`, `fw`, `gap`, `radius`, `c`).
   - Si es un chart, delegar en `@mantine/charts` cuando sea posible; solo usar SVG puro si Mantine no cubre el caso (ej: `Sparkline` en el registry ya es SVG puro por rendimiento).
   - Iconos: `@tabler/icons-react`.
3. **Crear los dos ficheros** siguiendo la convención:
   - `frontend/functions/ui/<name>.tsx` — código React.
   - `frontend/functions/ui/<name>.md` — frontmatter completo.
4. **Frontmatter del .md** (campos clave):
   ```yaml
   id: <name>_ts_ui
   name: <name>
   kind: component
   lang: ts
   domain: ui
   purity: impure
   framework: react
   version: 1.0.0
   description: "..."
   tags: [...]
   props: {...}
   emits: null
   params: []
   output: "JSX.Element — ..."
   source_repo: "claude.ai/design"
   source_license: ""
   source_file: "sources/frontend_designs/<NOMBRE>.html"
   file_path: frontend/functions/ui/<name>.tsx
   tested: false
   ```
5. **Añadir al barrel** `frontend/functions/ui/index.ts`: `export { Xxx } from './<name>'`.

### 5b. Para mejoras a componentes existentes (🟡)

Por cada aprobada:

1. **Leer** el `.tsx` actual.
2. **Aplicar la mejora** sin romper la API existente: añade prop opcional, amplía enum de `variant`, etc.
3. **Actualizar** el `.md` correspondiente para reflejar las nuevas variantes/props (campos `variant`, `props`, `description`).
4. **Si la firma cambia**, actualizar también el `signature` del frontmatter.

### 5c. Para patrones a documentar (🔵)

1. Añadir una sección "Patterns" en `frontend/DESIGN_SYSTEM.md` si no existe.
2. Registrar el patrón con un ejemplo corto.

---

## PASO 6 — Indexar y verificar

```bash
./fn index
```

- Si falla por integridad, arreglar y reintentar.
- Verificar cada componente nuevo: `./fn show <id>`.
- Confirmar que el barrel compila haciendo `cd frontend && pnpm tsc --noEmit` (si tarda, al menos verificar imports manualmente).

---

## PASO 7 — Sincronizar al espejo

```bash
cd subrepos/fn-design-system
./sync_from_registry.sh
git add -A
git status --short   # Mostrar qué cambió en el espejo
```

Si hay cambios, preparar commit. Si no, el sync no recogió las modificaciones — investigar.

---

## PASO 8 — Commit en ambos repos

### 8a. Commit en `fn_registry`

```bash
git add frontend/functions/ui/ frontend/DESIGN_SYSTEM.md registry.db
git commit -m "$(cat <<'EOF'
feat(ui): extract <N> components / <M> improvements from design export

From: sources/frontend_designs/<NOMBRE>.html

New components:
- <id> — <descripción corta>
- ...

Improvements:
- <id> — <cambio>
- ...

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"
```

### 8b. Commit en el espejo

```bash
cd subrepos/fn-design-system
git commit -m "sync: <N> new components + <M> improvements from <NOMBRE>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
```

---

## PASO 9 — Push

### 9a. Push del espejo (ambos remotes)

```bash
cd subrepos/fn-design-system
./push_all.sh
```

Esto propaga a:
- `gitea/dataforge/fn-design-system`
- `github/gutierenmanuel/fn-design-system` ← este es el que Claude Design consume

### 9b. Push de fn_registry

**Preguntar al usuario** antes — no push sin permiso (ver CLAUDE.md del proyecto). Si dice sí:

```bash
git push origin master
```

---

## PASO 10 — Resumen final

Mostrar al usuario:

```
✓ Extracción completa.

Nuevos componentes en @fn_library:
  - <id> (frontend/functions/ui/<name>.tsx)
  - ...

Mejoras aplicadas:
  - <id>: <qué cambió>

Espejo actualizado:
  - Commit gitea:  <sha>  → <url>
  - Commit github: <sha>  → <url>

Claude Design verá estas mejoras en su próxima lectura del repo enlazado.
Siguiente acción sugerida: probar un prompt de dashboard que use <componente_nuevo>.
```

---

## Reglas críticas

- **NUNCA extraer sin aprobación explícita del usuario** — siempre paso 4 con tabla y espera.
- **NUNCA sobrescribir un componente existente** en el paso 5b — solo añadir variantes/props opcionales. Si la mejora es incompatible, proponerlo como propuesta aparte (`fn proposal add`) en vez de aplicarla.
- **SIEMPRE `source_repo: "claude.ai/design"`** en el frontmatter de componentes nuevos, y `source_file` apuntando al `.html` original.
- **SIEMPRE mantener el orden:** registry → index → verify → sync mirror → commit both → push mirror → (ask to push fn_registry).
- **El barrel `index.ts`** debe estar actualizado antes de hacer `fn index` (hay apps que lo importan).
- **NO committear** `operations.db*`, `node_modules/`, `dist/`, `.env` ni nada que `.gitignore` excluya. Usa `git add` con rutas explícitas, no `git add -A` a ciegas.
- **Si el usuario cancela a mitad**, dejar el working tree limpio o documentar qué quedó pendiente. No medio-commits.
- **Patrones que no tienen sentido como primitiva** (ej. envs, branding específico) → documentar, no componentizar.