本文件使用 Web 特有的前端内容扩展 common/coding-style.md。

Web 编码风格¶

文件结构¶

按功能或界面区域组织，而不是按文件类型：

src/
├── components/
│   ├── hero/
│   │   ├── Hero.tsx
│   │   ├── HeroVisual.tsx
│   │   └── hero.css
│   ├── scrolly-section/
│   │   ├── ScrollySection.tsx
│   │   ├── StickyVisual.tsx
│   │   └── scrolly.css
│   └── ui/
│       ├── Button.tsx
│       ├── SurfaceCard.tsx
│       └── AnimatedText.tsx
├── hooks/
│   ├── useReducedMotion.ts
│   └── useScrollProgress.ts
├── lib/
│   ├── animation.ts
│   └── color.ts
└── styles/
    ├── tokens.css
    ├── typography.css
    └── global.css

CSS 自定义属性¶

将设计令牌定义为变量。不要反复硬编码调色板、排版和间距：

:root {
  --color-surface: oklch(98% 0 0);
  --color-text: oklch(18% 0 0);
  --color-accent: oklch(68% 0.21 250);

  --text-base: clamp(1rem, 0.92rem + 0.4vw, 1.125rem);
  --text-hero: clamp(3rem, 1rem + 7vw, 8rem);

  --space-section: clamp(4rem, 3rem + 5vw, 10rem);

  --duration-fast: 150ms;
  --duration-normal: 300ms;
  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
}

动画专用属性¶

优先使用对合成器友好的属性： - transform - opacity - clip-path - filter（谨慎使用）

避免动画化与布局相关的属性： - width - height - top - left - margin - padding - border - font-size

语义化 HTML 优先¶

<header>
  <nav aria-label="Main navigation">...</nav>
</header>
<main>
  <section aria-labelledby="hero-heading">
    <h1 id="hero-heading">...</h1>
  </section>
</main>
<footer>...</footer>

当存在语义化元素时，不要依赖通用的 div 包装器堆叠。

命名¶

组件：PascalCase（ScrollySection、SurfaceCard）
钩子：use 前缀（useReducedMotion）
CSS 类：kebab-case 或工具类
动画时间线：包含意图的 camelCase（heroRevealTl）

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC