@gradial/aci 0.1.20-preview.3 → 0.1.21

package/templates/common/.agents/skills/authoring/references/repo-structure.md

@@ -0,0 +1,157 @@
+# Repository Structure Reference
+
+## Directory Layout
+
+```
+.aci.yaml                        ACI config: contract paths, framework, routes
+package.json                     Dependencies and scripts
+tsconfig.json                    TypeScript config
+.content/                        Local content for development
+  config/
+    site.json                    Site metadata, navigation, footer, branding, SEO
+  pages/
+    home/_index.json             Homepage (route /)
+    about/_index.json            About page (route /about)
+  fragments/
+    navbar/_index.json           Navbar fragment (layout default)
+    site-footer/_index.json      Footer fragment (layout default)
+src/
+  cms/
+    contracts/
+      components/                Component contracts (framework-agnostic)
+        homeHero.contract.ts     Hero section contract
+        button.contract.ts       Button block contract
+        container.contract.ts    Container (nested blocks) contract
+        featureGrid.contract.ts  Feature grid contract
+        featureCard.contract.ts  Feature card contract
+        statsBar.contract.ts     Stats bar contract
+        siteNavigation.contract.ts  Site navigation contract
+        siteFooter.contract.ts   Site footer contract
+        index.ts                 Component contract barrel
+      layouts/
+        index.ts                 Layout contract barrel (plain objects)
+    registry.ts                  Component registry — createRegistry([contract, component] tuples)
+  components/
+    elements/                    Small reusable components + atomic content blocks
+      ButtonBlock.astro/.tsx     Button block (renders <a> with variant)
+    sections/                    Page-level section components
+      HomeHero.astro/.tsx        Hero section
+      ContainerSection.astro/.tsx  Container section (renders nested blocks)
+      FeatureGrid.astro/.tsx     Feature grid (renders nested feature cards)
+      FeatureCard.astro/.tsx     Feature card
+      StatsBar.astro/.tsx        Stats bar
+    chrome/                      Site chrome (Header, Footer, Nav)
+      Header.astro/.tsx          Site header (renders navbar fragment)
+      Footer.astro/.tsx          Site footer (renders footer fragment)
+  design-system/
+    styles.css                   Global stylesheet + Tailwind import
+    tokens/
+      colors.css                 Brand and semantic color tokens
+      typography.css             Font families, sizes, weights, line heights
+      spacing.css                Spacing scale
+      radii.css                  Border radius values
+      shadows.css                Shadow definitions
+      components.css             Component-level tokens
+      index.css                  Barrel import for all token files
+  app/                           Framework routes (Next.js App Router)
+    layout.tsx                   Root layout (minimal, imports CSS only)
+    [[...slug]]/page.tsx         Optional catch-all for all CMS pages
+  pages/                         Framework routes (Astro file-based routing)
+    [...slug].astro              Catch-all for all CMS pages
+  layouts/                       Page layout wrappers (framework-specific)
+  stories/                       Storybook stories (one per component tier)
+  fixtures/                      Test fixture data (optional)
+public/                          Static assets (images, fonts, logos)
+.agents/                         Agent skills and guides
+  AGENTS.md                      Site-level agent guide
+  skills/
+    aci/                         ACI onboarding and troubleshooting skill
+    authoring/                   Content authoring and component development skill
+    migration/                   Site migration skill
+.aci/
+  compiled/                      Generated compiled content (not checked in)
+  schemas/                       Auto-generated content schemas
+.storybook/                      Storybook configuration
+  main.ts                        Framework-specific Storybook config
+  preview.ts                     Global decorators, theme switching
+eslint-rules/
+  no-raw-tailwind-values.js      Custom ESLint rule for design token enforcement
+```
+
+## Framework-Specific Paths
+
+Only Next.js and Astro are supported. SvelteKit support has been removed.
+
+### Next.js
+
+| Concern | Path |
+|---------|------|
+| Routes | `src/app/[[...slug]]/page.tsx` (optional catch-all, `force-dynamic`) |
+| Root layout | `src/app/layout.tsx` (minimal — imports CSS, no chrome) |
+| Config | `next.config.ts` with `withAci()` |
+| Registry | `src/cms/registry.ts` (shared, `createRegistry` with `[contract, component]` tuples) |
+| Middleware | `src/middleware.ts` |
+| Asset routes | `src/app/gradial/assets/[releaseId]/[...path]/route.ts` |
+
+### Astro
+
+| Concern | Path |
+|---------|------|
+| Routes | `src/pages/[...slug].astro` |
+| Layout | `src/layouts/SiteLayout.astro` |
+| Config | `astro.config.mjs` with `withAci()` |
+| Registry | `src/cms/registry.ts` (shared, `createRegistry` with `[contract, component]` tuples) |
+| Storybook | `.storybook/main.ts`, `.storybook/preview.ts` |
+
+## Import Rules
+
+1. **Contract files** import only `@gradial/aci`, `zod`, and shared schema
+   helpers. No React, Astro, CSS, browser globals, or runtime modules.
+2. **Runtime components** may import contract types and framework code.
+3. **Registry files** (`src/cms/registry.ts`) import both contracts and
+   runtime components — they are the wiring point.
+4. Use `@gradial/aci` as the SDK package. Do not use `@baremetal/runtime`.
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Directories | lowercase, singular, no underscores | `sections/`, `chrome/` |
+| Component files | PascalCase | `HomeHero.astro`, `FeatureShowcase.tsx` |
+| Contract files | camelCase + `.contract.ts` | `homeHero.contract.ts` |
+| Contract `id` | snake_case | `home_hero`, `feature_grid` |
+| Test files | `*.test.ts` or `*.spec.ts` | `HomeHero.test.ts` |
+| Story files | `*.stories.ts` | `HomeHero.stories.ts` |
+| CSS files | lowercase, hyphen-separated | `colors.css`, `styles.css` |
+| Block `id` in content | kebab-case with section context | `hero-heading`, `feature-cta` |
+| Content `$type` | lowercase | `page`, `site`, `dam.assetRef` |
+
+## Generated Files (Not Checked In)
+
+```
+.aci/                    Compiled content and build artifacts
+node_modules/           Dependencies
+dist/                   Astro build output
+.next/                  Next.js build output
+```
+
+## Package.json Scripts
+
+Standard scripts across all frameworks:
+
+```json
+{
+  "scripts": {
+    "dev": "...",
+    "build": "...",
+    "typecheck": "...",
+    "aci:compile": "aci build --compile-only",
+    "content:compile": "aci build --skip-code --content ./.content --out ./.aci/compiled",
+    "aci:build": "aci build --content ./.content",
+    "aci:doctor": "aci doctor",
+    "aci:validate": "aci build --validate-only"
+  }
+}
+```
+
+Customer repos use `npm` as the package manager. The monorepo uses `pnpm`.

package/templates/common/.agents/skills/migration/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: migration
+description: Migrate existing websites, Figma designs, or screenshots into ACI repos. Use when reverse-engineering a live site, extracting design tokens, modeling content from HTML, building components to match a visual source, or running a pixel-perfect migration workflow.
+---
+
+# Migration — Reverse-Engineering into ACI
+
+## Goal
+
+A pixel-perfect migration. Phase 3 targets <10% visual variance per
+section. Phase 4 targets <1% variance per element.
+
+"We reused existing components and called it done" is not a successful
+migration. Build new components and copy CSS 1:1 when needed. Visual
+fidelity wins over design-system purity.
+
+## Phases
+
+### Phase 1: Style Transfer
+
+1. Visually inspect the live source site using browser automation.
+2. Describe the style visually first (color palette, type scale, spacing
+   rhythm, accent treatments) before touching code.
+3. Inspect source CSS files to extract exact font families, color hex/rgb
+   values, and typography specs.
+4. Scan source CSS for responsive breakpoints. Record the canonical
+   breakpoint set (e.g., `[360, 768, 1024, 1280, 1400]`).
+5. Translate findings into design tokens and populate
+   `src/design-system/tokens/`.
+6. Update base styling of the target: header, footer, logo, CTAs/buttons,
+   typography, accents.
+   - The customer logo must be downloaded and wired in Phase 1.
+   - Header and footer chrome colors must be extracted from source CSS,
+     not eyeballed.
+   - Font family must match.
+7. Visually inspect the target site, note discrepancies, then fix base
+   styling iteratively.
+
+### Phase 2: Content Modeling
+
+**CONTENT DRIVES LAYOUT.** The content model in `_index.json` and
+`site.json` describes every element you'll need to render.
+
+Rules:
+1. **Never hard-code content inside component code.** All content lives in
+   the JSON content model.
+2. **Do not use bare atomic blocks for migration-phase content modeling.**
+   Stub out named components with named props — even if the component
+   doesn't exist yet. The content model is a contract for what components
+   must be built.
+3. **Name components by inspecting the source HTML.** Look at class names
+   of root elements (e.g., `ancillary-nav`, `home-hero`) — that's your
+   component name.
+4. **Extract copy from HTML markup, not from visual inspection.** Use HTML
+   parsing to pull exact strings. Agents drift when reading text off
+   screenshots.
+5. **Classify imagery:** `<img>` child vs CSS `background-image` on the
+   root vs CSS `background-image` on a wrapper. This drives the component's
+   markup.
+6. **Migrate copy verbatim.** Do not paraphrase, summarize, or invent
+   marketing claims, policy text, or CTAs.
+7. **Stub every content element you observe.** Missing nav items, social
+   links, fine print — if it's on the source page, it's in the content
+   model.
+
+For global elements (header, footer, nav), put their content under
+`.content/config/site.json`, not in page content.
+
+### Phase 3: Component Development
+
+The default assumption is that **new components will be built.** If you
+finish a section and built no new components, re-inspect for missed detail.
+
+1. Work one page section at a time, starting with global sections (header,
+   footer).
+2. Build an atomic component system for reused elements.
+3. For each section: isolate single, reused, atomic elements first, then
+   build the broader section.
+4. Use browser tools to visually compare source -> target.
+5. Rely on visual descriptions first — describe layout, don't migrate
+   markup 1:1.
+6. Build Storybook stories for every component/block.
+7. For polish: if visual flourishes can't be expressed via existing
+   design-system primitives, build a new component or variant.
+
+**Variance bar: <10% per section.** If a section is over 10%, you're
+missing a structural element — fix that before moving on.
+
+### Phase 4: Polish (Pixel-Level Visual Regression)
+
+**<1% visual variance per element is the bar for "done."**
+
+1. Go element by element, not section by section.
+2. Inspect applied CSS on the source for each element using DevTools or
+   `getComputedStyle`.
+3. Copy CSS verbatim into the target when needed. Fidelity wins over
+   abstraction.
+4. Decide per element: extend the design system, or do a 1:1 CSS
+   migration?
+5. Diff workflow: scope the visual-diff to a single element. Diff, fix
+   one delta, re-diff. Iterate until under 1%.
+6. Compare at the same dimensions at every breakpoint from the source's
+   CSS breakpoint set.
+7. Report prose discrepancies, not just percentages.
+
+## Decision Principles
+
+- **Visual fidelity first, markup parity never.** Match the visual, build
+  the structure idiomatically.
+- **Atomic before composite.** Always migrate the smallest reusable unit
+  first.
+- **Describe before implementing.** Write a prose description of what you
+  see before writing code.
+- **Pixel fidelity beats design-system purity.** If the design system
+  can't express the source faithfully, build a new component or variant.
+- **Migrate copy verbatim.** Never paraphrase or invent content.
+- **One section at a time.** Resist the urge to scaffold everything at
+  once.
+
+## Deep Dive: Analyzing Source Sites
+
+Read `references/analyzing-source.md` for Playwright patterns, CSS
+extraction, DOM inspection, interactive state probing, and responsive
+inspection techniques.
+
+## Deep Dive: Component Migration
+
+Read `references/component-migration.md` for building components to spec,
+header/footer inventory checklists, visual verification workflows, CSS
+discipline rules, and interactivity approach.
+
+## Deep Dive: Selector Map
+
+Read `references/selector-map.md` for the source-to-target selector
+mapping format that tracks every migrated element.
+
+## Validation Gates
+
+Before considering any change complete:
+
+1. Run `npm run aci:validate` — content validation
+2. Run `npm run typecheck && npm run build` — CI build steps
+3. Run visual regression comparisons
+4. Verify Storybook stories render correctly
+
+## Asset Handling
+
+Default: treat customer fonts and imagery as proprietary. Substitute the
+closest licensed/open alternative and use neutral placeholders.
+
+**Demo override:** If this is a demo/proof-of-concept, download assets and
+serve them locally. Do NOT hot-link the customer's CDN.
+
+1. Fonts: extract `@font-face` declarations, download font files, rewrite
+   URLs to local paths.
+2. Images: download hero shots and section imagery, preserving `srcset`
+   variants.
+3. Logos: download the customer's logo and reference locally.
+4. Organize under a customer-scoped subdirectory
+   (e.g., `public/images/<customer>/`).

package/templates/common/.agents/skills/migration/references/analyzing-source.md

@@ -0,0 +1,215 @@
+# Analyzing Source Sites
+
+This guide covers how to probe live sites for migration: Playwright
+patterns, spatial relationships, interactive states, and CSS extraction.
+
+## Visual Inspection
+
+Before touching code, describe what you see:
+
+1. Open the source site in a browser (or via Playwright/headless browser).
+2. Take screenshots at desktop and mobile widths.
+3. Write a prose description:
+   - Overall layout (header, hero, sections, footer)
+   - Color palette (primary, secondary, accents, surfaces)
+   - Type scale (heading sizes, body size, eyebrow/caption sizes)
+   - Spacing rhythm (tight vs airy, section padding)
+   - Accent treatments (gradients, borders, shadows)
+   - Interactive elements (nav dropdowns, carousels, tabs, accordions)
+
+This description becomes the reference for Phase 1 style transfer.
+
+## CSS Extraction
+
+Inspect the source site's CSS to extract exact values:
+
+### Colors
+
+```javascript
+// Via Playwright evaluate
+const styles = getComputedStyle(document.querySelector('.hero'));
+console.log(styles.color, styles.backgroundColor, styles.borderColor);
+```
+
+Or inspect the source CSS files directly:
+- Look for `:root` or `body` custom properties
+- Find the brand color palette
+- Note semantic color usage (text, surface, border, accent)
+
+### Typography
+
+Extract:
+- Font family declarations (`font-family`)
+- Font weights used (`font-weight`)
+- Font sizes at each heading level
+- Line heights
+- Letter spacing
+- Font loading mechanism (`@font-face`, Google Fonts, etc.)
+
+### Spacing
+
+Look for:
+- Container max-width
+- Section vertical padding
+- Card padding
+- Gap values in grids/flex
+- Header/footer height
+
+### Responsive Breakpoints
+
+Scan CSS for `@media` rules across loaded stylesheets:
+
+```javascript
+// Via Playwright
+const sheets = Array.from(document.styleSheets);
+const breakpoints = new Set();
+for (const sheet of sheets) {
+  try {
+    const rules = sheet.cssRules;
+    for (const rule of rules) {
+      if (rule instanceof CSSMediaRule) {
+        const match = rule.conditionText.match(/min-width:\s*(\d+)/);
+        if (match) breakpoints.add(parseInt(match[1]));
+      }
+    }
+  } catch (e) { /* cross-origin */ }
+}
+console.log([...breakpoints].sort((a, b) => a - b));
+```
+
+Record the canonical breakpoint set. These are the only viewports for
+visual-diff comparisons.
+
+## DOM Inspection
+
+### Classify each element
+
+For every content element on the source page, classify:
+
+1. **Is it text or an image?**
+   - Use `textContent` or `innerHTML` to extract copy.
+   - Check if eyebrows/badges/logos that look like text are actually
+     `<img>` elements.
+
+2. **How is imagery rendered?**
+   - `<img>` child element
+   - CSS `background-image` on the root element
+   - CSS `background-image` on a wrapper element
+   - Check with: `getComputedStyle(el).backgroundImage`
+
+3. **Is it interactive?**
+   - Click to check for dropdowns, tabs, carousels
+   - Scroll to check for sticky elements
+   - Look for `transform`, `overflow-x`, `scroll-snap-type` (carousel
+     indicators)
+   - Look for `animation`, `transition`, `keyframes` (animated elements)
+
+### Extract copy from HTML
+
+```javascript
+// Via Playwright
+const hero = document.querySelector('.hero');
+const headline = hero.querySelector('h1')?.textContent;
+const description = hero.querySelector('p')?.textContent;
+const cta = hero.querySelector('a')?.textContent;
+const ctaHref = hero.querySelector('a')?.getAttribute('href');
+```
+
+Do NOT extract copy from screenshots. Agents drift when reading text off
+images. Always use HTML parsing.
+
+### Identify components by class name
+
+Look at the class names of root elements to determine component names:
+- `.ancillary-nav` → `ancillaryNav` component
+- `.home-hero` → `homeHero` component
+- `.footer-zip-code` → `footerZipCode` component
+
+Don't invent names from visual impressions. Use the source's class names
+as the guide.
+
+## Interactive State Inspection
+
+### Navigation dropdowns
+
+```javascript
+// Hover or click to reveal dropdowns
+const navItem = document.querySelector('.nav-item-has-children');
+navItem.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+// Wait, then inspect the revealed dropdown
+```
+
+### Carousels
+
+Check for:
+- `transform: translateX` on a container
+- `scroll-snap-type` CSS property
+- Prev/next control buttons
+- Carousel library class names (`slick`, `swiper`, `glide`)
+
+A carousel migrated as a grid will fail visual-diff. Inspect before
+deciding markup.
+
+### Tabs
+
+Click each tab to verify other panes exist and contain content. Note the
+tab labels and pane content for the content model.
+
+### Accordions
+
+Click to expand/collapse. Note which items are expanded by default.
+
+## Responsive Inspection
+
+View the source at multiple viewport sizes:
+
+```javascript
+// Via Playwright
+await page.setViewportSize({ width: 360, height: 800 });
+await page.screenshot({ path: 'source-mobile.png' });
+
+await page.setViewportSize({ width: 768, height: 1024 });
+await page.screenshot({ path: 'source-tablet.png' });
+
+await page.setViewportSize({ width: 1280, height: 800 });
+await page.screenshot({ path: 'source-desktop.png' });
+```
+
+Note layout changes at each breakpoint:
+- Does the nav switch to hamburger?
+- Do multi-column grids stack?
+- Does the hero image change aspect ratio?
+- Are there mobile-only or desktop-only elements?
+
+## Background Image Detection
+
+Easy to miss because they're CSS `background-image` and don't show in a
+child-element inventory:
+
+```javascript
+// Check every section root
+const sections = document.querySelectorAll('section, header, footer, .hero');
+for (const section of sections) {
+  const bg = getComputedStyle(section).backgroundImage;
+  if (bg && bg !== 'none') {
+    console.log(section.className, 'has background image:', bg);
+  }
+}
+```
+
+If the source root carries the image, the target root must too — don't
+substitute with a media-then-body card.
+
+## Recording Findings
+
+As you inspect, record:
+1. Component names (from class names)
+2. Content (from HTML parsing)
+3. Imagery mode (img child vs background-image)
+4. Interactive behavior (carousel, tabs, accordion, sticky)
+5. CSS values for style transfer (colors, fonts, spacing)
+6. Breakpoints for visual-diff
+7. Selector pairs for the selector map
+
+Update the selector map (`artifacts/source-vs-target/selector-map.json`)
+every time you inspect an element.