TSS Full-Stack Development Rules
Comprehensive development guidelines for the TSS project, covering frontend (Vue 3 + TypeScript), backend (Node.js + Express), testing, accessibility, and design system.
Environment Setup
Shell & Tools
Use WSL2 with fish shellBe aware of extra endline characters from WindowsCheck correct Node version by running `nvm use` in the terminalUse latest version of Cursor or VS CodeFrontend Development
TypeScript Configuration
Use latest stable version of Vue 3Enable TypeScript strict modeConfigure TypeScript with: - `verbatimModuleSyntax` enabled
- `isolatedModules` enabled
- `esModuleInterop` enabled
TypeScript Best Practices
**Always use type-only imports** for interfaces and types: `import type { IMyInterface } from './file'`Never mix type imports with value imports in the same import statementUse explicit return types for functions and methodsPrefer interfaces over type aliases for object shapesAnnotate exported constants and functions with explicit typesFile Organization & Imports
When moving files between directories, **ALWAYS update all import paths** in other files that reference the moved fileUse systematic approach to file moves: 1. Identify all files that import the file being moved
2. Update import paths in those files before or immediately after the move
3. Verify that all imports use the correct path after the move
4. Run the application to check for import errors
Use absolute imports with `@/` prefix for project filesUse relative imports for files in the same directory or for closely related filesWhen in doubt, search the entire codebase for references to the file being movedDesign System & Styling
**Semantic Variables (Mandatory)**
All styling must use semantic variables from `front/src/assets/vars.css`**NO hard-coded values allowed**Units must use `rem` as the base unit - **avoid px completely****Semantic Variable Guidelines:**
Always use semantic variables whenever possibleNever use base design tokens directly in componentsWhen creating new semantic variables: - Must be generic enough for multiple components
- Must represent a meaningful design concept or purpose
- Never create component-specific semantic variables
**Color System (Two Layers):**
1. Base design tokens (100-900 scale):
- `--color-primary-{variant}`
- `--color-secondary-{variant}`
- `--color-accent-{variant}`
- `--color-neutral-{variant}`
2. Semantic variables (meaning-based):
- Background: `--color-background`, `--color-background-alt`, `--color-background-muted`
- Text: `--color-text`, `--color-text-secondary`, `--color-text-muted`
- Border: `--color-border`, `--color-border-hover`
- Status: `--color-danger`, `--color-warning`, `--color-success`, `--color-info`
**Spacing System (8px Grid):**
**ONLY use these exact spacing variables:** - `--spacing-xs` (0.25rem)
- `--spacing-sm` (0.5rem)
- `--spacing-md` (1rem)
- `--spacing-lg` (1.5rem)
- `--spacing-xl` (2rem)
**NEVER use numeric spacing variables** like `--spacing-1`, `--spacing-2`, etc.**NEVER use px units for spacing****NEVER create custom spacing variables****Typography System:**
Font sizes in rem: `--font-size-{size}`Weights: `--font-weight-{weight}`Families: `--font-family-{type}`Component Development (Atomic Design)
Follow atomic design principles: atoms → molecules → organisms → templates → pages**Always search the codebase for existing components** before creating new ones to prevent duplicationComponents must be fully typed with TypeScript interfaces/typesProps must have proper validation and default valuesComponents must be responsive by defaultComponents must be accessible (WCAG 2.1 AA compliant)**Component Documentation:**
All component documentation **MUST be placed inside the component file (.vue)** as an HTML comment at the top**DO NOT create separate .md files** for component documentationComponent documentation must include: - Component name and brief description
- Features list
- Usage examples with code snippets
- Props table with types, defaults, and descriptions
- Accessibility considerations
Testing Requirements
**Framework & Organization:**
Use Vitest for unit tests, Cypress for E2E testsUnit tests must be co-located with components in `__tests__` directoryTest files must be named `*.test.ts` or `*.test.tsx`E2E tests must be in `cypress/e2e` directory**Component Testing Requirements:**
**Every component MUST have unit tests**Tests must cover all props, events, and slotsTests must verify accessibility featuresTests must include error states and edge casesTests must verify responsive behavior100% coverage required for critical components**Testing Best Practices:**
Use `vi.mock` for mocking dependenciesMock external dependencies and API callsTest user interactions and eventsVerify component state changesTest error handling and edge casesInclude accessibility testing**Testing Structure:**
Follow atomic design testing pattern for all componentsCreate separate test utility files (`*.test-utils.ts`)Create fixture files for mock data in `__fixtures__` directoryOrganize tests by category (rendering, props, events, etc.)Avoid script execution issues by creating files directly**Pinia Store Testing:**
Use `vi.mock` to mock Pinia storesMock store state, getters, and actionsTest store mutations and state changesTest store action error handlingExample store mock:```typescript
vi.mock('@/stores/myStore', () => ({
useMyStore: vi.fn(() => ({
state: {},
getters: {},
actions: vi.fn(),
})),
}));
```
Accessibility (WCAG 2.1 AA)
Use semantic HTML elementsProvide meaningful labels and descriptionsEnsure keyboard navigation is availableMake sure the website is usable by screen readersUse alt text for images**STRICT ARIA RULE:**
ARIA attributes are **FORBIDDEN** unless all of the following conditions are met: 1. Semantic HTML elements CANNOT provide the needed accessibility
2. The ARIA attribute serves a specific, necessary purpose that cannot be achieved with HTML alone
3. The attribute follows WAI-ARIA best practices and is being used correctly
4. Comprehensive testing with screen readers has proven the need for the attribute
**NEVER use redundant ARIA attributes:**
`role='button'` on a `<button>` element`aria-disabled` on elements with `disabled` attribute`role='link'` on an `<a>` element`aria-label` on elements with clear, visible text content`role='heading'` on an `<h1>`-`<h6>` element**When in doubt, DO NOT use ARIA attributes - use semantic HTML instead.**
Naming Conventions
**BEM syntax for CSS classes** (block__element--modifier)**kebab-case within BEM segments** (my-block__my-element--my-modifier)**Never use inline styles****Never use Tailwind CSS classes****PascalCase** for Vue components**camelCase** for variables, functions, and Vue methods**UPPERCASE** for constantsType interfaces must be prefixed with `I` (e.g., `IUser`)Enums must be suffixed with `Enum` (e.g., `StatusEnum`)Performance
Lazy load components when possibleOptimize images and assetsUse proper caching strategiesMonitor bundle sizeBackend Development
Framework & Language
Node.js with Express.js for API developmentTypeScript with strict mode enabledAPI Design
**GraphQL:**
Use DataLoader for N+1 query preventionImplement proper error handling and custom error typesUse field-level permissions**RESTful Endpoints:**
Follow proper HTTP methods and status codesImplement HATEOAS where applicable**Authentication & Security:**
JWT for authenticationImplement refresh token rotationUse proper token expiration strategiesProper rate limiting for endpoints (sliding window rate limiting)Configure per-route limits**Real-Time Features:**
WebSockets for notifications and chatImplement heartbeat mechanismHandle reconnection gracefullyDatabase Strategy
**MongoDB** (primary database for social content):
Use proper indexing strategiesImplement data validation at schema level**PostgreSQL** (relational data):
Use transactions for data integrityImplement proper constraints**Redis** (caching and session management):
Implement proper TTL strategiesUse appropriate data structuresStorage
AWS S3 or similar for media storageImplement proper file type validationUse CDN for media deliveryArchitecture Principles
Domain-driven designSOLID principlesClean Architecture patternsLayered architecture (controllers, services, repositories)Proper dependency injectionFollow single responsibility principleTesting Requirements
**Framework & Organization:**
Use Jest for unit and integration testsUnit tests must be co-located with source files in `__tests__` directoryTest files must be named `*.test.ts`Integration tests must be in `tests/integration` directoryE2E tests must be in `tests/e2e` directory**Testing Requirements:**
**Every service and controller MUST have unit tests**All API endpoints must have integration testsDatabase operations must have integration testsAuthentication flows must have E2E tests100% coverage required for critical pathsE2E tests required for main user flows**Testing Best Practices:**
Use proper test isolationMock external services and dependenciesUse test databases for integration testsClean up test data after each testTest error handling and edge casesInclude performance testing for critical pathsDocumentation
Swagger/OpenAPI with detailed schemasJSDoc for all public methodsREADME files for each moduleProject Structure
Frontend (`front/`)
`src/components/` - Vue components following atomic design`src/views/` - Page components`src/store/` - State management`src/services/` - API services`src/utils/` - Utility functions`src/types/` - TypeScript types`src/assets/` - Static assets and global stylesBackend (`back/`)
`src/controllers/` - Request handlers`src/services/` - Business logic`src/repositories/` - Data access`src/middleware/` - Custom middleware`src/models/` - Database models`src/schemas/` - GraphQL schemas`src/utils/` - Utility functions`src/types/` - TypeScript typesConfiguration
Keep in environment variablesUse proper configuration validationImplement environment-specific configsDatabase Migrations
Maintain migrations for schema changesVersion control migrationsImplement rollback strategiesCode Quality
ESLint for static code analysisPrettier for code formattingBiome for additional linting and formattingUse `npm run lint` and `npm run format:biome` to maintain code qualityFollow the rules defined in `biome.json`Husky for pre-commit hooksSonarQube for code quality metrics (backend)Key Principles
1. **Accessibility First** - WCAG 2.1 AA compliance is mandatory
2. **Semantic HTML Over ARIA** - Use native elements whenever possible
3. **Design System Discipline** - Only use semantic variables, never hard-code values
4. **Testing is Mandatory** - 100% coverage for critical components and paths
5. **TypeScript Strict Mode** - Proper typing for all code
6. **Atomic Design** - Consistent component organization
7. **Performance Matters** - Optimize from the start
8. **Documentation in Code** - Keep docs close to implementation