start-vibing 4.1.0 → 4.1.2

package/template/.claude/skills/ui-ux-audit/templates/improvement-recommendation.md

@@ -0,0 +1,450 @@
+# UI/UX Improvement Recommendation: [Feature/Component Name]
+
+**Date:** YYYY-MM-DD
+**Submitted By:** [Agent name]
+**Priority:** [Low/Medium/High/Critical]
+**Status:** [Proposed/Approved/In Progress/Completed/Rejected]
+
+---
+
+## Executive Summary
+
+[1-2 sentence summary of the problem and proposed solution]
+
+---
+
+## Current State
+
+### What Exists Now
+
+[Description of current implementation]
+
+**Screenshots:**
+
+[Add screenshots showing current state]
+
+### Problems Identified
+
+1. **[Problem 1]**
+    - Impact: [User/Business/Technical]
+    - Severity: [Low/Medium/High]
+    - Affected Users: [Who is impacted]
+
+2. **[Problem 2]**
+    - Impact: [User/Business/Technical]
+    - Severity: [Low/Medium/High]
+    - Affected Users: [Who is impacted]
+
+3. **[Problem 3]**
+    - Impact: [User/Business/Technical]
+    - Severity: [Low/Medium/High]
+    - Affected Users: [Who is impacted]
+
+### Metrics (Current)
+
+| Metric     | Current Value | Target Value | Status        |
+| ---------- | ------------- | ------------ | ------------- |
+| [Metric 1] | [Value]       | [Goal]       | [Below/Above] |
+| [Metric 2] | [Value]       | [Goal]       | [Below/Above] |
+| [Metric 3] | [Value]       | [Goal]       | [Below/Above] |
+
+---
+
+## Proposed Solution
+
+### Overview
+
+[Detailed description of proposed changes]
+
+### Design Mockups
+
+[Add mockups/wireframes of proposed solution]
+
+**Desktop:**
+
+[Desktop mockup]
+
+**Mobile:**
+
+[Mobile mockup]
+
+### Key Changes
+
+1. **[Change 1]**
+    - Current: [What it is now]
+    - Proposed: [What it will be]
+    - Rationale: [Why this change]
+
+2. **[Change 2]**
+    - Current: [What it is now]
+    - Proposed: [What it will be]
+    - Rationale: [Why this change]
+
+3. **[Change 3]**
+    - Current: [What it is now]
+    - Proposed: [What it will be]
+    - Rationale: [Why this change]
+
+---
+
+## Research & Evidence
+
+### Competitor Examples
+
+1. **[Competitor Name]**
+    - Approach: [How they handle this]
+    - Effectiveness: [Results/metrics if available]
+    - Applicability: [How it applies to us]
+
+2. **[Competitor Name]**
+    - Approach: [How they handle this]
+    - Effectiveness: [Results/metrics if available]
+    - Applicability: [How it applies to us]
+
+### Industry Best Practices
+
+1. [Best practice 1 - with source]
+2. [Best practice 2 - with source]
+3. [Best practice 3 - with source]
+
+### User Research
+
+[Any user testing, surveys, or feedback that supports this change]
+
+- [Finding 1]
+- [Finding 2]
+- [Finding 3]
+
+### Accessibility Standards
+
+[Any WCAG or accessibility guidelines that support this change]
+
+- [Guideline 1]
+- [Guideline 2]
+
+---
+
+## Benefits
+
+### User Benefits
+
+1. **[Benefit 1]**
+    - Description: [How it helps users]
+    - Impact: [Quantify if possible]
+
+2. **[Benefit 2]**
+    - Description: [How it helps users]
+    - Impact: [Quantify if possible]
+
+3. **[Benefit 3]**
+    - Description: [How it helps users]
+    - Impact: [Quantify if possible]
+
+### Business Benefits
+
+1. **[Benefit 1]**
+    - Description: [How it helps business]
+    - Impact: [Quantify if possible - conversions, revenue, etc]
+
+2. **[Benefit 2]**
+    - Description: [How it helps business]
+    - Impact: [Quantify if possible]
+
+### Technical Benefits
+
+1. **[Benefit 1]**
+    - Description: [Performance, maintainability, etc]
+    - Impact: [Quantify if possible]
+
+2. **[Benefit 2]**
+    - Description: [Performance, maintainability, etc]
+    - Impact: [Quantify if possible]
+
+---
+
+## Implementation Plan
+
+### Phase 1: Design & Validation
+
+**Duration:** [Time estimate]
+
+- [ ] Create detailed mockups
+- [ ] Review with stakeholders
+- [ ] User testing (if needed)
+- [ ] Finalize design specs
+
+**Deliverables:**
+
+- [Deliverable 1]
+- [Deliverable 2]
+
+### Phase 2: Development
+
+**Duration:** [Time estimate]
+
+- [ ] Create new component(s)
+- [ ] Update existing components
+- [ ] Add/update tests
+- [ ] Accessibility audit
+
+**Deliverables:**
+
+- [Deliverable 1]
+- [Deliverable 2]
+
+### Phase 3: Testing
+
+**Duration:** [Time estimate]
+
+- [ ] Unit tests
+- [ ] E2E tests
+- [ ] Visual regression tests
+- [ ] Accessibility tests
+- [ ] Cross-browser testing
+- [ ] Mobile device testing
+
+**Deliverables:**
+
+- [Deliverable 1]
+- [Deliverable 2]
+
+### Phase 4: Deployment
+
+**Duration:** [Time estimate]
+
+- [ ] Feature flag implementation
+- [ ] Gradual rollout plan
+- [ ] Monitor metrics
+- [ ] Gather user feedback
+
+**Deliverables:**
+
+- [Deliverable 1]
+- [Deliverable 2]
+
+---
+
+## Resource Requirements
+
+### Time Estimate
+
+| Phase       | Hours | Days | Team Members |
+| ----------- | ----- | ---- | ------------ |
+| Design      | [#]   | [#]  | [Who]        |
+| Development | [#]   | [#]  | [Who]        |
+| Testing     | [#]   | [#]  | [Who]        |
+| Deployment  | [#]   | [#]  | [Who]        |
+| **Total**   | [#]   | [#]  | -            |
+
+### Technical Requirements
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### External Dependencies
+
+- [Dependency 1]
+- [Dependency 2]
+
+---
+
+## Risks & Mitigation
+
+### Risk 1: [Risk Name]
+
+- **Probability:** [Low/Medium/High]
+- **Impact:** [Low/Medium/High]
+- **Mitigation:** [How to prevent/handle]
+
+### Risk 2: [Risk Name]
+
+- **Probability:** [Low/Medium/High]
+- **Impact:** [Low/Medium/High]
+- **Mitigation:** [How to prevent/handle]
+
+### Risk 3: [Risk Name]
+
+- **Probability:** [Low/Medium/High]
+- **Impact:** [Low/Medium/High]
+- **Mitigation:** [How to prevent/handle]
+
+---
+
+## Success Metrics
+
+### Key Performance Indicators
+
+| KPI        | Current | Target | Measurement Method |
+| ---------- | ------- | ------ | ------------------ |
+| [Metric 1] | [#]     | [#]    | [How to measure]   |
+| [Metric 2] | [#]     | [#]    | [How to measure]   |
+| [Metric 3] | [#]     | [#]    | [How to measure]   |
+
+### Success Criteria
+
+- [ ] [Criterion 1 - specific, measurable]
+- [ ] [Criterion 2 - specific, measurable]
+- [ ] [Criterion 3 - specific, measurable]
+
+### Monitoring Plan
+
+**Week 1:**
+
+- [What to monitor]
+- [What to monitor]
+
+**Week 2-4:**
+
+- [What to monitor]
+- [What to monitor]
+
+**Week 5+:**
+
+- [What to monitor]
+- [What to monitor]
+
+---
+
+## Alternatives Considered
+
+### Alternative 1: [Approach Name]
+
+**Description:** [What is this alternative]
+
+**Pros:**
+
+- [Pro 1]
+- [Pro 2]
+
+**Cons:**
+
+- [Con 1]
+- [Con 2]
+
+**Why Not Chosen:** [Explanation]
+
+### Alternative 2: [Approach Name]
+
+**Description:** [What is this alternative]
+
+**Pros:**
+
+- [Pro 1]
+- [Pro 2]
+
+**Cons:**
+
+- [Con 1]
+- [Con 2]
+
+**Why Not Chosen:** [Explanation]
+
+---
+
+## Related Improvements
+
+### Prerequisite Changes
+
+[Changes that must happen first]
+
+1. [Prerequisite 1]
+2. [Prerequisite 2]
+
+### Follow-up Improvements
+
+[Changes that can happen after]
+
+1. [Follow-up 1]
+2. [Follow-up 2]
+
+### Related Features
+
+[Other features that might be affected or that relate to this]
+
+1. [Feature 1]
+2. [Feature 2]
+
+---
+
+## Accessibility Checklist
+
+- [ ] **Color Contrast:** Meets WCAG 2.1 AA (4.5:1)
+- [ ] **Touch Targets:** Minimum 44x44px
+- [ ] **Keyboard Navigation:** Full keyboard access
+- [ ] **Focus Indicators:** Visible focus states
+- [ ] **Screen Reader:** Proper labels and ARIA
+- [ ] **Alt Text:** All images have descriptive alt
+- [ ] **Responsive:** Works 375px to 1920px
+- [ ] **Motion:** Respects prefers-reduced-motion
+
+---
+
+## Responsiveness Checklist
+
+- [ ] **Mobile (375px):** Optimized layout
+- [ ] **Tablet (768px):** Optimized layout
+- [ ] **Desktop (1280px):** Full features
+- [ ] **FullHD (1920px):** No overflow
+- [ ] **Zero horizontal scroll:** All viewports
+
+---
+
+## Browser Support
+
+- [ ] Chrome (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Edge (latest)
+- [ ] Mobile Safari (iOS 14+)
+- [ ] Chrome Mobile (latest)
+
+---
+
+## Documentation Updates Needed
+
+- [ ] Component documentation
+- [ ] User guide
+- [ ] API documentation
+- [ ] Changelog
+- [ ] Migration guide
+
+---
+
+## Approval & Sign-off
+
+### Stakeholder Review
+
+| Stakeholder | Role   | Approval Status             | Date       | Notes      |
+| ----------- | ------ | --------------------------- | ---------- | ---------- |
+| [Name]      | [Role] | [Pending/Approved/Rejected] | YYYY-MM-DD | [Comments] |
+
+### Final Decision
+
+**Decision:** [Approved/Rejected/Deferred]
+**Date:** YYYY-MM-DD
+**Decision Maker:** [Name]
+**Rationale:** [Why this decision]
+
+---
+
+## Implementation Tracking
+
+### Status Updates
+
+**[Date]:** [Status update]
+
+**[Date]:** [Status update]
+
+**[Date]:** [Status update]
+
+### Completion
+
+**Deployed:** YYYY-MM-DD
+**Post-Launch Review:** YYYY-MM-DD
+**Final Metrics:** [Results vs targets]
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** YYYY-MM-DD

package/template/.claude/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

package/template/.claude/skills/webapp-testing/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
+license: Complete terms in LICENSE.txt
+---
+
+# Web Application Testing
+
+To test local web applications, write native Python Playwright scripts.
+
+**Helper Scripts Available**:
+- `scripts/with_server.py` - Manages server lifecycle (supports multiple servers)
+
+**Always run scripts with `--help` first** to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.
+
+## Decision Tree: Choosing Your Approach
+
+```
+User task → Is it static HTML?
+    ├─ Yes → Read HTML file directly to identify selectors
+    │         ├─ Success → Write Playwright script using selectors
+    │         └─ Fails/Incomplete → Treat as dynamic (below)
+    │
+    └─ No (dynamic webapp) → Is the server already running?
+        ├─ No → Run: python scripts/with_server.py --help
+        │        Then use the helper + write simplified Playwright script
+        │
+        └�� Yes → Reconnaissance-then-action:
+            1. Navigate and wait for networkidle
+            2. Take screenshot or inspect DOM
+            3. Identify selectors from rendered state
+            4. Execute actions with discovered selectors
+```
+
+## Example: Using with_server.py
+
+To start a server, run `--help` first, then use the helper:
+
+**Single server:**
+```bash
+python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
+```
+
+**Multiple servers (e.g., backend + frontend):**
+```bash
+python scripts/with_server.py \
+  --server "cd backend && python server.py" --port 3000 \
+  --server "cd frontend && npm run dev" --port 5173 \
+  -- python your_automation.py
+```
+
+To create an automation script, include only Playwright logic (servers are managed automatically):
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
+    page = browser.new_page()
+    page.goto('http://localhost:5173') # Server already running and ready
+    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
+    # ... your automation logic
+    browser.close()
+```
+
+## Reconnaissance-Then-Action Pattern
+
+1. **Inspect rendered DOM**:
+   ```python
+   page.screenshot(path='/tmp/inspect.png', full_page=True)
+   content = page.content()
+   page.locator('button').all()
+   ```
+
+2. **Identify selectors** from inspection results
+
+3. **Execute actions** using discovered selectors
+
+## Common Pitfall
+
+❌ **Don't** inspect the DOM before waiting for `networkidle` on dynamic apps
+✅ **Do** wait for `page.wait_for_load_state('networkidle')` before inspection
+
+## Best Practices
+
+- **Use bundled scripts as black boxes** - To accomplish a task, consider whether one of the scripts available in `scripts/` can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use `--help` to see usage, then invoke directly. 
+- Use `sync_playwright()` for synchronous scripts
+- Always close the browser when done
+- Use descriptive selectors: `text=`, `role=`, CSS selectors, or IDs
+- Add appropriate waits: `page.wait_for_selector()` or `page.wait_for_timeout()`
+
+## Reference Files
+
+- **examples/** - Examples showing common patterns:
+  - `element_discovery.py` - Discovering buttons, links, and inputs on a page
+  - `static_html_automation.py` - Using file:// URLs for local HTML
+  - `console_logging.py` - Capturing console logs during automation

package/template/.claude/skills/workflow-state/workflow-state.json

@@ -0,0 +1,77 @@
+{
+	"taskId": "ui-ux-audit-fixes",
+	"type": "feature",
+	"title": "UI/UX Audit - Multiple Improvements",
+	"startTime": "2025-12-29T02:00:00.000Z",
+	"endTime": "2025-12-29T03:30:00.000Z",
+	"status": "completed",
+	"currentAgent": "commit-manager",
+	"completedSteps": [
+		"codebase-knowledge",
+		"analyzer",
+		"ui-ux-reviewer",
+		"documenter",
+		"implementation",
+		"tester",
+		"security-auditor",
+		"quality-checker",
+		"final-validator",
+		"domain-updater",
+		"commit-manager"
+	],
+	"remainingSteps": [],
+	"context": {
+		"branch": "feature/responsive-seed",
+		"description": "Comprehensive UI/UX audit fixes: bottom nav indicator size, achievement colors, winner highlighting, race creator flow, public race creation, host earnings display, explanatory page",
+		"affectedDomains": ["ui-ux-responsive", "races", "betting", "gamification"]
+	},
+	"files": {
+		"planned": [
+			"components/layout/BottomNav.tsx",
+			"components/gamification/BadgeCard.tsx",
+			"components/gamification/ProgressBar.tsx",
+			"components/gamification/LeaderboardTable.tsx",
+			"components/races/ParticipantList.tsx",
+			"app/(organizer)/my-races/page.tsx",
+			"app/(main)/races/[id]/page.tsx",
+			"app/(main)/how-it-works/page.tsx",
+			"app/(main)/profile/page.tsx"
+		],
+		"created": ["app/(main)/how-it-works/page.tsx"],
+		"modified": [
+			"components/layout/BottomNav.tsx",
+			"components/gamification/BadgeCard.tsx",
+			"components/gamification/ProgressBar.tsx",
+			"components/gamification/BadgeGallery.tsx",
+			"components/gamification/LeaderboardTable.tsx",
+			"components/races/ParticipantList.tsx",
+			"app/(main)/races/[id]/page.tsx",
+			"app/(main)/races/[id]/results/page.tsx",
+			"app/(main)/profile/page.tsx",
+			"app/(main)/achievements/page.tsx",
+			"app/(main)/bets/[id]/page.tsx",
+			"app/(main)/leaderboard/page.tsx",
+			"app/layout.tsx",
+			".claude/skills/codebase-knowledge/domains/ui-ux-responsive.md",
+			".claude/skills/codebase-knowledge/domains/races.md"
+		]
+	},
+	"results": {
+		"commit": "25a15c1",
+		"testsAdded": 0,
+		"testsPassed": "N/A (UI changes only)",
+		"qualityGates": "PASSED",
+		"securityAudit": "PASSED",
+		"completedFixes": {
+			"1_bottomnav_indicator": "✅ DONE - Reduced from 40x64px to 32x48px",
+			"2_achievement_colors": "✅ DONE - Zinc colors with dark mode support",
+			"3_winner_highlighting": "✅ DONE - Trophy, badge, gold gradient",
+			"4_race_results_display": "✅ DONE - Fetches results and highlights winner",
+			"5_fee_breakdown": "✅ DONE - Displayed in race details and profile",
+			"6_how_it_works_page": "✅ DONE - Comprehensive explanatory page",
+			"7_winner_declaration_ui": "⏳ DEFERRED - Requires backend changes",
+			"8_public_race_creation": "⏳ DEFERRED - Requires policy decision"
+		}
+	},
+	"notes": "Completed 6 of 8 requested fixes. Two items deferred due to backend/policy requirements."
+}

package/template/.claude/config/README.md

@@ -1,27 +0,0 @@
-# Project Configuration
-
-This directory contains project-specific configuration files that agents and skills read to adapt their behavior to your project.
-
-## Files
-
-| File                  | Purpose                                                 |
-| --------------------- | ------------------------------------------------------- |
-| `project-config.json` | Main project configuration (stack, structure, commands) |
-| `quality-gates.json`  | Quality check commands                                  |
-| `testing-config.json` | Testing framework and conventions                       |
-| `security-rules.json` | Security audit rules                                    |
-
-## How Agents and Skills Use These
-
-1. **tester-unit** agent - Reads `testing-config.json` for frameworks and conventions
-2. **commit-manager** agent - Reads `project-config.json` for commit conventions
-3. **quality-gate** skill - Reads `quality-gates.json` for commands
-4. **security-scan** skill - Reads `security-rules.json` for security patterns
-
-## Customizing for Your Project
-
-1. Update `project-config.json` with your stack and commands
-2. Update `testing-config.json` with your test conventions
-3. Update `security-rules.json` with your auth framework
-
-The agents and skills will automatically adapt to your configuration.