feat: frontend shadcn
This commit is contained in:
@@ -1,50 +1,255 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
<!--
|
||||
=====================================================================
|
||||
SYNC IMPACT REPORT
|
||||
=====================================================================
|
||||
Version change: 1.0.0 → 1.1.0 (MINOR: Added shadcn/ui component library)
|
||||
|
||||
Modified principles:
|
||||
- III. Styling → III. Styling & UI Components (expanded scope)
|
||||
|
||||
Added sections:
|
||||
- shadcn/ui configuration and usage guidelines
|
||||
- UI component library in Tech Stack
|
||||
- components/ui/ directory in Project Structure
|
||||
|
||||
Removed sections: None
|
||||
|
||||
Templates requiring updates:
|
||||
- .specify/templates/plan-template.md ✅ (compatible - no changes needed)
|
||||
- .specify/templates/spec-template.md ✅ (compatible - no changes needed)
|
||||
- .specify/templates/tasks-template.md ✅ (compatible - no changes needed)
|
||||
|
||||
Follow-up TODOs: None
|
||||
=====================================================================
|
||||
-->
|
||||
|
||||
# ThumbPreview Constitution
|
||||
|
||||
## Core Principles
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
### I. Tech Stack
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
All new code MUST use the established technology stack:
|
||||
|
||||
### [PRINCIPLE_3_NAME]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
**Frontend (React SPA):**
|
||||
- React 19.x with TypeScript 5.x
|
||||
- Vite as build tool with HMR
|
||||
- Tailwind CSS 4.x for styling
|
||||
- shadcn/ui for UI components (Radix UI primitives)
|
||||
- Zustand for client state management
|
||||
- @tanstack/react-query for server state
|
||||
- Axios for HTTP requests
|
||||
- lucide-react for icons
|
||||
|
||||
### [PRINCIPLE_4_NAME]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
**Backend (NestJS API):**
|
||||
- NestJS 11.x with TypeScript 5.x
|
||||
- Express via @nestjs/platform-express
|
||||
- PostgreSQL with TypeORM
|
||||
- class-validator and class-transformer for DTOs
|
||||
- Multer for file uploads
|
||||
- Sharp for image processing
|
||||
|
||||
### [PRINCIPLE_5_NAME]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
**Rationale:** Consistent tooling reduces onboarding friction, ensures compatibility,
|
||||
and enables shared patterns across the codebase.
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
### II. Architecture & Project Structure
|
||||
|
||||
[SECTION_2_CONTENT]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
This is a **monorepo** with separate frontend and backend packages. New code MUST
|
||||
follow the established directory organization:
|
||||
|
||||
## [SECTION_3_NAME]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
**Frontend (`/frontend/src/`):**
|
||||
- `components/` - Application React UI components
|
||||
- `components/ui/` - shadcn/ui primitive components (auto-generated)
|
||||
- `hooks/` - Custom React hooks (useX naming)
|
||||
- `store/` - Zustand state stores
|
||||
- `api/` - Axios client and API methods
|
||||
- `types/` - TypeScript interfaces and types
|
||||
- `lib/` - Utility functions (includes `utils.ts` for cn() helper)
|
||||
- `assets/` - Static images and resources
|
||||
|
||||
[SECTION_3_CONTENT]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
**Backend (`/backend/src/`):**
|
||||
- `modules/` - Feature modules (NestJS module pattern)
|
||||
- Each module contains: `*.module.ts`, `*.controller.ts`, `*.service.ts`
|
||||
- `entities/` - TypeORM entity definitions
|
||||
|
||||
**Configuration Files:**
|
||||
- `components.json` - shadcn/ui configuration (registry, aliases, styling)
|
||||
- `tsconfig.json` - Must include `@/*` path alias for shadcn imports
|
||||
|
||||
**Rules:**
|
||||
- One component/hook/service per file
|
||||
- Feature-based module organization in backend
|
||||
- Clear separation between API, state, and presentation layers
|
||||
- All imports MUST use `@/` alias for shadcn components and lib utilities
|
||||
- Application components use relative imports within packages
|
||||
|
||||
**Rationale:** Predictable structure enables faster navigation and reduces
|
||||
cognitive load when adding features.
|
||||
|
||||
### III. Styling & UI Components
|
||||
|
||||
All styling MUST use Tailwind CSS utility classes combined with shadcn/ui:
|
||||
|
||||
**shadcn/ui Usage:**
|
||||
- Use shadcn/ui components for standard UI elements (Button, Card, Input, etc.)
|
||||
- Install components via `npx shadcn@latest add <component>`
|
||||
- Components installed to `src/components/ui/` - DO NOT modify generated files
|
||||
- Use shadcn MCP server for component discovery and installation commands
|
||||
- Compose shadcn components with application-specific styling via className prop
|
||||
|
||||
**Tailwind Integration:**
|
||||
- Import Tailwind via `@import "tailwindcss"` in index.css
|
||||
- CSS variables defined in index.css for theming (--primary, --background, etc.)
|
||||
- Use `cn()` utility from `@/lib/utils` for conditional class merging
|
||||
- Dark mode via `class="dark"` on html element
|
||||
- Follow established color scheme via CSS variables
|
||||
|
||||
**Styling Rules:**
|
||||
- Prefer shadcn/ui components over custom implementations
|
||||
- Use Tailwind utilities for layout, spacing, and custom styling
|
||||
- Use CSS variables (--primary, --muted-foreground, etc.) for colors
|
||||
- Use Tailwind's responsive breakpoints (sm, md, lg, xl) for layouts
|
||||
|
||||
**Forbidden:**
|
||||
- Inline style objects except for dynamic values (e.g., computed widths)
|
||||
- Creating new CSS files for component-specific styles
|
||||
- Using `!important` overrides
|
||||
- CSS Modules, styled-components, or CSS-in-JS libraries
|
||||
- Modifying files in `components/ui/` directory
|
||||
|
||||
**Icon Usage:**
|
||||
- Use lucide-react for all icons
|
||||
- Import icons individually: `import { IconName } from 'lucide-react'`
|
||||
- Use `size-X` or `className="size-X"` for icon sizing
|
||||
|
||||
**Rationale:** shadcn/ui provides accessible, well-designed primitives while
|
||||
Tailwind enables customization. This combination ensures consistency and
|
||||
reduces custom CSS maintenance.
|
||||
|
||||
### IV. Data Management
|
||||
|
||||
**Frontend State:**
|
||||
- Use Zustand for UI/client state (view mode, selections, form data)
|
||||
- Use React Query for server state (API data, caching, mutations)
|
||||
- Define all store actions in the store file, not in components
|
||||
- React Query stale time: 1 hour for search results
|
||||
|
||||
**Backend Storage:**
|
||||
- PostgreSQL for persistent data (via TypeORM)
|
||||
- UUID primary keys for all entities
|
||||
- File uploads stored in `/backend/uploads/` directory
|
||||
- YouTube API responses cached in database with 24-hour TTL
|
||||
|
||||
**Environment Configuration:**
|
||||
- Backend: Use @nestjs/config with .env files
|
||||
- Frontend: Use Vite proxy for API calls (no .env needed)
|
||||
- Never commit .env files or API keys
|
||||
|
||||
**Rationale:** Clear boundaries between client and server state prevent
|
||||
synchronization bugs and simplify debugging.
|
||||
|
||||
### V. Development Practices
|
||||
|
||||
**TypeScript:**
|
||||
- Strict mode enabled for frontend application code
|
||||
- All new code MUST have explicit type annotations for function parameters
|
||||
- Use interfaces for object shapes, types for unions/aliases
|
||||
- No `any` type except in exceptional cases with justification
|
||||
- Path aliases MUST be configured: `@/*` → `./src/*`
|
||||
|
||||
**Linting & Formatting:**
|
||||
- Frontend: ESLint with React hooks and React Refresh plugins
|
||||
- Backend: ESLint + Prettier (singleQuote, trailingComma: all)
|
||||
- Run `npm run lint` before committing
|
||||
- Run `npm run format` (backend) for consistent formatting
|
||||
|
||||
**Testing (Backend):**
|
||||
- Jest for unit and integration tests
|
||||
- Test files: `*.spec.ts` adjacent to source files
|
||||
- Run `npm run test` for test suite
|
||||
|
||||
**Validation:**
|
||||
- Backend: Use class-validator decorators on all DTOs
|
||||
- Global validation pipe enabled (whitelist + transform)
|
||||
- File uploads: Validate MIME types (JPEG, PNG, WebP only, 5MB max)
|
||||
|
||||
**Rationale:** Consistent quality standards prevent regressions and
|
||||
maintain code health over time.
|
||||
|
||||
## Technology Stack Reference
|
||||
|
||||
| Layer | Technology | Version | Purpose |
|
||||
|-------|------------|---------|---------|
|
||||
| Frontend Runtime | React | 19.x | UI library |
|
||||
| Frontend Build | Vite | 7.x | Build + HMR |
|
||||
| Frontend Styling | Tailwind CSS | 4.x | Utility CSS |
|
||||
| Frontend UI | shadcn/ui | 3.x | Component library |
|
||||
| Frontend Icons | lucide-react | latest | Icon library |
|
||||
| Frontend State | Zustand | 5.x | Client state |
|
||||
| Frontend Data | React Query | 5.x | Server state |
|
||||
| Backend Framework | NestJS | 11.x | API server |
|
||||
| Backend Database | PostgreSQL | 16 | Data persistence |
|
||||
| Backend ORM | TypeORM | 0.3.x | DB abstraction |
|
||||
| Runtime | Node.js | 20+ | Server runtime |
|
||||
|
||||
New dependencies MUST be justified and reviewed for:
|
||||
- Compatibility with existing versions
|
||||
- Bundle size impact (frontend)
|
||||
- Maintenance status (active development, security updates)
|
||||
- License compatibility (MIT preferred)
|
||||
|
||||
**shadcn/ui Component Installation:**
|
||||
```bash
|
||||
# List available components
|
||||
npx shadcn@latest add --help
|
||||
|
||||
# Add a component (use shadcn MCP for discovery)
|
||||
npx shadcn@latest add button card input --yes
|
||||
|
||||
# Components are added to src/components/ui/
|
||||
```
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
**Pull Request Checklist:**
|
||||
1. Code follows architecture patterns (correct directory placement)
|
||||
2. Styling uses Tailwind utilities and/or shadcn components
|
||||
3. TypeScript types are explicit (no implicit any)
|
||||
4. Linter passes with no errors
|
||||
5. New backend endpoints include validation
|
||||
6. Environment variables documented if added
|
||||
7. shadcn components used for standard UI elements
|
||||
|
||||
**Commit Guidelines:**
|
||||
- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
|
||||
- Reference issue numbers when applicable
|
||||
- Keep commits focused (one logical change per commit)
|
||||
|
||||
**Code Review Focus Areas:**
|
||||
- Security: No hardcoded credentials, proper input validation
|
||||
- Performance: Avoid unnecessary re-renders, efficient queries
|
||||
- Maintainability: Clear naming, appropriate abstractions
|
||||
- UI Consistency: Use shadcn components, follow established patterns
|
||||
|
||||
## Governance
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
This constitution establishes non-negotiable development standards for the
|
||||
ThumbPreview project. All contributors MUST adhere to these principles.
|
||||
|
||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
**Amendment Process:**
|
||||
1. Propose changes via pull request to this file
|
||||
2. Document rationale for changes
|
||||
3. Increment version according to semver rules
|
||||
4. Update dependent templates if principle changes affect them
|
||||
|
||||
**Version Policy:**
|
||||
- MAJOR: Backward-incompatible changes (removing principles, changing stack)
|
||||
- MINOR: New principles or significant expansions
|
||||
- PATCH: Clarifications, typo fixes, non-semantic refinements
|
||||
|
||||
**Compliance:**
|
||||
- All PRs MUST pass constitution checks before merge
|
||||
- Violations require explicit justification in PR description
|
||||
- Repeated violations should trigger constitution review
|
||||
|
||||
**Version**: 1.1.0 | **Ratified**: 2026-01-29 | **Last Amended**: 2026-01-29
|
||||
|
||||
Reference in New Issue
Block a user