oil-oil/oil-frontend

Oil Frontend

Primero identifica la tarea del usuario, los objetos de negocio y las fuentes de datos; luego elimina contenido no válido y establece la información, el estado, la propiedad del código y la implementación compartida correctos.

Siempre cumple

• Parte de tareas reales del usuario, objetos de negocio y resultados completos; el contenido visible solo debe retener información que ayude a identificar, comparar, juzgar, operar o comprender los resultados.
• Una intención del usuario se ejecuta una sola vez, la acción debe producir un resultado real; los límites de datos, operación, ocupado y envío deben ser consistentes. En caso de fallo, conserva el objeto actual, la posición y el contenido ya ingresado.
• Las tareas comunes siguen la cognición existente del usuario; la navegación de recursos se muestra por defecto, la edición debe activarse explícitamente, los formularios solo recopilan los datos necesarios para la tarea actual y que pertenecen al objeto actual.
• Los iconos, las formas de énfasis y los tamaños fijos deben expresar un significado estable; no uses decoraciones genéricas de IA, bordes de énfasis sin significado o tamaños que solo se adapten a la instancia actual para crear jerarquías.
• Los ajustes visuales primero reutilizan las variables de diseño, componentes y densidad existentes del proyecto, luego manejan jerarquía, espaciado, tipografía, superficie y retroalimentación; solo cuando no hay un estándar del proyecto se utilizan los valores de respaldo de las reglas de referencia, sin expandir los valores de respaldo en un nuevo sistema de diseño.
• Para un mismo dato de negocio y un mismo significado, solo se mantiene una fuente de autoridad; prioriza la reparación del flujo de datos, el diseño padre y la implementación compartida, no apliques parches repetidamente en posiciones de página.
• Organiza componentes, hooks, funciones, tipos, estilos y pruebas según la propiedad del negocio; el código de un solo módulo se coloca cerca, solo cuando hay una reutilización estable entre módulos se mueve a la capa compartida.
• Ante lógica compleja, primero verifica las capacidades existentes del proyecto y las bibliotecas maduras; si la dependencia existente no es adecuada, se puede introducir una nueva biblioteca bien mantenida y compatible con el proyecto, no escribas a mano capacidades centrales ya cubiertas por soluciones maduras existentes. La lógica simple se implementa directamente, no introduzcas nuevas dependencias para pequeñas cantidades de código.
• El historial del proyecto no es una prueba de corrección; los patrones erróneos deben ser reemplazados, y después de migrar todas las ubicaciones de uso relevantes, se elimina el código antiguo, los fallbacks, la lógica legacy y los estados obsoletos.

Orden de lectura de archivos de referencia

1. Después de la activación, primero solo lee este archivo, identifica la tarea, el objeto y el alcance de la modificación; no leas previamente los archivos de referencia.
2. Si la tarea no involucra interfaz visible para el usuario, estado y flujo de datos del frontend, implementación de componentes u organización del código frontend, deja de usar este Skill.
3. Primero elige una regla principal basada en el resultado que el usuario quiere cambiar, no la selecciones por tipo de archivo o por palabras clave de CSS o animación que aparezcan en el código.
4. Para cambios locales simples, solo lee una regla principal; solo si la tarea realmente incluye un segundo problema independiente, añade una más. Solo para revisiones integrales entre páginas se pueden leer tres, nunca más.
5. No sigas leyendo reglas debido a la aparición de palabras clave, enlaces dentro del archivo o "por si acaso". Cuando un síntoma visual es causado por datos, estado o diseño padre, lee la regla que realmente maneja la causa raíz, no cargues reglas visuales adicionales.

Tarea actual	Regla principal	Solo se complementa en estos casos
"No se ve bien", refinamiento visual, jerarquía, espaciado, tipografía, color, radio de borde, borde, sombra o icono	Ingeniería visual	Cuando sea necesario modificar tokens compartidos, estilos predeterminados de componentes o variantes, lee Componentes y organización del código; cuando se cambie la estructura de columnas, desplazamiento o responsive, cambia a leer Viewport y diálogos como regla principal
Animación, transición, microinteracción, expandir/contraer, feedback de arrastre, efectos de desplazamiento o lentitud	Movimiento y rendimiento	Cuando la animación sirve como feedback de acción o jerarquía visual, lee Ingeniería visual; cuando la causa raíz es un estado asíncrono, cambia a leer Estado y carga como regla principal
Límites de módulos, componentes, hooks, funciones, tipos, propiedad de estilos, estilos compartidos, organización de CSS o implementación compartida	Componentes y organización del código	Cuando sea necesario agregar nuevas verificaciones, lee Automatización
Agregar o cambiar texto, significado de acción, icono, feedback de clic o énfasis visual	Información y acción	Cuando se involucre identidad de objeto, imágenes o selectores, lee Identificación de recursos

Datos, estado y diseño continúan seleccionándose según el resultado:

Tarea actual	Regla principal	Solo se complementa en estos casos
Lista, tarjeta, detalle, tabla u operación por lotes	Colección y detalle	Cuando se involucre identidad de recurso, lee Identificación de recursos; cuando se involucre edición, lee Interacción y edición
Formulario, selección, edición o flujo de trabajo de varios pasos	Interacción y edición	Cuando se involucre el alcance de guardado y la continuidad del flujo, lee Alcance de datos y operaciones
Resultados de consulta, paginación, conjunto candidato, alcance de guardado, alcance por lotes o propiedad de resultados de solicitud	Alcance de datos y operaciones	Cuando cambie simultáneamente la representación de loading, refreshing, empty, error o processing, lee Estado y carga
loading, refreshing, empty, filtered-empty, error, queued, processing o skeleton	Estado y carga	Cuando se involucre simultáneamente instantánea de consulta, alcance de operación o propiedad de resultados de guardado, lee Alcance de datos y operaciones
Cambiar tamaño de página, columnas, desplazamiento, estructura de diálogo o comportamiento responsive	Viewport y diálogos	Cuando se involucren superposiciones que dependen de un disparador (dropdown, menú, tooltip), lee Superposiciones

Los siguientes casos no activan lecturas adicionales:

• La presencia en el código de Tailwind, CSS, transition o bibliotecas de animación no significa que la tarea sea visual o de animación.
• Al cambiar atributos visibles como color, espaciado, borde, sombra, tipografía, la regla principal es Ingeniería visual; solo si la tarea también requiere ajustar la propiedad de estilos, la forma de compartir o los límites del módulo, se complementa la regla de Componentes y organización del código.
• Si solo se corrigen nombres de variables de color, nombres de clase, tipos o errores de importación, y no se cambia el resultado visual, no se lee la regla de Ingeniería visual.
• Si solo se cambia el estado de negocio, el enlace de eventos o la fuente de datos para una animación existente, y no se altera la forma de movimiento ni el rendimiento, no se lee la regla de Animación.
• Si solo se mueven controles existentes, y no se cambia el texto, el significado de la acción o el feedback, no se lee la regla de Información y acción.
• Si solo se ajusta la propiedad de contenedores padre comunes, y no se cambia el tamaño, el desplazamiento, el diálogo o el comportamiento responsive, no se lee la regla de Viewport y diálogos.
• Los enlaces en los archivos de referencia solo indican la ubicación de las reglas relacionadas, no implican que se deban seguir leyendo.

Glosario rápido

Las palabras centrales en este archivo y las reglas de referencia se entienden según las siguientes definiciones:

• Identidad del recurso: La combinación mínima de información que permite al usuario reconocer "qué objeto es este" — imagen + nombre + un campo diferenciador. Ejemplo: la lista de miembros muestra "avatar + nombre + departamento", no "uuid + etiqueta de tipo".
• Pseudoperación: Un control que parece utilizable pero que en realidad no produce un resultado real. Ejemplo: hacer clic en "Guardar" solo cambia el estado local, se pierde al actualizar; un botón de eliminar permanentemente deshabilitado que ocupa espacio.
• Parche visual de un solo componente: Aplicar estilos a un solo componente en una página que usa un componente compartido. Ejemplo: <Dialog className="h-[640px]">, anulaciones con !important, selectores de página específicos para modificar el interior del componente. La forma correcta es modificar el componente compartido en sí, o agregar una variante de componente nombrada por propósito.
• Variante de componente nombrada por propósito: Se nombra por "por qué es diferente". Ejemplo: variant="destructive", size="compact" son aceptables; variant="blue", variant="userListPage" no lo son.
• Acción principal: La operación que completa la tarea principal en la página, diálogo o área de operación actual. Como máximo un botón de alto énfasis por área.
• Límite de envío: Cuándo entra en vigor realmente una modificación: inmediato, guardado automático, envío unificado explícito, o solo vista previa temporal.
• Alcance de ocupado: El área mínima que necesita evitar operaciones repetidas mientras una solicitud está en curso. Una solicitud de un solo ítem solo bloquea ese ítem, no toda la página con una máscara.
• Instantánea de consulta enviada: Las condiciones de consulta, lista, total de resultados e información de paginación determinados conjuntamente por una misma respuesta. Antes de que se complete una nueva consulta, la instantánea anterior sigue perteneciendo a las condiciones anteriores.
• Tarea por lotes del mismo tipo: Tarea de llenar el mismo campo repetidamente para un lote de objetos del mismo tipo, como programación por lotes, cambio de precio por lotes.
• Hoja de trabajo editable: Una tabla que mantiene múltiples filas en estado de edición para tareas por lotes del mismo tipo. En contraste con la lista de recursos: se muestra por defecto, la edición debe activarse explícitamente.

Orden de decisión

Responde en orden antes de realizar cambios.

Tarea y objeto:

1. ¿Qué tarea quiere completar el usuario ahora, y qué resultado indica que está completa?
2. ¿Qué objeto central gestiona la página, y los campos pertenecen a quién?
3. ¿Es navegación, comparación, selección o edición? ¿Se sigue la estructura y terminología familiar del usuario?

Datos y alcance:

4. ¿Los datos provienen de una colección completa, una colección visible actual o resultados de búsqueda?
5. ¿La operación, el estado de ocupado y el límite de envío afectan a qué alcance? ¿Las condiciones de consulta remota y la lista actual ya pertenecen al mismo resultado enviado?
6. ¿En qué información se basa el usuario para distinguir objetos adyacentes?
7. ¿Se puede eliminar texto, pasos, confirmaciones, entrada repetida o campos que el sistema ya conoce?
8. ¿Qué información pertenece a la colección y qué pertenece solo al detalle?

Estructura y estado:

9. ¿Cuál es la acción principal de la página, diálogo o área de operación actual?
10. ¿Quién es responsable de la pantalla inicial, el contenedor de desplazamiento y los límites de la superposición?
11. ¿Cómo se excluyen mutuamente loading, empty, filtered-empty, queued, processing, error, ready?

Visual y animación, solo responde cuando la tarea lo requiera:

12. ¿Qué tokens, componentes y páginas adyacentes del proyecto actual definen la jerarquía, densidad y lenguaje de animación? ¿Qué atributo visible es realmente inconsistente?
13. ¿La animación es para feedback de estado, explicar relaciones espaciales o decoración? ¿Se puede completar solo con transform, opacity o capacidades de componentes existentes?

Punto de aterrizaje:

14. ¿Ya existe un módulo, componente, hook, función, tipo, variable de diseño unificada o estilo con la propiedad correcta? ¿Cuál es la fuente de datos, diseño padre o implementación compartida que se debe modificar finalmente?

Cuando no se pueda responder claramente, primero detén la adición de elementos de interfaz: haz al usuario las 1 o 2 preguntas más críticas; si no se puede preguntar, implementa en el alcance mínimo verificable y declara las suposiciones realizadas en la salida.

Flujo de ejecución

1. Restablecer los hechos

• Busca en el proyecto módulos, componentes, hooks, funciones, tipos, variables de diseño unificadas y estilos existentes, confirma si el mismo significado ya tiene una implementación correcta.
• Encuentra todas las páginas y componentes que usan componentes compartidos, así como otras entradas para los mismos datos.
• Las solicitudes de revisión solo proporcionan evidencia y sugerencias; solo implementa cuando el usuario solicite una modificación.

2. Definir el alcance

• Define el objeto central, el propietario de los campos, la colección de datos, el alcance de la operación, el alcance de ocupado y el límite de envío.
• Distingue entre problemas de estructura de página, comportamiento predeterminado de componentes, errores en el uso de la página y errores de flujo de datos.
• Para problemas visuales, solo registra las diferencias que puedan señalar elementos específicos, atributos, evidencia existente y puntos de código de aterrizaje; cuando no se pueda determinar el valor correcto, usa primero los tokens existentes del proyecto o componentes similares adyacentes, no inventes valores numéricos precisos basados en estética.

3. Primero eliminar

• Elimina contenido que no afecte el juicio, estados duplicados, entradas duplicadas, confirmaciones duplicadas y parches visuales dirigidos a un solo componente.
• Elimina pseudoperaciones que no tengan un cambio de estado real o que no puedan guardar datos realmente.
• Elimina componentes antiguos, funciones antiguas, tipos antiguos, estados antiguos, fallbacks, lógica legacy, estilos antiguos y referencias obsoletas que ya hayan sido reemplazados por nuevas implementaciones.

4. Elegir la estructura

• Primero verifica el uso establecido de páginas de tareas similares y componentes contenedores compartidos en el proyecto; solo reutiliza si el patrón existente cumple con esta especificación, de lo contrario, vuelve a elegir la estructura según la tarea real.
• Según la tarea (navegación, comparación, selección, configuración por lotes o edición profunda), elige entre lista, tabla, hoja de trabajo, selector, diálogo o área de trabajo completa.
• La lista se encarga de la identificación y comparación, el detalle del contenido completo, y el editor de la modificación.
• Los ajustes visuales se procesan en el orden: "jerarquía de información → espacio y alineación → tipografía → superficie → estado del control → animación"; si la capa anterior ya resuelve el problema, detente y no sigas acumulando decoración.

5. Reparar la ubicación realmente incorrecta

• Prioriza la reparación del alcance de datos, alcance de operación, diseño padre, comportamiento predeterminado de componentes compartidos y variantes de componentes con significado estable.
• Las identidades de recursos, menús, superposiciones, cargas, diálogos y barras de operación que aparecen repetidamente deben usar componentes compartidos.
• Solo abstrae cuando las responsabilidades, entradas/salidas y comportamientos sean estables y se repitan; no copies componentes solo porque la estructura local es similar, ni crees componentes universales con innumerables interruptores de página.
• Si los componentes compartidos, funciones, estilos o flujos de datos existentes son en sí mismos incorrectos, dentro del alcance autorizado, repara o reemplaza directamente la implementación compartida realmente incorrecta, y maneja todas las ubicaciones de uso afectadas; no sigas agregando implementaciones incorrectas para mantener la compatibilidad histórica.
• Si no se puede terminar de modificar todo dentro del alcance actual, detén la expansión del patrón antiguo, informa claramente cuántas ubicaciones de uso antiguas quedan y hasta dónde se ha llegado en esta modificación; no afirmes que ya está unificado.
• Al reparar problemas detectables repetidamente, juzga si el proyecto realmente necesita agregar nuevas reglas de lint, prueba o verificación; si es necesario, lee Automatización según la tabla de rutas y cuéntalo dentro del número de reglas complementarias. No construyas automatización para cambios pequeños.
• No modifiques áreas no relacionadas.

6. Verificar

• Ejecuta la verificación de tipos, lint, pruebas o compilación existentes del proyecto que estén relacionadas con los cambios.
• Para cambios locales simples, solo verifica la ubicación modificada, el comportamiento directo y las ubicaciones de uso más cercanas; no expandas a una matriz de estados completa.
• Cuando el cambio involucre componentes compartidos, alcance de datos, estados asíncronos, flujos de formulario, desplazamiento, responsive o múltiples páginas, verifica entonces los estados afectados, el alcance de datos, los viewports representativos y todas las ubicaciones de uso.
• Para cambios visuales, verifica el contenido real, los estados principales y los viewports afectados; para cambios de animación, verifica solo por tipo los comportamientos de interrupción, activación repetida, salida, desmontaje o desplazamiento aplicables. Solo usa grabación de rendimiento para animaciones complejas o lentitud real; no conviertas cada transición en una tarea de rendimiento especializada.
• Solo informa elementos verificados, elementos no verificados y las razones de bloqueo.

Autoverificación independiente

Solo cuando la revisión frontend involucre múltiples páginas, todas las ubicaciones de uso de componentes compartidos, múltiples viewports o estados, o ajustes de reglas de gran alcance, se envía una autoverificación independiente sin contexto histórico. Las páginas individuales, componentes individuales, capturas de pantalla individuales y diferencias locales son revisadas directamente por el agente principal.

La autoverificación independiente solo recibe el objeto de verificación, el alcance y oil-frontend; no recibe historial de conversación, conclusiones existentes, conjeturas sobre el problema, respuestas esperadas ni soluciones de reparación.

Requisitos de salida

Primero da la conclusión, luego la evidencia. Solo se debe generar:

1. Problemas específicos;
2. Contenido que debe eliminarse;
3. La información, acciones y estructura espacial correctas;
4. Los módulos, componentes compartidos o flujos de datos que deben modificarse;
5. Elementos verificados y no verificados.

Está prohibido usar descripciones como "mejorar la experiencia", "más moderno", "más intuitivo" que no guíen la implementación.

No expandas activamente a una auditoría de accesibilidad especializada. Al implementar la UI, sigue usando elementos de interacción nativos, no dañes el comportamiento de enfoque, teclado, etiquetas y ARIA existente del proyecto; solo realiza verificaciones cuando el usuario lo solicite explícitamente o cuando el cambio actual haga que una tarea sea imposible de completar.