Compatibilidad con HTML y CSS de UIDoc

Las funciones de HTML, CSS, diseño adaptable, interacción, desplazamiento y enlaces compatibles con UIDoc, además de las funciones importantes del navegador que omite.

---

UIDoc implementa intencionalmente un subconjunto práctico similar al de un navegador para la interfaz del juego. Compila los recursos por adelantado y los renderiza a través del motor; no ejecuta un navegador, JavaScript ni un DOM en vivo.

Para una primera pantalla funcional, empieza con Inicio rápido de UIDoc.

La referencia del repositorio generado, docs/uidoc_supported_css.md, es la lista exhaustiva de propiedades/valores. La emite UIDoc::debug_supported_css_reference() y la verifican las pruebas de UIDoc. Esta página explica ese contrato a nivel de autoría.

Las declaraciones desconocidas, los valores rechazados, los selectores no compatibles, el HTML mal formado y las consultas de medios no compatibles son errores de compilación. El analizador puede seguir recopilando diagnósticos, pero el recurso no es válido hasta que se corrijan los errores. Las at-rules de bloque CSS no compatibles se omiten silenciosamente; no dependas del comportamiento de at-rules del navegador.

El HTML y CSS de UIDoc no se recargan en caliente en un juego en ejecución. Reinicia el juego después de cambiar los recursos. Para depuración en tiempo de ejecución, uidoc_runtime_inspect expone nodos DOM en vivo, enlaces actuales, estilos calculados, manejadores de eventos/cargas útiles de teclas y rectángulos. Su screen_rect, client_ui_tree, y client_click usan coordenadas del viewport del motor con origen en la esquina inferior izquierda; los píxeles de la captura usan origen en la esquina superior izquierda.

La compilación herramienta incluye diagnósticos estructurados de UIDoc en línea cuando falla el preprocesamiento del recurso. uidoc_diagnostics con viewportMatrix: true devuelve recuentos agregados de aprobaciones y agrupa la misma categoría de incidencia para el mismo nodo de origen en todos los perfiles. unique_issue_count es ese recuento agrupado de nodo/categoría; issue_occurrence_count es el total bruto en todas las entradas de viewport/escala. Establece viewportMatrixVerbose: true solo cuando cada entrada que falla sea útil. Los nodos de origen distintos no se fusionan aunque compartan un selector o la misma línea de origen CSS, así que un problema de una regla compartida puede seguir apareciendo como varios grupos; corrige la regla una vez y vuelve a ejecutar los diagnósticos.

Dos advertencias comunes de autoría necesitan contexto:

• dynamic_text_intrinsic_layout significa que un texto que cambia con frecuencia puede alterar una caja de tamaño intrínseco e invalidar el diseño en caché. Añade data-text-reserve con la muestra esperada más ancha, teniendo en cuenta la localización, o asigna al elemento un ancho y alto definidos. No es un error de texto duplicado ni de renderizado.
• image_aspect_drift significa que una imagen tiene ancho y alto independientes con object-fit: fill. Usa contain, cover, o aspect-ratio para elementos gráficos normales. Un relleno de progreso diseñado específicamente y estirado deliberadamente dentro de su pista es una excepción válida; verifica ese caso visualmente.

Atributos HTML y de UIDoc

Los nombres de elementos se aceptan como nodos de diseño genéricos. Estos elementos tienen un comportamiento especializado en tiempo de ejecución:

Elemento	Comportamiento
span	Contenido de texto en línea
img	Imagen de recurso del motor cargada desde src
button	Interacción de puntero y eventos de clic
input	Texto editable enlazado con data-bind-value

El contenido de texto no vacío crea nodos de texto. Usa {{name}} para un enlace de texto de nivel superior y {{item.name}} dentro de una lista repetida. Los src valores de imagen también admiten esta interpolación. Los nombres de clase y data-key los valores son estáticos.

Atributo	Propósito
id, class, style	Coincidencia CSS y estilo en línea
src, width, height	Origen y dimensiones de la imagen
value, placeholder, disabled	Estado de entrada y control
data-if="binding"	Incluye un subárbol mientras un enlace booleano de nivel superior sea verdadero; opcional ! lo invierte
data-for="item in items"	Repite un subárbol para una lista enlazada a CSL
data-for-key="item.id"	Resuelve la event.key del clic repetido desde una expresión directa
data-key="role"	Asigna a un nodo un rol estático de interacción/entrada
data-bind-value="name"	Conecta una entrada a un valor de texto de UIDoc
data-text-reserve="00:00"	Mide una muestra literal estable mientras se pinta el texto enlazado en vivo
data-on-click="event:name"	Envía un evento de clic al callback de CSL; event.handler recibe el valor completo exacto, incluyendo event:
data-style-transform-x/y	Enlaza una traslación numérica sin relayout
data-style-transform-scale	Enlaza una escala visual numérica
data-style-opacity	Enlaza una opacidad numérica
data-style-color	Enlaza una cadena de color CSS compatible sin cambiar la estructura
data-style-image-fill-amount	Enlaza una cantidad de relleno de imagen
data-scroll-zoom	Enlaza el zoom completo del contenido en un viewport con desplazamiento

Los atributos de expresión de enlace contienen expresiones directas, por ejemplo data-for-key="item.id", data-style-opacity="item.opacity", y data-scroll-zoom="zoom". No pongas esas expresiones dentro de {{...}}. La interpolación Mustache se limita a los valores de texto e imagen src .

data-if es más restrictivo que los otros atributos de enlace sensibles a listas: busca un booleano de nivel superior y no resuelve un alias repetido como item.visible. Para un estado visual no interactivo en un subárbol repetido, enlaza item.opacity o item.color. La opacidad no desactiva la detección de pulsaciones, así que filtra filas estructurales o interactivas al construir la lista de CSL en lugar de dejar un botón invisible en su lugar.

Identidad y pruebas de controles repetidos

data-for-key determina la event.key. La identidad del control en tiempo de ejecución es independiente: comienza con el data-key (luego HTML id, luego un reemplazo de etiqueta anónima) y añade #key:index para cada bucle contenedor. Aquí key es el valor proporcionado a UI.uidoc_list_item(...); normalmente debería ser el mismo ID estable resuelto por data-for-key. Por lo tanto, un botón repetido puede aparecer en client_ui_tree como:

UI/board.uidoc:seed-cell#seed-42:7/__widget

Usa client_ui_tree para copiar la identidad exacta en vivo. Test.click_button acepta el nombre completo o un sufijo y trata el final /__widget como opcional, así que Test.click_button("seed-cell#seed-42:7") selecciona esa instancia cuando el sufijo es único. Una consulta solo por rol puede elegir una instancia repetida arbitraria y más cercana. Las listas anidadas añaden varios #key:index pares. Las cadenas de manejador y las etiquetas visibles no son selectores de identidad.

Sin procesar style y script bloques en el HTML son errores de compilación. Coloca el CSS escrito por el autor en index.css; no hay ningún runtime de JavaScript.

Selectores CSS y cascada

Los selectores compatibles incluyen:

• Nombres de elementos, .class, #id, y *.
• Combinadores de descendiente e hijo directo (>)
• Listas de selectores separadas por comas.
• :hover, :focus, :active, :pressed, :mouse-down, :dragging, :scroll-state, y :disabled.

UIDoc usa la especificidad normal de id/class/tipo y el orden de origen como criterio de desempate. El estilo en línea style se aplica al final. El orden de pintura usa z-index, y luego el orden del documento.

Las declaraciones que afectan al diseño dentro de reglas de pseudoestado de interacción se ignoran y se diagnostican. Pasar el cursor sobre un botón puede cambiar con seguridad su color u opacidad, pero no debería cambiar su tamaño ni el diseño circundante.

Las formas de selectores no compatibles incluyen combinadores de hermanos, selectores de atributos, pseudo-elementos, :not(), :nth-*, :is(), :where(), y :has().

Diseño CSS

UIDoc admite display: block, display: flex, y display: none. Otros valores de display se diagnostican y se degradan a block. Sus propiedades de diseño son:

• width, height, min-*, max-*, aspect-ratio, y box-sizing.
• margin, padding, gap, row-gap, y column-gap.
• flex, flex-direction, flex-wrap, flex-grow, flex-shrink, y flex-basis.
• align-items, align-self, align-content, y justify-content.
• position: static, relative, absolute, o fixed, con inset, top, right, bottom, y left.
• overflow, overflow-x, y overflow-y usando visible, hidden, auto, o scroll.

Las longitudes admiten las combinaciones relevantes de píxeles sin unidad, px, rem, em, %, vw, vh, safe-area env(...), y operaciones aditivas o sustractivas con calc(...) con hasta ocho términos. El padding y el margin porcentuales se diagnostican y se ignoran. Las unidades porcentuales y de viewport también son inválidas para los gaps, pero sí se admiten en tamaños, flex basis y los top/right/bottom/left offsets individuales.

padding, margin, y inset aceptan las formas estándar de uno, dos, tres y cuatro valores. Los valores porcentuales no son compatibles en la inset abreviatura; usa las propiedades de offset individuales cuando se necesiten porcentajes.

Las palabras clave y las operaciones matemáticas de CSS se comprueban por propiedad, no se aceptan globalmente solo porque un navegador las admitiría en algún sitio. En particular:

• auto es válido solo para las filas de propiedades que lo enumeran, como tamaños, flex basis, offsets, align-self, y overflow.
• none es válido solo donde se enumera, como display, reinicios compatibles de paint/filter, pointer-events, y image-fill-direction.
• calc(...) está disponible solo en los campos de longitud documentados. Permite la suma y la resta de como máximo ocho términos simples de longitud. La multiplicación, la división, las matemáticas anidadas, min(), max(), y clamp() no son compatibles, y los términos porcentuales requieren un bloque contenedor definido.

Si tienes dudas, consulta la fila exacta de la propiedad en docs/uidoc_supported_css.md; los valores aceptados por otra propiedad no son prueba de que el mismo token funcione aquí.

Texto, imágenes y pintura

Las características de presentación compatibles incluyen:

• color, background, background-color, y un background-image degradado lineal, radial o cónico.
• border, border-width, border-color, y un único border-radius valor uniforme de border-radius. Los bordes por lado como border-bottom, los radios por esquina y los radios porcentuales no son compatibles. Usa un divisor hijo explícito con altura/ancho fijos y color de fondo cuando solo se necesite un borde.
• Hasta ocho box-shadow o text-shadow capas separadas por comas; las sombras de caja pueden ser inset.
• Un filter: blur(...) o filter: drop-shadow(X Y [blur] [color]), además de backdrop-filter: blur(...).
• opacity, z-index, y pointer-events.
• font-family, font-size, font-style, font-weight, line-height, letter-spacing, text-align, white-space, overflow-wrap, y word-break.
• Texto outline-color y outline-width.
• object-fit: cover, contain, o fill para imágenes.
• image-tint, image-grayscale, image-fill-amount, y image-fill-direction.
• translate, escala, y el translate(...), translateX(...), translateY(...), y scale(...) subconjunto de transformación. Los porcentajes de translate se resuelven con respecto al propio border box del elemento; las unidades de translate de viewport siguen sin estar soportadas.

Los colores admiten formas CSS comunes, incluido hex, rgb()/rgba(), hsl()/hsla(), colores con nombre, transparent, y currentColor cuando corresponda.

Los degradados admiten hasta ocho paradas de color, direcciones/ángulos y posiciones CSS, currentColor, y en oklab o en srgb; Oklab es el valor predeterminado. No se admiten capas de fondo múltiples ni URL de imágenes CSS. Usa un img con una ruta de recurso del motor para fondos de mapa de bits.

box-shadow sigue el border box rectangular del elemento. filter: drop-shadow(X Y [blur] [color]) sigue el alfa pintado del elemento filtrado, incluidas las esquinas transparentes de la imagen. El color omitido usa por defecto el currentColor. Colócalo en el img real para un mapa de bits irregular o con nueve cortes; colocarlo en un contenedor también incluye a los descendientes pintados del contenedor en la silueta de la sombra.

Rellenos de imagen de progreso

Para una barra de progreso continua, coloca un img de tamaño completo dentro de una pista de tamaño fijo, vincula un 0..1 valor normalizado con data-style-image-fill-amount, y establece image-fill-direction: right más object-fit: fill. Usa una textura rectangular o con degradado sin huecos transparentes no deseados a través del interior de la barra.

No reutilices un icono u otra imagen decorativa transparente para el relleno. image-tint es multiplicativo y conserva el alfa de origen; no vuelve opacos los píxeles transparentes. object-fit: cover también recorta con fuerza el arte cuadrado cuando la pista es estrecha. Juntas, esas elecciones pueden producir espacio vacío al inicio o cuñas diagonales incluso cuando el recorte de relleno de UIDoc funciona correctamente.

Actualmente, los diagnósticos no inspeccionan el alfa de la textura ni marcan object-fit: cover en los rellenos de progreso. Verifica visualmente las barras de progreso en 0, 0.25, 0.5, y 1. El kit de UI de juego, con sus pares fill_*.png recursos están diseñados específicamente para sus fondos correspondientes, y .kit-progress-fill aplica el ajuste previsto.

UIDoc usa de forma predeterminada la familia AllIn incorporada, con caras reales 400, 700 y 900. @font-face puede declarar recursos de fuente TTF u OTF del proyecto por ID de recurso. El estilo y el peso seleccionan la cara declarada más cercana; la negrita o la inclinación faltantes pueden sintetizarse. Las fuentes se cargan de forma asíncrona, por lo que UIDoc usa la siguiente familia o AllIn hasta que una cara solicitada esté lista y luego invalida el diseño del texto.

Omitir line-height para la altura de línea predeterminada que escala con el tamaño de la fuente. line-height: normal no se acepta. Los valores sin unidad son multiplicadores; los valores de longitud son longitudes fijas heredadas.

letter-spacing se hereda y acepta normal, píxeles sin unidad, px, rem, o em. normal se resuelve a cero.

El subconjunto de transformación no incluye rotación, sesgo, transformaciones 3D ni escala valores de varios tokens. Un valor de filtro contiene un blur(...) o un drop-shadow(...); las cadenas de filtros y otras funciones de filtro no están soportadas. Los ámbitos del compositor de filter y backdrop-filter pueden anidarse hasta cuatro niveles.

Estilos responsivos y áreas seguras

Se admiten consultas de medios, pero solo para esta lista explícita de condiciones permitidas:

• (min-width: N) y (max-width: N).
• Consultas combinadas de ancho mínimo y máximo.
• Estilo Tailwind (width >= N) y (width <= N).
• (hover: hover).

Los valores de ancho aceptan píxeles sin unidad, px, y rem. Los bloques de medios no soportados se descartan con un diagnóstico.

Usa estos valores donde se acepten longitudes de área segura:

env(safe-area-inset-top)
env(safe-area-inset-right)
env(safe-area-inset-bottom)
env(safe-area-inset-left)

El inset superior de área segura de UIDoc también reserva la banda superior de la barra del juego.

Desplazamiento y zoom

overflow-x y overflow-y son independientes, por lo que una vista puede desplazarse horizontalmente, verticalmente o en ambos ejes. Una vista de dos ejes desplaza ambos ejes al arrastrar. La rueda del ratón se desplaza verticalmente cuando el desplazamiento vertical está habilitado; una vista solo horizontal asigna la rueda al desplazamiento horizontal.

En el runtime actualmente se dibuja el pulgar de una barra de desplazamiento vertical. El contenido horizontal sigue siendo accesible al arrastrar aunque no se dibuje un pulgar horizontal.

data-scroll-zoom="zoomBinding" añade zoom de contenido al estilo del navegador a una vista de desplazamiento interactiva. Escala la geometría, el texto, las imágenes, las transformaciones, la detección de clics y los límites de desplazamiento de los descendientes mientras la vista y sus elementos hermanos permanecen fijos. Cuando cambia la vinculación, el motor conserva el área visualizada alrededor del centro de la vista y vuelve a restringir la posición de desplazamiento. El rango de seguridad del motor es 0.05 hasta 20; las aplicaciones normalmente deberían usar límites más estrechos.

Clases al estilo Tailwind

Los recursos de UIDoc pueden usar clases de utilidad compatibles al estilo Tailwind. Las utilidades se resuelven y se traducen a CSS de UIDoc durante el procesamiento del recurso; Tailwind no se ejecuta en el juego. Las áreas cubiertas incluyen display, position, flex, sizing, spacing, inset, alignment, text, color, border, radius, overflow, pointer events, opacity, z-index, aspect ratio, shadows, transforms y propiedades arbitrarias de efectos de imagen.

El paso de traducción admite hover:, focus:, active:, disabled:, responsivo sm:/md:/lg:/xl:/2xl:, valores entre corchetes como w-[320px], y CSS @apply. No se incluye el reset preflight/base de Tailwind. La salida que UIDoc no pueda representar falla durante la compilación del recurso.

Características notables del navegador no soportadas

Característica del navegador	Enfoque de UIDoc
JavaScript y APIs DOM	Controla el estado con enlaces CSL, data-if, data-for, y callbacks de eventos.
CSS Grid	Usa flexbox, diseño de bloque o posicionamiento explícito.
Variables CSS y propiedades personalizadas	Vincula valores desde CSL o usa clases compartidas ordinarias.
Transiciones, keyframes y animaciones CSS	Anima enlaces CSL como opacidad, traducción, escala o zoom de desplazamiento.
Pseudoelementos y selectores avanzados	Añade elementos y clases explícitos al documento.
Consultas de contenedor y la mayoría de las características de medios	Usa las consultas compatibles de ancho de viewport y hover.
Fondos con URL CSS y capas de fondo múltiples	Usa un degradado compatible o un img recurso del motor.
Radios por esquina y más de ocho sombras	Usa los límites compatibles de radio único/ocho sombras o elementos anidados explícitos.
min(), max(), y clamp() Funciones matemáticas CSS	Combina width/height con las min-* y max-* propiedades compatibles.
Rotación, sesgo, transformaciones 3D, cadenas de filtros y otras funciones de filtro	Prepara lo visual como un recurso o usa los efectos compatibles de translate/scale/blur/drop-shadow.
Formularios web, navegación, fetch, iframes, canvas, SVG DOM, audio y video	Usa CSL y los sistemas del motor correspondientes.
Comportamiento semántico y de accesibilidad del navegador	Los elementos de UIDoc son nodos de UI del juego; los nombres de etiquetas HTML no implican comportamiento de navegador.

UIDoc busca facilitar la creación de UI comunes de juegos, no reproducir todas las características de HTML y CSS. Mantén el diseño dentro de este subconjunto para que los recursos se compilen de forma predecible y la simulación de UI cliente/servidor siga siendo determinista.