@forumone/create-throughline 0.2.1 → 0.3.0

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,
+  },
+}

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

@@ -0,0 +1,64 @@
+.card {
+  display: flex;
+  flex-direction: column;
+  background: var(--color-bg-primary);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+  text-decoration: none;
+  color: inherit;
+  transition: box-shadow 0.15s ease, border-color 0.15s ease;
+}
+
+.linked:hover {
+  border-color: var(--color-border-strong);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
+}
+
+.imageFrame {
+  aspect-ratio: 16 / 9;
+  background: var(--color-bg-tertiary);
+  overflow: hidden;
+}
+
+.image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.content {
+  padding: var(--spacing-6);
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-2);
+}
+
+.eyebrow {
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-semibold);
+  text-transform: uppercase;
+  letter-spacing: var(--letter-spacing-wide);
+  color: var(--color-text-secondary);
+}
+
+.title {
+  font-size: var(--font-size-xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-snug);
+  margin: 0;
+}
+
+.description {
+  font-size: var(--font-size-base);
+  color: var(--color-text-secondary);
+  line-height: var(--line-height-normal);
+  margin: 0;
+}
+
+.linkLabel {
+  margin-top: var(--spacing-2);
+  color: var(--color-brand-primary);
+  font-weight: var(--font-weight-semibold);
+  font-size: var(--font-size-sm);
+}

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

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Card } from './Card.js'
+
+const meta: Meta<typeof Card> = {
+  title: 'Card',
+  component: Card,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Card>
+
+export const Default: Story = {
+  args: {
+    image: { url: 'https://placehold.co/640x360', alt: 'Illustration of a forest' },
+    title: 'Reforesting urban lots',
+    description: 'Partners across three cities are turning vacant parcels into pollinator habitat.',
+    link: { label: 'Read the story', url: '#' },
+  },
+}
+
+export const WithEyebrow: Story = {
+  args: {
+    eyebrow: 'Program update',
+    image: { url: 'https://placehold.co/640x360', alt: 'Researchers reviewing findings' },
+    title: 'Year-one findings from the fellowship cohort',
+    description: 'Five researchers, twelve publications, and a clearer picture of where to go next.',
+    link: { label: 'View findings', url: '#' },
+  },
+}
+
+export const NoImage: Story = {
+  args: {
+    title: 'Policy brief: Community-led adaptation',
+    description: 'A short overview of our recommendations for local policymakers.',
+    link: { label: 'Download brief', url: '#' },
+  },
+}
+
+export const Static: Story = {
+  args: {
+    title: 'Mission statement',
+    description: 'Content that supports the work of mission-driven organizations.',
+  },
+}

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

@@ -0,0 +1,37 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Card } from './Card.js'
+
+describe('Card', () => {
+  it('renders as a link when a link target is provided', () => {
+    render(
+      <Card
+        title="Linked"
+        description="desc"
+        link={{ label: 'Read', url: '/read' }}
+      />,
+    )
+    const link = screen.getByRole('link', { name: /linked/i })
+    expect(link).toHaveAttribute('href', '/read')
+  })
+
+  it('renders as an article without link', () => {
+    const { container } = render(<Card title="Static" description="plain" />)
+    const root = container.firstChild as HTMLElement
+    expect(root.tagName.toLowerCase()).toBe('article')
+  })
+
+  it('renders image, eyebrow, and description when provided', () => {
+    render(
+      <Card
+        eyebrow="Program"
+        image={{ url: '/img.jpg', alt: 'Illustration' }}
+        title="Hello"
+        description="Some text"
+      />,
+    )
+    expect(screen.getByText('Program')).toBeInTheDocument()
+    expect(screen.getByRole('img', { name: 'Illustration' })).toBeInTheDocument()
+    expect(screen.getByText('Some text')).toBeInTheDocument()
+  })
+})

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

@@ -0,0 +1,39 @@
+import { clsx } from 'clsx'
+import styles from './Card.module.css'
+
+export interface CardProps {
+  title: string
+  description?: string
+  image?: { url: string; alt: string }
+  link?: { label: string; url: string }
+  eyebrow?: string
+  className?: string
+}
+
+export function Card({ title, description, image, link, eyebrow, className }: CardProps) {
+  const body = (
+    <>
+      {image ? (
+        <div className={styles.imageFrame}>
+          <img src={image.url} alt={image.alt} className={styles.image} />
+        </div>
+      ) : null}
+      <div className={styles.content}>
+        {eyebrow ? <p className={styles.eyebrow}>{eyebrow}</p> : null}
+        <h3 className={styles.title}>{title}</h3>
+        {description ? <p className={styles.description}>{description}</p> : null}
+        {link ? <span className={styles.linkLabel}>{link.label}</span> : null}
+      </div>
+    </>
+  )
+
+  if (link) {
+    return (
+      <a href={link.url} className={clsx(styles.card, styles.linked, className)}>
+        {body}
+      </a>
+    )
+  }
+
+  return <article className={clsx(styles.card, className)}>{body}</article>
+}

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

@@ -0,0 +1,2 @@
+export { Card, type CardProps } from './Card.js'
+export { contract as cardContract } from './Card.contract.js'