@gradial/aci 0.1.20-preview.3 → 0.1.21

package/templates/common/.agents/skills/migration/references/component-migration.md

@@ -0,0 +1,200 @@
+# Component Migration
+
+This guide covers building components to spec, visual verification, and
+variance targets during the component development phase.
+
+## Building Components
+
+### Start with global sections
+
+Work in this order:
+1. Header (navigation, branding, ancillary nav, utility buttons)
+2. Footer (columns, social links, legal links, copyright)
+3. Page sections (hero, feature grids, CTAs, etc.)
+
+### Atomic before composite
+
+Always migrate the smallest reusable unit first:
+
+1. Identify reused elements (buttons, icons, cards, logos)
+2. Build them as `elements/` components
+3. Compose sections from elements
+
+### Build new components
+
+The default assumption is that **new components will be built.** If you
+finish a section and built no new components, that's a smell — re-inspect
+for missed detail before declaring done.
+
+### Visual description first
+
+Before writing component code:
+1. Describe what you see in prose (layout, colors, spacing, imagery)
+2. Identify the source CSS class names for the component
+3. Determine the imagery mode (img child vs background-image)
+4. Note interactive behavior
+
+Then build the component to match the visual description, not the source
+markup.
+
+## Component Tiers
+
+Use the three-tier structure:
+
+| Tier | Directory | Purpose |
+|------|-----------|---------|
+| elements | `src/components/elements/` | Small reusable UI + atomic content blocks |
+| sections | `src/components/sections/` | Page-level section components |
+| chrome | `src/components/chrome/` | Site chrome (Header, Footer, Nav) |
+
+Do not create additional tiers. Three directories are sufficient.
+
+## Header Inventory Checklist
+
+Verify every item is present:
+- [ ] Customer logo (image, linked to brandHref)
+- [ ] Ancillary nav (top strip — residential/business switcher, phone, etc.)
+- [ ] Primary nav with hover/click flyouts for sub-links
+- [ ] Utility buttons (Support, Sign In) with icons
+- [ ] Address-availability signup form (if present on source)
+- [ ] Mobile: hamburger on correct side, mobile logo, mobile-nav icons,
+      mobile ancillary nav, full-screen drawer behavior
+
+**Mobile nav pro-tip:** do NOT try to contort the desktop nav into a
+mobile nav by re-arranging the same elements. Duplicate the nav elements
+for mobile and show/hide via media queries and JS-applied open/closed
+classes. Markup duplication is cheaper than the state machine you'll
+otherwise build.
+
+## Footer Inventory Checklist
+
+- [ ] Customer logo
+- [ ] Left column: phone number, address, legal disclaimer, copyright,
+      social icon links
+- [ ] Footer nav columns (Company, Products, Support, etc.)
+- [ ] Any sub-footer / accessibility links
+
+## Storybook Stories
+
+Build stories for every component/block, including variants and all states
+(hover, mobile-open, signed-in, etc.):
+
+```ts
+// src/stories/HomeHero.stories.ts
+export default {
+  title: 'Sections/HomeHero',
+  component: HomeHero,
+};
+
+export const Default = {
+  args: {
+    eyebrow: 'Welcome',
+    headline: 'Build something great',
+    ctaLabel: 'Get started',
+    ctaHref: '#start',
+  },
+};
+
+export const NoEyebrow = {
+  args: {
+    headline: 'Build something great',
+    ctaLabel: 'Get started',
+    ctaHref: '#start',
+  },
+};
+```
+
+## Visual Verification
+
+### Phase 3: <10% variance per section
+
+1. Render both source and target at the same viewport size.
+2. Take screenshots of each section.
+3. Compare visually and compute variance percentage.
+4. If over 10%, identify the missing structural element and fix it.
+
+Common Phase 3 failures:
+- Missing nav item
+- Missing icon
+- Wrong markup tree (e.g., media-then-body when source is
+  background-image overlay)
+- Missing entire section
+
+### Phase 4: <1% variance per element
+
+1. Go element by element (a single button, a single nav link, a single
+   heading).
+2. Inspect applied CSS on the source for each element.
+3. Copy CSS verbatim when the design system can't express the fidelity.
+4. Diff, fix one delta, re-diff. Iterate until under 1%.
+
+Common Phase 4 failures:
+- Wrong hex color
+- Wrong font weight (source uses 500/600 where you used 400/700)
+- Wrong padding between text elements
+- Missing icon
+- Wrong icon size
+- Missing accent line/underline
+- Wrong border-radius
+
+## CSS Discipline
+
+Phase 4 says "copy applied CSS verbatim" — that is the intent, not the
+implementation. The implementation must respect design-token discipline:
+
+- **Raw hex colors are banned in component CSS.** If the source uses
+  `#002864`, find the matching token or add a new one in
+  `src/design-system/tokens/colors.css`.
+- **Raw px/rem/em units are banned in component CSS.** Use existing
+  spacing/typography tokens, or add new ones. `px` is permitted for border
+  widths and inside `@media` declarations only.
+- **Tokens live in `src/design-system/tokens/`.** Add to these files when
+  source values don't map, then reference from component CSS.
+
+Workflow for a Phase 4 fix:
+1. Pull the value via `getComputedStyle`.
+2. Check if a token exists that matches.
+3. If not, add the token to the appropriate `tokens/*.css` file.
+4. Reference the token from the component.
+
+## Images-as-Text Detection
+
+Eyebrows, brand wordmarks, and badges that *look like text* are often
+`<img>` elements. Check the DOM:
+
+```javascript
+const eyebrow = document.querySelector('.hero .eyebrow');
+console.log(eyebrow.tagName); // 'IMG' or 'SPAN' or 'DIV'
+```
+
+If it's an `<img>`, treat it as an image in the content model, not text.
+
+## Interactivity Approach
+
+Apply interactivity with a light touch:
+- Click through tabs to verify other panes
+- Scroll to verify sticky elements
+- Use class name toggles over markup restructuring
+- Use show/hide variant content based on applied classes
+- Prefer style attributes and class application over drastic markup changes
+
+## Page Section Strategy
+
+- Stub sections with base container/column grid first
+- Most layouts should be child blocks within base layout blocks
+- Promote a section to its own section block only when it requires:
+  - Interactive elements
+  - Animations
+  - Dynamic data (product listings, tabs, carousels)
+
+## Responsive Verification
+
+Always view pages at multiple viewport sizes (mobile, tablet, desktop)
+before declaring a section complete. Use the source's breakpoint set as
+the reference viewports.
+
+## When to Ask for Clarification
+
+- The design system lacks tokens for a clearly important visual element
+- A section's interactivity model is unclear (carousel vs static grid)
+- Content modeling decisions have multiple valid interpretations

package/templates/common/.agents/skills/migration/references/selector-map.md

@@ -0,0 +1,31 @@
+# Selector Map
+
+Maintain a running log mapping every migrated content element to its
+source and target CSS selectors.
+
+Location: `artifacts/source-vs-target/selector-map.json`
+
+## Schema
+
+```json
+{
+  "sourceUrl": "https://www.example.com/",
+  "targetUrl": "http://localhost:3000/",
+  "breakpoints": [360, 768, 1024, 1280, 1400],
+  "entries": {
+    "content/pages/home/_index.json blocks[\"home-hero\"]": {
+      "source": ".home-hero",
+      "target": ".home-hero",
+      "viewport": "both",
+      "notes": "eyebrow is an <img>, not text"
+    }
+  }
+}
+```
+
+## Rules
+
+- Append, don't overwrite. Add new entries as you inspect new elements.
+- Both selectors must be precise.
+- Add an entry the moment you inspect an element.
+- Capture interactivity and animation in notes.

package/templates/common/.content/config/site.json

@@ -0,0 +1,192 @@
+{
+  "$type": "site",
+  "id": "meridian",
+  "status": "published",
+  "title": "Meridian",
+  "domain": "www.meridian.local",
+  "defaultLocale": "en-us",
+  "locales": ["en-us"],
+  "overlayResolution": ["locale", "audience"],
+  "brandHref": "/",
+  "brandLogo": {
+    "src": "/assets/meridian-logo.svg",
+    "alt": "Meridian"
+  },
+  "seo": {
+    "title": "Meridian",
+    "description": "Global satellite internet from anywhere on Earth.",
+    "siteName": "Meridian"
+  },
+  "navigation": [
+    {
+      "id": "home",
+      "label": "Home",
+      "href": "/"
+    },
+    {
+      "id": "plans",
+      "label": "Plans",
+      "href": "/plans/"
+    },
+    {
+      "id": "devices",
+      "label": "Devices",
+      "href": "/devices/"
+    },
+    {
+      "id": "business",
+      "label": "Business",
+      "href": "/business/"
+    },
+    {
+      "id": "blog",
+      "label": "Blog",
+      "href": "/blog/"
+    },
+    {
+      "id": "about",
+      "label": "About",
+      "href": "/about/"
+    }
+  ],
+  "utilities": [
+    {
+      "id": "sign-in",
+      "label": "Sign in",
+      "href": "/sign-in/",
+      "variant": "ghost"
+    },
+    {
+      "id": "contact-sales",
+      "label": "Contact sales",
+      "href": "/contact-sales/",
+      "variant": "primary"
+    }
+  ],
+  "footer": {
+    "columns": [
+      {
+        "id": "products",
+        "title": "Products",
+        "links": [
+          {
+            "id": "plans",
+            "label": "Plans",
+            "href": "/plans/"
+          },
+          {
+            "id": "devices",
+            "label": "Devices",
+            "href": "/devices/"
+          },
+          {
+            "id": "coverage",
+            "label": "Coverage",
+            "href": "/coverage/"
+          }
+        ]
+      },
+      {
+        "id": "solutions",
+        "title": "Solutions",
+        "links": [
+          {
+            "id": "business",
+            "label": "Business",
+            "href": "/business/"
+          },
+          {
+            "id": "maritime",
+            "label": "Maritime",
+            "href": "/business/maritime/"
+          },
+          {
+            "id": "aerospace",
+            "label": "Aerospace",
+            "href": "/business/aerospace/"
+          }
+        ]
+      },
+      {
+        "id": "resources",
+        "title": "Resources",
+        "links": [
+          {
+            "id": "blog",
+            "label": "Blog",
+            "href": "/blog/"
+          },
+          {
+            "id": "documentation",
+            "label": "Documentation",
+            "href": "/docs/"
+          },
+          {
+            "id": "support",
+            "label": "Support",
+            "href": "/support/"
+          }
+        ]
+      },
+      {
+        "id": "company",
+        "title": "Company",
+        "links": [
+          {
+            "id": "about",
+            "label": "About us",
+            "href": "/about/"
+          },
+          {
+            "id": "careers",
+            "label": "Careers",
+            "href": "/careers/"
+          },
+          {
+            "id": "contact",
+            "label": "Contact",
+            "href": "/contact/"
+          }
+        ]
+      }
+    ],
+    "social": [
+      {
+        "id": "x",
+        "label": "X",
+        "href": "https://x.com/meridian",
+        "icon": "X"
+      },
+      {
+        "id": "linkedin",
+        "label": "LinkedIn",
+        "href": "https://www.linkedin.com/company/meridian",
+        "icon": "in"
+      },
+      {
+        "id": "youtube",
+        "label": "YouTube",
+        "href": "https://www.youtube.com/meridian",
+        "icon": "YT"
+      }
+    ],
+    "legalLinks": [
+      {
+        "id": "terms",
+        "label": "Terms of Service",
+        "href": "/terms/"
+      },
+      {
+        "id": "privacy",
+        "label": "Privacy Policy",
+        "href": "/privacy/"
+      },
+      {
+        "id": "security",
+        "label": "Security",
+        "href": "/security/"
+      }
+    ],
+    "copyright": "Copyright (c) 2026 Meridian Satellite Networks, Inc. All rights reserved."
+  }
+}

package/templates/common/.content/dam/folders/seed/ast_site_about_hero/asset.json

@@ -0,0 +1,9 @@
+{
+  "$type": "dam.asset",
+  "schemaVersion": 1,
+  "assetId": "ast_site_about_hero",
+  "createdAt": "2026-06-01T00:00:00Z",
+  "createdBy": "local-seed",
+  "updatedAt": "2026-06-01T00:00:00Z",
+  "updatedBy": "local-seed"
+}

package/templates/common/.content/dam/folders/seed/ast_site_about_hero/editorial.json

@@ -0,0 +1,14 @@
+{
+  "$type": "dam.editorial",
+  "schemaVersion": 1,
+  "title": "Meridian about hero",
+  "description": "Seeded hero image for the Meridian about page.",
+  "altText": "Satellite ground station at twilight",
+  "tags": ["meridian", "hero", "ground-station", "satellite"],
+  "properties": {
+    "source": "unsplash",
+    "sourceUrl": "https://images.unsplash.com/photo-1516849841032-87cbac4d88f7?w=1920&q=80"
+  },
+  "customFields": {},
+  "notes": "Downloaded for the local DAM bridge harness."
+}

package/templates/common/.content/dam/folders/seed/ast_site_about_hero/governance.json

@@ -0,0 +1,23 @@
+{
+  "$type": "dam.governance",
+  "schemaVersion": 1,
+  "asset": {
+    "status": "active",
+    "legalHold": false,
+    "retention": {
+      "policy": "local-seed"
+    },
+    "publicationRestriction": "none"
+  },
+  "versions": {
+    "v0001": {
+      "status": "approved",
+      "approvedAt": "2026-06-01T00:00:00Z",
+      "approvedBy": "local-seed",
+      "license": {
+        "kind": "unsplash-local-fixture"
+      },
+      "publicationRestriction": "none"
+    }
+  }
+}

package/templates/common/.content/dam/folders/seed/ast_site_about_hero/versions/v0001.json

@@ -0,0 +1,37 @@
+{
+  "$type": "dam.assetVersion",
+  "schemaVersion": 1,
+  "versionId": "v0001",
+  "blob": {
+    "sha256": "fb3260e8286ea8231ea1c77b9c0be92d6edd9026565731eb14cfdcfd6b1b75b3",
+    "key": ".gradial-dam/blobs/sha256/fb/32/fb3260e8286ea8231ea1c77b9c0be92d6edd9026565731eb14cfdcfd6b1b75b3",
+    "byteSize": 14255,
+    "mime": "image/jpeg",
+    "originalFilename": "about-hero.jpg",
+    "checksumSource": "server-computed"
+  },
+  "technical": {
+    "dimensions": {
+      "width": 1200,
+      "height": 600
+    },
+    "duration": null,
+    "exif": {},
+    "iptc": {},
+    "xmp": {},
+    "video": null,
+    "audio": null,
+    "document": null,
+    "analysis": {
+      "saliency": null,
+      "faces": [],
+      "objects": [],
+      "segments": [],
+      "textRegions": [],
+      "logoRegions": [],
+      "safeAreas": []
+    }
+  },
+  "createdAt": "2026-06-01T00:00:00Z",
+  "createdBy": "local-seed"
+}

package/templates/common/.content/dam/folders/seed/ast_site_home_hero/asset.json

@@ -0,0 +1,9 @@
+{
+  "$type": "dam.asset",
+  "schemaVersion": 1,
+  "assetId": "ast_site_home_hero",
+  "createdAt": "2026-06-01T00:00:00Z",
+  "createdBy": "local-seed",
+  "updatedAt": "2026-06-01T00:00:00Z",
+  "updatedBy": "local-seed"
+}

package/templates/common/.content/dam/folders/seed/ast_site_home_hero/editorial.json

@@ -0,0 +1,14 @@
+{
+  "$type": "dam.editorial",
+  "schemaVersion": 1,
+  "title": "Meridian home hero",
+  "description": "Seeded hero image for the Meridian home page.",
+  "altText": "Earth from space with satellite constellation",
+  "tags": ["meridian", "hero", "space", "earth"],
+  "properties": {
+    "source": "unsplash",
+    "sourceUrl": "https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=1920&q=80"
+  },
+  "customFields": {},
+  "notes": "Downloaded for the local DAM bridge harness."
+}

package/templates/common/.content/dam/folders/seed/ast_site_home_hero/governance.json

@@ -0,0 +1,23 @@
+{
+  "$type": "dam.governance",
+  "schemaVersion": 1,
+  "asset": {
+    "status": "active",
+    "legalHold": false,
+    "retention": {
+      "policy": "local-seed"
+    },
+    "publicationRestriction": "none"
+  },
+  "versions": {
+    "v0001": {
+      "status": "approved",
+      "approvedAt": "2026-06-01T00:00:00Z",
+      "approvedBy": "local-seed",
+      "license": {
+        "kind": "unsplash-local-fixture"
+      },
+      "publicationRestriction": "none"
+    }
+  }
+}

package/templates/common/.content/dam/folders/seed/ast_site_home_hero/versions/v0001.json

@@ -0,0 +1,37 @@
+{
+  "$type": "dam.assetVersion",
+  "schemaVersion": 1,
+  "versionId": "v0001",
+  "blob": {
+    "sha256": "a0f506689de9b15a7055f70103a3f02cd3ba105771ae2de6754df2ede1210d3a",
+    "key": ".gradial-dam/blobs/sha256/a0/f5/a0f506689de9b15a7055f70103a3f02cd3ba105771ae2de6754df2ede1210d3a",
+    "byteSize": 15601,
+    "mime": "image/jpeg",
+    "originalFilename": "home-hero.jpg",
+    "checksumSource": "server-computed"
+  },
+  "technical": {
+    "dimensions": {
+      "width": 1200,
+      "height": 600
+    },
+    "duration": null,
+    "exif": {},
+    "iptc": {},
+    "xmp": {},
+    "video": null,
+    "audio": null,
+    "document": null,
+    "analysis": {
+      "saliency": null,
+      "faces": [],
+      "objects": [],
+      "segments": [],
+      "textRegions": [],
+      "logoRegions": [],
+      "safeAreas": []
+    }
+  },
+  "createdAt": "2026-06-01T00:00:00Z",
+  "createdBy": "local-seed"
+}

package/templates/common/.content/fragments/navbar/_index.json

@@ -0,0 +1,25 @@
+{
+  "$type": "fragment",
+  "fragmentId": "navbar",
+  "component": "site-navigation",
+  "props": {
+    "brandHref": "/",
+    "brandLabel": "Meridian",
+    "brandLogo": {
+      "src": "/assets/meridian-logo.svg",
+      "alt": "Meridian"
+    },
+    "navigation": [
+      { "id": "home", "label": "Home", "href": "/" },
+      { "id": "plans", "label": "Plans", "href": "/plans/" },
+      { "id": "devices", "label": "Devices", "href": "/devices/" },
+      { "id": "business", "label": "Business", "href": "/business/" },
+      { "id": "blog", "label": "Blog", "href": "/blog/" },
+      { "id": "about", "label": "About", "href": "/about/" }
+    ],
+    "utilities": [
+      { "id": "sign-in", "label": "Sign in", "href": "/sign-in/", "variant": "ghost" },
+      { "id": "contact-sales", "label": "Contact sales", "href": "/contact-sales/", "variant": "primary" }
+    ]
+  }
+}