メニュー
Use when Hermes writes generated Next.js app code: enforce formatting, named exports, component boundaries, route colocation, schema validation, and server action patterns.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
Use when applying, previewing, or migrating AppLoop Luma/shadcn themes: registry lookup, light/dark tokens, semantic token preservation, preview, and rollback.
Use when generating or revising AppLoop project UI: define hierarchy, responsive behavior, component map, accessibility, shadcn composition, and semantic class names.
Use when starting, restarting, inspecting, or validating an AppLoop generated project runtime: commands, logs, readiness checks, health checks, and preview-ready events.
Diagnose and recover from ORM migration state drift — when applied migrations don't match tracked state. Covers drizzle-kit + SQLite patterns, Drizzle ORM, and general SQLite schema inspection.
Use when working with AppLoop's chat checkpoint system: auto-save, git file snapshots, edit & resend, new session, DB persistence, and state restoration.
Use when AppLoop integrates with Hermes gateway streaming: session context, server-only authentication, event normalization, cancellation, and user-safe errors.
| name | generated-app-standards |
| description | Use when Hermes writes generated Next.js app code: enforce formatting, named exports, component boundaries, route colocation, schema validation, and server action patterns. |
| version | 1.0.0 |
| author | AppLoop |
| license | MIT |
| metadata | {"hermes":{"tags":["nextjs","generated-code","conventions","routes","components","schemas"],"related_skills":["frontend-design","theme-system","project-runtime"]}} |
Use this skill as the source of truth for generated-project code conventions. Apply these standards before editing and again during validation repair.
Do not use this skill to edit AppLoop builder source files.
npm run format, npm run lint, and npm run typecheck in the generated project when available.export const ComponentName = ({ prop }: Props) => { ... }.project-card.tsx exports ProjectCard.components/ folders for the route or feature that owns them.dashboard-header, dashboard-content, left-column, center-column, right-column, dashboard-footer, analytics-card, summary-card, primary-actions, and secondary-actions on user-meaningful boundaries.<body> element must carry the template classname: template-default for default, template-admin-luma for admin-luma, template-ai-engineer-cv for ai-engineer-cv, template-deep-research-paper for deep-research-paper, template-luminous-rings for luminous-rings, or template-solar-system for solar-system. Never remove or rename this classname — it identifies the template source in inspect mode and disambiguates overlapping semantic classnames between templates..map()) must have both a shared base classname (for grouping, e.g. metric-card summary-card) AND a unique per-instance descriptive classname (for precise inspect-mode identification, e.g. metric-revenue, metric-active-users). Without the unique classname, all instances appear identical in inspect mode and the user cannot target a specific one.
metric-card summary-card metric-revenue. The createSelectionPayload in inspector-provider.tsx picks the LAST classname as preferredSelector, which is the key used for multi-select toggling. If two elements share the same last classname, they collide and multi-select breaks.metric-label metric-revenue-label, metric-value metric-revenue-value, and metric-change metric-revenue-change. Template audits should reject missing className on visible elements and duplicate static last classnames.tests/generated-code-standards.test.ts) matches className="..." and className={`...`} patterns, but NOT className={cn(...)} or className={expression}. Composable UI primitives (e.g. components/ui/avatar.tsx, button.tsx) that use cn() will produce false-positive "missing className" failures. Workaround: when adding a new composable primitive to a template that uses cn(), also add its filename to the ignored Set in tests/generated-code-standards.test.ts → collectTemplateUiFiles. The ignore list already includes inspector-provider.tsx, theme-provider.tsx, button.tsx, avatar.tsx, and layout.tsx.
<any-named tags (e.g. useState<any>(...) in a .tsx file produces <any> which the regex treats as an HTML element). Avoid TypeScript generic type parameters in JSX files that the audit walks. Use typed state explicitly (useState<PlanetInfo | null>) or move the state to a non-audited file. If unavoidable, ensure the generic never contains a lowercase word like any.<mesh>, <group>, <points>, etc.) will trigger false "missing className" failures because their element names don't carry classNames. Add these template-specific three-component filenames (e.g. solar-system-scene.tsx, canvas-scene.tsx) to the ignored Set in the audit test..cv-profile-avatar-fallback) and a variant class (e.g. .cv-sidebar-avatar-fallback), and the base rule sets a property the variant must override (like background: transparent), the variant rule MUST appear AFTER the base rule in the CSS file. Both selectors have equal specificity (single class) so the last one in source order wins. If the variant appears first, the base rule silently overrides it — no warning, no error, just no visible effect. Always place variant rules after their base counterparts. (React Three Fiber, Three.js) install node_modules/. The audit walk function traverses all directories including node_modules/, picking up .tsx files from installed packages. Add if (entry.name === "node_modules") continue; inside the directory branch of collectTemplateUiFiles. Without this, node_modules/its-fine/src/index.tsx and similar files will fail the audit.data-builder-id values must be kebab-case, unique in the rendered route, and describe the boundary rather than visual styling.data-builder-component values should name the owning PascalCase component and stay out of business logic."use client" only when they use browser state, effects, refs, or event-only APIs.actions.ts, schema.ts, hooks.ts, atoms.ts, types.ts, utils.ts, and constants.ts.components/ folder under the route or an approved shared component root.export const PositionSchema = z.object({...}) plus export type Position = z.infer<typeof PositionSchema>.createPosition.data-builder-id metadata AND unique per-instance descriptive classnames.components/ folders.When an onSubmit handler is async, React's synthetic events are nulled after any await. event.currentTarget becomes null, causing Cannot read properties of null (reading 'reset').
Fix: Capture the form reference BEFORE the first await:
// CORRECT
onSubmit={async (event) => {
event.preventDefault();
const form = event.currentTarget; // ← capture before await
// ... any async calls
form.reset();
}}
// WRONG — event.currentTarget is null after await
onSubmit={async (event) => {
event.preventDefault();
const hash = await createFileSnapshot(projectId);
event.currentTarget.reset(); // ← null at this point
}}
This applies to any form handler that calls a server action, fetch, or any async operation where the form needs to be accessed afterward.
When rendering to document.body via createPortal, the call fails during server-side rendering because document is not defined.
Fix: Gate with a client-side hydration check:
const [isClient, setIsClient] = useState(false);
useEffect(() => {
setIsClient(true);
}, []);
// Only render portal after client mount
{isClient && createPortal(<Overlay />, document.body)}
This pattern is required for: inspector overlays, dropdown menus rendered at body level, tooltips, and session history panels that must escape overflow-hidden parent containers.
When a chat panel has a conversation area + sticky-bottom textarea inside a react-resizable-panels <Panel>, the conventional flex h-full flex-col layout fails because h-full requires a definite parent height, which the Panel's flex-basis percentage does not provide.
Fix: Use position: relative on the Panel and absolute inset-0 on the section, then CSS Grid for the internal layout:
<Panel className="relative">
<section className="absolute inset-0 grid grid-rows-[auto_1fr_auto]">
<div>header</div> {/* row 1: auto */}
<div className="overflow-y-auto">conv</div> {/* row 2: 1fr, scrolls */}
<form>textarea + buttons</form> {/* row 3: auto, pinned */}
</section>
</Panel>
The overflow-y-auto on the middle row handles vertical scrolling; add overflow-x-hidden to suppress horizontal scrollbars from long unbroken text.
See also: references/chat-checkpoints.md for the git-backed checkpoint and session history system, references/template-rename.md for the complete template rename/restructure workflow, references/template-theme-override.md for overriding a template's visual design from a reference website, references/cv-subpages.md for adding about-me / interview-QA subpages to the ai-engineer-cv template, references/solar-system-scene-physics.md for physically plausible solar-system orbit spacing, scale compression, Sun card behavior, and scene verification, references/template-selection-workspace-integrity.md for diagnosing generated projects that were named like one template but copied from template-default due to missing template form data, references/custom-template-authoring.md for the /projects New Template flow with editable theme CSS and DB-backed custom templates, and references/makefile-template-seeding.md for the Makefile targets to clean and seed template dependencies.
Generated project → template source sync: When the user customizes a generated project's design in the browser (AppLoop prompts, theme tweaks, manual CSS edits), those changes only exist in .apploop/projects/<slug>/. To make them permanent for new projects, copy the changed files back to the template source. Use diff first to identify which files changed, then cp them:
# Identify changes
diff templates/ai-engineer-cv/app/globals.css .apploop/projects/ai-engineer-cv/app/globals.css
# Sync all changed files back to template
cp .apploop/projects/ai-engineer-cv/app/page.tsx templates/ai-engineer-cv/app/page.tsx
cp .apploop/projects/ai-engineer-cv/app/globals.css templates/ai-engineer-cv/app/globals.css
After syncing, run npm --prefix templates/<id> run typecheck to verify. If the visual palette changed, also update defaultThemeId in lib/projects/templates.ts and register a custom theme in lib/themes/registry.ts so the Create Project modal shows the correct palette.
Generated project → template source sync: When the user customizes a generated project's design in the browser (AppLoop prompts, theme tweaks, manual CSS edits), those changes only exist in .apploop/projects/<slug>/. To make them permanent for new projects, copy the changed files back to the template source. Use diff first to identify which files changed, then cp them:
# Identify changes
diff templates/ai-engineer-cv/app/globals.css .apploop/projects/ai-engineer-cv/app/globals.css
# Sync all changed files back to template
cp .apploop/projects/ai-engineer-cv/app/page.tsx templates/ai-engineer-cv/app/page.tsx
cp .apploop/projects/ai-engineer-cv/app/globals.css templates/ai-engineer-cv/app/globals.css
After syncing, run npm --prefix templates/<id> run typecheck to verify. If the visual palette changed and the template has a custom look (dark gradients, unique accent colors), also:
lib/themes/registry.ts (use defineBuiltInTheme with a unique id)defaultThemeId in lib/projects/templates.tsapp/globals.css with the same theme idpreview object uses light-mode-consistent values (not near-black tokens), or the theme card shows black swatchesCritical pitfall — template mismatch: Each generated project was created from exactly one template.
Before syncing, check which template the project uses:
# Check the body classname in the generated project's layout
grep "template-" .apploop/projects/<slug>/app/layout.tsx
# Returns: template-default → use templates/default/
# Returns: template-admin-luma → use templates/admin-luma/
When the server is stuck after a wrong template sync:
kill $(lsof -ti:<port>)Template dependencies: Template files are independent Next.js projects with their own package.json. The standard template deps (react, next, tailwind-merge, etc.) don't require special tsconfig handling in the builder since the builder never imports from templates as modules — templates are only referenced as filesystem paths for copying. If you add a dependency to a template, the builder's tsc may fail; exclude templates/ from tsconfig.json temporarily and remove the exclude once the dependency is removed.
Generated projects use Next.js 16 with Turbopack. File changes written by external tools (Hermes prompts, the builder's file operations) may not be detected by Turbopack's native file system watcher (FSEvents/inotify). The symptom: globals.css is modified on disk, but the compiled CSS bundle hash never changes — the page still serves the old hash even after file touches or HMR pings.
Fix — layer 1 (preventative): Add CHOKIDAR_USEPOLLING=true to the dev script in the template's package.json:
"scripts": {
"dev": "CHOKIDAR_USEPOLLING=true next dev"
}
This forces polling (1s interval) instead of native OS events. New projects get this automatically; existing projects need the script updated or recreation.
Fix — layer 2 (recovery when polling didn't catch it): Even with CHOKIDAR_USEPOLLING, some file changes go undetected — touch on the file and browser reload don't help. The hash stays stale. Kill and restart the dev server:
kill $(lsof -ti:<port>) # e.g. kill $(lsof -ti:3100)
cd .apploop/projects/<slug> && CHOKIDAR_USEPOLLING=true npx next dev -p <port>
A clean kill+restart (new process) forces Turbopack to re-read all source files and rebuild the CSS chunks. This works in most cases without deleting .next/.
Fix — layer 3 (last resort): If kill+restart still serves the old hash, clear the build cache and restart:
kill $(lsof -ti:<port>)
rm -rf .apploop/projects/<slug>/.next
cd .apploop/projects/<slug> && CHOKIDAR_USEPOLLING=true npx next dev -p <port>
Verification — browser-side: Don't rely on curl alone. Check whether CSS rules are actually loaded in the browser:
// Check if new rules exist in any stylesheet
[...document.styleSheets].some(sheet => {
try { return [...sheet.cssRules].some(r => r.selectorText?.includes('.dashboard-page-header')) }
catch(e) { return false }
})
// Or verify computed styles directly
getComputedStyle(document.querySelector('.dashboard-page-header')).backgroundImage
If the rule is on disk but missing from browser stylesheets, the hash is stale — proceed to layer 2.
The preview area preview-frame.tsx has three overlay states that should all use dark backgrounds (bg-black or bg-black/80) to match the preview iframe's default dark theme:
bg-black/80 with centered spinner + "Loading preview" textbg-black with error messagebg-black with status messageDo not use bg-white — it flashes bright white during loading and clashes with the dark preview area.
When theming admin-luma headers with a color (gold, blue, etc.), use the paired sidebar-primary tokens — they provide the header background and a matching contrasting text color in both light and dark modes:
.admin-header-inner {
background: var(--sidebar-primary); /* colored bg */
}
.admin-brand,
.admin-nav a {
color: var(--sidebar-primary-foreground); /* contrasting text */
}
.theme-toggle {
border: 1px solid color-mix(in oklch, var(--sidebar-primary-foreground) 25%, transparent);
background: color-mix(in oklch, var(--sidebar-primary-foreground) 8%, transparent);
color: var(--sidebar-primary-foreground);
}
/* hover: subtle tint visible on the colored bg */
.admin-nav a:hover {
background: color-mix(in oklch, var(--sidebar-primary-foreground) 18%, transparent);
color: var(--sidebar-primary-foreground);
}
The --sidebar-primary / --sidebar-primary-foreground pair is designed for contrast in both light and dark modes (e.g., amber theme: gold bg + near-white text in light mode, brighter gold bg + dark brown text in dark mode). Always use this pair — never mix --sidebar-primary background with --sidebar-foreground or --foreground text, as those tokens are not paired for the same background.
The admin-luma template's .admin-header in dark mode can be nearly invisible because it blends into the dark gradient background. Fix with explicit contrast:
.admin-header {
border-bottom: 1px solid color-mix(in oklch, var(--sidebar-foreground) 12%, transparent);
background: color-mix(in oklch, var(--sidebar) 92%, var(--background));
backdrop-filter: blur(18px);
}
The .theme-toggle also needs a visible border and wider width:
.theme-toggle {
min-width: 7rem;
border: 1px solid color-mix(in oklch, var(--sidebar-foreground) 15%, transparent);
font-size: 0.8125rem;
font-weight: 600;
}
These changes ensure the header strip and toggle button are always distinguishable from the dark background, in both light and dark modes.
This applies to ANY template section using a hardcoded dark gradient — sidebars, headers, footers, cards, heroes. When a container has a fixed dark background, nested text and controls MUST use explicit hardcoded values for readability — oklch(...) or color-mix(in oklch, white N%, ...). Theme tokens like var(--muted-foreground) disappear on dark surfaces.
The user will say "still light" or "nested contrast should allow readability" until you stop using theme tokens inside dark-gradient containers. This is a FIRST-ATTEMPT rule.
/* Dark container: hardcoded gradient */
.dark-card {
background: linear-gradient(135deg, oklch(0.105 0.065 268), oklch(0.035 0.035 250));
}
/* ALL nested text needs explicit contrast */
.dark-card .title { color: oklch(0.985 0.008 255); }
.dark-card .label { color: color-mix(in oklch, white 78%, oklch(0.7 0.12 260)); }
.dark-card .icon { color: color-mix(in oklch, white 48%, transparent); }
.dark-card .tag { border-color: color-mix(in oklch, white 16%, transparent); color: color-mix(in oklch, white 82%, oklch(0.65 0.02 260)); }
.dark-card .button { background: linear-gradient(135deg, oklch(0.62 0.21 286), oklch(0.66 0.2 238)); color: white; }
Never use var(--muted-foreground) or bare var(--foreground) in dark gradient containers. Use 48-88% white mixes for text/icons/borders. Hardcoded values survive theme toggles.
When Hermes applies CSS or JS changes to a generated project, Turbopack may serve stale compiled output even with CHOKIDAR_USEPOLLING. Use a cache-bust query parameter on the iframe URL, NOT a runtime restart. Restarting the runtime (restartRuntimeAction) allocates a new port but doesn't always update projects.preview_port, creating a mismatch where the iframe loads a dead URL.
// builder-shell.tsx — after each Hermes response
const [previewReloadKey, setPreviewReloadKey] = useState(0);
useEffect(() => {
if (chat.status === "ready" && prevStatusRef.current === "streaming") {
setPreviewReloadKey((k) => k + 1);
}
prevStatusRef.current = chat.status;
}, [chat.status, projectId]);
// Pass to PreviewFrame: <PreviewFrame reloadKey={previewReloadKey} ... />
// preview-frame.tsx — append to iframe src
const frameSrc = `${buildPreviewFrameSrc(previewUrl, route)}${route.includes("?") ? "&" : "?"}_t=${reloadKey}`;
The ?_t=N parameter changes after every Hermes response, forcing the browser to bypass its cache and fetch fresh CSS/JS. Combined with CHOKIDAR_USEPOLLING=true for file watching, this reliably picks up all file changes without port issues. The reloadKey is different from the iframe's React key prop — the key forces a remount, while _t forces a fresh HTTP fetch even within the same iframe instance.
Inspector overlays in the preview area must remain visible and unclipped. The overlay renders inside the preview-viewport-frame div (which has position: relative and NO overflow-hidden).
Key CSS rules for the label:
.preview-selection-overlay {
position: absolute;
left: var(--selection-x);
top: var(--selection-y);
width: var(--selection-width);
height: var(--selection-height);
border: 2px dashed var(--accent);
box-shadow: 0 0 0 9999px rgba(32, 31, 27, 0.08);
}
.preview-selection-label {
position: absolute;
right: 0; /* anchor to right edge — extends left, never clipped on the right */
top: 0;
translate: 0 calc(-100% - 4px); /* position above the element */
display: inline-grid; /* sizes to content, not parent width */
width: max-content; /* expand to fit longest text */
white-space: nowrap; /* never wrap into narrow columns */
max-width: min(22rem, calc(100vw - 2rem));
background: var(--foreground);
color: var(--background);
}
Do NOT use portal + fixed positioning for the overlays — it causes them to float above the page without scrolling, and requires frameRect offset math. Keep them inside the preview-viewport-frame with position: absolute so they scroll naturally with the preview content. Tracking updates (every 100ms from inspector-provider.tsx) update the --selection-* CSS custom properties via updateSelectedElementRect in the store.
The preview-viewport-frame must NOT have overflow-hidden — it was removed because the overlay label (translate: 0 calc(-100% - 4px)) extends above the selection box and would be clipped. The outer parent's overflow-auto still clips but has pt-14 (56px) top padding to give the label breathing room.
When rendering to document.body via createPortal (e.g., session history dropdowns, tooltips), the call fails during server-side rendering because document is not defined.
Fix: Gate with a client-side hydration check:
const [isClient, setIsClient] = useState(false);
useEffect(() => {
setIsClient(true);
}, []);
// Only render portal after client mount
{isClient && createPortal(<Dropdown />, document.body)}
This pattern is required for session history dropdowns and any UI that must escape overflow-hidden parent containers. It was also tried for inspector overlays but later reverted — the overlays work better inside the preview container (see Selection Overlay CSS Patterns above).
The preview area needs enough top padding so that selection labels (positioned above elements) are not clipped by the container's overflow. The current value is pt-14 (56px) on the outer flex container. If labels are still clipped, increase to pt-16 or pt-20. Do not add overflow-hidden to the preview-viewport-frame — it clips the labels.