@forumone/create-throughline 0.2.1 → 0.3.1

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'

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

@@ -0,0 +1,78 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'CardGrid',
+  category: 'section',
+  description:
+    'A responsive layout container for two, three, or four Cards per row. Reflows to fewer columns on narrow viewports.',
+  intent:
+    'Lay out multiple Card components inside a section. Use for program lists, blog indexes, staff directories, and any collection of similarly-shaped content. CardGrid is purely layout; it does not fetch data or filter — authors list the Cards they want.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: ['Card'],
+    forbiddenAdjacent: [],
+    allowedSlots: { children: ['Card'] },
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'children',
+        type: 'array',
+        required: true,
+        constraints: 'An array of Card components',
+        of: [{ name: 'card', type: 'group', required: true }],
+      },
+    ],
+    variants: [
+      { name: '2', description: 'Two columns', whenToUse: 'Lists of 2-4 prominent items' },
+      { name: '3', description: 'Three columns', whenToUse: 'Default — works for most collections' },
+      { name: '4', description: 'Four columns', whenToUse: 'Denser lists of 8 or more short cards' },
+    ],
+  },
+
+  tokens: {
+    consumes: ['spacing.container', 'spacing.6'],
+    configurable: [
+      { prop: 'columns', tokenGroup: 'layout', allowedValues: ['2', '3', '4'] },
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Purely visual layout. Screen readers traverse children in source order; CardGrid itself adds no ARIA.',
+    contentWarnings: [
+      'Children must be Cards; mixing other components breaks the visual rhythm',
+      'Keep all cards roughly the same content length — dramatically unequal cards look broken',
+    ],
+  },
+
+  examples: [
+    { label: 'Two columns', intent: 'Featured program pair', storyId: 'card-grid--two-column' },
+    { label: 'Three columns', intent: 'Standard content index', storyId: 'card-grid--three-column' },
+    { label: 'Four columns', intent: 'Dense staff directory', storyId: 'card-grid--four-column' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Mixing Cards and non-Card children',
+      why: 'The grid assumes uniform children; mixing Stats or MediaBlocks produces broken columns',
+      useInstead: 'Group by type — one CardGrid, then the other components below',
+    },
+    {
+      label: 'Using CardGrid with a single Card',
+      why: 'A CardGrid wrapping one Card is overhead without benefit',
+      useInstead: 'Render the Card directly',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,34 @@
+.grid {
+  max-width: 72rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+  display: grid;
+  gap: var(--spacing-6);
+}
+
+.cols-2 {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.cols-3 {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.cols-4 {
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+}
+
+@media (max-width: 960px) {
+  .cols-3,
+  .cols-4 {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 600px) {
+  .cols-2,
+  .cols-3,
+  .cols-4 {
+    grid-template-columns: 1fr;
+  }
+}

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

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Card } from '../Card/Card.js'
+import { CardGrid } from './CardGrid.js'
+
+const meta: Meta<typeof CardGrid> = {
+  title: 'Card Grid',
+  component: CardGrid,
+}
+
+export default meta
+
+type Story = StoryObj<typeof CardGrid>
+
+function sampleCards(count: number) {
+  return Array.from({ length: count }, (_, index) => (
+    <Card
+      key={index}
+      image={{ url: `https://placehold.co/640x360?text=${index + 1}`, alt: `Placeholder ${index + 1}` }}
+      title={`Program ${index + 1}`}
+      description="Short description of this program or piece of content."
+      link={{ label: 'Learn more', url: '#' }}
+    />
+  ))
+}
+
+export const TwoColumn: Story = {
+  args: { columns: 2, children: sampleCards(4) },
+}
+
+export const ThreeColumn: Story = {
+  args: { columns: 3, children: sampleCards(6) },
+}
+
+export const FourColumn: Story = {
+  args: { columns: 4, children: sampleCards(8) },
+}

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

@@ -0,0 +1,25 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { CardGrid } from './CardGrid.js'
+
+describe('CardGrid', () => {
+  it('renders children', () => {
+    render(
+      <CardGrid>
+        <div data-testid="a">A</div>
+        <div data-testid="b">B</div>
+      </CardGrid>,
+    )
+    expect(screen.getByTestId('a')).toBeInTheDocument()
+    expect(screen.getByTestId('b')).toBeInTheDocument()
+  })
+
+  it('applies the columns modifier class', () => {
+    const { container } = render(
+      <CardGrid columns={4}>
+        <div />
+      </CardGrid>,
+    )
+    expect((container.firstChild as HTMLElement).className).toContain('cols-4')
+  })
+})

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

@@ -0,0 +1,19 @@
+import { clsx } from 'clsx'
+import type { ReactNode } from 'react'
+import styles from './CardGrid.module.css'
+
+export type CardGridColumns = 2 | 3 | 4
+
+export interface CardGridProps {
+  children: ReactNode
+  columns?: CardGridColumns
+  className?: string
+}
+
+export function CardGrid({ children, columns = 3, className }: CardGridProps) {
+  return (
+    <div className={clsx(styles.grid, styles[`cols-${columns}`], className)}>
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { CardGrid, type CardGridProps, type CardGridColumns } from './CardGrid.js'
+export { contract as cardGridContract } from './CardGrid.contract.js'

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

@@ -0,0 +1,87 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Divider',
+  category: 'utility',
+  description: 'A horizontal rule for separating sections of content.',
+  intent:
+    'Mark a visual pause between two blocks of content without introducing a new section header. Use sparingly — a SectionIntro is usually a better signal of a new topic. Divider is for rhythm, not hierarchy.',
+
+  composition: {
+    placement: ['page', 'section', 'inline'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['Divider'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'spacing',
+        type: 'select',
+        required: false,
+        constraints: 'compact | default | spacious',
+      },
+      {
+        name: 'decorative',
+        type: 'boolean',
+        required: false,
+        constraints: 'When true (default), the divider is aria-hidden',
+      },
+    ],
+    variants: [
+      { name: 'compact', description: 'Small vertical margin', whenToUse: 'Between tight pieces of content inside a list' },
+      { name: 'default', description: 'Standard vertical margin', whenToUse: 'Most cases' },
+      { name: 'spacious', description: 'Large vertical margin', whenToUse: 'Between major sections of a page' },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.border.default',
+      'spacing.24',
+      'spacing.12',
+      'spacing.6',
+    ],
+    configurable: [
+      { prop: 'spacing', tokenGroup: 'spacing', allowedValues: ['compact', 'default', 'spacious'] },
+    ],
+  },
+
+  accessibility: {
+    role: 'separator',
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'When decorative=true (default) the divider is marked aria-hidden and assistive tech skips it. When decorative=false it announces as a separator.',
+    contentWarnings: [
+      'Do not stack two Dividers in a row',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Standard section break', storyId: 'divider--default' },
+    { label: 'Compact', intent: 'Between related list items', storyId: 'divider--compact' },
+    { label: 'Spacious', intent: 'Between major page sections', storyId: 'divider--spacious' },
+    { label: 'Meaningful', intent: 'Semantic section break announced by screen readers', storyId: 'divider--meaningful' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Using Divider instead of SectionIntro',
+      why: 'Dividers carry no semantic meaning; readers cannot tell a new section has started without the accompanying headline',
+      useInstead: 'SectionIntro',
+    },
+    {
+      label: 'Decorative dividers announced to screen readers',
+      why: 'Adds noise without value',
+      useInstead: 'Leave decorative=true (the default)',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,18 @@
+.divider {
+  border: 0;
+  border-top: 1px solid var(--color-border-default);
+  max-width: 72rem;
+  margin-inline: auto;
+}
+
+.compact {
+  margin-block: var(--spacing-6);
+}
+
+.default {
+  margin-block: var(--spacing-12);
+}
+
+.spacious {
+  margin-block: var(--spacing-24);
+}

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

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Divider } from './Divider.js'
+
+const meta: Meta<typeof Divider> = {
+  title: 'Divider',
+  component: Divider,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Divider>
+
+export const Default: Story = {
+  render: (args) => (
+    <div>
+      <p>Above the divider.</p>
+      <Divider {...args} />
+      <p>Below the divider.</p>
+    </div>
+  ),
+}
+
+export const Compact: Story = { ...Default, args: { spacing: 'compact' } }
+export const Spacious: Story = { ...Default, args: { spacing: 'spacious' } }
+export const Meaningful: Story = {
+  ...Default,
+  args: { decorative: false },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use decorative={false} when the divider marks a meaningful section break that assistive technology should announce.',
+      },
+    },
+  },
+}

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

@@ -0,0 +1,20 @@
+import { render } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Divider } from './Divider.js'
+
+describe('Divider', () => {
+  it('renders a hr element', () => {
+    const { container } = render(<Divider />)
+    expect(container.querySelector('hr')).not.toBeNull()
+  })
+
+  it('defaults to aria-hidden for decorative use', () => {
+    const { container } = render(<Divider />)
+    expect(container.querySelector('hr')).toHaveAttribute('aria-hidden', 'true')
+  })
+
+  it('removes aria-hidden when not decorative', () => {
+    const { container } = render(<Divider decorative={false} />)
+    expect(container.querySelector('hr')).not.toHaveAttribute('aria-hidden')
+  })
+})

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

@@ -0,0 +1,17 @@
+import { clsx } from 'clsx'
+import styles from './Divider.module.css'
+
+export type DividerSpacing = 'compact' | 'default' | 'spacious'
+
+export interface DividerProps {
+  spacing?: DividerSpacing
+  decorative?: boolean
+  className?: string
+}
+
+export function Divider({ spacing = 'default', decorative = true, className }: DividerProps) {
+  const ariaProps = decorative
+    ? { role: 'presentation', 'aria-hidden': true as const }
+    : {}
+  return <hr {...ariaProps} className={clsx(styles.divider, styles[spacing], className)} />
+}

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

@@ -0,0 +1,2 @@
+export { Divider, type DividerProps, type DividerSpacing } from './Divider.js'
+export { contract as dividerContract } from './Divider.contract.js'

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

@@ -0,0 +1,104 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'FAQ',
+  category: 'data',
+  description:
+    'A disclosure-style question and answer list using native <details>/<summary> for keyboard accessibility with no JavaScript.',
+  intent:
+    'Answer the predictable questions readers arrive with. Use for program applications, purchase funnels, onboarding pages — anywhere the same three to ten questions come up repeatedly. Not for searchable knowledge bases (those need their own search UI).',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: 2,
+    requiredSiblings: [],
+    forbiddenAdjacent: [],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'headline',
+        type: 'text',
+        required: false,
+        maxLength: 100,
+      },
+      {
+        name: 'items',
+        type: 'array',
+        required: true,
+        constraints: 'Three to ten items; more than that needs its own dedicated page',
+        of: [
+          { name: 'question', type: 'text', required: true, maxLength: 200 },
+          { name: 'answer', type: 'richtext', required: true },
+        ],
+      },
+      {
+        name: 'defaultOpenFirst',
+        type: 'boolean',
+        required: false,
+        constraints: 'Set true when the first question is one readers always ask',
+      },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.bg.primary',
+      'color.text.primary',
+      'color.text.secondary',
+      'color.border.default',
+      'color.border.strong',
+      'spacing.16',
+      'spacing.8',
+      'spacing.5',
+      'spacing.4',
+      'spacing.2',
+      'spacing.container',
+      'font.size.3xl',
+      'font.size.xl',
+      'font.weight.semibold',
+      'line.height.relaxed',
+      'radius.md',
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [
+      'Tab to each question summary',
+      'Enter or Space opens/closes the current item',
+    ],
+    screenReaderBehavior:
+      'Each question is a <summary> inside <details>, so screen readers announce open/closed state natively. The answer becomes available to assistive tech when the item is expanded.',
+    contentWarnings: [
+      'Keep answers short and scannable — a paragraph at most',
+      'Do not nest FAQs inside FAQs',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Program application FAQ', storyId: 'faq--default' },
+    { label: 'First item open', intent: 'Lead with the most common question already answered', storyId: 'faq--open-first' },
+    { label: 'Without headline', intent: 'Inline FAQ under a larger section', storyId: 'faq--no-headline' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Twenty-question FAQ',
+      why: 'Past about ten items the disclosure pattern breaks down; readers cannot scan the list',
+      useInstead: 'Split into topic-specific FAQs across multiple pages, or build a searchable knowledge base',
+    },
+    {
+      label: 'Using FAQ to hide primary content',
+      why: 'Important content should be visible by default, not hidden behind a click',
+      useInstead: 'Prose or a proper section with a SectionIntro',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: true,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}