> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/all-out-docs/docs-es/ui/uidoc-html-css-support.md). # Compatibilidad con HTML y CSS de UIDoc *** 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](/all-out-docs/docs-es/ui/uidoc-quick-start.md). 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: ```css 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.