Engineering
Frontend (web) guidelines
Next.js, Fumadocs, and marketing site conventions
Frontend (web) guidelines
Applies to efacts-dev (this site) and, where analogous, efacts-website.
Defaults
| Prefer | Avoid |
|---|---|
| Server Components | Client waterfalls for first paint |
| Fumadocs layouts / MDX | One-off docs chrome |
| Design.md tokens in CSS | Ad-hoc purple gradients on dense UI |
next/image + brand SVGs | Jagged unprocessed PNGs when SVG exists |
| CSS / SMIL motion | Heavy continuous JS animation |
Docs site specifics
- Content:
content/docs/**+meta.jsonsidebars - Brand chrome:
BrandLogo— orange in light, white in dark (public/brand/) - Collapsed sidebar:
CollapsedSidebarMark→ S mark - Theme:
next-themesvia Fumadocs RootProvider - Performance rule:
.cursor/rules/performance.mdc
Homepage hero
Decorative receipt path (EFactsHero) stays behind content (z-0, pointer-events-none), framed to empty margins with a content-safe CSS mask. Copy must remain readable in light and dark.
Checklist before merging UI
- Light + dark both readable
- Touch targets ≥ 44px where interactive
- No secrets in client bundles
-
npm run buildpasses - Motion honors
prefers-reduced-motion