@jaimevalasek/aioson 1.8.0 → 1.9.0

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

@@ -1,135 +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.
+---
+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

@@ -1,155 +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
-```
+---
+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
+```