yousefnaim/yousefnaim-protofolio

Kit de portafolio neo-brutalista

Una plantilla de portafolio completa y probada, extraída de un sitio en producción. Todo está en assets/ — cópialo en un proyecto nuevo de Vite + React, reemplaza los datos de muestra con los del propietario y despliega. El kit se verificó con vite build desde cero y se renderizó sin errores en la consola.

Lo que obtienes

• Sistema de diseño — colores planos saturados, bordes de 3px, sombras sólidas descentradas, tarjetas inclinadas (assets/src/brutal/brutal.css, con ámbito bajo .nb).
• Secciones — cargador · navegación fija (scroll-spy, conmutadores de tema + idioma + sonido, hoja móvil) · héroe con efecto hover por letra · acerca de · cuadrícula de proyectos con una superposición de caso de estudio a pantalla completa (anterior/siguiente, teclado, restauración de foco) · pila · acordeón de experiencia · formulario de contacto · pie de página con reloj local en vivo.
• Bilingüe + RTL — Inglés/Árabe con propiedades CSS lógicas; modo claro/oscuro sin parpadeo.
• Sonido — Bucle generativo de synthwave a 124 BPM y efectos hover/click (cada letra del héroe reproduce una nota pentatónica). Sin archivos de audio, sin licencias.
• Asistente — Chat flotante respaldado por api/chat.js: RAG sobre los datos del propietario (BM25 consciente del árabe + embeddings de Gemini), respuestas fundamentadas, respaldo de modelo, mismo origen + límite de tasa. La clave API nunca llega al navegador.
• Configuración de despliegue — vercel.json (reescrituras SPA), .vercelignore.

Inicio rápido (nuevo proyecto)

1. npm create vite@latest mi-portafolio -- --template react e instala las dependencias listadas en assets/package.deps.json (i18next react-i18next lenis framer-motion lucide-react @emailjs/browser @google/genai).
2. Copia el contenido de assets/ en la raíz del proyecto (fusiona src/, reemplaza index.html y vite.config.js, añade api/, vercel.json, .vercelignore). Elimina las importaciones predeterminadas de src/App.css/index.css — el kit trae su propio CSS a través de brutal.css.
3. Rellena los datos del propietario (consulta Qué personalizar).
4. Añade el retrato en src/Imgs/portrait.jpg y las capturas de pantalla de los proyectos en public/projects/ (WebP, ≤1280px de ancho).
5. npm run dev → comprueba modo claro/oscuro, EN/AR, 375px y 1440px. npx vite build debe pasar.
6. Despliega: consulta references/deploy-and-secrets.md.

Qué personalizar (los únicos archivos que contienen contenido)

Archivo	Qué poner
src/data/siteFacts.js	nombre (EN/AR), nombre del héroe dividido, iniciales de navegación, ubicación, zona horaria, enlaces de contacto, IDs públicos de EmailJS, columnas de la pila tecnológica, herramientas
src/data/projectsMeta.js	proyectos: título, etiquetas, URL en vivo (o null), order, i18nIndex
src/data/projectImages.js	capturas de pantalla por proyecto; la primera imagen es la portada de la tarjeta
src/i18n/locales/{en,ar}.json	todo el texto — declaración del héroe, texto/estadísticas de acerca de, destacados, experiencia, subtítulo/descripción/etiquetas de pantalla por proyecto, "tipos" de proyecto, texto de contacto, indicaciones del asistente
index.html	<title>, descripción, favicon

Reglas al rellenar: escribe solo hechos que el propietario pueda confirmar; nunca inventes clientes, números, fechas o enlaces; mantén los nombres técnicos en inglés en ambos idiomas; projects.items[i] en los archivos de configuración regional debe coincidir con i18nIndex.

Lenguaje de diseño (resumen — valores exactos en references/design-system-spec.md)

• Solo color plano. Sin degradados, resplandor, desenfoque, vidrio o aspecto "AI" púrpura. Profundidad = borde + sombra dura.
• Bordes 3px solid var(--nb-line) · sombras desplazamientos sólidos (5px/8px 8px 0, 12–14px al pasar el ratón) · inclinación -2°…2°, enderezar al pasar el ratón.
• Tipografía: Bricolage Grotesque 800 mayúsculas para visualización, Space Grotesk para cuerpo, JetBrains Mono mayúsculas para etiquetas. Árabe: Cairo 700–900, sin espaciado, sin mayúsculas.
• Regla de contraste: el texto sobre un relleno saturado siempre es #111 con bordes #111 en ambos temas; solo las superficies neutras cambian con el tema.
• Ritmo de secciones: héroe amarillo → acerca de papel → proyectos azul → pila papel → experiencia lila → contacto rosa → pie negro. Cambia de color modificando los tokens --nb-*; mantén el ritmo.

Reglas de ingeniería (mantener al editar)

• Estado de revelación en un atributo de datos (data-reveal → data-in), nunca una clase — los re-renderizados de React sobrescriben las clases.
• La superposición de casos necesita data-lenis-prevent, de lo contrario, Lenis bloquea la rueda dentro. Lo mismo para cualquier superposición desplazable (chat del asistente, hoja móvil).
• Usa CSS lógico (inline-start/end, margin-inline), invierte las flechas en RTL, envuelve contadores numéricos en dir="ltr", nunca espacies letras en árabe.
• Nunca llames a localhost desde código de producción — los navegadores piden permiso a los visitantes para la red local. Llama a una API solo cuando su variable de entorno de URL esté configurada.
• Rendimiento: carga perezosa de secciones fuera de la pantalla; imágenes WebP con loading="lazy"; anima solo transform/opacity; respeta prefers-reduced-motion; sin bibliotecas 3D/UI pesadas en la ruta pública.
• Secretos: las claves API viven solo en variables de entorno del servidor (GEMINI_API_KEY). Nunca prefijes un secreto con VITE_ (se empaqueta en el navegador). Los IDs públicos de EmailJS están bien en el código del cliente.
• Accesibilidad: anillo de foco visible, enlace de salto, aria-pressed en conmutadores, role="dialog" + restauración de foco en superposiciones, soporte para movimiento reducido.

Verificar antes de decir "listo"

1. npx vite build pasa.
2. Modo claro + oscuro, EN + AR (RTL), 375px y 1440px; sin desbordamiento horizontal.
3. Abre un caso de estudio → Anterior/Siguiente/Esc, desplázate dentro con la rueda del ratón.
4. Pasa el ratón sobre el nombre del héroe y los controles (después de un clic) para confirmar los sonidos; los conmutadores persisten.
5. Si el asistente está desplegado: haz una pregunta de contacto, una pregunta para listar todos los proyectos y algo que no esté en los datos (debe decir que no lo sabe).
6. El panel de vista previa puede estar oculto (animaciones pausadas) — confirma el movimiento con una segunda captura de pantalla o un navegador real.

Artefactos del sistema de diseño

• DESIGN-SYSTEM.md — resumen + tabla de paleta/reglas con enlaces.
• design-system/tokens.css y tokens.json — los tokens para usar fuera del kit de React.
• design-system/styleguide.html — guía de estilo en vivo (abrir en un navegador): paleta con contraste, escala tipográfica, escalas de sombra/inclinación, cada componente, movimiento, hacer/no hacer.

Referencias (leer cuando sea necesario)

• references/design-system-spec.md — el sistema de diseño exacto: principios, cada color y dónde va, números de contraste, escala tipográfica, espaciado, escalas de sombra/borde/inclinación, tokens de movimiento, z-index, puntos de interrupción, anatomía y estados de los componentes.
• references/design-system.md — catálogo de clases, recetas de secciones, cómo cambiar el color o añadir una sección.
• references/interaction-and-sound.md — comportamiento hover/presión, sistema de revelación, arquitectura y ajuste de música + SFX.
• references/i18n-and-rtl.md — estructura de configuración regional, mapa de claves, tipografía árabe, lista de verificación RTL.
• references/assistant-rag.md — cómo funciona el endpoint del chat, fragmentos de conocimiento, ajuste de recuperación y el mensaje.
• references/deploy-and-secrets.md — pasos de GitHub + Vercel, variables de entorno, rotación de claves, solución de problemas.