Primeros pasos con Lily

Instalación

Lily se publica como repositorios Git independientes para cada framework. La forma más rápida de probarla es clonar el repositorio headless de tu tecnología:

git clone https://github.com/LilyDesignSystem/lily-design-system-react-headless
cd lily-design-system-react-headless
pnpm install

El mismo patrón sirve para los demás frameworks:

• @lilydesignsystem/html-headless — no hace falta instalar nada; copia los archivos .html
• @lilydesignsystem/svelte-headless — pnpm install
• @lilydesignsystem/react-headless — pnpm install
• @lilydesignsystem/vue-headless — pnpm install
• @lilydesignsystem/angular-headless — pnpm install
• @lilydesignsystem/nunjucks-headless — pnpm install
• lily-design-system-blazor-headless — dotnet build

Las bibliotecas headless están pensadas para clonarse o incorporarse al proyecto: trata el código fuente como la fuente de verdad y copia lo que necesites. Los asistentes de preferencias se distribuyen además como paquetes instalables con una canalización de compilación y publicación (npm para los frameworks de JS, NuGet para Blazor).

Usar un componente headless

Los componentes headless incluyen HTML semántico, ARIA y propiedades, pero nada de CSS. Aquí tienes un botón en cada framework:

HTML

<button class="button" type="button" aria-label="Save">
  Save
</button>

Svelte

<script>
  import Button from "lily-design-system-svelte-headless/components/Button/Button.svelte";
</script>

<Button onclick={save}>Save</Button>

React

import Button from "lily-design-system-react-headless/components/Button";

<Button onClick={save}>Save</Button>

Vue

<script setup>
  import Button from "lily-design-system-vue-headless/components/Button.vue";
</script>

<Button @click="save">Save</Button>

Angular

import { Button } from "@lilydesignsystem/angular-headless";

@Component({
  imports: [Button],
  template: `<lily-button (click)="save()">Save</lily-button>`,
})

Blazor

<Button OnClick="Save">Save</Button>

Nunjucks

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "button" }) }}

Usar un ejemplo con estilo

Las aplicaciones de ejemplo incluyen CSS, rutas y páginas de demostración completas. La forma más rápida de experimentar es iniciar la aplicación de ejemplo de SvelteKit, Next, Nuxt, Analog o Eleventy y ver la demostración en /components.

git clone https://github.com/LilyDesignSystem/lily-design-system-svelte-sveltekit-examples
cd lily-design-system-svelte-sveltekit-examples
pnpm install
pnpm run dev

Después abre http://localhost:5173 y explora /components.

Estilos y tokens de diseño

Cada componente se renderiza con una única clase en kebab-case en su elemento raíz. Por ejemplo, <Button> renderiza <button class="button">. Dale el estilo que quieras:

.button {
  background: var(--my-primary);
  color: #fff;
  padding: 0.75rem 1.5rem;
  border-radius: 0.5rem;
}
.button:hover { background: var(--my-primary-hover); }

La paleta de colores predeterminada de Lily (usada en las aplicaciones de ejemplo) es:

• Primario: #2563eb
• Peligro: #dc2626
• Advertencia: #f59e0b
• Éxito: #16a34a
• Fondo de página: #f9fafb
• Fondo de tarjeta: #ffffff

Son sugerencias, no requisitos. Sustitúyelas por la paleta de tu propia marca y Lily se adaptará encantada.

Temas listos para usar

¿No quieres escribir CSS desde cero? Lily incluye 45 temas de referencia independientes en el directorio themes/. Cada uno es una hoja de estilo que apunta a las clases de enlace de Lily: enlázala y ya tienes estilo:

<link rel="stylesheet" href="/assets/themes/united-kingdom-government-digital-service.css" />

El conjunto abarca:

• Sector público — NHS England, NHS Scotland y NHS Wales (con variantes para pacientes y para profesionales), GOV.UK GDS y el Sistema de diseño web de EE. UU.
• Inspirados en proveedores — Adobe Spectrum, Mozilla Protocol.
• Uso general — claro, oscuro, nord, dracula, wireframe y una treintena más.

Los selectores de los temas usan :where(...), de modo que tu propio CSS siempre gana en especificidad. Combínalos con el asistente theme-picker que verás más abajo para cambiar de tema en tiempo de ejecución, o sigue el tutorial de temas.

Asistentes de preferencias

Cada framework tiene un catálogo complementario *-helpers con ocho selectores pequeños (y un picker-bar que los reúne). Cada uno es un botón de icono headless que abre una ventana emergente —una lista de opciones, una lista de enlaces, un formulario de búsqueda o (en el caso de date-time-picker) un diálogo de selección de fecha—, no un <select> nativo; es compatible con SSR y no incluye CSS:

• theme-picker — carga hojas de estilo de temas en tiempo de ejecución intercambiando un <link> gestionado, establece data-theme en el documento y, opcionalmente, lo guarda en localStorage.
• locale-picker — establece lang y dir (con detección automática de escritura de derecha a izquierda) para que tu biblioteca de i18n pueda seguirlos; no traduce nada por sí mismo.
• text-size-picker — establece data-text-size en el documento; tu CSS asigna cada valor a un tamaño de fuente.
• motion-picker — establece data-motion en el documento, partiendo de la preferencia de movimiento reducido del visitante; tu CSS y tus scripts deciden qué suprimir.
• search-picker — un botón de icono que abre un campo de búsqueda; al enviarlo se navega a una página de búsqueda. Se encarga de una acción, no de una preferencia.
• link-picker — un icono de inicio que abre un menú con los enlaces de página que define tu aplicación (Inicio, Quiénes somos, Contacto, Política de privacidad, …). Se encarga de una acción, no de una preferencia.
• share-picker — abre la hoja de compartir nativa o una lista de destinos proporcionada por el consumidor, además de copiar la URL. Se encarga de una acción, no de una preferencia: no aplica nada y no guarda nada.
• date-time-picker — un campo de texto más un diálogo de selección de fecha APG para una fecha, una hora o ambas. Se encarga de un valor de formulario, no de una preferencia: la cadena ISO se convierte de ida y vuelta con <input type="date">.

git clone https://github.com/LilyDesignSystem/lily-design-system-svelte-helpers

El catálogo de Svelte es la referencia canónica; las versiones para React, Vue, Angular, HTML, Nunjucks, Web Components y Blazor coinciden con él contrato por contrato. Consulta el tutorial de asistentes.

Accesibilidad

Los componentes apuntan a WCAG 2.2 AAA. Siguen estos patrones:

• Elementos HTML semánticos en lugar de <div> genéricos.
• <label for="id"> para vincular etiquetas con campos.
• aria-labelledby / aria-describedby para referencias cruzadas.
• aria-invalid + aria-errormessage para estados de error.
• role="alert" y aria-live para contenido dinámico.
• aria-pressed, aria-expanded, aria-current para el estado.
• tabindex itinerante para las cuadrículas.

Los indicadores de foco los aporta el consumidor de forma intencionada: Lily nunca dibuja un anillo de foco predeterminado que choque con tu diseño. Las aplicaciones de ejemplo mantienen una base limpia de axe-core en todas sus rutas.

Internacionalización

Toda etiqueta, marcador de posición, mensaje de error y texto de botón es una propiedad. No hay cadenas escritas en el código. Incorpora el framework de traducción que prefieras: Paraglide, i18next, vue-i18n, react-intl, archivos .resx, lo que sea.

Para fechas, números y monedas, los componentes aceptan cadenas ya formateadas: tú las formateas con Intl.DateTimeFormat / Intl.NumberFormat / tu biblioteca preferida y pasas el resultado.

El asistente locale-picker comunica a tu biblioteca de i18n la configuración regional elegida estableciendo lang y dir en la raíz del documento.

Pruebas

Cada subproyecto de framework incluye sus propias pruebas con su pila idiomática:

• HTML: WebDriverIO con navegadores reales.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (mediante el complemento Analog de Vite).
• Nunjucks: Vitest con un asistente de renderizado.
• Blazor: bUnit.

Las pruebas usan únicamente los comparadores integrados de Vitest, nunca los comparadores de jest-dom. Así los conjuntos de pruebas siguen siendo portables. Las aplicaciones de ejemplo añaden conjuntos de Playwright de extremo a extremo, bases de accesibilidad con axe-core y un barrido de tamaños de ventana adaptables.

Agentes de IA

Este sitio publica llms.txt y llms.json en su raíz: un mapa cuidado de sus páginas más importantes, para cualquier herramienta que siga la convención llms.txt.

El monorrepositorio canónico incluye además dos habilidades de Claude: lily-design-system-skill, una habilidad de uso general que cubre los conceptos, la terminología y los patrones de composición de Lily para quien construye con el sistema, y lily-design-system-maintainer-skill, una habilidad técnica que cubre la estructura de archivos obligatorios y las herramientas del monorrepositorio para quien trabaja en él. Ambas están en la raíz del monorrepositorio canónico.

Solución de problemas

Cómo contribuir

Lily es joven y agradece la colaboración. Las contribuciones más útiles ahora mismo son:

• Componentes nuevos (sobre todo patrones de sistemas de diseño consolidados).
• Temas nuevos: cada uno es una hoja de estilo independiente, una primera solicitud de cambios bien acotada.
• Mejores estilos de ejemplo: muestra lo que es posible.
• Traducciones de las cadenas de las aplicaciones de ejemplo.
• Informes de errores con un caso reproducible mínimo.
• Auditorías de accesibilidad con lectores de pantalla y tecnologías de apoyo.

Abre incidencias y solicitudes de cambios en el repositorio correspondiente de github.com/LilyDesignSystem.

Comunidad y asistencia

• Preguntas e informes de errores — abre una incidencia en el repositorio correspondiente de github.com/LilyDesignSystem.
• Correo electrónico — el responsable lee joel@joelparkerhenderson.com y agradece la colaboración, la orientación y los comentarios.
• Réplicas — Lily también se publica en Codeberg y GitLab, para que puedas participar desde la plataforma que prefieras.
• Conducta — el proyecto sigue un código de conducta estándar; sé amable y presupón buena fe.

Preguntas frecuentes