Cursor rule

1> This file extends [common/coding-style.md](../common/coding-style.md) with web-specific frontend content.
2 
3# Web Coding Style
4 
5## File Organization
6 
7Organize by feature or surface area, not by file type:
8 
9```text
10src/
11├── components/
12│   ├── hero/
13│   │   ├── Hero.tsx
14│   │   ├── HeroVisual.tsx
15│   │   └── hero.css
16│   ├── scrolly-section/
17│   │   ├── ScrollySection.tsx
18│   │   ├── StickyVisual.tsx
19│   │   └── scrolly.css
20│   └── ui/
21│       ├── Button.tsx
22│       ├── SurfaceCard.tsx
23│       └── AnimatedText.tsx
24├── hooks/
25│   ├── useReducedMotion.ts
26│   └── useScrollProgress.ts
27├── lib/
28│   ├── animation.ts
29│   └── color.ts
30└── styles/
31    ├── tokens.css
32    ├── typography.css
33    └── global.css
34```
35 
36## CSS Custom Properties
37 
38Define design tokens as variables. Do not hardcode palette, typography, or spacing repeatedly:
39 
40```css
41:root {
42  --color-surface: oklch(98% 0 0);
43  --color-text: oklch(18% 0 0);
44  --color-accent: oklch(68% 0.21 250);
45 
46  --text-base: clamp(1rem, 0.92rem + 0.4vw, 1.125rem);
47  --text-hero: clamp(3rem, 1rem + 7vw, 8rem);
48 
49  --space-section: clamp(4rem, 3rem + 5vw, 10rem);
50 
51  --duration-fast: 150ms;
52  --duration-normal: 300ms;
53  --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
54}
55```
56 
57## Animation-Only Properties
58 
59Prefer compositor-friendly motion:
60- `transform`
61- `opacity`
62- `clip-path`
63- `filter` (sparingly)
64 
65Avoid animating layout-bound properties:
66- `width`
67- `height`
68- `top`
69- `left`
70- `margin`
71- `padding`
72- `border`
73- `font-size`
74 
75## Semantic HTML First
76 
77```html
78<header>
79  <nav aria-label="Main navigation">...</nav>
80</header>
81<main>
82  <section aria-labelledby="hero-heading">
83    <h1 id="hero-heading">...</h1>
84  </section>
85</main>
86<footer>...</footer>
87```
88 
89Do not reach for generic wrapper `div` stacks when a semantic element exists.
90 
91## Naming
92 
93- Components: PascalCase (`ScrollySection`, `SurfaceCard`)
94- Hooks: `use` prefix (`useReducedMotion`)
95- CSS classes: kebab-case or utility classes
96- Animation timelines: camelCase with intent (`heroRevealTl`)
97