39b2b642d2
Plan UI premium 6–8 semaines (design system, shell, Storybook, a11y): - Design system: DESIGN_TOKENS.md, APP_SHELL.md, FULL_LAYOUT_PAGE.md. Single source for layout/shell (index.css), shadows (design-system.css), durations/easing. - Tokens: shadow-cover-depth, shadow-gold-glow, shadow-fab-glow; layout max-height (max-h-layout-drawer, max-h-layout-panel, max-h-layout-list). All duration-200/300/500 replaced by --duration-fast/normal/slow. Arbitrary shadows replaced by token classes. - Shell & player: Sidebar, Header, GlobalPlayer, MiniPlayer, PlayerQueue, PlayerControls, AudioPlayer use tokens; focus-visible on Sidebar, PlayerQueue, DropdownMenuTrigger/Item, TabsTrigger. Typography: text-[10px]/[9px] → text-xs where applicable. - ESLint: no-restricted-syntax (warn) for w-/h-/rounded-/shadow-/text-/spacing arbitrary. - Scripts: report-arbitrary-values.mjs, capture/compare/generate visual; visual-complete.spec.ts. - Stories full layout: Dashboard, Playlists, Library, Settings, Profile in DashboardLayout.stories. - .cursorrules + README: DESIGN_TOKENS, APP_SHELL, visual commands, no arbitrary without justification. - apps/web/.gitignore: e2e test artifacts (test-results-visual, playwright-report-visual). Co-authored-by: Cursor <cursoragent@cursor.com>
198 lines
5.4 KiB
Markdown
198 lines
5.4 KiB
Markdown
# Veza Frontend
|
|
|
|
React + TypeScript frontend application for the Veza audio collaboration platform.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+ and npm
|
|
- Backend API running (see `veza-backend-api/README.md`)
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
The application will be available at `http://localhost:5173`.
|
|
|
|
### Building
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
## Setup Steps
|
|
|
|
### 1. Environment Variables
|
|
|
|
Copy `.env.example` to `.env` and configure:
|
|
|
|
```bash
|
|
# API Configuration
|
|
VITE_API_URL=http://localhost:8080/api/v1
|
|
VITE_WS_URL=ws://localhost:8081
|
|
VITE_STREAM_URL=http://localhost:8082
|
|
|
|
# Optional: Enable MSW mocks for development
|
|
VITE_USE_MSW=0
|
|
```
|
|
|
|
See `.env.example` for all available environment variables.
|
|
|
|
### 2. Type Generation
|
|
|
|
TypeScript types are generated from the OpenAPI specification. To regenerate types:
|
|
|
|
```bash
|
|
npm run generate:types
|
|
```
|
|
|
|
This script:
|
|
- Reads `veza-backend-api/openapi.yaml`
|
|
- Generates TypeScript types to `src/types/generated/`
|
|
- Creates barrel exports for easy importing
|
|
|
|
**Note**: Types are automatically generated in CI/CD before type checking.
|
|
|
|
### 3. Validation
|
|
|
|
Validate types and schemas:
|
|
|
|
```bash
|
|
# Type checking
|
|
npm run validate:types
|
|
|
|
# Schema validation
|
|
npm run validate:schemas
|
|
|
|
# Both
|
|
npm run validate:all
|
|
```
|
|
|
|
## Available Scripts
|
|
|
|
### Development
|
|
- `npm run dev` - Start development server
|
|
- `npm run dev:lab` - Start with lab environment (real database)
|
|
- `npm run dev:mocks` - Start with MSW mocks enabled
|
|
|
|
### Building
|
|
- `npm run build` - Build for production
|
|
- `npm run preview` - Preview production build
|
|
|
|
### Testing
|
|
- `npm test` - Run unit tests (Vitest)
|
|
- `npm run test:ui` - Run tests with UI
|
|
- `npm run test:e2e` - Run E2E tests (Playwright)
|
|
|
|
### Code Quality
|
|
- `npm run lint` - Run ESLint
|
|
- `npm run lint:fix` - Fix ESLint issues
|
|
- `npm run lint:ui` - Run ESLint on `src/components` and `src/features` only
|
|
- `npm run report:arbitrary` - Report Tailwind arbitrary values (w-[...], gap-[...], etc.) for migration
|
|
- `npm run typecheck` - Type check without emitting files
|
|
- `npm run fmt` - Format code with Prettier
|
|
|
|
### Type Generation & Validation
|
|
- `npm run generate:types` - Generate TypeScript types from OpenAPI spec
|
|
- `npm run validate:schemas` - Validate Zod schemas
|
|
- `npm run validate:types` - Type check
|
|
- `npm run validate:all` - Run all validations
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
apps/web/
|
|
├── src/
|
|
│ ├── components/ # Reusable UI components
|
|
│ ├── features/ # Feature modules (auth, tracks, playlists, etc.)
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ ├── services/ # API clients and services
|
|
│ ├── stores/ # Zustand state management (UI state stores)
|
|
│ │ # Note: Feature stores (auth, chat) are in features/*/store/
|
|
│ ├── types/ # TypeScript types
|
|
│ │ └── generated/ # Auto-generated types from OpenAPI
|
|
│ ├── utils/ # Utility functions
|
|
│ └── styles/ # Global styles and design tokens
|
|
├── e2e/ # End-to-end tests (Playwright)
|
|
├── scripts/ # Build and utility scripts
|
|
└── public/ # Static assets
|
|
```
|
|
|
|
## Design System
|
|
|
|
The application uses the Kodo design system. **Single source of truth** for layout, spacing, shadows, and transitions: `docs/DESIGN_TOKENS.md`. Shell layout: `docs/APP_SHELL.md`.
|
|
|
|
- **Colors**: Kodo color palette (see `src/styles/COLOR_USAGE.md`)
|
|
- **Components**: Design system components in `src/components/ui/`
|
|
- **Typography**: Type scale and hierarchy (see `docs/DESIGN_TOKENS.md`, `src/styles/TYPOGRAPHY_GUIDE.md`)
|
|
- **Spacing**: Spacing scale (see `docs/SPACING_GUIDE.md`) — no arbitrary values (e.g. `w-[300px]`, `gap-[7px]`) without justification.
|
|
|
|
**Visual regression**: `npm run visual:capture`, `npm run visual:compare`, `npm run visual:update` (see `visual-tests/README.md`). **Arbitrary values report**: `npm run report:arbitrary` to list Tailwind arbitrary patterns for migration. **New full-layout page**: see `docs/FULL_LAYOUT_PAGE.md`.
|
|
|
|
## ESLint Rules
|
|
|
|
The project enforces:
|
|
|
|
- **Typography**: Use type scale classes (text-xs, text-sm, etc.) instead of arbitrary sizes
|
|
- **Spacing**: Use spacing scale (gap-0 through gap-24) instead of arbitrary values
|
|
- **Colors**: Use Kodo design system colors instead of Tailwind defaults
|
|
- **Components**: Use design system Button component instead of native `<button>`
|
|
|
|
See `eslint.config.js` for full rule configuration.
|
|
|
|
## Contributing
|
|
|
|
1. Follow the existing code style
|
|
2. Run `npm run validate:all` before committing
|
|
3. Ensure all tests pass: `npm test`
|
|
4. Type generation runs automatically in CI/CD
|
|
|
|
## Documentation
|
|
|
|
- **Architecture Guide**: `docs/ARCHITECTURE.md` (MUST READ)
|
|
- **Component Usage**: `src/components/COMPONENT_USAGE.md`
|
|
- **Color Usage**: `src/styles/COLOR_USAGE.md`
|
|
- **Typography**: `src/styles/TYPOGRAPHY_GUIDE.md`
|
|
- **Spacing**: `src/styles/SPACING_GUIDE.md`
|
|
|
|
## Troubleshooting
|
|
|
|
### Type Generation Fails
|
|
|
|
Ensure `veza-backend-api/openapi.yaml` exists and is valid:
|
|
|
|
```bash
|
|
cd ../../veza-backend-api
|
|
swag init # Generate OpenAPI spec
|
|
```
|
|
|
|
### Build Errors
|
|
|
|
1. Clear node_modules and reinstall:
|
|
```bash
|
|
rm -rf node_modules package-lock.json
|
|
npm install
|
|
```
|
|
|
|
2. Clear Vite cache:
|
|
```bash
|
|
rm -rf node_modules/.vite
|
|
```
|
|
|
|
### Type Errors
|
|
|
|
Run type generation and validation:
|
|
|
|
```bash
|
|
npm run generate:types
|
|
npm run validate:types
|
|
```
|