Crear o modificar componentes en una biblioteca de componentes de UI con temas

## Localizar los archivos que afecta un cambio de componente Actúa como una persona colaboradora cuidadosa en una biblioteca de componentes reutilizable, personalizable mediante temas y accesible. Antes de editar, identifica el comportamiento solicitado, el componente o la utilidad afectados y cada área relacionada directamente. Usa la estructura real del repositorio, pero ten en cuenta que un cambio de componente puede abarcar algunas de estas áreas: - Componentes de ejecución y composables. - Tipos públicos y exportaciones. - Recetas de tema, variantes y valores predeterminados. - Pruebas unitarias, de renderizado, de instantáneas y de accesibilidad. - Documentación y ejemplos para usuarios. - Un entorno de pruebas local o una página de demostración. No supongas que todas las áreas deben cambiar. Sigue el componente existente y su equivalente más cercano; después, enumera únicamente las áreas necesarias para la solicitud. Limita las convenciones del código fuente y de las pruebas a esos directorios; no las apliques indiscriminadamente a la documentación, los ejemplos o las herramientas. Conserva el comportamiento público existente salvo que la tarea lo cambie explícitamente. Trata el reenvío de atributos, la resolución de valores predeterminados, la semántica de accesibilidad, el comportamiento de derecha a izquierda y las API documentadas como contratos, no como detalles de implementación. ## Leer solo las guías necesarias y empezar con el generador Lee primero las pautas de contribución del repositorio y carga después solo las referencias pertinentes para la tarea. Por ejemplo, usa las pautas de estructura de componentes para props, slots, events y patrones de plantilla; las pautas de temas para slots y variants; las pautas de pruebas para renderizado, instantáneas y accesibilidad; y las pautas de documentación para ejemplos y marcado. No cargues todas las referencias solo porque existan. Empieza por el archivo afectado, examina una implementación reciente y comparable, y abre pautas adicionales únicamente cuando el cambio alcance ese ámbito. Usa los scripts de paquete declarados por el proyecto y el gestor de paquetes compatible. Después de instalar las dependencias, ejecuta cualquier paso obligatorio de preparación o generación de tipos antes de iniciar un entorno de pruebas, el sitio de documentación o las comprobaciones. Usa el entorno local apropiado para el cambio: el entorno de pruebas de la aplicación principal, uno para otro framework, un entorno centrado en reproducir el problema o el sitio de documentación. Al crear un componente, prefiere el generador aprobado por el repositorio. Revisa los archivos generados antes de editarlos y solicita solo las plantillas necesarias para la tarea. Si no se puede aplicar ningún generador, reproduce manualmente la disposición de archivos y las convenciones de nombres establecidas. ## Respetar el orden de los valores predeterminados del tema y el diseño de derecha a izquierda Sigue de forma coherente las convenciones de código establecidas por la biblioteca: - Mantén separadas las importaciones exclusivas de tipos cuando lo exijan la cadena de herramientas o la guía de estilo. - Define los valores predeterminados de props en tiempo de ejecución mediante el asistente estándar y documenta los valores predeterminados públicos en la API orientada a tipos. - Añade marcadores de slot estables a los elementos renderizados. En el elemento raíz, un marcador proporcionado por quien llama debe prevalecer sobre el valor alternativo del componente; los elementos internos conservan sus propios marcadores. - Cuando la propagación automática de atributos esté desactivada, ordena o resuelve los enlaces de la raíz para que los atributos de quien llama no se sobrescriban silenciosamente. - Genera una salida de tema reactiva mediante el mecanismo calculado estándar, en vez de evaluar el estado del tema una sola vez. - Resuelve los valores predeterminados mediante toda la cadena de precedencia: entrada explícita del componente, contexto de grupo o campo más cercano, sustituciones del tema a nivel de biblioteca, valores predeterminados del componente y, por último, configuración de la aplicación según la defina el proyecto. - Pasa entradas sin procesar a los asistentes de contexto cuando convertirlas en proxies alteraría la precedencia de inyección. Cuando no haya un contexto más cercano, recurre al valor resuelto del componente en vez de descartar un valor predeterminado del tema. - Reenvía los props y events de la biblioteca de primitivas mediante el adaptador del proyecto compatible con proxies para conservar los valores predeterminados resueltos. Usa tokens de diseño semánticos en vez de valores sin procesar de la paleta. Usa propiedades lógicas de espaciado, posición, borde, radio y alineación de texto para que los diseños funcionen tanto en contextos de izquierda a derecha como de derecha a izquierda. Añade alternativas explícitas que tengan en cuenta la dirección para transformaciones, cursores, degradados o transiciones cuando las propiedades lógicas no puedan expresar el comportamiento. Mantén la implementación alineada con los patrones existentes. No introduzcas un sistema de valores predeterminados, una ruta de reenvío de props ni una capa de resolución de temas que compita con las existentes para un solo componente. ## Crear el componente con una lista de comprobación, del tema a las pruebas y la documentación Haz el seguimiento de un componente nuevo o de una funcionalidad importante de un componente mediante esta lista de comprobación: 1. Genera la estructura inicial o crea el componente en la ubicación estándar de ejecución. 2. Implementa el comportamiento, los props públicos, los slots, los events y la semántica de accesibilidad. 3. Añade o actualiza la receta del tema, incluidos slots, variants, variants compuestas y tokens semánticos. 4. Exporta los tipos públicos y registra cualquier interfaz de valores predeterminados del componente que requiera el sistema de temas. 5. Añade pruebas específicas para el comportamiento, los props, los slots, el reenvío de atributos, la direccionalidad y la accesibilidad, según corresponda. 6. Actualiza la documentación para usuarios con instrucciones de uso, ejemplos y detalles de la API. 7. Añade o actualiza un ejemplo del entorno de pruebas que muestre el comportamiento modificado. 8. Ejecuta el lint, las comprobaciones estáticas de tipos y el conjunto de pruebas pertinente. Usa instantáneas únicamente cuando el proyecto las considere un contrato útil y revisa los cambios generados en vez de aceptarlos automáticamente. Centra las pruebas en el comportamiento significativo desde el exterior y en las reglas de precedencia conocidas. Cuando la documentación se despliegue antes que una versión del paquete, conserva el marcador de prelanzamiento aprobado por el proyecto en los encabezados o ejemplos afectados. El marcador comunica deliberadamente que la documentación integrada puede describir una funcionalidad que se publicará en la siguiente versión; no lo retires ni lo señales como incoherente sin consultar la política de versiones. ## Ejecutar lint y pruebas, y abrir el pull request con los resultados reales Compara el diff final con los patrones establecidos más cercanos y con la solicitud original. Verifica lo siguiente: - La estructura del componente, los tipos públicos y las exportaciones son coherentes. - El código del tema usa tokens semánticos y conserva toda la cadena de precedencia de los valores predeterminados. - Los atributos de la raíz y los marcadores de slot respetan las sustituciones de quien llama. - Las propiedades lógicas o las variantes explícitas de dirección cubren el comportamiento de derecha a izquierda. - Las pruebas cubren los props, slots, comportamientos y requisitos de accesibilidad modificados. - La documentación contiene el uso, los ejemplos y los cambios de API necesarios. - Los marcadores intencionados de documentación de prelanzamiento permanecen intactos. Ejecuta los comandos de lint, comprobación de tipos y pruebas pertinentes del repositorio, e informa de sus resultados reales. No afirmes que las comprobaciones pasan basándote solo en una inspección. Actualiza la documentación cuando cambie el comportamiento público. Usa la convención obligatoria del repositorio para los mensajes de commit y su plantilla de pull request. Enlaza el elemento de trabajo correspondiente, identifica el tipo de cambio, describe el comportamiento y la verificación, y completa únicamente los elementos de la lista respaldados por pruebas. No reescribas, hagas `rebase`, uses `force-push` ni compactes el historial de commits de una persona colaboradora solo para ordenarlo. Puede ser aceptable conservar varios commits de desarrollo cuando el repositorio realiza una fusión mediante squash; sigue la política real de fusión del repositorio y la autorización del usuario.