@jaimevalasek/aioson 1.7.0 → 1.8.0

package/template/.aioson/docs/site-forge-build.md

@@ -0,0 +1,195 @@
+---
+description: "site-forge Phase 4 — Build Layer: component implementation, interactions, video, asset wiring, assembly"
+agents: [site-forge]
+---
+
+# site-forge: Phase 4 — Build Layer
+
+**Goal:** Implement all sections and components.
+
+Active token source by mode:
+- **Mode A:** skill `references/design-tokens.md`
+- **Mode B:** forged skill from Phase 3B
+- **Mode C:** skill tokens; slot extracted content/images from component map
+- **Mode E:** `blended-tokens.css` from Phase 3E
+
+## 4.1 Complexity budget
+
+- **Simple** (< 3 sub-components): implement directly
+- **Moderate** (3–5 sub-components): one worktree builder
+- **Complex** (> 5 sub-components): split across multiple builders
+
+## 4.2 Direct implementation (simple sections)
+
+Build inline. Use skill tokens. Reference section spec and component map. Run `npx tsc --noEmit` after each file.
+
+## 4.3 Worktree builders (moderate/complex sections)
+
+```bash
+git worktree add ../worktree-<section> -b builder/<section>
+```
+
+Each builder receives:
+1. Section spec file (inline)
+2. Component map rows for this section (inline)
+3. Relevant tokens from active token file (inline — only what's needed)
+4. Path to screenshots
+5. Target file: `src/components/<SectionName>.tsx`
+6. Requirement: `npx tsc --noEmit` must pass
+
+After builder completes:
+```bash
+npx tsc --noEmit
+git add -A && git commit -m "build(<section>): implement with <skill-name> tokens"
+git worktree remove ../worktree-<section>
+git merge builder/<section> --no-ff -m "merge: <section> builder"
+```
+
+Conflict resolution: structure wins — preserve DOM hierarchy from spec; replace style values with skill tokens.
+
+## 4.4 Interaction implementation (MANDATORY — do not skip)
+
+Read `docs/research/<hostname>/animations-raw.json` → `jsLibraries` and `dom-mutations.json` before choosing strategy.
+
+### 4.4.A Implementation strategy routing
+
+**Step 1 — Choose animation layer based on detected libraries:**
+
+| Detected | Install | Strategy |
+|---|---|---|
+| `gsap: true` | `npm install gsap` | GSAP + ScrollTrigger for all scroll-driven |
+| `framerMotion: true` | `npm install framer-motion` | `<motion.div>` with `whileInView` / `useScroll` |
+| `swiper: true` | `npm install swiper` | Swiper React for carousels/sliders |
+| `lottie: true` | `npm install lottie-react` | `<Lottie>` for SVG animations |
+| `aos: true` | *(no install)* | `IntersectionObserver` + CSS classes |
+| none detected | *(no install)* | `IntersectionObserver` + CSS `@keyframes` |
+
+Install all detected libraries simultaneously.
+
+**Step 2 — Scroll-driven animations from `dom-mutations.json`:**
+
+```typescript
+// GSAP ScrollTrigger (when gsap detected)
+gsap.from('.hero__headline', {
+  opacity: 0, y: 20, duration: 0.4, ease: 'power2.out',
+  scrollTrigger: {
+    trigger: '.hero__headline',
+    start: 'top 80%', // derived from mutation scrollY / pageHeight
+    once: true,
+  },
+});
+
+// IntersectionObserver (when no GSAP)
+const observer = new IntersectionObserver(entries => {
+  entries.forEach(e => { if (e.isIntersecting) e.target.classList.add('is-animated'); });
+}, { threshold: 0.15 });
+document.querySelectorAll('.animate-on-scroll').forEach(el => observer.observe(el));
+```
+
+Use `scrollY` values from `dom-mutations.json` to calibrate `start` offsets or `threshold` values.
+
+**Step 3 — Recreate `@keyframes` from `animations-raw.json`:**
+
+Copy each entry's `cssText` verbatim into `src/app/globals.css`. Apply duration via class, not inside keyframe:
+
+```css
+@keyframes fadeSlideUp {
+  from { opacity: 0; transform: translateY(20px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.animate-fade-slide-up {
+  animation: fadeSlideUp var(--transition-slow) var(--ease-out) forwards;
+}
+```
+
+**Step 4 — Parallax from `animations-raw.json.parallax`:**
+
+- `backgroundAttachment: fixed` → `background-attachment: fixed` — no JS.
+- JS parallax (transform changes between scroll positions):
+```typescript
+useEffect(() => {
+  const el = ref.current;
+  const handleScroll = () => {
+    const rate = 0.4; // adjust to match observed translation ratio
+    el.style.transform = `translate3d(0, ${window.scrollY * rate}px, 0)`;
+  };
+  window.addEventListener('scroll', handleScroll, { passive: true });
+  return () => window.removeEventListener('scroll', handleScroll);
+}, []);
+```
+
+**Step 5 — Remaining interactions from `interaction-spec.md`:**
+
+- **SCROLL-DRIVEN without mutation data:** `IntersectionObserver` with `threshold: 0.1`
+- **CLICK-DRIVEN:** React `useState` toggle + conditional className
+- **HOVER:** Tailwind hover variants or CSS `:hover` + `transition: var(--transition-all)`
+- **STATE-TOGGLE:** React `useState` + conditional className
+
+Use motion tokens for all `transition` and `animation-duration`. Never hardcode `ms`.
+
+Every interaction in the spec must be implemented. If too complex, implement simplified and note in QA report as ⚠️ — never leave unimplemented.
+
+### 4.4.B Video background implementation (MANDATORY when videos.json is non-empty)
+
+```tsx
+// VideoBackground.tsx
+export function VideoBackground({ role }: { role: string }) {
+  return (
+    <div className="absolute inset-0 overflow-hidden" aria-hidden="true">
+      <video
+        autoPlay muted loop playsInline
+        poster={`/images/<hostname>/${role}-poster.jpg`}
+        className="w-full h-full object-cover"
+        style={{ willChange: 'transform' }}
+      >
+        <source src={`/videos/<hostname>/${role}.webm`} type="video/webm" />
+        <source src={`/videos/<hostname>/${role}.mp4`} type="video/mp4" />
+      </video>
+      <div className="absolute inset-0" style={{ backgroundColor: 'var(--overlay-dark)' }} />
+    </div>
+  );
+}
+```
+
+If skipped (> 10MB or blocked): use poster as `background-image`, note in QA report as ⚠️ with original URL.
+
+- Render video behind content (`z-index: 0` on video, `z-index: 1` on content).
+- Always include overlay div for text readability.
+- Always add `prefers-reduced-motion` support:
+```css
+@media (prefers-reduced-motion: reduce) {
+  video[autoplay] { display: none; }
+}
+```
+
+## 4.5 Asset wiring (MANDATORY — do not skip)
+
+Before assembly, verify every downloaded image is referenced in its component.
+
+Check `docs/research/components/<section-slug>.spec.md` → "Content slots" → Image entries. Use `next/image`:
+
+```tsx
+// Correct
+import Image from 'next/image'
+<Image src="/images/<hostname>/hero.webp" alt="hero" fill className="object-cover" />
+
+// Wrong — placeholder when downloaded asset exists
+<div className="bg-gray-200 w-full h-64" />
+```
+
+If not downloaded (> 2MB or blocked): placeholder + note in QA report as ⚠️ with original URL.
+
+**Asset lifecycle notice (display once before assembly):**
+> "As imagens em `public/images/<hostname>/` são referências de desenvolvimento. Substitua-as pelos seus próprios assets antes de publicar."
+
+## 4.6 Assembly
+
+1. Create `src/app/page.tsx` importing all sections in page topology order.
+2. Apply token root in `src/app/globals.css`:
+   - Modes A, B, C: paste skill's `:root {}` block
+   - Mode E: paste `blended-tokens.css` content
+3. Run `npm run build` — must pass with 0 errors and 0 TypeScript errors.
+
+Fix TypeScript errors first, then CSS token resolution. Do not proceed to Phase 5 with a broken build.
+
+**Exit criterion:** `npm run build` passes. All sections rendered. All interactions implemented. All downloaded assets referenced. Skill tokens active globally.

package/template/.aioson/docs/site-forge-extraction.md

@@ -0,0 +1,135 @@
+---
+description: "site-forge Phase 2 — Selective Extraction: section specs, component inventory, interaction specs, aesthetic capture"
+agents: [site-forge]
+---
+
+# site-forge: Phase 2 — Selective Extraction
+
+**Goal:** Document structure and behavior of every section.
+
+**Mode A, C:** Discard ALL aesthetic values — skill tokens replace them. Preserve content slots (texts, image paths).
+**Mode B, D, E:** Extract structure AND aesthetic values — raw material for the skill or blend.
+
+## 2.1 Section specs
+
+For each section in page topology, create `docs/research/components/<section-slug>.spec.md`:
+
+```markdown
+# <SectionName> — Structure Specification
+
+## Layout pattern
+- Container: [max-width | full-viewport | fluid]
+- Display: [flex | grid | block]
+- Children arrangement: [column | row | grid-cols-3 | etc.]
+- Overflow: [visible | hidden | scroll]
+
+## Elements
+- [element-type]: [role — e.g. "primary headline", "CTA button", "feature image"]
+
+## Interaction model
+- Type: [NONE | SCROLL-DRIVEN | CLICK-DRIVEN | HOVER | STATE-TOGGLE]
+- Trigger: [precise trigger condition]
+- Effect: [which elements, which CSS property types]
+- Timing: [fast | medium | slow — relative only]
+
+## Responsive changes
+- At 768px: [what changes]
+- At 390px: [what changes]
+
+## Content slots
+- Headline: "[actual text]"
+- Subtext: "[actual text]"
+- CTA label: "[actual text]"
+- Image: [what it depicts, path to downloaded file]
+
+## Aesthetic values (Modes B, D, E only — omit in Modes A, C)
+- Background color: [hex or rgba]
+- Text colors: [hex values per role: heading, body, muted, accent]
+- Border radius: [observed px values]
+- Shadow: [observed box-shadow values]
+- Padding/gap pattern: [observed px values]
+```
+
+## 2.2 Component inventory
+
+List all distinct reusable component types across the page:
+```
+Button: primary, secondary, ghost, icon-only
+Card: media-card, text-card, stat-card
+Input: text, email, textarea, select
+NavItem / Modal / Dropdown / TabBar / Accordion / Toast / Badge / Avatar
+```
+
+For each component, create `docs/research/components/<component-slug>.spec.md`:
+
+```markdown
+# <ComponentName> — Component Specification
+
+## DOM structure
+- <outer-element> (semantic role)
+  - <child>: [role]
+
+## Variants
+- [variant-name]: [how it differs structurally]
+
+## States
+- default / hover / active / disabled / loading: [what changes per state]
+  (type only for Mode A/C | type + value for Mode B/D/E)
+
+## Behavior
+- [action]: [effect]
+```
+
+## 2.3 Interaction specifications
+
+For every non-static section, create/append `docs/research/<hostname>/interaction-spec.md`:
+
+```markdown
+# <Name> — Interaction Specification
+
+## Model: [SCROLL-DRIVEN | CLICK-DRIVEN | HOVER | STATE-TOGGLE]
+## Trigger: [precise trigger condition]
+## Effect: [which elements, which CSS property types]
+## Timing: [fast / medium / slow — relative only]
+## Implementation direction: [e.g. "scroll listener on window", "CSS :hover + transition"]
+```
+
+## 2.4 Aesthetic capture (Modes B, D, E only)
+
+```javascript
+const elements = {
+  body: document.body,
+  h1: document.querySelector('h1'),
+  h2: document.querySelector('h2'),
+  p: document.querySelector('p'),
+  primaryBtn: document.querySelector('button, [class*="btn-primary"], [class*="cta"]'),
+  card: document.querySelector('[class*="card"], article'),
+  nav: document.querySelector('nav, header')
+};
+
+const extracted = {};
+for (const [name, el] of Object.entries(elements)) {
+  if (!el) continue;
+  const s = window.getComputedStyle(el);
+  extracted[name] = {
+    backgroundColor: s.backgroundColor, color: s.color,
+    fontFamily: s.fontFamily, fontSize: s.fontSize,
+    fontWeight: s.fontWeight, lineHeight: s.lineHeight,
+    borderRadius: s.borderRadius, boxShadow: s.boxShadow,
+    padding: s.padding, gap: s.gap, transition: s.transition
+  };
+}
+return extracted;
+```
+
+Save to `docs/research/<hostname>/aesthetics-raw.json`.
+
+## Phase 2 output
+
+- `docs/research/<hostname>/structure-spec.md` — overview of all sections
+- `docs/research/<hostname>/interaction-spec.md` — all interactions
+- `docs/research/<hostname>/aesthetics-raw.json` — Modes B, D, E only
+- `docs/research/components/*.spec.md` — one per section + one per component type
+
+**Exit criterion (Modes A, C):** Every section has a spec. No color/size/spacing values in any spec file.
+**Exit criterion (Modes B, D, E):** Every section has a spec WITH aesthetic values. `aesthetics-raw.json` populated.

package/template/.aioson/docs/site-forge-qa.md

@@ -0,0 +1,155 @@
+---
+description: "site-forge Phase 5 — Visual QA, screenshot comparison, interaction testing, skill fidelity check, output contract"
+agents: [site-forge]
+---
+
+# site-forge: Phase 5 — Visual QA
+
+**Goal:** Verify the clone behaves like the original and looks like the skill.
+
+## 5.1 Start dev server
+
+```bash
+npm run dev
+# Wait for "ready" — up to 30s
+```
+
+## 5.2 Screenshot comparison
+
+Capture both at 1440px, 768px, 390px:
+- Original: target URL
+- Clone: `http://localhost:3000`
+
+**Mode A, C:** Acceptable: colors/fonts/spacing replaced. Unacceptable: missing sections, broken layout, missing interactive elements, missing content.
+**Mode B:** Clone should visually resemble original. Large color/font differences signal extraction miss — investigate before passing.
+**Mode E:** Blend must be visible — neither pure copy nor pure skill application. If identical to either source, blend was not applied.
+
+## 5.3 Interaction testing
+
+Per interaction in the spec:
+- Scroll triggers: does the effect fire at the right scroll position?
+- Click triggers: do tabs, dropdowns, modals, toggles work?
+- Hover triggers: do cards lift, nav items change state?
+- Responsive: do breakpoints trigger correct layout changes?
+
+## 5.4 Skill fidelity check
+
+- CSS variables resolving (no browser defaults as fallback)?
+- Motion tokens used (no hardcoded `ms` in components)?
+- **Mode A, C:** Skill colors applied — not original site colors?
+- **Mode B:** Extracted site colors reproduced accurately?
+- **Mode E:** Blended values present — verify at least 3 tokens from each source?
+
+## 5.5 QA report
+
+Create `docs/research/<hostname>/qa-report.md`:
+
+```markdown
+# QA Report — <hostname> → <skill-name>
+**Mode:** [A | B | C | D | E]
+**Date:** [date]
+**Build status:** passing
+
+## Structural fidelity
+✅/⚠️/❌ [Section]: [note]
+
+## Content slots (Modes C, E)
+✅/⚠️/❌ [Section]: extracted text/images present
+
+## Interactions
+✅/⚠️/❌ [Interaction name]: [status and note]
+
+## Skill fidelity
+✅/⚠️/❌ Colors: tokens applied / hardcoded values remain
+✅/⚠️/❌ Typography: skill fonts active
+✅/⚠️/❌ Spacing: scale tokens applied
+✅/⚠️/❌ Motion: transition tokens applied
+
+## Blend verification (Mode E only)
+✅/⚠️/❌ Site tokens present: [list 3 examples]
+✅/⚠️/❌ Skill tokens present: [list 3 examples]
+
+## Issues to fix
+1. [issue] → [fix]
+
+## Known deviations (acceptable ⚠️)
+- [deviation]: [reason]
+```
+
+Fix all ❌ before closing. Pass requires fewer than 5 ⚠️.
+
+---
+
+# Output contract
+
+## Modes A, B, C, E (builds a site)
+
+```
+docs/research/<hostname>/
+├── reconnaissance.json
+├── crawl-manifest.json
+├── structure-spec.md
+├── interaction-spec.md          ← updated with scroll-triggered entries from Phase 1.5.4
+├── animations-raw.json          ← jsLibraries, keyframes, animationRules, parallax
+├── videos.json
+├── dom-mutations.json
+├── component-map.md             (Modes A, C)
+├── blend-map.md                 (Mode E only)
+├── blended-tokens.css           (Mode E only)
+└── qa-report.md
+
+docs/research/<hostname>/scroll-recording/
+└── scroll-00pct.png … scroll-100pct.png
+
+docs/research/components/
+└── <section-slug>.spec.md  (one per section + one per component type)
+
+public/images/<hostname>/     [replace before publishing]
+public/videos/<hostname>/     [replace before publishing]
+
+src/components/
+└── <SectionName>.tsx
+└── VideoBackground.tsx       (if videos found)
+
+src/app/
+├── page.tsx
+└── globals.css               [skill token root + extracted @keyframes]
+```
+
+## Mode B additionally
+
+```
+docs/research/<hostname>/aesthetics-raw.json
+
+.aioson/installed-skills/<hostname>/
+├── SKILL.md
+├── references/design-tokens.md
+├── references/components.md
+├── references/patterns.md
+├── references/motion.md      ← extracted @keyframes + detected animation libraries
+├── references/websites.md
+└── .skill-meta.json
+```
+
+## Mode D (skill only — no site built)
+
+```
+docs/research/<hostname>/
+├── reconnaissance.json
+├── crawl-manifest.json
+├── structure-spec.md
+├── interaction-spec.md
+├── animations-raw.json
+├── videos.json
+├── dom-mutations.json
+└── aesthetics-raw.json
+
+.aioson/installed-skills/<hostname>/
+├── SKILL.md
+├── references/design-tokens.md
+├── references/components.md
+├── references/patterns.md
+├── references/motion.md
+├── references/websites.md
+└── .skill-meta.json
+```