From 1f96aec2b6e3ed74d3a608eecb3e8d4f9c94bcdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C2=A8NW=C2=A8?= <¨neroworld@mail.ru¨> Date: Sun, 5 Apr 2026 01:02:38 +0100 Subject: [PATCH] feat: add landing-page workflow for HTML mockup to production deployment --- .kilo/commands/landing-page.md | 1097 ++++++++++++++++++++++++++++++++ 1 file changed, 1097 insertions(+) create mode 100644 .kilo/commands/landing-page.md diff --git a/.kilo/commands/landing-page.md b/.kilo/commands/landing-page.md new file mode 100644 index 0000000..f01f642 --- /dev/null +++ b/.kilo/commands/landing-page.md @@ -0,0 +1,1097 @@ +--- +description: Create fully functional landing page from HTML mockups with Docker deployment +mode: landing +model: ollama-cloud/kimi-k2.5 +color: "#8B5CF6" +permission: + read: allow + edit: allow + write: allow + bash: allow + glob: allow + grep: allow + task: + "frontend-developer": allow + "system-analyst": allow + "sdet-engineer": allow + "code-skeptic": allow + "the-fixer": allow + "release-manager": allow + "visual-tester": allow + "browser-automation": allow +--- + +# Landing Page Workflow + +Create a fully functional, tested, and documented landing page from HTML mockups/scetches. Outputs a production-ready Docker container. + +## Parameters + +- `mockup_dir`: Directory containing HTML mockups (default: `./mockups/`) +- `project_name`: Project name for the landing page (required) +- `style`: CSS framework - 'tailwind', 'bootstrap', 'vanilla' (default: 'tailwind') +- `responsive`: Enable responsive design (default: true) +- `docker`: Create Docker deployment (default: true) +- `issue`: Gitea issue number for tracking (optional) + +## Overview + +``` +HTML Mockups → Architecture → Components → Styling → E2E Tests → Docker → Documentation → Product +``` + +## Step 1: Analyze Mockups + +**Agent**: `@FrontendDeveloper` + +### Input Analysis + +1. Scan mockup directory for HTML files: + ```bash + find {mockup_dir} -name "*.html" -o -name "*.htm" | head -20 + ``` + +2. Extract structure from each mockup: + - Sections (header, hero, features, pricing, footer) + - Navigation elements + - Forms and CTAs + - Responsive breakpoints + - Assets (images, fonts, icons) + +3. Create component inventory: + ```markdown + ## Component Inventory + + ### Pages + - index.html → Home page with hero, features, pricing + - about.html → About page with team section + - contact.html → Contact form page + + ### Shared Components + - Header: Logo, navigation, CTA button + - Footer: Links, social icons, copyright + - Hero: Headline, subheadline, CTA buttons + - Features: Icon cards grid + - Pricing: Pricing cards table + - Contact Form: Name, email, message fields + + ### Assets Detected + - Images: logo.png, hero-bg.jpg, feature-icons/ + - Fonts: Inter, Helvetica + - Icons: Font Awesome / Heroicons + ``` + +4. Post analysis to Gitea: + ```python + post_gitea_comment(issue_number, """## 🎨 Landing Page Analysis + + **Pages Found**: {page_count} + **Components Identified**: {component_count} + **Estimated Sections**: {sections} + + ### Component Tree + {component_tree} + + **Next**: Architecture design + """) + ``` + +## Step 2: Architecture Design + +**Agent**: `@SystemAnalyst` + +### Project Structure + +``` +project_name/ +├── src/ +│ ├── index.html # Main landing page +│ ├── pages/ # Additional pages +│ │ ├── about.html +│ │ └── contact.html +│ ├── components/ # Reusable components +│ │ ├── header.html +│ │ ├── footer.html +│ │ └── cta-button.html +│ ├── assets/ +│ │ ├── images/ +│ │ ├── fonts/ +│ │ └── icons/ +│ ├── styles/ +│ │ ├── main.css +│ │ └── components/ +│ ├── scripts/ +│ │ └── main.js +│ └── forms/ +│ └── contact-handler.js +├── public/ +│ └── favicon.ico +├── tests/ +│ ├── e2e/ +│ │ ├── navigation.spec.js +│ │ ├── forms.spec.js +│ │ └── visual.spec.js +│ └── unit/ +├── Dockerfile +├── docker-compose.yml +├── nginx.conf +├── package.json +└── README.md +``` + +### Technology Stack + +| Layer | Technology | Purpose | +|-------|------------|---------| +| Markup | HTML5 | Semantic structure | +| Styling | CSS/Tailwind | Visual design | +| Scripts | Vanilla JS/Alpine.js | Interactivity | +| Build | Vite/esbuild | Optimization | +| Deploy | Docker + Nginx | Production server | +| Testing | Playwright | E2E tests | + +### Architecture Decisions + +```markdown +## Architecture Decision Record + +### ADR-001: CSS Framework +- **Decision**: Use {style} CSS framework +- **Reason**: Based on mockup complexity and maintenance needs +- **Alternatives**: Tailwind (utility-first), Bootstrap (component-based) + +### ADR-002: JavaScript +- **Decision**: Vanilla JS with optional Alpine.js +- **Reason**: Minimal interactivity needs, no heavy framework required +- **Bundle Size**: < 50KB gzipped + +### ADR-003: Build Tool +- **Decision**: Vite for development and build +- **Reason**: Fast HMR, simple config, good for static sites + +### ADR-004: Deployment +- **Decision**: Docker with Nginx +- **Reason**: Production-ready, scalable, easy deployment +``` + +### Post Architecture + +```python +post_gitea_comment(issue_number, """## 📐 Architecture Complete + +**Stack**: HTML5 + {style} + Vanilla JS +**Build**: Vite +**Deploy**: Docker + Nginx + +### Project Structure +``` +{project_tree} +``` + +**Next**: Component implementation +""") +``` + +## Step 3: Component Implementation + +**Agent**: `@FrontendDeveloper` + +### Implementation Order + +1. **Base Structure** + - HTML5 boilerplate + - Meta tags and SEO + - Viewport and responsive base + - CSS reset/normalize + +2. **Layout Components** + - Header (logo, nav, CTA) + - Footer (links, social, copyright) + - Sidebar (if applicable) + +3. **Section Components** + - Hero section + - Features section + - Pricing section + - Testimonials section + - Contact form + - Call-to-action banners + +4. **Interactive Components** + - Mobile menu toggle + - Form validation + - Scroll animations + - Modal windows + +### Component Template + +```html + +
+
+

{title}

+

{subtitle}

+
+ {cta_primary} + {cta_secondary} +
+
+
+ + + + +``` + +### Responsive Implementation + +```css +/* Mobile First Approach */ + +/* Base: Mobile */ +.hero { + padding: 2rem 1rem; +} + +.hero-title { + font-size: 1.5rem; +} + +/* Tablet: 768px+ */ +@media (min-width: 768px) { + .hero { + padding: 4rem 2rem; + } + + .hero-title { + font-size: 2.5rem; + } +} + +/* Desktop: 1024px+ */ +@media (min-width: 1024px) { + .hero { + padding: 6rem 4rem; + } + + .hero-title { + font-size: 3.5rem; + } +} +``` + +### Accessibility Checklist + +- [ ] Semantic HTML5 elements +- [ ] ARIA labels for interactive elements +- [ ] Focus states for keyboard navigation +- [ ] Color contrast ≥ 4.5:1 +- [ ] Alt text for all images +- [ ] Skip navigation link +- [ ] Form labels associated with inputs +- [ ] Form validation messages visible +- [ ] Mobile touch targets ≥ 44x44px + +### Post Implementation + +```python +post_gitea_comment(issue_number, """## 🎨 Components Implemented + +**Files Created**: {file_count} +**Components**: {components_list} + +### Implementation Details +- ✅ Semantic HTML5 +- ✅ {style} CSS framework +- ✅ Responsive breakpoints: mobile, tablet, desktop +- ✅ Accessibility: ARIA labels, focus states + +### Files +{file_list} + +**Next**: Testing +""") +``` + +## Step 4: E2E Testing + +**Agent**: `@SDETEngineer` → `@browser-automation` + +### Test Strategy + +Create comprehensive tests for: + +| Test Type | Purpose | Priority | +|-----------|---------|----------| +| Smoke | Basic functionality | High | +| Navigation | Menu links work | High | +| Responsive | Breakpoints correct | Medium | +| Forms | Validation and submission | High | +| Visual | Pixel-perfect match | Medium | +| Accessibility | WCAG compliance | High | + +### Test File Structure + +```javascript +// tests/e2e/navigation.spec.js +import { test, expect } from '@playwright/test'; + +test.describe('Landing Page Navigation', () => { + test.beforeEach(async ({ page }) => { + await page.goto('/'); + }); + + test('header logo visible', async ({ page }) => { + const logo = page.locator('.header-logo'); + await expect(logo).toBeVisible(); + }); + + test('navigation links work', async ({ page }) => { + const navLinks = page.locator('.nav-link'); + const count = await navLinks.count(); + + for (let i = 0; i < count; i++) { + const link = navLinks.nth(i); + const href = await link.getAttribute('href'); + if (href && href.startsWith('#')) { + await link.click(); + await expect(page.locator(href)).toBeInViewport(); + } + } + }); + + test('mobile menu toggle', async ({ page }) => { + await page.setViewportSize({ width: 375, height: 667 }); + const menuButton = page.locator('.mobile-menu-toggle'); + await menuButton.click(); + await expect(page.locator('.mobile-menu')).toBeVisible(); + }); +}); +``` + +### Visual Regression Tests + +```javascript +// tests/e2e/visual.spec.js +import { test, expect } from '@playwright/test'; + +test.describe('Visual Regression', () => { + const viewports = [ + { name: 'mobile', width: 375, height: 667 }, + { name: 'tablet', width: 768, height: 1024 }, + { name: 'desktop', width: 1280, height: 720 } + ]; + + for (const viewport of viewports) { + test(`matches mockup at ${viewport.name}`, async ({ page }) => { + await page.setViewportSize(viewport); + await page.goto('/'); + await page.waitForLoadState('networkidle'); + + await expect(page).toHaveScreenshot( + `homepage-${viewport.name}.png`, + { maxDiffPixels: 100 } + ); + }); + } +}); +``` + +### Form Validation Tests + +```javascript +// tests/e2e/forms.spec.js +import { test, expect } from '@playwright/test'; + +test.describe('Contact Form', () => { + test('validates required fields', async ({ page }) => { + await page.goto('/'); + await page.click('button[type="submit"]'); + + await expect(page.locator('.error-message')).toBeVisible(); + }); + + test('validates email format', async ({ page }) => { + await page.goto('/'); + await page.fill('input[name="email"]', 'invalid-email'); + await page.click('button[type="submit"]'); + + await expect(page.locator('.email-error')).toBeVisible(); + }); + + test('submits valid form', async ({ page }) => { + await page.goto('/'); + await page.fill('input[name="name"]', 'Test User'); + await page.fill('input[name="email"]', 'test@example.com'); + await page.fill('textarea[name="message"]', 'Test message'); + await page.click('button[type="submit"]'); + + await expect(page.locator('.success-message')).toBeVisible(); + }); +}); +``` + +### Run Tests + +```bash +# Install Playwright +npm install -D @playwright/test + +# Run all tests +npx playwright test + +# Run specific test +npx playwright test navigation.spec.js + +# Run with visible browser +npx playwright test --headed + +# Generate test report +npx playwright show-report +``` + +### Post Testing + +```python +post_gitea_comment(issue_number, """## ✅ Tests Complete + +**Test Suite**: Playwright E2E +**Tests Run**: {test_count} +**Tests Passed**: {pass_count} +**Tests Failed**: {fail_count} + +### Coverage +- ✅ Navigation: {nav_tests} passed +- ✅ Forms: {form_tests} passed +- ✅ Responsive: {resp_tests} passed +- ✅ Visual: {visual_tests} passed +- ✅ Accessibility: {a11y_tests} passed + +### Visual Regression +- Baseline screenshots created +- Diff threshold: 0.1% + +**Next**: Docker deployment +""") +``` + +## Step 5: Docker Deployment + +**Agent**: `@LeadDeveloper` + +### Dockerfile + +```dockerfile +# Dockerfile +FROM node:20-alpine AS builder + +WORKDIR /app + +# Copy package files +COPY package*.json ./ +RUN npm ci --only=production + +# Copy source files +COPY . . + +# Build +RUN npm run build + +# Production image +FROM nginx:alpine + +# Copy built files +COPY --from=builder /app/dist /usr/share/nginx/html + +# Copy nginx config +COPY nginx.conf /etc/nginx/nginx.conf + +# Expose port +EXPOSE 80 + +# Health check +HEALTHCHECK --interval=30s --timeout=3s \ + CMD wget --no-verbose --tries=1 --spider http://localhost/ || exit 1 + +# Start nginx +CMD ["nginx", "-g", "daemon off;"] +``` + +### Nginx Configuration + +```nginx +# nginx.conf +worker_processes auto; +error_log /var/log/nginx/error.log warn; +pid /var/run/nginx.pid; + +events { + worker_connections 1024; +} + +http { + include /etc/nginx/mime.types; + default_type application/octet-stream; + + log_format main '$remote_addr - $remote_user [$time_local] "$request" ' + '$status $body_bytes_sent "$http_referer" ' + '"$http_user_agent" "$http_x_forwarded_for"'; + + access_log /var/log/nginx/access.log main; + + sendfile on; + tcp_nopush on; + tcp_nodelay on; + keepalive_timeout 65; + gzip on; + gzip_types text/plain text/css application/json application/javascript text/xml; + + server { + listen 80; + server_name localhost; + + # Security headers + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-Content-Type-Options "nosniff" always; + add_header X-XSS-Protection "1; mode=block" always; + + root /usr/share/nginx/html; + index index.html; + + # SPA fallback + location / { + try_files $uri $uri/ /index.html; + } + + # Cache static assets + location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + + # No cache for HTML + location ~* \.html$ { + expires -1; + add_header Cache-Control "no-cache, no-store, must-revalidate"; + } + } +} +``` + +### Docker Compose + +```yaml +# docker-compose.yml +version: '3.8' + +services: + landing: + build: + context: . + dockerfile: Dockerfile + ports: + - "8080:80" + environment: + - NODE_ENV=production + restart: unless-stopped + healthcheck: + test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/"] + interval: 30s + timeout: 3s + retries: 3 +``` + +### Build and Run + +```bash +# Build Docker image +docker build -t {project_name}:latest . + +# Run container +docker run -d -p 8080:80 --name {project_name} {project_name}:latest + +# Or with docker-compose +docker-compose up -d + +# Check logs +docker logs {project_name} + +# Health check +curl http://localhost:8080/ +``` + +### Post Docker + +```python +post_gitea_comment(issue_number, """## 🐳 Docker Ready + +**Image**: {project_name}:latest +**Size**: {image_size}MB +**Port**: 8080 + +### Build Commands +```bash +docker build -t {project_name}:latest . +docker run -d -p 8080:80 {project_name}:latest +``` + +### Health Check +```bash +curl http://localhost:8080/ +``` + +**Next**: Documentation +""") +``` + +## Step 6: Documentation + +**Agent**: `@SystemAnalyst` + +### README.md + +```markdown +# {Project Name} - Landing Page + +Fully functional, tested, and Dockerized landing page. + +## Quick Start + +### Development + +```bash +npm install +npm run dev +``` + +Open http://localhost:5173 + +### Production + +```bash +npm run build +npm run preview +``` + +### Docker + +```bash +docker-compose up -d +``` + +Open http://localhost:8080 + +## Project Structure + +``` +{project_name}/ +├── src/ # Source files +│ ├── index.html # Main page +│ ├── pages/ # Additional pages +│ ├── components/ # Reusable components +│ ├── styles/ # CSS styles +│ └── scripts/ # JavaScript +├── tests/ # E2E tests +├── Dockerfile # Docker build +├── nginx.conf # Nginx config +└── docker-compose.yml +``` + +## Features + +- ✅ Semantic HTML5 +- ✅ {style} CSS framework +- ✅ Responsive design (mobile-first) +- ✅ Accessibility (WCAG 2.1 AA) +- ✅ E2E testing with Playwright +- ✅ Docker deployment +- ✅ Nginx configuration optimized + +## Testing + +```bash +npm run test # Run tests +npm run test:ui # UI mode +npm run test:report # View report +``` + +## Customization + +### Colors +Edit `src/styles/variables.css`: +```css +:root { + --primary: #your-color; + --secondary: #your-color; +} +``` + +### Content +Edit HTML files in `src/` directory. + +### Forms +Configure form handler in `src/scripts/forms.js`. + +## Deployment + +### Docker Hub +```bash +docker tag {project_name} your-registry/{project_name} +docker push your-registry/{project_name} +``` + +### Static Hosting +```bash +npm run build +# Upload dist/ to any static host +``` + +## License + +MIT License +``` + +### Technical Documentation + +Create `docs/TECHNICAL.md`: + +```markdown +# Technical Documentation + +## Architecture + +### Technology Stack + +| Component | Technology | Version | +|-----------|------------|---------| +| Markup | HTML5 | - | +| Styling | {style} | {version} | +| Scripts | Vanilla JS | ES6+ | +| Build | Vite | 5.x | +| Server | Nginx | 1.24 | +| Container | Docker | 24.x | + +### Component Structure + +[Component diagram] + +### Data Flow + +[Data flow diagram] + +### Responsive Breakpoints + +| Breakpoint | Width | Target | +|------------|-------|--------| +| xs | <640px | Mobile | +| sm | ≥640px | Large mobile | +| md | ≥768px | Tablet | +| lg | ≥1024px | Desktop | +| xl | ≥1280px | Large desktop | + +## Security + +### Headers +- X-Frame-Options: SAMEORIGIN +- X-Content-Type-Options: nosniff +- X-XSS-Protection: 1; mode=block + +### Form Handling +- Client-side validation +- CSRF protection (if backend) +- Input sanitization + +## Performance + +### Optimization +- Minified CSS/JS +- Image optimization +- Lazy loading +- Gzip compression + +### Metrics Target +- First Contentful Paint < 1.5s +- Largest Contentful Paint < 2.5s +- Cumulative Layout Shift < 0.1 +- Total Blocking Time < 200ms +``` + +### Deployment Guide + +Create `docs/DEPLOYMENT.md`: + +```markdown +# Deployment Guide + +## Prerequisites + +- Docker 24.x +- Docker Compose (optional) +- 512MB RAM minimum +- 1GB disk space + +## Option 1: Docker + +```bash +docker-compose up -d +``` + +## Option 2: Static Hosting + +1. Build: `npm run build` +2. Upload `dist/` folder +3. Configure server for SPA routing + +## Option 3: CDN + +1. Build: `npm run build` +2. Upload to CDN +3. Configure cache headers + +## Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| NODE_ENV | production | Environment | +| PORT | 80 | Server port | + +## SSL Configuration + +Add to nginx.conf: +```nginx +listen 443 ssl; +ssl_certificate /path/to/cert.pem; +ssl_certificate_key /path/to/key.pem; +``` + +## Monitoring + +### Health Check +```bash +curl http://localhost:8080/health +``` + +### Logs +```bash +docker logs {project_name} +``` +``` + +### Post Documentation + +```python +post_gitea_comment(issue_number, """## 📚 Documentation Complete + +### Files Created +- ✅ README.md - Quick start guide +- ✅ docs/TECHNICAL.md - Technical docs +- ✅ docs/DEPLOYMENT.md - Deployment guide + +### Documentation Coverage +- Installation instructions +- Usage examples +- Configuration options +- Troubleshooting guide + +**Next**: Final validation +""") +``` + +## Step 7: Final Validation + +**Agent**: `@CodeSkeptic` → `@Evaluator` + +### Validation Checklist + +- [ ] All HTML valid +- [ ] CSS valid +- [ ] JavaScript no errors +- [ ] All tests passing +- [ ] Docker build succeeds +- [ ] Documentation complete +- [ ] Accessibility audit passed +- [ ] Performance audit passed +- [ ] Mobile responsive verified + +### Run Validations + +```bash +# HTML validation +npx html-validate src/**/*.html + +# CSS validation +npx stylelint "src/**/*.css" + +# JS linting +npx eslint src/**/*.js + +# Accessibility audit +npx pa11y http://localhost:8080 + +# Performance audit +npx lighthouse http://localhost:8080 --output=json +``` + +### Final Report + +```python +post_gitea_comment(issue_number, """## ✅ Landing Page Complete + +### Summary +**Project**: {project_name} +**Status**: Production Ready +**Score**: {score}/10 + +### Deliverables +- ✅ {pages_count} HTML pages +- ✅ {components_count} components +- ✅ {tests_count} E2E tests (all passing) +- ✅ Docker image ({image_size}MB) +- ✅ Complete documentation + +### Metrics +- Accessibility: WCAG 2.1 AA +- Performance: Lighthouse {lighthouse_score} +- Responsive: Mobile-first +- Bundle size: {bundle_size}KB + +### Files Created +``` +{file_tree} +``` + +### Quick Start +```bash +docker-compose up -d +# Open http://localhost:8080 +``` + +### Delivery +This landing page is ready for client delivery: +1. All source code in `/src` +2. Docker image ready for deployment +3. Documentation complete +4. Tests passing + +**Status**: 🟢 COMPLETE +""") +``` + +## Quality Gates + +| Gate | Criteria | Pass Condition | +|------|----------|----------------| +| Analysis | All components identified | 100% mockup coverage | +| Architecture | Tech stack defined | Stack documented | +| Implementation | All components built | No console errors | +| Testing | All tests passing | 100% pass rate | +| Docker | Container builds and runs | Health check passes | +| Documentation | All docs created | README complete | +| Validation | All audits passing | Score ≥ 8/10 | + +## Error Handling + +### Build Errors +``` +If build fails: +1. Check console for errors +2. Verify all dependencies installed +3. Run `npm run lint` for issues +4. Fix reported problems +5. Retry build +``` + +### Test Failures +``` +If tests fail: +1. Run `npx playwright test --debug` +2. Check screenshots in test-results/ +3. Fix identified issues +4. Re-run tests +``` + +### Docker Issues +``` +If Docker fails: +1. Check Docker daemon running +2. Verify Dockerfile syntax +3. Check disk space +4. Review build logs: `docker build --progress=plain .` +``` + +## Handoff to Client + +After completion, deliver: + +1. **Source Code** + - Complete `/src` directory + - All components and pages + - All assets and styles + +2. **Docker Image** + - Pre-built image + - Or Dockerfile for custom build + +3. **Documentation** + - README.md (quick start) + - docs/TECHNICAL.md (technical details) + - docs/DEPLOYMENT.md (deployment guide) + +4. **Tests** + - All test files + - Test report + - Visual regression baselines + +5. **Instructions** + - How to run locally + - How to deploy + - How to customize + +## Example Invocation + +``` +User: /landing-page --mockup_dir=./mockups --project_name=MyProduct --style=tailwind + +Agent: +1. Analyzes mockups in ./mockups/ +2. Creates project structure +3. Implements components +4. Writes E2E tests +5. Creates Docker setup +6. Generates documentation +7. Validates everything +8. Reports to Gitea +9. Delivers ready-to-deploy package +``` + +## Gitea Integration + +Every step posts progress to the linked issue: + +1. 🎨 Analysis → Issue comment with component inventory +2. 📐 Architecture → Issue comment with project structure +3. 🛠️ Implementation → Issue comment with file changes +4. ✅ Testing → Issue comment with test results +5. 🐳 Docker → Issue comment with build status +6. 📚 Documentation → Issue comment with deliverables +7. ✅ Complete → Issue comment with final package + +## Status Tracking + +Update issue labels throughout: + +- `status: new` → Analysis starting +- `status: designing` → Architecture in progress +- `status: implementing` → Components being built +- `status: testing` → E2E tests running +- `status: releasing` → Docker building +- `status: completed` → Package delivered \ No newline at end of file