yousefnaim/yousefnaim-protofolio

Kit portfolio néo-brutaliste

Un modèle de portfolio complet et testé, extrait d'un site de production. Tout se trouve dans assets/ — copiez-le dans un nouveau projet Vite + React, remplacez les données factices par celles du propriétaire, et expédiez. Le kit a été vérifié avec vite build à partir de zéro et s'affiche sans erreur dans la console.

Ce que vous obtenez

• Système de design — couleurs saturées plates, bordures de 3px, ombres portées solides, tuiles inclinées (assets/src/brutal/brutal.css, limité au sélecteur .nb).
• Sections — écran de chargement · navigation fixe (défilement spy, bascules thème + langue + son, panneau mobile) · héros avec survol par lettre · à propos · grille de projets avec superposition d'étude de cas en plein écran (précédent/suivant, clavier, restauration du focus) · compétences · accordéon d'expérience · formulaire de contact · pied de page avec horloge locale en direct.
• Bilingue + RTL — Anglais/Arabe avec propriétés CSS logiques ; clair/sombre sans flash.
• Son — Boucle générative synthwave à 124 BPM et effets de survol/clic (chaque lettre du héros joue une note pentatonique). Pas de fichiers audio, pas de licence.
• Assistant — Chat flottant alimenté par api/chat.js : RAG sur les données du propriétaire (BM25 adapté à l'arabe + embeddings Gemini), réponses fondées, fallback de modèle, même origine + limite de débit. La clé API n'atteint jamais le navigateur.
• Configuration de déploiement — vercel.json (réécritures SPA), .vercelignore.

Démarrage rapide (nouveau projet)

1. npm create vite@latest mon-portfolio -- --template react et installez les dépendances listées dans assets/package.deps.json (i18next react-i18next lenis framer-motion lucide-react @emailjs/browser @google/genai).
2. Copiez le contenu de assets/ dans la racine du projet (fusionnez src/, remplacez index.html et vite.config.js, ajoutez api/, vercel.json, .vercelignore). Supprimez les imports par défaut src/App.css/index.css — le kit apporte son propre CSS via brutal.css.
3. Remplissez les données du propriétaire (voir Quoi personnaliser).
4. Ajoutez le portrait dans src/Imgs/portrait.jpg et les captures d'écran des projets dans public/projects/ (WebP, ≤1280px de large).
5. npm run dev → vérifiez le mode clair/sombre, EN/AR, 375px et 1440px. npx vite build doit réussir.
6. Déploiement : voir references/deploy-and-secrets.md.

Quoi personnaliser (les seuls fichiers qui contiennent du contenu)

Fichier	Ce qu'il faut y mettre
src/data/siteFacts.js	nom (EN/AR), nom du héros divisé, initiales de la navigation, localisation, fuseau horaire, liens de contact, ID publics EmailJS, colonnes de la pile technique, outils
src/data/projectsMeta.js	projets : titre, tags, URL en ligne (ou null), order, i18nIndex
src/data/projectImages.js	captures d'écran par projet ; la première image est la couverture de la carte
src/i18n/locales/{en,ar}.json	tout le texte — déclaration du héros, texte/statistiques à propos, points forts, expérience, sous-titre/description/labels d'écran par projet, "types" de projets, texte de contact, invites de l'assistant
index.html	<title>, description, favicon

Règles lors du remplissage : écrivez uniquement des faits que le propriétaire peut confirmer ; n'inventez jamais de clients, de chiffres, de dates ou de liens ; conservez les noms techniques en anglais dans les deux langues ; projects.items[i] dans les fichiers de locale doit correspondre à i18nIndex.

Langage de design (résumé — valeurs exactes dans references/design-system-spec.md)

• Couleur plate uniquement. Pas de dégradés, de lueur, de flou, de verre ou d'aspect "IA" violet. La profondeur = bordure + ombre dure.
• Bordures 3px solid var(--nb-line) · ombres décalages solides (5px/8px 8px 0, 12–14px au survol) · inclinaison -2°…2°, redressez au survol.
• Typographie : Bricolage Grotesque 800 en majuscules pour l'affichage, Space Grotesk pour le corps, JetBrains Mono en majuscules pour les étiquettes. Arabe : Cairo 700–900, pas d'espacement, pas de majuscules.
• Règle de contraste : le texte sur un fond saturé est toujours #111 avec des bordures #111 dans les deux thèmes ; seules les surfaces neutres changent avec le thème.
• Rythme des sections : héros jaune → à propos papier → travaux bleu → compétences papier → expérience lilas → contact rose → pied de page noir. Recolorez en modifiant les tokens --nb-* ; conservez le rythme.

Règles d'ingénierie (à conserver lors de l'édition)

• Révélez l'état dans un attribut de données (data-reveal → data-in), jamais dans une classe — les re-rendus React écrasent les classes.
• La superposition d'étude de cas nécessite data-lenis-prevent, sinon Lenis bloque la molette à l'intérieur. Idem pour toute superposition défilable (chat de l'assistant, panneau mobile).
• Utilisez le CSS logique (inline-start/end, margin-inline), inversez les flèches en RTL, encadrez les compteurs numériques avec dir="ltr", ne mettez jamais d'espacement entre les lettres de l'arabe.
• N'appelez jamais localhost depuis le code de production — les navigateurs demandent l'autorisation du réseau local aux visiteurs. N'appelez une API que lorsque sa variable d'environnement d'URL est définie.
• Performances : chargement différé des sections hors écran ; images WebP avec loading="lazy" ; animez uniquement transform/opacity ; respectez prefers-reduced-motion ; pas de bibliothèques 3D/UI lourdes sur le chemin public.
• Secrets : les clés API vivent uniquement dans les variables d'environnement du serveur (GEMINI_API_KEY). Ne préfixez jamais un secret avec VITE_ (il est intégré dans le navigateur). Les ID publics EmailJS sont acceptables dans le code client.
• Accessibilité : anneau de focus visible, lien d'évitement, aria-pressed sur les bascules, role="dialog" + restauration du focus sur les superpositions, prise en charge de reduced-motion.

Vérifiez avant de dire "terminé"

1. npx vite build réussit.
2. Mode clair + sombre, EN + AR (RTL), 375px et 1440px ; aucun débordement horizontal.
3. Ouvrez une étude de cas → Précédent/Suivant/Echap, défilez à l'intérieur avec la molette de la souris.
4. Survolez le nom du héros et les contrôles (après un clic) pour confirmer les sons ; les bascules persistent.
5. Si l'assistant est déployé : posez une question de contact, une question de liste de tous les projets, et quelque chose qui ne se trouve pas dans les données (il doit dire qu'il ne sait pas).
6. Le volet d'aperçu peut être masqué (animations en pause) — confirmez le mouvement avec une deuxième capture d'écran ou un vrai navigateur.

Artefacts du système de design

• DESIGN-SYSTEM.md — aperçu + tableau des palettes/règles avec liens.
• design-system/tokens.css et tokens.json — les tokens pour une utilisation en dehors du kit React.
• design-system/styleguide.html — guide de style vivant (ouvrez dans un navigateur) : palette avec contraste, échelle typographique, échelles d'ombre/inclinaison, chaque composant, animation, à faire/à ne pas faire.

Références (à lire si nécessaire)

• references/design-system-spec.md — le système de design exact : principes, chaque couleur et son emplacement, chiffres de contraste, échelle typographique, espacement, échelles d'ombre/bordure/inclinaison, tokens d'animation, z-index, points de rupture, anatomie et états des composants.
• references/design-system.md — catalogue des classes, recettes de sections, comment recolorer ou ajouter une section.
• references/interaction-and-sound.md — comportement au survol/appui, système de révélation, architecture et réglage de la musique + des effets sonores.
• references/i18n-and-rtl.md — structure des locales, correspondance des clés, typographie arabe, checklist RTL.
• references/assistant-rag.md — fonctionnement du point de terminaison du chat, blocs de connaissances, réglage de la récupération et de l'invite.
• references/deploy-and-secrets.md — étapes GitHub + Vercel, variables d'environnement, rotation des clés, dépannage.