@forumone/create-throughline 0.2.0 → 0.3.0

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

@@ -0,0 +1,41 @@
+import { clsx } from 'clsx'
+import type { ReactNode } from 'react'
+import styles from './FAQ.module.css'
+
+export interface FAQItem {
+  question: string
+  answer: ReactNode
+}
+
+export interface FAQProps {
+  headline?: string
+  items: FAQItem[]
+  /** If true, the first item is open by default. */
+  defaultOpenFirst?: boolean
+  className?: string
+}
+
+export function FAQ({ headline, items, defaultOpenFirst = false, className }: FAQProps) {
+  return (
+    <section className={clsx(styles.faq, className)}>
+      <div className={styles.container}>
+        {headline ? <h2 className={styles.headline}>{headline}</h2> : null}
+        <ul className={styles.list}>
+          {items.map((item, index) => (
+            <li key={item.question}>
+              <details className={styles.item} open={defaultOpenFirst && index === 0}>
+                <summary className={styles.question}>
+                  <span>{item.question}</span>
+                  <span aria-hidden="true" className={styles.chevron}>
+                    +
+                  </span>
+                </summary>
+                <div className={styles.answer}>{item.answer}</div>
+              </details>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </section>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { FAQ, type FAQProps, type FAQItem } from './FAQ.js'
+export { contract as faqContract } from './FAQ.contract.js'

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

@@ -0,0 +1,182 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Hero',
+  category: 'hero',
+  description:
+    'A page opener with prominent headline, supporting copy, and primary call to action.',
+  intent:
+    'Establish what a page is about within the first viewport. Use when the page introduces a new topic, program, or initiative that deserves prominent editorial framing. Typically appears once at the top of a page.',
+
+  composition: {
+    placement: ['page'],
+    maxPerPage: 1,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['Hero', 'SectionIntro'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'eyebrow',
+        type: 'text',
+        required: false,
+        maxLength: 40,
+        constraints: 'Short kicker label, typically the section or program name',
+      },
+      {
+        name: 'headline',
+        type: 'text',
+        required: true,
+        maxLength: 80,
+        constraints: 'Sentence case; avoid all caps; keep scannable',
+      },
+      {
+        name: 'body',
+        type: 'text',
+        required: false,
+        maxLength: 240,
+        constraints: 'Two to three sentences that support the headline without repeating it',
+      },
+      {
+        name: 'cta',
+        type: 'group',
+        required: false,
+        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 },
+        ],
+      },
+      {
+        name: 'media',
+        type: 'image',
+        required: false,
+        constraints: 'Required when variant is "split"; otherwise optional',
+      },
+    ],
+    variants: [
+      {
+        name: 'default',
+        description: 'Centered text, no media',
+        whenToUse: 'Editorial pages and mission statements where content carries the weight',
+      },
+      {
+        name: 'compact',
+        description: 'Reduced vertical padding',
+        whenToUse: 'Subpages where the hero is contextual framing rather than primary introduction',
+      },
+      {
+        name: 'split',
+        description: 'Text on one side, media on the other',
+        whenToUse: 'Program pages or anywhere a single supporting image carries meaning',
+      },
+    ],
+  },
+
+  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.12',
+      'spacing.8',
+      'spacing.6',
+      'spacing.4',
+      'spacing.3',
+      'font.size.5xl',
+      'font.size.4xl',
+      'font.size.xl',
+      'font.size.sm',
+      'font.weight.bold',
+      'font.weight.semibold',
+      'line.height.tight',
+      'line.height.relaxed',
+      'letter.spacing.tight',
+      'letter.spacing.wide',
+      'radius.md',
+      'radius.lg',
+    ],
+    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 h1 element. The eyebrow is read as supplementary text before the headline. Decorative media is treated as presentational when the alt attribute is empty.',
+    contentWarnings: [
+      'Avoid text overlay on busy images',
+      'Ensure sufficient color contrast between headline and background',
+    ],
+  },
+
+  examples: [
+    {
+      label: 'Default',
+      intent: 'Standard editorial page opener with CTA',
+      storyId: 'hero--default',
+    },
+    {
+      label: 'Program landing page',
+      intent: 'Introduce a new fellowship program',
+      storyId: 'hero--program-landing',
+    },
+    {
+      label: 'Compact subpage',
+      intent: 'Open a secondary page with light framing',
+      storyId: 'hero--compact',
+    },
+    {
+      label: 'Split with media',
+      intent: 'Open a content page with supporting visual context',
+      storyId: 'hero--split',
+    },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Multiple heroes on one page',
+      why: 'A page should have a single primary opener; multiple heroes flatten hierarchy and confuse screen readers with multiple h1s',
+      useInstead: 'Use SectionIntro for secondary section headers',
+    },
+    {
+      label: 'Hero at the bottom of a page',
+      why: 'Heroes are editorial openers, not closers',
+      useInstead: 'Use CTASection for page-bottom calls to action',
+    },
+    {
+      label: 'Split variant without media',
+      why: 'The split layout allocates half the space for media; leaving it empty creates awkward whitespace',
+      useInstead: 'Use the default variant when media is not available',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,124 @@
+.hero {
+  padding: var(--spacing-section) 0;
+  position: relative;
+}
+
+.bg-primary {
+  background: var(--color-bg-primary);
+  color: var(--color-text-primary);
+}
+
+.bg-secondary {
+  background: var(--color-bg-secondary);
+  color: var(--color-text-primary);
+}
+
+.bg-inverse {
+  background: var(--color-bg-inverse);
+  color: var(--color-text-inverse);
+}
+
+.container {
+  max-width: 72rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+  display: grid;
+  gap: var(--spacing-12);
+}
+
+.split .container {
+  grid-template-columns: 1fr 1fr;
+  align-items: center;
+}
+
+.compact {
+  padding: var(--spacing-16) 0;
+}
+
+.content {
+  max-width: 42rem;
+}
+
+.eyebrow {
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-semibold);
+  text-transform: uppercase;
+  letter-spacing: var(--letter-spacing-wide);
+  color: var(--color-text-secondary);
+  margin-bottom: var(--spacing-3);
+}
+
+.headline {
+  font-size: var(--font-size-5xl);
+  font-weight: var(--font-weight-bold);
+  line-height: var(--line-height-tight);
+  letter-spacing: var(--letter-spacing-tight);
+  margin-bottom: var(--spacing-6);
+}
+
+.body {
+  font-size: var(--font-size-xl);
+  line-height: var(--line-height-relaxed);
+  color: var(--color-text-secondary);
+  margin-bottom: var(--spacing-8);
+}
+
+.bg-inverse .body {
+  color: var(--color-text-inverse);
+  opacity: 0.85;
+}
+
+.actions {
+  display: flex;
+  gap: var(--spacing-4);
+  flex-wrap: wrap;
+}
+
+.primaryCta,
+.secondaryCta {
+  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;
+}
+
+.primaryCta {
+  background: var(--color-brand-primary);
+  color: var(--color-text-inverse);
+}
+
+.primaryCta:hover {
+  background: var(--color-brand-primary-hover);
+}
+
+.secondaryCta {
+  border: 1px solid var(--color-border-strong);
+  color: var(--color-text-primary);
+}
+
+.bg-inverse .secondaryCta {
+  border-color: var(--color-text-inverse);
+  color: var(--color-text-inverse);
+}
+
+.secondaryCta:hover {
+  background: var(--color-bg-secondary);
+}
+
+.media img {
+  width: 100%;
+  border-radius: var(--radius-lg);
+}
+
+@media (max-width: 768px) {
+  .split .container {
+    grid-template-columns: 1fr;
+  }
+
+  .headline {
+    font-size: var(--font-size-4xl);
+  }
+}

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

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Hero } from './Hero.js'
+
+const meta: Meta<typeof Hero> = {
+  title: 'Hero',
+  component: Hero,
+  parameters: { layout: 'fullscreen' },
+}
+
+export default meta
+
+type Story = StoryObj<typeof Hero>
+
+export const Default: Story = {
+  args: {
+    headline: 'Build tomorrow, starting today',
+    body: 'An opinionated starting point for teams that take content seriously.',
+    cta: { label: 'Learn more', url: '#' },
+  },
+}
+
+export const ProgramLanding: Story = {
+  args: {
+    eyebrow: 'New program',
+    headline: 'Fellowship for climate researchers',
+    body: 'A one-year fellowship supporting researchers at the intersection of climate and community resilience.',
+    cta: { label: 'Apply now', url: '#' },
+    secondaryCta: { label: 'Learn about eligibility', url: '#' },
+  },
+}
+
+export const Compact: Story = {
+  args: {
+    variant: 'compact',
+    headline: 'About our work',
+    body: 'Meet the team and learn how we approach our mission.',
+  },
+}
+
+export const Split: Story = {
+  args: {
+    variant: 'split',
+    eyebrow: 'Case study',
+    headline: 'How we helped a foundation modernize its grant process',
+    body: 'A twelve-month engagement that reduced processing time by 60% while improving applicant experience.',
+    cta: { label: 'Read the case study', url: '#' },
+    media: { url: 'https://placehold.co/800x600', alt: 'Foundation office' },
+  },
+}
+
+export const Inverse: Story = {
+  args: {
+    background: 'inverse',
+    headline: 'A darker opener',
+    body: 'Use the inverse background when a hero needs to cut against surrounding content.',
+    cta: { label: 'Get started', url: '#' },
+  },
+}

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

@@ -0,0 +1,49 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Hero } from './Hero.js'
+
+describe('Hero', () => {
+  it('renders the headline as h1', () => {
+    render(<Hero headline="Big news" />)
+    const heading = screen.getByRole('heading', { level: 1 })
+    expect(heading).toHaveTextContent('Big news')
+  })
+
+  it('renders eyebrow, body, and both CTAs when provided', () => {
+    render(
+      <Hero
+        eyebrow="Program"
+        headline="Fellowship for climate researchers"
+        body="A one-year program."
+        cta={{ label: 'Apply', url: '/apply' }}
+        secondaryCta={{ label: 'Eligibility', url: '/eligibility' }}
+      />,
+    )
+    expect(screen.getByText('Program')).toBeInTheDocument()
+    expect(screen.getByText('A one-year program.')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'Apply' })).toHaveAttribute('href', '/apply')
+    expect(screen.getByRole('link', { name: 'Eligibility' })).toHaveAttribute(
+      'href',
+      '/eligibility',
+    )
+  })
+
+  it('omits the media region unless variant is split', () => {
+    const { container, rerender } = render(
+      <Hero
+        headline="Hi"
+        media={{ url: '/img.jpg', alt: 'pic' }}
+      />,
+    )
+    expect(container.querySelector('img')).toBeNull()
+
+    rerender(
+      <Hero
+        headline="Hi"
+        variant="split"
+        media={{ url: '/img.jpg', alt: 'pic' }}
+      />,
+    )
+    expect(container.querySelector('img')).not.toBeNull()
+  })
+})

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

@@ -0,0 +1,67 @@
+import { clsx } from 'clsx'
+import styles from './Hero.module.css'
+
+export type HeroVariant = 'default' | 'compact' | 'split'
+export type HeroBackground = 'primary' | 'secondary' | 'inverse'
+
+export interface HeroProps {
+  eyebrow?: string
+  headline: string
+  body?: string
+  cta?: { label: string; url: string }
+  secondaryCta?: { label: string; url: string }
+  media?: { url: string; alt: string }
+  variant?: HeroVariant
+  background?: HeroBackground
+  className?: string
+}
+
+export function Hero({
+  eyebrow,
+  headline,
+  body,
+  cta,
+  secondaryCta,
+  media,
+  variant = 'default',
+  background = 'primary',
+  className,
+}: HeroProps) {
+  return (
+    <section
+      className={clsx(
+        styles.hero,
+        styles[variant],
+        styles[`bg-${background}`],
+        className,
+      )}
+    >
+      <div className={styles.container}>
+        <div className={styles.content}>
+          {eyebrow ? <p className={styles.eyebrow}>{eyebrow}</p> : null}
+          <h1 className={styles.headline}>{headline}</h1>
+          {body ? <p className={styles.body}>{body}</p> : null}
+          {cta || secondaryCta ? (
+            <div className={styles.actions}>
+              {cta ? (
+                <a href={cta.url} className={styles.primaryCta}>
+                  {cta.label}
+                </a>
+              ) : null}
+              {secondaryCta ? (
+                <a href={secondaryCta.url} className={styles.secondaryCta}>
+                  {secondaryCta.label}
+                </a>
+              ) : null}
+            </div>
+          ) : null}
+        </div>
+        {variant === 'split' && media ? (
+          <div className={styles.media}>
+            <img src={media.url} alt={media.alt} />
+          </div>
+        ) : null}
+      </div>
+    </section>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { Hero, type HeroProps, type HeroVariant, type HeroBackground } from './Hero.js'
+export { contract as heroContract } from './Hero.contract.js'

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

@@ -0,0 +1,94 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'MediaBlock',
+  category: 'media',
+  description:
+    'A full-width image or video block with optional caption and configurable aspect ratio.',
+  intent:
+    'Insert a single piece of featured media inside a content flow. Use for editorial imagery that deserves its own moment — a photograph illustrating a story, a portrait accompanying a quote, or a video introducing a program. Not a gallery; for multiple items compose a custom layout.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: [],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'media',
+        type: 'group',
+        required: true,
+        of: [
+          { name: 'type', type: 'select', required: true },
+          { name: 'url', type: 'link', required: true },
+          { name: 'alt', type: 'text', required: false, maxLength: 200 },
+          { name: 'poster', type: 'image', required: false },
+          { name: 'ariaLabel', type: 'text', required: false, maxLength: 120 },
+        ],
+      },
+      {
+        name: 'caption',
+        type: 'text',
+        required: false,
+        maxLength: 200,
+        constraints: 'One sentence that adds context the image alone cannot carry',
+      },
+    ],
+    variants: [
+      { name: '16:9', description: 'Cinematic widescreen', whenToUse: 'Most photographs and video' },
+      { name: '4:3', description: 'Classic television ratio', whenToUse: 'Vintage or squared compositions' },
+      { name: 'square', description: '1:1', whenToUse: 'Portraits or product shots' },
+      { name: 'auto', description: 'Media\'s native ratio', whenToUse: 'Diagrams, infographics, or tall images' },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.bg.tertiary',
+      'color.text.secondary',
+      'spacing.container',
+      'spacing.3',
+      'font.size.sm',
+      'radius.lg',
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: ['Video: native play/pause/seek controls'],
+    screenReaderBehavior:
+      'Images announce their alt text. Videos announce their aria-label (or fall back to native labeling). Captions are associated with the figure semantically via <figcaption>.',
+    contentWarnings: [
+      'Always author alt text for images that carry information; use empty alt ("") for purely decorative media',
+      'Videos with spoken content must ship captions',
+    ],
+  },
+
+  examples: [
+    { label: 'Image with caption', intent: 'Editorial photograph', storyId: 'media-block--image' },
+    { label: 'Square crop', intent: 'Portrait or product shot', storyId: 'media-block--square' },
+    { label: 'Video', intent: 'Introductory video with poster', storyId: 'media-block--video' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Stacking three MediaBlocks for a gallery',
+      why: 'MediaBlock is a spotlight element; stacking them creates awkward repetition without true gallery ergonomics',
+      useInstead: 'Build a dedicated gallery component in your client DS',
+    },
+    {
+      label: 'Decorative image with invented alt text',
+      why: 'Screen readers read the alt text; inventing "people smiling" for decorative media wastes listener attention',
+      useInstead: 'Use alt="" for purely decorative media',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,49 @@
+.figure {
+  margin: 0 auto;
+  max-width: 72rem;
+  padding: 0 var(--spacing-container);
+}
+
+.frame {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  border-radius: var(--radius-lg);
+  background: var(--color-bg-tertiary);
+}
+
+.aspect16x9 {
+  aspect-ratio: 16 / 9;
+}
+
+.aspect4x3 {
+  aspect-ratio: 4 / 3;
+}
+
+.aspect-square {
+  aspect-ratio: 1 / 1;
+}
+
+.aspect-auto {
+  aspect-ratio: auto;
+}
+
+.media {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.aspect-auto .media {
+  position: static;
+  height: auto;
+}
+
+.caption {
+  margin-top: var(--spacing-3);
+  font-size: var(--font-size-sm);
+  color: var(--color-text-secondary);
+  text-align: center;
+}