Imported from edmundlzen/flux (
packages/renderer/AGENTS.md). Install upstream withnpx skills add edmundlzen/flux --skill renderer. Copyright stays with the author.
Renderer Guidance
This file applies to packages/renderer/.
@flux/renderer is a Next.js static-export site renderer. It consumes the validated
combined site.config.json from @flux/config-schema. It is the production
renderer for previews, paid builds, and revisions.
Rendering Paths
layout.template === "cafe"uses the bespoke cafe composition.- Other templates use
renderSections()andsectionRegistry. - Keep the cafe composition until premium registry variants reach visual parity and the user signs off.
- Unknown section variant names must resolve to the section default.
Tailwind Contract
Use Tailwind for components and template pages. Prefer semantic token utilities:
bg-background,bg-surface,bg-primarytext-foreground,text-muted,text-primary-foreground,text-accentborder-borderfont-heading,font-bodypy-section,gap-gap- named
z-*utilities duration-[var(--duration)]andease-[var(--easing)]
Theme config becomes CSS variables through themeToCssVars() and is attached to
<html>. That inline variable map is intentional; ordinary component styling
should not use inline styles.
Use cn() for conditional classes and CVA for reusable component variants. Keep
Tailwind classes statically discoverable. Do not generate class names from runtime
strings.
Fixed black, white, or neutral treatments are only appropriate for image scrims and guaranteed inverse contrast. Never place white overlay text directly on an image without a dark scrim.
Variant Quality Contract
Every section variant:
- Accepts
SectionVariantProps. - Uses the provided tone.
- Handles absent content safely.
- Works at 375, 768, and 1280 pixels without horizontal overflow.
- Uses uniform media framing and
object-cover. - Uses configured button radius and shared button behavior.
- Provides a working burger for navbar variants below
md. - Ties motion to
theme.motionand respects reduced motion. - Produces zero console, page, and hydration errors.
Do not use suppressHydrationWarning to hide application mismatches.
Theming Gaps
Do not assume theme coverage is complete:
- Colors, fonts, type scale, radius, section spacing, motion, and layers are wired.
- Button, card, and navbar config are consumed.
- Input, float, and modal config do not have rendered primitives yet.
- Several shadow utilities remain fixed design-system choices.
- Registry compositions use automatic positional tones from
normalizeComposition().
Improve token consumption when touching these areas.
Generated Output
Do not hand-edit .next/, out/, dist/, or screenshots. Change source and rebuild.
Fonts must remain bundled through Fontsource packages; production builds must not
depend on downloading Google Fonts.
Verification
The renderer scripts compile the schema automatically:
npm run lint -w @flux/renderer
npm run test:e2e -w @flux/rendererPlaywright currently checks the configured render, mobile menu operation, reduced motion, horizontal overflow, console and hydration errors, and screenshots at all three breakpoints. Add focused tests as the variant library grows.