@forumone/create-throughline 0.2.1 → 0.3.1

package/dist/templates/with-reference-ds/design-system/scripts/build-manifest.ts

@@ -0,0 +1,89 @@
+import { readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+import {
+  CONTRACT_VERSION,
+  ManifestSchema,
+  type ComponentContract,
+} from '@forumone/throughline-design-contract'
+import { getTokenList } from '../src/tokens/index.ts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(__dirname, '..')
+const componentsDir = resolve(packageRoot, 'src/components')
+const outputDir = resolve(packageRoot, 'dist')
+const outputFile = resolve(outputDir, 'manifest.json')
+
+async function readPackageVersion(): Promise<string> {
+  const raw = await readFile(resolve(packageRoot, 'package.json'), 'utf8')
+  const parsed = JSON.parse(raw) as { version?: string }
+  return parsed.version ?? '0.0.0'
+}
+
+async function collectContracts(): Promise<Record<string, ComponentContract>> {
+  const components: Record<string, ComponentContract> = {}
+
+  let entries: string[]
+  try {
+    entries = await readdir(componentsDir)
+  } catch {
+    return components
+  }
+
+  for (const name of entries) {
+    const dir = resolve(componentsDir, name)
+    const dirStat = await stat(dir).catch(() => null)
+    if (!dirStat?.isDirectory()) continue
+
+    const contractPath = join(dir, `${name}.contract.ts`)
+    const contractStat = await stat(contractPath).catch(() => null)
+    if (!contractStat?.isFile()) continue
+
+    const module = (await import(pathToFileURL(contractPath).href)) as {
+      contract?: ComponentContract
+    }
+    if (!module.contract) {
+      throw new Error(`${name}.contract.ts does not export "contract"`)
+    }
+    components[name] = module.contract
+  }
+
+  return components
+}
+
+async function main() {
+  const components = await collectContracts()
+
+  const manifest = {
+    contractVersion: CONTRACT_VERSION,
+    designSystem: {
+      name: '@forumone/throughline-reference-ds',
+      version: await readPackageVersion(),
+      description:
+        'A brand-neutral reference design system demonstrating contract compliance for Throughline.',
+    },
+    tokens: getTokenList(),
+    components,
+    build: {
+      timestamp: new Date().toISOString(),
+      source: 'scripts/build-manifest.ts',
+    },
+  }
+
+  const result = ManifestSchema.safeParse(manifest)
+  if (!result.success) {
+    console.error('Generated manifest failed validation:')
+    for (const issue of result.error.issues) {
+      console.error(`  - ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+    }
+    process.exit(1)
+  }
+
+  await mkdir(outputDir, { recursive: true })
+  await writeFile(outputFile, JSON.stringify(result.data, null, 2), 'utf8')
+
+  const componentCount = Object.keys(components).length
+  console.log(`Wrote ${outputFile} (${componentCount} components)`)
+}
+
+await main()

package/dist/templates/with-reference-ds/design-system/scripts/build-styles.ts

@@ -0,0 +1,28 @@
+import { copyFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const stylesSrc = resolve(__dirname, '../src/styles')
+const stylesDist = resolve(__dirname, '../dist/styles')
+
+await mkdir(stylesDist, { recursive: true })
+
+const entries = await readdir(stylesSrc)
+const cssFiles = entries.filter((f) => f.endsWith('.css'))
+
+for (const file of cssFiles) {
+  await copyFile(resolve(stylesSrc, file), resolve(stylesDist, file))
+}
+
+// Also emit a combined bundle so consumers can import `@forumone/throughline-reference-ds/styles.css`.
+const bundleParts: string[] = []
+for (const file of ['reset.css', 'tokens.css', 'base.css']) {
+  if (cssFiles.includes(file)) {
+    const content = await readFile(resolve(stylesSrc, file), 'utf8')
+    bundleParts.push(`/* ${basename(file)} */\n${content.trim()}\n`)
+  }
+}
+await writeFile(resolve(stylesDist, 'index.css'), bundleParts.join('\n'), 'utf8')
+
+console.log(`Copied ${cssFiles.length} CSS files to dist/styles`)

package/dist/templates/with-reference-ds/design-system/scripts/build-tokens-css.ts

@@ -0,0 +1,43 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { colors, darkOverrides } from '../src/tokens/colors.ts'
+import { layout } from '../src/tokens/layout.ts'
+import { radii } from '../src/tokens/radii.ts'
+import { spacing } from '../src/tokens/spacing.ts'
+import { typography } from '../src/tokens/typography.ts'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const outputPath = resolve(__dirname, '../src/styles/tokens.css')
+
+/** Turns `color.brand.primaryHover` into `--color-brand-primary-hover`. */
+function tokenToVariable(name: string): string {
+  const kebab = name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+  return `--${kebab.replace(/\./g, '-')}`
+}
+
+function section(title: string, entries: Array<readonly [string, string]>): string {
+  const rules = entries.map(([name, value]) => `  ${tokenToVariable(name)}: ${value};`).join('\n')
+  return `  /* ${title} */\n${rules}`
+}
+
+const light = [
+  section('Colors', Object.entries(colors)),
+  section('Typography', Object.entries(typography)),
+  section('Spacing', Object.entries(spacing)),
+  section('Radii', Object.entries(radii)),
+  section('Layout & Containers', Object.entries(layout)),
+].join('\n\n')
+
+const dark = Object.entries(darkOverrides)
+  .map(([name, value]) => `    ${tokenToVariable(name)}: ${value};`)
+  .join('\n')
+
+const banner = '/* Auto-generated by scripts/build-tokens-css.ts. Do not edit by hand. */'
+
+const output = `${banner}\n\n:root {\n${light}\n}\n\n@media (prefers-color-scheme: dark) {\n  :root {\n${dark}\n  }\n}\n`
+
+await mkdir(dirname(outputPath), { recursive: true })
+await writeFile(outputPath, output, 'utf8')
+
+console.log(`Wrote ${outputPath}`)

package/dist/templates/with-reference-ds/design-system/scripts/validate.ts

@@ -0,0 +1,58 @@
+import { readFile, stat } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadManifest } from '@forumone/throughline-design-contract'
+import { formatLintIssues, lintManifest } from '@forumone/throughline-design-contract/lint'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(__dirname, '..')
+const manifestPath = resolve(packageRoot, 'dist/manifest.json')
+const storybookIndexPath = resolve(packageRoot, 'storybook-static/index.json')
+
+async function readJson<T>(path: string): Promise<T> {
+  const raw = await readFile(path, 'utf8')
+  return JSON.parse(raw) as T
+}
+
+async function collectStoryIds(): Promise<Set<string> | undefined> {
+  const exists = await stat(storybookIndexPath).catch(() => null)
+  if (!exists) {
+    console.warn(
+      `No storybook-static/index.json found; skipping storyId lint. Run \`pnpm build-storybook\` first to enable it.`,
+    )
+    return undefined
+  }
+  const index = await readJson<{ entries: Record<string, { id: string; type: string }> }>(
+    storybookIndexPath,
+  )
+  const ids = new Set<string>()
+  for (const entry of Object.values(index.entries)) {
+    if (entry.type === 'story') ids.add(entry.id)
+  }
+  return ids
+}
+
+async function main() {
+  const raw = await readJson<unknown>(manifestPath)
+  const loaded = loadManifest(raw)
+
+  const availableStoryIds = await collectStoryIds()
+  const lintOptions = availableStoryIds ? { availableStoryIds } : {}
+
+  const issues = lintManifest(loaded.raw, lintOptions)
+  const errors = issues.filter((i) => i.severity === 'error')
+  const warnings = issues.filter((i) => i.severity === 'warning')
+
+  if (errors.length > 0) {
+    console.error(formatLintIssues(errors))
+    process.exit(1)
+  }
+
+  if (warnings.length > 0) {
+    console.warn(formatLintIssues(warnings))
+  } else {
+    console.log(`Manifest is clean (${loaded.listComponents().length} components).`)
+  }
+}
+
+await main()

package/dist/templates/with-reference-ds/design-system/src/components/CTASection/CTASection.contract.ts

@@ -0,0 +1,128 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'CTASection',
+  category: 'cta',
+  description:
+    'A page-bottom call to action with a headline, optional supporting copy, and one or two buttons.',
+  intent:
+    'Close a page with a clear next step. Use at the end of program pages, campaigns, and marketing pages where the reader has enough context to act. Do not use at the top of a page (that is Hero\'s job) or as a section opener (that is SectionIntro\'s).',
+
+  composition: {
+    placement: ['page', 'section'],
+    maxPerPage: 2,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['CTASection'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'headline',
+        type: 'text',
+        required: true,
+        maxLength: 100,
+        constraints: 'Direct, imperative; reads like an invitation',
+      },
+      {
+        name: 'body',
+        type: 'text',
+        required: false,
+        maxLength: 200,
+        constraints: 'One sentence that reduces friction to clicking',
+      },
+      {
+        name: 'cta',
+        type: 'group',
+        required: true,
+        of: [
+          { name: 'label', type: 'text', required: true, maxLength: 30 },
+          { name: 'url', type: 'link', required: true },
+        ],
+      },
+      {
+        name: 'secondaryCta',
+        type: 'group',
+        required: false,
+        of: [
+          { name: 'label', type: 'text', required: true, maxLength: 30 },
+          { name: 'url', type: 'link', required: true },
+        ],
+      },
+    ],
+    variants: [
+      { name: 'primary', description: 'Standard background', whenToUse: 'Default' },
+      { name: 'secondary', description: 'Subtle grey background', whenToUse: 'Most page closes — less visual weight than Hero' },
+      { name: 'inverse', description: 'Dark background', whenToUse: 'Campaign pages or high-stakes calls to action' },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.bg.primary',
+      'color.bg.secondary',
+      'color.bg.inverse',
+      'color.text.primary',
+      'color.text.secondary',
+      'color.text.inverse',
+      'color.brand.primary',
+      'color.brand.primaryHover',
+      'color.border.strong',
+      'spacing.section',
+      'spacing.container',
+      'spacing.8',
+      'spacing.6',
+      'spacing.4',
+      'spacing.3',
+      'font.size.4xl',
+      'font.size.lg',
+      'font.weight.bold',
+      'font.weight.semibold',
+      'line.height.tight',
+      'line.height.relaxed',
+      'radius.md',
+    ],
+    configurable: [
+      {
+        prop: 'background',
+        tokenGroup: 'color.bg',
+        allowedValues: ['primary', 'secondary', 'inverse'],
+      },
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: ['Tab to primary CTA', 'Tab to secondary CTA'],
+    screenReaderBehavior:
+      'The headline is announced as an h2. CTAs are standard links; their label text is announced as the link name.',
+    contentWarnings: [
+      'Avoid verb-only labels ("Click", "Go") — include the destination ("Start building", "Read the docs")',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Two-button page close', storyId: 'cta-section--default' },
+    { label: 'Primary only', intent: 'Single-action CTA', storyId: 'cta-section--primary-only' },
+    { label: 'Inverse', intent: 'High-contrast campaign CTA', storyId: 'cta-section--inverse' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Three or more CTAs',
+      why: 'Too many options reduces conversion; pick the top one, put the rest on a detail page',
+      useInstead: 'One primary + optional secondary',
+    },
+    {
+      label: 'Using CTASection as a page opener',
+      why: 'Readers cannot convert without context; CTA belongs at the end',
+      useInstead: 'Hero',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: true,
+  },
+}

package/dist/templates/with-reference-ds/design-system/src/components/CTASection/CTASection.module.css

@@ -0,0 +1,83 @@
+.cta {
+  padding: var(--spacing-section) 0;
+  text-align: center;
+}
+
+.bg-primary {
+  background: var(--color-bg-primary);
+}
+
+.bg-secondary {
+  background: var(--color-bg-secondary);
+}
+
+.bg-inverse {
+  background: var(--color-bg-inverse);
+  color: var(--color-text-inverse);
+}
+
+.container {
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+}
+
+.headline {
+  font-size: var(--font-size-4xl);
+  font-weight: var(--font-weight-bold);
+  line-height: var(--line-height-tight);
+  margin-bottom: var(--spacing-4);
+}
+
+.body {
+  font-size: var(--font-size-lg);
+  color: var(--color-text-secondary);
+  line-height: var(--line-height-relaxed);
+  margin-bottom: var(--spacing-8);
+}
+
+.bg-inverse .body {
+  color: var(--color-text-inverse);
+  opacity: 0.85;
+}
+
+.actions {
+  display: flex;
+  gap: var(--spacing-4);
+  justify-content: center;
+  flex-wrap: wrap;
+}
+
+.primary,
+.secondary {
+  display: inline-flex;
+  align-items: center;
+  padding: var(--spacing-3) var(--spacing-6);
+  border-radius: var(--radius-md);
+  font-weight: var(--font-weight-semibold);
+  text-decoration: none;
+  transition: background-color 0.15s ease, border-color 0.15s ease;
+}
+
+.primary {
+  background: var(--color-brand-primary);
+  color: var(--color-text-inverse);
+}
+
+.primary:hover {
+  background: var(--color-brand-primary-hover);
+}
+
+.secondary {
+  border: 1px solid var(--color-border-strong);
+  color: var(--color-text-primary);
+}
+
+.bg-inverse .secondary {
+  border-color: var(--color-text-inverse);
+  color: var(--color-text-inverse);
+}
+
+.secondary:hover {
+  background: var(--color-bg-secondary);
+}

package/dist/templates/with-reference-ds/design-system/src/components/CTASection/CTASection.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { CTASection } from './CTASection.js'
+
+const meta: Meta<typeof CTASection> = {
+  title: 'CTA Section',
+  component: CTASection,
+  parameters: { layout: 'fullscreen' },
+}
+
+export default meta
+
+type Story = StoryObj<typeof CTASection>
+
+export const Default: Story = {
+  args: {
+    headline: 'Ready to get started?',
+    body: 'Create your first site in under an hour with a working content model.',
+    cta: { label: 'Start building', url: '#' },
+    secondaryCta: { label: 'Read the docs', url: '#' },
+  },
+}
+
+export const PrimaryOnly: Story = {
+  args: {
+    headline: 'Join the next cohort',
+    body: 'Applications close on October 15th.',
+    cta: { label: 'Apply now', url: '#' },
+  },
+}
+
+export const Inverse: Story = {
+  args: {
+    background: 'inverse',
+    headline: 'Support our work',
+    body: 'Your contribution makes this research possible.',
+    cta: { label: 'Donate', url: '#' },
+    secondaryCta: { label: 'Learn more', url: '#' },
+  },
+}

package/dist/templates/with-reference-ds/design-system/src/components/CTASection/CTASection.test.tsx

@@ -0,0 +1,27 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { CTASection } from './CTASection.js'
+
+describe('CTASection', () => {
+  it('renders headline as h2 and primary CTA', () => {
+    render(
+      <CTASection
+        headline="Act now"
+        cta={{ label: 'Start', url: '/start' }}
+      />,
+    )
+    expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent('Act now')
+    expect(screen.getByRole('link', { name: 'Start' })).toHaveAttribute('href', '/start')
+  })
+
+  it('renders secondary CTA when provided', () => {
+    render(
+      <CTASection
+        headline="Act now"
+        cta={{ label: 'Start', url: '/start' }}
+        secondaryCta={{ label: 'Learn more', url: '/learn' }}
+      />,
+    )
+    expect(screen.getByRole('link', { name: 'Learn more' })).toBeInTheDocument()
+  })
+})

package/dist/templates/with-reference-ds/design-system/src/components/CTASection/CTASection.tsx

@@ -0,0 +1,41 @@
+import { clsx } from 'clsx'
+import styles from './CTASection.module.css'
+
+export type CTASectionBackground = 'primary' | 'secondary' | 'inverse'
+
+export interface CTASectionProps {
+  headline: string
+  body?: string
+  cta: { label: string; url: string }
+  secondaryCta?: { label: string; url: string }
+  background?: CTASectionBackground
+  className?: string
+}
+
+export function CTASection({
+  headline,
+  body,
+  cta,
+  secondaryCta,
+  background = 'secondary',
+  className,
+}: CTASectionProps) {
+  return (
+    <section className={clsx(styles.cta, styles[`bg-${background}`], className)}>
+      <div className={styles.container}>
+        <h2 className={styles.headline}>{headline}</h2>
+        {body ? <p className={styles.body}>{body}</p> : null}
+        <div className={styles.actions}>
+          <a href={cta.url} className={styles.primary}>
+            {cta.label}
+          </a>
+          {secondaryCta ? (
+            <a href={secondaryCta.url} className={styles.secondary}>
+              {secondaryCta.label}
+            </a>
+          ) : null}
+        </div>
+      </div>
+    </section>
+  )
+}

package/dist/templates/with-reference-ds/design-system/src/components/CTASection/index.ts

@@ -0,0 +1,2 @@
+export { CTASection, type CTASectionProps, type CTASectionBackground } from './CTASection.js'
+export { contract as ctaSectionContract } from './CTASection.contract.js'

package/dist/templates/with-reference-ds/design-system/src/components/Card/Card.contract.ts

@@ -0,0 +1,122 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Card',
+  category: 'card',
+  description:
+    'A single content card with optional image, eyebrow, title, description, and link. Renders as a link when a link target is provided.',
+  intent:
+    'Surface a single piece of content in a scannable, consistent shape — a program page, a blog post, a case study, a staff bio. Cards are typically laid out in a CardGrid, but a single Card can appear alone inside a section when the content warrants singular emphasis.',
+
+  composition: {
+    placement: ['section', 'inline'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: [],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'eyebrow',
+        type: 'text',
+        required: false,
+        maxLength: 30,
+        constraints: 'Short label such as the content type ("Case study", "Program update")',
+      },
+      {
+        name: 'image',
+        type: 'image',
+        required: false,
+        constraints: 'Landscape orientation; framing works best for images that read at small sizes',
+      },
+      {
+        name: 'title',
+        type: 'text',
+        required: true,
+        maxLength: 100,
+        constraints: 'Sentence case; reads like a headline',
+      },
+      {
+        name: 'description',
+        type: 'text',
+        required: false,
+        maxLength: 200,
+        constraints: 'One to two sentences that give the reader a reason to click',
+      },
+      {
+        name: 'link',
+        type: 'group',
+        required: false,
+        of: [
+          { name: 'label', type: 'text', required: true, maxLength: 30 },
+          { name: 'url', type: 'link', required: true },
+        ],
+      },
+    ],
+    variants: [
+      { name: 'linked', description: 'Entire card is clickable', whenToUse: 'Teaser for a single piece of content' },
+      { name: 'static', description: 'No link; presentational only', whenToUse: 'Inline informational cards (team bios, program descriptions) that do not link elsewhere' },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.bg.primary',
+      'color.bg.tertiary',
+      'color.text.primary',
+      'color.text.secondary',
+      'color.border.default',
+      'color.border.strong',
+      'color.brand.primary',
+      'spacing.6',
+      'spacing.2',
+      'font.size.xl',
+      'font.size.base',
+      'font.size.sm',
+      'font.size.xs',
+      'font.weight.semibold',
+      'line.height.snug',
+      'line.height.normal',
+      'letter.spacing.wide',
+      'radius.lg',
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: ['When linked, the whole card is a single tab stop'],
+    screenReaderBehavior:
+      'Linked cards render as a single <a> element announcing the title + description + link label as one unit. Static cards render as <article> with an h3 title.',
+    contentWarnings: [
+      'Avoid nested interactive elements inside a linked card (buttons, additional links)',
+      'Always author alt text for card images or omit the image entirely',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Content teaser with image and link', storyId: 'card--default' },
+    { label: 'With eyebrow', intent: 'Labeled teaser highlighting content type', storyId: 'card--with-eyebrow' },
+    { label: 'No image', intent: 'Text-only teaser for resources or downloads', storyId: 'card--no-image' },
+    { label: 'Static', intent: 'Presentational card without a link target', storyId: 'card--static' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Nesting interactive controls inside a linked card',
+      why: 'A linked card is a single tab stop; adding buttons or additional links creates nested interactive regions that confuse assistive technology',
+      useInstead: 'Use a static card with explicit nested controls, or move secondary actions to a detail page',
+    },
+    {
+      label: 'Using Card as a navigation menu item',
+      why: 'Cards are for content teasers; site navigation belongs in a Menu or Nav component',
+      useInstead: 'A dedicated navigation component',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}