@forumone/create-throughline 0.2.0 → 0.3.0

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

@@ -0,0 +1,108 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'SectionIntro',
+  category: 'section',
+  description:
+    'A section opener that establishes what the next block of content is about without competing with the page hero.',
+  intent:
+    'Introduce a new section inside a page. Use when you need an h2-level heading with optional eyebrow and supporting body copy, such as "Our approach", "Recent work", or "What we believe". Pairs with any content block below it.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['SectionIntro'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'eyebrow',
+        type: 'text',
+        required: false,
+        maxLength: 40,
+        constraints: 'Short kicker label above the headline',
+      },
+      {
+        name: 'headline',
+        type: 'text',
+        required: true,
+        maxLength: 100,
+        constraints: 'Sentence case; scannable; reads like a chapter title',
+      },
+      {
+        name: 'body',
+        type: 'text',
+        required: false,
+        maxLength: 240,
+        constraints: 'One or two sentences that set up the section',
+      },
+    ],
+    variants: [
+      {
+        name: 'start',
+        description: 'Left-aligned',
+        whenToUse: 'Default — pairs with left-aligned content blocks below',
+      },
+      {
+        name: 'center',
+        description: 'Center-aligned',
+        whenToUse: 'Landing pages and marketing sections where the intro anchors a centered layout',
+      },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.text.primary',
+      'color.text.secondary',
+      'spacing.container',
+      'spacing.3',
+      'spacing.2',
+      'font.size.3xl',
+      'font.size.lg',
+      'font.size.sm',
+      'font.weight.semibold',
+      'line.height.snug',
+      'line.height.relaxed',
+      'letter.spacing.wide',
+    ],
+  },
+
+  accessibility: {
+    role: 'region',
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'The headline is announced as an h2 element. The eyebrow is supplementary text read before the headline. No interactive controls.',
+    contentWarnings: [
+      'Do not use SectionIntro before Hero on the same page — the page must start with a single h1',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Introduce a section inside a content page', storyId: 'section-intro--default' },
+    { label: 'Centered', intent: 'Anchor a centered marketing section', storyId: 'section-intro--centered' },
+    { label: 'Headline only', intent: 'Minimal section divider with just a heading', storyId: 'section-intro--headline-only' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Using SectionIntro as the page opener',
+      why: 'SectionIntro renders h2; a page should begin with an h1 for accessibility and SEO',
+      useInstead: 'Hero',
+    },
+    {
+      label: 'Stacking two SectionIntros with no content between them',
+      why: 'Creates a visual and semantic duplicate that signals nothing new',
+      useInstead: 'Merge into a single SectionIntro with a longer body',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,36 @@
+.intro {
+  max-width: 48rem;
+  padding: 0 var(--spacing-container);
+  margin: 0 auto;
+}
+
+.start {
+  text-align: start;
+  margin-inline-start: 0;
+}
+
+.center {
+  text-align: center;
+}
+
+.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-2);
+}
+
+.headline {
+  font-size: var(--font-size-3xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-snug);
+  margin-bottom: var(--spacing-3);
+}
+
+.body {
+  font-size: var(--font-size-lg);
+  line-height: var(--line-height-relaxed);
+  color: var(--color-text-secondary);
+}

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

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { SectionIntro } from './SectionIntro.js'
+
+const meta: Meta<typeof SectionIntro> = {
+  title: 'Section Intro',
+  component: SectionIntro,
+}
+
+export default meta
+
+type Story = StoryObj<typeof SectionIntro>
+
+export const Default: Story = {
+  args: {
+    eyebrow: 'Our approach',
+    headline: 'How we work with partners',
+    body: 'We start with the content model, then the governance, then the visual design.',
+  },
+}
+
+export const Centered: Story = {
+  args: {
+    alignment: 'center',
+    headline: 'What we believe',
+    body: 'Editorial teams deserve tools that take their workflows seriously.',
+  },
+}
+
+export const HeadlineOnly: Story = {
+  args: {
+    headline: 'Recent work',
+  },
+}

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

@@ -0,0 +1,28 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { SectionIntro } from './SectionIntro.js'
+
+describe('SectionIntro', () => {
+  it('renders the headline as h2', () => {
+    render(<SectionIntro headline="Our approach" />)
+    const heading = screen.getByRole('heading', { level: 2 })
+    expect(heading).toHaveTextContent('Our approach')
+  })
+
+  it('renders eyebrow and body when provided', () => {
+    render(
+      <SectionIntro
+        eyebrow="About"
+        headline="How we work"
+        body="We start with content."
+      />,
+    )
+    expect(screen.getByText('About')).toBeInTheDocument()
+    expect(screen.getByText('We start with content.')).toBeInTheDocument()
+  })
+
+  it('omits the body when not provided', () => {
+    render(<SectionIntro headline="Plain" />)
+    expect(screen.queryByText(/we start/i)).not.toBeInTheDocument()
+  })
+})

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

@@ -0,0 +1,28 @@
+import { clsx } from 'clsx'
+import styles from './SectionIntro.module.css'
+
+export type SectionIntroAlignment = 'start' | 'center'
+
+export interface SectionIntroProps {
+  eyebrow?: string
+  headline: string
+  body?: string
+  alignment?: SectionIntroAlignment
+  className?: string
+}
+
+export function SectionIntro({
+  eyebrow,
+  headline,
+  body,
+  alignment = 'start',
+  className,
+}: SectionIntroProps) {
+  return (
+    <header className={clsx(styles.intro, styles[alignment], className)}>
+      {eyebrow ? <p className={styles.eyebrow}>{eyebrow}</p> : null}
+      <h2 className={styles.headline}>{headline}</h2>
+      {body ? <p className={styles.body}>{body}</p> : null}
+    </header>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { SectionIntro, type SectionIntroProps, type SectionIntroAlignment } from './SectionIntro.js'
+export { contract as sectionIntroContract } from './SectionIntro.contract.js'

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

@@ -0,0 +1,76 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Spacer',
+  category: 'utility',
+  description: 'An explicit vertical spacing block that inserts a token-sized gap between adjacent components.',
+  intent:
+    'Add breathing room between two components when neither component\'s own margins produce the right rhythm. Prefer component-owned spacing when possible; reach for Spacer only when layout composition requires it, such as between Stats and a following CardGrid on a dense page.',
+
+  composition: {
+    placement: ['page', 'section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['Spacer'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'size',
+        type: 'select',
+        required: false,
+        constraints: 'xs | sm | md | lg | xl',
+      },
+    ],
+    variants: [
+      { name: 'xs', description: 'Extra small', whenToUse: 'Fine-grained adjustment' },
+      { name: 'sm', description: 'Small', whenToUse: 'Between closely related elements' },
+      { name: 'md', description: 'Medium (default)', whenToUse: 'Most cases' },
+      { name: 'lg', description: 'Large', whenToUse: 'Between page sections that need visual separation' },
+      { name: 'xl', description: 'Extra large', whenToUse: 'Major visual pauses on long landing pages' },
+    ],
+  },
+
+  tokens: {
+    consumes: ['spacing.2', 'spacing.4', 'spacing.8', 'spacing.16', 'spacing.24'],
+    configurable: [
+      { prop: 'size', tokenGroup: 'spacing', allowedValues: ['xs', 'sm', 'md', 'lg', 'xl'] },
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Spacer is a presentational div marked aria-hidden. Assistive technology skips it entirely.',
+    contentWarnings: [
+      'Do not use Spacer to replace paragraph margins inside Prose — the typography already handles that',
+    ],
+  },
+
+  examples: [
+    { label: 'Small', intent: 'Subtle gap', storyId: 'spacer--small' },
+    { label: 'Medium', intent: 'Standard gap', storyId: 'spacer--medium' },
+    { label: 'Large', intent: 'Major section break', storyId: 'spacer--large' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Stacking multiple Spacers to achieve a custom size',
+      why: 'Nesting spacers bypasses the token scale and makes spacing unauditable',
+      useInstead: 'Pick the nearest size in the scale or adjust the neighboring components',
+    },
+    {
+      label: 'Using Spacer for semantic breaks',
+      why: 'Spacer has no semantic meaning; readers cannot tell one section has ended and another begun',
+      useInstead: 'Divider (decorative=false) or SectionIntro',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,23 @@
+.spacer {
+  width: 100%;
+}
+
+.xs {
+  height: var(--spacing-2);
+}
+
+.sm {
+  height: var(--spacing-4);
+}
+
+.md {
+  height: var(--spacing-8);
+}
+
+.lg {
+  height: var(--spacing-16);
+}
+
+.xl {
+  height: var(--spacing-24);
+}

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

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Spacer, type SpacerSize } from './Spacer.js'
+
+const meta: Meta<typeof Spacer> = {
+  title: 'Spacer',
+  component: Spacer,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Spacer>
+
+function bracket(size: SpacerSize) {
+  return (
+    <div style={{ background: 'var(--color-bg-secondary)', padding: '0.5rem' }}>
+      <p>Content above (size: {size})</p>
+      <Spacer size={size} />
+      <p>Content below</p>
+    </div>
+  )
+}
+
+export const Small: Story = { render: () => bracket('sm'), args: { size: 'sm' } }
+export const Medium: Story = { render: () => bracket('md'), args: { size: 'md' } }
+export const Large: Story = { render: () => bracket('lg'), args: { size: 'lg' } }

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

@@ -0,0 +1,17 @@
+import { render } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Spacer } from './Spacer.js'
+
+describe('Spacer', () => {
+  it('is aria-hidden and presentational', () => {
+    const { container } = render(<Spacer />)
+    const spacer = container.firstChild as HTMLElement
+    expect(spacer).toHaveAttribute('aria-hidden', 'true')
+    expect(spacer).toHaveAttribute('role', 'presentation')
+  })
+
+  it('applies the size modifier class', () => {
+    const { container } = render(<Spacer size="lg" />)
+    expect((container.firstChild as HTMLElement).className).toContain('lg')
+  })
+})

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

@@ -0,0 +1,19 @@
+import { clsx } from 'clsx'
+import styles from './Spacer.module.css'
+
+export type SpacerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+export interface SpacerProps {
+  size?: SpacerSize
+  className?: string
+}
+
+export function Spacer({ size = 'md', className }: SpacerProps) {
+  return (
+    <div
+      aria-hidden="true"
+      role="presentation"
+      className={clsx(styles.spacer, styles[size], className)}
+    />
+  )
+}

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

@@ -0,0 +1,2 @@
+export { Spacer, type SpacerProps, type SpacerSize } from './Spacer.js'
+export { contract as spacerContract } from './Spacer.contract.js'

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

@@ -0,0 +1,103 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Stats',
+  category: 'data',
+  description:
+    'A numerical data display with two to four stat items, each with a value, a label, and an optional description.',
+  intent:
+    'Surface a small set of headline metrics in a scannable row. Use for impact reports, program highlights, and annual summaries where numbers tell the story. Not appropriate for dense tabular data — that needs a real table component.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: [],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'eyebrow',
+        type: 'text',
+        required: false,
+        maxLength: 40,
+      },
+      {
+        name: 'headline',
+        type: 'text',
+        required: false,
+        maxLength: 100,
+      },
+      {
+        name: 'items',
+        type: 'array',
+        required: true,
+        constraints: 'Two to four items',
+        of: [
+          { name: 'value', type: 'text', required: true, maxLength: 20 },
+          { name: 'label', type: 'text', required: true, maxLength: 60 },
+          { name: 'description', type: 'text', required: false, maxLength: 80 },
+        ],
+      },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.text.primary',
+      'color.text.secondary',
+      'color.brand.primary',
+      'spacing.16',
+      'spacing.10',
+      'spacing.8',
+      'spacing.3',
+      'spacing.2',
+      'spacing.1',
+      'spacing.container',
+      'font.size.5xl',
+      'font.size.3xl',
+      'font.size.sm',
+      'font.weight.bold',
+      'font.weight.semibold',
+      'line.height.tight',
+      'letter.spacing.wide',
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Statistics are rendered as a <dl> with <dt>/<dd> pairs. Screen readers traverse each value + label + description as a definition list entry.',
+    contentWarnings: [
+      'Keep values concise — "4,200" instead of "4,200,000,000 dollars"',
+      'Never invent numbers to fill the grid; use the real count even if unequal',
+    ],
+  },
+
+  examples: [
+    { label: 'Three stats', intent: 'Annual report highlights', storyId: 'stats--three-stats' },
+    { label: 'Two stats', intent: 'Minimal impact summary', storyId: 'stats--two-stats' },
+    { label: 'Four stats', intent: 'Dense overview', storyId: 'stats--four-stats' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Five or more stats',
+      why: 'Beyond four items the layout cramps on mobile and the individual numbers lose impact',
+      useInstead: 'Pick the top four; move the rest to a full report page',
+    },
+    {
+      label: 'Paragraph-length values',
+      why: 'Stats are designed for at-a-glance reading; long values overwhelm the layout',
+      useInstead: 'Use Prose for extended narrative',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,88 @@
+.stats {
+  padding: var(--spacing-16) 0;
+}
+
+.container {
+  max-width: 72rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+}
+
+.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);
+  text-align: center;
+}
+
+.headline {
+  font-size: var(--font-size-3xl);
+  font-weight: var(--font-weight-semibold);
+  margin-bottom: var(--spacing-10);
+  text-align: center;
+}
+
+.list {
+  display: grid;
+  gap: var(--spacing-8);
+  margin: 0;
+}
+
+.cols-2 {
+  grid-template-columns: repeat(2, 1fr);
+}
+
+.cols-3 {
+  grid-template-columns: repeat(3, 1fr);
+}
+
+.cols-4 {
+  grid-template-columns: repeat(4, 1fr);
+}
+
+@media (max-width: 720px) {
+  .cols-2,
+  .cols-3,
+  .cols-4 {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (max-width: 480px) {
+  .cols-2,
+  .cols-3,
+  .cols-4 {
+    grid-template-columns: 1fr;
+  }
+}
+
+.item {
+  text-align: center;
+}
+
+.value {
+  font-size: var(--font-size-5xl);
+  font-weight: var(--font-weight-bold);
+  line-height: var(--line-height-tight);
+  color: var(--color-brand-primary);
+  margin: 0;
+}
+
+.label {
+  margin: var(--spacing-2) 0 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-1);
+}
+
+.labelText {
+  font-weight: var(--font-weight-semibold);
+}
+
+.description {
+  font-size: var(--font-size-sm);
+  color: var(--color-text-secondary);
+}

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

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Stats } from './Stats.js'
+
+const meta: Meta<typeof Stats> = {
+  title: 'Stats',
+  component: Stats,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Stats>
+
+export const ThreeStats: Story = {
+  args: {
+    eyebrow: 'Impact',
+    headline: 'Year in review',
+    items: [
+      { value: '128', label: 'Grants awarded', description: 'Across twelve programs' },
+      { value: '$4.2M', label: 'Total funded' },
+      { value: '87%', label: 'Completion rate', description: 'Measured over five years' },
+    ],
+  },
+}
+
+export const TwoStats: Story = {
+  args: {
+    items: [
+      { value: '30', label: 'Partner organizations' },
+      { value: '1,200', label: 'Researchers supported' },
+    ],
+  },
+}
+
+export const FourStats: Story = {
+  args: {
+    headline: 'By the numbers',
+    items: [
+      { value: '12', label: 'Countries' },
+      { value: '48', label: 'Programs' },
+      { value: '300+', label: 'Publications' },
+      { value: '5M', label: 'People reached' },
+    ],
+  },
+}

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

@@ -0,0 +1,44 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Stats } from './Stats.js'
+
+describe('Stats', () => {
+  it('renders each item as a dt/dd pair inside a dl', () => {
+    const { container } = render(
+      <Stats
+        items={[
+          { value: '100', label: 'Projects' },
+          { value: '50', label: 'Partners' },
+        ]}
+      />,
+    )
+    expect(container.querySelector('dl')).not.toBeNull()
+    const dts = container.querySelectorAll('dt')
+    const dds = container.querySelectorAll('dd')
+    expect(dts).toHaveLength(2)
+    expect(dds).toHaveLength(2)
+    expect(dts[0]).toHaveTextContent('100')
+    expect(dds[0]).toHaveTextContent('Projects')
+  })
+
+  it('renders optional eyebrow + headline', () => {
+    render(
+      <Stats
+        eyebrow="Impact"
+        headline="Summary"
+        items={[{ value: '1', label: 'Thing' }]}
+      />,
+    )
+    expect(screen.getByText('Impact')).toBeInTheDocument()
+    expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent('Summary')
+  })
+
+  it('renders item description when present', () => {
+    render(
+      <Stats
+        items={[{ value: '1', label: 'Thing', description: 'Extra context' }]}
+      />,
+    )
+    expect(screen.getByText('Extra context')).toBeInTheDocument()
+  })
+})