# Instrucciones para agentes de código (Copilot / AI)

Este repo es una librería de estilos y scripts para la Universidad de Concepción. Estas instrucciones resumen lo esencial para que un agente sea productivo rápidamente.

1) Propósito y arquitectura (big picture)
- Repositorio entrega estilos (SCSS/CSS) y scripts (JS) compilados y empaquetados en `dist/`.
- Fuentes principales: `src/scss/` (estilos), `src/js/` (scripts). El bundle principal de entrada es `src/scss/index.scss` y `src/js/index.js`.
- Sistema de build: Webpack Encore (`webpack.config.js`) genera `udec-styles` y `udec-scripts` en `dist/`.

2) Flujo de desarrollo y comandos importantes
- Instalar dependencias: `npm install`.
- Desarrollo rápido (build no minificado, con source maps): `npm run dev`.
- Build de producción: `npm run build`.
- Watch durante cambios: `npm run build:watch`.
- Lint CSS: `npm run lint` (nota: el `lint` en `package.json` termina con `|| true`, por eso no hace fallar el proceso).

3) Convenciones del proyecto
- Estructura: `src/scss/` está organizada en subcarpetas `components/`, `layouts/`, `utilities/`, `tokens/`, etc. Editar `src/scss/index.scss` para incluir nuevas piezas.
- En varios subdirectorios los archivos aparecen con extensión `.css` (previamente compilados o parciales). Respeta la organización: los cambios de diseño se hacen en `src/scss/*` y se compilan con Encore.
- JS: agregar/editar scripts en `src/js/`. El entry principal es `src/js/index.js` (re-exporta o importa los módulos necesarios).
- Ejemplos: `examples/` contiene HTML de referencia (ej. `examples/components/udec-banner.html`) que muestran cómo consumir los estilos y scripts.

4) Integración y puntos sensibles
- Entradas de Webpack: `.addEntry('udec-scripts', './src/js/index.js')` y `.addStyleEntry('udec-styles', './src/scss/index.scss')` en `webpack.config.js`. Cambiar estas entradas afecta el output empaquetado.
- PostCSS/Sass: habilitados por Encore (`.enableSassLoader()`, `.enablePostCssLoader()`), por lo que las convenciones de Sass y PostCSS se aplican en la compilación.
- Versionado/Source Maps: `enableSourceMaps(!Encore.isProduction())` y `enableVersioning(Encore.isProduction())`.
 - Gestión de assets estáticos: `webpack.config.js` copia `src/img` -> `dist/img/` y `src/icons` -> `dist/icons/` mediante `Encore.copyFiles()` para que `dist/` contenga las imágenes e íconos necesarios en el paquete publicado. Esto evita depender de que el consumidor recompilé el paquete.

  Nota: las rutas resultantes son `dist/img/...` y `dist/icons/...`. Las referencias desde CSS compilado apuntarán a rutas relativas generadas por Webpack (o a `dist/...` si se consume la hoja compilada manualmente).

5) Reglas prácticas para PRs y modificaciones por AI
- No modifiques `webpack.config.js` a menos que entiendas el impacto en `dist/` y las entradas de bundle.
- Para cambios de estilos: editar archivos bajo `src/scss/`, luego ejecutar `npm run dev` o `npm run build` y validar ejemplos en `examples/`.
- Para cambios JS: editar `src/js/` y asegurarse de que `src/js/index.js` exporte o importe los módulos adecuados.
- Evitar tocar `dist/` manualmente; es output generado.

6) Calidad y linting
- Stylelint está configurado como dependencia; usar `npm run lint` para chequeos rápidos. La tarea de lint no falla el build por diseño (ver `|| true`).

7) Qué no está en el repo (limitaciones)
- No hay tests automatizados (`test` en `package.json` es placeholder).
- No existe todavía `.github` con plantillas de PR/ISSUE o CI; agregar CI debe incluir pasos `npm ci && npm run build && npm run lint`.

8) Ejemplos rápidos de edición y verificación
- Añadir un componente SCSS:
  - Añadir archivo en `src/scss/components/`.
  - Importarlo desde `src/scss/index.scss`.
  - Ejecutar:
    ```bash
    npm install
    npm run dev
    ```
  - Abrir ejemplos locales (por ejemplo `examples/components/udec-banner.html`) con un servidor estático para verificar.

9) Archivos clave a revisar cuando realices cambios
- `package.json` — scripts y dependencias.
- `webpack.config.js` — entradas y loaders.
- `src/scss/index.scss` — punto de ensamblado de estilos.
- `src/js/index.js` — punto de ensamblado de scripts.
- `examples/` — páginas de referencia para comprobar cambios visuales.

Si algo en estas instrucciones está incompleto o quieres que incluya convenciones de commit/PR o ejemplos concretos de `src/scss`/`src/js`, indícalo y lo amplío.
