claude-code-mastery-project-starter-kit: Skill for Claude Code

Web Performance: Decide It Up Front

Performance is an architecture decision made at the start, not a cleanup pass at the end. The first question for anything user-facing is: what does the user need to see and interact with first, and what can wait. Build to that split. Loading everything eagerly and optimizing later is the expensive path, and it's the one Claude defaults to.

Split first paint from later, and load each accordingly

Sort every resource into two buckets and treat them differently:

• Critical, needed for first paint (above the fold, the main content and its styles): put it in the initial HTML, inline the critical CSS (see css-structure), preload the largest image and the one critical font.
• Later (below the fold, interactions, secondary features, third-party): defer it. Lazy-load below-fold images and iframes natively with loading="lazy", no JavaScript library or IntersectionObserver needed, the browser handles it, and on an iframe it defers heavy third-party embeds like maps and video players too. Then defer or async non-critical scripts, dynamic-import offscreen components and routes, and load analytics and third-party tags late and async.

Don't let CSS or JS block first paint

CSS is render-blocking: a single large stylesheet delays the first paint until it's downloaded and parsed. Inline the above-the-fold slice and load the rest without blocking (<link rel="preload" as="style" onload="this.rel='stylesheet'">, or a media swap). A <script> in <head> without defer blocks HTML parsing; use defer (runs after parse, in order) or async (independent scripts), or put scripts at the end of <body>. Keep the number of render-blocking requests small.

The LCP element gets priority and is never lazy-loaded

The Largest Contentful Paint is usually the hero image or headline above the fold, and it's the metric users feel as "has it loaded yet." Preload it, mark it fetchpriority="high", and serve it correctly sized and compressed. Do NOT put loading="lazy" on it, that's a common mistake that delays the very thing LCP measures. Lazy-loading is for everything below the fold, not the first thing on screen.