Skip to content

notque/vexjoy-agent / skills/frontend/frontend

frontend

Unverified

Frontend: UI design, distinctive visual styles, HTML artifacts, Three.js 3D, TypeScript/React/Next.js apps, e-commerce, portfolios, React Native, web performance.

FileKindSize
SKILL.mdskill md22.5 KB
SPEC.mdmarkdown4.3 KB
agents/html-builder.mdmarkdown5.9 KB
assets/base-template.htmlother495 B
references/design-refs/accessibility-review.mdmarkdown13.0 KB
references/design-refs/design-critique.mdmarkdown10.4 KB
references/design-refs/design-handoff.mdmarkdown9.9 KB
references/design-refs/design-systems.mdmarkdown9.3 KB
references/design-refs/llm-design-failure-modes.mdmarkdown9.1 KB
references/design-refs/ux-copy.mdmarkdown9.5 KB
references/distinctive-frontend-design-refs/animation-patterns.mdmarkdown10.5 KB
references/distinctive-frontend-design-refs/background-techniques.mdmarkdown10.5 KB
references/distinctive-frontend-design-refs/balatro-shader-breakdown.mdmarkdown14.9 KB
references/distinctive-frontend-design-refs/card-shader-patterns.mdmarkdown10.9 KB
references/distinctive-frontend-design-refs/color-inspirations.jsonconfig9.4 KB
references/distinctive-frontend-design-refs/css-audit-patterns.mdmarkdown4.7 KB
references/distinctive-frontend-design-refs/font-catalog.jsonconfig9.7 KB
references/distinctive-frontend-design-refs/game-ui-polish.mdmarkdown6.3 KB
references/distinctive-frontend-design-refs/honest-placeholders.mdmarkdown3.2 KB
references/distinctive-frontend-design-refs/implementation-examples.mdmarkdown7.7 KB
references/distinctive-frontend-design-refs/macrostructure-catalog.mdmarkdown9.3 KB
references/distinctive-frontend-design-refs/oklch-color-harmony.mdmarkdown7.3 KB
references/distinctive-frontend-design-refs/performance-budgets.mdmarkdown10.6 KB
references/distinctive-frontend-design-refs/phase-details.mdmarkdown4.8 KB
references/distinctive-frontend-design-refs/pptx-conversion.mdmarkdown9.7 KB
references/distinctive-frontend-design-refs/roll-text.mdmarkdown7.2 KB
references/distinctive-frontend-design-refs/shader-integration-react.mdmarkdown16.7 KB
references/distinctive-frontend-design-refs/slide-controller.mdmarkdown9.4 KB
references/distinctive-frontend-design-refs/text-animation-patterns.mdmarkdown4.3 KB
references/html-artifact-refs/design-system.mdmarkdown10.2 KB
references/html-artifact-refs/diagram-layering.mdmarkdown3.9 KB
references/html-artifact-refs/infographic-layouts.mdmarkdown4.9 KB
references/html-artifact-refs/pdf-export.mdmarkdown6.0 KB
references/html-artifact-refs/pptx-export.mdmarkdown10.2 KB
references/html-artifact-refs/shape-diagram-illustration.mdmarkdown4.3 KB
references/nextjs-ecommerce.mdmarkdown3.4 KB
references/nextjs-ecommerce/admin-dashboard.mdmarkdown9.8 KB
references/nextjs-ecommerce/error-catalog.mdmarkdown7.9 KB
references/nextjs-ecommerce/expertise.mdmarkdown5.1 KB
references/nextjs-ecommerce/patterns-and-errors.mdmarkdown4.6 KB
references/nextjs-ecommerce/preferred-patterns.mdmarkdown8.0 KB
references/nextjs-ecommerce/shopping-cart-patterns.mdmarkdown7.7 KB
references/nextjs-ecommerce/stripe-integration.mdmarkdown9.5 KB
references/performance-optimization.mdmarkdown9.9 KB
references/performance-optimization/browser-dom-optimizations.mdmarkdown6.0 KB
references/performance-optimization/bundle-optimization.mdmarkdown7.9 KB
references/performance-optimization/core-web-vitals.mdmarkdown9.6 KB
references/performance-optimization/js-algorithm-optimizations.mdmarkdown9.6 KB
references/performance-optimization/metrics-and-monitoring.mdmarkdown8.8 KB
references/performance-optimization/nextjs-optimization.mdmarkdown10.6 KB
references/performance-optimization/performance-testing.mdmarkdown9.6 KB
references/performance-optimization/preferred-patterns.mdmarkdown7.4 KB
references/performance-optimization/react-async-patterns.mdmarkdown7.0 KB
references/performance-optimization/react-bundle-optimization.mdmarkdown6.3 KB
references/performance-optimization/react-rendering-performance.mdmarkdown12.0 KB
references/react-native.mdmarkdown4.4 KB
references/react-native/animation-patterns.mdmarkdown3.9 KB
references/react-native/error-handling.mdmarkdown7.7 KB
references/react-native/list-performance.mdmarkdown5.4 KB
references/react-native/monorepo-config.mdmarkdown2.3 KB
references/react-native/navigation-patterns.mdmarkdown2.0 KB
references/react-native/rendering-patterns.mdmarkdown3.2 KB
references/react-native/state-management.mdmarkdown3.3 KB
references/react-native/testing.mdmarkdown6.2 KB
references/react-native/ui-patterns.mdmarkdown5.0 KB
references/react-portfolio.mdmarkdown7.7 KB
references/react-portfolio/gallery-patterns.mdmarkdown2.5 KB
references/react-portfolio/image-optimization.mdmarkdown3.4 KB
references/react-portfolio/lightbox-patterns.mdmarkdown6.1 KB
references/react-portfolio/nextjs-app-router.mdmarkdown4.9 KB
references/react-portfolio/performance.mdmarkdown3.9 KB
references/react-portfolio/portfolio-seo.mdmarkdown4.8 KB
references/react-portfolio/responsive-design.mdmarkdown3.3 KB
references/threejs-builder-refs/advanced-animation.mdmarkdown12.1 KB
references/threejs-builder-refs/advanced-topics.mdmarkdown11.0 KB
references/threejs-builder-refs/build-recipes.mdmarkdown7.4 KB
references/threejs-builder-refs/game-architecture.mdmarkdown10.4 KB
references/threejs-builder-refs/game-patterns.mdmarkdown12.5 KB
references/threejs-builder-refs/gltf-loading.mdmarkdown8.6 KB
references/threejs-builder-refs/performance-patterns.mdmarkdown11.8 KB
references/threejs-builder-refs/react-three-fiber.mdmarkdown17.8 KB
references/threejs-builder-refs/shader-patterns.mdmarkdown15.0 KB
references/threejs-builder-refs/visual-polish.mdmarkdown16.3 KB
references/threejs-builder-refs/webgpu.mdmarkdown20.4 KB
references/typescript-frontend.mdmarkdown5.3 KB
references/typescript-frontend/engineering-rules.mdmarkdown7.8 KB
references/typescript-frontend/nextjs-security.mdmarkdown2.6 KB
references/typescript-frontend/react-view-transitions.mdmarkdown5.4 KB
references/ui-design.mdmarkdown10.2 KB
references/ui-design/ai-slop-detection.mdmarkdown8.5 KB
references/ui-design/design-conventions.mdmarkdown2.8 KB
references/ui-design/motion-and-interaction.mdmarkdown5.6 KB
scripts-distinctive-frontend-design/css_slop_rules.pyscript15.3 KB
scripts-distinctive-frontend-design/tests/test_css_slop_rules.pyscript6.9 KB
scripts-distinctive-frontend-design/tests/test_validate_design_advisory.pyscript3.3 KB
scripts-distinctive-frontend-design/tests/test_validate_design_macro.pyscript4.3 KB
scripts-distinctive-frontend-design/validate_design.pyscript22.2 KB
scripts-html-artifact/assemble-template.pyscript7.5 KB
scripts-html-artifact/css_slop_rules.pyscript15.4 KB
scripts-html-artifact/detect-shape.pyscript7.0 KB
scripts-html-artifact/fill-template.pyscript5.5 KB
scripts-html-artifact/pptx-bridge/__init__.pyscript490 B
scripts-html-artifact/pptx-bridge/_pptx_engine.pyscript26.4 KB
scripts-html-artifact/pptx-bridge/extract_slides.pyscript13.5 KB
scripts-html-artifact/pptx-bridge/render_pptx.pyscript6.9 KB
scripts-html-artifact/pptx-bridge/run-unified.pyscript11.6 KB
scripts-html-artifact/render-github-issues.pyscript7.5 KB
scripts-html-artifact/tests/test_assemble_template.pyscript29.5 KB
scripts-html-artifact/tests/test_css_slop_emission.pyscript7.9 KB
scripts-html-artifact/tests/test_detect_shape.pyscript5.3 KB
scripts-html-artifact/tests/test_fill_template.pyscript5.2 KB
scripts-html-artifact/tests/test_to_pdf.pyscript13.3 KB
scripts-html-artifact/tests/test_validate_artifact.pyscript13.6 KB
scripts-html-artifact/to-pdf.pyscript12.5 KB
scripts-html-artifact/validate-artifact.pyscript11.0 KB
templates/base-reset.cssother1.2 KB
templates/components/collapsible.cssother1.1 KB
templates/components/collapsible.jsscript516 B
templates/components/copy-button.cssother534 B
templates/components/copy-button.jsscript334 B
templates/components/drag-drop.cssother612 B
templates/components/drag-drop.jsscript1.1 KB
templates/components/filter.cssother1.1 KB
templates/components/filter.jsscript987 B
templates/components/keyboard-nav.cssother249 B
templates/components/keyboard-nav.jsscript900 B
templates/components/scrollytelling.cssother1.5 KB
templates/components/scrollytelling.jsscript2.0 KB
templates/components/slider.cssother848 B
templates/components/tabs.cssother770 B
templates/components/tabs.jsscript508 B
templates/components/theme-toggle.cssother1.2 KB
templates/components/theme-toggle.jsscript178 B
templates/fonts/ArchivoBlack-OFL.txtmarkdown4.4 KB
templates/fonts/archivo-black.cssother13.7 KB
templates/print/code-review-print.cssother1.9 KB
templates/print/data-viz-print.cssother1.5 KB
templates/print/deck-print.cssother1.5 KB
templates/print/default-print.cssother1.6 KB
templates/print/diagram-print.cssother1.6 KB
templates/print/editor-print.cssother2.1 KB
templates/print/prototype-print.cssother1.4 KB
templates/print/report-print.cssother1.8 KB
templates/print/spec-print.cssother1.4 KB
templates/saved/README.mdmarkdown1.8 KB
templates/saved/business-review.htmlother17.1 KB
templates/saved/business-review.slots.jsonconfig1.5 KB
templates/saved/github-issues.htmlother34.0 KB
templates/saved/project-kickoff.htmlother17.3 KB
templates/saved/project-kickoff.slots.jsonconfig1.7 KB
templates/saved/system-design.htmlother16.9 KB
templates/saved/system-design.slots.jsonconfig1.6 KB
templates/shapes/code-review.cssother2.7 KB
templates/shapes/data-viz.cssother2.3 KB
templates/shapes/deck.cssother1.9 KB
templates/shapes/diagram.cssother2.7 KB
templates/shapes/editor.cssother2.8 KB
templates/shapes/prototype.cssother2.7 KB
templates/shapes/report.cssother2.9 KB
templates/shapes/spec.cssother3.0 KB
templates/themes/birchline.cssother2.4 KB
templates/themes/dark-focus.cssother2.6 KB
templates/themes/interactive-warm.cssother4.5 KB
templates/themes/minimal-document.cssother2.6 KB

references/performance-optimization/performance-testing.md

View on GitHub
# Performance Testing Reference
<!-- Loaded via performance-optimization.md when task involves Lighthouse CI, performance budgets, regression testing, synthetic monitoring, or CI/CD performance gates -->

> **Scope**: Automated performance testing in CI/CD, Lighthouse CI setup, performance budgets, and regression detection. Does NOT cover RUM/real-user monitoring (see `metrics-and-monitoring.md`).
> **Version range**: Lighthouse CI 0.12+, @lhci/cli 0.12+
> **Generated**: 2026-04-09

---

## Overview

Synthetic performance testing in CI/CD catches regressions before they reach production. The most common failure mode is running Lighthouse manually during development and never catching performance regressions in CI — so bundle size grows 20% over 6 months with no alerts. Performance budgets with automated gates prevent this category of problem entirely.

---

## Pattern Table

| Tool | Purpose | When to Use |
|------|---------|-------------|
| `@lhci/cli` | Lighthouse CI — runs Lighthouse in CI, stores results, enforces assertions | Primary CI performance gate |
| `bundlesize` / `size-limit` | Bundle size gates — fail CI if JS bundle exceeds limit | Add alongside @lhci when bundle size is the primary concern |
| `playwright` + tracing | Real browser performance measurement with network control | Integration tests that need timing precision |
| `web-vitals` + Vitest | Unit-level performance assertions | Catching regressions in specific components |

---

## Correct Patterns

### Lighthouse CI Configuration with Assertions

`.lighthouserc.js` at repo root is the standard config location.

```javascript
// .lighthouserc.js
module.exports = {
  ci: {
    collect: {
      // Run against the built app served locally
      url: ['http://localhost:3000/', 'http://localhost:3000/products'],
      numberOfRuns: 3, // Average over 3 runs to reduce variance
      startServerCommand: 'npm run start', // Production build
      startServerReadyPattern: 'ready on',
    },
    assert: {
      // Fail CI if these thresholds aren't met
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }], // 90+ score
        'categories:accessibility': ['warn', { minScore: 0.9 }],
        'first-contentful-paint': ['error', { maxNumericValue: 2000 }], // 2s
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }], // 2.5s
        'total-blocking-time': ['error', { maxNumericValue: 300 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        // Bundle size gates via Lighthouse
        'total-byte-weight': ['error', { maxNumericValue: 1_600_000 }], // 1.6MB
        'uses-optimized-images': ['warn', {}],
        'unused-javascript': ['warn', { maxLength: 2 }], // Max 2 unused JS chunks
      },
    },
    upload: {
      target: 'temporary-public-storage', // Free LHCI storage for 30 days
      // Or: target: 'lhci', serverBaseUrl: 'https://lhci.yourcompany.com'
    },
  },
}
```

**Why**: `numberOfRuns: 3` is essential — single-run Lighthouse scores have 10-15 point variance on CI machines. Assertions use `'error'` to fail CI (not just warn). The upload step stores historical data so you can see score trends over time.

---

### GitHub Actions Workflow for Lighthouse CI

```yaml
# .github/workflows/lighthouse.yml
name: Lighthouse CI
on: [push, pull_request]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli@0.14
          lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
```

**Why**: Running `lhci autorun` reads `.lighthouserc.js` automatically. The `LHCI_GITHUB_APP_TOKEN` enables PR status checks and comments. Without it, Lighthouse results don't appear inline in PRs.

---

### size-limit for Bundle Size Gates

```javascript
// package.json
{
  "size-limit": [
    {
      "path": ".next/static/chunks/main-*.js",
      "limit": "80 kB",
      "gzip": true
    },
    {
      "path": ".next/static/chunks/pages/**/*.js",
      "limit": "50 kB",
      "gzip": true,
      "ignore": ["node_modules"]
    }
  ],
  "scripts": {
    "size": "size-limit",
    "analyze": "ANALYZE=true next build"
  }
}
```

```yaml
# Add to CI workflow
- name: Check bundle size
  run: npx size-limit --json > size-report.json
- name: Report size
  uses: andresz1/size-limit-action@v1
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
```

**Why**: `size-limit` measures gzipped output, which is what the browser actually downloads. Failing CI on bundle size regressions prevents the incremental growth pattern where no single PR is "bad" but 6 months of PRs add 150KB.

---

## Pattern Catalog

### Average Multiple Lighthouse Runs
**Detection**:
```bash
grep -rn "numberOfRuns\|number-of-runs" .lighthouserc.* .lhci* 2>/dev/null
# If no output: numberOfRuns is not configured (defaults to 1)
```

**Signal**:
```javascript
// .lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:3000'],
      // numberOfRuns missing — defaults to 1
    },
  },
}
```

**Why this matters**: A single Lighthouse run has 10-15 point score variance on CI machines (shared CPU, GC pauses, network jitter). A score of 85 one run, 72 the next — both from the same code. Single-run CI gates either false-positive (blocking good PRs) or miss real regressions.

**Preferred action**:
```javascript
collect: {
  url: ['http://localhost:3000'],
  numberOfRuns: 3, // Minimum for stable averages
},
```

---

### Use error Level for Core Performance Assertions
**Detection**:
```bash
grep -rn "largest-contentful-paint\|first-contentful-paint\|total-blocking-time" .lighthouserc.*
# Check if it uses 'warn' instead of 'error' for core metrics
```

**Signal**:
```javascript
assertions: {
  'largest-contentful-paint': ['warn', { maxNumericValue: 2500 }],
  // 'warn' doesn't fail CI — regressions ship silently
},
```

**Why it matters**: `warn` level assertions appear in logs but allow regressions to ship. LCP regressions only stop at the gate when the check fails the build.

**Preferred action**:
```javascript
assertions: {
  'largest-contentful-paint': ['error', { maxNumericValue: 2500 }], // Fails CI
  'categories:performance': ['error', { minScore: 0.9 }],
},
```

---

### Run Lighthouse Against Production Build
**Detection**:
```bash
grep -rn "next dev\|npm run dev\|yarn dev" .lighthouserc.* .github/workflows/*.yml
```

**Signal**:
```javascript
collect: {
  startServerCommand: 'npm run dev', // Development server!
},
```

**Why this matters**: `next dev` doesn't minify, doesn't split bundles, doesn't optimize images. A dev server Lighthouse score is meaningless for production performance — typically 20-40 points lower than production. You're testing the wrong artifact.

**Preferred action**:
```javascript
collect: {
  startServerCommand: 'npm run build && npm run start', // Production build
  startServerReadyPattern: 'ready on',
},
```

---

### Add Automated Bundle Size Gates to CI
**Detection**:
```bash
# Check for any bundle size monitoring
grep -rn "size-limit\|bundlesize\|bundle-size\|ANALYZE" package.json
grep -rn "size-limit\|bundlesize" .github/workflows/*.yml
# If neither exists: no automated bundle regression detection
```

**Why this matters**: Without automated bundle size gates, bundle size grows incrementally. Each PR adds "just a small dependency" until the main bundle is 500KB and LCP is 4.5s. Manual review doesn't catch this — bundle analysis is only done when performance is already bad.

**Preferred action**: Add `size-limit` with `error` thresholds to CI. Start with current bundle size as the baseline and set limits 10% above it to allow headroom, then tighten over time.

---

## Error-Fix Mappings

| Error / Symptom | Root Cause | Fix |
|-----------------|------------|-----|
| `lhci: No assertions failed but score fluctuates 15+ points` | `numberOfRuns: 1` — high variance | Set `numberOfRuns: 3` in collect config |
| `AssertionError: largest-contentful-paint failure` in CI but not local | CI machine is slower than dev machine | Increase `maxNumericValue` for CI or use percentile-based assertions |
| `Error: ECONNREFUSED` in Lighthouse CI | Server not ready when Lighthouse starts | Add `startServerReadyPattern` that matches your server's ready message |
| `lhci autorun: command not found` | `@lhci/cli` not installed | Add `npm install -g @lhci/cli` before `lhci autorun` in CI |
| size-limit reports 0KB for Next.js chunks | Glob pattern doesn't match `.next` build output | Use `.next/static/chunks/**/*.js` glob pattern |

---

## Detection Commands Reference

```bash
# Check if Lighthouse CI is configured
ls .lighthouserc.js .lighthouserc.json .lighthouserc.yaml 2>/dev/null

# Check if performance CI job exists
grep -rn "lighthouse\|lhci" .github/workflows/ 2>/dev/null

# Check numberOfRuns configuration
grep -rn "numberOfRuns" .lighthouserc* 2>/dev/null

# Check if using dev server (incorrect) vs build server (correct)
grep -rn "startServerCommand" .lighthouserc* 2>/dev/null

# Check for bundle size gates
grep -rn "size-limit\|bundlesize" package.json .github/workflows/ 2>/dev/null

# Analyze current Next.js bundle manually
ANALYZE=true next build 2>/dev/null || npx @next/bundle-analyzer 2>/dev/null
```

---

## See Also

- `metrics-and-monitoring.md` — RUM implementation for production monitoring
- `react-bundle-optimization.md` — code splitting patterns that reduce bundle size
- `nextjs-optimization.md` — Next.js-specific patterns that affect Lighthouse scores
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall