---
description: Next.js frontend, UI structure, CSS Modules, a11y, Storybook
globs: apps/web/**/*
alwaysApply: false
---

You are working on the frontend in `apps/web`.

## Framework and rendering
- Use Next.js.
- Prefer Server Components where appropriate.
- Avoid unnecessary client components.
- Keep data-fetching and business logic out of presentational layers.

## UI structure
Use the following frontend structure consistently:
- `components` = pure presentational building blocks and small UI pieces
- `widgets` = composed UI units with local behavior
- `views` = page-level compositions of components and widgets

## Component behavior
- Components may include local UI behavior where appropriate, such as disclosure, accordion, or local interaction state.
- Components must not make API calls or contain unrelated side effects on their own.
- Heavy business logic must not live in the UI presentation layer.
- Data shaping and domain logic should live outside presentational components.

## Shared UI
- Shared UI primitives belong in a dedicated UI package.
- Do not duplicate shared primitives inside app-specific code.
- App-level components may compose primitives from the UI package.

## Styling
- Tailwind is forbidden.
- Use CSS Modules for component styling.
- Use PostCSS for CSS processing.
- Use design tokens and CSS custom properties first.
- Avoid ad hoc spacing, color, and sizing values.
- Prefer token-based styling.
- Use inline styles only when truly necessary for dynamic one-off values.
- Stylelint should be part of linting and style validation.
- Target modern browsers only.
- Use modern CSS features appropriate for current browser support, including CSS nesting / modern syntax supported by the project PostCSS setup.

## Accessibility
Accessibility is a primary requirement.
- Prefer semantic HTML first.
- All interactive UI must be keyboard operable.
- Always provide visible focus states.
- Use proper labels and accessible names.
- Maintain color contrast awareness.
- Use ARIA only when native semantics are insufficient.
- Consider accessibility during implementation, not as an afterthought.

## Storybook
- Every component and widget should have Storybook stories.
- Stories should include:
  - default states
  - loading states where relevant
  - empty/error states where relevant
  - accessibility-relevant and keyboard-relevant states where useful
- Include controls and docs in stories.
- Follow i18n patterns in stories where applicable.