fix(react-dsfr): promote anti-flash pattern in SKILL.md#17
Open
benoitvx wants to merge 1 commit into
Open
Conversation
The dark mode flash on initial load is the most common regression
when setting up react-dsfr with Next.js App Router. The fix has
always been in references/setup.md (createGetHtmlAttributes +
getScriptToRunAsap injected in <head>) but two issues prevented
Claude from applying it:
1. The SKILL.md only mentioned the flash issue in passing, in a
"Couleurs et thème" subsection, with obsolete pre-v1.30 names
(StartDsfr, DsfrHead) and without mentioning the critical
getScriptToRunAsap script.
2. The references/setup.md Next.js App Router section showed a
layout.tsx WITHOUT the anti-flash script as step 2, then
documented the flash issue separately in a later section.
Claude reads step 2 linearly and applies the broken pattern.
Symptom confirmed in Run 2 of the eig-vibe migration test plan
(test-cadrer-20260521, 2026-05-21): generated layout.tsx had
getHtmlAttributes but no script in <head>, causing the visible
dark/light glitch.
Changes:
SKILL.md:
- New top-level "## Setup Next.js App Router" section right after
"Import pattern", with the complete minimal layout.tsx including
the anti-flash script and a clear warning that omitting
getScriptToRunAsap causes the flash.
- Listed the three critical elements (createGetHtmlAttributes,
getScriptToRunAsap, StartDsfrOnHydration) with their role.
- Documented v1.30+ names and explicitly listed obsolete names to
avoid.
- Replaced the obsolete one-liner in "Couleurs et thème" by a
short cross-reference to the new section.
- Updated the bottom "Setup par framework" pointer.
references/setup.md (Next.js App Router section):
- Moved the "flash dark mode" explanation up, before the layout
patterns.
- Reorganized into two clearly labeled patterns:
- Pattern 1 (recommended): direct imports, no transpilePackages,
anti-flash injected manually. This is the working pattern.
- Pattern 2 (variant): DsfrHeadBase + transpilePackages +
webpack rule for .woff2.
- Added a comparison table to help choose.
- Updated "Re-initialisation DSFR" section to acknowledge that
StartDsfrOnHydration handles this by default; kept the manual
DsfrStartup fallback for edge cases.
No change to skills/react-dsfr/references/components.md.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for react-dsfr to include comprehensive setup instructions for the Next.js App Router (v1.30+). It introduces two distinct setup patterns: a recommended approach using direct imports that eliminates the need for transpilePackages, and an alternative using DsfrHeadBase. The updates specifically address common issues such as the "dark mode flash" by detailing the use of createGetHtmlAttributes() and getScriptToRunAsap(), and ensure proper DOM re-initialization via StartDsfrOnHydration. I have no feedback to provide as there were no review comments.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Contexte
Le flash dark mode au chargement initial est la régression la plus courante quand on setup react-dsfr avec Next.js App Router. Le fix est déjà documenté dans
references/setup.md(createGetHtmlAttributes+getScriptToRunAsapinjecté dans<head>), mais Claude ne l'applique pas spontanément quand il génère un layout.tsx.Symptôme confirmé
Sur un test fait, je constate que le
src/app/layout.tsxgénéré contient :getHtmlAttributesest bien utilisé, mais aucun script anti-flash dans<head>. Résultat : flash visible au chargement en mode sombre.Cause racine — deux problèmes dans la skill
1. Le
SKILL.mdn'attire pas l'attention sur l'anti-flashLe
SKILL.mdne mentionnait le problème que dans une sous-section Couleurs et thème, sous cette forme :Deux soucis :
<StartDsfr />,<DsfrHead />,getHtmlAttributes()) sont les anciens noms pré-v1.30. Le package les a renommés enStartDsfrOnHydration,DsfrHeadBase,createGetHtmlAttributes— les anciens n'existent plus.getScriptToRunAsap()injecté dans<head>— n'était pas mentionné.Donc même si Claude lit cette ligne, il n'a pas le pattern correct sous les yeux.
2. Le
references/setup.mdprésente d'abord un layout casséLa section Next.js App Router de
references/setup.mdétait organisée comme ça :next.config.mjsavectranspilePackageslayout.tsx(sans script anti-flash dans<head>) ← le pattern présenté ici est cassétranspilePackages(qui contenait enfin le pattern correct avec anti-flash)Claude lit l'étape 2 linéairement, applique le code, et n'a aucune raison de descendre lire les 4 sections en dessous. La logique est inversée : le pattern correct devrait être en premier, et les variantes en dessous.
Changements
skills/react-dsfr/SKILL.md(+64 / -3 lignes)## Setup Next.js App Routeren tête, juste après Import pattern, avec :layout.tsx(Pattern 1 : imports directs, sanstranspilePackages)getScriptToRunAsap()dans<head>, le mode sombre cause un flash blanc visiblecreateGetHtmlAttributes,getScriptToRunAsap,StartDsfrOnHydrationreferences/setup.mdpour les variantesskills/react-dsfr/references/setup.md(+150 / -65 lignes)Réorganisation de la section Next.js App Router :
layout.tsxcomplet avec anti-flash, sanstranspilePackages. Le pattern qui marche, présenté en premier.DsfrHeadBase+transpilePackages+ règle webpack.woff2. Présenté comme alternative pour ceux qui ont déjàtranspilePackagespour d'autres raisons.StartDsfrOnHydration(déjà inclus dans les deux patterns) fait le boulot par défaut ; leDsfrStartupmanuel reste comme fallback pour les cas exotiques.Aucun changement sur
references/components.md, les autres frameworks (Vite, Next.js Pages Router, CRA), ou la section ESLint.Périmètre vérifié
Ces changements ne touchent que la skill
react-dsfr. Les autres skills (rgaa,securite-anssi,datagouv-apis,lasuite-ui-kit) sont intactes.Test plan
src/app/layout.tsxgénéré contient bien le<script>issu degetScriptToRunAsapdans<head>rgaasur le code généré pour vérifier que les attributs SSR (data-fr-scheme, etc.) sont bien posésSKILL.md(Header, Footer, formulaires, grille)🤖 Generated with Claude Code