heraspec 0.1.13 → 0.1.15

package/dist/core/templates/skills/deploy-documentation-skill.md

@@ -0,0 +1,408 @@
+---
+name: deploy-documentation
+description: Tự động hoá quy trình chụp screenshot và cập nhật documentation sau mỗi lần build & deploy — discover routes, generate manifest, capture screenshots, update HTML. Hoạt động với mọi loại web application.
+projectType: all
+---
+
+# Deploy Documentation — Auto Screenshot & Docs Generator
+
+## Purpose
+
+Skill này tự động hoá quy trình chụp ảnh màn hình và cập nhật documentation sau mỗi lần build & deploy sản phẩm. Thay vì developer phải truy cập thủ công từng trang, chụp ảnh, rồi cập nhật landing page — skill này thực hiện toàn bộ quy trình một cách tự động và nhất quán.
+
+**Vấn đề giải quyết:**
+- Sau khi build xong plugin/module/software, developer phải truy cập từng trang tính năng trên site
+- Chụp ảnh thủ công, dễ sai sót (quên cập nhật mô tả)
+- Tốn thời gian khi có nhiều route, lặp lại mỗi version
+
+## When to Use
+
+- Sau mỗi lần release / deploy phiên bản mới
+- Khi cần sync documentation screenshots với UI thực tế
+- Khi thêm tính năng mới chưa có trong manifest
+- Khi cần chụp ảnh từ nhiều site khác nhau (local, demo, client)
+
+---
+
+## Architecture: 2 Phases
+
+```
+Phase 1: DISCOVER — Quét codebase → Suggest manifest entries
+Phase 2: CAPTURE  — Đọc manifest → Login → Navigate → Screenshot → Update HTML
+```
+
+---
+
+## Phase 1: Route Discovery & Manifest Generation
+
+### Mục đích
+Tự động quét codebase để phát hiện routes/pages, sau đó suggest thêm entries vào `deploy_manifest.json`.
+
+### Cách hoạt động
+
+**1. Quét routes — tìm tất cả route definitions trong codebase:**
+
+| Project Type | Source files |
+|---|---|
+| Perfex CRM Module | `config/my_routes.php` + controller method names |
+| Laravel App | `routes/web.php`, `routes/api.php` |
+| WordPress Plugin | `add_menu_page()`, `add_submenu_page()` hooks |
+| Next.js / Vite SPA | `pages/` directory, router config files |
+| Electron App | Window/view registrations |
+| Generic | Navigation config files, sitemap |
+
+**2. Quét menu registrations — tìm sidebar/nav menu items:**
+- Perfex CRM: `$this->app_menu->add_sidebar_menu_item()` calls
+- WordPress: `add_menu_page()`, `add_submenu_page()`
+- Generic: tìm navigation config files
+
+**3. Quét migration changelog:**
+- Parse `logChanged()` hoặc `CHANGELOG.md` để detect features mới chưa có trong manifest
+
+**4. Cross-reference với manifest:**
+- So sánh routes discovered vs entries đã khai báo → suggest entries còn thiếu
+
+### Discovery Scan Targets (Perfex CRM modules — example)
+
+```
+modules/{module}/config/my_routes.php       → Route definitions
+modules/{module}/data_builder.php           → Menu items (add_sidebar_menu_item)
+modules/{module}/controllers/*.php          → Controller methods = pages
+modules/{module}/views/admin/**/*.php       → View templates
+modules/{module}/migrations/*_version_*.php → Changelog (logChanged)
+```
+
+### Output Format — Suggested Entry
+
+```json
+{
+  "id": "auto-discovered-{route}",
+  "filename": "{Feature-Name}-{Product}.png",
+  "title": "{Feature Name}",
+  "route": "/admin/{module}/{controller}/{method}",
+  "wait_for": "#app, .panel, .table-responsive",
+  "section": "core-features",
+  "actions_before": [
+    { "action": "wait", "ms": 2000 }
+  ],
+  "_discovered_from": "controller: Builder.php → method: index()",
+  "_status": "suggested"
+}
+```
+
+> **IMPORTANT**: Entries có `_status: "suggested"` cần user review và confirm trước khi chạy Phase 2. Agent MUST NOT auto-proceed.
+
+### Site Suggestion Logic (khi discover)
+
+| Loại page | Site đề xuất | Lý do |
+|---|---|---|
+| Admin management pages | `local` | Không cần real data |
+| Charts, runtime reports | `demo` | Cần data đẹp, trực quan |
+| Public embed / iframe | `demo` | Cần public view đã setup |
+| Client-specific feature | `client_x` | Cần data thực tế của client |
+
+---
+
+## Phase 2: Screenshot Capture & Documentation Update
+
+### Prerequisites
+- File `deploy_manifest.json` đã được review và xác nhận
+- Site đang chạy và accessible tại `base_url`
+- Credentials hợp lệ
+
+### Step 1: Build Site Groups
+
+```
+1. Đọc manifest.sites{} và manifest.default_site
+2. Với mỗi entry trong screenshots[]:
+   - Nếu entry có "site" key → site = sites[entry.site]
+   - Nếu không → site = sites[default_site]
+3. Group entries by site key → { local: [...], demo: [...], client_x: [...] }
+```
+
+### Step 2: Login (một lần mỗi site)
+
+```
+Foreach unique_site in groups:
+  site_config = sites[unique_site]
+  1. Mở browser tab mới tại: {site_config.base_url}{site_config.login_url}
+  2. Điền credentials:
+       - email_selector ← site_config.login_form.email_selector
+       - password_selector ← site_config.login_form.password_selector
+  3. Click submit: site_config.login_form.submit_selector
+  4. Chờ redirect hoặc dashboard element xuất hiện
+  5. Lưu session/cookies cho site này
+  Log: ✅ Logged in to {site_config.base_url} / ❌ Login failed
+```
+
+**login_form supports:**
+- Perfex CRM: `input[name='email']` + `input[name='password']`
+- WordPress: `input#user_login` + `input#user_pass`
+- Laravel / generic: any valid CSS selector
+
+### Step 3: Screenshot Loop
+
+```
+Foreach entry in manifest.screenshots[]:
+  site_config = sites[entry.site || default_site]
+  base_url    = site_config.base_url
+
+  1. Navigate tới {base_url}{entry.route}
+     Resolve dynamic tokens nếu có:
+       {first_view_id}      → Scrape view list page → first row ID
+       {first_view_route}   → Scrape view list page → first row route slug
+       {first_public_route} → Scrape views → first with public_access indicator
+       {latest_record_id}   → Scrape or sort by date → most recent ID
+
+  2. Set viewport: entry.viewport || manifest.defaults.viewport
+
+  3. Execute actions_before[] theo thứ tự:
+       wait                → sleep(ms)
+       click               → click(selector)
+       click_first_visible → find first visible element → click
+       scroll_down         → window.scrollBy(0, px)
+       scroll_to           → element.scrollIntoView()
+       type                → type text into selector (for search/filter inputs)
+
+  4. Wait for: entry.wait_for selector to appear in DOM
+
+  5. Capture screenshot:
+       format = entry.format || manifest.defaults.format
+       Save → {output.images_dir}/{entry.filename}
+
+  Log: ✅ {entry.id} → {entry.filename} / ❌ reason
+```
+
+### Step 4: HTML Update (Optional)
+
+```
+1. Đọc index.html
+2. Cập nhật version number từ source code
+3. Cập nhật date (Updated: {current month year})
+4. Parse changelog từ migration file → inject vào #changelog-content
+5. Verify tất cả <img src="images/..."> đều có file tương ứng
+6. Save index.html
+```
+
+---
+
+## Manifest Format Reference
+
+Tạo file `deploy_manifest.json` **cùng folder với `AGENTS.heraspec.md` và thư mục `heraspec/`** của project/module đó — không nhất thiết là root của toàn bộ monorepo:
+
+```json
+{
+  "product": {
+    "name": "Product Name",
+    "tagline": "Short description",
+    "version_source": "path/to/version_file",
+    "changelog_source": "path/to/migration_or_changelog"
+  },
+
+  "sites": {
+    "local": {
+      "base_url": "https://localhost:PORT",
+      "login_url": "/admin/authentication",
+      "login_form": {
+        "email_selector": "input[name='email']",
+        "password_selector": "input[name='password']",
+        "submit_selector": "button[type='submit']"
+      },
+      "credentials": {
+        "email": "admin@admin.com",
+        "password": "password"
+      },
+      "description": "Local dev"
+    },
+    "demo": {
+      "base_url": "https://demo.example.com",
+      "login_url": "/admin/authentication",
+      "login_form": {
+        "email_selector": "input[name='email']",
+        "password_selector": "input[name='password']",
+        "submit_selector": "button[type='submit']"
+      },
+      "credentials": {
+        "email": "admin@demo.com",
+        "password": "password"
+      },
+      "description": "Live demo site for marketing screenshots"
+    }
+  },
+
+  "default_site": "local",
+
+  "output": {
+    "images_dir": "path/to/documentation/images",
+    "html_file": "path/to/documentation/index.html"
+  },
+
+  "defaults": {
+    "viewport": { "width": 1440, "height": 900 },
+    "format": "png",
+    "wait_ms": 2000
+  },
+
+  "screenshots": [
+    {
+      "id": "feature-overview",
+      "filename": "Feature-Overview-ProductName.png",
+      "title": "Feature Overview",
+      "route": "/admin/module/page",
+      "wait_for": "#app, .panel, .table-responsive",
+      "section": "core-features",
+      "actions_before": [
+        { "action": "wait", "ms": 2000 }
+      ]
+    },
+    {
+      "id": "feature-on-demo",
+      "site": "demo",
+      "filename": "Feature-Demo-ProductName.png",
+      "title": "Feature (Demo Data)",
+      "route": "/admin/module/page",
+      "wait_for": ".chart-container",
+      "section": "core-features",
+      "actions_before": [
+        { "action": "wait", "ms": 3000 }
+      ]
+    }
+  ]
+}
+```
+
+### Dynamic Route Tokens
+
+| Token | Resolution |
+|-------|-----------|
+| `{first_view_id}` | ID của record đầu tiên trong view list |
+| `{first_view_route}` | Route slug của view đầu tiên |
+| `{first_public_route}` | Route của view public đầu tiên |
+| `{latest_record_id}` | ID của record mới nhất |
+
+Agent resolves các token này bằng cách scrape trang list hoặc query database.
+
+---
+
+## Prompt Templates
+
+### Full workflow (Discover + Capture):
+
+```
+Sử dụng skill deploy-documentation.
+Project: {module_path}
+Manifest: {manifest_path}
+
+1. Phase 1: Quét codebase tại {module_path}, phát hiện routes/features chưa có trong manifest, suggest entries mới (đề xuất site phù hợp cho từng entry)
+2. Tôi sẽ review và confirm manifest
+3. Phase 2: Login vào từng site trong manifest, chụp tất cả screenshots, lưu vào images_dir
+4. Cập nhật index.html với ảnh mới và changelog
+```
+
+### Chỉ chụp ảnh — tất cả sites (manifest đã sẵn):
+
+```
+Sử dụng skill deploy-documentation.
+Đọc manifest tại {manifest_path}.
+Login vào từng site được khai báo, chụp tất cả screenshots theo manifest, lưu vào output.images_dir.
+```
+
+### Chỉ chụp ảnh — 1 site cụ thể:
+
+```
+Sử dụng skill deploy-documentation.
+Đọc manifest tại {manifest_path}.
+Chỉ chụp các screenshots thuộc site "demo".
+Login vào demo site, navigate và capture, lưu vào images_dir.
+```
+
+### Chỉ chụp lại 1 số ảnh cụ thể:
+
+```
+Sử dụng skill deploy-documentation.
+Đọc manifest tại {manifest_path}.
+Chỉ chụp lại các entries: {id1}, {id2}, {id3}.
+Sử dụng site mặc định (default_site) trừ khi entry có khai báo site riêng.
+```
+
+### Chỉ discover — suggest entries mới:
+
+```
+Sử dụng skill deploy-documentation.
+Quét codebase tại {module_path}, so sánh với manifest tại {manifest_path}.
+Suggest entries mới cho features/routes chưa được khai báo.
+Với mỗi entry mới: đề xuất site phù hợp (local nếu là admin page, demo nếu cần real-data screenshot).
+Không tự thêm vào manifest — liệt kê để tôi review trước.
+```
+
+---
+
+## Compatibility — Supported Project Types
+
+| Project Type | Route Discovery Source |
+|---|---|
+| Perfex CRM Module | `my_routes.php` + controller methods |
+| Laravel App | `routes/web.php` + `routes/api.php` |
+| WordPress Plugin | `add_menu_page()` + `add_submenu_page()` |
+| Next.js / Vite SPA | `pages/` directory + router config |
+| Electron App | Window/view registrations |
+| Generic Web App | Navigation config files, sitemap |
+
+Mỗi project chỉ cần 1 file `deploy_manifest.json` riêng. Cùng skill, cùng workflow.
+
+---
+
+## File Structure (per project/module)
+
+`deploy_manifest.json` nằm **cùng folder với `AGENTS.heraspec.md` và `heraspec/`** của module/project đó:
+
+```
+{heraspec_workspace_dir}/        ← Thư mục chứa AGENTS.heraspec.md
+├── AGENTS.heraspec.md
+├── heraspec/
+├── deploy_manifest.json         ← Đặt tại đây
+└── documentation/
+    ├── index.html
+    └── images/
+```
+
+**Ví dụ với Perfex CRM** (mỗi module là một workspace HeraSpec riêng):
+
+```
+perfex_crm/
+└── modules/
+    ├── data_builder/
+    │   ├── AGENTS.heraspec.md
+    │   ├── heraspec/
+    │   ├── deploy_manifest.json    ← manifest của data_builder
+    │   └── documentation/
+    └── another_module/
+        ├── AGENTS.heraspec.md
+        ├── heraspec/
+        ├── deploy_manifest.json    ← manifest riêng của another_module
+        └── documentation/
+```
+
+> **Rule**: `deploy_manifest.json` luôn nằm cùng cấp với `AGENTS.heraspec.md` và `heraspec/` — dù workspace đó là module con hay project độc lập.
+
+
+---
+
+## Inputs
+
+- `deploy_manifest.json` — manifest file của project (xem templates/deploy_manifest.template.json)
+- Codebase path — để Phase 1 discover routes
+- Running site — để Phase 2 capture screenshots
+
+## Outputs
+
+- Screenshot PNG/WebP files tại `output.images_dir`
+- Updated `index.html` tại `output.html_file`
+- Suggested entries (Phase 1 only) — danh sách để user review
+
+## Limitations
+
+- Yêu cầu browser agent có khả năng điều khiển browser (navigate, click, screenshot)
+- Login session không persistent giữa các lần chạy — phải login lại mỗi session
+- Dynamic tokens (`{first_view_id}`, v.v.) cần site đang có dữ liệu thực
+- HTML auto-update chỉ hoạt động nếu `index.html` có structure đúng format (có `#changelog-content`, `<img>` tags với đúng src pattern)

package/dist/core/templates/skills/design-system/knowledge/design-systems/airbnb/DESIGN.md

@@ -0,0 +1,246 @@
+# Design System: Airbnb
+
+## 1. Visual Theme & Atmosphere
+
+Airbnb's website is a warm, photography-forward marketplace that feels like flipping through a travel magazine where every page invites you to book. The design operates on a foundation of pure white (`#ffffff`) with the iconic Rausch Red (`#ff385c`) — named after Airbnb's first street address — serving as the singular brand accent. The result is a clean, airy canvas where listing photography, category icons, and the red CTA button are the only sources of color.
+
+The typography uses Airbnb Cereal VF — a custom variable font that's warm and approachable, with rounded terminals that echo the brand's "belong anywhere" philosophy. The font operates in a tight weight range: 500 (medium) for most UI, 600 (semibold) for emphasis, and 700 (bold) for primary headings. Slight negative letter-spacing (-0.18px to -0.44px) on headings creates a cozy, intimate reading experience rather than the compressed efficiency of tech companies.
+
+What distinguishes Airbnb is its palette-based token system (`--palette-*`) and multi-layered shadow approach. The primary card shadow uses a three-layer stack (`rgba(0,0,0,0.02) 0px 0px 0px 1px, rgba(0,0,0,0.04) 0px 2px 6px, rgba(0,0,0,0.1) 0px 4px 8px`) that creates a subtle, warm lift. Combined with generous border-radius (8px–32px), circular navigation controls (50%), and a category pill bar with horizontal scrolling, the interface feels tactile and inviting — designed for browsing, not commanding.
+
+**Key Characteristics:**
+- Pure white canvas with Rausch Red (`#ff385c`) as singular brand accent
+- Airbnb Cereal VF — custom variable font with warm, rounded terminals
+- Palette-based token system (`--palette-*`) for systematic color management
+- Three-layer card shadows: border ring + soft blur + stronger blur
+- Generous border-radius: 8px buttons, 14px badges, 20px cards, 32px large elements
+- Circular navigation controls (50% radius)
+- Photography-first listing cards — images are the hero content
+- Near-black text (`#222222`) — warm, not cold
+- Luxe Purple (`#460479`) and Plus Magenta (`#92174d`) for premium tiers
+
+## 2. Color Palette & Roles
+
+### Primary Brand
+- **Rausch Red** (`#ff385c`): `--palette-bg-primary-core`, primary CTA, brand accent, active states
+- **Deep Rausch** (`#e00b41`): `--palette-bg-tertiary-core`, pressed/dark variant of brand red
+- **Error Red** (`#c13515`): `--palette-text-primary-error`, error text on light
+- **Error Dark** (`#b32505`): `--palette-text-secondary-error-hover`, error hover
+
+### Premium Tiers
+- **Luxe Purple** (`#460479`): `--palette-bg-primary-luxe`, Airbnb Luxe tier branding
+- **Plus Magenta** (`#92174d`): `--palette-bg-primary-plus`, Airbnb Plus tier branding
+
+### Text Scale
+- **Near Black** (`#222222`): `--palette-text-primary`, primary text — warm, not cold
+- **Focused Gray** (`#3f3f3f`): `--palette-text-focused`, focused state text
+- **Secondary Gray** (`#6a6a6a`): Secondary text, descriptions
+- **Disabled** (`rgba(0,0,0,0.24)`): `--palette-text-material-disabled`, disabled state
+- **Link Disabled** (`#929292`): `--palette-text-link-disabled`, disabled links
+
+### Interactive
+- **Legal Blue** (`#428bff`): `--palette-text-legal`, legal links, informational
+- **Border Gray** (`#c1c1c1`): Border color for cards and dividers
+- **Light Surface** (`#f2f2f2`): Circular navigation buttons, secondary surfaces
+
+### Surface & Shadows
+- **Pure White** (`#ffffff`): Page background, card surfaces
+- **Card Shadow** (`rgba(0,0,0,0.02) 0px 0px 0px 1px, rgba(0,0,0,0.04) 0px 2px 6px, rgba(0,0,0,0.1) 0px 4px 8px`): Three-layer warm lift
+- **Hover Shadow** (`rgba(0,0,0,0.08) 0px 4px 12px`): Button hover elevation
+
+## 3. Typography Rules
+
+### Font Family
+- **Primary**: `Airbnb Cereal VF`, fallbacks: `Circular, -apple-system, system-ui, Roboto, Helvetica Neue`
+- **OpenType Features**: `"salt"` (stylistic alternates) on specific caption elements
+
+### Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|------|--------|-------------|----------------|-------|
+| Section Heading | Airbnb Cereal VF | 28px (1.75rem) | 700 | 1.43 | normal | Primary headings |
+| Card Heading | Airbnb Cereal VF | 22px (1.38rem) | 600 | 1.18 (tight) | -0.44px | Category/card titles |
+| Card Heading Medium | Airbnb Cereal VF | 22px (1.38rem) | 500 | 1.18 (tight) | -0.44px | Lighter variant |
+| Sub-heading | Airbnb Cereal VF | 21px (1.31rem) | 700 | 1.43 | normal | Bold sub-headings |
+| Feature Title | Airbnb Cereal VF | 20px (1.25rem) | 600 | 1.20 (tight) | -0.18px | Feature headings |
+| UI Medium | Airbnb Cereal VF | 16px (1.00rem) | 500 | 1.25 (tight) | normal | Nav, emphasized text |
+| UI Semibold | Airbnb Cereal VF | 16px (1.00rem) | 600 | 1.25 (tight) | normal | Strong emphasis |
+| Button | Airbnb Cereal VF | 16px (1.00rem) | 500 | 1.25 (tight) | normal | Button labels |
+| Body / Link | Airbnb Cereal VF | 14px (0.88rem) | 400 | 1.43 | normal | Standard body |
+| Body Medium | Airbnb Cereal VF | 14px (0.88rem) | 500 | 1.29 (tight) | normal | Medium body |
+| Caption Salt | Airbnb Cereal VF | 14px (0.88rem) | 600 | 1.43 | normal | `"salt"` feature |
+| Small | Airbnb Cereal VF | 13px (0.81rem) | 400 | 1.23 (tight) | normal | Descriptions |
+| Tag | Airbnb Cereal VF | 12px (0.75rem) | 400–700 | 1.33 | normal | Tags, prices |
+| Badge | Airbnb Cereal VF | 11px (0.69rem) | 600 | 1.18 (tight) | normal | `"salt"` feature |
+| Micro Uppercase | Airbnb Cereal VF | 8px (0.50rem) | 700 | 1.25 (tight) | 0.32px | `text-transform: uppercase` |
+
+### Principles
+- **Warm weight range**: 500–700 dominate. No weight 300 or 400 for headings — Airbnb's type is always at least medium weight, creating a warm, confident voice.
+- **Negative tracking on headings**: -0.18px to -0.44px letter-spacing on display creates intimate, cozy headings rather than cold, compressed ones.
+- **"salt" OpenType feature**: Stylistic alternates on specific UI elements (badges, captions) create subtle glyph variations that add visual interest.
+- **Variable font precision**: Cereal VF enables continuous weight interpolation, though the design system uses discrete stops at 500, 600, and 700.
+
+## 4. Component Stylings
+
+### Buttons
+
+**Primary Dark**
+- Background: `#222222` (near-black, not pure black)
+- Text: `#ffffff`
+- Padding: 0px 24px
+- Radius: 8px
+- Hover: transitions to error/brand accent via `var(--accent-bg-error)`
+- Focus: `0 0 0 2px var(--palette-grey1000)` ring + scale(0.92)
+
+**Circular Nav**
+- Background: `#f2f2f2`
+- Text: `#222222`
+- Radius: 50% (circle)
+- Hover: shadow `rgba(0,0,0,0.08) 0px 4px 12px` + translateX(50%)
+- Active: 4px white border ring + focus shadow
+- Focus: scale(0.92) shrink animation
+
+### Cards & Containers
+- Background: `#ffffff`
+- Radius: 14px (badges), 20px (cards/buttons), 32px (large)
+- Shadow: `rgba(0,0,0,0.02) 0px 0px 0px 1px, rgba(0,0,0,0.04) 0px 2px 6px, rgba(0,0,0,0.1) 0px 4px 8px` (three-layer)
+- Listing cards: full-width photography on top, details below
+- Carousel controls: circular 50% buttons
+
+### Inputs
+- Search: `#222222` text
+- Focus: `var(--palette-bg-primary-error)` background tint + `0 0 0 2px` ring
+- Radius: depends on context (search bar uses pill-like rounding)
+
+### Navigation
+- White sticky header with search bar centered
+- Airbnb logo (Rausch Red) left-aligned
+- Category filter pills: horizontal scroll below search
+- Circular nav controls for carousel navigation
+- "Become a Host" text link, avatar/menu right-aligned
+
+### Image Treatment
+- Listing photography fills card top with generous height
+- Image carousel with dot indicators
+- Heart/wishlist icon overlay on images
+- 8px–14px radius on contained images
+
+## 5. Layout Principles
+
+### Spacing System
+- Base unit: 8px
+- Scale: 2px, 3px, 4px, 6px, 8px, 10px, 11px, 12px, 15px, 16px, 22px, 24px, 32px
+
+### Grid & Container
+- Full-width header with centered search
+- Category pill bar: horizontal scrollable row
+- Listing grid: responsive multi-column (3–5 columns on desktop)
+- Full-width footer with link columns
+
+### Whitespace Philosophy
+- **Travel-magazine spacing**: Generous vertical padding between sections creates a leisurely browsing pace — you're meant to scroll slowly, like browsing a magazine.
+- **Photography density**: Listing cards are packed relatively tightly, but each image is large enough to feel immersive.
+- **Search bar prominence**: The search bar gets maximum vertical space in the header — finding your destination is the primary action.
+
+### Border Radius Scale
+- Subtle (4px): Small links
+- Standard (8px): Buttons, tabs, search elements
+- Badge (14px): Status badges, labels
+- Card (20px): Feature cards, large buttons
+- Large (32px): Large containers, hero elements
+- Circle (50%): Nav controls, avatars, icons
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Flat (Level 0) | No shadow | Page background, text blocks |
+| Card (Level 1) | `rgba(0,0,0,0.02) 0px 0px 0px 1px, rgba(0,0,0,0.04) 0px 2px 6px, rgba(0,0,0,0.1) 0px 4px 8px` | Listing cards, search bar |
+| Hover (Level 2) | `rgba(0,0,0,0.08) 0px 4px 12px` | Button hover, interactive lift |
+| Active Focus (Level 3) | `rgb(255,255,255) 0px 0px 0px 4px` + focus ring | Active/focused elements |
+
+**Shadow Philosophy**: Airbnb's three-layer shadow system creates a warm, natural lift. Layer 1 (`0px 0px 0px 1px` at 0.02 opacity) is an ultra-subtle border. Layer 2 (`0px 2px 6px` at 0.04) provides soft ambient shadow. Layer 3 (`0px 4px 8px` at 0.1) adds the primary lift. This graduated approach creates shadows that feel like natural light rather than CSS effects.
+
+## 7. Do's and Don'ts
+
+### Do
+- Use `#222222` (warm near-black) for text — never pure `#000000`
+- Apply Rausch Red (`#ff385c`) only for primary CTAs and brand moments — it's the singular accent
+- Use Airbnb Cereal VF at weight 500–700 — the warm weight range is intentional
+- Apply the three-layer card shadow for all elevated surfaces
+- Use generous border-radius: 8px for buttons, 20px for cards, 50% for controls
+- Use photography as the primary visual content — listings are image-first
+- Apply negative letter-spacing (-0.18px to -0.44px) on headings for intimacy
+- Use circular (50%) buttons for carousel/navigation controls
+
+### Don't
+- Don't use pure black (`#000000`) for text — always `#222222` (warm)
+- Don't apply Rausch Red to backgrounds or large surfaces — it's an accent only
+- Don't use thin font weights (300, 400) for headings — 500 minimum
+- Don't use heavy shadows (>0.1 opacity as primary layer) — keep them warm and graduated
+- Don't use sharp corners (0–4px) on cards — the generous rounding (20px+) is core
+- Don't introduce additional brand colors beyond the Rausch/Luxe/Plus system
+- Don't override the palette token system — use `--palette-*` variables consistently
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Mobile Small | <375px | Single column, compact search |
+| Mobile | 375–550px | Standard mobile listing grid |
+| Tablet Small | 550–744px | 2-column listings |
+| Tablet | 744–950px | Search bar expansion |
+| Desktop Small | 950–1128px | 3-column listings |
+| Desktop | 1128–1440px | 4-column grid, full header |
+| Large Desktop | 1440–1920px | 5-column grid |
+| Ultra-wide | >1920px | Maximum grid width |
+
+*Note: Airbnb has 61 detected breakpoints — one of the most granular responsive systems observed, reflecting their obsession with layout at every possible screen size.*
+
+### Touch Targets
+- Circular nav buttons: adequate 50% radius sizing
+- Listing cards: full-card tap target on mobile
+- Search bar: prominently sized for thumb interaction
+- Category pills: horizontally scrollable with generous padding
+
+### Collapsing Strategy
+- Listing grid: 5 → 4 → 3 → 2 → 1 columns
+- Search: expanded bar → compact bar → overlay
+- Category pills: horizontal scroll at all sizes
+- Navigation: full header → mobile simplified
+- Map: side panel → overlay/toggle
+
+### Image Behavior
+- Listing photos: carousel with swipe on mobile
+- Responsive image sizing with aspect ratio maintained
+- Heart overlay positioned consistently across sizes
+- Photo quality adjusts based on viewport
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Background: Pure White (`#ffffff`)
+- Text: Near Black (`#222222`)
+- Brand accent: Rausch Red (`#ff385c`)
+- Secondary text: `#6a6a6a`
+- Disabled: `rgba(0,0,0,0.24)`
+- Card border: `rgba(0,0,0,0.02) 0px 0px 0px 1px`
+- Card shadow: full three-layer stack
+- Button surface: `#f2f2f2`
+
+### Example Component Prompts
+- "Create a listing card: white background, 20px radius. Three-layer shadow: rgba(0,0,0,0.02) 0px 0px 0px 1px, rgba(0,0,0,0.04) 0px 2px 6px, rgba(0,0,0,0.1) 0px 4px 8px. Photo area on top (16:10 ratio), details below: 16px Airbnb Cereal VF weight 600 title, 14px weight 400 description in #6a6a6a."
+- "Design search bar: white background, full card shadow, 32px radius on container. Search text at 14px Cereal VF weight 400. Red search button (#ff385c, 50% radius, white icon)."
+- "Build category pill bar: horizontal scrollable row. Each pill: 14px Cereal VF weight 600, #222222 text, bottom border on active. Circular prev/next arrows (#f2f2f2 bg, 50% radius)."
+- "Create a CTA button: #222222 background, white text, 8px radius, 16px Cereal VF weight 500, 0px 24px padding. Hover: brand red accent."
+- "Design a heart/wishlist button: transparent background, 50% radius, white heart icon with dark shadow outline."
+
+### Iteration Guide
+1. Start with white — the photography provides all the color
+2. Rausch Red (#ff385c) is the singular accent — use sparingly for CTAs only
+3. Near-black (#222222) for text — the warmth matters
+4. Three-layer shadows create natural, warm lift — always use all three layers
+5. Generous radius: 8px buttons, 20px cards, 50% controls
+6. Cereal VF at 500–700 weight — no thin weights for any heading
+7. Photography is hero — every listing card is image-first