docs: consolidate repository guides and preserve audit history

2026-09-11 14:22:41 +02:00
parent 115441a409
commit 682a3028bb
404 changed files with 3402 additions and 2621 deletions
@@ -0,0 +1,47 @@
+# Accessibility Requirements
+
+## Goal
+
+Make Jobjakt usable by as many people as possible.
+
+---
+
+# Requirements
+
+Support:
+
+- Keyboard navigation.
+- Screen readers.
+- Proper labels.
+- Focus states.
+- Colour contrast.
+
+---
+
+# Forms
+
+Every field requires:
+
+- Label.
+- Validation message.
+- Helpful error.
+
+---
+
+# Documents
+
+CV previews should consider:
+
+- Text readability.
+- Contrast.
+- Print output.
+
+---
+
+# Testing
+
+Use:
+
+- Lighthouse.
+- Axe.
+- Manual testing.
@@ -0,0 +1,73 @@
+# Dashboard Experience
+
+## Purpose
+
+The dashboard is the user's command centre.
+
+It should answer:
+
+"What should I do next?"
+
+---
+
+# Primary Information
+
+Display:
+
+## Application Overview
+
+Examples:
+
+- Active applications.
+- Interviews.
+- Pending follow-ups.
+- Recent activity.
+
+---
+
+## Upcoming Actions
+
+Examples:
+
+- Follow up with company.
+- Prepare interview.
+- Complete application.
+
+---
+
+## Progress
+
+Examples:
+
+- Applications this month.
+- Interview rate.
+- Response rate.
+
+---
+
+# Dashboard Actions
+
+Primary action:
+
+Add Job
+
+Secondary:
+
+- Update CV.
+- Review follow-ups.
+- Search jobs.
+
+---
+
+# Design Direction
+
+Inspired by:
+
+- Notion.
+- Linear.
+
+Avoid:
+
+- Dense dashboards.
+- Too many cards.
+- Information overload.
@@ -0,0 +1,74 @@
+# Design System
+
+## Design Direction
+
+Jobjakt should feel:
+
+- Modern.
+- Professional.
+- Premium.
+- Simple.
+- Intelligent.
+
+---
+
+# Inspirations
+
+Notion:
+
+- Organisation.
+- Content editing.
+
+Linear:
+
+- Professional software.
+
+FlowCV:
+
+- CV building experience.
+
+---
+
+# Colours
+
+Support:
+
+- Light mode.
+- Dark mode.
+
+Use:
+
+- Neutral backgrounds.
+- Clear accent colour.
+- Strong contrast.
+
+---
+
+# Components
+
+Maintain consistency:
+
+- Buttons.
+- Forms.
+- Cards.
+- Dialogs.
+- Tables.
+- Navigation.
+
+---
+
+# Typography
+
+Prioritise:
+
+- Readability.
+- Clear hierarchy.
+- Professional appearance.
+
+---
+
+# UX Rule
+
+Every screen should have:
+
+One obvious primary action.
@@ -0,0 +1,30 @@
+
+# Empty States
+
+## Purpose
+
+Empty states should guide users.
+
+---
+
+Every empty state should explain:
+
+1. What this area does.
+2. Why it matters.
+3. What action to take.
+
+---
+
+Examples:
+
+No jobs:
+
+"Start tracking your job search by adding your first opportunity."
+
+No CV:
+
+"Create your career profile to generate your first CV."
+
+No applications:
+
+"Import a job to begin tracking your application."
@@ -0,0 +1,29 @@
+# Error Experience
+
+## Principles
+
+Errors should be:
+
+- Clear.
+- Helpful.
+- Actionable.
+
+---
+
+Avoid technical messages.
+
+Bad:
+
+"500 Internal Server Error"
+
+Better:
+
+"Something went wrong while importing your CV. Please try again."
+
+---
+
+Include:
+
+- What happened.
+- Possible cause.
+- Next action.
@@ -0,0 +1,29 @@
+# Loading States
+
+## Requirements
+
+Loading should always communicate progress.
+
+---
+
+Examples:
+
+AI generation:
+
+"Creating your tailored CV..."
+
+CV extraction:
+
+"Reading your CV and organising your experience..."
+
+Job import:
+
+"Extracting job details..."
+
+---
+
+Avoid:
+
+Blank screens.
+
+Unexplained spinners.
@@ -0,0 +1,121 @@
+# Navigation Design
+
+## Goal
+
+Navigation should make the application structure obvious.
+
+---
+
+# Primary Navigation
+
+The application hierarchy:
+
+## Main
+
+Dashboard
+
+↓
+
+Jobs
+
+↓
+
+Applications
+
+↓
+
+Calendar / Follow-ups
+
+---
+
+## Career
+
+Career Profile
+
+↓
+
+CV Builder
+
+↓
+
+Cover Letters
+
+↓
+
+Portfolio
+
+---
+
+## Settings
+
+Account
+
+Connected Services
+
+AI Settings
+
+Preferences
+
+---
+
+# Sidebar Principles
+
+The sidebar should:
+
+- Be predictable.
+- Avoid excessive items.
+- Group related functionality.
+
+---
+
+# Current Direction
+
+Move Gmail/email settings into:
+
+Settings
+
+↓
+
+Connected Accounts
+
+---
+
+# Profile vs Career
+
+Important distinction:
+
+## Profile
+
+User account information:
+
+- Name.
+- Email.
+- Password.
+- Avatar.
+- Preferences.
+
+---
+
+## Career
+
+Professional identity:
+
+- Experience.
+- Skills.
+- CV.
+- Documents.
+
+Do not mix these.
+
+---
+
+# Mobile Navigation
+
+Mobile should prioritise:
+
+- Dashboard.
+- Jobs.
+- Add Job.
+- Career.
+
+Advanced settings can remain secondary.
@@ -0,0 +1,41 @@
+# Notifications
+
+## Purpose
+
+Keep users informed without becoming distracting.
+
+---
+
+Types:
+
+## Important
+
+Examples:
+
+- Authentication issues.
+- Failed imports.
+
+---
+
+## Reminder
+
+Examples:
+
+- Follow-ups.
+- Upcoming interviews.
+
+---
+
+## Informational
+
+Examples:
+
+- Completed AI generation.
+
+---
+
+Rules:
+
+Avoid excessive notifications.
+
+Users should control preferences.
@@ -0,0 +1,181 @@
+# User Onboarding Experience
+
+## Purpose
+
+Define how new users should experience Jobjakt from registration to first successful job application workflow.
+
+The onboarding goal is not to show every feature.
+
+The goal is to quickly help users achieve value.
+
+---
+
+# Core Principle
+
+The user should understand:
+
+"Jobjakt helps me organise my job search and create better applications."
+
+within the first few minutes.
+
+---
+
+# Current Ideal Flow
+
+## Step 1 - Registration
+
+Supported:
+
+- Email/password registration.
+- Google registration.
+- Microsoft registration.
+
+After registration:
+
+Create user account.
+
+Verify email where required.
+
+Redirect to onboarding.
+
+---
+
+# Step 2 - Profile Creation
+
+Collect basic information:
+
+Required:
+
+- Name.
+- Email.
+
+Optional:
+
+- Profile picture.
+- Location.
+- Professional title.
+
+Avoid asking unnecessary questions.
+
+---
+
+# Step 3 - Import Career Information
+
+Prompt user:
+
+"Do you already have a CV?"
+
+Options:
+
+## Upload CV
+
+Supported:
+
+- PDF.
+- DOCX.
+- Common CV formats.
+
+System:
+
+- Extracts information.
+- Creates structured career profile.
+- Allows user review.
+
+---
+
+## Create Manually
+
+User builds:
+
+- Experience.
+- Skills.
+- Education.
+
+---
+
+# Step 4 - Connect Email
+
+Optional.
+
+Purpose:
+
+Enable:
+
+- Email tracking.
+- Application communication.
+
+Supported providers:
+
+- Gmail.
+- Microsoft.
+- IMAP.
+
+Do not block the user.
+
+---
+
+# Step 5 - Add First Job
+
+Guide user through:
+
+Import job URL.
+
+↓
+
+Extract details.
+
+↓
+
+Review information.
+
+↓
+
+Create application.
+
+---
+
+# Step 6 - Create Application Documents
+
+Optional workflow:
+
+CV
+
+↓
+
+Cover Letter
+
+↓
+
+Portfolio
+
+↓
+
+Additional files
+
+Users can skip any step.
+
+---
+
+# Onboarding Rules
+
+Never:
+
+- Force users through long forms.
+- Require optional information.
+- Hide the skip option.
+
+Always:
+
+- Show progress.
+- Explain benefits.
+- Provide clear next actions.
+
+---
+
+# First Success Moment
+
+The user should reach:
+
+"I have my first job application tracked."
+
+as quickly as possible.
@@ -0,0 +1,59 @@
+# Profile Experience
+
+## Purpose
+
+Separate personal account information from career information.
+
+---
+
+# Account Profile
+
+Contains:
+
+- Profile picture.
+- Name.
+- Username.
+- Email.
+- Password.
+- Security settings.
+
+---
+
+# Career Profile
+
+Separate area.
+
+Contains:
+
+- Experience.
+- Skills.
+- Education.
+- Projects.
+- Certifications.
+- Languages.
+
+---
+
+# CV Builder
+
+The CV builder should not live directly inside profile.
+
+Recommended:
+
+Career
+
+↓
+
+Master CV
+
+↓
+
+Builder
+
+---
+
+# Important Rule
+
+A user's account profile is not their professional profile.
+
+Keep these separate.
@@ -0,0 +1,47 @@
+# Responsive Design
+
+## Goal
+
+Support desktop and mobile users.
+
+---
+
+# Desktop
+
+Primary experience.
+
+Optimised for:
+
+- Job management.
+- CV building.
+- Document editing.
+
+---
+
+# Tablet
+
+Support:
+
+- Dashboard.
+- Applications.
+- Profile.
+
+---
+
+# Mobile
+
+Prioritise:
+
+- Checking applications.
+- Adding jobs.
+- Follow-ups.
+
+Complex CV editing may be simplified.
+
+---
+
+# Rule
+
+Do not simply shrink desktop layouts.
+
+Design mobile experiences intentionally.
@@ -0,0 +1,88 @@
+# Settings Experience
+
+## Purpose
+
+Settings should allow users to manage their account and application preferences.
+
+---
+
+# Structure
+
+Recommended tabs:
+
+## General
+
+Contains:
+
+- Appearance.
+- Language.
+- Preferences.
+
+Remove unnecessary complexity.
+
+---
+
+## Account
+
+Contains:
+
+- Name.
+- Email.
+- Password.
+- Security.
+
+---
+
+## Connected Accounts
+
+Contains:
+
+Email providers:
+
+- Gmail.
+- Microsoft.
+- IMAP.
+
+Future:
+
+- Other integrations.
+
+---
+
+## AI Settings
+
+Contains:
+
+- AI provider selection.
+- Usage settings.
+- Model preferences.
+
+Admin controls should remain restricted.
+
+---
+
+## Notifications
+
+Contains:
+
+- Email notifications.
+- Follow-up reminders.
+- Application alerts.
+
+---
+
+# Rules
+
+Normal users should not see:
+
+- System management.
+- Import/export administration.
+- Infrastructure controls.
+
+---
+
+# UX Goal
+
+Settings should feel like a normal modern application.
+
+Not an admin panel.
@@ -0,0 +1,99 @@
+# User Flows
+
+## Add Job Flow
+
+Recommended:
+
+Add Job
+
+↓
+
+Enter URL
+
+↓
+
+Import Details
+
+↓
+
+Review Information
+
+↓
+
+Create Application
+
+↓
+
+CV
+
+↓
+
+Cover Letter
+
+↓
+
+Portfolio
+
+↓
+
+Files
+
+↓
+
+Complete
+
+---
+
+# CV Creation Flow
+
+Career Profile
+
+↓
+
+Generate CV
+
+↓
+
+Choose Theme
+
+↓
+
+Customise
+
+↓
+
+Preview
+
+↓
+
+Export
+
+---
+
+# Tailored Application Flow
+
+Job
+
+↓
+
+Analyse Requirements
+
+↓
+
+Generate Suggestions
+
+↓
+
+Create Tailored CV
+
+↓
+
+Review
+
+↓
+
+Save Copy
+
+↓
+
+Export