Complete workflow for migrating static HTML pages to Next.js App Router page.tsx in the QA_Studies project. Covers CSS variable mapping (HTML vars to Tailwind v4 @theme tokens), page-specific CSS extraction, Header.tsx navigation updates, and CLAUDE.md documentation. Extends the global html-to-nextjs-migration skill with project-specific knowledge including font loading via next/font/google, design token alignment, and accessibility patterns.
Complete workflow for migrating static HTML pages to Next.js App Router page.tsx in the QA_Studies project. Covers CSS variable mapping (HTML vars to Tailwind v4 @theme tokens), page-specific CSS extraction, Header.tsx navigation updates, and CLAUDE.md documentation. Extends the global html-to-nextjs-migration skill with project-specific knowledge including font loading via next/font/google, design token alignment, and accessibility patterns.
QA_Studies HTML → Next.js Migration Workflow
Goal
Provide the complete, ordered workflow for converting a standalone HTML page (with embedded <style>) into a fully integrated Next.js App Router page within the QA_Studies project. This skill extends the global html-to-nextjs-migration skill (JSX pitfalls) with project-specific CSS token mapping, file organization, and integration steps.
Prerequisite: The global skill covers <pre> block conversion, class/className rules, HTML entity handling, @layer priority, and cache invalidation. This skill assumes that knowledge and focuses on the end-to-end workflow.
Before writing any code, read the source HTML and extract:
CSS Custom Properties — List all :root variables (colors, fonts, radii, shadows)
Unique Component Classes — Classes not present in app/globals.css (page-specific UI)
Font Families — Check if fonts match layout.tsx (Noto Sans JP, JetBrains Mono, DM Sans). layout.tsx assigns --font-display to DM Sans, --font-body to Noto Sans JP, --font-mono to JetBrains Mono. If the HTML uses different fonts (e.g., Playfair Display, Plus Jakarta Sans, Sora), note these as needing replacement with these project fonts
Animation Keyframes — List all @keyframes names; rename camelCase to kebab-case
Sections / IDs — Map the HTML structure to plan the page.tsx component tree
Phase 2: CSS Variable Mapping
Map every HTML CSS variable to the project's globals.css@theme token. Do NOT define HTML-local variables in the project.
Critical: The project uses a unified dark theme. Light-theme HTML pages must be re-themed to match the dark color system. Do not attempt to preserve the original light color scheme.
Phase 3: Create Page-Specific CSS File
Create app/<page-name>.css for styles unique to this page
Do NOT use @layer components — use plain CSS selectors for proper specificity over Tailwind preflight
Replace all HTML-local CSS variables with project @theme tokens (with fallbacks)
Rename keyframes from camelCase to kebab-case (e.g., fadeUp → fade-up)
Place @keyframes definitions that are page-specific in the page CSS, not globals
Import the CSS at the top of the page component: import '../<page-name>.css';
CSS Pitfalls Checklist (learned from code reviews)
Also recalculate the overall coverage percentage (--coverage CSS variable and the <span> displaying the % value) to reflect the updated tested/total page count.
Phase 6: Verification
Build Verification
rm -rf .next && bun run build
Common build failures:
Unclosed JSX tags
class not converted to className in JSX (keep class inside dangerouslySetInnerHTML)
Never import external fonts via <link> tags — Use next/font/google in layout.tsx only. If a new font is needed, add it to layout.tsx with a CSS variable
Never define duplicate CSS variables in page CSS that already exist in globals.css @theme
Never use @layer components for page-specific styles — plain CSS only for proper specificity
Never duplicate z-index in CSS when Tailwind class is used in JSX
Never place responsive overrides outside @media queries
Never use camelCase for @keyframes names — use kebab-case
Pages are server-rendered — no useState, useEffect, or client-side interactivity unless explicitly needed (use 'use client' directive)
Always update Header.tsx and CLAUDE.md when adding a new page
Always use fallback values for CSS vars that may not be defined: var(--radius-DEFAULT, 12px)
Never use {"\n"} for line breaks inside .code-block — .code-block の white-space はデフォルト normal のため {"\n"} はスペースに正規化される。各行を <div className="code-line">...</div> でラップすること（.code-line には white-space: pre が定義済み）
Never align tabular data with spaces in .code-block — デシジョンテーブルや行列データはフォント変更で列ズレが起きるため <table> 要素を使うこと
Never remove page-specific anchor nav bars — ページ固有のスティッキーナビ（IntersectionObserver 付き）はグローバル Header と別物。'use client' コンポーネントとして移行し top: 60px を設定すること
Never duplicate page scope classes in CSS selectors — .page-class .alert.page-class .green ではなく、.page-class .alert.green のようにページクラスは最上位の1回のみ使用すること
