@ssheleg/sheleg-dev 0.4.0

package/plugins/sheleg-dev/skills/frontend-performance/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: frontend-performance
+description: >-
+  Use when building or auditing web pages for performance — running PageSpeed Insights,
+  optimizing Lighthouse scores, fixing render-blocking resources, reducing bundle size,
+  improving load times, or diagnosing slow page rendering. Covers Core Web Vitals (LCP, FCP,
+  CLS, INP, TBT, Speed Index), font loading strategies, CSS animation compositing, JavaScript
+  bundle optimization, cache headers, code splitting, Content Security Policy, image
+  optimization, and the contrast and heading issues that move a Lighthouse score. Triggers -
+  "performance audit", "PageSpeed", "Lighthouse", "Core Web Vitals", "LCP", "CLS", "INP",
+  "render-blocking", "bundle size", "code splitting", "lazy loading", "cache headers",
+  "performance budget", "ускорить сайт", "медленно грузится", "оптимизация скорости", "вес
+  бандла". Not for visual design or conversion work.
+---
+
+# Frontend Performance
+
+Optimize frontend applications for maximum Lighthouse scores and real-user performance. This skill covers the technical performance layer -- for visual design, see `frontend-design`; for conversion optimization, see `landing-page-design`.
+
+## Audit Workflow
+
+1. **Measure** -- Run PageSpeed Insights or Lighthouse. Record scores and failing audits.
+2. **Diagnose** -- Map each failing audit to a specific code-level cause (see checklist below).
+3. **Prioritize** -- Fix by impact: P0 blocks rendering, P1 hurts metrics, P2 is informational.
+4. **Implement** -- Apply fixes per the reference guides.
+5. **Validate** -- `next build` (or framework equivalent) + re-run Lighthouse. Verify no regressions.
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| LCP (Largest Contentful Paint) | < 2.5s | 2.5-4.0s | > 4.0s |
+| INP (Interaction to Next Paint) | < 200ms | 200-500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | < 0.1 | 0.1-0.25 | > 0.25 |
+| FCP (First Contentful Paint) | < 1.8s | 1.8-3.0s | > 3.0s |
+| TBT (Total Blocking Time) | < 200ms | 200-600ms | > 600ms |
+| SI (Speed Index) | < 3.4s | 3.4-5.8s | > 5.8s |
+
+## Performance Checklist
+
+### Fonts (LCP, FCP)
+
+- **Self-host fonts** -- Never load from external CDNs via `<link>` tags. Use framework font optimization (`next/font/google`, `@fontsource`, etc.) to inline CSS and self-host files.
+- **Preload critical fonts** -- The font used by the LCP element must load early.
+- **Limit font families** -- Max 3 families. Each family adds ~20-50KB.
+- **Subset fonts** -- Only load needed character sets (`latin`, `latin-ext`).
+- **Use `font-display: swap`** -- Prevents invisible text during load (FOIT).
+- **Remove unused preconnects** -- If fonts are self-hosted, `preconnect` to font CDNs is dead weight.
+
+### JavaScript (TBT, FCP, LCP)
+
+- **Code split aggressively** -- Lazy-load below-the-fold sections. Only hero + nav in initial bundle.
+- **Defer third-party scripts** -- GA, analytics, chat widgets load after interactive (`afterInteractive` or `defer`).
+- **Target modern browsers** -- Set `browserslist` to avoid shipping polyfills for `Array.prototype.at`, `Object.fromEntries`, etc.:
+  ```
+  last 2 Chrome versions, last 2 Firefox versions, last 2 Safari versions, last 2 Edge versions
+  ```
+- **Tree-shake imports** -- Named imports only. No `import * as`.
+- **Analyze bundles** -- Use `@next/bundle-analyzer`, `source-map-explorer`, or `vite-plugin-visualizer`.
+
+### CSS & Animations (CLS)
+
+- **Composite-only animations** -- Only animate `transform` and `opacity` (GPU-composited). Never animate `background-position`, `width`, `height`, `top/left`, `margin`, `padding`.
+- **Use `will-change` sparingly** -- Add `will-change: transform` or `will-change: filter` only on elements that actually animate.
+- **Inline critical CSS** -- Framework should handle this (Next.js does automatically).
+- **Avoid layout shifts** -- Set explicit `width`/`height` on images and embeds. Reserve space for dynamic content.
+
+### Images (LCP, CLS)
+
+- **Use `<Image>` component** -- Framework-optimized components (`next/image`, Astro `<Image>`) auto-resize, convert to WebP/AVIF, and add `width`/`height`.
+- **Priority-load LCP image** -- Add `priority` (Next.js) or `fetchpriority="high"` to the hero/LCP image.
+- **Lazy-load below-fold** -- All images below the initial viewport get `loading="lazy"`.
+- **Size budget**: Hero < 200KB, thumbnails < 50KB, icons as SVG.
+- **Responsive `sizes`** -- Always provide `sizes` attribute for responsive images.
+
+### Caching (Repeat Visits)
+
+- **Static assets**: `Cache-Control: public, max-age=31536000, immutable` for hashed files (JS, CSS, fonts, images).
+- **HTML**: `Cache-Control: public, max-age=0, must-revalidate` (or framework default).
+- **Verify patterns** -- Test cache header `source` patterns against actual URLs. Common mistake: glob-style patterns (`{.svg,.png}`) don't work in all frameworks' path-matching (e.g., Next.js uses `path-to-regexp`). Use regex parameter syntax instead:
+  ```
+  /:path*.:ext(svg|png|jpg|jpeg|gif|webp|ico|woff|woff2)
+  ```
+
+### Content Security Policy (Best Practices)
+
+- **Whitelist all loaded origins** -- CSP blocks = console errors = lower Best Practices score.
+- **Audit after every third-party change** -- Adding analytics, fonts, or CDN scripts requires CSP updates.
+- **Tighten after migration** -- If you move from external fonts to self-hosted, remove the old CSP entries.
+- **Common CSP origins**:
+  - Google Analytics: `https://www.googletagmanager.com`, `https://www.google-analytics.com`
+  - Cloudflare: `https://static.cloudflareinsights.com`
+  - Stripe: `https://js.stripe.com`
+
+### Accessibility (Lighthouse A11y Score)
+
+These directly affect the Lighthouse Accessibility score:
+
+- **Contrast ratio** -- WCAG AA requires 4.5:1 for normal text, 3:1 for large text. Avoid opacity modifiers on text colors (e.g., `text-primary/80` in Tailwind reduces contrast). Use full-opacity color tokens.
+- **Heading hierarchy** -- Sequential: `h1` -> `h2` -> `h3`. Never skip levels. Use non-heading elements (`<p>`) for visual-only "headings" (e.g., footer column titles).
+- **Alt text** -- Decorative images next to identical text get `alt=""`. Informative images get descriptive alt. Never duplicate adjacent text.
+- **Tap targets** -- Minimum 48x48px on mobile. Applies to buttons, links, form inputs.
+
+## Framework-Specific Guides
+
+- **Next.js**: See [references/nextjs.md](references/nextjs.md) for `next/font`, `next/image`, `next/dynamic`, `next/script`, cache headers in `next.config`, CSP configuration, and bundle analysis.
+- **CSS/Animation**: See [references/css-performance.md](references/css-performance.md) for compositing rules, gradient animation alternatives, `will-change` usage, and critical CSS strategies.
+- **Accessibility**: See [references/accessibility-perf.md](references/accessibility-perf.md) for contrast calculations, heading hierarchy rules, and ARIA patterns that affect Lighthouse.
+
+## Common PageSpeed Failures & Fixes
+
+| Audit | Cause | Fix |
+|-------|-------|-----|
+| "Eliminate render-blocking resources" | External font CSS, large CSS files | Self-host fonts, inline critical CSS |
+| "Reduce unused JavaScript" | Full page bundle loaded upfront | Code-split with dynamic imports |
+| "Avoid non-composited animations" | Animating `background-position`, `width`, etc. | Replace with `transform`/`opacity`/`filter` |
+| "Serve static assets with efficient cache policy" | Missing or short `Cache-Control` headers | Set `max-age=31536000, immutable` for hashed assets |
+| "Background/foreground colors do not have sufficient contrast" | Opacity modifiers on text colors | Use full-opacity color tokens |
+| "Heading elements not in sequential order" | Skipped heading levels (h1 -> h4) | Fix hierarchy or use `<p>` for non-structural headings |
+| "Browser errors logged to console" | CSP blocking scripts/styles | Whitelist required origins in CSP |
+| "Image elements do not have [alt] attributes" | Missing or redundant alt text | Add descriptive alt, or `alt=""` for decorative |
+| "Avoid chaining critical requests" | Waterfall of blocking resources | Preload critical resources, self-host |
+| "Legacy JavaScript" | Polyfills for modern APIs | Update `browserslist` targets |
+
+## Performance Budget Template
+
+Set these limits for landing pages:
+
+| Resource | Budget |
+|----------|--------|
+| Total page weight | < 1.5 MB |
+| JavaScript (compressed) | < 200 KB |
+| CSS (compressed) | < 50 KB |
+| Fonts (total) | < 150 KB |
+| Hero image | < 200 KB |
+| LCP | < 2.5s (mobile) |
+| FCP | < 1.8s (mobile) |
+| CLS | < 0.1 |
+| TBT | < 200ms |
+
+## Related Skills
+
+- `frontend-design` -- Visual aesthetics and UI design
+- `landing-page-design` -- Conversion optimization and layout
+- `next-best-practices` -- Next.js framework patterns
+- `seo-audit` -- Technical SEO and crawlability
+- `responsive-design` -- Adaptive layouts and container queries

package/plugins/sheleg-dev/skills/frontend-performance/references/accessibility-perf.md

@@ -0,0 +1,172 @@
+# Accessibility Rules That Affect Lighthouse Score
+
+These accessibility issues are automatically detected by Lighthouse and directly reduce the Accessibility score.
+
+## Contents
+
+- [Color Contrast](#color-contrast)
+- [Heading Hierarchy](#heading-hierarchy)
+- [Image Alt Text](#image-alt-text)
+- [Interactive Element Sizing](#interactive-element-sizing)
+- [Focus Indicators](#focus-indicators)
+- [ARIA Landmarks](#aria-landmarks)
+- [Language Attribute](#language-attribute)
+
+
+## Color Contrast
+
+### WCAG AA Requirements
+
+| Text Type | Minimum Ratio | Example |
+|-----------|--------------|---------|
+| Normal text (< 18px or < 14px bold) | 4.5:1 | Body copy, labels, section headers |
+| Large text (>= 18px or >= 14px bold) | 3:1 | Headings, hero text |
+| UI components & graphical objects | 3:1 | Buttons, icons, form borders |
+
+### Common Failures in Dark Themes
+
+Dark themes are the most common source of contrast failures because designers use opacity to create visual hierarchy:
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| `text-primary/80` | 80% opacity reduces contrast below 4.5:1 | Use `text-primary` (full opacity) |
+| `text-muted-foreground/60` | 60% opacity on already-muted color | Use `text-muted-foreground` |
+| `text-white/60` on dark bg | Insufficient contrast | Use `text-white/80` minimum, test with tool |
+| `text-gray-400` on `bg-gray-900` | May or may not pass depending on exact values | Test with contrast checker |
+
+### Tailwind Opacity vs Dedicated Color Tokens
+
+**Bad (Lighthouse failure):**
+```html
+<p class="text-primary/80">Section Label</p>
+<span class="text-muted-foreground/60">Subtitle</span>
+```
+
+**Good:**
+```html
+<p class="text-primary">Section Label</p>
+<span class="text-muted-foreground">Subtitle</span>
+```
+
+If you need visual hierarchy without reducing contrast below WCAG thresholds:
+- Use `font-weight` differences (semibold vs regular)
+- Use `font-size` differences (sm vs xs)
+- Use `letter-spacing` and `uppercase` for labels
+- Use a dedicated lighter color token that still passes contrast (e.g., define `--muted-accent` that's tested for 4.5:1)
+
+### Checking Contrast
+
+Use Chrome DevTools: inspect element -> color picker shows contrast ratio against computed background.
+
+Or calculate manually: `(L1 + 0.05) / (L2 + 0.05)` where L1 is the lighter relative luminance.
+
+### Intentional Low-Contrast Exceptions
+
+Some design systems (cyberpunk, neon, etc.) intentionally use low-contrast text as an aesthetic choice (`text-cyan-400/60`, `text-white/40`). These should:
+- Be reviewed with visual testing, not bulk-replaced
+- Only be used on decorative, non-essential text
+- Never be used on actionable elements (buttons, links, form labels)
+
+## Heading Hierarchy
+
+### Rules
+
+1. **One `<h1>` per page** -- typically the main page title or hero headline.
+2. **Sequential descent** -- `h1` -> `h2` -> `h3` -> `h4`. Never skip levels.
+3. **Non-structural "headings"** use `<p>` or `<span>` -- footer column titles, sidebar labels, card subtitles are not document headings.
+
+### Common Violations
+
+| Location | Violation | Fix |
+|----------|-----------|-----|
+| Footer column titles as `<h4>` | h1 -> h2 -> h4 (skips h3) | Change to `<p class="font-semibold text-xs uppercase ...">` |
+| Multiple `<h1>` per page | Each section has its own h1 | Use `<h2>` for section titles |
+| Card titles as `<h3>` inside a section with no `<h2>` | Heading skip | Wrap cards in a section with an `<h2>` |
+
+### Screen Reader Impact
+
+Screen reader users navigate by heading level. Skipped levels break expected navigation patterns and confuse the document outline.
+
+## Image Alt Text
+
+### Decision Tree
+
+```
+Is the image decorative (purely visual, no information)?
+├── YES → alt=""
+│   Examples: background patterns, decorative borders, logos next to brand text
+└── NO → Write descriptive alt text
+    ├── Is it informative? → Describe the content
+    │   Example: alt="Dashboard showing 50% growth in monthly users"
+    ├── Is it functional (link/button)? → Describe the action
+    │   Example: alt="Download PDF report"
+    └── Is it complex (chart/diagram)? → Summarize + provide long description
+        Example: alt="Sales trend chart" + aria-describedby for details
+```
+
+### Redundancy Rule
+
+If an image appears next to text that says the same thing, the image is decorative:
+
+**Bad (screen reader announces "PrivateClawd" twice):**
+```html
+<img alt="PrivateClawd" src="/logo.svg" />
+<span>PrivateClawd</span>
+```
+
+**Good:**
+```html
+<img alt="" src="/logo.svg" />
+<span>PrivateClawd</span>
+```
+
+## Interactive Element Sizing
+
+Minimum tap target: **48x48px** (Google), **44x44px** (Apple HIG).
+
+```css
+/* Ensure minimum tap target even for small visual buttons */
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+```
+
+Adjacent tap targets need at least 8px spacing to prevent accidental taps.
+
+## Focus Indicators
+
+Lighthouse checks for visible focus indicators on interactive elements:
+
+```css
+/* Never remove focus outlines without replacement */
+:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+/* Bad -- removes accessibility */
+*:focus { outline: none; }
+```
+
+## ARIA Landmarks
+
+Ensure the page has proper landmark regions. Lighthouse checks for:
+
+- `<main>` -- one per page, wrapping primary content
+- `<nav>` -- navigation regions
+- `<header>` / `<footer>` -- page header and footer
+- `role="search"` on search forms
+
+Landmarks enable screen reader users to jump between page sections.
+
+## Language Attribute
+
+```html
+<html lang="en">
+```
+
+Always set the `lang` attribute on `<html>`. Lighthouse flags its absence. Use the correct BCP 47 language tag for the page's primary language.

package/plugins/sheleg-dev/skills/frontend-performance/references/css-performance.md

@@ -0,0 +1,180 @@
+# CSS & Animation Performance
+
+
+## Contents
+
+- [GPU-Composited Properties](#gpu-composited-properties)
+- [Gradient Animation Alternatives](#gradient-animation-alternatives)
+- [`will-change` Usage](#will-change-usage)
+- [Critical CSS](#critical-css)
+- [Layout Shift Prevention](#layout-shift-prevention)
+- [Tailwind CSS Performance](#tailwind-css-performance)
+
+## GPU-Composited Properties
+
+The browser can animate these properties on the GPU compositor thread without triggering layout or paint:
+
+| Property | GPU-composited | Use For |
+|----------|---------------|---------|
+| `transform` | Yes | Movement, scaling, rotation |
+| `opacity` | Yes | Fading in/out |
+| `filter` | Yes (most browsers) | Blur, hue-rotate, brightness |
+| `background-position` | **No** | Avoid animating |
+| `width` / `height` | **No** | Avoid animating |
+| `top` / `left` / `right` / `bottom` | **No** | Use `transform: translate()` instead |
+| `margin` / `padding` | **No** | Avoid animating |
+| `border-radius` | **No** | Avoid animating |
+| `box-shadow` | **No** | Use `opacity` on a pseudo-element instead |
+| `color` / `background-color` | **No** | Pre-render both states, animate `opacity` |
+
+Animating non-composited properties triggers layout recalculation and paint on every frame, causing jank and increasing CLS.
+
+## Gradient Animation Alternatives
+
+### Problem: Animated `background-position`
+
+```css
+/* BAD -- triggers paint on every frame */
+@keyframes gradient-shift {
+  0% { background-position: 0% 50%; }
+  50% { background-position: 100% 50%; }
+  100% { background-position: 0% 50%; }
+}
+.animate-gradient {
+  background-size: 200% 200%;
+  animation: gradient-shift 6s ease infinite;
+}
+```
+
+This is flagged by Lighthouse as "non-composited animation" because `background-position` cannot be GPU-composited.
+
+### Fix Option A: `filter: hue-rotate()` (recommended)
+
+```css
+@keyframes gradient-shift {
+  0%, 100% { filter: hue-rotate(0deg); }
+  50% { filter: hue-rotate(30deg); }
+}
+.animate-gradient {
+  animation: gradient-shift 6s ease infinite;
+  will-change: filter;
+}
+```
+
+Pros: GPU-composited, subtle color variation, minimal code change.
+Cons: Shifts all colors (not just the gradient), effect is different from background-position scrolling.
+
+### Fix Option B: Transform on pseudo-element
+
+```css
+.animate-gradient {
+  position: relative;
+  overflow: hidden;
+}
+.animate-gradient::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(to right, #a855f7, #d946ef, #a855f7);
+  background-size: 200% 100%;
+  animation: gradient-slide 6s ease infinite;
+  will-change: transform;
+  z-index: -1;
+}
+@keyframes gradient-slide {
+  0%, 100% { transform: translateX(0); }
+  50% { transform: translateX(-50%); }
+}
+```
+
+Pros: True sliding gradient, fully GPU-composited.
+Cons: More complex markup, doesn't work with `bg-clip-text`.
+
+### Fix Option C: Remove animation
+
+```css
+.animate-gradient {
+  /* Static gradient, no animation */
+}
+```
+
+Simplest fix. Use when the animation is subtle and non-essential.
+
+## `will-change` Usage
+
+`will-change` hints the browser to promote an element to its own compositor layer.
+
+**Rules:**
+- Only add to elements that actually animate
+- Remove after animation completes (for one-shot animations)
+- Never use `will-change: auto` (it's the default, useless)
+- Never apply to more than a few elements -- each promoted layer uses GPU memory
+
+```css
+/* Good -- only on animated elements */
+.animate-gradient { will-change: filter; }
+.slide-in { will-change: transform; }
+
+/* Bad -- blanket application */
+* { will-change: transform; }
+```
+
+## Critical CSS
+
+### Framework Handling
+
+Most modern frameworks handle critical CSS automatically:
+- **Next.js**: Inlines CSS for initial render via built-in optimization
+- **Astro**: Scoped styles are inlined per-component
+- **Vite/SvelteKit**: CSS is extracted and linked efficiently
+
+### Manual Optimization
+
+If the framework doesn't handle it:
+
+1. Extract CSS used by above-the-fold elements
+2. Inline it in `<style>` within `<head>`
+3. Load remaining CSS asynchronously:
+   ```html
+   <link rel="preload" href="/styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+   <noscript><link rel="stylesheet" href="/styles.css"></noscript>
+   ```
+
+## Layout Shift Prevention
+
+| Element | Fix |
+|---------|-----|
+| Images | Always set `width` and `height` attributes |
+| Embeds/iframes | Set explicit dimensions or use `aspect-ratio` |
+| Dynamic content | Reserve space with `min-height` |
+| Web fonts | Use `font-display: swap` + size-adjusted fallback |
+| Ads/banners | Reserve slot with fixed dimensions |
+| Sticky headers | Account for height with `scroll-padding-top` |
+
+### Font CLS Mitigation
+
+When fonts swap from fallback to web font, text reflows and causes CLS. Mitigate with:
+
+```css
+/* Size-adjust the fallback to match the web font */
+@font-face {
+  font-family: "Fallback";
+  src: local("Arial");
+  size-adjust: 105%;
+  ascent-override: 95%;
+  descent-override: 22%;
+  line-gap-override: 0%;
+}
+body {
+  font-family: "YourWebFont", "Fallback", sans-serif;
+}
+```
+
+`next/font` does this automatically when you use the `variable` option.
+
+## Tailwind CSS Performance
+
+- **Purge unused classes** -- Tailwind v3+ does this automatically in production. Ensure `content` paths cover all template files.
+- **Avoid runtime class generation** -- Never use string interpolation for Tailwind classes (`text-${color}-500`). Tailwind can't detect these at build time.
+- **Opacity modifiers and contrast** -- `text-primary/80` creates 80% opacity, which may fail WCAG contrast. Prefer full-opacity tokens for text, use opacity only on decorative elements.
+- **Minimize `@apply`** -- Excessive `@apply` bloats CSS. Use component composition instead.