dodio12138/pixel-hud-ui

Pixel HUD UI

Un framework d'interface, pas juste un thème de couleurs. Il possède trois couches, et un bon résultat les utilise toutes :

1. Fondations : une grille de 4px, une échelle typographique adaptée à une police pixel de 12px, des rôles de couleurs (chaque couleur signifie une chose), des règles de 1px au lieu d'ombres, une animation pas à pas.
2. Contrôles : panneaux et barres de titre, touches (boutons) avec intentions, touches d'icônes, onglets, contrôles segmentés, lignes de liste, champs de formulaire, entrées, sélecteurs, cases à cocher et boutons radio carrés, interrupteurs à lampe, curseurs de jauge, jauges de progression, lampes, étiquettes, badges, capuchons de touches, menus, info-bulles, dialogues, toasts, tableaux, blocs de code, prose, chargeurs, états vides. Chacun a des tailles fixes et un modèle d'état partagé (survol, appuyé, focus, sélectionné, désactivé, chargement, erreur).
3. Palettes : jetons --hud-*, de sorte que le framework repose sur n'importe quelles couleurs, y compris celles de la marque de l'application.

Fichiers

Fichier	Ce que c'est
references/design-system.md	Le cahier des charges. Principes, fondations, anatomie de chaque contrôle, tailles, états, quand l'utiliser et accessibilité. Lisez-le avant de concevoir.
assets/pixel-hud.css	L'implémentation : jetons, globaux clairs sous [data-skin="pixel"], et classes de contrôle hud-*
assets/palettes.css	starward (espace profond, sombre), terminal (gris-vert, sombre), paper (sable chaud, clair)
assets/fonts.css	Fusion Pixel 12px (OFL), lié via jsDelivr ; ou auto-hébergé via @fontsource
assets/pixel-caret.js	Curseur bloc 3px optionnel pour les champs de texte (data-pixel-caret)
assets/demo.html	Chaque contrôle dans tous ses états, avec un sélecteur de palette : la référence visuelle
references/integration.md	Recettes par pile : mappage des couleurs d'une application, Tailwind, shadcn/ui, React/Next, Vue, encapsulation, bascule sans flash, polices auto-hébergées
scripts/check-contrast.mjs	Vérification WCAG pour n'importe quelle palette : node scripts/check-contrast.mjs mon.css

Flux de travail

1. Lire le cahier des charges et la démo

Lisez references/design-system.md (au moins les Principes, les Fondations et les contrôles dont la tâche a besoin) et regardez assets/demo.html. Le cahier des charges explique pourquoi chaque contrôle ressemble à ce qu'il est ; le suivre est ce qui fait qu'un écran se lit comme ce framework plutôt que "un thème sombre avec une police pixel".

2. Examiner le projet

Avant de copier quoi que ce soit, découvrez :

• la pile et où le CSS global se charge (fichier de layout, main.ts, index.html, entrée Tailwind) ;
• comment les couleurs sont définies aujourd'hui (propriétés personnalisées CSS, thème Tailwind, variables HSL de shadcn, hexadécimal dans les composants) ;
• s'il s'agit d'une nouvelle interface ou d'un restylage, du seul look de l'application ou d'un thème commutable, de la page entière ou d'une zone.

Cela détermine le mappage des couleurs (étape 4) et vous évite de lutter contre les styles de l'application.

3. Ajouter le kit

Copiez pixel-hud.css, fonts.css, palettes.css (si une palette groupée est utilisée) et pixel-caret.js (si l'application a des champs de texte) dans le projet. Ordre de chargement : polices → palettes → pixel-hud.css, après les styles de base de l'application.

4. Choisir les couleurs

• Une palette groupée : data-hud-palette="starward" | "terminal" | "paper".
• Les propres couleurs de l'application : un bloc mappe ses variables sur --hud-* (references/integration.md › Mappage des couleurs d'une application). Conserve la marque, ajoute le framework.
• Une nouvelle palette : suivez "新建一套配色" dans le cahier des charges.

Exécutez ensuite node scripts/check-contrast.mjs <fichier> pour toute palette que vous avez écrite ou mappée, et corrigez chaque ÉCHEC : les contrôles dépendent de la lisibilité des couleurs de la barre, du texte et du vert sur chaque surface.

5. L'activer

<html data-skin="pixel" data-hud-palette="starward">

Un thème commutable définit ces attributs avant le premier rendu (references/integration.md › Bascule sans flash). Pour styliser une seule zone, mettez les deux attributs sur son conteneur.

6. Construire avec les contrôles

Les globaux gèrent déjà la typographie, les coins carrés, les entrées natives, les sélecteurs, les curseurs de plage, les cases à cocher, les barres de défilement, les anneaux de focus, la sélection et les lignes de balayage. Donnez à chaque élément son rôle avec une classe, en suivant le cahier des charges pour la taille et l'état :

Besoin	Contrôle (classe)
Grouper des informations connexes	.hud-panel + .hud-titlebar (+ .hud-titlebar__actions), corps .hud-panel__body, sections .hud-subhead
Action principale	.hud-btn.is-solid (intention : accent, go, warn, info, danger)
Action secondaire	.hud-btn
Action avec icône uniquement	.hud-icon-btn + aria-label
Changer de vues	.hud-tabs > .hud-tab[aria-selected]
Choisir une valeur parmi 2–5	.hud-segmented > button[aria-pressed]
Liste navigable	.hud-row[aria-current]
Champ étiqueté	.hud-field > .hud-label + input/select + .hud-help / .hud-error
Menu déroulant	.hud-select > select
Oui/non, un parmi plusieurs	.hud-check, .hud-radio (marques carrées)
Allumer/éteindre instantané	button.hud-switch[role=switch][aria-checked] > .hud-switch__knob
Niveau / progression	.hud-gauge + --value (data-state warn/alert)
État	.hud-lamp[data-state]
Valeur, ID, paramètre	.hud-tag ; comptes .hud-badge ; touches kbd
Menus, astuces, modale, retour	.hud-menu, .hud-tooltip, .hud-backdrop > .hud-dialog, .hud-toasts > .hud-toast
Données, code, articles	table.hud-table, .hud-code, .hud-prose
Entrée de commande / chat	.hud-input + data-pixel-caret
Attente, rien à afficher	.hud-loader, aria-busy sur une touche, .hud-empty

Placez les classes dans le code source du composant (JSX, templates), en les passant via la propriété className/class d'une bibliothèque de composants, plutôt que d'écrire des sélecteurs contre les internes du framework : elles survivent aux refontes et se lisent clairement.

Lors du restylage d'une application existante, mappez d'abord chaque composant existant vers le tableau ci-dessus (une courte liste dans votre réponse aide l'utilisateur à suivre), puis appliquez-le.

7. Vérifier le résultat

• Prenez une capture d'écran de la page (ou ouvrez-la) et comparez avec assets/demo.html.
• Confirmez que la police pixel est chargée (document.fonts, onglet Réseau) ; une CSP peut bloquer jsDelivr, alors auto-hébergez-la.
• Parcourez au clavier : chaque contrôle atteignable, anneaux de focus verts de 1px visibles.
• Parcourez le modèle d'état sur les contrôles principaux : survol, appuyé, désactivé, chargement, erreur.
• Le script de contraste passe pour la palette utilisée.

Les règles les plus importantes

Le cahier des charges contient le raisonnement complet ; voici celles qui sont le plus souvent enfreintes :

• Carré et plat. Pas de rayon, pas d'ombres floues, pas de dégradés sauf les lignes de balayage. Seules les superpositions reçoivent l'ombre décalée dure.
• Les couleurs gardent leur rôle. Barre = structure et sélection ; vert = allumé, emphase, focus ; jaune = valeurs ; orange = notes et avertissements ; rouge = danger. Le vert utilisé comme décoration cesse de signifier "allumé".
• Sélectionné = inversé. Fond de barre avec texte sombre ; les lignes ajoutent un bord vert de 3px. Sur un fond de couleur de barre, le survol inverse dans l'autre sens.
• Une seule action principale pleine par zone ; les actions côte à côte reçoivent chacune leur propre couleur d'intention et la conservent lorsqu'elles sont désactivées (atténuation, pas de contour).
• Les barres de titre ne coiffent que les panneaux. Les en-têtes de tableaux et de code utilisent la teinte douce --hud-bar-soft.
• Les tailles proviennent de l'échelle : contrôles 24/28/32px, espacement sur la grille de 4px, texte 12/14/16/24/36px.

Pièges

• Le framework force border-radius: 0 !important dans sa portée. Gardez quelque chose de rond (un avatar) en limitant le skin à un conteneur qui l'exclut.
• color-mix() nécessite Chrome/Edge 111, Safari 16.2, Firefox 113 ; pour les navigateurs plus anciens, définissez --hud-bar-soft / --hud-bar-line avec des couleurs unies.
• Une classe qui définit display afficherait les éléments hidden ; le framework ré-cache [hidden] dans sa portée, donc préférez l'attribut hidden pour l'affichage/masquage.
• Les frameworks qui définissent la valeur d'un champ via du code ne déclenchent pas input ; appelez field.__pixelCaret.update() après un tel changement si le curseur doit se déplacer immédiatement.
• Les lignes de balayage se trouvent à un z-index très élevé avec pointer-events: none ; désactivez-les avec data-hud-scanlines="off" là où elles gênent (captures d'écran, applications canvas).