@gradial/aci 0.1.20-preview.3 → 0.1.20

package/templates/astro/template/src/design-system/tokens/components.css

@@ -0,0 +1,69 @@
+@theme {
+  --width-logo-mobile: calc(var(--spacing) * 31);
+  --width-logo: calc(var(--spacing) * 52);
+  --width-logo-footer-mobile: calc(var(--spacing) * 37);
+  --width-logo-footer: calc(var(--spacing) * 56);
+  --logo-filter: brightness(1.18) saturate(1.14);
+  --text-button: var(--text-size-body-small);
+  --leading-button: 1;
+  --spacing-button-x: calc(var(--spacing) * 4);
+  --spacing-button-y: calc(var(--spacing) * 3);
+  --height-button-min: calc(var(--spacing) * 10);
+  --button-hover-opacity: 0.85;
+  --transition-duration-fast: 200ms;
+  --button-primary-bg: var(--color-black);
+  --button-primary-text: var(--color-white);
+  --button-primary-border: var(--color-black);
+  --button-secondary-bg: transparent;
+  --button-secondary-text: var(--color-black);
+  --button-secondary-border: var(--color-black);
+  --button-outline-bg: transparent;
+  --button-outline-text: var(--color-black);
+  --button-outline-border: var(--color-border);
+  --button-tertiary-bg: transparent;
+  --button-tertiary-text: var(--color-accent-primary);
+  --button-tertiary-border: transparent;
+  --header-bg: var(--color-chrome-surface-default);
+  --header-text: var(--color-fg-inverse);
+  --header-muted: var(--color-fg-inverse-soft);
+  --header-border: var(--color-edge-inverse);
+  --header-link-hover: var(--color-accent-secondary);
+  --header-icon: var(--color-fg-inverse-muted);
+  --mobile-nav-bg: var(--color-chrome-surface-default);
+  --mobile-nav-text: var(--color-fg-inverse);
+  --mobile-nav-muted: var(--color-fg-inverse-muted);
+  --mobile-nav-border: var(--color-edge-inverse);
+  --mobile-nav-link-hover: var(--color-accent-secondary);
+  --mobile-nav-link-size: calc(var(--spacing) * 12);
+  --mobile-nav-link-line-height: 1.05;
+  --footer-bg: var(--color-chrome-surface-default);
+  --footer-text: var(--color-fg-inverse);
+  --footer-muted: var(--color-fg-inverse-muted);
+  --footer-border: var(--color-edge-inverse);
+  --footer-link-hover: var(--color-accent-secondary);
+  --footer-grid-columns: 1fr 2fr;
+  --color-callout-icon-bg-light: color-mix(in srgb, var(--color-accent-primary) 8%, var(--color-white));
+  --color-callout-icon-bg-dark: color-mix(in srgb, var(--color-accent-primary) 18%, transparent);
+  --color-callout-icon-bg: var(--color-callout-icon-bg-light);
+  --callout-icon-color: var(--color-accent-primary);
+  --max-width-rich-text: var(--max-width-container-narrow);
+  --max-width-rich-text-wide: calc(var(--spacing) * 216);
+  --rich-text-flow-space: calc(var(--spacing) * 6);
+  --rich-text-heading-space: calc(var(--spacing) * 10);
+  --rich-text-link-decoration-thickness: 0.09em;
+  --rich-text-link-underline-offset: 0.18em;
+  --rich-text-list-indent: 1.4em;
+  --rich-text-blockquote-border-width: calc(var(--spacing) * 1.2);
+  --rich-text-inline-code-padding: 0.08em 0.32em;
+  --rich-text-quote-border: var(--color-accent-primary);
+  --rich-text-quote-bg: color-mix(in srgb, var(--color-accent-primary) 6%, var(--color-white));
+  --rich-text-quote-bg-dark: color-mix(in srgb, var(--color-accent-primary) 16%, transparent);
+  --rich-text-quote-bg-default: var(--rich-text-quote-bg);
+  --rich-text-inline-code-bg: color-mix(in srgb, var(--color-fg-base-muted) 8%, var(--color-white));
+  --rich-text-inline-code-bg-dark: color-mix(in srgb, var(--color-white) 12%, transparent);
+  --rich-text-inline-code-bg-default: var(--rich-text-inline-code-bg);
+  --rich-text-inline-code-text: var(--color-fg);
+  --max-width-cta: calc(var(--spacing) * 304);
+  --z-header: 50;
+  --z-overlay: 60;
+}

package/templates/astro/template/src/design-system/tokens/index.css

@@ -0,0 +1,6 @@
+@import "./colors.css";
+@import "./typography.css";
+@import "./spacing.css";
+@import "./shadows.css";
+@import "./radii.css";
+@import "./components.css";

package/templates/astro/template/src/design-system/tokens/radii.css

@@ -0,0 +1,5 @@
+@theme {
+  --radius-button: calc(var(--spacing) * 2);
+  --radius-card: calc(var(--spacing) * 3);
+  --radius-cta: calc(var(--spacing) * 2);
+}

package/templates/astro/template/src/design-system/tokens/shadows.css

@@ -0,0 +1,5 @@
+@theme {
+  --shadow-card: 0 calc(var(--spacing) * 5.5) calc(var(--spacing) * 15) color-mix(in srgb, var(--color-black) 8%, transparent);
+  --shadow-card-dark: 0 calc(var(--spacing) * 5.5) calc(var(--spacing) * 15) color-mix(in srgb, var(--color-black) 36%, transparent);
+  --shadow-card-default: var(--shadow-card);
+}

package/templates/astro/template/src/design-system/tokens/spacing.css

@@ -0,0 +1,13 @@
+@theme {
+  --max-width-container: calc(var(--spacing) * 352);
+  --max-width-container-narrow: calc(var(--spacing) * 208);
+  --spacing-container: clamp(calc(var(--spacing) * 4), 4vw, calc(var(--spacing) * 11));
+  --spacing-section-y: clamp(calc(var(--spacing) * 18), 7vw, calc(var(--spacing) * 32));
+  --height-header: calc(var(--spacing) * 20);
+  --spacing-footer-y: clamp(calc(var(--spacing) * 18), 8vw, calc(var(--spacing) * 32));
+  --height-hero-min: clamp(calc(var(--spacing) * 144), 68vw, calc(var(--spacing) * 192));
+  --width-hero-content: calc(var(--spacing) * 180);
+  --spacing-card: clamp(calc(var(--spacing) * 5.5), 2vw, calc(var(--spacing) * 8));
+  --spacing-cta-y: clamp(calc(var(--spacing) * 17), 8vw, calc(var(--spacing) * 29));
+  --spacing-cta-x: clamp(calc(var(--spacing) * 6), 5vw, calc(var(--spacing) * 20));
+}

package/templates/astro/template/src/design-system/tokens/typography.css

@@ -0,0 +1,24 @@
+@theme {
+  --font-family-base: "Inter", "Helvetica Neue", Arial, sans-serif;
+  --font-family-heading: "Inter", "Helvetica Neue", Arial, sans-serif;
+  --font-weight-regular: 400;
+  --font-weight-medium: 560;
+  --font-weight-semibold: 650;
+  --font-weight-bold: 760;
+  --text-size-brand: 1.5rem;
+  --text-size-eyebrow: 0.8125rem;
+  --text-size-caption: 0.8125rem;
+  --text-size-body-small: 0.9375rem;
+  --text-size-body: 1.0625rem;
+  --text-size-body-large: 1.25rem;
+  --text-size-h1-mobile: 3.25rem;
+  --text-size-h1: 5rem;
+  --text-size-h2-mobile: 2.5rem;
+  --text-size-h2: 3.25rem;
+  --text-size-h3: 1.75rem;
+  --leading-tight: 0.96;
+  --leading-heading: 1.08;
+  --leading-body: 1.5;
+  --leading-relaxed: 1.68;
+  --letter-spacing-label: 0;
+}

package/templates/astro/template/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="astro/client" />

package/templates/astro/template/src/fixtures/atomicBlocks.ts

@@ -0,0 +1,33 @@
+import type { KernelPageBlock } from '@gradial/aci/content';
+
+export interface AtomicBlockStoryFixture {
+  id: string;
+  storybookId: string;
+  title: string;
+  block: KernelPageBlock;
+}
+
+export const atomicBlockStoryFixtures: AtomicBlockStoryFixture[] = [
+  {
+    id: 'button-variants',
+    storybookId: 'core-atomic-blocks-button--variants',
+    title: 'Button / All Variants',
+    block: {
+      id: 'fixture-button-variants',
+      component: 'container',
+      props: {
+        theme: 'auto',
+        blocks: [
+          { id: 'btn-primary', component: 'button', props: { label: 'Primary button', href: '#', variant: 'primary' } },
+          { id: 'btn-secondary', component: 'button', props: { label: 'Secondary button', href: '#', variant: 'secondary' } },
+          { id: 'btn-tertiary', component: 'button', props: { label: 'Tertiary button', href: '#', variant: 'tertiary' } },
+          { id: 'btn-icon-before', component: 'button', props: { label: 'Icon before', href: '#', variant: 'primary', icon: 'arrow-right', iconPosition: 'before' } },
+          { id: 'btn-icon-after', component: 'button', props: { label: 'Icon after', href: '#', variant: 'secondary', icon: 'arrow-right', iconPosition: 'after' } },
+          { id: 'btn-new-window', component: 'button', props: { label: 'Opens in new tab', href: 'https://example.com', variant: 'primary', newWindow: true, icon: 'arrow-right', iconPosition: 'after' } }
+        ]
+      }
+    }
+  }
+];
+
+export const atomicBlockVisualStoryIds = atomicBlockStoryFixtures.map((fixture) => fixture.storybookId);

package/templates/astro/template/src/fixtures/composition.ts

@@ -0,0 +1,31 @@
+import type { KernelPageBlock } from '@gradial/aci/content';
+
+export interface CompositionStoryFixture {
+  id: string;
+  storybookId: string;
+  title: string;
+  direction?: 'ltr' | 'rtl';
+  block: KernelPageBlock;
+}
+
+export const compositionStoryFixtures: CompositionStoryFixture[] = [
+  {
+    id: 'container-buttons',
+    storybookId: 'composition-container--buttons',
+    title: 'Container / Buttons',
+    block: {
+      id: 'fixture-container-buttons',
+      component: 'container',
+      props: {
+        theme: 'auto',
+        className: 'space-y-4',
+        blocks: [
+          { id: 'btn-1', component: 'button', props: { label: 'Primary action', href: '#', variant: 'primary', icon: 'arrow_forward', iconPosition: 'after' } },
+          { id: 'btn-2', component: 'button', props: { label: 'Secondary action', href: '#', variant: 'secondary' } }
+        ]
+      }
+    }
+  }
+];
+
+export const compositionVisualStoryIds = compositionStoryFixtures.map((fixture) => fixture.storybookId);

package/templates/astro/template/src/fixtures/index.ts

@@ -0,0 +1,17 @@
+export {
+  compositionStoryFixtures,
+  compositionVisualStoryIds,
+  type CompositionStoryFixture
+} from './composition';
+
+export {
+  sectionStoryFixtures,
+  sectionVisualStoryIds,
+  type SectionStoryFixture
+} from './sections';
+
+export {
+  atomicBlockStoryFixtures,
+  atomicBlockVisualStoryIds,
+  type AtomicBlockStoryFixture
+} from './atomicBlocks';

package/templates/astro/template/src/fixtures/sections.ts

@@ -0,0 +1,39 @@
+import type { KernelPageBlock } from '@gradial/aci/content';
+
+export interface SectionStoryFixture {
+  id: string;
+  storybookId: string;
+  title: string;
+  direction?: 'ltr' | 'rtl';
+  block: KernelPageBlock;
+}
+
+export const sectionStoryFixtures: SectionStoryFixture[] = [
+  {
+    id: 'home-hero',
+    storybookId: 'sections-home-hero--default',
+    title: 'Home Hero',
+    block: {
+      id: 'fixture-home-hero',
+      component: 'home_hero',
+      props: {
+        eyebrow: 'Bare Metal Learn',
+        headline: 'Ship the same site on every framework.',
+        description: 'One content model, three renderers. Build once in Next.js, Astro, and SvelteKit—then prove parity with shared fixtures.',
+        ctaLabel: 'Get started',
+        ctaHref: '/docs',
+          image: {
+          $type: 'gradial.image',
+          assetId: 'fixture_seattle',
+          versionId: 'v0001',
+          alt: 'Seattle skyline at dusk',
+          sources: [
+            { src: '/assets/seattle.avif', width: 1920, height: 1280, type: 'image/avif' }
+          ]
+        }
+      }
+    }
+  }
+];
+
+export const sectionVisualStoryIds = sectionStoryFixtures.map((fixture) => fixture.storybookId);

package/templates/astro/template/src/layouts/SiteLayout.astro

@@ -0,0 +1,30 @@
+---
+import '../design-system/styles.css';
+
+interface Props {
+  title: string;
+  description: string;
+  canonical?: string;
+  siteName?: string;
+}
+
+const { title, description, canonical, siteName = 'Gradial' } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title}</title>
+    <link rel="icon" type="image/png" href="/assets/bare-metal-logo.png" />
+    <meta name="description" content={description} />
+    {canonical ? <link rel="canonical" href={canonical} /> : null}
+    <meta property="og:title" content={title} />
+    <meta property="og:description" content={description} />
+    <meta property="og:site_name" content={siteName} />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>

package/templates/astro/template/src/pages/[...slug].astro

@@ -0,0 +1,61 @@
+---
+import { getGradialStaticPaths, getPageRuntimeRenderInput, createRenderChildren } from '@gradial/aci/astro';
+import { normalizeRoute, routeMetadataForContent, resolveSlots } from '@gradial/aci/content';
+import { FileContentProvider } from '@gradial/aci/providers/file';
+import type { KernelPage, KernelSiteConfig, LayoutEntry, FragmentData } from '@gradial/aci/content';
+import { registry } from '../cms/registry';
+import SiteLayout from '../layouts/SiteLayout.astro';
+
+export const getStaticPaths = getGradialStaticPaths;
+
+const route = normalizeRoute(Astro.params.slug ? `/${Astro.params.slug}` : '/');
+const runtimeInput = getPageRuntimeRenderInput(Astro.request);
+let siteConfig: KernelSiteConfig;
+let page: KernelPage;
+let provider: FileContentProvider;
+if (runtimeInput) {
+  siteConfig = runtimeInput.siteConfig as KernelSiteConfig;
+  page = runtimeInput.page as KernelPage;
+} else {
+  provider = new FileContentProvider();
+  [siteConfig, page] = await Promise.all([
+    provider.getSiteConfig<KernelSiteConfig>(),
+    provider.getPage<KernelPage>(route),
+  ]);
+}
+
+const meta = routeMetadataForContent(siteConfig, page);
+const layout = (runtimeInput?.layouts?.[page.layout] ?? await (provider ?? new FileContentProvider()).getLayout<LayoutEntry>(page.layout)) as LayoutEntry;
+const resolvedSlots = await resolveSlots(
+  layout,
+  page?.regions || {},
+  async (id) => {
+    if (runtimeInput?.fragments?.[id]) return runtimeInput.fragments[id] as FragmentData;
+    return await (provider ?? new FileContentProvider()).getFragment<FragmentData>(id);
+  }
+);
+
+const renderChildren = createRenderChildren(registry);
+---
+
+<SiteLayout title={meta.title} description={meta.description} canonical={meta.canonical} siteName={meta.siteName}>
+  {layout.slots.map((slot) => {
+    const blocks = resolvedSlots[slot.name];
+    if (!blocks?.length) return null;
+    const rendered = renderChildren(blocks);
+    if (slot.name === 'main') {
+      return (
+        <main id="content-main">
+          {rendered.map((child) => {
+            const Comp = child.Component as any;
+            return Comp ? <Comp {...child.props} /> : null;
+          })}
+        </main>
+      );
+    }
+    return rendered.map((child) => {
+      const Comp = child.Component as any;
+      return Comp ? <Comp {...child.props} /> : null;
+    });
+  })}
+</SiteLayout>

package/templates/astro/template/src/render/RenderPage.astro

@@ -0,0 +1,66 @@
+---
+import SiteLayout from '../layouts/SiteLayout.astro';
+import type { KernelPage, KernelSiteConfig } from '@gradial/aci/content';
+import { registryLookup } from '@gradial/aci/astro';
+import { registry } from '../cms/registry';
+import Header from '../components/chrome/Header.astro';
+import Footer from '../components/chrome/Footer.astro';
+
+interface RenderInput {
+  route: string;
+  domain: string;
+  locale: string;
+  siteConfig: KernelSiteConfig;
+  page: KernelPage;
+}
+
+interface Props {
+  input: RenderInput;
+}
+
+const { input } = Astro.props;
+const { siteConfig, page } = input;
+const title = page.metadata?.title || siteConfig.seo?.title || siteConfig.title;
+const description = page.metadata?.description || siteConfig.seo?.description || '';
+const canonical = page.metadata?.canonical;
+const siteName = siteConfig.seo?.siteName || siteConfig.title;
+
+const footer = siteConfig.footer || {};
+const blocks = page?.regions?.main || [];
+---
+
+<SiteLayout {title} {description} {canonical} {siteName}>
+  <Header
+    brandHref={siteConfig.brandHref || '/'}
+    brandLabel={siteConfig.title || 'Gradial'}
+    brandLogo={siteConfig.brandLogo || null}
+    navigation={(siteConfig.navigation || []) as any}
+    utilities={(siteConfig.utilities || []) as any}
+  />
+
+  <main id="content-main">
+    {page && page.status === 'published' ? (
+      blocks.map((block) => {
+        // Astro's type checker can't validate dynamically resolved components,
+        // so we cast to any. The registry is type-safe at registration time.
+        const Component = registryLookup(registry, block.component) as any;
+        return Component ? <Component {...block.props} /> : null;
+      })
+    ) : (
+      <section class="mx-auto max-w-container-narrow px-[var(--spacing-container)] py-[var(--spacing-section-y)] text-center">
+        <h1 class="[font-family:var(--font-family-heading)] text-[length:var(--text-size-h2-mobile)] font-[var(--font-weight-semibold)] leading-heading md:text-[length:var(--text-size-h2)]">Page not found</h1>
+        <p class="mt-5 text-[length:var(--text-size-body)] text-[color:var(--color-fg-secondary)]">The requested content route is not available in the local content kernel.</p>
+      </section>
+    )}
+  </main>
+
+  <Footer
+    brandHref={siteConfig.brandHref || '/'}
+    brandLabel={siteConfig.title || 'Gradial'}
+    brandLogo={siteConfig.brandLogo || null}
+    social={(footer.social || []) as any}
+    columns={(footer.columns || []) as any}
+    legalLinks={(footer.legalLinks || []) as any}
+    copyright={String(footer.copyright || '')}
+  />
+</SiteLayout>

package/templates/astro/template/src/stories/CompositionStoryFrame.astro

@@ -0,0 +1,15 @@
+---
+import type { KernelPageBlock } from '@gradial/aci/content';
+import ContainerSection from '../components/sections/ContainerSection.astro';
+
+interface Props {
+  block: KernelPageBlock;
+  direction?: 'ltr' | 'rtl';
+}
+
+const { block, direction = 'ltr' } = Astro.props;
+---
+
+<div dir={direction}>
+  {block.component === 'container' ? <ContainerSection {...block.props} /> : null}
+</div>

package/templates/astro/template/src/stories/HomeHero.stories.ts

@@ -0,0 +1,24 @@
+import { sectionStoryFixtures } from '../fixtures/sections';
+import SectionStoryFrame from './SectionStoryFrame.astro';
+
+const fixtureById = Object.fromEntries(
+  sectionStoryFixtures.map((fixture) => [fixture.id, fixture])
+);
+
+export default {
+  title: 'Sections/Home Hero',
+  component: SectionStoryFrame,
+  parameters: {
+    docs: {
+      description: {
+        component: 'Image-backed homepage hero with headline, body copy, and primary CTA.'
+      }
+    }
+  }
+};
+
+export const Default = {
+  args: {
+    block: fixtureById['home-hero'].block
+  }
+};

package/templates/astro/template/src/stories/SectionStoryFrame.astro

@@ -0,0 +1,16 @@
+---
+import type { KernelPageBlock } from '@gradial/aci/content';
+import HomeHero from '../components/sections/HomeHero.astro';
+
+interface Props {
+  block: KernelPageBlock;
+  direction?: 'ltr' | 'rtl';
+}
+
+const { block, direction = 'ltr' } = Astro.props;
+const props = block.props as any;
+---
+
+<div dir={direction}>
+  {block.component === 'home_hero' ? <HomeHero {...props} /> : null}
+</div>

package/templates/astro/template/src/stories/StoryDocFrame.astro

@@ -0,0 +1,31 @@
+---
+import type { KernelPageBlock } from '@gradial/aci/content';
+import CompositionStoryFrame from './CompositionStoryFrame.astro';
+
+interface Props {
+  heading?: string;
+  description?: string;
+  block: KernelPageBlock;
+  direction?: 'ltr' | 'rtl';
+}
+
+const { heading, description, block, direction = 'ltr' } = Astro.props;
+---
+
+<div>
+  {(heading || description) && (
+    <div class="theme-auto bg-surface-default px-8 pt-8 pb-4">
+      {heading && (
+        <h2 class="[font-family:var(--font-family-heading)] text-[length:var(--text-size-h3)] font-[var(--font-weight-semibold)] leading-heading text-fg">
+          {heading}
+        </h2>
+      )}
+      {description && (
+        <p class="mt-2 max-w-3xl text-[length:var(--text-size-body)] leading-body text-fg-muted">
+          {description}
+        </p>
+      )}
+    </div>
+  )}
+  <CompositionStoryFrame block={block} direction={direction} />
+</div>

package/templates/astro/template/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "astro/tsconfigs/base",
+  "include": [
+    ".astro/types.d.ts",
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/templates/common/.agents/AGENTS.md

@@ -0,0 +1,37 @@
+# ACI Site Agent Guide
+
+This is an ACI (Agentic Content Infrastructure) frontend project. Agents
+working in this repo should load skills before making changes.
+
+## Skills
+
+| Skill | Load when |
+|-------|-----------|
+| `aci` | Onboarding, running builds, validating, troubleshooting |
+| `authoring` | Creating or editing content, adding components, design tokens |
+| `migration` | Reverse-engineering a live site or design into ACI |
+
+Skills live in `.agents/skills/`. Each has a `SKILL.md` entry point and
+`references/` for deeper topics.
+
+## Quick Reference
+
+- Content lives in `.content/` as JSON.
+- Contracts live in `src/cms/contracts/` (Zod schemas, no framework imports).
+- Runtime components live in `src/components/` (framework code).
+- Registry lives in `src/cms/registry.ts` (`createRegistry` with `[contract, component]` tuples).
+- Compiled output goes to `.aci/compiled/` (generated, not checked in).
+- Framework integration via `withAci()` in the framework config.
+- Supported frameworks: Astro and Next.js (SvelteKit removed).
+
+## Commands
+
+```bash
+npm install
+npm run dev              # Start dev server
+npm run aci:validate     # Validate content
+npm run aci:compile      # Compile contracts
+npm run content:compile  # Compile content
+npm run build            # Framework build
+npm run aci:doctor       # Health check
+```