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.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
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回のみ使用すること
