cocktail.glass CLAUDE.md

cocktail.glass

Stack

• Astro 6 static site, deployed to Cloudflare Pages
• No JS framework — vanilla inline scripts with is:inline. One exception: src/components/WebMcp.astro is a bundled module (no is:inline) because it imports the shared cocktail-tools.mjs tool module, and inline scripts cannot import.
• Pagefind for search (custom UI, not PagefindUI)
• cocktail-tools.mjs (repo root) holds the seven MCP tool definitions and matching logic. Both the remote MCP server (functions/mcp.js) and the in-browser WebMCP integration import it — change a tool in one place.

HTML principles

• Minimize attributes per element. Avoid adding classes when the element can be targeted by its position in the DOM (e.g., .grid > a > h3 instead of .card-name on every card).
• Don't add data- attributes that duplicate information derivable from the DOM tree (e.g., don't put data-category on every card when the parent section already has it).
• Use is:global styles instead of Astro's scoped styles for pages with many repeated elements — scoped styles add a data-astro-cid-* attribute to every element, which adds significant weight at scale (saved ~155KB on the homepage with 500 cards).
• Scope bare element selectors (e.g., header, h1) to a parent class when using is:global to prevent them bleeding into the layout.

CSS principles

• Prefer cascading selectors over class-per-element. Inside a known structure like .grid > a, target children by element type and position rather than adding classes.
• When converting from scoped to global styles, remove :global() wrappers — they create broken double-global selectors inside <style is:global>.
• Use scroll-margin-top on anchor targets to account for the sticky header.

Performance

• Only the first 4 images in the homepage grid are eager-loaded (loading="eager", fetchpriority="high"). The first image is also preloaded via <link rel="preload">.
• JSON-LD schema and search overlay JS are in the footer, after visible content.
• System font stack for body text (--font-sans), custom font only for display headings (Playfair Display). Only the latin subset is loaded.
• Homepage is ~526KB raw / ~54KB gzipped with 500 cocktail cards.
• Use content-visibility: auto on category sections for render performance.