Initial commit with translated description
This commit is contained in:
43
SKILL.md
Normal file
43
SKILL.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: Web Development
|
||||
description: "使用HTML、CSS、JavaScript、现代框架和生产最佳实践构建、调试和部署网站。"
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Need | See |
|
||||
|------|-----|
|
||||
| HTML/CSS issues | `html-css.md` |
|
||||
| JavaScript patterns | `javascript.md` |
|
||||
| React/Next.js/frameworks | `frameworks.md` |
|
||||
| Deploy to production | `deploy.md` |
|
||||
| Performance/SEO/a11y | `performance.md` |
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **DOCTYPE matters** — Missing `<!DOCTYPE html>` triggers quirks mode; layouts break unpredictably
|
||||
2. **CSS specificity beats cascade** — `.class` overrides element selectors regardless of order
|
||||
3. **`===` not `==`** — Type coercion causes `"0" == false` to be true
|
||||
4. **Async/await in loops** — `forEach` doesn't await; use `for...of` or `Promise.all`
|
||||
5. **CORS is server-side** — No client-side fix; configure `Access-Control-Allow-Origin` on the server
|
||||
6. **Responsive = viewport meta** — Without `<meta name="viewport">`, mobile renders desktop-width
|
||||
7. **Form without `preventDefault`** — Page reloads; call `e.preventDefault()` in submit handler
|
||||
8. **Images need dimensions** — Missing `width`/`height` causes layout shift (CLS penalty)
|
||||
9. **HTTPS or blocked** — Mixed content (HTTP resources on HTTPS pages) gets blocked by browsers
|
||||
10. **Environment variables leak** — `NEXT_PUBLIC_*` exposes to client; never prefix secrets
|
||||
|
||||
## Common Requests
|
||||
|
||||
**"Make it responsive"** → Mobile-first CSS with media queries; test at 320px, 768px, 1024px
|
||||
**"Deploy to production"** → See `deploy.md` for Vercel/Netlify/VPS patterns
|
||||
**"Fix CORS error"** → Server must send headers; proxy through same-origin if you can't control server
|
||||
**"Improve performance"** → Lighthouse audit; focus on LCP, CLS, FID; lazy-load below-fold images
|
||||
**"Add SEO"** → Title/description per page, semantic HTML, OG tags, sitemap.xml
|
||||
|
||||
## Framework Decision Tree
|
||||
|
||||
- **Static content, fast builds** → Astro or plain HTML
|
||||
- **Blog/docs with MDX** → Astro or Next.js App Router
|
||||
- **Interactive app with auth** → Next.js or Remix
|
||||
- **Full SSR/ISR control** → Next.js
|
||||
- **Simple SPA, no SEO needed** → Vite + React/Vue
|
||||
6
_meta.json
Normal file
6
_meta.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"ownerId": "kn73vp5rarc3b14rc7wjcw8f8580t5d1",
|
||||
"slug": "web",
|
||||
"version": "1.0.0",
|
||||
"publishedAt": 1771082933366
|
||||
}
|
||||
35
deploy.md
Normal file
35
deploy.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Deployment Patterns
|
||||
|
||||
## Platform Comparison
|
||||
|
||||
| Platform | Best for | Gotchas |
|
||||
|----------|----------|---------|
|
||||
| Vercel | Next.js, serverless | Cold starts; limited to 10s (Hobby) or 60s (Pro) for functions |
|
||||
| Netlify | Static + serverless | Functions timeout at 10s (free) / 26s (paid) |
|
||||
| Cloudflare Pages | Static + Workers | Workers have no Node APIs; use `node-compat` flag |
|
||||
| VPS (Docker) | Full control, long-running | You manage SSL, updates, scaling |
|
||||
| Railway/Render | Docker apps | Sleep after inactivity on free tier |
|
||||
|
||||
## Common Deploy Issues
|
||||
|
||||
- **Build fails locally works** — Check Node version matches; use `.nvmrc` or `engines` in package.json
|
||||
- **Environment variables missing** — Platform dashboards don't auto-sync; redeploy after adding vars
|
||||
- **Static export breaks API routes** — `next export` is static only; use Vercel/custom server for API routes
|
||||
- **Trailing slashes** — Configure consistently; `/about` vs `/about/` causes duplicate content/redirects
|
||||
|
||||
## DNS Setup
|
||||
|
||||
1. **Add A record** — Point `@` to platform IP (or use CNAME for subdomains)
|
||||
2. **Add CNAME for www** — Point `www` to apex or platform domain
|
||||
3. **Wait for propagation** — Up to 48h but usually minutes; check with `dig` or online tools
|
||||
4. **SSL auto-provisions** — Most platforms handle Let's Encrypt; may take a few minutes after DNS resolves
|
||||
|
||||
## Deployment Checklist
|
||||
|
||||
- [ ] Environment variables set in platform dashboard
|
||||
- [ ] Build command correct (`npm run build`, not `npm start`)
|
||||
- [ ] Output directory correct (`out`, `.next`, `dist`)
|
||||
- [ ] Domain DNS configured and propagated
|
||||
- [ ] HTTPS working (check certificate valid)
|
||||
- [ ] 404 page configured
|
||||
- [ ] Redirects for old URLs if migrating
|
||||
27
frameworks.md
Normal file
27
frameworks.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Framework Patterns and Traps
|
||||
|
||||
## React
|
||||
|
||||
- **State updates are async** — `setState(x)` doesn't immediately change state; use callback form for derived state
|
||||
- **Keys must be stable** — Don't use array index as key if list reorders; causes bugs with forms/animations
|
||||
- **useEffect dependencies** — Missing deps cause stale closures; ESLint exhaustive-deps catches these
|
||||
- **useEffect cleanup** — Return cleanup function for subscriptions/timers; prevents memory leaks
|
||||
- **Conditional hooks** — Hooks can't be in conditions/loops; breaks React's hook order tracking
|
||||
- **Context rerenders** — Every consumer rerenders when context value changes; memoize or split contexts
|
||||
|
||||
## Next.js (App Router)
|
||||
|
||||
- **Server vs Client Components** — Default is server; add `"use client"` for hooks, browser APIs, events
|
||||
- **`fetch` in Server Components** — Automatically deduped and cached; use `{cache: 'no-store'}` for fresh
|
||||
- **Middleware runs on edge** — No Node APIs; limited to Web APIs and edge-compatible packages
|
||||
- **Route handlers** — Export `GET`, `POST` functions from `route.ts`; not `page.tsx`
|
||||
- **`revalidatePath`/`revalidateTag`** — Call after mutations to bust cache; ISR invalidation
|
||||
- **Parallel routes** — Use `@folder` convention for loading multiple routes in same layout
|
||||
- **`NEXT_PUBLIC_` prefix** — Required for env vars in client code; others are server-only
|
||||
|
||||
## General SPA
|
||||
|
||||
- **Hydration mismatch** — Server and client must render identically on first pass; use `useEffect` for client-only
|
||||
- **Bundle size** — Tree-shaking needs ES modules; named imports from lodash don't tree-shake without lodash-es
|
||||
- **Code splitting** — Use `lazy()` or `next/dynamic` for below-fold components; improves LCP
|
||||
- **SSR data fetching** — Fetch on server to avoid waterfalls; don't fetch in useEffect for initial data
|
||||
24
html-css.md
Normal file
24
html-css.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# HTML/CSS Patterns and Traps
|
||||
|
||||
## HTML
|
||||
|
||||
- **Semantic elements for SEO/a11y** — Use `<main>`, `<article>`, `<nav>`, `<header>`, `<footer>`; screen readers depend on them
|
||||
- **`<button>` vs `<a>`** — Buttons for actions, anchors for navigation; mixing breaks keyboard/screen reader UX
|
||||
- **`<img alt="">`** — Decorative images need empty alt (not missing); screen readers announce filename otherwise
|
||||
- **Self-closing tags** — In HTML5, `<br/>` works but `<br>` is canonical; `<div/>` is WRONG (not self-closing)
|
||||
- **ID must be unique** — Duplicate IDs break `querySelector`, labels, and ARIA; use classes for styling
|
||||
- **`<input type="number">`** — Allows `e`, `+`, `-` characters; validate server-side for real numbers
|
||||
- **Hidden content still in DOM** — `display: none` hides from screen readers; `visibility: hidden` doesn't remove from flow
|
||||
|
||||
## CSS
|
||||
|
||||
- **`margin: auto` needs width** — Won't center without explicit `width` or `max-width` on block elements
|
||||
- **`z-index` needs position** — Only works on positioned elements (`relative`, `absolute`, `fixed`, `sticky`)
|
||||
- **Flexbox gap support** — `gap` works in flexbox in all modern browsers; no need for margin hacks
|
||||
- **Grid auto-fit vs auto-fill** — `auto-fit` collapses empty tracks; `auto-fill` preserves them
|
||||
- **`100vh` on mobile** — Includes address bar; use `100dvh` or JS for true viewport height
|
||||
- **`:focus-visible`** — Shows focus ring only for keyboard users; cleaner than removing `:focus` outlines
|
||||
- **Cascade layers** — `@layer` controls specificity across files; newer than `!important` hacks
|
||||
- **Custom properties scope** — CSS variables cascade; define on `:root` for global, on element for local
|
||||
- **`calc()` whitespace** — `calc(100% -20px)` fails; needs spaces: `calc(100% - 20px)`
|
||||
- **Transform origin** — Default is center; for corner rotations, set `transform-origin: top left`
|
||||
35
javascript.md
Normal file
35
javascript.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# JavaScript Patterns and Traps
|
||||
|
||||
## Type Coercion
|
||||
|
||||
- **`==` vs `===`** — Always use `===`; `"0" == false` is true, `"0" === false` is false
|
||||
- **`typeof null`** — Returns `"object"` (bug from JS v1); check with `=== null`
|
||||
- **`NaN !== NaN`** — Use `Number.isNaN()` not `=== NaN`
|
||||
- **Array in boolean context** — Empty array `[]` is truthy; check `.length` for emptiness
|
||||
|
||||
## Async
|
||||
|
||||
- **`forEach` doesn't await** — Use `for...of` loop or `Promise.all(arr.map(async...))` for parallel
|
||||
- **Unhandled rejection** — Always `.catch()` or wrap in try/catch; uncaught rejections crash Node
|
||||
- **`async` function returns Promise** — Even if you return a value, caller gets a Promise
|
||||
- **Race conditions** — Multiple `setState` calls can overwrite; use functional updates or refs
|
||||
|
||||
## DOM
|
||||
|
||||
- **`querySelector` returns null** — Check before accessing properties; `document.querySelector('.x').classList` crashes if `.x` missing
|
||||
- **Event delegation** — Add listener to parent, check `e.target`; better than listeners on each child
|
||||
- **`innerHTML` security** — Never insert user content with `innerHTML`; use `textContent` or sanitize
|
||||
- **Live vs static NodeLists** — `getElementsByClassName` is live (updates); `querySelectorAll` is static
|
||||
|
||||
## Objects/Arrays
|
||||
|
||||
- **Shallow copy** — `{...obj}` and `[...arr]` are shallow; nested objects share references
|
||||
- **Array holes** — `Array(5)` creates holes; `.map()` skips them; use `Array(5).fill()` instead
|
||||
- **`delete` on array** — Creates hole, doesn't shift; use `.splice()` to remove elements
|
||||
- **Object key order** — Guaranteed insertion order for string keys; numeric keys sort ascending
|
||||
|
||||
## Functions
|
||||
|
||||
- **`this` in arrow functions** — Lexically bound; can't be changed with `.bind()`, `.call()`, `.apply()`
|
||||
- **Default parameters evaluate** — `fn(x = Date.now())` evaluates on each call, not definition
|
||||
- **Rest parameters must be last** — `fn(...rest, other)` is syntax error
|
||||
44
performance.md
Normal file
44
performance.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Performance, SEO, and Accessibility
|
||||
|
||||
## Core Web Vitals
|
||||
|
||||
| Metric | Target | How to improve |
|
||||
|--------|--------|----------------|
|
||||
| LCP (Largest Contentful Paint) | < 2.5s | Preload hero image, optimize server response, avoid render-blocking JS |
|
||||
| FID (First Input Delay) | < 100ms | Break up long tasks, defer non-critical JS, use web workers |
|
||||
| CLS (Cumulative Layout Shift) | < 0.1 | Set explicit image dimensions, reserve space for ads/embeds |
|
||||
|
||||
## Image Optimization
|
||||
|
||||
- **Format** — Use WebP/AVIF with fallbacks; JPEG for photos, PNG only for transparency
|
||||
- **Sizing** — Serve appropriately sized images; don't scale 2000px to 200px in CSS
|
||||
- **Lazy loading** — Add `loading="lazy"` to below-fold images
|
||||
- **Dimensions** — Always include `width` and `height` attributes to prevent CLS
|
||||
- **Next.js Image** — Use `<Image>` component for automatic optimization and formats
|
||||
|
||||
## JavaScript Performance
|
||||
|
||||
- **Defer non-critical** — Use `defer` or `async` on scripts; or load at end of body
|
||||
- **Code split** — Lazy-load routes and heavy components
|
||||
- **Tree shake** — Use ES modules; avoid default exports from barrel files
|
||||
- **Avoid layout thrashing** — Batch DOM reads before writes; avoid interleaved read-write
|
||||
|
||||
## SEO Essentials
|
||||
|
||||
- **Unique title per page** — 50-60 characters, include primary keyword
|
||||
- **Meta description** — 150-160 characters, compelling for click-through
|
||||
- **Semantic HTML** — `<h1>` once per page, proper heading hierarchy
|
||||
- **Canonical URL** — Set `<link rel="canonical">` to prevent duplicate content
|
||||
- **Open Graph tags** — `og:title`, `og:description`, `og:image` for social sharing
|
||||
- **Sitemap** — Generate `sitemap.xml`, submit to Search Console
|
||||
- **Robots.txt** — Don't accidentally block important pages
|
||||
|
||||
## Accessibility (a11y)
|
||||
|
||||
- **Keyboard navigation** — All interactive elements focusable and operable with keyboard
|
||||
- **Color contrast** — 4.5:1 minimum for normal text, 3:1 for large text
|
||||
- **Alt text** — Descriptive for content images, empty for decorative
|
||||
- **Focus indicators** — Don't remove outlines; use `:focus-visible` for keyboard-only
|
||||
- **ARIA labels** — Use when semantic HTML isn't enough; `aria-label`, `aria-describedby`
|
||||
- **Form labels** — Every input needs associated `<label>` or `aria-label`
|
||||
- **Heading order** — Don't skip levels; `<h1>` → `<h2>` → `<h3>`, not `<h1>` → `<h3>`
|
||||
Reference in New Issue
Block a user