@forumone/create-throughline 0.2.1 → 0.3.1

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()
+  })
+})

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

@@ -0,0 +1,39 @@
+import { clsx } from 'clsx'
+import styles from './Stats.module.css'
+
+export interface StatItem {
+  value: string
+  label: string
+  description?: string
+}
+
+export interface StatsProps {
+  eyebrow?: string
+  headline?: string
+  items: StatItem[]
+  className?: string
+}
+
+export function Stats({ eyebrow, headline, items, className }: StatsProps) {
+  return (
+    <section className={clsx(styles.stats, className)}>
+      <div className={styles.container}>
+        {eyebrow ? <p className={styles.eyebrow}>{eyebrow}</p> : null}
+        {headline ? <h2 className={styles.headline}>{headline}</h2> : null}
+        <dl className={clsx(styles.list, styles[`cols-${items.length}`])}>
+          {items.map((item) => (
+            <div key={`${item.value}-${item.label}`} className={styles.item}>
+              <dt className={styles.value}>{item.value}</dt>
+              <dd className={styles.label}>
+                <span className={styles.labelText}>{item.label}</span>
+                {item.description ? (
+                  <span className={styles.description}>{item.description}</span>
+                ) : null}
+              </dd>
+            </div>
+          ))}
+        </dl>
+      </div>
+    </section>
+  )
+}

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

@@ -0,0 +1,2 @@
+export { Stats, type StatsProps, type StatItem } from './Stats.js'
+export { contract as statsContract } from './Stats.contract.js'

package/dist/templates/with-reference-ds/design-system/src/css-modules.d.ts

@@ -0,0 +1,5 @@
+/* eslint-disable import-x/no-default-export -- CSS Modules loaders emit a default export. */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}

package/dist/templates/with-reference-ds/design-system/src/foundations/Colors.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { colors } from '../tokens'
+import { FoundationPage } from './_helpers.tsx'
+
+const meta: Meta = {
+  title: 'Foundations/Colors',
+}
+export default meta
+
+function cssVar(name: string): string {
+  return `--${name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase().replace(/\./g, '-')}`
+}
+
+const groups = ['neutral', 'brand', 'text', 'bg', 'border', 'state']
+
+export const Colors: StoryObj = {
+  render: () => (
+    <FoundationPage
+      title="Colors"
+      intro="The palette is grouped by role: neutral ramp, brand accents, text, background, border, and state. Components read these as CSS custom properties so a brand override re-themes everything without touching component code."
+    >
+      {groups.map((group) => {
+        const entries = Object.entries(colors).filter(([k]) => k.startsWith(`color.${group}.`))
+        if (entries.length === 0) return null
+        return (
+          <section key={group} style={{ marginBottom: '2rem' }}>
+            <h2 style={{ fontSize: 'var(--font-size-lg)', margin: '0 0 0.75rem', textTransform: 'capitalize' }}>
+              {group}
+            </h2>
+            <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(9rem, 1fr))', gap: '0.75rem' }}>
+              {entries.map(([name, value]) => (
+                <div key={name} style={{ border: '1px solid var(--color-border-default)', borderRadius: 'var(--radius-md)', overflow: 'hidden' }}>
+                  <div style={{ height: '3.5rem', background: value }} />
+                  <div style={{ padding: '0.5rem' }}>
+                    <div style={{ fontFamily: 'var(--font-family-mono)', fontSize: 'var(--font-size-xs)' }}>{cssVar(name)}</div>
+                    <div style={{ fontSize: 'var(--font-size-xs)', color: 'var(--color-text-muted)' }}>{value}</div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          </section>
+        )
+      })}
+    </FoundationPage>
+  ),
+}

package/dist/templates/with-reference-ds/design-system/src/foundations/Elevation.stories.tsx

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { FoundationPage } from './_helpers.tsx'
+
+const meta: Meta = {
+  title: 'Foundations/Elevation',
+}
+export default meta
+
+export const Elevation: StoryObj = {
+  render: () => (
+    <FoundationPage
+      title="Elevation"
+      intro="The reference design system uses flat depth: elevation is expressed through 1px borders and surface-color shifts rather than drop shadows. Reserve real shadows for transient overlays (modals, popovers)."
+    >
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(12rem, 1fr))', gap: '1rem' }}>
+        <div style={{ padding: '1.5rem', background: 'var(--color-bg-primary)', border: '1px solid var(--color-border-default)', borderRadius: 'var(--radius-lg)' }}>
+          <strong>Surface</strong>
+          <p style={{ margin: '0.5rem 0 0', color: 'var(--color-text-secondary)', fontSize: 'var(--font-size-sm)' }}>
+            bg.primary + border.default
+          </p>
+        </div>
+        <div style={{ padding: '1.5rem', background: 'var(--color-bg-secondary)', border: '1px solid var(--color-border-strong)', borderRadius: 'var(--radius-lg)' }}>
+          <strong>Raised</strong>
+          <p style={{ margin: '0.5rem 0 0', color: 'var(--color-text-secondary)', fontSize: 'var(--font-size-sm)' }}>
+            bg.secondary + border.strong
+          </p>
+        </div>
+        <div style={{ padding: '1.5rem', background: 'var(--color-bg-primary)', border: '1px solid var(--color-border-default)', borderRadius: 'var(--radius-lg)', boxShadow: '0 8px 24px rgba(0,0,0,0.12)' }}>
+          <strong>Overlay</strong>
+          <p style={{ margin: '0.5rem 0 0', color: 'var(--color-text-secondary)', fontSize: 'var(--font-size-sm)' }}>
+            shadow — modals / popovers only
+          </p>
+        </div>
+      </div>
+    </FoundationPage>
+  ),
+}

package/dist/templates/with-reference-ds/design-system/src/foundations/LayoutContainers.stories.tsx

@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { layout } from '../tokens'
+import { FoundationPage, TokenTable } from './_helpers.tsx'
+
+const meta: Meta = {
+  title: 'Foundations/Layout & Containers',
+}
+export default meta
+
+/** Token name → CSS custom property (mirrors build-tokens-css). */
+function cssVar(name: string): string {
+  return `--${name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase().replace(/\./g, '-')}`
+}
+
+const containers = Object.entries(layout).filter(([k]) => k.startsWith('layout.container.'))
+const breakpoints = Object.entries(layout).filter(([k]) => k.startsWith('layout.breakpoint.'))
+const gutter = layout['layout.gutter']
+const margin = layout['layout.margin']
+
+export const LayoutAndContainers: StoryObj = {
+  render: () => (
+    <FoundationPage
+      title="Layout & Containers"
+      intro="Page content constrains to one of a small set of max-widths. The gutter is the space between grid columns; the page margin is the breathing room between the container and the viewport edge. Breakpoints are min-width and progressively widen the layout."
+    >
+      <h2 style={{ fontSize: 'var(--font-size-xl)', margin: '0 0 1rem' }}>Container widths</h2>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', marginBottom: '2.5rem' }}>
+        {containers.map(([name, value]) => (
+          <div key={name}>
+            <div
+              style={{
+                fontFamily: 'var(--font-family-mono)',
+                fontSize: 'var(--font-size-xs)',
+                color: 'var(--color-text-secondary)',
+                marginBottom: '0.25rem',
+              }}
+            >
+              {cssVar(name)} · {value}
+            </div>
+            <div
+              style={{
+                height: '2rem',
+                width: `min(100%, ${value})`,
+                background: 'var(--color-brand-primary)',
+                borderRadius: 'var(--radius-sm)',
+              }}
+            />
+          </div>
+        ))}
+      </div>
+
+      <h2 style={{ fontSize: 'var(--font-size-xl)', margin: '0 0 1rem' }}>Gutter & page margin</h2>
+      <TokenTable
+        rows={[
+          {
+            name: cssVar('layout.gutter'),
+            value: gutter,
+            preview: <div style={{ height: '1rem', width: gutter, background: 'var(--color-brand-secondary)' }} />,
+          },
+          {
+            name: cssVar('layout.margin'),
+            value: margin,
+            preview: <div style={{ height: '1rem', width: margin, background: 'var(--color-brand-secondary)' }} />,
+          },
+        ]}
+      />
+
+      <h2 style={{ fontSize: 'var(--font-size-xl)', margin: '2.5rem 0 1rem' }}>Breakpoints</h2>
+      <TokenTable
+        rows={breakpoints.map(([name, value]) => ({
+          name: cssVar(name),
+          value,
+          preview: (
+            <div
+              style={{
+                height: '0.5rem',
+                width: `min(100%, calc(${value} / 4))`,
+                background: 'var(--color-border-strong)',
+              }}
+            />
+          ),
+        }))}
+      />
+    </FoundationPage>
+  ),
+}

package/dist/templates/with-reference-ds/design-system/src/foundations/Radii.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { radii } from '../tokens'
+import { FoundationPage } from './_helpers.tsx'
+
+const meta: Meta = {
+  title: 'Foundations/Radii',
+}
+export default meta
+
+function cssVar(name: string): string {
+  return `--${name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase().replace(/\./g, '-')}`
+}
+
+export const Radii: StoryObj = {
+  render: () => (
+    <FoundationPage
+      title="Radii"
+      intro="Corner radii available to components. A brand may collapse this to a binary set (sharp vs. pill); the tokens stay the same so components don't change."
+    >
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(10rem, 1fr))', gap: '1rem' }}>
+        {Object.entries(radii).map(([name, value]) => (
+          <div key={name}>
+            <div
+              style={{
+                height: '5rem',
+                background: 'var(--color-bg-tertiary)',
+                border: '1px solid var(--color-border-strong)',
+                borderRadius: value,
+              }}
+            />
+            <div style={{ fontFamily: 'var(--font-family-mono)', fontSize: 'var(--font-size-xs)', marginTop: '0.5rem' }}>{cssVar(name)}</div>
+            <div style={{ fontSize: 'var(--font-size-xs)', color: 'var(--color-text-muted)' }}>{value}</div>
+          </div>
+        ))}
+      </div>
+    </FoundationPage>
+  ),
+}

package/dist/templates/with-reference-ds/design-system/src/foundations/Spacing.stories.tsx

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { spacing } from '../tokens'
+import { FoundationPage } from './_helpers.tsx'
+
+const meta: Meta = {
+  title: 'Foundations/Spacing',
+}
+export default meta
+
+function cssVar(name: string): string {
+  return `--${name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase().replace(/\./g, '-')}`
+}
+
+export const Spacing: StoryObj = {
+  render: () => (
+    <FoundationPage
+      title="Spacing"
+      intro="A single spacing scale drives padding, margins, and gaps. Section and container spacing are semantic aliases on top of the numeric scale."
+    >
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
+        {Object.entries(spacing).map(([name, value]) => (
+          <div key={name} style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>
+            <span style={{ fontFamily: 'var(--font-family-mono)', fontSize: 'var(--font-size-xs)', color: 'var(--color-text-muted)', width: '11rem', flexShrink: 0 }}>
+              {cssVar(name)}
+            </span>
+            <span style={{ fontSize: 'var(--font-size-xs)', color: 'var(--color-text-secondary)', width: '4rem', flexShrink: 0 }}>{value}</span>
+            <div style={{ height: '1rem', width: value, background: 'var(--color-brand-primary)', borderRadius: 'var(--radius-sm)' }} />
+          </div>
+        ))}
+      </div>
+    </FoundationPage>
+  ),
+}

package/dist/templates/with-reference-ds/design-system/src/foundations/Typography.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { typography } from '../tokens'
+import { FoundationPage, TokenTable } from './_helpers.tsx'
+
+const meta: Meta = {
+  title: 'Foundations/Typography',
+}
+export default meta
+
+function cssVar(name: string): string {
+  return `--${name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase().replace(/\./g, '-')}`
+}
+
+const sizes = Object.entries(typography).filter(([k]) => k.startsWith('font.size.'))
+const families = Object.entries(typography).filter(([k]) => k.startsWith('font.family.'))
+const weights = Object.entries(typography).filter(([k]) => k.startsWith('font.weight.'))
+
+export const Typography: StoryObj = {
+  render: () => (
+    <FoundationPage
+      title="Typography"
+      intro="Type sizes form a single scale; hierarchy comes from size and weight, not from mixing typefaces. The font family is a token, so a brand swap (e.g. DM Sans) re-themes every component."
+    >
+      <h2 style={{ fontSize: 'var(--font-size-xl)', margin: '0 0 1rem' }}>Type scale</h2>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem', marginBottom: '2.5rem' }}>
+        {sizes.map(([name, value]) => (
+          <div key={name} style={{ display: 'flex', alignItems: 'baseline', gap: '1rem' }}>
+            <span style={{ fontFamily: 'var(--font-family-mono)', fontSize: 'var(--font-size-xs)', color: 'var(--color-text-muted)', width: '8rem', flexShrink: 0 }}>
+              {cssVar(name)}
+            </span>
+            <span style={{ fontSize: value, lineHeight: 1.1 }}>The quick brown fox</span>
+          </div>
+        ))}
+      </div>
+
+      <h2 style={{ fontSize: 'var(--font-size-xl)', margin: '0 0 1rem' }}>Families</h2>
+      <TokenTable
+        rows={families.map(([name, value]) => ({
+          name: cssVar(name),
+          value,
+          preview: <span style={{ fontFamily: value }}>Aa Bb Cc 123</span>,
+        }))}
+      />
+
+      <h2 style={{ fontSize: 'var(--font-size-xl)', margin: '2.5rem 0 1rem' }}>Weights</h2>
+      <TokenTable
+        rows={weights.map(([name, value]) => ({
+          name: cssVar(name),
+          value,
+          preview: <span style={{ fontWeight: value as number }}>The quick brown fox</span>,
+        }))}
+      />
+    </FoundationPage>
+  ),
+}