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 shell

Be aware of extra endline characters from Windows

Check correct Node version by running `nvm use` in the terminal

Use latest version of Cursor or VS Code

Frontend Development

TypeScript Configuration

Use latest stable version of Vue 3

Enable TypeScript strict mode

Configure 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 statement

Use explicit return types for functions and methods

Prefer interfaces over type aliases for object shapes

Annotate exported constants and functions with explicit types

File Organization & Imports

When moving files between directories, **ALWAYS update all import paths** in other files that reference the moved file

Use 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 files

Use relative imports for files in the same directory or for closely related files

When in doubt, search the entire codebase for references to the file being moved

Design 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 possible

Never use base design tokens directly in components

When 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 duplication

Components must be fully typed with TypeScript interfaces/types

Props must have proper validation and default values

Components must be responsive by default

Components 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 documentation

Component 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 tests

Unit tests must be co-located with components in `__tests__` directory

Test 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 slots

Tests must verify accessibility features

Tests must include error states and edge cases

Tests must verify responsive behavior

100% coverage required for critical components

**Testing Best Practices:**

Use `vi.mock` for mocking dependencies

Mock external dependencies and API calls

Test user interactions and events

Verify component state changes

Test error handling and edge cases

Include accessibility testing

**Testing Structure:**

Follow atomic design testing pattern for all components

Create separate test utility files (`*.test-utils.ts`)

Create fixture files for mock data in `__fixtures__` directory

Organize tests by category (rendering, props, events, etc.)

Avoid script execution issues by creating files directly

**Pinia Store Testing:**

Use `vi.mock` to mock Pinia stores

Mock store state, getters, and actions

Test store mutations and state changes

Test store action error handling

Example store mock:

```typescript

vi.mock('@/stores/myStore', () => ({

useMyStore: vi.fn(() => ({

state: {},

getters: {},

actions: vi.fn(),

})),

}));

```

Accessibility (WCAG 2.1 AA)

Use semantic HTML elements

Provide meaningful labels and descriptions

Ensure keyboard navigation is available

Make sure the website is usable by screen readers

Use 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 constants

Type interfaces must be prefixed with `I` (e.g., `IUser`)

Enums must be suffixed with `Enum` (e.g., `StatusEnum`)

Performance

Lazy load components when possible

Optimize images and assets

Use proper caching strategies

Monitor bundle size

Backend Development

Framework & Language

Node.js with Express.js for API development

TypeScript with strict mode enabled

API Design

**GraphQL:**

Use DataLoader for N+1 query prevention

Implement proper error handling and custom error types

Use field-level permissions

**RESTful Endpoints:**

Follow proper HTTP methods and status codes

Implement HATEOAS where applicable

**Authentication & Security:**

JWT for authentication

Implement refresh token rotation

Use proper token expiration strategies

Proper rate limiting for endpoints (sliding window rate limiting)

Configure per-route limits

**Real-Time Features:**

WebSockets for notifications and chat

Implement heartbeat mechanism

Handle reconnection gracefully

Database Strategy

**MongoDB** (primary database for social content):

Use proper indexing strategies

Implement data validation at schema level

**PostgreSQL** (relational data):

Use transactions for data integrity

Implement proper constraints

**Redis** (caching and session management):

Implement proper TTL strategies

Use appropriate data structures

Storage

AWS S3 or similar for media storage

Implement proper file type validation

Use CDN for media delivery

Architecture Principles

Domain-driven design

SOLID principles

Clean Architecture patterns

Layered architecture (controllers, services, repositories)

Proper dependency injection

Follow single responsibility principle

Testing Requirements

**Framework & Organization:**

Use Jest for unit and integration tests

Unit tests must be co-located with source files in `__tests__` directory

Test files must be named `*.test.ts`

Integration tests must be in `tests/integration` directory

E2E tests must be in `tests/e2e` directory

**Testing Requirements:**

**Every service and controller MUST have unit tests**

All API endpoints must have integration tests

Database operations must have integration tests

Authentication flows must have E2E tests

100% coverage required for critical paths

E2E tests required for main user flows

**Testing Best Practices:**

Use proper test isolation

Mock external services and dependencies

Use test databases for integration tests

Clean up test data after each test

Test error handling and edge cases

Include performance testing for critical paths

Documentation

Swagger/OpenAPI with detailed schemas

JSDoc for all public methods

README files for each module

Project 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 styles

Backend (`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 types

Configuration

Keep in environment variables

Use proper configuration validation

Implement environment-specific configs

Database Migrations

Maintain migrations for schema changes

Version control migrations

Implement rollback strategies

Code Quality

ESLint for static code analysis

Prettier for code formatting

Biome for additional linting and formatting

Use `npm run lint` and `npm run format:biome` to maintain code quality

Follow the rules defined in `biome.json`

Husky for pre-commit hooks

SonarQube 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

TSS Full-Stack Development Rules

TSS Full-Stack Development Rules

Environment Setup

Shell & Tools

Frontend Development

TypeScript Configuration

TypeScript Best Practices

File Organization & Imports

Design System & Styling

Component Development (Atomic Design)

Testing Requirements

Accessibility (WCAG 2.1 AA)

Naming Conventions

Performance

Backend Development

Framework & Language

API Design

Database Strategy

Storage

Architecture Principles

Testing Requirements

Documentation

Project Structure

Frontend (`front/`)

Backend (`back/`)

Configuration

Database Migrations

Code Quality

Key Principles

Reviews (0)