@forumone/create-throughline 0.2.1 → 0.3.1

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

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

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { MediaBlock } from './MediaBlock.js'
+
+const meta: Meta<typeof MediaBlock> = {
+  title: 'Media Block',
+  component: MediaBlock,
+}
+
+export default meta
+
+type Story = StoryObj<typeof MediaBlock>
+
+export const Image: Story = {
+  args: {
+    media: { type: 'image', url: 'https://placehold.co/1600x900', alt: 'Foundation staff at work' },
+    caption: 'Team members gathered for the annual retreat.',
+  },
+}
+
+export const Square: Story = {
+  args: {
+    aspect: 'square',
+    media: { type: 'image', url: 'https://placehold.co/800x800', alt: 'Portrait' },
+  },
+}
+
+export const Video: Story = {
+  args: {
+    media: {
+      type: 'video',
+      url: 'https://example.com/clip.mp4',
+      poster: 'https://placehold.co/1600x900',
+      ariaLabel: 'Introduction video',
+    },
+    caption: 'A three-minute introduction to the program.',
+  },
+}

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

@@ -0,0 +1,35 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { MediaBlock } from './MediaBlock.js'
+
+describe('MediaBlock', () => {
+  it('renders an image with alt text', () => {
+    render(
+      <MediaBlock media={{ type: 'image', url: '/pic.jpg', alt: 'A picture' }} />,
+    )
+    expect(screen.getByRole('img', { name: 'A picture' })).toHaveAttribute('src', '/pic.jpg')
+  })
+
+  it('renders a caption inside a figcaption when provided', () => {
+    render(
+      <MediaBlock
+        media={{ type: 'image', url: '/pic.jpg', alt: 'x' }}
+        caption="Explanatory caption"
+      />,
+    )
+    const caption = screen.getByText('Explanatory caption')
+    expect(caption.tagName.toLowerCase()).toBe('figcaption')
+  })
+
+  it('renders a video element with aria-label and poster', () => {
+    const { container } = render(
+      <MediaBlock
+        media={{ type: 'video', url: '/clip.mp4', poster: '/poster.jpg', ariaLabel: 'Intro' }}
+      />,
+    )
+    const video = container.querySelector('video')
+    expect(video).not.toBeNull()
+    expect(video).toHaveAttribute('aria-label', 'Intro')
+    expect(video).toHaveAttribute('poster', '/poster.jpg')
+  })
+})

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

@@ -0,0 +1,49 @@
+import { clsx } from 'clsx'
+import styles from './MediaBlock.module.css'
+
+export type MediaBlockAspect = '16:9' | '4:3' | 'square' | 'auto'
+
+type ImageMedia = { type: 'image'; url: string; alt: string }
+type VideoMedia = {
+  type: 'video'
+  url: string
+  poster?: string
+  /** Accessible label used when the video lacks audio/captions narrative context. */
+  ariaLabel?: string
+}
+
+export type MediaBlockMedia = ImageMedia | VideoMedia
+
+export interface MediaBlockProps {
+  media: MediaBlockMedia
+  caption?: string
+  aspect?: MediaBlockAspect
+  className?: string
+}
+
+export function MediaBlock({
+  media,
+  caption,
+  aspect = '16:9',
+  className,
+}: MediaBlockProps) {
+  const aspectKey = aspect === '16:9' ? 'aspect16x9' : aspect === '4:3' ? 'aspect4x3' : `aspect-${aspect}`
+  return (
+    <figure className={clsx(styles.figure, className)}>
+      <div className={clsx(styles.frame, styles[aspectKey])}>
+        {media.type === 'image' ? (
+          <img src={media.url} alt={media.alt} className={styles.media} />
+        ) : (
+          <video
+            src={media.url}
+            poster={media.poster}
+            controls
+            aria-label={media.ariaLabel}
+            className={styles.media}
+          />
+        )}
+      </div>
+      {caption ? <figcaption className={styles.caption}>{caption}</figcaption> : null}
+    </figure>
+  )
+}

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

@@ -0,0 +1,7 @@
+export {
+  MediaBlock,
+  type MediaBlockAspect,
+  type MediaBlockMedia,
+  type MediaBlockProps,
+} from './MediaBlock.js'
+export { contract as mediaBlockContract } from './MediaBlock.contract.js'

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

@@ -0,0 +1,107 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Prose',
+  category: 'section',
+  description:
+    'A typographic container for long-form content — articles, policies, documentation, any flowing prose with headings and lists.',
+  intent:
+    'Wrap free-flowing editorial content with sensible typography defaults (heading hierarchy, paragraph rhythm, list styling, blockquote treatment). Use any time you have a block of content authored as rich text and you want it to read well without styling each element individually.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: [],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'children',
+        type: 'richtext',
+        required: true,
+        constraints:
+          'Rich text content authored in the CMS; can include h2-h4, paragraphs, lists, blockquotes, links',
+      },
+    ],
+    variants: [
+      {
+        name: 'default',
+        description: 'Standard reading rhythm',
+        whenToUse: 'Most articles and editorial content',
+      },
+      {
+        name: 'compact',
+        description: 'Tighter spacing and line height',
+        whenToUse: 'Denser reference content, product docs, or reading-room pages',
+      },
+      {
+        name: 'spacious',
+        description: 'Looser spacing and line height',
+        whenToUse: 'Long-form essays where the reader benefits from breathing room',
+      },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.text.primary',
+      'color.text.secondary',
+      'color.border.strong',
+      'color.brand.primary',
+      'spacing.container',
+      'spacing.10',
+      'spacing.8',
+      'spacing.6',
+      'spacing.5',
+      'spacing.4',
+      'spacing.2',
+      'font.size.3xl',
+      'font.size.2xl',
+      'font.size.xl',
+      'font.size.lg',
+      'font.weight.semibold',
+      'line.height.snug',
+      'line.height.normal',
+      'line.height.relaxed',
+      'line.height.loose',
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Children render as their native semantic HTML (h2, h3, p, ul, ol, blockquote, a). Prose adds no ARIA beyond what the authored content provides.',
+    contentWarnings: [
+      'Author h2 and below inside Prose; never h1 (the page already has one)',
+      'Use real list markup, not paragraphs with bullets',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Standard article body', storyId: 'prose--default' },
+    { label: 'Compact', intent: 'Reference or documentation page', storyId: 'prose--compact' },
+    { label: 'Spacious', intent: 'Long-form essay or manifesto', storyId: 'prose--spacious' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Nesting Prose inside Prose',
+      why: 'Creates duplicate typography scales and unpredictable spacing',
+      useInstead: 'Use a single Prose at the outermost level',
+    },
+    {
+      label: 'Putting interactive components inside Prose',
+      why: 'Prose is for flowing editorial content; components like Stats or CardGrid have their own layout',
+      useInstead: 'Close the Prose, render the component, open another Prose for continuing text',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}

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

@@ -0,0 +1,72 @@
+.prose {
+  max-width: 42rem;
+  margin: 0 auto;
+  padding: 0 var(--spacing-container);
+  color: var(--color-text-primary);
+  line-height: var(--line-height-relaxed);
+}
+
+.prose > * + * {
+  margin-top: var(--spacing-5);
+}
+
+.prose h2 {
+  font-size: var(--font-size-3xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-snug);
+  margin-top: var(--spacing-10);
+}
+
+.prose h3 {
+  font-size: var(--font-size-2xl);
+  font-weight: var(--font-weight-semibold);
+  line-height: var(--line-height-snug);
+  margin-top: var(--spacing-8);
+}
+
+.prose h4 {
+  font-size: var(--font-size-xl);
+  font-weight: var(--font-weight-semibold);
+}
+
+.prose p {
+  font-size: var(--font-size-lg);
+}
+
+.prose a {
+  color: var(--color-brand-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
+.prose ul,
+.prose ol {
+  padding-inline-start: var(--spacing-6);
+}
+
+.prose li + li {
+  margin-top: var(--spacing-2);
+}
+
+.prose blockquote {
+  border-inline-start: 3px solid var(--color-border-strong);
+  padding-inline-start: var(--spacing-4);
+  color: var(--color-text-secondary);
+  font-style: italic;
+}
+
+.compact {
+  line-height: var(--line-height-normal);
+}
+
+.compact > * + * {
+  margin-top: var(--spacing-4);
+}
+
+.spacious {
+  line-height: var(--line-height-loose);
+}
+
+.spacious > * + * {
+  margin-top: var(--spacing-6);
+}

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

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Prose } from './Prose.js'
+
+const meta: Meta<typeof Prose> = {
+  title: 'Prose',
+  component: Prose,
+}
+
+export default meta
+
+type Story = StoryObj<typeof Prose>
+
+const sampleContent = (
+  <>
+    <h2>Why content-first CMSes matter</h2>
+    <p>
+      A content management system should help editorial teams describe the world accurately, not
+      force them into a grid of tiles and buckets. When the CMS models the world well, the rest of
+      the work — rendering, governance, publication — becomes tractable.
+    </p>
+    <h3>The three pillars</h3>
+    <ul>
+      <li>Content models that describe intent, not layout</li>
+      <li>Governance that encodes approval policy</li>
+      <li>Publication that&apos;s reversible and auditable</li>
+    </ul>
+    <blockquote>
+      &ldquo;The best CMS is the one your editors forget they are using.&rdquo;
+    </blockquote>
+    <p>
+      Everything else is detail. The reference design system exists to prove the framework can
+      ship a working, accessible, and accountable editorial experience with just a dozen components.
+    </p>
+  </>
+)
+
+export const Default: Story = { args: { children: sampleContent } }
+export const Compact: Story = { args: { size: 'compact', children: sampleContent } }
+export const Spacious: Story = { args: { size: 'spacious', children: sampleContent } }

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

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { Prose } from './Prose.js'
+
+describe('Prose', () => {
+  it('renders child headings with their native semantics', () => {
+    render(
+      <Prose>
+        <h2>Section</h2>
+        <p>Body</p>
+      </Prose>,
+    )
+    expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent('Section')
+    expect(screen.getByText('Body')).toBeInTheDocument()
+  })
+
+  it('applies size variants', () => {
+    const { container } = render(
+      <Prose size="compact">
+        <p>One</p>
+      </Prose>,
+    )
+    const root = container.firstChild as HTMLElement
+    expect(root.className).toContain('compact')
+  })
+})

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

@@ -0,0 +1,15 @@
+import { clsx } from 'clsx'
+import type { ReactNode } from 'react'
+import styles from './Prose.module.css'
+
+export type ProseSize = 'default' | 'compact' | 'spacious'
+
+export interface ProseProps {
+  children: ReactNode
+  size?: ProseSize
+  className?: string
+}
+
+export function Prose({ children, size = 'default', className }: ProseProps) {
+  return <div className={clsx(styles.prose, styles[size], className)}>{children}</div>
+}

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

@@ -0,0 +1,2 @@
+export { Prose, type ProseProps, type ProseSize } from './Prose.js'
+export { contract as proseContract } from './Prose.contract.js'

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

@@ -0,0 +1,101 @@
+import type { ComponentContract } from '@forumone/throughline-design-contract'
+
+export const contract: ComponentContract = {
+  name: 'Quote',
+  category: 'media',
+  description:
+    'A pullquote or testimonial rendered as a <figure> with a <blockquote> and optional figcaption attribution.',
+  intent:
+    'Surface a single human-scale quotation — a testimonial, a pullquote, a foundational claim. Use sparingly; quotes lose weight when stacked. The attribution is optional because some quotes stand on their own without a named author.',
+
+  composition: {
+    placement: ['section'],
+    maxPerPage: null,
+    requiredSiblings: [],
+    forbiddenAdjacent: ['Quote'],
+  },
+
+  content: {
+    fields: [
+      {
+        name: 'quote',
+        type: 'text',
+        required: true,
+        maxLength: 400,
+        constraints: 'One or two sentences; longer belongs in Prose',
+      },
+      {
+        name: 'attribution',
+        type: 'group',
+        required: false,
+        of: [
+          { name: 'name', type: 'text', required: true, maxLength: 80 },
+          { name: 'role', type: 'text', required: false, maxLength: 100 },
+          { name: 'avatar', type: 'image', required: false },
+        ],
+      },
+    ],
+    variants: [
+      { name: 'default', description: 'Standard size', whenToUse: 'Most testimonials and pullquotes' },
+      { name: 'large', description: 'Oversized display treatment', whenToUse: 'Editorial openers or mission-page quotes that carry real weight' },
+    ],
+  },
+
+  tokens: {
+    consumes: [
+      'color.text.primary',
+      'color.text.secondary',
+      'spacing.10',
+      'spacing.6',
+      'spacing.3',
+      'spacing.container',
+      'font.size.4xl',
+      'font.size.2xl',
+      'font.size.sm',
+      'font.weight.semibold',
+      'line.height.tight',
+      'line.height.snug',
+      'radius.full',
+    ],
+    configurable: [
+      { prop: 'size', tokenGroup: 'layout', allowedValues: ['default', 'large'] },
+    ],
+  },
+
+  accessibility: {
+    keyboardSupport: [],
+    screenReaderBehavior:
+      'Rendered as <figure> containing a <blockquote>; attribution is read as the figcaption. Decorative quotation marks are generated via CSS and are not in the accessible name.',
+    contentWarnings: [
+      'Do not quote someone without permission',
+      'Use their actual words; a paraphrase inside quotation marks misrepresents them',
+    ],
+  },
+
+  examples: [
+    { label: 'Default', intent: 'Testimonial with role', storyId: 'quote--default' },
+    { label: 'With avatar', intent: 'Testimonial with portrait', storyId: 'quote--with-avatar' },
+    { label: 'Large', intent: 'Editorial mission statement', storyId: 'quote--large' },
+    { label: 'Without attribution', intent: 'Aphoristic pullquote', storyId: 'quote--without-attribution' },
+  ],
+
+  antiExamples: [
+    {
+      label: 'Four quotes in a row',
+      why: 'Quote is meant to punctuate content, not fill a page',
+      useInstead: 'Pick the strongest quote; move the rest into Prose or a CardGrid of Cards',
+    },
+    {
+      label: 'Using Quote for product blurbs',
+      why: 'Quote implies a real human author; marketing copy without a source undermines trust',
+      useInstead: 'CTASection or Prose',
+    },
+  ],
+
+  behavior: {
+    fetchesData: false,
+    hasClientState: false,
+    animates: false,
+    requiresAnalytics: false,
+  },
+}