Reglas

Las reglas definen las clases de utilidad y el CSS resultante. UnoCSS tiene muchas reglas integradas pero también permite agregar fácilmente reglas personalizadas.

Reglas estáticas

Con este ejemplo:

rules: [
  ['m-1', { margin: '0.25rem' }],
]

Se generará el siguiente CSS siempre que se detecte m-1 en el código base de los usuarios:

.m-1 { margin: 0.25rem; }

Nota: La sintaxis del cuerpo sigue la sintaxis de propiedades CSS, ej. font-weight en lugar de fontWeight. Si hay un guión - en el nombre de la propiedad debe estar entre comillas.

rules: [
  ['font-bold', { 'font-weight': 700 }],
]

Reglas dinámicas

Para hacerlo más inteligente, cambia el matcher a un RegExp y el cuerpo a una función:

rules: [
  [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
  [/^p-(\d+)$/, match => ({ padding: `${match[1] / 4}rem` })],
]

El primer argumento de la función del cuerpo es el resultado de coincidencia RegExp que se puede desestructurar para obtener los grupos coincidentes.

Por ejemplo, con el siguiente uso:

<div class="m-100">
  <button class="m-3">
    <icon class="p-5" />
    Mi Botón
  </button>
</div>

se generará el CSS correspondiente:

.m-100 { margin: 25rem; }
.m-3 { margin: 0.75rem; }
.p-5 { padding: 1.25rem; }

¡Felicitaciones! Ahora tienes tus propias utilidades de CSS atómico poderosas. ¡Disfruta!

Fallback de Reglas CSS

En casos donde podrías querer aprovechar el fallback de reglas CSS para usar nuevas características de CSS mientras también puedes hacer fallback para soportar navegadores antiguos, puedes opcionalmente devolver un array 2D como la representación CSS para reglas con las mismas claves. Por ejemplo:

rules: [
  [/^h-(\d+)dvh$/, ([_, d]) => {
    return [
      ['height', `${d}vh`],
      ['height', `${d}dvh`],
    ]
  }],
]

Lo que hará que h-100dvh genere:

.h-100dvh { height: 100vh; height: 100dvh; }

Ordenamiento

UnoCSS respeta el orden de las reglas que definiste en el CSS generado. Las posteriores vienen con mayor prioridad.

Al usar reglas dinámicas, puede coincidir con múltiples tokens. Por defecto, la salida de aquellos coincidentes bajo una sola regla dinámica se ordenará alfabéticamente dentro del grupo.

Fusión de reglas

Por defecto, UnoCSS fusionará las reglas CSS con el mismo cuerpo para minimizar el tamaño del CSS.

Por ejemplo, <div class="m-2 hover:m2"> generará:

.hover\:m2:hover,
.m-2 {
  margin: 0.5rem;
}

En lugar de dos reglas separadas:

.hover\:m2:hover {
  margin: 0.5rem;
}
.m-2 {
  margin: 0.5rem;
}

Símbolos especiales

Desde v0.61, UnoCSS soporta símbolos especiales para definir información meta adicional para tu CSS generado. Puedes acceder a símbolos desde el segundo argumento de la función matcher de regla dinámica.

Por ejemplo:

rules: [
  [/^grid$/, ([, d], { symbols }) => {
    return {
      [symbols.parent]: '@supports (display: grid)',
      display: 'grid',
    }
  }],
]

Generará:

@supports (display: grid) {
  .grid {
    display: grid;
  }
}

Símbolos disponibles

• symbols.parent: El wrapper padre de la regla CSS generada (ej. @supports, @media, etc.)
• symbols.selector: Una función para modificar el selector de la regla CSS generada (ver el ejemplo a continuación)
• symbols.layer: Una cadena/función/regex match que establece la capa UnoCSS de la regla CSS generada
• symbols.variants: Un array de manejadores de variantes que se aplican al objeto CSS actual
• symbols.shortcutsNoMerge: Un booleano para deshabilitar la fusión de la regla actual en atajos
• symbols.noMerge: Un booleano para deshabilitar la fusión de la regla actual en atajos
• symbols.sort: Un número para sobrescribir el orden de clasificación del objeto CSS actual

Reglas multi-selector

Desde v0.61, UnoCSS soporta multi-selector a través de funciones Generador de JavaScript.

Por ejemplo:

rules: [
  [/^button-(.*)$/, function* ([, color], { symbols }) {
    yield {
      background: color
    }
    yield {
      [symbols.selector]: selector => `${selector}:hover`,
      // https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix
      background: `color-mix(in srgb, ${color} 90%, black)`
    }
  }],
]

Generará múltiples reglas CSS:

.button-red {
  background: red;
}
.button-red:hover {
  background: color-mix(in srgb, red 90%, black);
}

Reglas completamente controladas

TIP

Esta es una característica avanzada, en la mayoría de situaciones no será necesaria.

Cuando realmente necesites algunas reglas avanzadas que no están cubiertas por la combinación de Reglas Dinámicas y Variantes, UnoCSS también proporciona una forma de darte control completo para generar el CSS.

Te permite devolver una cadena desde la función del cuerpo de la regla dinámica que se pasará directamente al CSS generado (esto también significa que necesitas cuidar cosas como el escape de CSS, la aplicación de variantes, la construcción de CSS, y así sucesivamente).

import { defineConfig, toEscapedSelector as e } from 'unocss'

export default defineConfig({
  rules: [
    [/^custom-(.+)$/, ([, name], { rawSelector, currentSelector, variantHandlers, theme }) => {
      // descartar reglas que no coinciden
      if (name.includes('something'))
        return

      // si quieres, puedes deshabilitar las variantes para esta regla
      if (variantHandlers.length)
        return
      const selector = e(rawSelector)
      // devolver una cadena en lugar de un objeto
      return `
${selector} {
  font-size: ${theme.fontSize.sm};
}
/* puedes tener múltiples reglas */
${selector}::after {
  content: 'after';
}
.foo > ${selector} {
  color: red;
}
/* o media queries */
@media (min-width: ${theme.breakpoints.sm}) {
  ${selector} {
    font-size: ${theme.fontSize.sm};
  }
}
`
    }],
  ],
})