front-end-dev-standards 1.0.0 → 1.1.0

package/standards//360/237/216/250 ui-ux.md"

@@ -0,0 +1,391 @@
+# UI/UX Standards
+
+Version: 1.0
+Framework: Angular 20+
+Design System: Angular Material 3
+Goal: Consistent, Accessible, Responsive Enterprise User Experience
+
+---
+
+# 1. UI/UX Principles
+
+## Core Principles
+
+1. Consistency Over Creativity
+2. Accessibility First
+3. Mobile Responsive by Default
+4. User Feedback for Every Action
+5. Simplicity Over Complexity
+6. Performance Aware Design
+7. Predictable User Experience
+8. Design System Driven Development
+
+---
+
+# 2. Design System
+
+Approved UI Framework:
+
+```text
+Angular Material 3
+```
+
+Allowed:
+
+✓ Angular Material
+
+✓ Angular CDK
+
+✓ Company Design System Components
+
+Avoid:
+
+✗ Bootstrap
+
+✗ Tailwind Utility-Only Architecture
+
+✗ Multiple UI Libraries
+
+✗ jQuery UI
+
+Only one design system should exist.
+
+---
+
+# 3. Layout Standards
+
+## Application Layout
+
+```text
+┌──────────────────────────────┐
+│ Header                       │
+├───────────┬──────────────────┤
+│ Sidebar   │ Content          │
+│           │                  │
+├───────────┴──────────────────┤
+│ Footer                       │
+└──────────────────────────────┘
+```
+
+Required:
+
+✓ Header
+
+✓ Sidebar Navigation
+
+✓ Main Content Area
+
+✓ Responsive Behavior
+
+---
+
+# 4. Responsive Breakpoints
+
+| Device  | Width          |
+| ------- | -------------- |
+| Mobile  | < 768px        |
+| Tablet  | 768px - 1024px |
+| Desktop | > 1024px       |
+
+Design mobile-first whenever possible.
+
+---
+
+# 5. Spacing Standards
+
+Use 8px Grid System.
+
+```text
+4px
+8px
+16px
+24px
+32px
+40px
+48px
+64px
+```
+
+Avoid arbitrary spacing values.
+
+Bad:
+
+```scss
+margin: 13px;
+```
+
+Good:
+
+```scss
+margin: 16px;
+```
+
+---
+
+# 6. Typography Standards
+
+| Element | Size |
+| ------- | ---- |
+| H1      | 32px |
+| H2      | 28px |
+| H3      | 24px |
+| H4      | 20px |
+| Body    | 16px |
+| Caption | 14px |
+
+Use Material Typography.
+
+Avoid custom font scales.
+
+---
+
+# 7. Color Standards
+
+Use Design Tokens.
+
+Example:
+
+```scss
+--primary-color
+--secondary-color
+--error-color
+--success-color
+```
+
+Never hardcode colors.
+
+Bad:
+
+```scss
+color: red;
+```
+
+Good:
+
+```scss
+color: var(--error-color);
+```
+
+---
+
+# 8. Button Standards
+
+Primary Actions:
+
+```html
+<button mat-flat-button>
+```
+
+Secondary Actions:
+
+```html
+<button mat-stroked-button>
+```
+
+Tertiary Actions:
+
+```html
+<button mat-button>
+```
+
+Destructive Actions:
+
+```html
+<button mat-flat-button color="warn">
+```
+
+---
+
+# 9. Form Standards
+
+Every form must have:
+
+✓ Labels
+
+✓ Validation
+
+✓ Error Messages
+
+✓ Required Indicators
+
+✓ Loading State
+
+✓ Submit State
+
+Example:
+
+```html
+<mat-form-field>
+  <mat-label>Email</mat-label>
+  <input matInput />
+</mat-form-field>
+```
+
+---
+
+# 10. Validation Standards
+
+Display errors:
+
+✓ On Blur
+
+✓ On Submit
+
+Avoid showing errors while typing.
+
+---
+
+# 11. Loading States
+
+Every async action requires:
+
+✓ Loading Spinner
+
+✓ Skeleton Loader
+
+✓ Progress Indicator
+
+Never leave users wondering.
+
+---
+
+# 12. Empty States
+
+Every table/list requires empty state.
+
+Example:
+
+```text
+No employees found.
+Try adjusting filters.
+```
+
+Avoid blank screens.
+
+---
+
+# 13. Error States
+
+Display:
+
+✓ User-Friendly Message
+
+✓ Retry Option
+
+✓ Error Tracking
+
+Never expose technical details.
+
+---
+
+# 14. Table Standards
+
+Required:
+
+✓ Pagination
+
+✓ Sorting
+
+✓ Filtering
+
+✓ Empty State
+
+✓ Loading State
+
+Use Angular Material Table.
+
+---
+
+# 15. Dialog Standards
+
+Dialogs should:
+
+✓ Focus First Element
+
+✓ Trap Keyboard Focus
+
+✓ Support ESC Close
+
+✓ Support Mobile
+
+Avoid nested dialogs.
+
+---
+
+# 16. Accessibility Standards
+
+All components must support:
+
+✓ Keyboard Navigation
+
+✓ Screen Readers
+
+✓ Focus Management
+
+✓ ARIA Labels
+
+Target:
+
+WCAG 2.2 AA
+
+---
+
+# 17. Navigation Standards
+
+Current page must be visible.
+
+Sidebar must support:
+
+✓ Active State
+
+✓ Collapse State
+
+✓ Mobile State
+
+---
+
+# 18. Notification Standards
+
+Use Snackbar for:
+
+✓ Success
+
+✓ Warning
+
+✓ Information
+
+✓ Error
+
+Messages should be concise.
+
+---
+
+# 19. Dashboard Standards
+
+Every dashboard should include:
+
+✓ Loading State
+
+✓ Error State
+
+✓ Empty State
+
+✓ Last Updated Timestamp
+
+---
+
+# 20. Definition of UI Quality
+
+UI is production-ready when:
+
+✓ Responsive
+
+✓ Accessible
+
+✓ Consistent
+
+✓ Tested
+
+✓ Design System Compliant
+
+✓ User Friendly

package/standards//360/237/223/232 documentation.md"

@@ -0,0 +1,127 @@
+# Documentation Standards
+
+Version: 1.0
+Goal: Clear, Maintainable, Discoverable Knowledge Base
+
+---
+
+# 1. Documentation Principles
+
+1. Documentation is Part of Code
+2. Keep It Updated
+3. Keep It Simple
+4. Document Why, Not Just What
+5. Avoid Duplication
+
+---
+
+# 2. Required Documentation Types
+
+Each feature must include:
+
+✓ README.md
+✓ API references
+✓ Usage examples
+
+---
+
+# 3. Feature Documentation Structure
+
+```text
+Feature Name
+Purpose
+Routes
+Components
+Services
+Models
+Usage Guide
+```
+
+---
+
+# 4. README Standards
+
+Each feature README must include:
+
+* Overview
+* Setup
+* Usage
+* Dependencies
+* API integration
+
+---
+
+# 5. Code Documentation
+
+Use JSDoc:
+
+```typescript
+/**
+ * Fetch employee details by ID
+ */
+```
+
+---
+
+# 6. Architecture Documentation
+
+Must include:
+
+* Feature boundaries
+* Data flow
+* Dependencies
+
+---
+
+# 7. ADR (Architecture Decision Records)
+
+Format:
+
+```text
+Problem
+Decision
+Alternatives
+Outcome
+```
+
+---
+
+# 8. API Documentation
+
+All APIs must be documented with:
+
+* Request
+* Response
+* Error formats
+
+---
+
+# 9. Component Documentation
+
+Shared components must include:
+
+* Inputs
+* Outputs
+* Examples
+
+---
+
+# 10. Change Documentation
+
+Any breaking change must be documented.
+
+---
+
+# 11. Versioning Docs
+
+Document all major changes per release.
+
+---
+
+# 12. AI Documentation Rules
+
+AI-generated code must include:
+
+✓ Clear comments
+✓ Usage examples
+✓ Type definitions

package/standards//360/237/224/214 api-standards.md"

@@ -0,0 +1,201 @@
+# API Standards
+
+Version: 1.0
+Framework: Angular 20+ Frontend Integration
+Goal: Consistent, Secure, Scalable API Communication
+
+---
+
+# 1. API Design Principles
+
+## Core Principles
+
+1. Consistency Across All Services
+2. Strong Typing for All Requests/Responses
+3. No Direct API Calls in Components
+4. Backend is Source of Truth
+5. Frontend Must Never Assume Data Shape
+6. Fail Gracefully Always
+
+---
+
+# 2. API Layer Architecture
+
+All API calls must go through services:
+
+```text
+Component → Service → HTTP Client → Backend
+```
+
+Never:
+
+❌ Call HttpClient directly in components
+
+---
+
+# 3. Endpoint Standards
+
+## Naming Convention
+
+Use RESTful naming:
+
+| Action  | Pattern               |
+| ------- | --------------------- |
+| Get All | GET /resources        |
+| Get One | GET /resources/:id    |
+| Create  | POST /resources       |
+| Update  | PUT /resources/:id    |
+| Delete  | DELETE /resources/:id |
+
+---
+
+# 4. DTO Standards
+
+## Separate Models
+
+```typescript
+Employee
+CreateEmployeeRequest
+UpdateEmployeeRequest
+EmployeeResponse
+```
+
+Never reuse API models directly in UI logic.
+
+---
+
+# 5. Response Wrapper
+
+All APIs must follow:
+
+```typescript
+interface ApiResponse<T> {
+  data: T;
+  message: string;
+  success: boolean;
+}
+```
+
+---
+
+# 6. Error Handling
+
+Standard API error:
+
+```typescript
+interface ApiError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+```
+
+---
+
+# 7. Pagination Standards
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+```
+
+---
+
+# 8. Filtering & Sorting
+
+Standard query params:
+
+```text
+?page=1&pageSize=10&sortBy=name&order=asc
+```
+
+---
+
+# 9. HTTP Methods Rules
+
+| Method | Usage          |
+| ------ | -------------- |
+| GET    | Read           |
+| POST   | Create         |
+| PUT    | Full Update    |
+| PATCH  | Partial Update |
+| DELETE | Remove         |
+
+---
+
+# 10. Authentication Standards
+
+* Use Bearer Token
+* Inject via HTTP Interceptor
+* Never manually attach token in services
+
+---
+
+# 11. Caching Strategy
+
+Cache allowed for:
+
+✓ Master Data
+✓ Dropdown Data
+✓ Static Configs
+
+Do NOT cache:
+
+❌ Payroll Data
+❌ Sensitive Employee Data
+
+---
+
+# 12. Retry Policy
+
+Retry only:
+
+* Network failures
+* Timeout errors
+
+Never retry:
+
+❌ 4xx errors
+
+---
+
+# 13. Logging
+
+Log only:
+
+✓ API failures
+✓ Performance issues
+
+Never log sensitive payloads.
+
+---
+
+# 14. Versioning
+
+APIs must support versioning:
+
+```text
+/api/v1/employees
+```
+
+---
+
+# 15. Security Rules
+
+* Always use HTTPS
+* Validate input on backend
+* Never trust frontend validation alone
+
+---
+
+# 16. AI API Rules
+
+AI-generated API calls must:
+
+✓ Use typed responses
+✓ Follow DTO structure
+✓ Never bypass interceptors