# Tai Chi — Méthodologie **La source de vérité unique de ce projet.** Marque, système de design, base de données probantes, logique de prescription, politique de contenu et périmètre de sécurité vivent tous ici. Si le code et ce document divergent, l'un des deux est un bug — dites lequel dans la PR. Statut : document vivant · Dernière révision substantielle : 2026-08-02 > Traduction du document anglais `docs/METHODOLOGY.md`, section par section et > dans le même ordre. Cette correspondance est structurelle : les identifiants > des titres de `/fr/method` proviennent du fichier anglais par position, de > sorte que `/method#42-joints` et `/fr/method#42-joints` désignent la même > section. Cette traduction n'a pas été relue par un locuteur natif ; voir §11. --- ## 1. Ce que c'est, et ce que cela refuse d'être Tai Chi est un compagnon de tai-chi gratuit, public et sans inscription. Vous l'ouvrez, il sait quel jour on est, et il vous donne une séance façonnée par votre stabilité sur vos pieds, le temps dont vous disposez et ce que vous travaillez. **C'est :** - Un *planificateur et un minuteur* enroulés autour de l'enseignement d'autres personnes. - Un *moteur de rotation* dont la tâche principale est que demain ne ressemble pas à aujourd'hui. - Un intermédiaire honnête : chaque vidéo est attribuée, renvoie à son auteur et figure en entier sur la page bibliothèque. **Ce n'est délibérément pas :** - Un professeur. Il ne corrige pas votre posture, il ne peut pas vous voir, et il n'affirmera jamais qu'un mouvement est « correct ». - Un dispositif médical ni une intervention clinique. Il résume des données publiées pour expliquer *pourquoi les séances ont cette forme* ; il ne diagnostique pas, ne traite pas et ne s'adapte pas à une pathologie. - Un produit à comptes. Pas d'inscription, pas d'e-mail, pas de profil côté serveur, pas d'analytics. Tout vit dans `localStorage`, sur un seul appareil. ### 1.1 Pourquoi pas de compte Le pratiquant visé a de façon disproportionnée plus de 65 ans. Chaque mur d'inscription est un abandon, et un outil de bien-être qui demande à une personne de 78 ans de vérifier un e-mail est un outil qu'elle ouvre une seule fois. Les coûts de cette décision sont réels et nous les assumons ouvertement dans l'interface : pas de synchronisation entre appareils, et effacer les données du site efface la série. --- ## 2. Marque ### 2.1 Le nom **Tai Chi** (太極, *tài jí*) nomme la pratique elle-même plutôt qu'une ambiance autour d'elle. Il a été retenu parce que : - Il dit exactement à quoi sert l'application, avec les mots que les gens emploient déjà lorsqu'ils la cherchent. - Il est concret. « Flow », « Balance », « Serenity » sont des adjectifs déguisés en produits. - Il ne porte aucune affirmation. L'application programme l'enseignement d'autres personnes ; un nom de marque inventé sous-entendrait une méthode propre, et il n'y en a pas. ### 2.2 La voix Simple, calme et légèrement sèche. Phrases courtes. Jamais haletante, jamais mystique, jamais un coach qui hurle des encouragements. | Nous écrivons | Nous n'écrivons pas | | ------------------------------------------------------ | -------------------------------------------- | | « Rien à accomplir ici. Tenez-vous debout, c'est tout. » | « Accueillez votre quiétude intérieure ! » | | « La courbature, oui ; la douleur vive, non. » | « Écoutez votre corps 🙏 » | | « Le repos est de l'entraînement, pas un trou dedans. » | « Ne cassez pas votre série ! » | | « Celle-ci ne se lit pas ici. » | « Oups ! Une erreur est survenue. » | La culpabilité n'est jamais utilisée comme moteur. Il n'existe pas d'état « vous avez sauté 3 jours », et une série interrompue est signalée sans commentaire. ### 2.3 Le signe Deux arcs entrelacés — l'un qui monte, l'autre qui descend, partageant un centre — qui tracent le trajet des mains dans les « mains nuages ». Il porte l'échange yin/yang sur lequel repose la pratique sans recourir au taijitu, visuellement épuisé et qui se lit comme un logo de 1997. Épaisseur de trait unique, grille de 24 unités, lisible à la taille d'un favicon. ### 2.4 Couleur — nuit profonde et clair de lune L'application est **sombre par défaut**, et le sombre est l'état conçu, pas un accommodement. Le tai-chi se pratique à l'aube, dans une pièce peu éclairée, souvent avant d'allumer. Une page blanche et lumineuse à six heures du matin est hostile. Le mode clair existe et est complet, mais c'est la même marque à midi, pas une autre. L'écran est **un ciel nocturne avec une seule source de lumière dedans**. Tout en découle : la lune est fixée en haut à droite, les arêtes spéculaires des panneaux de verre supposent une lumière venant d'en haut et de la droite, et aucune surface n'émet sa propre couleur — elles captent le clair de lune. Tout est en `oklch`, si bien que les rampes de luminosité sont perceptuellement régulières et que les couches translucides se mélangent de façon prévisible. | Rampe | Rôle | Pourquoi cette teinte | | ---------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | **Nuit** | Fond et structure | Noir bleuté, jamais gris neutre. Ce léger bleu est ce qui fait lire l'accent comme de la *lumière* et non comme de la peinture | | **Clair de lune**| Primaire. L'unique source de lumière, et l'accent | Bleu pâle désaturé. Utilisé pour la commande de lecture, l'anneau du minuteur et l'état actif — et presque rien d'autre | | **Céladon** | La couleur de la pratique : qigong, échauffement, douce | Un jade retenu au point de se lire comme une porcelaine émaillée sous la lune, et non comme un « vert bien-être » | | **Lampe** | Aujourd'hui, séries, effort modéré | La seule teinte chaude en usage normal. Rationnée durement, pour qu'elle veuille dire quelque chose | | **Braise** | Intensité vigoureuse, actions destructrices | La seule teinte brûlante. Elle apparaît sur deux surfaces peut-être dans toute l'application | **La couleur n'est jamais le seul signal.** Chaque puce de phase associe la couleur à un libellé et à une icône ; les points d'intensité portent un équivalent textuel `sr-only`. ### 2.5 Typographie Deux familles, choisies pour le sujet et non pour la mode. - **Cormorant** (titrage) — une old-style calligraphique à modulation de trait proche du pinceau. Elle porte la qualité de la peinture à l'encre propre à la pratique sans recourir à un pastiche de caractère « oriental », qui serait à la fois laid et un peu insultant. Tailles de titrage uniquement : elle est bien trop fine pour composer du texte courant, et nous ne le faisons jamais. - **Inter** (tout ce qui est fonctionnel) — interface, commandes, et surtout le minuteur. Grande hauteur d'x, neutre, et de vrais chiffres tabulaires. Les chiffres tabulaires sont imposés au minuteur et à toute valeur qui change sur place, pour que les chiffres ne sautillent pas en se remplaçant. --- ## 3. Système de design ### 3.1 Les niveaux de tokens Trois niveaux, une seule direction de dépendance. Les composants ne consomment que le niveau 3. 1. **Primitif** — `--ch-moon-400`, `--ch-night-950`. Valeurs de marque brutes. Jamais référencées par un composant. 2. **Sémantique** — `--primary`, `--phase-form`, `--glass-blur`. Porteuses de sens, commutables par thème. C'est la couche que clair et sombre échangent. 3. **Composant** — utilitaires Tailwind générés dans `@theme inline` (`bg-phase-form`, `text-timer`, `rounded-3xl`). Une nouvelle couleur qui part directement dans un composant est une remarque de revue, pas un correctif. ### 3.2 Le verre liquide, spécifié Un panneau, ce sont quatre signaux empilés. S'il en manque un, cela ressemble à un rectangle translucide, pas à du verre. 1. **Réfraction** — `backdrop-filter: blur() saturate() brightness()`. C'est la saturation qui fait vendre ; le flou seul se lit comme du plastique dépoli. Dans la version sombre, les panneaux sont *fumés* plutôt que dépolis : le remplissage tombe à ~6 % et c'est la remontée de luminosité qui travaille. 2. **Corps** — un remplissage teinté translucide (`--glass-tint` / `--glass-fill`). 3. **Arêtes** — un filet clair en haut (`inset 0 1px 0`) et une ligne de contact sombre en bas. C'est ce qui suggère l'épaisseur. 4. **Spéculaire** — un balayage de reflet en diagonale via `::before`, plus un grain de bruit à 3,5 % via `::after`. Le grain existe pour vaincre l'aspect plastique des grands remplissages flous. Exposé comme `@utility glass`, `glass-faint`, `glass-strong`, `glass-specular`, `glass-grain`, `glass-press`, et consommé via une primitive `` unique à trois axes : `depth`, `tone`, `radius`. **Règle : ne bricolez jamais un `backdrop-blur` dans un composant.** Utilisez ``, ou ajoutez une variante. Deux choses rendent cela viable plutôt que décoratif : - **Le ciel nocturne.** Le verre ne se lit comme du verre que s'il y a derrière quelque chose qui mérite d'être réfracté. Une lune fixe et deux champs de sol lents et froids se tiennent derrière tout, en `-z-10`. CSS pur, pas de canvas, pas de rAF. Un voile par-dessus garantit le contraste du texte quel que soit l'endroit où un champ tombe — le ciel est une décoration, et le texte ne doit jamais en dépendre. - **Le repli `@supports`.** Là où `backdrop-filter` n'est pas pris en charge ou est désactivé, les remplissages passent à 88–98 % d'opacité. Le contraste du texte ne dépend jamais du flou. ### 3.3 Le mouvement | Règle | Raison | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Deux courbes d'accélération seulement, sur mesure | `--ease-glass` pour la matière, `--ease-settle` pour les arrivées. Au-delà de deux, cela se lit comme une incohérence. | | Rien n'arrive en animation par le côté | Le mouvement périphérique attire l'œil et casse une posture debout. Les repères apparaissent en fondu sur place. | | Les boucles d'ambiance durent 28–44 s | Assez lentes pour passer inaperçues ; plus rapides, elles deviennent un métronome contre lequel on lutte. | | `prefers-reduced-motion` supprime la dérive | …mais conserve les transitions d'opacité et de couleur, car elles portent l'état de la séance. | ### 3.4 Engagements d'accessibilité - Cibles tactiles : 44 px minimum, 48 px pour le transport, 64 px pour la lecture. - Chaque commande a un vrai `aria-label` ; l'anneau du minuteur est `aria-hidden` avec une région live `sr-only` à gros grain, pour ne pas être annoncé chaque seconde. - `role="radiogroup"` pour les options de réglage, afin que les flèches et les annonces de position fonctionnent. - Lien d'évitement, anneau de focus visible, `aria-current` sur la navigation et sur le bloc actif. - **Pas de `maximumScale`.** Cette application vise des personnes de plus de 65 ans ; le zoom n'est pas optionnel. - Sous-titres activés par défaut dans le lecteur — une grande partie de la bibliothèque est silencieuse, accentuée ou en mandarin, et la personne qui regarde est à l'autre bout de la pièce. ### 3.5 Architecture responsive La première version cassait en dessous d'environ 400 px, ce qui est inacceptable pour une application dont les utilisateurs l'ouvriront le plus souvent sur un téléphone calé contre une lampe. Les règles désormais : - **La navigation se déplace, elle ne rétrécit pas.** En dessous de `md`, l'en-tête ne porte que le signe de marque et deux commandes ; les quatre destinations de navigation deviennent une **barre d'onglets basse** fixe, en verre, consciente des zones sûres, avec icônes *et* libellés. Les barres à icônes seules sont illisibles pour la tranche d'âge visée. - **`overflow-x: hidden` sur `html` et `body`, et `min-width: 0` sur chaque élément.** Rien n'est jamais plus large que la fenêtre ; si quelque chose l'est, c'est un bug — mais un bug qui ne doit pas devenir une page qui défile latéralement. - **La bande hebdomadaire doit tenir sept cellules à 330 px.** Le libellé texte disparaît en dessous de `sm` ; l'initiale du jour, la date et le point de couleur survivent. Les cellules restent d'au moins 44 px de haut quoi qu'il arrive — c'est la commande la plus touchée de l'application. - **Zones sûres partout** : `env(safe-area-inset-*)` sur l'en-tête, la barre d'onglets et le panneau de réglage. - **Le minuteur est dimensionné par rapport à son anneau**, pas à la fenêtre. Un `clamp` piloté par `vw` débordait de l'anneau sur les grands écrans. - **`font-size: max(16px, 1em)` sur les commandes**, pour qu'iOS ne zoome jamais la page. ### 3.6 Internationalisation La langue est **détectée automatiquement depuis le navigateur** à la première visite, puis mémorisée. 1. Lire `navigator.languages` — la liste de préférences ordonnée de l'utilisateur — et prendre la première entrée prise en charge. Quelqu'un dont la liste est `[ca, es, en]` obtient l'espagnol, pas l'anglais. 2. Ne comparer que la sous-étiquette principale : `es-419`, `es-MX` et `es` se résolvent tous en espagnol. Toute variante chinoise se résout en simplifié — livrer `zh-Hant` sans véritable traduction en traditionnel serait pire que d'afficher du simplifié. 3. Un choix explicite dans le panneau de réglage l'emporte sur la détection et est écrit dans `localStorage`. « Suivre mon navigateur » efface ce choix. Langues livrées : **anglais, espagnol, français, allemand, chinois simplifié.** Deux décisions d'architecture font que cela fonctionne au lieu de fonctionner à moitié : - **Le moteur émet des clés, jamais de la prose.** `prescribe` et `select` sont purs et aveugles à la langue : ils renvoient `Note = { key, values }` et l'interface le résout. La justification, les précautions et les notes de bloc sont donc traduites, pas seulement l'habillage. Lorsqu'une valeur est *elle-même* un terme traduisible (« vous avez demandé *douce* »), le moteur l'émet derrière une sentinelle NUL et `translate` la résout d'un niveau. - **L'anglais est la source de vérité et le type.** Chaque autre langue est typée `Record` : une clé manquante est une erreur de compilation. Une clé manquante à l'exécution retombe sur l'anglais plutôt que d'afficher la clé brute. Toutes les familles de routes sont traduites : l'habillage, les pages de cours, les treize essais `/for/*`, le tutoriel d'installation et ce document. `src/lib/i18n/coverage.ts` reste la source de vérité pour savoir lesquelles peuvent être *indexées* dans quelle langue, et retirer une affirmation tient en une ligne par famille. Deux catégories ne sont délibérément pas traduites, et une l'est délibérément d'une manière inhabituelle : - **Non traduits : les noms de rangs** (noms propres, comme les grades kyū et dan) et **les titres de vidéos et noms de chaînes** (l'attribution doit correspondre à la source). - **Non traduites : les ancres de titres de la méthodologie.** `/method#42-joints` se résout dans toutes les langues, parce que les identifiants du document rendu proviennent du fichier anglais par position et non d'un slug des titres traduits. Une ancre est un identifiant, et les identifiants ne se traduisent pas. Le coût : une traduction ne doit ni ajouter, ni supprimer, ni réordonner une section ; le test l'impose. - **Traduits par l'éditeur, pas par nous : les libellés de menu de `/install`.** iOS, Chrome, Firefox et Samsung Internet localisent leurs propres menus, donc `install.label.*` porte la formulation propre à chaque éditeur dans chaque langue. Lorsqu'un éditeur ne traduit pas un libellé, laisser la chaîne anglaise est la bonne valeur — le seul endroit des dictionnaires où c'est vrai. --- ## 3A. Progression La progression se mesure en **jours où vous êtes venu** — jamais en minutes, jamais en intensité. Une séance assise de cinq minutes un mauvais jour compte exactement autant qu'une forme de quarante-cinq minutes un bon jour. Ce n'est pas un adoucissement. Récompenser le volume pousserait précisément les personnes pour qui cette application est faite — plus âgées, plus raides, moins sûres — à en faire trop, ce qui est la principale façon dont une intervention d'exercice fait du mal. **Rangs** (dérivés des jours accomplis, jamais stockés) : | Rang | | Jours | | Rang | | Jours | | --- | --- | --- | --- | --- | --- | --- | | Esprit du débutant | 初心 | 0 | | Grue blanche | 白鶴 | 60 | | Première lumière | 初光 | 1 | | Long fleuve | 長江 | 100 | | Eau calme | 靜水 | 5 | | Socle rocheux | 磐石 | 180 | | Bambou vert | 青竹 | 15 | | Vieux pin | 古松 | 365 | | Nuage en marche | 行雲 | 30 | | | | | Les **jalons** se gagnent et ne se perdent jamais. L'un d'eux — *Revenu* — est explicitement pour le retour après quinze jours d'absence, parce que c'est plus difficile qu'une série et qu'aucun suivi d'habitudes ne le récompense. Anti-modèles que cet écran refuse : - Pas d'état « vous avez cassé votre série », et pas de rouge nulle part. - Ne pas avoir encore pratiqué aujourd'hui ne casse **pas** la série. La journée n'est pas finie. - Aucune comparaison avec d'autres personnes. Il n'y a personne d'autre ici. - Tout est **dérivé du journal à chaque rendu.** Stocker une série à côté de l'historique qui la produit, c'est ainsi que tout suivi d'habitudes finit par afficher un nombre que ses propres données contredisent. --- ## 4. La base de données probantes Chaque affirmation ci-dessous porte sa source et son **statut de vérification** : `✅ vérifié` signifie que les chiffres ont été contrôlés sur la source lors de la rédaction ; `⚠️ non vérifié` signifie qu'elle est énoncée à partir de connaissances générales et devrait être confirmée avant tout usage marketing public. ### 4.1 Chutes - **Le tai-chi réduit le taux de chutes d'environ 19 %** chez les personnes âgées vivant à domicile (RaR 0,81 ; IC 95 % 0,67–0,99 ; 2 655 participants sur 7 études ; données de *faible certitude*). Sherrington et al., Cochrane Database of Systematic Reviews, 2019. ✅ vérifié - La même revue classe l'**exercice d'équilibre et fonctionnel** plus haut : 24 % de réduction, données de certitude élevée (RaR 0,76 ; IC 95 % 0,70–0,81 ; 39 études). Le tai-chi est *bon*, pas *le meilleur*, et la certitude est moindre. - **Dans une population à haut risque, un protocole thérapeutique de tai ji quan a réduit les chutes de 58 % par rapport aux étirements et de 31 % par rapport à un exercice multimodal** (IRR 0,42 ; IC 95 % 0,31–0,56 vs étirements). Li et al., *JAMA Internal Medicine*, 2018, 670 adultes de 70 ans et plus avec des antécédents de chute ou une mobilité réduite. ✅ vérifié **Ce que nous en retenons :** le travail d'équilibre est le bloc à plus forte valeur pour les pratiquants âgés, donc l'objectif `balance` double à peu près cette phase, et le cadrage « prévention des chutes » est honnête plutôt qu'exagéré. ### 4.2 Articulations - **Dans l'arthrose du genou, le tai-chi a produit des améliorations WOMAC comparables à la kinésithérapie standard** à 12 semaines (tai-chi 167 points, IC 95 % 145–190 ; kiné 143 points, IC 95 % 119–167 ; différence entre groupes non significative). Wang et al., *Annals of Internal Medicine*, 2016, n = 204. ✅ vérifié - Le *Tai Chi for Arthritis* du Dr Paul Lam (style Sun, posture haute, sans flexion profonde du genou) est le protocole le plus largement diffusé dans ce domaine et constitue le contenu `form` par défaut pour l'objectif `joints` et la tranche 75+. ⚠️ non vérifié (popularité du programme, pas une affirmation d'efficacité) ### 4.3 Dose - **Recommandations de l'OMS 2020**, adultes de 65 ans et plus : 150–300 min d'activité aérobie d'intensité modérée par semaine, renforcement musculaire ≥2 jours/semaine, et **activité multicomposante variée mettant l'accent sur l'équilibre fonctionnel et la force, à intensité modérée ou supérieure, ≥3 jours/semaine**. ✅ vérifié **Ce que nous en retenons :** le plan par défaut est de 5 jours/semaine, et la planification hebdomadaire garantit que l'accent sur l'équilibre apparaît sur plusieurs jours non consécutifs. Un pratiquant qui choisit moins de 3 jours n'est pas averti — harceler est contraire à la marque — mais le plan répartit tout de même l'accent au lieu de répéter une seule qualité. ### 4.4 Intensité - Le tai-chi général est conventionnellement classé comme d'**intensité légère à modérée, autour de 3,0 MET** (Compendium of Physical Activities). ⚠️ non vérifié — traité uniquement comme heuristique de conception, jamais affiché aux utilisateurs comme un nombre. L'intensité en tai-chi n'est *pas la vitesse*. Elle est modulée par : 1. **La hauteur de posture** — la variable dominante, de loin. 2. **L'amplitude de mouvement.** 3. **Le temps sur une jambe** — le principal moteur à la fois de l'effet d'entraînement et du risque de chute. 4. **La continuité** — quelle part de la séance est un mouvement ininterrompu. C'est pourquoi l'interface indique « En tai-chi, cela tient à la hauteur de posture et au temps sur une jambe, pas à la vitesse » juste sous la commande d'intensité. ### 4.5 Respiration - Les blocs guidés donnent un rythme d'environ **5,5 respirations par minute** (un cycle de 11 secondes), dans la plage de fréquence de résonance associée aux effets à court terme les plus nets sur la variabilité de la fréquence cardiaque et la sensibilité du baroréflexe. ⚠️ non vérifié — présenté comme une *suggestion* ; rien dans l'application n'impose de s'y tenir. ### 4.6 Habitude - Le levier le plus fort sur l'assiduité que nous puissions réellement actionner est de rendre la séance suivante **visible et déjà décidée**. D'où la bande hebdomadaire épinglée au-dessus de tout, et les jours de repos affichés plutôt qu'omis. ⚠️ non vérifié en tant qu'effet chiffré ; traité comme un principe produit. ### 4.7 Ce que les données ne permettent *pas* d'affirmer Énoncé clairement, pour que personne ne bâtisse sur du sable : - Il n'a **pas** été démontré que le tai-chi soit supérieur à un entraînement de l'équilibre conventionnel bien conçu pour les chutes. - La certitude des données spécifiquement sur le tai-chi est en général **faible à modérée** ; les essais sont petits, l'aveugle est impossible et les comparateurs de contrôle d'attention sont inconstants. - Rien ici ne soutient d'affirmation sur l'immunité, l'« énergie », le fonctionnement des organes ou la guérison de maladies. L'application n'en fait jamais, y compris dans les textes sur le qigong, où les *titres* de vidéos en font parfois. Nous reproduisons les titres mot pour mot au titre de l'attribution — ce n'est pas une approbation. --- ## 5. Le modèle de prescription `src/lib/engine/prescribe.ts` — un profil entre, un plan sort. Aucun contenu n'est sélectionné ici, ce qui rend la *forme* de la séance testable sans toucher à la bibliothèque de vidéos. ### 5.1 L'arc en cinq phases Chaque séance, à toute durée, suit le même arc. La familiarité est le but : le rituel ne devrait pas changer simplement parce que le contenu change. | Phase | 中文 | Objet | Part de base | | ------------------ | ---- | --------------------------------------------------------------------------------- | ------------ | | **Installation** | 無極 | Arriver. Poser le souffle, trouver l'alignement vertical. | 8 % | | **Échauffement** | 熱身 | Mobiliser chevilles, hanches, colonne et épaules dans l'amplitude sans douleur. | 17 % | | **Qigong** | 氣功 | Mouvement répétable lié au souffle. Construit la coordination. | 27 % | | **Forme** | 套路 | Chorégraphie continue. Le cœur cognitif et postural. | 30 % | | **Équilibre** | 平衡 | Transfert de poids délibéré, pas contrôlé, posture étroite. | 13 % | | **Clôture** | 收功 | Redescendre. Ralentir le souffle, revenir dans la pièce. | 5 % | **L'installation et la clôture sont toujours présentes et toujours racontées par l'application, pas par une vidéo.** Trois raisons : personne ne publie un bon retour au calme de deux minutes ; une ouverture et une clôture fixes sont le plus puissant repère d'habitude disponible ; et cela signifie qu'une séance fonctionne encore quand une vidéo est retirée ou que la connexion tombe. ### 5.2 Repondération par objectif L'objectif multiplie les parts de base, puis tout est renormalisé — un objectif peut donc accentuer une phase mais jamais en supprimer une par arithmétique. | Objectif | Accent | | --------------- | ------------------------------------------------------------- | | **équilibre** | équilibre ×2,0 ; échauffement ×1,1 ; forme/qigong ×0,85 | | **articulations** | échauffement ×1,55 ; qigong ×1,2 ; forme ×0,8 | | **apaisement** | installation ×2,2 ; clôture ×2,0 ; qigong ×1,2 ; forme ×0,7 | | **force** | équilibre ×1,45 ; forme ×1,15 ; installation ×0,7 | | **endurance** | forme ×1,3 ; qigong ×1,2 ; installation ×0,5 | | **cognition** | forme ×1,55 ; équilibre ×1,1 ; qigong ×0,8 | ### 5.3 Planchers de phase et suppression Chaque phase a un minimum en dessous duquel elle ne vaut pas la peine — vous passeriez le bloc entier à trouver la position de départ de la vidéo. `center 90s · warmup 120s · qigong 180s · form 240s · balance 120s · close 90s` L'allocation itère : calculer les parts → repérer les phases sous-dotées → supprimer la supprimable de plus faible poids → recalculer. L'itération compte, car supprimer une phase peut en faire passer une autre au-dessus de son plancher. `center` et `close` sont protégées et jamais supprimées ; au moins l'une de `qigong` / `form` / `balance` doit survivre. Les durées finales sont arrondies à 15 s, le reste étant reporté sur le plus gros bloc. C'est pourquoi une séance de 10 minutes a quatre blocs et une séance de 45 minutes en a six, sans aucun gabarit codé en dur par durée. ### 5.4 Plafonds de sécurité **La mobilité est la barrière stricte. L'âge est une barrière souple.** Une personne stable de 80 ans l'emporte sur une personne instable de 55 ans, et l'interface interroge la mobilité *en premier* pour signaler qu'il s'agit d'une question de sécurité et non de démographie. ``` mobility ceiling: seated → gentle supported → gentle steady → vigorous age ceiling: <50 → vigorous 50–64 → vigorous 65–74 → moderate 75+ → gentle effective = min(requested, mobility ceiling, age ceiling) ``` Une exception : **stable sur ses pieds _et_ pratique installée** relève le plafond d'*âge* d'un cran. Une capacité démontrée l'emporte sur une année de naissance. Le plafond de mobilité n'est jamais relevé. Quand l'intensité demandée est plafonnée, l'application le dit, et dit quelle contrainte a tranché — « C'est l'appui debout qui limite, pas l'âge. » Conséquences structurelles supplémentaires : - `seated` → **la phase d'équilibre est entièrement retirée** (il n'existe pas d'équivalent assis honnête à la station sur une jambe) et son temps va au qigong, où le contrôle du tronc et le transfert de poids se travaillent assis. - `seated` ou `supported` → `requireChairFriendly`, qui est un filtre strict sur le contenu, pas une préférence. - `new` → échauffement ×1,25 ; forme ×0,85 ; et les professeurs pas à pas sont préférés. - `established` → forme ×1,2 ; échauffement ×0,85. ### 5.5 Format court La même séance, découpée autrement. `prescribe()` prend un format — `"full"` ou `"shorts"` — et le pratiquant bascule de l'un à l'autre sur l'écran de pratique. Tout ce qui compte est partagé : le même profil, les mêmes minutes, le même arc en cinq phases dans le même ordre, et **le même plafond de sécurité**, calculé par le même code. Une séance courte n'est pas une séance allégée. Ce qui change : - **Les phases sont découpées en cartes.** Cible 75 s, jamais sous 45 s ni au-dessus de 105 s, 26 cartes au plus. Les deux bornes sont posées : une borne basse seule laissait passer une phase de 110 secondes en une seule carte, ce qui est un bloc de séance complète déguisé en carte. - **Les planchers de phase baissent** à environ une carte chacun (`center 45 · warmup 45 · qigong 60 · form 60 · balance 45 · close 45`) et le grain d'allocation passe de 15 s à 5 s. Une séance courte de 15 minutes peut donc contenir les cinq phases là où le format complet en aurait supprimé deux — l'arc est plus complet, pas moins. - **Le contenu doit tenir dans une carte.** Le sélecteur plafonne la durée candidate à 5 minutes, avec un relâchement à 10 et pas au-delà ; un cours assis de 42 minutes montré pendant 75 secondes n'est pas un cours, c'en est un fragment. - **Environ une carte sur trois est guidée plutôt que filmée**, en plus de l'installation et de la clôture qui le sont toujours. C'est à cela que servent les 29 blocs `micro` : un fondamental nommé chacun, avec son chinois et son pinyin sur la carte. Pourquoi ce format existe : la séance complète suppose que vous avez décidé de pratiquer. Le fil suppose que non, et demande une minute. La littérature sur la dose (§4.3) parle de semaines cumulées de pratique, pas de la durée d'une séance : une séance de quinze minutes prise en douze cartes n'est donc pas une version dégradée de quoi que ce soit. Ce qu'il n'emprunte délibérément pas aux fils auxquels il ressemble : il se termine, rien n'est recadré pour remplir l'écran, et c'est l'horloge — pas la vidéo — qui décide quand une carte est finie. --- ## 6. Le moteur anti-répétition `src/lib/engine/select.ts`. C'est la partie dont dépend tout le produit : **cela ne doit pas donner l'impression d'être la même chose tous les jours.** Un score naïf de « meilleure correspondance » échoue immédiatement — la meilleure correspondance est déterministe, donc le jour 2 est identique au jour 1. La nouveauté n'est donc pas ici un critère de départage. C'est le plus grand terme du score. ### 6.1 Score ``` score = 0.42 · novelty # days since last served / 21, capped at 1 + 0.30 · durationFit # how well the runtime covers the block + 0.20 · fit # focus, intensity, level, teaching style + 0.08 · jitter # seeded random — what "Shuffle" perturbs × 0.55 if the channel appeared in either of the last two sessions × 0.85 if the style appeared in the last session ``` Les cartes du format court repondèrent les mêmes termes au lieu d'utiliser un autre score : `novelty 0.32 · durationFit 0.46 · fit 0.17 · jitter 0.05`. L'ajustement de durée domine parce qu'une carte fait 75 secondes et que la pénalité pour un cours qui s'épuise en milieu de carte est sévère. **La langue est appliquée après le choix, pas dans le score.** Quinze cours sont sans paroles ; les autres sont commentés, presque tous en anglais. Le classement est identique pour toutes les langues, et ce n'est qu'ensuite — à l'intérieur de la fenêtre de tirage dans laquelle il choisissait déjà — qu'un spectateur non anglophone reçoit le premier cours compréhensible si celui tiré ne l'était pas. Pondérer le score par la langue réordonne au contraire toute la liste par langue, et l'index de rotation du jour désigne alors un cours différent dans chaque ordre : un spectateur francophone pourrait ainsi recevoir le cours anglais qu'un cours sans paroles venait de déplacer dans sa propre liste. La promesse « jamais moins de cours sans paroles qu'un spectateur anglophone » est désormais vraie par construction. ### 6.2 Règles strictes, et l'ordre dans lequel elles cèdent | | Règle | | - | ---- | | **STRICTE** | Aucune vidéo deux fois dans une même séance | | **STRICTE** | Aucune chaîne deux fois dans une même séance — le premier facteur du sentiment de « déjà-vu » | | **STRICTE** | Aucune vidéo vue à l'intérieur de `cooldownDays` | | **SOUPLE** | Pénalité de chaîne sur les deux dernières séances | | **SOUPLE** | Pénalité de style sur la dernière séance | `cooldownDays = clamp(floor(eligiblePoolSize × 0.6), 1, 14)`. Cela s'ajuste à ce que la phase peut réellement atteindre : une phase avec 15 vidéos éligibles obtient un délai de 9 jours, une avec 3 obtient 1 jour. Une constante fixe affamerait les phases étroites ou ferait à peine tourner les larges. Si une phase devait rester vide, les contraintes se relâchent **dans un ordre défini** — (1) correspondance du niveau d'expérience, (2) le délai de refroidissement, (3) plage d'intensité et variété de chaînes, (4) *pas de répétition dans la séance* — et **le plafond de sécurité ne se relâche à aucun niveau**. Le niveau 4 n'existe que pour le fil au format court, qui demande jusqu'à 26 choses distinctes là où la séance complète en demande six ; même là, le même cours n'est jamais servi sur deux cartes consécutives, seule répétition que quelqu'un remarquerait vraiment. Le plafond de longueur de carte se relâche au niveau 3 plutôt qu'au niveau 4 : le sélecteur répétera donc un cours court avant de servir un cours de 40 minutes en carte de 75 secondes. Les règles relâchées sont rapportées dans `session.rationale` et montrées à l'utilisateur, parce qu'ignorer silencieusement ses propres contraintes est la façon dont un système de recommandation pourrit. ### 6.3 L'ajustement de durée est asymétrique, exprès Une vidéo *plus longue* que son bloc ne pose pas de problème — vous pratiquez les N premières minutes et le minuteur vous fait avancer, exactement comme un cours. Une vidéo *plus courte* que son bloc vous laisse debout dans le silence, ce qui est un échec bien pire. Donc : ``` r = budget / runtime r > 1 → max(0, 1 − (r−1) × 1.25) # too short: punished hard r ≤ 1 → r ^ 0.45 # long is acceptable, not preferred ``` ### 6.4 Déterminisme La séance qu'on vous a donnée ne doit pas se remélanger en silence si vous rechargez en pleine pratique. Chaque tirage aléatoire vient d'un PRNG mulberry32 initialisé par `hash(date, profileKey, variant)`. **`variant` est la seule chose qui change la séance d'un jour**, et une seule commande l'incrémente : « Une autre séance ». ### 6.5 Pourquoi la bibliothèque est bâtie ainsi Le moteur ne peut faire tourner que ce qui existe. La bibliothèque porte donc délibérément **les mêmes ensembles canoniques enseignés par des professeurs différents** — sept enregistrements de Ba Duan Jin, six de Shibashi, huit de la forme Yang en 24. C'est là l'astuce : le *contenu* reste familier (vous apprenez une forme, pas cinquante), tandis que la *voix, le tempo et l'angle de caméra* tournent. Pratique familière, séance neuve. Cible éditoriale : **≥5 chaînes distinctes par case (phase × intensité).** --- ## 7. Planification hebdomadaire `src/lib/engine/week.ts`. Une semaine de séances identiques est le moyen le plus rapide d'arrêter, et c'est en outre un mauvais entraînement. - **Un jour long** — l'objectif propre du pratiquant, durée ×1,5, placé sur son *dernier* jour sélectionné de la semaine (souvent le week-end, souvent le seul jour avec du temps). C'est la séance où une forme s'apprend vraiment. Nécessite ≥3 jours de pratique. - **Un jour facile** — un cran d'intensité en moins, objectif basculé sur `stress`, placé en milieu de semaine. Récupération, pas trou. Nécessite ≥4 jours de pratique. - **Tout le reste** alterne entre l'objectif choisi et son complément, de sorte qu'aucune qualité n'est travaillée deux jours de suite. ``` balance ↔ strength strength → joints joints → stress stress → balance cardio → balance cognition → joints ``` - **Les jours de repos sont affichés, pas cachés.** Un jeudi vide est une décision du plan. Le sélectionner propose « Pratiquer quand même », ce qui construit à intensité réduite plutôt que de refuser. Les semaines commencent le lundi — c'est ainsi que les gens parlent de « cette semaine », et cela place le jour long naturel à la fin plutôt qu'au milieu. --- ## 8. Politique de contenu ### 8.1 Vérification Chaque entrée de `src/lib/content/videos.ts` a été contrôlée par machine avant publication : - `https://www.youtube.com/oembed?url=…` → existe, est publique, vrai titre, vraie chaîne. - la page de lecture → `lengthSeconds`, et `playableInEmbed: true`. Relancez-le avec `bun run verify:library`. **Les titres mentent constamment.** « 10 min » se pose régulièrement sur une vidéo de 14 minutes. Le champ `seconds` est toujours le nombre propre de YouTube, parce que c'est dessus que le minuteur budgète. Sur 52 candidates, **51 ont été publiées** ; une (`ILFcKMnMkPQ`) rapportait `playableInEmbed: false` et a été écartée plutôt que publiée en cadre mort. ### 8.2 Règles éditoriales pour ajouter une entrée 1. Durée réelle dans `seconds`. Jamais le nombre du titre. 2. `chairFriendly` est une **affirmation de sécurité**, pas une étiquette de confort. Vrai seulement si la vidéo est assise, ou assez lente et à posture assez étroite pour être faite en se tenant à un dossier de chaise. 3. **Ne taguez jamais une vidéo dans plus de trois phases.** Le sur-étiquetage est ainsi qu'une bibliothèque de 50 commence à ressembler à une bibliothèque de 6. 4. Visez ≥5 chaînes distinctes par case (phase × intensité). ### 8.3 Attribution et usage loyal Rien n'est hébergé, réuploadé, téléchargé ni dépouillé. Les vidéos sont intégrées via le lecteur de YouTube lui-même (hôte `youtube-nocookie`), commandes natives laissées actives, noms de chaînes affichés sur toutes les surfaces, et un lien « Regarder sur YouTube » sur chaque fiche de bibliothèque. La bibliothèque complète est publique à `/library`. Si un créateur demande à être retiré, on retire l'entrée. Pas de négociation, pas de « mais le moteur en a besoin ». ### 8.4 Défaillance élégante Des vidéos sont supprimées et les autorisations d'intégration changent. Quand le lecteur échoue, la scène se dégrade en une carte avec l'affiche, une explication et un lien externe — **et le minuteur continue de tourner.** Une iframe vide n'est jamais acceptable. --- ## 9. Périmètre de sécurité Ce que l'application fait : - Interroge la stabilité debout avant toute chose. - Impose un plafond d'intensité strict qu'aucun chemin de relâchement ne peut contourner. - Affiche les précautions au-dessus du lecteur, à chaque séance, pas une seule fois à l'installation. - Précautions universelles : arrêter en cas de douleur vive, de douleur dans la poitrine, de vertige ou d'essoufflement qui ne passe pas ; ne jamais forcer le genou au-delà de la pointe du pied ; le genou suit l'axe du pied. - Précautions conditionnelles : chaise à portée pour `supported` ; chaise ferme, sans roulettes, pieds à plat pour `seated` ; « remontez votre posture avant de raccourcir votre séance » pour modérée et au-delà. Ce qu'elle ne fait explicitement pas, et ne doit pas commencer à faire sans un clinicien dans la boucle : - Rechercher des contre-indications (chirurgie récente, événements cardiaques aigus, troubles vestibulaires, hypertension non contrôlée). - S'adapter à un diagnostic nommé. - Affirmer un résultat thérapeutique pour un individu. --- ## 10. Architecture ``` src/ app/ routes: / · /progress · /library · /method components/ brand/ mark, wordmark, lockup glass/ NightSky, Glass — the material layer ui/ shadcn primitives (extended, not forked) layout/ header, bottom tab bar, skip link, nav definition practice/ stage, timer, transport, rail, screen, full player + short-form feed, format switch progress/ rank, milestones, stats calendar/ week strip setup/ option groups, setup sheet library/ library browser hooks/ timer, session runtime, chime, wake lock, hydration gate lib/ domain/types.ts the vocabulary. Nothing decorative lives here content/ verified video registry + app-narrated guided blocks engine/ prescribe → select → week. Pure, locale-blind progress/ ranks + derived stats. Pure i18n/ detection, dictionaries (en·es·fr·de·zh), provider store/ the only persisted state docs/METHODOLOGY.md this file docs/methodology/ its translations scripts/verify-library.ts ``` **Conventions** - `lib/engine/*` et `lib/progress/*` sont purs : pas de React, pas de DOM, pas de `Date.now()` implicite, et **pas de langue**. Chaque fonction reçoit la date en argument, ce qui rend les séances reproductibles et testables, et renvoie des clés de dictionnaire plutôt que des phrases. - Un champ existe dans `domain/types.ts` seulement si une règle du moteur le lit ou si un libellé l'affiche. - Fichiers en kebab-case, exports nommés, imports directs, pas de fichiers baril. - Les composants clients sont des feuilles. `PracticeScreen` détient la date sélectionnée et le format choisi, et tout le reste en découle. - **Les deux lecteurs partagent un même runtime.** `useSessionRuntime` possède le minuteur, le carillon, le verrou d'écran, le gel du ciel nocturne et le journal, de sorte que la séance complète et le fil ne peuvent pas diverger sur ce que vous avez pratiqué — ni sur ce qui se passe si vous partez à mi-chemin, à savoir un enregistrement partiel au-delà de deux minutes et rien en deçà. ### 10.1 Le minuteur, précisément Trois décisions qui méritent d'être défendues : 1. **L'horloge est un scalaire unique.** Un nombre — les millisecondes écoulées dans toute la séance — et le bloc courant en est *dérivé* par rapport à des frontières cumulées. Avancer, revenir et faire défiler sont la même opération. Un compte à rebours par bloc séparé du total de la séance, c'est ainsi que ces deux valeurs divergent. 2. **Horloge murale, pas comptage de ticks.** L'écoulé vaut `committed + (now − startedAt)`, recalculé à chaque tick. Accumuler `+250 ms` par intervalle perd des minutes sur une séance de 45 minutes, car les onglets en arrière-plan brident fortement les minuteurs. 3. **Il survit donc à la mise en arrière-plan.** Un téléphone qui se verrouille en pleine séance reprend à l'heure correcte, pas à l'heure du verrouillage. Le minuteur est aussi la source de vérité pour la vidéo : mettre la séance en pause met YouTube en pause, et une vidéo qui atteint sa propre fin ne termine pas le bloc. --- ## 11. Lacunes connues Liste honnête. Elles ne sont pas cachées derrière un « travaux futurs ». - **Toujours pas de tests.** `prescribe`, `select`, `week` et `progress/stats` sont purs et ont été écrits pour être testables ; rien n'a été écrit. C'est de loin la plus grande lacune. - **`localStorage` uniquement.** Pas de synchronisation, pas d'export, pas d'import. Un bouton d'export/import JSON est le correctif utile le moins cher, et donnerait aussi un moyen d'emporter une année de pratique sur un nouveau téléphone. - ~~**La langue est appliquée après le montage**, donc la première image peinte est en anglais.~~ **Corrigé.** La langue est un segment de route : l'anglais est servi sans préfixe à `/library`, les quatre autres à `/fr/library` et ainsi de suite, et `` est correct dès le premier octet. Il n'y a ni correction au montage ni flash d'anglais. - ~~**Le `