commit 2ad76ae14a6378e55b227f90ed0b4fd88a78774e Author: TenX PM Date: Tue May 5 22:28:19 2026 +0000 deploy: betterhuman-designs diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..dbb4721 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,586 @@ +You are the autonomous Project Manager (PM) for "betterhuman" (project ID: 8a14e99e-54e4-459e-8f3f-17006c17956a). +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. + +▸ Coolify MCP tools + Deploy applications to production via Coolify. You MUST use Coolify for + all deployments — nginx previews are for local dev testing only. + Available tools include creating applications, triggering deployments, + checking deployment status, and managing domains. + +▸ 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 betterhuman-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/8a14e99e-54e4-459e-8f3f-17006c17956a/ │ +│ 3. Developer must produce: │ +│ • The full application code │ +│ • SigNoz APM instrumentation (OpenTelemetry auto-instrumentation, │ +│ OTLP exporter to $SIGNOZ_OTEL_ENDPOINT). This is MANDATORY. │ +│ • Nginx configuration to serve the app │ +│ • 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 app runs locally: curl the preview URL and confirm 200. │ +│ If curl fails, have the Developer debug and fix. │ +│ 6. Deploy the app: bash deploy.sh betterhuman nixpacks │ +│ (or "static" for HTML-only, "dockerfile" if Dockerfile exists) │ +│ 7. Read the deploy.sh output — it prints the production URL. │ +│ │ +│ Exit: App deployed on Coolify, production URL confirmed with curl. │ +│ Milestone: Post "First build deployed" with the PRODUCTION URL. │ +│ 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) + • Maximum 3 polls per batch, send as many batches as needed (up to 10 total) + +──────────────────────────────────────────────────────────────────────────────── +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/8a14e99e-54e4-459e-8f3f-17006c17956a/ +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 THIS SCRIPT FOR EVERY DEPLOYMENT ██ +Do NOT call Coolify MCP tools (mcp__coolify__application, mcp__coolify__deploy, +mcp__coolify__env_vars) directly. They require full URLs and are error-prone. +deploy.sh handles everything correctly — git, Gitea repo creation, full +Gitea URL construction, Coolify app creation, env vars, and deployment. +If you bypass deploy.sh, the deployment WILL fail with "does not appear to +be a git repository" because Coolify needs the FULL Gitea URL, not a +relative path. + +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 email +
+
+ +
+ + +
+ +
+ + +
+ +
+ + Forgot password? +
+ + + + + + + + + diff --git a/designs/02-dashboard.html b/designs/02-dashboard.html new file mode 100644 index 0000000..51b57a1 --- /dev/null +++ b/designs/02-dashboard.html @@ -0,0 +1,696 @@ + + + + + +BetterHuman — Dashboard + + + + + + + + + +
+ +
+
+ Dashboard + Good morning, Priya — Monday, 5 May 2026 +
+
+
+ + + + +
+
+ + + +
+
+
PS
+
+
+ + +
+ +
+ + + +
+ + +
+
+
+
Total Employees
+
247
+
+8 this month
+
+
+ + + + +
+
+
+
+
Open Positions
+
12
+
3 urgent
+
+
+ + + +
+
+
+
+
On Leave Today
+
8
+
3.2% of workforce
+
+
+ + + + +
+
+
+
+
Pending Approvals
+
5
+
2 overdue
+
+
+ + + + +
+
+
+ + +
+
+
+
Monthly Payroll — May 2026
+
₹48.2L
+
+2.4% vs last month
+
+
+ + + +
+
+
+
+
Avg Engagement Score
+
78%
+
+3pts from last survey
+
+
+ + + +
+
+
+ + +
+ +
+
+
+ Headcount by Department + View All +
+
+
+
Engineering
+
+
89
+
+
89
+
+
+
Sales
+
+
45
+
+
45
+
+
+
Operations
+
+
35
+
+
35
+
+
+
Product
+
+
28
+
+
28
+
+
+
Finance
+
+
18
+
+
18
+
+
+
HR
+
+
12
+
+
12
+
+
+
+ + +
+
+ Pending Leave Approvals + View All (5) +
+
+
AK
+
+
Ananya Krishnan
+
Annual Leave · May 8–12 · 5 days · Engineering
+
+
+ + +
+
+
+
VS
+
+
Vikram Singh
+
Sick Leave · May 6 · 1 day · Sales
+
+
+ + +
+
+
+
RD
+
+
Rohan Das
+
Compensatory Off · May 9 · 1 day · Product
+
+
+ + +
+
+
+
+ + +
+ +
+
+ Upcoming Birthdays + This Month +
+
+
MN
+
+
Meera Nair
+
Engineering · May 7
+
+ 🎂 +
+
+
KP
+
+
Karan Patel
+
Sales · May 11
+
+ 🎂 +
+
+
SR
+
+
Sanya Reddy
+
Product · May 18
+
+ 🎂 +
+
+ + +
+
+ Recent Hires + This Month +
+
+
AR
+
+
Arjun Rao
+
Backend Engineer · May 1
+
+
+ Active +
+
+
+
PJ
+
+
Pooja Joshi
+
Sales Executive · May 2
+
+
+ Probation +
+
+
+
NB
+
+
Nikhil Bhat
+
DevOps Engineer · May 3
+
+
+ Probation +
+
+
+
DK
+
+
Divya Kumar
+
UX Designer · May 5
+
+
+ Probation +
+
+
+
+
+
+
+ + + diff --git a/designs/03-people.html b/designs/03-people.html new file mode 100644 index 0000000..e7f14f1 --- /dev/null +++ b/designs/03-people.html @@ -0,0 +1,383 @@ + + + + + +BetterHuman — People Directory + + + + + + + + +
+
+
+ People Directory + Manage your workforce +
+
+
+
+
PS
+
+
+ +
+ +
+
+ + +
+ + + +
+ + +
+
+ + +
+
Active247
+
On Leave8
+
Terminated this month3
+
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EmployeeDepartmentPositionLocationStatusManagerStart DateActions
PS
Priya Sharma
EMP-0001
EngineeringSr. Software EngineerBengaluruActiveRahul MehtaJan 15, 2022 + + +
AK
Ananya Krishnan
EMP-0024
EngineeringFrontend EngineerBengaluruOn LeavePriya SharmaMar 10, 2023 + + +
VS
Vikram Singh
EMP-0037
SalesSales ManagerMumbaiActiveNeha GuptaJul 4, 2021 + + +
MN
Meera Nair
EMP-0052
ProductProduct ManagerBengaluruActiveArjun RaoNov 22, 2020 + + +
RD
Rohan Das
EMP-0068
EngineeringDevOps EngineerHyderabadProbationPriya SharmaApr 1, 2026 + + +
KP
Karan Patel
EMP-0079
SalesAccount ExecutiveDelhi NCRActiveVikram SinghSep 16, 2022 + + +
SR
Sanya Reddy
EMP-0091
ProductUX DesignerBengaluruActiveMeera NairJun 20, 2023 + + +
AR
Arjun Rao
EMP-0102
EngineeringBackend EngineerBengaluruProbationPriya SharmaMay 1, 2026 + + +
PJ
Pooja Joshi
EMP-0115
FinanceFinancial AnalystMumbaiActiveDeepak VermaFeb 14, 2024 + + +
NB
Nikhil Bhat
EMP-0128
OperationsOperations LeadHyderabadOn LeaveSuresh PillaiAug 8, 2019 + + +
+ +
+
+
+ + + diff --git a/designs/04-employee-profile.html b/designs/04-employee-profile.html new file mode 100644 index 0000000..178a309 --- /dev/null +++ b/designs/04-employee-profile.html @@ -0,0 +1,431 @@ + + + + + +BetterHuman — Employee Profile + + + + + + + +
+
+
+
+ People + / + Priya Sharma +
+
+
+
+
PS
+
+
+ +
+ +
+
PS
+
+
Priya Sharma
+
Senior Software Engineer · Engineering
+
+ Active +
+ + Bengaluru +
+
+ + EMP-0001 · Full-time +
+
+ + Joined Jan 15, 2022 +
+
+
+
+ + + +
+
+ + +
+
Overview
+
Documents
+
Leave
+
Payroll
+
Performance
+
Assets
+
+ + +
+ +
+ +
+
Personal Information Edit
+
+
+ Date of Birth + March 12, 1994 +
+
+ Gender + Female +
+
+ Nationality + Indian +
+
+ Blood Group + O+ +
+
+ Phone + +91 98765 43210 +
+
+ Personal Email + priya.s@gmail.com +
+
+ Emergency Contact + Rajesh Sharma (Father) · +91 98123 45678 +
+
+
+ + +
+
Work Information Edit
+
+
+ Employee ID + EMP-0001 +
+
+ Employment Type + Full-time Permanent +
+
+ Work Email + priya@techcorp.in +
+
+ Department + Engineering +
+
+ Manager + Rahul Mehta +
+
+ Location + Bengaluru HQ +
+
+ Start Date + January 15, 2022 +
+
+ Probation End + April 15, 2022 (Cleared) +
+
+ PAN Number + ABCDE1234F +
+
+ PF Account No. + KA/BLR/0123456/001 +
+
+
+
+ + +
+ +
+
Leave Balance
+
+
+
+ Annual Leave + 18 / 24 days +
+
+
6 days used
+
+
+
+ Sick Leave + 6 / 12 days +
+
+
6 days used
+
+
+
+ Compensatory Off + 2 / 5 days +
+
+
3 days used
+
+
+
+ Emergency Leave + 3 / 3 days +
+
+
0 days used
+
+
+
+ + +
+
Recent Activity
+
+
+
+
+
Leave request approved for Apr 18–19 (2 days Sick Leave)
+
2 days ago
+
+
+
+
+
+
Self-assessment submitted for Q1 2026 Performance Review
+
5 days ago
+
+
+
+
+
+
Payslip downloaded for March 2026
+
Apr 1, 2026
+
+
+
+
+
+
Completed "Advanced React Patterns" learning module
+
Mar 28, 2026
+
+
+
+
+ + +
+
Documents Upload
+
+
+
+
+
Offer Letter
+
Signed Jan 10, 2022
+
+
+
+
+
+
+
Aadhar Card
+
No expiry
+
+
+
+
+
+
+
Passport
+
Expires Dec 18, 2030
+
+
+
+
+
+
+
+
+
+ + + diff --git a/designs/05-leave.html b/designs/05-leave.html new file mode 100644 index 0000000..b5478ac --- /dev/null +++ b/designs/05-leave.html @@ -0,0 +1,336 @@ + + + + + +BetterHuman — Leave Management + + + + + + + +
+
+
+ Leave Management + Your leave balance and requests +
+
+ +
+
PS
+
+
+ +
+ +
+ My Leave Balance · 2026 +
+
+
+
Annual Leave
+
18 / 24 days
+
+
6 days used · 0 pending
+
+
+
Sick Leave
+
6 / 12 days
+
+
6 days used · 0 pending
+
+
+
Compensatory Off
+
2 / 5 days
+
+
3 days used · 1 pending
+
+
+
Emergency Leave
+
3 / 3 days
+
+
0 days used · 0 pending
+
+
+ + +
+ +
+ +
+
+ May 2026 +
+
+ May 2026 +
+
+
+
+
+
Sun
Mon
Tue
+
Wed
Thu
Fri
Sat
+
+
+ +
27
28
29
+
30
1
2
3
+ +
4
5
6
+
7
8
9
10
+ +
11
12
13
+
14
15
16
17
+ +
18
19
20
+
21
22
23
24
+ +
25
26
27
+
28
29
30
31
+
+
+
+
Today
+
Approved Leave
+
Pending
+
Public Holiday
+
+
+ + +
+
Team on Leave Today
+
+
+
AK
+
Ananya Krishnan
Annual · May 8–12
+
+
+
NB
+
Nikhil Bhat
Sick · May 5
+
+
+
SR
+
Sanya Reddy
Annual · May 5–7
+
+
+
KP
+
Karan Patel
Comp Off · May 5
+
+
+
+
+ + +
+
+
My Leave History
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PeriodTypeDaysStatus
Apr 18–19Sick2Approved
Mar 22Annual1Approved
May 20–21Annual2Pending
Feb 14Annual1Approved
Jan 26Comp Off1Approved
+
+
+
+
+
+ + + diff --git a/designs/06-payroll.html b/designs/06-payroll.html new file mode 100644 index 0000000..c1cf4bc --- /dev/null +++ b/designs/06-payroll.html @@ -0,0 +1,361 @@ + + + + + +BetterHuman — Payroll + + + + + + + +
+
+
+ Payroll + Manage salaries, deductions, and payslips +
+
+ + + +
+
PS
+
+
+ +
+ +
+
+
+
April 2026 Payroll — Completed
+
Processed on Apr 28, 2026 · 247 employees paid · All transfers successful
+
+
+ + +
+
+
Gross Pay
+
₹48,24,000
+
247 employees
+
+
+
Net Pay Disbursed
+
₹38,96,000
+
After all deductions
+
+
+
Total Deductions
+
₹9,28,000
+
PF + ESI + TDS + PT
+
+
+
Employees Paid
+
247
+
100% success rate
+
+
+ + +
+
+
Payslip Summary — April 2026
+

Individual payroll breakdown for all active employees this cycle.

+
+
+
Deduction Breakdown
+
+
+
PF (Employee)
+
₹2,88,000
12% of basic
+
+
+
PF (Employer)
+
₹2,88,000
12% of basic
+
+
+
ESI
+
₹36,000
0.75% of gross
+
+
+
TDS
+
₹3,16,000
As per IT slab
+
+
+
Professional Tax
+
₹18,000
₹200/month
+
+
+
+
+ + +
+
+
Employee Payslips
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EmployeeGrossPFESITDSProf TaxNet PayStatus
PS
Priya Sharma
Engineering
₹1,85,000₹13,320₹1,388₹22,400₹200₹1,47,692Paid
RM
Rahul Mehta
Engineering
₹2,40,000₹17,280₹1,800₹38,500₹200₹1,82,220Paid
AK
Ananya Krishnan
Engineering
₹1,20,000₹8,640₹900₹9,200₹200₹1,01,060Paid
VS
Vikram Singh
Sales
₹1,60,000₹11,520₹1,200₹16,800₹200₹1,30,280Paid
MN
Meera Nair
Product
₹1,90,000₹13,680₹1,425₹24,200₹200₹1,50,495Paid
KP
Karan Patel
Sales
₹95,000₹6,840₹713₹4,800₹200₹82,447Paid
PJ
Pooja Joshi
Finance
₹1,10,000₹7,920₹825₹7,600₹200₹93,455Paid
NB
Nikhil Bhat
Operations
₹1,35,000₹9,720₹1,013₹12,400₹200₹1,11,667Paid
+
+
+
+ + + diff --git a/designs/07-recruitment.html b/designs/07-recruitment.html new file mode 100644 index 0000000..542ed70 --- /dev/null +++ b/designs/07-recruitment.html @@ -0,0 +1,322 @@ + + + + + +BetterHuman — Recruitment + + + + + + + +
+
+
+ Recruitment — ATS + Track candidates across your hiring pipeline +
+
+ +
+
PS
+
+
+ +
+ +
+
+
Open Positions (3)
+ +
+
+
Senior Frontend Engineer
+
Engineering · Bengaluru
+
+ Active + Senior + 12 +
+
+
+
Product Manager
+
Product · Bengaluru / Remote
+
+ Active + Mid-Sr + 8 +
+
+
+
Regional Sales Lead
+
Sales · Delhi NCR
+
+ Active + Senior + 4 +
+
+
+ + +
+ +
+
+
Senior Frontend Engineer
+
+
Bengaluru HQ
+
₹25–40L CTC
+
Senior · Engineering
+
Posted 18 days ago
+
+
+
+ + +
+
+ + +
+ +
+
+ Applied + 12 +
+
+
+
RV
Rahul Verma
Applied 1d ago
+
LinkedInReact
+
+
+
SM
Shreya Malhotra
Applied 2d ago
+
ReferralVue.js
+
+
+ +
+ + +
+
+ Screening + 7 +
+
+
+
AP
Aryan Patel
Screened 3d ago
+
NaukriTypeScript
+
+
+
NK
Naina Kapoor
Screened 4d ago
+
LinkedInNext.js
+
+
+ +
+ + +
+
+ Interview + 4 +
+
+
+
DM
Dev Mehrotra
Round 2 · May 8
+
DirectReact · Node
+
+
+
PR
Pooja Rao
Round 1 · May 9
+
ReferralAngular
+
+
+ +
+ + +
+
+ Offer + 2 +
+
+
+
KS
Kunal Sharma
Offer sent 2d ago
+
NegotiatingReact
+
+
+
AS
Anika Singh
Offer accepted
+
AcceptedVue
+
+
+ +
+ + +
+
+ Hired + 1 +
+
+
+
RD
Rohan Das
Joined May 1, 2026
+
OnboardedReact
+
+
+ +
+
+
+
+
+ + + diff --git a/designs/08-performance.html b/designs/08-performance.html new file mode 100644 index 0000000..f8bc399 --- /dev/null +++ b/designs/08-performance.html @@ -0,0 +1,386 @@ + + + + + +BetterHuman — Performance + + + + + + + +
+
+
+ Performance Management + Reviews, OKRs, and 1:1s +
+
+ +
+
PS
+
+
+ +
+ +
+
+
Q1 2026 Performance Review
+
Annual review cycle — 360° feedback + OKR assessment
+
+
+ 68% submitted +
+
+
+
Cycle ends June 30, 2026
+ +
+
+ + +
+
+
+
Reviews Submitted
+
168/247
+
68% completion
+
+
+
+ +
+
+
+
+
Self Reviews Done
+
201/247
+
81% completion
+
+
+
+ +
+
+
+
+
Avg Team Rating
+
3.8/5
+
+0.3 from last cycle
+
+ + + + + +
+
+
+ +
+
+
+ + +
+
+ +
+
My Pending Reviews View All
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EmployeeReview TypeDue DateStatus
PS
Priya Sharma
Self Review
SelfJune 15, 2026Pending
AK
Ananya Krishnan
Engineering
ManagerJune 20, 2026Pending
RD
Rohan Das
Engineering
ManagerJune 20, 2026Submitted
MN
Meera Nair
Product
PeerJune 18, 2026Overdue
+
+ + +
+
My OKRs — Q1 2026 Edit Goals
+
+
+
Launch BetterHuman v2.0 Mobile App
+
+ Engineering · Owner: Priya Sharma + 72% +
+
+
+
+
Achieve Q2 Revenue Target of ₹8.5Cr
+
+ Company · Owner: Neha Gupta + 45% +
+
+
+
+
Reduce Customer Churn from 12% to 8%
+
+ Product · Owner: Meera Nair + 88% +
+
+
+
+
+
+ + +
+
+
Upcoming 1:1
+
+
Scheduled 1:1
+
1:1 with Rahul Mehta
+
Tomorrow — Wednesday, May 6 · 3:00 PM
+
Agenda: Q1 review progress, career development discussion, team expansion plans.
+
+
+
+ +
+
Rating Distribution
+
+
+
Outstanding (5)
+
+
12%
+
+
+
Exceeds (4)
+
+
28%
+
+
+
Meets (3)
+
+
45%
+
+
+
Below (2)
+
+
12%
+
+
+
Needs Impr (1)
+
+
3%
+
+
+
+
+
+
+
+ + + diff --git a/designs/09-analytics.html b/designs/09-analytics.html new file mode 100644 index 0000000..7badaf9 --- /dev/null +++ b/designs/09-analytics.html @@ -0,0 +1,373 @@ + + + + + +BetterHuman — Analytics + + + + + + + +
+
+
+ Analytics & Reports + People insights and workforce trends +
+
+ + +
+
PS
+
+
+ +
+ +
+
+
Headcount Growth vs Q1
+
+12%
+
+ + +27 employees this quarter +
+
+
+
Attrition Rate YTD
+
8.2%
+
+ + Down from 11.4% last year +
+
+
+
Avg Time to Hire Days
+
24 days
+
+ + 3 days faster than Q4 +
+
+
+
Engagement Score eNPS
+
78%
+
+ + +3 pts from last survey +
+
+
+ + +
+ +
+
Headcount by Department Details
+
+
+
Engineering
+
89
+
89
+
+
+
Sales
+
45
+
45
+
+
+
Operations
+
35
+
35
+
+
+
Product
+
28
+
28
+
+
+
Finance
+
18
+
18
+
+
+
HR
+
12
+
12
+
+
+
+ + +
+
+
Gender Distribution
+
+
60%
+
36%
+
4%
+
+
+
Male · 148
+
Female · 89
+
Other · 10
+
+
+ +
+
Monthly Attrition Last 6 Months
+
+
+
+
Nov
+
+
+
+
Dec
+
+
+
+
Jan
+
+
+
+
Feb
+
+
+
+
Mar
+
+
+
+
Apr
+
+
+
+
+
+ + +
+
+
Less than 1 year
+
42
+
17% of workforce
+
+
+
1–3 years
+
89
+
36% of workforce
+
+
+
3–5 years
+
67
+
27% of workforce
+
+
+
5+ years
+
49
+
20% of workforce
+
+
+ + +
+
+
Saved Reports
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Report NameTypeGenerated ByDateActions
Monthly Headcount Report — April 2026PeoplePriya SharmaMay 1, 2026
Q1 2026 Attrition AnalysisAttritionRahul MehtaApr 15, 2026
Payroll Summary — March 2026PayrollPriya SharmaApr 1, 2026
Engagement Survey Results — Q1EngagementPriya SharmaMar 31, 2026
+
+
+
+ + + diff --git a/designs/10-settings.html b/designs/10-settings.html new file mode 100644 index 0000000..89ff388 --- /dev/null +++ b/designs/10-settings.html @@ -0,0 +1,320 @@ + + + + + +BetterHuman — Settings + + + + + + + +
+
+
+ Settings + Manage your workspace configuration +
+
+
+
PS
+
+
+ +
+
+ +
+
+
Organization
+
+ + Company +
+
+ + Departments +
+
+ + Positions +
+
+ + Locations +
+
+
+
Access
+
+ + Roles & Permissions +
+
+
+
Preferences
+
+ + Notifications +
+
+ + Integrations +
+
+ + Billing +
+
+
+ + +
+ +
+
Company Profile
+
Update your company's basic information and branding.
+ + +
+
TC
+
+
TechCorp India Pvt. Ltd.
+
PNG, JPG, SVG — Max 2MB · Recommended 400x400px
+
+ +
+ +
+
+ + +
+
+ + + Used for SSO and employee email validation +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ + +
+
+ +
+ +
Currency & Locale
+
+
+ + +
+
+ + +
+
+ +
+ + +
+
+ + +
+
Danger Zone
+
Actions in this section are irreversible. Please proceed with extreme caution.
+
+
+
Export All Company Data
+
Download a full JSON/CSV export of all employee data, payroll records, and settings.
+
+ +
+
+
+
Delete Company Account
+
Permanently delete this workspace and all associated data. This cannot be undone.
+
+ +
+
+
+
+
+
+ + + diff --git a/designs/index.html b/designs/index.html new file mode 100644 index 0000000..2217abd --- /dev/null +++ b/designs/index.html @@ -0,0 +1,363 @@ + + + + + +BetterHuman — Design Gallery + + + + + + +
+
+
+ + + + +
+
+
BetterHuman
+
HR Platform — Design Mockups
+
+
+
+
Version 1.0 · May 2026
+
10 Screens
+
+
+ + +
+
Design System &
Mockup Gallery
+
A comprehensive set of UI mockups for BetterHuman — the modern HR platform for India's growing SMB and mid-market companies. All mockups are fully responsive, use realistic data, and follow a consistent design system.
+
+
Inter + Sora Fonts
+
Indigo Design System
+
8px Grid
+
India-First Data
+
Pure HTML/CSS
+
+
+ + +
+
All Screens
+
+ + + + +
+
01 · Authentication
+
Login Page
+
Split-panel login with Google OAuth, email/password, and brand storytelling on the left.
+
View Design
+
+ + + + +
+
+
+
+
+
+
+
+
+
+
02 · Overview
+
HR Admin Dashboard
+
KPI metrics, headcount charts, pending approvals, upcoming birthdays, and recent hires.
+
View Design
+
+ + + + +
+
+
+
+
03 · People
+
Employee Directory
+
Searchable employee table with filters, status badges, manager info, and bulk actions.
+
View Design
+
+ + + + +
+
+
+
+
04 · People
+
Employee Profile
+
Detailed employee view with tabbed sections: personal info, work details, leave balance, documents.
+
View Design
+
+ + + + +
+
+
+
+
05 · Workforce
+
Leave Management
+
Leave balance tracker, monthly calendar with color-coded days, team absence view.
+
View Design
+
+ + + + +
+
+
+
+
06 · Workforce
+
Payroll
+
Monthly payroll summary with PF, ESI, TDS breakdown and per-employee payslips.
+
View Design
+
+ + + + +
+
+
+
+
+
+
+
+
+
+
07 · Workforce
+
Recruitment — ATS
+
Full Kanban pipeline: Applied → Screening → Interview → Offer → Hired. Jobs sidebar included.
+
View Design
+
+ + + + +
+
+
+
+
08 · Talent
+
Performance Management
+
Active review cycle banner, OKR progress bars, pending reviews table, and 1:1 scheduling.
+
View Design
+
+ + + + +
+
+
+
+
09 · Insights
+
Analytics Dashboard
+
KPIs, headcount charts, gender distribution, tenure breakdown, attrition trends, saved reports.
+
View Design
+
+ + + + +
+
+
+
+
10 · Admin
+
Settings
+
Company profile, logo upload, departments, locations, integrations, billing, and danger zone.
+
View Design
+
+ + +
+
+ + +
+
BetterHuman HR Platform · Design Mockups v1.0 · May 2026 · India
+
+
HTML5
+
CSS3
+
Inter + Sora
+
Inline SVG Icons
+
+
+ + + 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); +});