@startsimpli/ui 0.4.92 → 0.4.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.92",
+  "version": "0.4.93",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -44,9 +44,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/api": "^0.5.54",
     "@startsimpli/auth": "^0.4.34",
-    "@startsimpli/i18n": "^0.1.1",
-    "@startsimpli/api": "^0.5.54"
+    "@startsimpli/i18n": "^0.1.1"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/dashboard/DashboardSection.tsx

@@ -1,4 +1,6 @@
 import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { TYPE_SCALE } from '../../theme/type-scale'
 
 export interface DashboardSectionProps {
   title: string
@@ -16,12 +18,17 @@ export function DashboardSection({
   className = '',
 }: DashboardSectionProps) {
   return (
-    <div className={`space-y-4 ${className}`}>
-      <div className="flex items-start justify-between">
+    <div className={cn('space-y-4', className)}>
+      <div className="flex items-start justify-between gap-4">
         <div>
-          <h2 className="text-lg font-semibold text-gray-900">{title}</h2>
+          {/* `heading` is the section step of the type scale; the colour comes
+              from the theme, so this reads on a dark tenant as well as a light
+              one. `text-gray-900`/`text-gray-600` used to hard-code light. */}
+          <h2 className={cn(TYPE_SCALE.heading, 'text-foreground')}>{title}</h2>
           {description && (
-            <p className="text-sm text-gray-600 mt-1">{description}</p>
+            <p className={cn(TYPE_SCALE.muted, 'mt-1 text-muted-foreground')}>
+              {description}
+            </p>
           )}
         </div>
         {action && <div className="flex-shrink-0">{action}</div>}

package/src/components/dashboard/MetricCard.tsx

@@ -36,7 +36,10 @@ export function MetricCard({
   const content = (
     <div
       className={cn(
-        'rounded-xl border bg-card text-card-foreground shadow p-6 transition-all duration-200 hover:shadow-lg cursor-pointer',
+        // `border` on its own resolves to currentColor in Tailwind v4 — on a
+        // card that sets text-card-foreground that draws a near-black outline
+        // in light mode and a glaring pale one on a dark tenant. Name the token.
+        'rounded-xl border border-border bg-card text-card-foreground shadow p-6 transition-all duration-200 hover:shadow-lg cursor-pointer',
         error && 'border-red-200 bg-red-50',
         isLoading && 'animate-pulse',
         className,

package/src/components/unified-table/__tests__/components/TablePagination.test.tsx

@@ -316,18 +316,75 @@ describe('TablePagination', () => {
     })
   })
 
-  describe('Edge Cases', () => {
-    it('should handle zero total count', () => {
-      const pagination = createMockPagination({
+  // An empty table has nothing to count. Every number on this line is either
+  // wrong or noise, so the line becomes a sentence instead of arithmetic.
+  describe('Empty result set', () => {
+    const emptyPagination = (overrides?: Partial<UsePaginationReturn>) =>
+      createMockPagination({
         totalCount: 0,
         totalPages: 1,
+        canGoNext: false,
+        canGoPrevious: false,
         getDisplayRange: jest.fn(() => ({ start: 0, end: 0 })),
+        ...overrides,
       })
-      render(<TablePagination pagination={pagination} />)
 
-      expect(screen.getByText(/0-0/)).toBeInTheDocument()
+    it('states that there is nothing rather than printing a range', () => {
+      const { container } = render(
+        <TablePagination pagination={emptyPagination()} totalFilteredCount={0} />
+      )
+
+      const countLine = container.querySelector('.text-muted-foreground')
+      expect(countLine?.textContent).toBe('No items')
+    })
+
+    it('never prints a range whose start is past its end', () => {
+      const { container } = render(
+        <TablePagination
+          pagination={emptyPagination({
+            // What the unfixed hook hands the component on an empty table.
+            getDisplayRange: jest.fn(() => ({ start: 1, end: 0 })),
+          })}
+        />
+      )
+
+      expect(container.textContent).not.toContain('1-0')
+    })
+
+    it('does not leak a stray 0 out of the filtered-count guard', () => {
+      // `{count && <span/>}` renders the NUMBER 0 when count is 0 — that is the
+      // second 0 in "of 00".
+      const { container } = render(
+        <TablePagination pagination={emptyPagination()} totalFilteredCount={0} />
+      )
+
+      expect(container.textContent).not.toMatch(/00/)
+      expect(container.textContent).toBe('No items')
+    })
+
+    it('does not leak a stray 0 out of the select-all guard', () => {
+      const { container } = render(
+        <TablePagination
+          pagination={emptyPagination()}
+          showSelectAllPrompt
+          onSelectAllPages={jest.fn()}
+          totalFilteredCount={0}
+        />
+      )
+
+      expect(container.textContent).toBe('No items')
+      expect(screen.queryByText(/Select all/)).not.toBeInTheDocument()
     })
 
+    it('hides page controls when there is nothing to page through', () => {
+      render(<TablePagination pagination={emptyPagination()} />)
+
+      expect(screen.queryByTitle('First page')).not.toBeInTheDocument()
+      expect(screen.queryByTitle('Next page')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Edge Cases', () => {
     it('should handle single item', () => {
       const pagination = createMockPagination({
         totalCount: 1,

package/src/components/unified-table/__tests__/hooks/usePagination.test.ts

@@ -341,6 +341,28 @@ describe('usePagination', () => {
       const range = result.current.getDisplayRange()
       expect(range).toEqual({ start: 51, end: 75 })
     })
+
+    it('should report an empty range when there are no rows at all', () => {
+      const { result } = renderHook(() =>
+        usePagination({ ...defaultProps, totalCount: 0 })
+      )
+
+      // A range that begins at 1 and ends at 0 describes nothing; it is the
+      // arithmetic leaking out. Nothing shown means nothing on both ends.
+      const range = result.current.getDisplayRange()
+      expect(range).toEqual({ start: 0, end: 0 })
+      expect(range.start).not.toBeGreaterThan(range.end)
+    })
+
+    it('should report an empty range when the page sits past the last row', () => {
+      // Server-side counts shrink under a page that is already open (rule 8:
+      // the count comes from the server, the client never recounts).
+      const { result } = renderHook(() =>
+        usePagination({ ...defaultProps, totalCount: 10, initialPage: 2 })
+      )
+
+      expect(result.current.getDisplayRange()).toEqual({ start: 0, end: 0 })
+    })
   })
 
   describe('Server-Side Pagination', () => {

package/src/components/unified-table/__tests__/utils/border-tokens.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Every border in the table names its colour (startsim-768w.35.2.4).
+ *
+ * In Tailwind v4 a bare `border` / `border-b` sets a width and leaves the
+ * colour at `currentColor`, so the rule is painted in the TEXT colour of
+ * whatever it sits in. It is quiet on a white page — the rows just look heavier
+ * than intended — and loud on a dark tenant, where every row separator turns
+ * near-white. Browser-confirmed on both surfaces before this guard existed.
+ *
+ * The fix is always the same: say `border-border` (or a token shade like
+ * `border-border/50`) next to the width utility.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+const TABLE_SRC = path.resolve(__dirname, '../..')
+
+/** `border`, `border-t`, `border-x` — width with no colour. */
+const BARE_BORDER = /^border(-[trblxy])?$/
+/** Anything that names a colour: `border-border`, `border-primary`, `border-[#fff]`. */
+const NAMED_COLOR = /^([a-z-]+:)*border-(?!\d|[trblxy]$)/
+
+function sourceFiles(dir: string, acc: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__' || entry.name === 'node_modules') continue
+      sourceFiles(full, acc)
+    } else if (/\.tsx?$/.test(entry.name)) {
+      acc.push(full)
+    }
+  }
+  return acc
+}
+
+function offenders(): string[] {
+  const found: string[] = []
+  for (const file of sourceFiles(TABLE_SRC)) {
+    fs.readFileSync(file, 'utf8')
+      .split('\n')
+      .forEach((rawLine, i) => {
+        // Prose in a doc comment may legitimately name the banned class.
+        const line = rawLine.replace(/^\s*(\/\/|\/\*|\*).*$/, '')
+        for (const quoted of line.match(/'[^']*'|"[^"]*"|`[^`]*`/g) ?? []) {
+          const tokens = quoted.slice(1, -1).split(/\s+/)
+          const bare = tokens.filter((t) => BARE_BORDER.test(t))
+          if (!bare.length) continue
+          if (tokens.some((t) => NAMED_COLOR.test(t))) continue
+          found.push(`${path.relative(TABLE_SRC, file)}:${i + 1} ${bare.join(' ')}`)
+        }
+      })
+  }
+  return found
+}
+
+describe('unified-table borders are theme-coloured, not currentColor', () => {
+  it('no border utility ships without a colour token beside it', () => {
+    expect(offenders()).toEqual([])
+  })
+})

package/src/components/unified-table/components/BulkActionBar/index.tsx

@@ -54,7 +54,7 @@ export function BulkActionBar({
       )}
       aria-hidden={!isVisible}
     >
-      <div className="flex items-center gap-2 p-3 bg-muted/50 rounded-lg border">
+      <div className="flex items-center gap-2 p-3 bg-muted/50 rounded-lg border border-border">
         {/* Selection summary */}
         <div className="flex items-center gap-2 text-sm font-medium">
           {selectAllPages ? (

package/src/components/unified-table/components/DataTableCore/index.tsx

@@ -330,7 +330,7 @@ export function DataTableCore<TData>({
   return (
     // overflow-x-auto: a wide table scrolls horizontally inside its own border
     // instead of overflowing the page to the right (startsim column-overflow).
-    <div className={cn('rounded-md border overflow-x-auto', className)}>
+    <div className={cn('rounded-md border border-border overflow-x-auto', className)}>
       <Table>
         {renderColumnHeaders()}
 

package/src/components/unified-table/components/MobileView/Card.tsx

@@ -186,7 +186,7 @@ export function Card<TData = any>({
             )}
 
             {secondaryFields && secondaryFields.length > 0 && (
-              <div className="border-t pt-3">
+              <div className="border-t border-border pt-3">
                 <div className="grid grid-cols-2 gap-3">
                   {secondaryFields.map((field) => (
                     <div

package/src/components/unified-table/components/TableFilters/index.tsx

@@ -157,7 +157,7 @@ export function TableFilters({ config, filters, className, defaultExpanded = fal
     const isExpanded = expandedSections.has(section.id)
 
     return (
-      <div key={section.id} className="border rounded-lg p-3">
+      <div key={section.id} className="border border-border rounded-lg p-3">
         <Button
           variant="ghost"
           size="sm"
@@ -214,7 +214,7 @@ export function TableFilters({ config, filters, className, defaultExpanded = fal
   const activeFilterCount = filters.getActiveFilterCount()
 
   return (
-    <div className={cn('rounded-lg border bg-muted/30', className)}>
+    <div className={cn('rounded-lg border border-border bg-muted/30', className)}>
       {/* Collapsible Header */}
       <button
         type="button"

package/src/components/unified-table/components/TablePagination/index.tsx

@@ -37,15 +37,29 @@ export function TablePagination({
   const { start, end } = getDisplayRange()
   const pageNumbers = getPageNumbers()
 
+  // Nothing to count: a range would read "1-0 of 0". Say it in words instead.
+  const isEmpty = totalCount <= 0 || end < start || end <= 0
+  // `count && <jsx/>` renders the NUMBER 0 when count is 0 — compare explicitly.
+  const showFilteredNote =
+    totalFilteredCount != null && totalFilteredCount !== totalCount
+  const showSelectAll =
+    Boolean(showSelectAllPrompt) &&
+    Boolean(onSelectAllPages) &&
+    (totalFilteredCount ?? 0) > end
+
   return (
     <div className={className}>
       <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
         {/* Item count display */}
         <div className="text-sm text-muted-foreground">
-          Showing <span className="font-medium">{start}-{end}</span> of{' '}
-          <span className="font-medium">{totalCount}</span>
-          {totalFilteredCount && totalFilteredCount !== totalCount && (
-            <span> filtered items</span>
+          {isEmpty ? (
+            'No items'
+          ) : (
+            <>
+              Showing <span className="font-medium">{start}-{end}</span> of{' '}
+              <span className="font-medium">{totalCount}</span>
+              {showFilteredNote && <span> filtered items</span>}
+            </>
           )}
         </div>
 
@@ -137,7 +151,7 @@ export function TablePagination({
       </div>
 
       {/* Select all pages prompt */}
-      {showSelectAllPrompt && onSelectAllPages && totalFilteredCount && totalFilteredCount > end && (
+      {showSelectAll && (
         <div className="mt-3 flex items-center justify-center p-3 bg-blue-50 border border-blue-200 rounded-lg">
           <span className="text-sm text-blue-900 mr-2">
             Select all <span className="font-semibold">{totalFilteredCount}</span> items?

package/src/components/unified-table/hooks/usePagination.ts

@@ -97,9 +97,21 @@ export function usePagination({
     return pages
   }, [currentPage, totalPages])
 
+  /**
+   * The 1-based span of rows on screen, or `{ start: 0, end: 0 }` when there is
+   * no span to describe. `totalCount` is whatever the server reported, so it can
+   * legitimately be 0, or drop below the page the user already has open — both
+   * cases used to produce a backwards range like `1-0`.
+   */
   const getDisplayRange = useCallback(() => {
+    if (totalCount <= 0) return { start: 0, end: 0 }
+
     const start = (currentPage - 1) * pageSize + 1
     const end = Math.min(currentPage * pageSize, totalCount)
+
+    // The page begins past the last row: nothing is shown here.
+    if (start > end) return { start: 0, end: 0 }
+
     return { start, end }
   }, [currentPage, pageSize, totalCount])
 

package/src/components/unified-table/utils/themes.ts

@@ -15,19 +15,22 @@ export interface TableTheme {
   mobileCardContent: string
 }
 
+// Every rule here names its border colour. A bare `border` / `border-b` takes
+// currentColor in Tailwind v4, which paints table rules in the TEXT colour —
+// near-black rows on a light page, glaring pale rows on a dark tenant.
 export const defaultTheme: TableTheme = {
   name: 'default',
   container: 'w-full',
   header: 'bg-muted/50',
   headerCell: 'px-4 py-3 text-left text-sm font-medium text-muted-foreground',
   body: '',
-  row: 'border-b transition-colors',
+  row: 'border-b border-border transition-colors',
   rowHover: 'hover:bg-muted/50',
   rowSelected: 'bg-primary/10 border-primary',
   cell: 'px-4 py-3 text-sm',
-  pagination: 'flex items-center justify-between px-4 py-3 border-t',
+  pagination: 'flex items-center justify-between px-4 py-3 border-t border-border',
   emptyState: 'flex items-center justify-center py-12 text-muted-foreground',
-  mobileCard: 'rounded-lg border bg-card shadow-sm',
+  mobileCard: 'rounded-lg border border-border bg-card shadow-sm',
   mobileCardHeader: 'p-4 pb-2',
   mobileCardContent: 'p-4 pt-2',
 }
@@ -37,7 +40,7 @@ export const compactTheme: TableTheme = {
   name: 'compact',
   headerCell: 'px-2 py-2 text-left text-xs font-medium text-muted-foreground',
   cell: 'px-2 py-2 text-xs',
-  pagination: 'flex items-center justify-between px-2 py-2 border-t',
+  pagination: 'flex items-center justify-between px-2 py-2 border-t border-border',
   mobileCardHeader: 'p-3 pb-1',
   mobileCardContent: 'p-3 pt-1',
 }
@@ -47,7 +50,7 @@ export const spaciousTheme: TableTheme = {
   name: 'spacious',
   headerCell: 'px-6 py-4 text-left text-sm font-medium text-muted-foreground',
   cell: 'px-6 py-4 text-sm',
-  pagination: 'flex items-center justify-between px-6 py-4 border-t',
+  pagination: 'flex items-center justify-between px-6 py-4 border-t border-border',
   mobileCardHeader: 'p-6 pb-3',
   mobileCardContent: 'p-6 pt-3',
 }

package/src/theme/__tests__/type-scale.test.tsx

@@ -0,0 +1,145 @@
+/**
+ * The type scale is a contract, so it gets tested like one (startsim-768w.35.2.4).
+ *
+ * Two things went wrong without it:
+ *   1. Every consumer picked sizes by hand. 77% of one app's text landed on
+ *      `text-sm` or `text-xs` — two ADJACENT steps — so a card title and its
+ *      body were 1.5px apart and the hierarchy read as flat.
+ *   2. DashboardSection hard-coded `text-gray-900` / `text-gray-600`, which is
+ *      invisible-adjacent on a dark tenant. Apps hand-rolled their own headings
+ *      rather than use it, which is how you end up with nineteen loose <h2>s.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { render, screen } from '@testing-library/react'
+import {
+  TYPE_SCALE,
+  TYPE_SCALE_ORDER,
+  TYPE_SCALE_DEFAULTS,
+  TYPE_SCALE_TOKENS,
+  typeClass,
+} from '../type-scale'
+import { THEME_TOKENS } from '../contract'
+import { DashboardSection } from '../../components/dashboard/DashboardSection'
+
+const CONTRACT_CSS = fs.readFileSync(
+  path.resolve(__dirname, '../../../theme/contract.css'),
+  'utf8',
+)
+
+describe('the type scale is a real contract', () => {
+  it('names every role in packages/ui/theme/contract.css', () => {
+    const missing = TYPE_SCALE_TOKENS.filter(
+      (token) => !new RegExp(`${token}\\s*:`).test(CONTRACT_CSS),
+    )
+    expect(missing).toEqual([])
+  })
+
+  it('is listed in THEME_TOKENS so apps can enumerate what they must define', () => {
+    expect(THEME_TOKENS.typeScale).toEqual(TYPE_SCALE_TOKENS)
+  })
+
+  it('drives every role off a CSS variable, so one override reshapes the estate', () => {
+    for (const role of TYPE_SCALE_ORDER) {
+      expect(TYPE_SCALE[role]).toMatch(/text-\[length:var\(--text-[a-z-]+-size,/)
+      expect(TYPE_SCALE[role]).toMatch(/leading-\[var\(--text-[a-z-]+-leading,/)
+    }
+  })
+
+  it('carries a fallback in every variable, so a component still renders in an app that has not adopted the contract', () => {
+    for (const role of TYPE_SCALE_ORDER) {
+      // var(--x) with no comma is the failure mode: the utility computes to
+      // nothing and the text falls back to the browser default.
+      expect(TYPE_SCALE[role]).not.toMatch(/var\(--text-[a-z-]+-(size|leading)\)/)
+    }
+  })
+
+  it('gives every role its own size — no two steps land on the same number', () => {
+    const sizes = TYPE_SCALE_ORDER.map((role) => TYPE_SCALE_DEFAULTS[role])
+    expect(new Set(sizes).size).toBe(sizes.length)
+  })
+
+  it('keeps adjacent steps far enough apart to be seen as different', () => {
+    const sizes = TYPE_SCALE_ORDER.map((role) => TYPE_SCALE_DEFAULTS[role])
+    for (let i = 1; i < sizes.length; i++) {
+      expect(sizes[i]).toBeLessThan(sizes[i - 1])
+      // The original defect was a card title 1.5px larger than its own body —
+      // a difference nobody can see. 0.125rem (2px) is the floor.
+      expect(sizes[i - 1] - sizes[i]).toBeGreaterThanOrEqual(0.125)
+    }
+  })
+
+  it('spans a wide enough range that a headline cannot be mistaken for body copy', () => {
+    expect(TYPE_SCALE_DEFAULTS.display / TYPE_SCALE_DEFAULTS.body).toBeGreaterThanOrEqual(3)
+  })
+
+  it('sets size and weight only — colour stays a theme decision', () => {
+    for (const role of TYPE_SCALE_ORDER) {
+      expect(TYPE_SCALE[role]).not.toMatch(/(^|\s)text-(gray|slate|zinc|neutral|stone|foreground)/)
+    }
+  })
+
+  it('exposes the roles through a helper for dynamic call sites', () => {
+    expect(typeClass('heading')).toBe(TYPE_SCALE.heading)
+  })
+})
+
+describe('DashboardSection is theme-driven, not light-locked', () => {
+  const classesOf = (el: Element | null | undefined) =>
+    (el?.getAttribute('class') ?? '').split(/\s+/)
+
+  it('renders the title on the heading step of the scale', () => {
+    render(<DashboardSection title="Overview"><div /></DashboardSection>)
+    const heading = screen.getByRole('heading', { level: 2, name: 'Overview' })
+
+    for (const cls of TYPE_SCALE.heading.split(/\s+/)) {
+      expect(heading).toHaveClass(cls)
+    }
+  })
+
+  it('renders the description on the muted step of the scale', () => {
+    render(
+      <DashboardSection title="Overview" description="Last 28 days">
+        <div />
+      </DashboardSection>,
+    )
+    const description = screen.getByText('Last 28 days')
+
+    for (const cls of TYPE_SCALE.muted.split(/\s+/)) {
+      expect(description).toHaveClass(cls)
+    }
+  })
+
+  it('colours text with theme tokens so it reads on a dark tenant', () => {
+    const { container } = render(
+      <DashboardSection title="Overview" description="Last 28 days">
+        <div />
+      </DashboardSection>,
+    )
+
+    expect(screen.getByRole('heading', { level: 2 })).toHaveClass('text-foreground')
+    expect(screen.getByText('Last 28 days')).toHaveClass('text-muted-foreground')
+
+    // No `gray-*` / `bg-white` anywhere in the subtree — those ignore the theme.
+    const offenders = Array.from(container.querySelectorAll('*'))
+      .flatMap((el) => classesOf(el))
+      .filter((cls) => /^(bg|text|border|divide|ring)-(gray|slate|zinc|neutral|stone)-\d{2,3}$|^bg-white$/.test(cls))
+    expect(offenders).toEqual([])
+  })
+
+  it('never draws a bare `border`, which is currentColor in Tailwind v4', () => {
+    const { container } = render(
+      <DashboardSection title="Overview" action={<button>Export</button>}>
+        <div />
+      </DashboardSection>,
+    )
+
+    for (const el of Array.from(container.querySelectorAll('*'))) {
+      const classes = classesOf(el)
+      const bare = classes.filter((c) => /^border(-[trblxy])?$/.test(c))
+      if (!bare.length) continue
+      expect(classes.some((c) => c.startsWith('border-') && !/^border-[trblxy]$/.test(c))).toBe(true)
+    }
+  })
+})

package/src/theme/contract.ts

@@ -1,3 +1,5 @@
+import { TYPE_SCALE_TOKENS } from './type-scale'
+
 /** All CSS custom property names that apps must define in their theme */
 export const THEME_TOKENS = {
   colors: [
@@ -33,6 +35,8 @@ export const THEME_TOKENS = {
   ],
   shadows: ['--shadow-sm', '--shadow-md', '--shadow-lg', '--shadow-xl'],
   typography: ['--font-sans', '--font-mono', '--font-heading'],
+  // The type scale — see ./type-scale.ts for the roles these size.
+  typeScale: TYPE_SCALE_TOKENS,
   animation: ['--duration-fast', '--duration-normal', '--duration-slow', '--easing-default'],
   borders: ['--border-width'],
 } as const
@@ -44,5 +48,6 @@ export type ThemeToken =
   | ThemeShapeTokens
   | (typeof THEME_TOKENS.shadows)[number]
   | (typeof THEME_TOKENS.typography)[number]
+  | (typeof THEME_TOKENS.typeScale)[number]
   | (typeof THEME_TOKENS.animation)[number]
   | (typeof THEME_TOKENS.borders)[number]

package/src/theme/index.ts

@@ -7,3 +7,13 @@ export { default as tailwindPreset } from './tailwind.preset'
 // Design token contract — all CSS variables apps must define
 export { THEME_TOKENS } from './contract'
 export type { ThemeColorTokens, ThemeShapeTokens, ThemeToken } from './contract'
+
+// Type scale — the named roles every text size in the estate comes from
+export {
+  TYPE_SCALE,
+  TYPE_SCALE_ORDER,
+  TYPE_SCALE_DEFAULTS,
+  TYPE_SCALE_TOKENS,
+  typeClass,
+} from './type-scale'
+export type { TypeScaleRole, TypeScaleToken } from './type-scale'

package/src/theme/type-scale.ts

@@ -0,0 +1,119 @@
+/**
+ * The type scale — packages/ui's contract for how big text is.
+ *
+ * Before this existed, every consumer picked font sizes by hand and the ladder
+ * collapsed: across one app 77% of all text was `text-sm` or `text-xs`, two
+ * ADJACENT steps, so a card title and its body differed by 1.5px and were told
+ * apart only by weight. The same "big number" was rendered at seven different
+ * sizes on seven screens because there was no rule to point at.
+ *
+ * There are seven roles, named for the job the text does, not for its size.
+ * Pick the role; the scale picks the pixels. The ladder is a deliberate 4:1
+ * from `display` down to `caption`, so any two adjacent roles are visibly
+ * different — that is the whole point.
+ *
+ *   display    48px / 800   the one hero figure on a screen
+ *   stat       32px / 800   a metric's value in a tile
+ *   heading    20px / 700   a section header
+ *   cardTitle  18px / 600   the name of a card
+ *   body       16px / 400   prose and table cells
+ *   muted      14px / 400   supporting copy under a title
+ *   caption    12px / 400   labels, kickers, timestamps
+ *
+ * Mirrors packages/ui-native/src/tokens.ts + styles.ts, so a screen reads the
+ * same on web and iOS.
+ *
+ * SIZE and LINE-HEIGHT come from CSS variables (packages/ui/theme/contract.css),
+ * so an app reshapes the whole estate by overriding seven numbers — the same way
+ * `--radius` reshapes every corner. Each utility carries the default inline as a
+ * `var()` fallback, so a component still renders correctly in an app that has
+ * not adopted the contract file.
+ *
+ * WEIGHT and TRACKING are fixed per role, deliberately. They are what makes a
+ * role recognisable; an app that wants a lighter heading wants a different
+ * design, not a different token.
+ *
+ * Usage:
+ *   import { TYPE_SCALE } from '@startsimpli/ui/theme'
+ *   <h2 className={cn(TYPE_SCALE.heading, 'text-foreground')}>{title}</h2>
+ *
+ * The scale sets size/weight/leading only. COLOUR stays separate and must come
+ * from a theme token (`text-foreground`, `text-muted-foreground`) — never a
+ * `gray-*` literal, or the component is light-locked and unreadable on a dark
+ * tenant.
+ */
+
+export type TypeScaleRole =
+  | 'display'
+  | 'stat'
+  | 'heading'
+  | 'cardTitle'
+  | 'body'
+  | 'muted'
+  | 'caption'
+
+/** Tailwind utilities for each role. Compose with a colour token. */
+export const TYPE_SCALE: Record<TypeScaleRole, string> = {
+  display:
+    'text-[length:var(--text-display-size,3rem)] leading-[var(--text-display-leading,1.05)] font-extrabold tracking-tight',
+  stat: 'text-[length:var(--text-stat-size,2rem)] leading-[var(--text-stat-leading,1.1)] font-extrabold tracking-tight tabular-nums',
+  heading:
+    'text-[length:var(--text-heading-size,1.25rem)] leading-[var(--text-heading-leading,1.3)] font-bold tracking-tight',
+  cardTitle:
+    'text-[length:var(--text-card-title-size,1.125rem)] leading-[var(--text-card-title-leading,1.4)] font-semibold',
+  body: 'text-[length:var(--text-body-size,1rem)] leading-[var(--text-body-leading,1.5)] font-normal',
+  muted:
+    'text-[length:var(--text-muted-size,0.875rem)] leading-[var(--text-muted-leading,1.5)] font-normal',
+  caption:
+    'text-[length:var(--text-caption-size,0.75rem)] leading-[var(--text-caption-leading,1.4)] font-normal',
+}
+
+/**
+ * The roles in visual order, largest first. Useful for rendering the ladder in
+ * a harness and for tests that assert the steps stay distinct.
+ */
+export const TYPE_SCALE_ORDER: readonly TypeScaleRole[] = [
+  'display',
+  'stat',
+  'heading',
+  'cardTitle',
+  'body',
+  'muted',
+  'caption',
+] as const
+
+/** Default size of each role, in rem — the fallback baked into the utilities. */
+export const TYPE_SCALE_DEFAULTS: Record<TypeScaleRole, number> = {
+  display: 3,
+  stat: 2,
+  heading: 1.25,
+  cardTitle: 1.125,
+  body: 1,
+  muted: 0.875,
+  caption: 0.75,
+}
+
+/** CSS custom properties an app may override to reshape the scale. */
+export const TYPE_SCALE_TOKENS = [
+  '--text-display-size',
+  '--text-display-leading',
+  '--text-stat-size',
+  '--text-stat-leading',
+  '--text-heading-size',
+  '--text-heading-leading',
+  '--text-card-title-size',
+  '--text-card-title-leading',
+  '--text-body-size',
+  '--text-body-leading',
+  '--text-muted-size',
+  '--text-muted-leading',
+  '--text-caption-size',
+  '--text-caption-leading',
+] as const
+
+export type TypeScaleToken = (typeof TYPE_SCALE_TOKENS)[number]
+
+/** `typeClass('heading')` — the utilities for a role, for dynamic call sites. */
+export function typeClass(role: TypeScaleRole): string {
+  return TYPE_SCALE[role]
+}