@forumone/create-throughline 0.2.1 → 0.3.1

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

@@ -0,0 +1,59 @@
+.figure {
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: var(--spacing-10) var(--spacing-container);
+  text-align: center;
+}
+
+.quote {
+  margin: 0 0 var(--spacing-6);
+  font-style: italic;
+}
+
+.quote p {
+  font-size: var(--font-size-2xl);
+  line-height: var(--line-height-snug);
+  color: var(--color-text-primary);
+  margin: 0;
+}
+
+.large .quote p {
+  font-size: var(--font-size-4xl);
+  line-height: var(--line-height-tight);
+}
+
+.quote p::before {
+  content: '\201C';
+  margin-right: 0.1em;
+}
+
+.quote p::after {
+  content: '\201D';
+  margin-left: 0.1em;
+}
+
+.attribution {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-3);
+  color: var(--color-text-secondary);
+  font-size: var(--font-size-sm);
+  font-style: normal;
+}
+
+.avatar {
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--radius-full);
+  object-fit: cover;
+}
+
+.name {
+  font-weight: var(--font-weight-semibold);
+  color: var(--color-text-primary);
+}
+
+.role::before {
+  content: '\00B7';
+  margin: 0 0.25em;
+}

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

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Quote } from './Quote.js'
+
+const meta: Meta<typeof Quote> = {
+  title: 'Quote',
+  component: Quote,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Quote>
+
+export const Default: Story = {
+  args: {
+    quote:
+      'The best CMS is the one your editorial team forgets they are using.',
+    attribution: { name: 'Jordan Rivers', role: 'Design director' },
+  },
+}
+
+export const WithAvatar: Story = {
+  args: {
+    quote:
+      'After we moved to a content-first model, our publishing velocity nearly doubled without adding to the team.',
+    attribution: {
+      name: 'Maria Santos',
+      role: 'Head of content, Greenfield Foundation',
+      avatar: { url: 'https://placehold.co/80x80', alt: 'Portrait of Maria Santos' },
+    },
+  },
+}
+
+export const Large: Story = {
+  args: {
+    size: 'large',
+    quote: 'Editorial teams deserve tools that take their workflows seriously.',
+  },
+}
+
+export const WithoutAttribution: Story = {
+  args: {
+    quote: 'Content first. Everything else follows.',
+  },
+}

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

@@ -0,0 +1,37 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Quote } from './Quote.js'
+
+describe('Quote', () => {
+  it('renders the quote inside a blockquote', () => {
+    const { container } = render(<Quote quote="Content first." />)
+    expect(container.querySelector('blockquote')).not.toBeNull()
+    expect(screen.getByText('Content first.')).toBeInTheDocument()
+  })
+
+  it('renders the attribution inside a figcaption when provided', () => {
+    const { container } = render(
+      <Quote
+        quote="Words."
+        attribution={{ name: 'Ada Lovelace', role: 'Mathematician' }}
+      />,
+    )
+    const caption = container.querySelector('figcaption')
+    expect(caption).not.toBeNull()
+    expect(caption).toHaveTextContent('Ada Lovelace')
+    expect(caption).toHaveTextContent('Mathematician')
+  })
+
+  it('renders an avatar when attribution includes one', () => {
+    render(
+      <Quote
+        quote="Words."
+        attribution={{
+          name: 'Grace Hopper',
+          avatar: { url: '/avatar.jpg', alt: 'Grace Hopper portrait' },
+        }}
+      />,
+    )
+    expect(screen.getByRole('img', { name: 'Grace Hopper portrait' })).toBeInTheDocument()
+  })
+})

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

@@ -0,0 +1,40 @@
+import { clsx } from 'clsx'
+import styles from './Quote.module.css'
+
+export type QuoteSize = 'default' | 'large'
+
+export interface QuoteProps {
+  quote: string
+  attribution?: {
+    name: string
+    role?: string
+    avatar?: { url: string; alt: string }
+  }
+  size?: QuoteSize
+  className?: string
+}
+
+export function Quote({ quote, attribution, size = 'default', className }: QuoteProps) {
+  return (
+    <figure className={clsx(styles.figure, styles[size], className)}>
+      <blockquote className={styles.quote}>
+        <p>{quote}</p>
+      </blockquote>
+      {attribution ? (
+        <figcaption className={styles.attribution}>
+          {attribution.avatar ? (
+            <img
+              src={attribution.avatar.url}
+              alt={attribution.avatar.alt}
+              className={styles.avatar}
+            />
+          ) : null}
+          <span className={styles.name}>{attribution.name}</span>
+          {attribution.role ? (
+            <span className={styles.role}>{attribution.role}</span>
+          ) : null}
+        </figcaption>
+      ) : null}
+    </figure>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { Quote, type QuoteProps, type QuoteSize } from './Quote.js'
+export { contract as quoteContract } from './Quote.contract.js'

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'