@startsimpli/ui 0.4.92 → 0.4.94

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