# Handoff UI → Dev (WordPress FSE) + Nomenclatura

> Cómo el sistema UI (`ui/output/`) aterriza en el theme de Dev. Auditado 2026-07-09.
> Dev = raíz del repo (tema de bloques ACF). Editar solo `ui/`; esto es la **guía de traspaso**.

## 1. El patrón de Dev (fuente única)
Cada bloque = `blocks/<name>/{block.json, render.php}`. `render.php` mapea `get_field()` (ACF) a una
**función de componente** `sek_c_*` (en `components/{atoms,molecules,organisms}/`). Storybook ejecuta
los mismos componentes. **Editas el componente una vez → editor, front y Storybook se actualizan.**

```php
// blocks/<name>/render.php
$_sek_brand = sek_block_brand_open();          // abre wrapper de marca [data-sek-brand]
sek_c_<component>([                            // llama al componente único
  'title' => (string) get_field('title'),
  'items' => /* … mapea campos ACF … */,
]);
sek_block_brand_close($_sek_brand);            // cierra wrapper
```
- **Marca**: `sek_block_brand_open()/close()` envuelve el bloque en `[data-sek-brand]` → recolorea con nuestros tokens. **Ya alineado** con `tokens.css`.
- **Enlaces**: campo ACF Link → helper `sek_link()` → `{text,url,target}`.
- `block.json`: `"category":"sek"`, `"acf":{"mode":"preview","renderTemplate":"render.php"}`, supports align/anchor.
- Scaffold de nuevos: skill **`dev-block-scaffold`** (crea component + block.json + render.php + story).

## 2. Convención — ALINEADA vs DIVERGENTE
| Capa | UI (mío) | Dev | Estado |
|------|----------|-----|--------|
| Tokens | `--sek-color-*` / `--sek-primitive-*` | idem (`generate-css-vars.js`) | ✅ **alineado** |
| Marca | `[data-sek-brand]` | `[data-sek-brand]` + `sek_block_brand_*()` | ✅ **alineado** |
| Componente PHP | `sek_c_<name>()` (propuesto) | `sek_c_<name>()` | ✅ **alineado** |
| **Estilos** | clases `.sek-*` (BEM) + `components.css` | **Tailwind** + clases `sekSchools-*` | ⚠️ **DIVERGENTE** (decisión Guille/dev) |

> **Decisión pendiente clave**: Dev estiliza con **Tailwind** (utilidades + `sekSchools-*`); mi sistema
> usa **`.sek-*` + CSS vars** (`components.css`). Dos caminos: (a) Dev adopta `components.css` como capa
> de componentes (yo entrego CSS), o (b) mis clases se traducen a componentes Tailwind. Recomiendo (a)
> para no perder el trabajo tokenizado; a validar.

## 3. Mapeo componente UI → `sek_c_*` de Dev
Dev **ya tiene** ~40 `sek_c_*`. La mayoría de mis componentes **ya existen con otro nombre** → alinear.

| UI (mío) | clase | `sek_c_*` de Dev | Bloque `acf/*` | Nota de nomenclatura |
|----------|-------|------------------|----------------|----------------------|
| Icon | `.sek-icon` | `sek_c_icon` | — | ✅ igual |
| **Link** | `.sek-link` | `sek_c_arrow_link` | — | ⚠️ Dev = "arrow-link" |
| Button | `.sek-btn` | `sek_c_button` | — | Dev lo tiene en *molecules* |
| Icon-Button | `.sek-iconbtn` | *(solo `social_icon_button`)* | — | ⚠️ falta genérico → scaffold |
| **Chip** | `.sek-chip` | *(falta)* | — | ⚠️ nuevo → scaffold |
| Item | `.sek-item` | *(≈ `ranked_post`?)* | — | revisar |
| Overlay-text | `.sek-overlay` | *(util)* | — | util CSS |
| Media Button | `.sek-mediabtn` | *(dentro de media)* | — | scaffold `media_button` |
| Logo | `.sek-logo` | *(assets header)* | — | assets |
| **Breadcrumbs** | `.sek-breadcrumbs` | `sek_c_breadcrumb` | — | ⚠️ singular |
| Button Group | `.sek-btn-group` | *(falta)* | — | scaffold |
| **Title Section** | `.sek-title-section` | `sek_c_section_heading` | — | ⚠️ Dev = "section-heading" |
| **Accordion** | `.sek-accordion` | `sek_c_faq_item` / `sek_c_faqs` | `acf/faqs` | ⚠️ Dev lo modela como FAQ |
| Media | `.sek-media` | `sek_c_media_card` | `acf/media-text` | ~ |
| Slider Controls | `.sek-slider-nav` | *(Swiper en gallery)* | — | motor Swiper |
| Anchor-bar | `.sek-anchor-bar` | *(falta)* | — | scaffold |
| Map | `.sek-map` | *(falta)* | — | scaffold |
| Card/Content | `.sek-card` | `sek_c_media_card` / `mega_card` / `media_promo` | `acf/media-text` | varias variantes en Dev |
| **Card/Feature** | `.sek-card-feature` | `sek_c_feature_card` / `sek_c_feature_cards` | `acf/feature-cards` | ✅ concepto igual |
| **Card/Highlight** | `.sek-card-highlight` | `sek_c_stat_item` / `sek_c_stats` | `acf/stats` | ⚠️ Dev = "stat/stats" |
| **Card/Agenda** | `.sek-card-agenda` | `sek_c_event_card` | *(≈ `acf/experiences`)* | ⚠️ Dev = "event-card" |
| Gallery | `.sek-gallery` | `sek_c_gallery` | `acf/gallery` | ✅ igual |

**Bloques `acf/*` de Dev (17):** blog-cards, blog-feed, blog-sidebar, certifications, director-message,
dropdown, experiences, faqs, feature-cards, footer, gallery, header, hero, media-text, post-header, stats, testimonials.

## 4. Propuesta de convención (para consensuar Guille ↔ dev)
1. **Nombres = los de Dev** (arrow-link, section-heading, stats, event-card, faqs…) — Dev es el theme; renombrar mis clases al aterrizar, o mapear en el handoff. **No inventar nombres nuevos donde Dev ya tiene uno.**
2. **Componentes que faltan en Dev** (Chip, Button Group, Anchor-bar, Map, Icon-Button genérico, Media Button): scaffold con `dev-block-scaffold` usando mi HTML/receta como spec.
3. **Estilos**: resolver Tailwind vs `.sek-*`+`components.css` (decisión (a)/(b) arriba).
4. **Tokens y marca ya alineados** — no tocar.

## 5. Gaps acumulados (tokens/fuentes/a11y)
- **Fuentes**: vendorizar Encode Sans Semi Expanded + Plus Jakarta Sans; reconciliar `font-family-action` (token=Jakarta) vs Figma (Semi Expanded).
- **Tokens**: `alpha-dark-60` (scrims), `.sek-btn--danger` (destructivo), ratios Media limpios vs exactos.
- **A11y**: `inert` en accordion cerrado; `<time datetime>` en Card/Agenda; contraste superficies accent(naranja)+inverse; deshabilitar prev/next del carrusel en extremos. Verificar con `accesslint-scan`.
- **Migrar** demos de atoms a `components.css` (limpieza).

## 6. Pendiente de criterio de Guille
- **Cotejar notas UX (wireframes)** con los componentes construidos (no ejecutado; requiere tu revisión).
- Confirmar la decisión de estilos (Tailwind vs components.css) y el set de nombres.