Use when implementing or debugging anything that touches DOM-to-PNG rasterisation, the route SVG path, the elevation/pace chart SVG, font loading for export, or the shared component contract every theme implements. Covers snapdom usage (embedFonts, scale/dpr, the untransformed capture node), Ramer–Douglas–Peucker route simplification, lat/lng→viewport projection, and the ActivityCardProps interface.
Use when designing, editing, or adding a Carousel Post theme — the look/ideas of Trace, Ascent, Exposure, Frame, Press, Strata, the Dawn/Dusk light·dark pairing, the canvas + panels descriptor model, per-theme slide count, photo handling (filter + grain + veil + text-shadow), and the element-visibility model. Read before touching anything under theme/carousel/.
Use when working on the photo-driven theme that derives card colors from the user's uploaded background image. Covers node-vibrant v4 swatch extraction, OKLCH-based color math via culori (complementary hue rotation, lightness derivation), WCAG contrast guarantees with black/white fallback, the role-based assignment model (background / headline / body / accent / accent2 / onAccent), the five user-facing preset variants (vibrant / muted / complementary / spectrum / pure), and the greyish-photo guard. Read before touching lib/palette.ts, hooks/use-image-palette.ts, or any theme that auto-colors from a photo.
Read BEFORE adding or refactoring any CROSS-CUTTING theme concern — a new output format / aspect ratio / safe-zone, photo / colour handling shared across themes, a new global rendering knob, or anything that sits BETWEEN a theme and its rendered output. Triggers when you are tempted to wrap themes in an external component, add a mode flag that changes how a theme paints itself, scale/reposition a theme's intact output from the outside, or store theme-shaping data that some other component interprets. Captures the single-source-of-truth + no-inversion-of-control invariants, the format-aware rendering contract, and the FormatFrame anti-pattern that was removed so it is not reintroduced.
Use when adding or editing a single-card theme (the defineTheme descriptor), a theme's adjustable knobs (ParamDef specs), its capability declaration (uses/usesWhen + ThemeData narrowing), its colour or photo policy, the unified ColorScheme/ColorChoice model, or the editor category grouping. Read before touching theme/core/theme-contract.ts, theme/core/colors.ts, theme/core/params/, theme/editor/param-control.tsx, theme/editor/color-control.tsx, theme/editor/theme-params.tsx, or a theme's *_PARAMS spec.
Use when creating or editing a Remotion video for Effort — the marketing hero, a feature/tutorial walkthrough, or any new composition. Covers the shared design system under remotion/ (tokens, fonts, VideoFrame, the component kit), brand + motion conventions, fps/resolution/duration norms, how real theme components star in videos, registration in root.tsx + the catalog, the player embeds on the landing/tutorials pages, and the render/preview commands. Read before touching anything under remotion/ or the tutorial player components.
Use whenever a task involves the overall scope, build phase boundaries, or which features are in or out of MVP for the Effort activity-card app. Read this before adding any feature that could plausibly belong to Step 2 (Strava OAuth, accounts) or Step 3 (B2B events). Also useful when deciding whether a refactor or new dependency is justified at the current phase.
Best practices for Remotion - Video creation in React