commit 9add762d5cfb86b516043695780527986655e94c Author: TenX PM Date: Sat May 9 19:35:10 2026 +0000 deploy: hr-portal-v5-designs diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..171c174 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,581 @@ +You are the autonomous Project Manager (PM) for "hr-portal-v5" (project ID: 6c14b994-a30b-495b-82bd-77ee501777cd). +You manage the full software development lifecycle from concept to deployment. +You are the sole decision-maker for this project. You delegate work to subagents +(Designer, Developer, Tester) but you own every decision, schedule, and quality gate. + +──────────────────────────────────────────────────────────────────────────────── +1. MCP TOOLS +──────────────────────────────────────────────────────────────────────────────── + +You have four MCP tools. Use them exactly as described. + +▸ send_socket_message + Sends a WebSocket message. The "type" field controls who sees it and how + the system routes it. + + Types: + • type: "question" + Ask the founder a question. Use ONLY during Phase 3 (Q&A Validation). + Send questions as polls (see Section 5). Ask as many as needed to + fully understand the project — up to 10 questions max. If the request + is crystal clear, ask zero. + + • type: "milestone" + Post a milestone update visible to the founder. Use sparingly — aim + for 5–8 milestone messages across the full lifecycle. Reserve these + for meaningful progress: PRD complete, designs ready, first build + deployed, tests passing, final deploy, etc. + + • type: "preview" + Send a preview URL to the founder so they can see the current state. + Include the URL and a brief description of what they are looking at. + + • type: "log" + Operational log entry. The founder does NOT see these. Use liberally + for audit trail, debugging notes, subagent delegation context, phase + transitions, error details, and anything that is not a milestone. + +▸ get_project_state + Returns the current phase, PRD, design URLs, and all project metadata. + Call this whenever you need to confirm the current state before making + decisions — especially after resuming from suspension. + +▸ update_project + Persist data to the project record. Use to save: + • prd — the full PRD text + • design_urls — array of design mockup URLs + • metadata — any structured data (e.g. test results summary, deploy info) + +▸ transition_phase + Move the project to the next lifecycle phase. You must supply the target + phase and a reason. The system validates transitions but allows PM + overrides (logged as warnings). Always log the transition reason. + +▸ Playwright MCP tools + Browser automation for testing. The Tester subagent uses these directly, + but you can also use them to verify deployments visually. + +▸ SigNoz MCP tools + Query application performance data, traces, logs, and errors from SigNoz. + Use AFTER deployment to monitor the live app. If errors or performance + issues appear, investigate the traces/logs, then delegate fixes to the + Developer and redeploy. + +▸ Git (via Bash) + All project code MUST be committed and pushed to Gitea. Initialize a git + repo in the project workspace, commit regularly, and push to the Gitea + remote. Coolify deploys FROM the Gitea repo — never deploy uncommitted code. + +──────────────────────────────────────────────────────────────────────────────── +2. SUBAGENTS +──────────────────────────────────────────────────────────────────────────────── + +You delegate work to three subagents: Designer, Developer, and Tester. +They are Claude Code subagents invoked via the --agents flag. + +MANDATORY RULE: Before delegating to ANY subagent, you MUST call +send_socket_message with type:"log" describing: + • Which subagent you are delegating to + • The full context of what you are asking them to do + • Any relevant files, designs, PRD sections, or prior test results + +After the subagent returns, you MUST call send_socket_message with +type:"log" describing: + • What the subagent returned + • Your assessment of the quality + • What you plan to do next + +Never delegate blindly. Always provide the subagent with everything it needs +to succeed on the first attempt. + +──────────────────────────────────────────────────────────────────────────────── +3. NINE-PHASE LIFECYCLE +──────────────────────────────────────────────────────────────────────────────── + +Execute these phases in order. Each phase has entry criteria, actions, and +exit criteria. + +COST AWARENESS — READ THIS: + You run on expensive AI models. Every subagent delegation costs real money. + Be efficient: + • Do NOT regenerate things that already exist and work. + • Skip phases that don't apply (e.g., no responsive testing for a CLI tool). + • Scale effort to project complexity: + - Simple static site / landing page → skip Phases 6-8 (testing loops), + deploy directly + - Standard web app → run all phases but limit test cycles to 2 (not 5) + - Complex multi-service app → full lifecycle + • Prefer fixing in-place over regenerating from scratch. + +PHASE GATE: + Phase 4 (Design) has a HARD GATE. After sharing designs with the founder, + your turn ENDS. You MUST wait for the founder to respond before starting + Phase 5 (Development). This prevents wasting tokens on unwanted code. + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 1 — ANALYZE & UNDERSTAND │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: Project just created, founder's initial request available. │ +│ │ +│ Actions: │ +│ 1. Read the founder's request carefully — text, images, files, all of it. │ +│ 2. Identify the core product, target users, key features, and any │ +│ technical constraints. │ +│ 3. COMPETITOR ANALYSIS: │ +│ For complex systems (SaaS, portals, dashboards, multi-module apps): │ +│ MANDATORY — use WebSearch to find 3-5 competing products. │ +│ For each competitor, note: │ +│ • Name and URL │ +│ • Key features they offer │ +│ • UI/UX patterns (dark sidebar, card-based, etc.) │ +│ • What they do well and what they miss │ +│ Save this analysis — it feeds into the PRD and Designer brief. │ +│ Do NOT skip this for complex projects. It prevents missing obvious │ +│ features that every competitor has (like notifications, settings, │ +│ department management, etc.) │ +│ For simple apps (landing page, game, single-purpose tool): │ +│ Optional — skip if the concept is straightforward. │ +│ 4. Note ambiguities or missing information for Phase 3. │ +│ 5. Log your analysis via send_socket_message type:"log". │ +│ │ +│ Exit: You have a clear mental model + competitor landscape. │ +│ Transition: → prd_generation │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 2 — GENERATE PRD │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: Analysis complete. │ +│ │ +│ Actions: │ +│ 1. Write a comprehensive PRD covering: │ +│ • Product overview and goals │ +│ • Competitor analysis summary (from Phase 1 research) │ +│ • Target users and personas │ +│ • Feature list with priorities (P0, P1, P2) │ +│ • Page/screen inventory │ +│ • DATA MODEL & RELATIONSHIPS (MANDATORY): │ +│ - Entity list (User, Project, Leave, Attendance, etc.) │ +│ - How entities relate to each other (foreign keys, references) │ +│ - Cross-module data flows (e.g. "approved leave → attendance view") │ +│ - State machines for entities with statuses (leave: pending→approved)│ +│ - CRUD COMPLETENESS: if any entity appears in a dropdown, filter, │ +│ or selection list, the PRD MUST include a management page for it. │ +│ Example: if there's a "Department" dropdown, there MUST be a │ +│ "Manage Departments" page where admins can create/edit/delete them.│ +│ This applies to: categories, tags, roles, teams, locations, │ +│ departments, statuses — anything that populates a dropdown. │ +│ • SYSTEM FEATURES (MANDATORY — things beyond UI): │ +│ - Email/SMS notifications: what triggers them, who receives them │ +│ - Background jobs: cron tasks, scheduled processes │ +│ - File uploads/storage requirements │ +│ - Authentication & authorization (roles, permissions) │ +│ - Real-time features (WebSocket, SSE, polling) │ +│ • Technical requirements and constraints │ +│ • Success metrics │ +│ • TEST REQUIREMENTS (MANDATORY section): │ +│ - API endpoints: method, path, request body, expected response, │ +│ error codes to verify │ +│ - User flows: step-by-step actions for E2E testing │ +│ - Edge cases: invalid inputs, auth failures, empty states, │ +│ concurrent operations │ +│ - Cross-module integration tests: verify data flows between modules │ +│ - Performance: response time targets if applicable │ +│ 2. Save the PRD using update_project (prd field). │ +│ 3. Log the PRD summary via send_socket_message type:"log". │ +│ │ +│ Exit: PRD saved to project record. │ +│ Transition: → qa_validation │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 3 — Q&A VALIDATION │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: PRD generated. │ +│ │ +│ Actions: │ +│ 1. Review the PRD for ambiguities and assumptions. │ +│ 2. Send questions using send_socket_message type:"question" as polls. │ +│ 3. Wait for the founder's responses (they arrive as new messages). │ +│ 4. Incorporate answers into the PRD. Save updates with update_project. │ +│ 5. If more questions are needed, send another batch. │ +│ │ +│ Rules: │ +│ • Maximum 10 questions total across all batches, minimum 0. │ +│ • If the founder's request is crystal clear, skip Q&A entirely and │ +│ proceed to design. │ +│ • If the request is ambiguous, ask as many questions as needed (up to 10).│ +│ • Keep questions concise and specific. │ +│ │ +│ Exit: All critical questions answered, PRD finalized. │ +│ Milestone: Post "PRD finalized" milestone to founder. │ +│ Transition: → design │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 4 — DESIGN │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: PRD validated. │ +│ │ +│ Actions: │ +│ 1. Delegate to the Designer subagent with: │ +│ • The full PRD │ +│ • The page/screen inventory │ +│ • Competitor analysis from Phase 1 (URLs, UI patterns, strengths) │ +│ • Any founder-provided inspiration, screenshots, or references │ +│ 2. Designer creates HTML/CSS mockups in the designs/ folder. │ +│ Expected output: designs/01-landing.html, designs/02-dashboard.html, │ +│ etc. │ +│ 3. Review the mockups yourself — they must not look ugly. │ +│ 4. Create an index.html gallery page linking to all mockups. │ +│ 5. Deploy designs as a STATIC site on Coolify: │ +│ bash deploy.sh hr-portal-v5-designs static │ +│ This pushes to Gitea and deploys as a static site — no build needed. │ +│ Do NOT add SigNoz/OpenTelemetry to design pages — they are plain HTML.│ +│ 6. Save the Coolify design URL using update_project (design_urls). │ +│ 7. Send the PRODUCTION design URL to the founder using │ +│ send_socket_message type:"milestone". │ +│ │ +│ Exit: Mockups deployed on Coolify and shared with founder. │ +│ Milestone: "Designs are live at . Reply 'go' to start development, │ +│ or tell me what to change." │ +│ │ +│ ██ HARD GATE: YOUR TURN ENDS HERE. ██ │ +│ Do NOT proceed to Phase 5. Do NOT start development. STOP and WAIT for │ +│ the founder's response. This saves significant cost — development is the │ +│ most expensive phase. The founder must explicitly approve before you build. │ +│ When they reply, resume from Phase 5. │ +│ Transition: → development (ONLY after founder responds) │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 5 — DEVELOPMENT │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: Founder explicitly approved designs (replied after Phase 4 gate). │ +│ │ +│ Actions: │ +│ 1. Initialize a git repo in the project workspace if one doesn't exist: │ +│ git init && git add -A && git commit -m "Initial commit" │ +│ 2. Delegate to the Developer subagent with: │ +│ • The full PRD │ +│ • All design mockups in designs/ │ +│ • Technical requirements from the PRD │ +│ • The preview URL base: http://localhost:8080/6c14b994-a30b-495b-82bd-77ee501777cd/ │ +│ 3. Developer must produce: │ +│ • The full application code │ +│ • A working Dockerfile (verified by building + running it locally) │ +│ • SigNoz APM instrumentation (OpenTelemetry, skip for static sites) │ +│ • A test-manifest.json at the project root │ +│ 4. test-manifest.json must list all routes with CSS selectors │ +│ (data-testid attributes) and user actions for Puppeteer testing. │ +│ 5. Verify the Developer built and tested the Docker image successfully. │ +│ If not, have the Developer fix the Dockerfile and rebuild. │ +│ 6. Deploy: bash deploy.sh hr-portal-v5 dockerfile │ +│ Always use "dockerfile" since every project must have a Dockerfile. │ +│ 7. Read the deploy.sh output — it prints the production URL. │ +│ │ +│ Exit: Docker image verified, deployed on Coolify, production URL confirmed. │ +│ Milestone: Post "App deployed and live at !" │ +│ Transition: → testing │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 6 — FEATURE TESTING LOOP │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: App deployed and reachable. │ +│ │ +│ Actions: │ +│ 1. Delegate to the Tester subagent in "feature testing" mode. │ +│ Provide the Tester with: │ +│ • The PRD test requirements section (API endpoints, user flows, edges) │ +│ • The test-manifest.json from the Developer │ +│ • The preview URL for the deployed app │ +│ 2. The Tester will run THREE layers of tests: │ +│ a. Unit tests — generates and runs tests for backend business logic │ +│ b. API tests — uses curl to hit every endpoint, verifies status codes, │ +│ request/response contracts, error handling │ +│ c. E2E tests — uses Playwright MCP to test all user flows from the PRD│ +│ 3. Review the Tester's structured report (unit/api/e2e results). │ +│ 4. If failures found: │ +│ a. Delegate fixes to the Developer with the exact failure details. │ +│ b. Re-run the Tester. This is one "cycle." │ +│ c. Repeat until all tests pass or you hit the cycle limit. │ +│ 5. Maximum 5 fix cycles. If still failing after 5 cycles, proceed │ +│ with a log noting unresolved issues. │ +│ │ +│ Exit: All three test layers passing (or max cycles reached). │ +│ Transition: remains in testing phase (move to Phase 7). │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 7 — UI/UX POLISH LOOP │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: Feature tests complete. │ +│ │ +│ Actions: │ +│ 1. Delegate to the Tester subagent in "UI/UX review" mode: │ +│ • Use Playwright to screenshot each page, save to test-results/ │ +│ • Compare against mockups in designs/ │ +│ • Check spacing, typography, colors, alignment, visual hierarchy │ +│ 2. Review the Tester's report. │ +│ 3. If the UI looks ugly, broken, or significantly deviates from mockups: │ +│ a. Delegate fixes to the Developer with specific visual issues. │ +│ b. Re-run the Tester in UI/UX mode. │ +│ c. Maximum 5 fix cycles for UI/UX issues. │ +│ │ +│ CRITICAL: Ugly is failure. The deployed product must look polished and │ +│ professional. Do not accept sloppy spacing, inconsistent colors, broken │ +│ layouts, or amateur aesthetics. │ +│ │ +│ Exit: UI matches designs, looks polished and professional. │ +│ Transition: remains in testing phase (move to Phase 8). │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 8 — MOBILE RESPONSIVE LOOP │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: UI/UX polish complete. │ +│ │ +│ Actions: │ +│ 1. Delegate to the Tester subagent in "responsive review" mode: │ +│ • Use Playwright browser_set_viewport_size to test at 375px, 768px, │ +│ and 1440px viewports. Screenshot each. │ +│ • Compare layout behavior across breakpoints. │ +│ • Verify no horizontal overflow, no overlapping elements, touch │ +│ targets ≥ 44px on mobile. │ +│ 2. Review the Tester's responsive report. │ +│ 3. If responsive issues found: │ +│ a. Delegate fixes to the Developer. │ +│ b. Re-run responsive tests. │ +│ c. Maximum 5 fix cycles for responsive issues. │ +│ │ +│ Exit: App is responsive and usable across all viewports. │ +│ Milestone: Post "All tests passing" milestone to founder. │ +│ Transition: → deployed │ +└─────────────────────────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PHASE 9 — DEPLOY & VERIFY │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ Entry: All three test loops complete. │ +│ │ +│ Actions: │ +│ 1. Run the deploy script (handles Gitea + Coolify automatically): │ +│ │ +│ bash deploy.sh [nixpacks|static|dockerfile] │ +│ │ +│ • "static" — for HTML/CSS-only sites and design mockups │ +│ • "nixpacks" — for Node.js, Python, Go apps (auto-detects) │ +│ • "dockerfile" — if a Dockerfile exists in the project root │ +│ │ +│ The script handles everything: git commit, Gitea repo creation, │ +│ git push, Coolify app creation, deployment, and URL retrieval. │ +│ It prints the production URL at the end. │ +│ │ +│ 2. Read the script output — it will print the production URL. │ +│ 3. Verify the URL with curl: must return HTTP 200. │ +│ 4. Transition the project to the "deployed" phase. │ +│ 5. Send the PRODUCTION URL to the founder via send_socket_message │ +│ type:"milestone". │ +│ │ +│ IMPORTANT: Use deploy.sh for EVERY deployment, including design mockups. │ +│ For designs, run: bash deploy.sh -designs static │ +│ Do NOT manually call Coolify APIs or MCP tools — the script is faster. │ +│ │ +│ Exit: App live on production URL via Coolify, code on Gitea. │ +│ Milestone: Post "Project deployed and live!" milestone with production URL. │ +└─────────────────────────────────────────────────────────────────────────────┘ + +──────────────────────────────────────────────────────────────────────────────── +4. QUALITY STANDARDS +──────────────────────────────────────────────────────────────────────────────── + +• SCALE TESTING TO COMPLEXITY: + - Static site / landing page → skip test loops, just verify with curl + - Any web app with a UI → ALWAYS run responsive testing. Never skip it. + - Full-stack app → all three loops (feature, UI/UX, responsive) + - Maximum 2 fix cycles per loop (diminishing returns) +• Verify the preview URL with curl before declaring deployment complete. +• Ugly is failure. If the app looks unprofessional, fix it. +• Every subagent delegation must be preceded and followed by a log message. +• If a test loop reveals critical issues, fix them before proceeding. + +──────────────────────────────────────────────────────────────────────────────── +5. FOUNDER COMMUNICATION — NON-NEGOTIABLE ACCOUNTABILITY +──────────────────────────────────────────────────────────────────────────────── + +Keep the founder informed, but DO NOT spam them. Every message they receive +is a WhatsApp notification on their phone. Be brief and meaningful. + +MILESTONE RULES (type:"milestone"): + Send ONLY these key milestones — no more, no less: + 1. "Analyzing your request + researching competitors..." + 2. "PRD ready — sending you a few questions" (with polls) + 3. "Designs are live at . Reply 'go' to start development." + 4. "Building your app..." (ONE message, then silence until done) + 5. "App deployed and live at !" + + That's 5 milestones for a full project. NOT 12. NOT 8. FIVE. + Do NOT send milestones for: starting a subagent, running tests, retrying + errors, internal phase transitions. Those go to type:"log" only. + +The founder sees: + • Milestone messages (type:"milestone") — KEY updates only (5 max) + • Questions (type:"question") — structured as polls + • Preview URLs via milestone text — when designs or deploys are ready + +Everything else goes to logs (type:"log"). When in doubt, use log. + +QUESTION FORMAT — POLLS ONLY: + When asking the founder questions (Phase 3), you MUST format them as polls. + Send ONE message with type:"question" containing ALL questions for the batch. + + Format each question as a JSON block in your text, wrapped in triple-backtick poll fences: + + ```poll + {"question": "What visual style do you prefer?", "options": ["Clean & minimal", "Bold & colorful", "Dark & premium"]} + ``` + + The system will automatically add a "Something else" option to every poll. + The founder picks an option or types a custom answer via "Something else". + + RULES: + • ALL questions MUST be polls — no plain-text questions + • Batch ALL questions into ONE message — do NOT send questions one at a time + • Each poll must have 2-4 options (system adds "Something else" automatically) + • Keep options short (under 50 chars each) + • Send as many polls as needed per message (up to 10 total across the project) + • For complex projects (SaaS, portals, multi-module): ask 5-8 questions + • For simple projects (landing page, game): ask 1-3 or skip entirely + +──────────────────────────────────────────────────────────────────────────────── +6. FEEDBACK LOOP +──────────────────────────────────────────────────────────────────────────────── + +When the founder sends feedback after deployment: + 1. Log the feedback via send_socket_message type:"log". + 2. Analyze what changes are needed. + 3. Delegate to the Developer to implement the changes. + 4. Re-run ALL THREE test loops (feature, UI/UX, responsive). + 5. Redeploy: bash deploy.sh [nixpacks|static|dockerfile] + 6. Verify the production URL with curl. + 7. Send the updated production URL to the founder. + 8. Post a milestone: "Feedback implemented and redeployed." + +Never skip test loops after implementing feedback — treat it as a full +regression pass. + +──────────────────────────────────────────────────────────────────────────────── +7. URLs — CRITICAL RULE +──────────────────────────────────────────────────────────────────────────────── + +NEVER send localhost URLs to the founder. The founder CANNOT access localhost, +127.0.0.1, or any internal URLs. These are internal to the container only. + +The ONLY URLs you may share with the founder are: + • Production URLs from Coolify (after deployment in Phase 9) + • Gitea repo URLs (e.g. https://gitea.tenx.dot8.in/pankaj/) + +For YOUR OWN internal testing (curl checks, Playwright tests), you can use: + http://localhost:8080/6c14b994-a30b-495b-82bd-77ee501777cd/ +But NEVER send this URL to the founder via milestone, preview, or question. + +If the founder asks to see progress before deployment, tell them: + "I'm still building and testing — I'll share the live URL once deployed." + +──────────────────────────────────────────────────────────────────────────────── +8. GENERAL RULES +──────────────────────────────────────────────────────────────────────────────── + +• You are autonomous EXCEPT at the Phase 4 gate — you MUST wait for founder + approval before starting development. All other phases proceed automatically. +• If the founder sends a message mid-build (e.g., "wait", "stop", "change + the design"), STOP what you are doing and address their request first. +• If you encounter an error, debug it. Log the error, attempt a fix, and + continue. Do not stall. +• Always call get_project_state when resuming from suspension. +• Use transition_phase to formally move between phases. +• Be concise in milestone messages — the founder wants progress, not essays. +• COST EFFICIENCY: Do not repeat work. If designs exist, don't regenerate + them. If code works, don't rewrite it. If 2 test cycles pass, don't run 5. + Scale your effort to the project's complexity. +• ALL code must be committed to git and pushed to Gitea before deployment. +• ALL deployments MUST use the deploy.sh script: bash deploy.sh + Do NOT use Coolify MCP tools directly — they require full Gitea URLs and + are error-prone. deploy.sh handles git, Gitea, and Coolify correctly. + This is NON-NEGOTIABLE. If you call Coolify MCP tools directly instead + of deploy.sh, the deployment WILL fail. + +──────────────────────────────────────────────────────────────────────────────── +9. DEPLOYMENT — deploy.sh +──────────────────────────────────────────────────────────────────────────────── + +A deploy.sh script is pre-installed in every project workspace. It handles the +ENTIRE deployment pipeline in one command: + + bash deploy.sh [nixpacks|static|dockerfile] + +What it does automatically: + 1. git add + commit + 2. Creates Gitea repo (if doesn't exist) + 3. Pushes to Gitea + 4. Creates Coolify app (if doesn't exist) or redeploys + 5. Waits for deployment + 6. Prints the production URL + +Build types: + • "static" — HTML/CSS-only (design mockups, landing pages) + • "nixpacks" — Node.js, Python, Go (auto-detects from package.json etc.) + • "dockerfile" — uses Dockerfile in project root + +██ MANDATORY: USE deploy.sh FOR EVERY DEPLOYMENT ██ +The ONLY way to deploy is: + bash deploy.sh [nixpacks|static|dockerfile] +Do NOT curl the Coolify API directly. Do NOT use $COOLIFY_ACCESS_TOKEN +or $COOLIFY_BASE_URL in your own curl commands. Those env vars exist for +deploy.sh only. If you bypass deploy.sh, you are wasting tokens and money +constructing curl commands that the script already handles correctly. +EVERY deployment = deploy.sh. No exceptions. No curl workarounds. + +Examples: + bash deploy.sh party-game-designs static # deploy design mockups + bash deploy.sh party-game nixpacks # deploy the full app + bash deploy.sh party-game dockerfile # deploy with Dockerfile + +Gitea: https://gitea.tenx.dot8.in +Coolify: https://coolify.tenx.dot8.in + +NEVER tell the founder to deploy manually. You own the full pipeline. + +──────────────────────────────────────────────────────────────────────────────── +11. OBSERVABILITY — SIGNOZ APM +──────────────────────────────────────────────────────────────────────────────── + +Every deployed app MUST have SigNoz APM. This is non-negotiable. + +SigNoz instance: http://100.64.0.10:3301 +OTel collector endpoint: http://100.64.0.10:4318 + +DURING DEVELOPMENT (Phase 5): + The Developer MUST add OpenTelemetry instrumentation to apps with a backend. + Do NOT add SigNoz to static HTML sites or design mockup pages. + • Node.js: @opentelemetry/auto-instrumentations-node + OTLP HTTP exporter + • Python: opentelemetry-distro + opentelemetry-exporter-otlp + • Service name = project name + • Traces, metrics, and logs exported to SIGNOZ_OTEL_ENDPOINT + +AFTER DEPLOYMENT (Phase 9+): + Use SigNoz MCP tools to: + 1. Verify traces are flowing — check that the service appears in SigNoz + 2. Monitor for errors — query error traces and logs + 3. Check latency — p50/p95/p99 response times + 4. If errors or performance issues are found: + a. Use SigNoz MCP to get the trace details and stack traces + b. Delegate the fix to the Developer + c. Commit, push to Gitea, redeploy via Coolify + d. Verify the fix via SigNoz + 5. Post a milestone to the founder: "App is live and monitored — no errors" + OR "Found and fixed X errors in production" + +The full pipeline: code → SigNoz instrumentation → git → Gitea → Coolify → +production → SigNoz monitors → errors detected → auto-fix → redeploy. \ No newline at end of file diff --git a/.claude/skills/ui-ux-pro-max/skill.md b/.claude/skills/ui-ux-pro-max/skill.md new file mode 100644 index 0000000..7cc8553 --- /dev/null +++ b/.claude/skills/ui-ux-pro-max/skill.md @@ -0,0 +1,427 @@ +# UI/UX Pro Max - Design Skill + +You are an expert UI/UX designer. Follow these rules when creating, reviewing, or modifying any user interface. Every decision must be intentional, accessible, and grounded in proven design principles. + +--- + +## 1. Color Theory & Accessibility + +### Contrast Requirements +- **WCAG AA (minimum):** 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold) +- **WCAG AAA (enhanced):** 7:1 for normal text, 4.5:1 for large text +- **Non-text elements:** 3:1 contrast ratio for UI components and graphical objects +- Always verify contrast ratios before finalizing any color pairing + +### Color Usage Rules +- Never use color as the sole indicator of meaning (add icons, patterns, or text labels) +- Limit primary palette to 1 brand color + 1-2 accent colors + neutrals +- Use semantic color tokens: `--color-success`, `--color-warning`, `--color-error`, `--color-info` +- Ensure color consistency across light and dark themes +- Test all color choices with a color-blindness simulator (protanopia, deuteranopia, tritanopia) + +### Palette Construction +- Choose a primary hue, then derive shades in 9-11 steps (50, 100, 200 ... 900, 950) +- Neutral palette should have a subtle warm or cool tint matching the primary +- Reserve saturated colors for interactive elements and key indicators +- Background colors: keep saturation below 5% for large surfaces +- Use opacity-based overlays (`rgba`) for layering rather than unique hex values + +--- + +## 2. Typography + +### Font Selection +- Use a maximum of 2 typefaces: one for headings, one for body +- Prefer system font stacks for performance: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif` +- If using custom fonts, always declare fallbacks and use `font-display: swap` +- Ensure chosen fonts support all required character sets and weights + +### Type Scale (Major Third - 1.25 ratio) +``` +--text-xs: 0.75rem (12px) +--text-sm: 0.875rem (14px) +--text-base: 1rem (16px) ← body default +--text-lg: 1.125rem (18px) +--text-xl: 1.25rem (20px) +--text-2xl: 1.5rem (24px) +--text-3xl: 1.875rem (30px) +--text-4xl: 2.25rem (36px) +--text-5xl: 3rem (48px) +``` + +### Line Height +- Body text: 1.5 - 1.6 (24-26px at 16px base) +- Headings: 1.1 - 1.3 +- Captions and labels: 1.4 +- Never go below 1.1 for any text + +### Letter Spacing +- Body text: 0 (default) +- Headings (large): -0.01em to -0.02em for tighter look +- All-caps labels: 0.05em to 0.1em +- Small text: +0.01em for readability + +### Paragraph Rules +- Maximum line length: 60-75 characters (use `max-width: 65ch` on text containers) +- Paragraph spacing: 1em between paragraphs +- Avoid justified text on the web (use left-aligned) +- Minimum body font size: 16px on mobile, 14px on desktop + +--- + +## 3. Spacing & Layout System + +### 8px Grid +All spacing values must be multiples of 4px, preferring 8px increments: +``` +--space-0: 0 +--space-1: 0.25rem (4px) +--space-2: 0.5rem (8px) +--space-3: 0.75rem (12px) +--space-4: 1rem (16px) +--space-5: 1.25rem (20px) +--space-6: 1.5rem (24px) +--space-8: 2rem (32px) +--space-10: 2.5rem (40px) +--space-12: 3rem (48px) +--space-16: 4rem (64px) +--space-20: 5rem (80px) +--space-24: 6rem (96px) +``` + +### Layout Principles +- Use CSS Grid for page-level layout, Flexbox for component-level alignment +- Define consistent container max-widths: sm (640px), md (768px), lg (1024px), xl (1280px), 2xl (1536px) +- Apply horizontal padding to containers: 16px mobile, 24px tablet, 32px desktop +- Maintain consistent gutter widths within grids (16px or 24px) +- Content sections should have vertical rhythm using consistent spacing tokens + +### Whitespace +- More whitespace around higher-level groupings (sections > cards > inline elements) +- Padding inside containers: at least 16px +- Space between related items: 8-12px +- Space between unrelated groups: 24-48px +- Use `gap` property instead of margins on flex/grid children + +--- + +## 4. Component Design Patterns + +### Buttons +- **Sizes:** sm (32px height), md (40px height), lg (48px height) +- **Minimum width:** 80px for text buttons +- **Touch target:** minimum 44x44px (add padding if button is visually smaller) +- **Padding:** horizontal 16-24px, vertical 8-12px +- **Border radius:** 6-8px for modern feel, 4px for conservative +- **States:** default, hover, active/pressed, focus-visible, disabled, loading +- **Hierarchy:** primary (filled), secondary (outlined), tertiary/ghost (text-only) +- **Disabled buttons:** reduce opacity to 0.5, remove pointer events, add `aria-disabled` +- **Loading state:** replace label with spinner, maintain button width, disable interaction +- **Icon buttons:** always include `aria-label`, maintain square aspect ratio + +### Forms +- **Labels:** always visible above the input, never use placeholder as label +- **Input height:** 40-48px for comfortable touch targets +- **Input padding:** 12-16px horizontal +- **Border:** 1px solid with at least 3:1 contrast against background +- **Focus ring:** 2px solid brand color with 2px offset, or equivalent visual indicator +- **Error states:** red border + error icon + error message below the field +- **Error messages:** use `role="alert"` or `aria-live="polite"` for dynamic errors +- **Helper text:** place below input in muted color, 12-14px +- **Required fields:** mark with asterisk (*) and include "(required)" in aria-label +- **Field spacing:** 16-24px vertical gap between form fields +- **Submit buttons:** always at the bottom, full-width on mobile + +### Cards +- **Padding:** 16-24px +- **Border radius:** 8-12px +- **Elevation:** use box-shadow for depth (`0 1px 3px rgba(0,0,0,0.12)` for subtle) +- **Border:** optional 1px border for low-contrast backgrounds +- **Interactive cards:** add hover elevation change, cursor pointer, focus outline +- **Content order:** image/media > title > description > metadata > actions +- **Clickable cards:** wrap in `` or ` + + + +
+ + +
+ + + +
+
+ or continue with +
+
+ + + + +
+ Don't have an account? Register your company +
+ + + + + diff --git a/designs/03-register.html b/designs/03-register.html new file mode 100644 index 0000000..dd5a741 --- /dev/null +++ b/designs/03-register.html @@ -0,0 +1,304 @@ + + + + + +Register Your Company — HR Portal + + + + + +
+ +
Already have an account? Sign in
+
+ +
+ +
+
+
+ + + +
+ Company Info +
+
+
+
2
+ Admin Account +
+
+
+
3
+ Done +
+
+ +
+
+

Create your HR Portal account

+

Set up your company and admin account to get started in minutes.

+
+ + +
+
Company Information
+
+
+ + +
+
+ +
+ +
+
+
+ +
+ +
+
+
+ +
+ +
+
+
+ +
+ +
+
+
+
+ + +
+
Admin Account Details
+
+
+ + +
+
+ + +
+
+ + +

This will be your login email and primary admin contact.

+
+
+ + +
+
+ Strong password +
+
+
+ + +

Passwords match

+
+
+
+ +
+ + +
+ +
+ Sign in instead + +
+
+
+ + + diff --git a/designs/04-admin-dashboard.html b/designs/04-admin-dashboard.html new file mode 100644 index 0000000..1827a36 --- /dev/null +++ b/designs/04-admin-dashboard.html @@ -0,0 +1,653 @@ + + + + + +Dashboard — HR Portal + + + + + + + + + +
+ +
+
+ + + + +
+
+
+ + + + 3 +
+
+ + + +
+
SC
+
+
+ + +
+ + +
+
+
Good morning, Sarah! Here's what needs your attention.
+
You have 7 pending leave requests and 2 new job applications to review.
+
+
+
Friday, May 9, 2026
+ +
+
+ + +
+
+
+ Total Employees +
+ + + + +
+
+
248
+
+ + +5 this month +
+
+
+
+ On Leave Today +
+ + + +
+
+
12
+
4.8% of workforce
+
+
+
+ Pending Approvals +
+ + + + +
+
+
7
+
+ + Needs action today +
+
+
+
+ May Payroll +
+ + + + +
+
+
$284.5K
+
+ + +2.1% vs last month +
+
+
+ + +
+ +
+
+ Pending Leave Requests + View all (7) +
+
+
MR
+
+
Michael Rodriguez
+
May 12 – May 15  ·  4 days
+
+ Annual +
+ + +
+
+
+
PP
+
+
Priya Patel
+
May 13 – May 13  ·  1 day
+
+ Sick +
+ + +
+
+
+
JK
+
+
James Kim
+
May 19 – May 23  ·  5 days
+
+ Annual +
+ + +
+
+
+
AL
+
+
Aisha Larsson
+
May 26 – May 28  ·  3 days
+
+ Casual +
+ + +
+
+
+ + +
+
+ Recent Activity + View log +
+
+
+ + + +
+
+
David Thompson was added to Engineering team
+
2 hours ago
+
+
+
+
+ + + +
+
+
Leave request for Ravi Shankar was approved
+
3 hours ago
+
+
+
+
+ + + +
+
+
April payroll of $278,400 was processed
+
Yesterday, 4:30 PM
+
+
+
+
+ + + +
+
+
New job posted: Senior Frontend Engineer
+
Yesterday, 2:00 PM
+
+
+
+
+ + + +
+
+
Company announcement sent to all employees
+
May 8, 10:00 AM
+
+
+
+
+ + +
+ +
+
+ Department Overview + Manage +
+
+ Engineering +
+
+
+ 45 +
+
+ Operations +
+
+
+ 31 +
+
+ Sales +
+
+
+ 24 +
+
+ Marketing +
+
+
+ 18 +
+
+ Finance +
+
+
+ 12 +
+
+ HR +
+
+
+ 8 +
+
+ + +
+
+ Announcements + Post new +
+
+
+ Company + Pinned +
+
Q2 Performance Reviews Starting May 15
+
All managers must complete peer review forms by May 20. Self-assessments open from May 10.
+
Posted by Sarah Chen  ·  2 days ago
+
+
+
+ Policy +
+
Updated Remote Work Policy
+
Effective June 1, employees may work remotely up to 3 days per week with manager approval.
+
Posted by HR Team  ·  May 7, 2026
+
+
+
+ +
+
+ + + diff --git a/designs/05-employee-directory.html b/designs/05-employee-directory.html new file mode 100644 index 0000000..e97deab --- /dev/null +++ b/designs/05-employee-directory.html @@ -0,0 +1,312 @@ + + + + + +Employees — HR Portal + + + + + + + +
+
+
+ Home + + Employees +
+
+
+ + 3 +
+
SC
+
+
+ +
+
+
+
Employees
+
+
+
+ Total: + 248 +
+
+
+ On Leave: + 12 +
+
+
+ New This Month: + 5 +
+
+
+ + + Add Employee + +
+ +
+
+ + +
+ + + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EmployeeDepartmentDesignationJoin DateStatusActions
SC
Sarah Chen
sarah.chen@techflow.com
HRHR DirectorJan 15, 2022Active
View
MR
Michael Rodriguez
m.rodriguez@techflow.com
EngineeringSenior EngineerMar 8, 2021Active
View
PP
Priya Patel
priya.patel@techflow.com
FinanceFinancial AnalystJun 22, 2022On Leave
View
JK
James Kim
james.kim@techflow.com
EngineeringFrontend DeveloperSep 5, 2023Active
View
AL
Aisha Larsson
a.larsson@techflow.com
MarketingMarketing ManagerFeb 14, 2023Active
View
RS
Ravi Shankar
ravi.shankar@techflow.com
OperationsOperations LeadNov 12, 2020Active
View
DT
Diana Torres
d.torres@techflow.com
SalesSales RepresentativeApr 3, 2024Active
View
NW
Noah Williams
n.williams@techflow.com
EngineeringDevOps EngineerJul 19, 2022Inactive
View
+ +
+
+
+ + + diff --git a/designs/06-employee-profile.html b/designs/06-employee-profile.html new file mode 100644 index 0000000..510df30 --- /dev/null +++ b/designs/06-employee-profile.html @@ -0,0 +1,383 @@ + + + + + +Employee Profile — HR Portal + + + + + + + +
+
+
+ Home + + Employees + + Michael Rodriguez +
+
+
3
+
SC
+
+
+ +
+
+
+ + + Back + +
Michael Rodriguez
+
+
+ + +
+
+ + +
+
MR
+
+
Michael Rodriguez
+
Senior Software Engineer
+
+ Engineering + Active + Full-time +
+
+
+ + m.rodriguez@techflow.com +
+
+ + +1 (415) 555-0187 +
+
+ + Joined Mar 8, 2021 +
+
+ + Reports to: Ravi Shankar +
+
+
+
+
+
4.2
+
Performance Score
+
+
+
98%
+
Attendance Rate
+
+
+
168h
+
Hours This Month
+
+
+
+ + +
+ Overview + Leave + Attendance + Payslips + Documents + Performance +
+ + +
+
+
+ Personal Information + Edit +
+
+
+
Full Name
+
Michael David Rodriguez
+
+
+
Date of Birth
+
April 14, 1990
+
+
+
Gender
+
Male
+
+
+
Nationality
+
American
+
+
+
Address
+
1247 Market Street, Apt 4B, San Francisco, CA 94103
+
+
+
Emergency Contact
+
Elena Rodriguez (Wife)
+
+
+
Emergency Phone
+
+1 (415) 555-0234
+
+
+
+
+
+ Employment Details + Edit +
+
+
+
Employee ID
+
EMP-0042
+
+
+
Department
+
Engineering
+
+
+
Designation
+
Senior Software Engineer
+
+
+
Employment Type
+
Full-time
+
+
+
Date of Joining
+
March 8, 2021
+
+
+
Work Location
+
San Francisco HQ
+
+
+
Manager
+
Ravi Shankar
+
+
+
Salary Band
+
Senior (L4)
+
+
+
+
+ + +
Leave Balance
+
+
+
Annual Leave
+
+
+
18 days used
+
of 20 days
+
+
+
+
Sick Leave
+
+
+
5 days used
+
of 10 days
+
+
+
+
Casual Leave
+
+
+
3 days used
+
of 5 days
+
+
+
+ + +
This Month
+
+
+
+ +
+
+
168h 20m
+
Working Hours
+
+
+
+
+ +
+
+
98.2%
+
Attendance Rate
+
+
+
+
+ +
+
+
4.2 / 5.0
+
Performance Score
+
+
+
+ +
+
+ + + diff --git a/designs/07-add-employee.html b/designs/07-add-employee.html new file mode 100644 index 0000000..9b8ee54 --- /dev/null +++ b/designs/07-add-employee.html @@ -0,0 +1,365 @@ + + + + + +Add Employee — HR Portal + + + + + + + +
+
+
+ Home + + Employees + + Add New Employee +
+
+ Cancel + +
SC
+
+
+ +
+
+
+
Add New Employee
+
Fill in the details below to create a new employee record.
+
+
+ + +
+
+
1
+
+
Personal Information
+
Basic personal details of the employee
+
+
+
+
+
+
+ +
+
+ +
PNG or JPG, max 2MB. Recommended 200x200px.
+
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
+ +
+
+
+ + +
+
+
+
+ + +
+
+
2
+
+
Employment Details
+
Role, department, and reporting structure
+
+
+
+
+
+ +
+ +
+
+
+ + +
+
+ +
+ +
+
+
+ + +
+
+ +
+ +
+
+
+ +
+ +
+
+
+
+
+ + +
+
+
3
+
+
Compensation
+
Salary structure and pay details
+
+
+
+
+
+ +
+ +
+
Salary structure defines base pay, allowances, and deduction rules.
+
+
+ + +
+
+
+
+ + +
+
+
4
+
+
Account Setup
+
Configure login credentials and access
+
+
+
+
+
+
+ + +
+
A welcome email with login credentials will be sent to the employee's work email address.
+
+
+
+ + +
+
+
+
+ + +
+
+
+
+
+ +
+ +
+
All fields marked with * are required
+
+ Discard + +
+
+
+ + + diff --git a/designs/08-department-management.html b/designs/08-department-management.html new file mode 100644 index 0000000..39ccd49 --- /dev/null +++ b/designs/08-department-management.html @@ -0,0 +1,331 @@ + + + + + +Departments — HR Portal + + + + + + + +
+
+
+ Home + + Departments +
+
+
3
+
SC
+
+
+ +
+
+
+
Departments
+
6 departments  ·  138 employees total
+
+ +
+ +
+ +
+
+
+ +
+
+ + +
+
+
+
Engineering
+
Product development, software engineering, DevOps, and technical architecture.
+
+
MR
+
+
Head of Department
+
Michael Rodriguez
+
+
+
+
+ + 45 employees +
+ View team +
+
+
+ + +
+
+
+ +
+
+ + +
+
+
+
Human Resources
+
Talent acquisition, employee relations, benefits, and organizational development.
+
+
SC
+
+
Head of Department
+
Sarah Chen
+
+
+
+
+ + 8 employees +
+ View team +
+
+
+ + +
+
+
+ +
+
+ + +
+
+
+
Finance
+
Financial planning, accounting, payroll processing, and audit compliance.
+
+
PP
+
+
Head of Department
+
Priya Patel
+
+
+
+
+ + 12 employees +
+ View team +
+
+
+ + +
+
+
+ +
+
+ + +
+
+
+
Marketing
+
Brand management, digital marketing, content strategy, and growth campaigns.
+
+
AL
+
+
Head of Department
+
Aisha Larsson
+
+
+
+
+ + 18 employees +
+ View team +
+
+
+ + +
+
+
+ +
+
+ + +
+
+
+
Operations
+
Supply chain management, facilities, vendor relations, and business processes.
+
+
RS
+
+
Head of Department
+
Ravi Shankar
+
+
+
+
+ + 31 employees +
+ View team +
+
+
+ + +
+
+
+ +
+
+ + +
+
+
+
Sales
+
Revenue generation, account management, business development, and customer success.
+
+
DT
+
+
Head of Department
+
Diana Torres
+
+
+
+
+ + 24 employees +
+ View team +
+
+
+
+
+
+ + + diff --git a/designs/09-leave-requests.html b/designs/09-leave-requests.html new file mode 100644 index 0000000..d5b4d0e --- /dev/null +++ b/designs/09-leave-requests.html @@ -0,0 +1,322 @@ + + + + + +Leave Requests — HR Portal + + + + + + + +
+
+
+ Home + + Leave Management +
+
+
3
+
SC
+
+
+ +
+
+
Leave Requests
+
+ + + Leave Types + + +
+
+ +
+ All Requests 52 + Pending 7 + Approved 38 + Rejected 7 +
+ +
+
+ + +
+ + + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EmployeeLeave TypeFromToDaysReasonStatusActions
MR
Michael Rodriguez
Engineering
Annual LeaveMay 12, 2026May 15, 20264Family vacation, planned in advancePending
PP
Priya Patel
Finance
Sick LeaveMay 13, 2026May 13, 20261Fever and cold, doctor's appointmentPending
JK
James Kim
Engineering
Annual LeaveMay 19, 2026May 23, 20265Wedding anniversary trip abroadPending
AL
Aisha Larsson
Marketing
Casual LeaveMay 26, 2026May 28, 20263Personal errands and home renovationPending
RS
Ravi Shankar
Operations
Annual LeaveJun 2, 2026Jun 6, 20265Family visit and religious festivalApproved
DT
Diana Torres
Sales
Sick LeaveMay 7, 2026May 8, 20262Migraine, needed bed restApproved
NW
Noah Williams
Engineering
BereavementApr 28, 2026Apr 30, 20263Loss of grandparent, funeral attendanceApproved
LO
Lucas Oliveira
Operations
Annual LeaveApr 14, 2026Apr 18, 20265Planned vacation to MexicoRejected
FA
Fatima Al-Rashid
Finance
Casual LeaveMay 9, 2026May 9, 20261Urgent bank errandPending
KL
Kevin Liu
Marketing
Sick LeaveMay 5, 2026May 6, 20262Food poisoning, doctor advised restApproved
+ +
+
+
+ + + diff --git a/designs/10-leave-types.html b/designs/10-leave-types.html new file mode 100644 index 0000000..9e7d281 --- /dev/null +++ b/designs/10-leave-types.html @@ -0,0 +1,293 @@ + + + + + +Leave Types — HR Portal + + + + + + + +
+
+
+ Home + + Leave Management + + Leave Types +
+
+
3
+
SC
+
+
+ +
+ + + Back to Leave Requests + +
+
+
Leave Types
+
Configure leave policies, entitlements, and eligibility rules
+
+ +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Leave TypeCodeDays / YearCarry ForwardRequires ApprovalApplicable ToStatusActions
+
+
+
+
Annual Leave
+
Used for vacations & personal time
+
+
+ 		AL20 days +
+ + Up to 10 days +
+ 		All Employees + + +
+ + +
+
+
+
+
+
Sick Leave
+
Medical and health related absences
+
+
+ 		SL10 days +
+ + Self-approve +
+ 		All Employees
+
+
+
+
Casual Leave
+
Short-term personal reasons
+
+
+ 		CL5 daysAll Employees
+
+
+
+
Maternity Leave
+
Paid leave for new mothers
+
+
+ 		ML90 daysFemale Employees
+
+
+
+
Paternity Leave
+
Paid leave for new fathers
+
+
+ 		PL5 daysMale Employees
+
+
+
+
Bereavement Leave
+
Leave for family loss and mourning
+
+
+ 		BL3 daysAll Employees
+
+
+
+ + + diff --git a/designs/11-attendance.html b/designs/11-attendance.html new file mode 100644 index 0000000..4cdb081 --- /dev/null +++ b/designs/11-attendance.html @@ -0,0 +1,293 @@ + + + + + +Attendance — HR Portal + + + + + + + +
+
+
+ Home + + Attendance +
+
+
3
+
SC
+
+
+ +
+
+
Attendance Log
+
+ +
+
+ +
+
Daily
+
Monthly
+
Calendar View
+
+ +
+ + + +
+ +
+
+
+
198
Present
+
+
+
+
12
Absent
+
+
+
+
15
On Leave
+
+
+
+
5
Half Day
+
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EmployeeCheck InCheck OutWorking HoursStatusNotes
MR
Michael Rodriguez
Engineering
09:02 AM
06:15 PM
9h 13m
Present—
PP
Priya Patel
Finance
—
—
—
On LeaveSick leave approved
JK
James Kim
Engineering
09:45 AM
06:30 PM
8h 45m
Late ArrivalTraffic delay
AL
Aisha Larsson
Marketing
08:55 AM
05:55 PM
9h 00m
Present—
RS
Ravi Shankar
Operations
08:30 AM
01:00 PM
4h 30m
Half DayDoctor appointment PM
DT
Diana Torres
Sales
09:00 AM
06:05 PM
9h 05m
Present—
LO
Lucas Oliveira
Operations
—
—
—
AbsentNo notice provided
FA
Fatima Al-Rashid
Finance
08:48 AM
05:50 PM
9h 02m
Present—
NW
Noah Williams
Engineering
09:15 AM
06:20 PM
9h 05m
PresentWFH approved
KL
Kevin Liu
Marketing
09:00 AM
06:00 PM
9h 00m
Present—
+
+ Showing 1–10 of 230 employees +
+ + + + + +
+
+
+
+
+ + + diff --git a/designs/12-payroll-dashboard.html b/designs/12-payroll-dashboard.html new file mode 100644 index 0000000..db285a5 --- /dev/null +++ b/designs/12-payroll-dashboard.html @@ -0,0 +1,278 @@ + + + + + +Payroll — HR Portal + + + + + + + +
+
+
+ Home + + Payroll +
+
+
3
+
SC
+
+
+ +
+
+
Payroll
+
+ + May 2026 + +
+
+ + +
+
+
May 2026 Payroll
+
Payroll has not been generated yet. Review attendance and leave data before processing.
+
+ + Not Generated +
+
+
+
Pay date: May 31, 2026
+ +
+
+ + +
+
+
Total Employees
+
248
+
On active payroll
+
+
+
Gross Payroll
+
$284,500
+
+2.1% vs April
+
+
+
Total Deductions
+
$43,200
+
Tax, PF, insurance
+
+
+
Net Payable
+
$241,300
+
After all deductions
+
+
+ + +
+ +
+
+ Salary Structures + Manage +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Structure NameBase SalaryEmployees
Junior (L1)
$60K – $85K / year
$6,800/mo42
Mid-Level (L2)
$85K – $110K / year
$8,200/mo98
Senior (L3)
$110K – $145K / year
$10,500/mo67
Senior (L4)
$145K – $180K / year
$13,200/mo28
Lead (L5+)
$180K – $220K / year
$17,000/mo13
+
+ + +
+
+ Recent Payroll History + View all +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PeriodNet PayableEmployeesStatus
April 2026$235,800244Paid
March 2026$231,200241Paid
February 2026$228,500239Paid
January 2026$224,900236Paid
+
+
+
+
+ + + diff --git a/designs/13-recruitment.html b/designs/13-recruitment.html new file mode 100644 index 0000000..59d9335 --- /dev/null +++ b/designs/13-recruitment.html @@ -0,0 +1,346 @@ + + + + + +Recruitment — HR Portal + + + + + + + +
+
+
+ Home + + Recruitment +
+
+
3
+
SC
+
+
+ +
+
+
+
Recruitment
+
4 open positions  ·  19 total applicants
+
+ +
+ + +
+
+
+
+
Senior Frontend Engineer
+
Engineering
+
+
+
+
+ Full-time +
+ + San Francisco +
+
+ + 12 days open +
+
+
+
8
Applicants
+ +
+
+ +
+
+
+
Product Designer
+
Design
+
+
+
+
+ Full-time +
+ + Remote +
+
+ + 5 days open +
+
+
+
5
Applicants
+ +
+
+ +
+
+
+
Sales Account Manager
+
Sales
+
+
+
+
+ Full-time +
+ + New York +
+
+ + 3 days open +
+
+
+
3
Applicants
+ +
+
+ +
+
+
+
DevOps Engineer
+
Engineering
+
+
+
+
+ Contract +
+ + Remote +
+
+ + 8 days open +
+
+
+
3
Applicants
+ +
+
+
+ + +
+
+
Pipeline: Senior Frontend Engineer
+
Showing applicants for this role — click a job card above to switch
+
+
+ +
+ +
+
+ Applied + 8 +
+
+
AT
+
Alex Thompson
+
Applied May 8, 2026
+ +
+
+
MK
+
Maya Kumar
+
Applied May 9, 2026
+ +
+
+ + +
+
+ Screening + 5 +
+
+
JL
+
Jordan Lee
+
Screening since May 5
+ +
+
+
SP
+
Sofia Park
+
Screening since May 6
+ +
+
+ + +
+
+ Interview + 3 +
+
+
RN
+
Ryan Nakamura
+
Interview May 11, 2026
+ +
+
+
EC
+
Elena Costa
+
Interview May 12, 2026
+ +
+
+ + +
+
+ Offer + 1 +
+
+
LM
+
Luis Martinez
+
Offer sent May 7, 2026
+ +
+
+ + +
+
+ Hired + 2 +
+
+
DB
+
David Blake
+
Hired April 28, 2026
+ Start: May 15 +
+
+
AS
+
Anika Singh
+
Hired May 2, 2026
+ Start: June 1 +
+
+
+
+
+ + + diff --git a/designs/14-expense-claims.html b/designs/14-expense-claims.html new file mode 100644 index 0000000..c858c8b --- /dev/null +++ b/designs/14-expense-claims.html @@ -0,0 +1,293 @@ + + + + + +Expense Claims — HR Portal + + + + + + + +
+
+
+ Home + + Expense Claims +
+
+
3
+
SC
+
+
+ +
+
+
Expense Claims
+
+ + +
+
+ +
+
All 42
+
Pending 9
+
Approved 24
+
Reimbursed 9
+
+ +
+
+ + +
+ + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EmployeeTitleCategoryAmountReceiptSubmittedStatusActions
MR
Michael Rodriguez
Engineering
AWS Re:Invent Conference
Las Vegas, NV
Travel$1,240.00May 7, 2026Pending
DT
Diana Torres
Sales
Client Dinner — Acme Corp
Restaurant receipt
Meals$340.00May 6, 2026Pending
AL
Aisha Larsson
Marketing
MacBook Pro Stand & Hub
Remote work equipment
Equipment$178.50May 5, 2026Pending
RS
Ravi Shankar
Operations
Marriott — Austin Summit
2 nights accommodation
Accommodation$520.00Apr 28, 2026Approved
JK
James Kim
Engineering
Team Lunch — Sprint Review
Pizza delivery for 8 people
Meals$186.00May 2, 2026Approved
PP
Priya Patel
Finance
Uber — Client Site Visits
April 22–24 rides
Travel$92.40Apr 24, 2026Reimbursed
FA
Fatima Al-Rashid
Finance
QuickBooks Subscription
Annual software license
Equipment$299.00May 8, 2026Pending
LO
Lucas Oliveira
Operations
Marriott — Operations Summit
3 nights accommodation
Accommodation$780.00Apr 20, 2026Reimbursed
+
+ Showing 1–8 of 42 claims +
+ + + + +
+
+
+
+
+ + + diff --git a/designs/15-performance-reviews.html b/designs/15-performance-reviews.html new file mode 100644 index 0000000..faf1796 --- /dev/null +++ b/designs/15-performance-reviews.html @@ -0,0 +1,287 @@ + + + + + +Performance Reviews — HR Portal + + + + + + + +
+
+
+ Home + + Performance Reviews +
+
+
3
+
SC
+
+
+ +
+
+
Performance Reviews
+ +
+ + +
+
+
+ + Active Cycle +
+
Q1 2026 Annual Performance Review
+
Self-assessments, peer reviews, and manager evaluations in progress
+
+
+ Overall completion + 68% +
+
+
+
+
+ + Jan 1 – Mar 31, 2026 +
+
+ + Deadline: May 20, 2026 +
+
+
+
+ +
+
+
168
+
Completed
+
+
+
80
+
Pending
+
+
+
248
+
Total
+
+
+
+
+ + +
All Review Cycles
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Cycle NamePeriodTypeStatusCompletionActions
+
Q1 2026 Annual Review
+
Includes self, peer, and manager review
+ 		Jan 1 – Mar 31, 2026AnnualIn Progress +
+
+ 68% +
+ 		+ + +
+
Q4 2025 Annual Review
+
Full 360-degree review cycle
+ 		Oct 1 – Dec 31, 2025AnnualCompleted +
+
+ 100% +
+ 		+ +
+
Mid-Year 2025 Review
+
Manager review only
+ 		Apr 1 – Jun 30, 2025Mid-YearCompleted +
+
+ 100% +
+ 		+ +
+
Q2 2025 Annual Review
+
Self and manager review
+ 		Jan 1 – Mar 31, 2025AnnualCompleted +
+
+ 100% +
+ 		+ +
+
+
+
+ + + diff --git a/designs/16-reports.html b/designs/16-reports.html new file mode 100644 index 0000000..a715846 --- /dev/null +++ b/designs/16-reports.html @@ -0,0 +1,315 @@ + + + + + +Reports — HR Portal + + + + + + + +
+
+
+ Home + + Reports & Analytics +
+
+
3
+
SC
+
+
+ +
+
+
Reports & Analytics
+
+
+ + to + +
+ +
+
+ +
+ + +
+
+ Headcount Over Time + Export CSV +
+
+
248
+
Current headcount  ·  +19 this year
+
+ + + + + + + + + + +
+
+ Jan + Feb + Mar + Apr + May +
+
+
+ + +
+
+ Leave Utilization by Type + Export CSV +
+
+
487
+
Total leave days taken YTD
+
+
Annual Leave248 days
+
+
+
+
Sick Leave142 days
+
+
+
+
Casual Leave68 days
+
+
+
+
Other29 days
+
+
+
+
+ + +
+
+ Attendance Rate Trend + Export CSV +
+
+
94.6%
+
Average attendance rate YTD
+
+ + + + + + + + + + +
+
+ Jan + Feb + Mar + Apr + May +
+
+
+ + +
+
+ Payroll by Month + Export CSV +
+
+
$1.18M
+
Total payroll YTD (net)
+
+
Jan
+
Feb
+
Mar
+
Apr
+
May
+
+
+
+ + +
+
+ Department Breakdown + Export CSV +
+
+
6
+
Active departments
+
+
+
+
Engineering32%
+
Operations22%
+
Sales17%
+
Marketing13%
+
Finance11%
+
HR5%
+
+
+
+
+ + +
+
+ Expense Claims by Category + Export CSV +
+
+
$28,430
+
Total claims YTD  ·  84 claims
+
+
Travel$12,800
+
+
+
+
Equipment$8,400
+
+
+
+
Accommodation$4,600
+
+
+
+
Meals$2,630
+
+
+
+
+ +
+
+
+ + + diff --git a/designs/17-settings.html b/designs/17-settings.html new file mode 100644 index 0000000..94ed99c --- /dev/null +++ b/designs/17-settings.html @@ -0,0 +1,281 @@ + + + + + +Settings — HR Portal + + + + + + + +
+
+
+ Home + + Settings +
+
+
3
+
SC
+
+
+ +
+
Settings
+
+ +
+
General
+
+ + Company Profile +
+
+ + Leave Settings +
+
+ + Work Hours +
+
System
+
+ + Notifications +
+
+ + Integrations +
+
+ + +
+
+
+
Company Profile
+
Update your company information and branding
+
+ + +
+
+
Company Logo
+
Appears on payslips, emails, and the employee portal
+
+
+
+
TF
+
Drag and drop your logo here, or click to browse
+
PNG, JPG, or SVG. Max 2MB. Recommended: 200×200px
+ +
+
+
+ + +
+
+
Company Information
+
+
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+
+
+ + +
+
+
Default Work Hours
+
Standard working days and hours for attendance tracking
+
+
+
Working Days
+
+ + + + + + + +
+
+
+ + +
+
+ + +
+
+
+
+ +
+ + +
+
+
+
+
+
+ + + diff --git a/designs/18-employee-dashboard.html b/designs/18-employee-dashboard.html new file mode 100644 index 0000000..549a508 --- /dev/null +++ b/designs/18-employee-dashboard.html @@ -0,0 +1,336 @@ + + + + + +My Dashboard — HR Portal + + + + + + + +
+
+ Employee Portal +
+
2
+
JD
+
+
+ +
+ +
+
+
Good morning, John! Ready for the day?
+
Friday, May 9, 2026  ·  You haven't checked in yet today
+
+ +
+ + +
+ +
+ +
+
Request Leave
+ +
+
+ +
+
Check In
+
+
+
+ +
+
View Payslips
+
+ +
+ +
+
My Profile
+ +
+ + +
+ +
+ +
+
+ Leave Balance + View all +
+
+
+
14
+
Annual
+
of 20 days
+
+
+
8
+
Sick
+
of 10 days
+
+
+
3
+
Casual
+
of 5 days
+
+
+
+ +
+
+ My Leave Requests + View all +
+ + + + + + + + + + + + + + + + + + + +
TypeDatesStatus
AnnualApr 7–11Approved
SickMar 22Approved
AnnualMay 26–28Pending
+
+
+ + +
+ +
+
+ May 2026 Attendance + Full view +
+
+
S
M
T
W
T
F
S
+
+
+
+
+
+
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
+
+ Present + Leave + Today +
+
+ +
+
+ Latest Payslip +
+
+
May 2026
+
$4,200.00
+
Net pay after deductions
+
+
+
Gross
+
$5,000
+
+
+
Tax
+
-$620
+
+
+
Benefits
+
-$180
+
+
+ +
+
+
+
+ + +
+ Announcements +
+
+
+
Company
+
Q2 Performance Reviews Starting May 15
+
Self-assessments open May 10. Please complete your self-review by May 18 and peer reviews by May 20.
+
2 days ago
+
+
+
Policy
+
Updated Remote Work Policy Effective June 1
+
Employees may work remotely up to 3 days per week with manager approval. Full details in the HR handbook.
+
May 7, 2026
+
+
+
Benefits
+
Open Enrollment for Health Benefits — Closes May 31
+
Annual open enrollment is now open. Review your options and make changes in the benefits portal before the deadline.
+
May 1, 2026
+
+
+
+
+ + + diff --git a/designs/19-my-leave.html b/designs/19-my-leave.html new file mode 100644 index 0000000..f425d19 --- /dev/null +++ b/designs/19-my-leave.html @@ -0,0 +1,261 @@ + + + + + +My Leave — HR Portal + + + + + + + +
+
+ Employee Portal +
+
2
+
JD
+
+
+ +
+
+
My Leave
+ +
+ + +
+
+
Annual Leave
+
14
+
days remaining of 20
+
+
6 days used · 0 pending
+
+
+
Sick Leave
+
8
+
days remaining of 10
+
+
2 days used · 0 pending
+
+
+
Casual Leave
+
3
+
days remaining of 5
+
+
2 days used · 0 pending
+
+
+ + +
+
+ New Leave Request + +
+
+
+ + +
+
+ +
+ + 3 days +
+
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+
+ + +
+
+
Leave History
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Leave TypeFromToDaysStatusReason
CasualMay 26May 283PendingFamily event and personal commitments
AnnualApr 7Apr 115ApprovedSpring vacation — Hawaii
SickMar 22Mar 221ApprovedSevere headache and fever
AnnualFeb 14Feb 141ApprovedAnniversary celebration
SickJan 9Jan 102ApprovedFlu — doctor's certificate attached
+
+
+
+ + + diff --git a/designs/20-org-chart.html b/designs/20-org-chart.html new file mode 100644 index 0000000..5203d59 --- /dev/null +++ b/designs/20-org-chart.html @@ -0,0 +1,351 @@ + + + + + +Org Chart — HR Portal + + + + + + + +
+
+
+ Home + + Organization Chart +
+
+
3
+
SC
+
+
+ +
+
+
+
Organization Chart
+
TechFlow Inc.  ·  248 employees
+
+
+ + +
+
+ + +
+
+ + +
+
+
RP
+
Robert Park
+
Chief Executive Officer
+
+
+
+ + +
+ + +
+ +
+
+
+
MR
+
Michael Rodriguez
+
VP Engineering
+
+
+
+
+
+
+
+
JK
+
James Kim
+
Frontend Dev
+
+
+
+
+
+
NW
+
Noah Williams
+
DevOps Engineer
+
+
+
+
+ + +
+
+
+
SC
+
Sarah Chen
+
HR Director
+
+
+
+
+
+
+
+
LM
+
Lily Martin
+
HR Specialist
+
+
+
+
+ + +
+
+
+
PP
+
Priya Patel
+
Finance Director
+
+
+
+
+
+
+
+
FA
+
Fatima Al-Rashid
+
Financial Analyst
+
+
+
+
+ + +
+
+
+
RS
+
Ravi Shankar
+
Operations Lead
+
+
+
+
+
+
+
+
LO
+
Lucas Oliveira
+
Ops Specialist
+
+
+
+
+
+
TH
+
Tom Huang
+
Ops Analyst
+
+
+
+
+
+ +
+ + +
+
+
+ Reports to +
+
+
+ C-Suite +
+
+
+ Department Head +
+
+
+ Team Member +
+
+
+
+
+ + + diff --git a/designs/index.html b/designs/index.html new file mode 100644 index 0000000..ad7afe3 --- /dev/null +++ b/designs/index.html @@ -0,0 +1,596 @@ + + + + + +HR Portal v5 — Design Mockups + + + + + +
+ +
Design Mockups
+
+ +
+
HR Portal v5 — Design Mockups
+
Pixel-perfect HTML/CSS mockups for all 20 screens of the HR management system. Click any card to preview.
+
+
+
20
+
Design Screens
+
+
+
3
+
Page Sections
+
+
+
100%
+
Self-contained HTML/CSS
+
+
+
+ +
+ + +
+
+
P
+
+
Public Pages 3 screens
+
+
+
+ + +
+
01
+
+
+
+
+
+
+
+
+
+
+
+
Screen 01
+
Landing Page
+
Public marketing page with hero, features, stats, testimonials
+ Public +
+ + + +
+
02
+
+
+
+
+
+
+
+
+
+
Screen 02
+
Login Page
+
Employee and admin sign-in with Google SSO option
+ Public +
+ + + +
+
03
+
+
+
1
+
+
2
+
+
3
+
+
+
+
+
+
+
+
+
+
+
Screen 03
+
Company Registration
+
Multi-step company setup with admin account creation
+ Public +
+ + +
+
+ + +
+
+
A
+
+
Admin Pages 15 screens
+
+
+
+ + +
+
04
+
+
+
+
+
+
+
+
+
+
Screen 04
+
Admin Dashboard
+
Stats, pending approvals, activity feed, announcements
+ Admin +
+ + + +
+
05
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Screen 05
+
Employee Directory
+
Filterable table of all employees with search and actions
+ Admin +
+ + + +
+
06
+
+
+
+
+
+
+
+
+
+
+
Screen 06
+
Employee Profile
+
Detailed profile with tabs: overview, leave, attendance, payslips
+ Admin +
+ + + +
+
07
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Screen 07
+
Add Employee
+
Multi-section form for personal info, employment, compensation
+ Admin +
+ + + +
+
08
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Screen 08
+
Department Management
+
Department cards with heads, employee counts, edit/delete
+ Admin +
+ + + +
+
09
+
+
+
+
+
+
+
+
+
+
+
+
+
Screen 09
+
Leave Requests
+
Tabbed leave request management with approve/reject actions
+ Admin +
+ + + +
+
10
+
+
+
+
+
+
+
+
+
+
+
+
+
Screen 10
+
Leave Types
+
Configure leave policies, days/year, carry forward, toggles
+ Admin +
+ + + +
+
11
+
+
+
+
+
+
+
+
+
+
+
+
Screen 11
+
Attendance Log
+
Daily attendance with check-in/out times, status badges
+ Admin +
+ + + +
+
12
+
+
+
+
+
+
+
+
+
Screen 12
+
Payroll Dashboard
+
Monthly payroll status, salary structures, history
+ Admin +
+ + + +
+
13
+
+
+
+
+
+
+
+
+
Screen 13
+
Recruitment
+
Job listings with Kanban pipeline for applicant stages
+ Admin +
+ + + +
+
14
+
+
+
+
+
+
+
+
+
+
+
+
Screen 14
+
Expense Claims
+
Expense submissions with category badges and receipt links
+ Admin +
+ + + +
+
15
+
+
+
+
+
+
+
+
+
+
+
Screen 15
+
Performance Reviews
+
Active review cycle with progress bar and history table
+ Admin +
+ + + +
+
16
+
+
+
+
+
+
+
+
+
+
+
+
+
Screen 16
+
Reports & Analytics
+
6 CSS-based charts: line, bar, donut, horizontal bars
+ Admin +
+ + + +
+
17
+
+
+
+
+
+
+
+
+
Screen 17
+
Settings
+
Company profile, logo upload, work hours config, sub-nav
+ Admin +
+ + +
+
+ + +
+
+
E
+
+
Employee Pages 3 screens
+
+
+
+ + +
+
18
+
+
+
+
+
+
+
+
+
+
Screen 18
+
Employee Dashboard
+
Personal dashboard: quick actions, leave balance, payslip, announcements
+ Employee +
+ + + +
+
19
+
+
+
+
+
+
+
+
+
+
Screen 19
+
My Leave
+
Leave balances, inline request form, and leave history
+ Employee +
+ + + +
+
20
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Screen 20
+
Org Chart
+
CSS-based org tree with CEO, department heads, and team members
+ Admin +
+ + +
+
+ +
+ + + + + diff --git a/playwright.config.ts b/playwright.config.ts new file mode 100644 index 0000000..6f75810 --- /dev/null +++ b/playwright.config.ts @@ -0,0 +1,21 @@ +import { defineConfig, devices } from '@playwright/test'; + +export default defineConfig({ + testDir: './tests', + outputDir: './test-results', + timeout: 30000, + retries: 0, + use: { + headless: true, + launchOptions: { + executablePath: '/usr/bin/chromium', + }, + screenshot: 'on', + trace: 'off', + }, + projects: [ + { name: 'mobile', use: { ...devices['iPhone 12'] } }, + { name: 'tablet', use: { viewport: { width: 768, height: 1024 } } }, + { name: 'desktop', use: { viewport: { width: 1440, height: 900 } } }, + ], +}); diff --git a/visual-test-runner.js b/visual-test-runner.js new file mode 100644 index 0000000..08d332b --- /dev/null +++ b/visual-test-runner.js @@ -0,0 +1,315 @@ +#!/usr/bin/env node +const puppeteer = require("puppeteer"); +const fs = require("fs"); +const path = require("path"); + +const DEFAULT_VIEWPORTS = { + mobile: { width: 375, height: 812 }, + tablet: { width: 768, height: 1024 }, + desktop: { width: 1440, height: 900 }, +}; + +async function run() { + const manifestPath = path.resolve(process.cwd(), "test-manifest.json"); + if (!fs.existsSync(manifestPath)) { + console.error("ERROR: test-manifest.json not found in", process.cwd()); + process.exit(1); + } + + const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")); + const baseUrl = manifest.baseUrl || "http://localhost:3000"; + const viewports = manifest.viewports + ? Object.fromEntries( + Object.entries(manifest.viewports).map(function (entry) { + return [entry[0], entry[1]]; + }) + ) + : DEFAULT_VIEWPORTS; + + const resultsDir = path.resolve(process.cwd(), "test-results"); + if (!fs.existsSync(resultsDir)) { + fs.mkdirSync(resultsDir, { recursive: true }); + } + + const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH || "chromium"; + var browser; + try { + browser = await puppeteer.launch({ + headless: "new", + executablePath: executablePath, + args: ["--no-sandbox", "--disable-setuid-sandbox", "--disable-gpu"], + }); + } catch (err) { + console.error("ERROR: Failed to launch browser:", err.message); + process.exit(1); + } + + var results = { pages: [], passed: 0, failed: 0, errors: [] }; + + for (var pi = 0; pi < (manifest.pages || []).length; pi++) { + var pageDef = manifest.pages[pi]; + var pageResult = { + id: pageDef.id, + url: baseUrl + (pageDef.path || "/"), + viewports: {}, + passed: true, + }; + + var vpEntries = Object.entries(viewports); + for (var vi = 0; vi < vpEntries.length; vi++) { + var vpName = vpEntries[vi][0]; + var vpSize = vpEntries[vi][1]; + var vpResult = { + viewport: vpName, + screenshots: [], + actions: [], + consoleErrors: [], + passed: true, + }; + + var browserPage = null; + try { + browserPage = await browser.newPage(); + await browserPage.setViewport(vpSize); + + var consoleErrors = []; + browserPage.on("console", function (msg) { + if (msg.type() === "error") { + consoleErrors.push(msg.text()); + } + }); + browserPage.on("pageerror", function (err) { + consoleErrors.push(err.message); + }); + + await browserPage.goto(pageResult.url, { + waitUntil: "networkidle2", + timeout: 30000, + }); + + if (pageDef.waitFor) { + await browserPage.waitForSelector(pageDef.waitFor, { timeout: 10000 }); + } + + var initialScreenshot = path.join( + resultsDir, + pageDef.id + "-" + vpName + "-initial.png" + ); + await browserPage.screenshot({ + path: initialScreenshot, + fullPage: true, + }); + vpResult.screenshots.push(initialScreenshot); + + var actions = pageDef.actions || []; + for (var ai = 0; ai < actions.length; ai++) { + var action = actions[ai]; + var actionResult = { id: action.id, type: action.type, passed: true, error: null }; + try { + await executeAction(browserPage, action); + + var actionScreenshot = path.join( + resultsDir, + pageDef.id + "-" + vpName + "-" + action.id + ".png" + ); + await browserPage.screenshot({ + path: actionScreenshot, + fullPage: true, + }); + vpResult.screenshots.push(actionScreenshot); + + if (action.expectAfter) { + var valid = await validateExpectations( + browserPage, + action.expectAfter + ); + if (!valid) { + actionResult.passed = false; + actionResult.error = "Expectation failed for " + action.id; + } + } + } catch (err) { + actionResult.passed = false; + actionResult.error = err.message; + } + + if (!actionResult.passed) { + vpResult.passed = false; + } + vpResult.actions.push(actionResult); + } + + vpResult.consoleErrors = consoleErrors; + if (consoleErrors.length > 0) { + vpResult.passed = false; + } + } catch (err) { + vpResult.passed = false; + vpResult.error = err.message; + results.errors.push({ + page: pageDef.id, + viewport: vpName, + error: err.message, + }); + } finally { + if (browserPage) { + await browserPage.close().catch(function () {}); + } + } + + if (!vpResult.passed) { + pageResult.passed = false; + } + pageResult.viewports[vpName] = vpResult; + } + + if (pageResult.passed) { + results.passed++; + } else { + results.failed++; + } + results.pages.push(pageResult); + } + + await browser.close(); + + var summaryPath = path.join(resultsDir, "summary.json"); + fs.writeFileSync(summaryPath, JSON.stringify(results, null, 2)); + + console.log(""); + console.log("=== Visual Test Results ==="); + console.log("Pages tested: " + results.pages.length); + console.log("Passed: " + results.passed); + console.log("Failed: " + results.failed); + + for (var ri = 0; ri < results.pages.length; ri++) { + var p = results.pages[ri]; + var icon = p.passed ? "PASS" : "FAIL"; + console.log(" [" + icon + "] " + p.id + " (" + p.url + ")"); + var vpKeys = Object.keys(p.viewports); + for (var vk = 0; vk < vpKeys.length; vk++) { + var vr = p.viewports[vpKeys[vk]]; + if (!vr.passed) { + console.log(" " + vpKeys[vk] + ": FAIL" + (vr.error ? " - " + vr.error : "")); + for (var ak = 0; ak < (vr.actions || []).length; ak++) { + var a = vr.actions[ak]; + if (!a.passed) { + console.log(" action " + a.id + ": " + a.error); + } + } + if (vr.consoleErrors && vr.consoleErrors.length > 0) { + console.log(" console errors: " + vr.consoleErrors.length); + } + } + } + } + + console.log(""); + console.log("Summary written to: " + summaryPath); + process.exit(results.failed > 0 ? 1 : 0); +} + +async function executeAction(page, action) { + switch (action.type) { + case "click": + await page.waitForSelector(action.selector, { timeout: 5000 }); + await page.click(action.selector); + break; + case "fill-form": + var fields = action.fields || []; + for (var fi = 0; fi < fields.length; fi++) { + var field = fields[fi]; + await page.waitForSelector(field.selector, { timeout: 5000 }); + await page.click(field.selector, { clickCount: 3 }); + await page.type(field.selector, field.value); + } + break; + case "select": + await page.waitForSelector(action.selector, { timeout: 5000 }); + await page.select(action.selector, action.value); + break; + case "scroll": + if (action.selector) { + await page.waitForSelector(action.selector, { timeout: 5000 }); + await page.$eval(action.selector, function (el) { + el.scrollIntoView({ behavior: "smooth", block: "center" }); + }); + } else { + await page.evaluate( + function (x, y) { window.scrollTo(x, y); }, + action.x || 0, + action.y || 0 + ); + } + await new Promise(function (r) { setTimeout(r, 500); }); + break; + case "hover": + await page.waitForSelector(action.selector, { timeout: 5000 }); + await page.hover(action.selector); + await new Promise(function (r) { setTimeout(r, 300); }); + break; + case "wait": + if (action.selector) { + await page.waitForSelector(action.selector, { + timeout: action.timeout || 10000, + }); + } else { + await new Promise(function (r) { setTimeout(r, action.duration || 1000); }); + } + break; + default: + throw new Error("Unknown action type: " + action.type); + } +} + +async function validateExpectations(page, expectations) { + var items = Array.isArray(expectations) ? expectations : [expectations]; + for (var ei = 0; ei < items.length; ei++) { + var expect = items[ei]; + if (expect.url) { + var currentUrl = page.url(); + var pattern = new RegExp(expect.url); + if (!pattern.test(currentUrl)) { + return false; + } + } + if (expect.visible) { + var el = await page.$(expect.visible); + if (!el) return false; + var isVisible = await page.evaluate(function (s) { + var e = document.querySelector(s); + if (!e) return false; + var r = e.getBoundingClientRect(); + return r.width > 0 && r.height > 0; + }, expect.visible); + if (!isVisible) return false; + } + if (expect.hidden) { + var elH = await page.$(expect.hidden); + if (elH) { + var isVis = await page.evaluate(function (s) { + var e = document.querySelector(s); + if (!e) return false; + var r = e.getBoundingClientRect(); + return r.width > 0 && r.height > 0; + }, expect.hidden); + if (isVis) return false; + } + } + if (expect.text) { + var textContent = await page.$eval( + expect.text.selector, + function (el) { return el.textContent; } + ); + if (!textContent || !textContent.includes(expect.text.contains)) { + return false; + } + } + } + return true; +} + +run().catch(function (err) { + console.error("Fatal error:", err); + process.exit(1); +});