Lineamientos y buenas prácticas de maquetación

El principio fundamental: Div no reemplaza la semántica

"La etiqueta <div> es un contenedor genérico sin significado semántico. Nunca debe utilizarse para reemplazar elementos nativos de HTML5 que ya poseen roles, estados y comportamientos estandarizados."

El uso indiscriminado de divs ("Div-Soup") destruye la accesibilidad del portal, desorienta a los usuarios de lectores de pantalla e impide que los motores de búsqueda identifiquen la relevancia de los distintos bloques de contenido.

Elementos semánticos estructurales (Landmarks)

• <header>: Cabecera de la página o de una sección temática, habitualmente con el logotipo, buscador o títulos destacados.
• <nav>: Bloque destinado a la navegación. Si hay múltiples elementos <nav> en la página (menú principal, migas de pan, paginador), deben diferenciarse con aria-label .
• <main>: Contenedor exclusivo del contenido principal. Solo debe existir uno por página, con id="main" y tabindex="-1" para el salto de navegación.
• <section>: Agrupación temática de contenido funcional. Se recomienda iniciar siempre cada sección con un encabezado descriptivo (h2-h6).
• <article>: Composición independiente que tiene sentido pleno por sí misma (noticias, tarjetas de producto, comunicados).
• <aside>: Contenido complementario o secundario relacionado tangencialmente con el contenido principal.
• <footer>: Pie de página con información legal, enlaces a políticas, mapa del sitio y contactos corporativos.

Nomenclatura corporativa para clases e identificadores

Para el desarrollo de componentes y páginas se debe aplicar la convención kebab-case descriptiva:

• Clases (CSS): Usar minúsculas separadas por guiones medios: hero-banner , card-producto , form-contacto , btn-primario .
• Identificadores (IDs): Únicos en todo el documento HTML, también en kebab-case: id="campo-email" , id="menu-usuario" .
• Prohibiciones: Prohibido usar PascalCase ( SeccionBanner ), camelCase ( cardProducto ), guiones bajos ( card_producto ) o caracteres con acento.

Titles (Título de página) y patrón corporativo

La etiqueta <title> es el elemento de metadatos más influyente para motores de búsqueda y lectores de pantalla:

• Cada página debe poseer un <title> único y distintivo dentro de todo el portal.
• Evitar títulos genéricos ("Inicio", "Página", "Documento").
• Patrón corporativo YPF: [Nombre de página] | YPF .
• Ejemplos oficiales:  

• • Lineamientos de Maquetación | YPF
  • Accesibilidad Web | YPF
  • Sistema de Diseño | YPF

Meta Description

• Debe existir una única etiqueta <meta name="description"> por página.
• Redactada en lenguaje claro y comprensible, orientada a personas reales y no a listados de palabras clave.
• Extensión recomendada: Entre 140 y 160 caracteres para evitar truncamientos en pantallas móviles y de escritorio.

Jerarquía lógica de encabezados (Headings)

• Un único <h1>: Debe sintetizar el tema o propósito central de la página.
• Secuencia sin saltos: Estructurar el contenido en niveles ordenados (h1 → h2 → h3). Jamás saltar de un h2 a un h4.
• No usar encabezados con fines estéticos: Los tamaños tipográficos se asignan con clases CSS, nunca forzando etiquetas de encabezado.

URLs y enlaces descriptivos

• URLs amigables y legibles: Priorizar rutas semánticas como /lineamientos/maquetacion o /estaciones-servicio frente a URLs con parámetros opacos como /pagina.aspx?id=1028 .
• Eliminación de textos ambiguos: Prohibido usar textos genéricos como "Click aquí" o "Leer más". Los enlaces deben describir con claridad el destino o la acción: 

• • Incorrecto: <a href="norma.pdf">Click aquí</a>
  • Correcto: <a href="norma.pdf">Descargar Especificación Técnica YPF (PDF, 1.8 MB)</a>
• Documentos descargables: Indicar siempre el formato del documento (PDF, ZIP, DOCX) y su tamaño aproximado en megabytes (MB) para informar a usuarios con planes móviles reducidos.

Datos estructurados (Introducción a Schema.org)

Los sitios públicos de YPF pueden incorporar fragmentos de datos estructurados en formato JSON-LD para brindar información explícita a buscadores:

• Organization: Describe la entidad corporativa de YPF, logotipos oficiales, redes sociales y canales de atención.
• BreadcrumbList: Refleja la jerarquía de navegación de la página en los resultados de búsqueda.
• Article / NewsArticle: Especifica titulares, fecha de publicación y autoría en noticias institucionales.
• FAQPage: Habilita preguntas y respuestas desplegables directamente en la página de resultados de Google.

Estrategia Mobile First y Breakpoints corporativos

El maquetado debe desarrollarse bajo la filosofía Mobile First : los estilos base se escriben para pantallas móviles compactas y se enriquecen progresivamente hacia pantallas mayores mediante media queries con min-width .

Los puntos de quiebre (breakpoints) estándar del ecosistema YPF son:

• Mobile (0px - 767px): Layout lineal a una columna, menús colapsables (hamburguesa) y zonas de toque generosas.
• Tablet (768px - 991px): Reorganización en columnas dobles, cabeceras compactas.
• Desktop (992px - 1199px): Menús horizontales completos, grillas multicolumna y barras laterales secundarias.
• Desktop amplio (1200px o superior): Ancho máximo de lectura restringido mediante el contenedor .yl-container para preservar la legibilidad.

Layouts fluidos: Flexbox y CSS Grid

El posicionamiento moderno en YPF se apoya en Flexbox (ideal para componentes unidimensionales como barras de navegación, botones con iconos y tarjetas) y CSS Grid (ideal para matrices bidimensionales complejas de grillas de noticias o galerías). Queda terminantemente prohibido el uso de tablas para maquetación o floats para estructura de columnas.

Imágenes responsive: <picture>, srcset y sizes

Para evitar que un dispositivo móvil descargue imágenes de alta resolución pensadas para monitores 4K, se debe implementar la etiqueta <picture> combinada con srcset y sizes :

• Permite a los navegadores seleccionar de forma automática la versión con la resolución más eficiente.
• Permite realizar recortes artísticos (art direction) ajustando la composición visual para pantallas verticales angostas.
• Evita el desperdicio de ancho de banda y mejora sustancialmente el puntaje Core Web Vitals.

Formatos gráficos modernos: WebP, SVG y AVIF

• AVIF: Formato de última generación con la tasa de compresión más alta de la industria. Recomendado para fotografías pesadas y banners hero con fallback a WebP.
• WebP: Estándar de facto moderno para fotografías e imágenes de producto. Ofrece reducciones de peso de entre 30% y 50% frente a JPEG y PNG con idéntica calidad visual.
• SVG: Formato vectorial obligatorio para logotipos, iconos, diagramas e ilustraciones planas. Es liviano, nítido en cualquier densidad de píxeles (Retina/HiDPI) y permite estilarse mediante CSS.
• Animaciones: Desalentar el uso de GIF pesados; priorizar formatos modernos como WebM, video MP4 sin audio o animaciones Lottie vectoriales.

Métricas Core Web Vitals

Google y los estándares de la industria evalúan la experiencia de navegación a través de tres métricas fundamentales que deben monitorearse en todo desarrollo YPF:

• LCP (Largest Contentful Paint): Mide el tiempo de renderizado del bloque visual más grande visible en pantalla (generalmente el banner hero o el titular principal). Debe ser inferior a 2.5 segundos .
• CLS (Cumulative Layout Shift): Mide la estabilidad visual y previene saltos inesperados de contenido mientras la página se carga. Debe mantenerse en un valor menor a 0.1 .
  Solución de maquetado: Declarar siempre los atributos width y height (o la propiedad CSS aspect-ratio ) en todas las imágenes y contenedores para reservar su espacio antes de que finalice la descarga.
• INP (Interaction to Next Paint): Mide la latencia de respuesta tras la interacción del usuario (clics, toques o pulsaciones de teclado). Debe ser menor a 200 milisegundos .

Carga diferida (Lazy Loading) y decodificación asíncrona

• Aplicar loading="lazy" en todas las imágenes y recursos multimedia que se encuentren debajo del primer scroll (below the fold).
• Incorporar el atributo decoding="async" para que la decodificación de imágenes pesadas no bloquee el hilo principal de renderizado del navegador.
• Excepción importante: NUNCA aplicar loading="lazy" a la imagen del banner principal o hero que se visualiza al cargar la página, ya que perjudicaría directamente el puntaje de LCP.

Minimización y Presupuesto de Rendimiento (Performance Budget)

• Minimización de código: Todas las hojas CSS y scripts JS en ambientes de producción deben servirse minificados (sin comentarios, saltos de línea ni espacios innecesarios).
• Presupuesto de rendimiento: Ninguna página de maquetación estática debería superar los 1.5 MB a 2.0 MB de peso total acumulado en su carga inicial, asegurando fluidez incluso en dispositivos conectados a redes móviles 3G/4G en áreas operativas remotas.
• Librerías de terceros: Deben alojarse localmente dentro de los directorios del proyecto y estar estrictamente homologadas. Queda prohibida la carga de scripts o estilos desde CDNs externos no autorizados por seguridad y para prevenir puntos únicos de fallo (SPOF).

Variables CSS (Custom Properties) y Tokens de Diseño

Para facilitar el mantenimiento y la consistencia de marca, se deben utilizar variables declaradas en el bloque :root para los valores recurrentes de color, tipografía, espaciado y sombras.

El Design System de YPF ya provee variables globales (ej. --font-din-regular , --Grey-Scale-900 ) que deben consumirse directamente en lugar de ingresar valores hexadecimales o tipografías cableadas en duro.

Convenciones de formato y estandarización en CSS

• Indentación y estructura: Utilizar 2 espacios o tabulaciones coherentes. Escribir cada declaración de propiedad en su propia línea.
• Espaciados: Dejar un espacio antes de abrir la llave { y un espacio tras los dos puntos en cada propiedad ( propiedad: valor; ).
• Punto y coma: Finalizar toda línea de propiedad con punto y coma ; .
• Selectores múltiples: Cuando varios selectores compartan estilos, colocarlos en líneas separadas para agilizar la lectura y el control de versiones.
• Comillas: Emplear comillas dobles tanto en HTML como en CSS (ej. url("imagen.svg") ).

Comentarios y modularización corporativa

Cuando una hoja de estilo administre múltiples componentes o vistas, se debe individualizar cada bloque temático mediante el encabezado corporativo estándar:

Los comentarios explicativos específicos deben ubicarse siempre en la línea inmediatamente superior a la regla que aclaran, nunca al final de la línea.

El Design System corporativo: Reutilización antes que recreación

"Queda estrictamente desaconsejado recrear o reprogramar desde cero componentes que ya se encuentran resueltos en el ecosistema YLITE y el Design System corporativo (yl-components)."

Priorizar la reutilización garantiza que cualquier actualización de accesibilidad, seguridad o imagen de marca impacte inmediatamente en todos los sitios de YPF sin requerir refactorizaciones costosas.

Requisitos esenciales de accesibilidad para maquetadores

La accesibilidad web no es una capa decorativa posterior, sino un requisito estructural de la maquetación. En cada desarrollo se deben asegurar los siguientes puntos mínimos:

• Textos alternativos en imágenes (alt): Descriptivos en imágenes con aporte informativo; vacíos alt="" en imágenes puramente decorativas. Nunca dejar una imagen sin atributo alt .
• Navegación 100% por teclado: Todos los elementos interactivos (botones, enlaces, modales) deben ser operables con Tab, Enter, Espacio y Escape sin trampas de teclado.
• Foco visible destacado: Prohibido declarar outline: none sin brindar un sustituto visual mediante :focus-visible que cuente con al menos 3:1 de contraste.
• Contraste cromático: Mínimo 4.5:1 para texto normal y 3.0:1 para textos grandes e indicadores de interfaz gráfica no textuales (bordes de campos, iconos, botones).
• Formularios rotulados: Todo campo debe tener un <label for="..."> explícito y mensajes de error asociados con aria-describedby y aria-invalid="true" .
• Enlaces contextuales: Textos claros que informen acción y destino, evitando términos vagos.

Para profundizar en los 54 criterios de conformidad de WCAG 2.2, patrones WAI-ARIA avanzados y metodología de testing con lectores de pantalla, consultá el documento oficial:

Ver guía completa de accesibilidad web (WCAG 2.1 / 2.2)

Header corporativo: ypf-header

El componente web ypf-header es el encabezado oficial y unificado de navegación para todas las plataformas digitales de YPF:

• Obligatoriedad: Su inclusión es obligatoria en todos los sitios públicos, aplicaciones de clientes e intranets para garantizar identidad de marca consistente.
• Beneficios: Mantenimiento centralizado del árbol de navegación, adaptabilidad responsive integrada, accesibilidad certificada de fábrica y persistencia de sesión corporativa.
• Modo de uso: Se incluye el archivo JavaScript del web component y se declara la etiqueta personalizada en el HTML:

Integración GraphQL para ypf-header

El componente consulta la estructura dinámica del menú mediante una solicitud a la API GraphQL corporativa utilizando la función fetch nativa:

La estructura JSON del menú responde a un esquema jerárquico basado en colecciones de elementos:

• Array principal items donde cada objeto representa una sección del encabezado con su title y colección data .
• Elementos de grupo con atributos text , type ("seccion", "grupo" o "link"), propiedades de enlace en props (url, target, cssClass) y posibles submenús en children .

Footer corporativo: ypf-footer

El componente web ypf-footer representa el pie de página institucional estandarizado para todo el ecosistema web de YPF:

• Mantenimiento centralizado: Actualización automática de leyendas legales, derechos de autor, normativas de privacidad y enlaces a redes sociales oficiales sin requerir despliegues en cada sitio individual.
• Modo de uso: Se importa el script oficial en el documento y se invoca la etiqueta <ypf-footer> antes del cierre de <body> :

Integración GraphQL para ypf-footer

De forma homóloga al encabezado, el pie de página recupera sus datos institucionales a través de una consulta GraphQL que retorna la estructura estructurada en JSON:

Matriz de compatibilidad en navegadores modernos

Todo desarrollo maquetado debe ser verificado en los navegadores web de mayor adopción actual, eliminando dependencias de plataformas obsoletas:

• Escritorio (Desktop):  

• • Google Chrome (últimas dos versiones estables).
  • Microsoft Edge (versión Chromium actualizada).
  • Mozilla Firefox (versión estable y ESR).
  • Apple Safari (versiones 16 o superior en macOS).

• Dispositivos Móviles (Smartphones y Tablets):  

• • Android: Google Chrome y Samsung Internet.
  • iOS: Safari Mobile en iPhone y iPad.

Herramientas de evaluación y auditoría automatizada

• Google Lighthouse: Medición en Chrome DevTools de métricas Core Web Vitals, SEO técnico, mejores prácticas y accesibilidad (meta de puntaje ≥ 90 en todos los ejes).
• W3C Markup Validation Service: Validación técnica del código HTML5 mediante validator.w3.org para certificar la ausencia de errores de marcado.
• Axe DevTools y WAVE: Auditorías integradas de accesibilidad web para detectar problemas de contraste cromático, roles ARIA y etiquetado de formularios.

Checklist de QA Manual imprescindible

Las auditorías automáticas deben complementarse obligatoriamente con las siguientes comprobaciones manuales antes del pase a producción:

• 1. Navegación por teclado: Recorrer la totalidad de la página utilizando solo Tab , Shift + Tab , Enter y Escape , verificando el foco visible en todo momento.
• 2. Adaptabilidad responsive en dispositivos físicos: Validar el comportamiento de menús, espaciados y tamaños de toque en teléfonos móviles reales con diferentes densidades de pantalla.
• 3. Prueba de zoom y reflow: Ampliar la interfaz al 200% y al 400% verificando que ningún texto se desborde ni aparezca scroll horizontal no deseado.
• 4. Verificación de SEO técnico: Corroborar la presencia y fidelidad del <title> corporativo, la meta descripción, la jerarquía de títulos y los enlaces descriptivos.
• 5. Rendimiento en red móvil: Simular conexiones 4G/3G en las herramientas de desarrollo para asegurar una experiencia fluida bajo condiciones de conectividad moderada.