@halogen-ui/tokens 0.1.0

package/src/primitives/scale.ts

@@ -0,0 +1,163 @@
+/**
+ * Halogen — dimensional primitives: space, radius, size, border width, layer.
+ *
+ * Every value here is a decision from the aesthetic direction, not a default.
+ * The gaps in the spacing scale are deliberate: there is no 28, 36, 44 or 56,
+ * because a scale with every value in it is not a scale.
+ */
+
+/**
+ * 4px base. Two sub-step values exist for hairlines and optical nudges only.
+ *
+ * The 2px step is named `half`, not `0.5`. A dot is not valid in a CSS custom
+ * property name, and `--halogen-space-0.5` does not merely fail on its own — the
+ * parser's error recovery discarded the surrounding declarations, which took out
+ * every spacing and color primitive declared before it. The page rendered with
+ * no padding and no gaps anywhere, while every utility still compiled and every
+ * test still passed.
+ */
+export const space = {
+  0: '0px',
+  px: '1px',
+  half: '2px',
+  1: '4px',
+  2: '8px',
+  3: '12px',
+  4: '16px',
+  5: '20px',
+  6: '24px',
+  8: '32px',
+  10: '40px',
+  12: '48px',
+  16: '64px',
+  20: '80px',
+  24: '96px',
+  32: '128px',
+  40: '160px',
+  48: '192px',
+  /**
+   * 64 and 80 are card widths, not gaps.
+   *
+   * The scale's gaps are deliberate everywhere else — there is no 28, 36, 44 or
+   * 56, because a scale with every value in it is not a scale. These two earn a
+   * place because a horizontally scrolling rail needs a fixed item width, and
+   * `Rail` shipped asking for `w-64` and `w-80` against a scale that stopped at
+   * 48. Both compiled to nothing, so the default item width and the large one
+   * silently became `auto` — sm (192px) was the only width that worked, and
+   * `lg` was not larger than it.
+   */
+  64: '256px',
+  80: '320px',
+} as const;
+
+/**
+ * Radius. The nesting law — inner = outer − padding, clamped to the nearest
+ * step, never below `xs` — is enforced by a helper in @halogen-ui/react, not by
+ * convention. `full` is reserved for components that *are* pills.
+ */
+export const radius = {
+  none: '0px',
+  xs: '4px',
+  sm: '6px',
+  md: '10px',
+  lg: '16px',
+  xl: '24px',
+  '2xl': '32px',
+  full: '9999px',
+} as const;
+
+/**
+ * Control heights. `md` is the default. The 44px minimum touch target is not on
+ * this scale because it is not a height — it is a hit-area floor applied via
+ * pseudo-element expansion, so a visually 32px control still takes a 44px tap.
+ */
+export const control = {
+  sm: '32px',
+  md: '40px',
+  lg: '48px',
+  xl: '56px',
+} as const;
+
+/** Icon sizes. Three, and only three. */
+export const icon = {
+  sm: '16px',
+  md: '20px',
+  lg: '24px',
+} as const;
+
+/** Icon stroke widths, scaled with size so optical weight stays constant. */
+export const iconStroke = {
+  sm: '1.5',
+  md: '1.75',
+  lg: '2',
+} as const;
+
+export const borderWidth = {
+  0: '0px',
+  1: '1px',
+  2: '2px',
+} as const;
+
+/** Minimum interactive hit area. Exceeds WCAG 2.5.8 AA (24px) deliberately. */
+export const target = {
+  /** WCAG 2.5.8 AA floor — the absolute minimum, used only where 44 is impossible. */
+  min: '24px',
+  /** The Halogen house standard for anything reachable by touch. */
+  touch: '44px',
+} as const;
+
+/** Layout containers, from aesthetic direction §8. */
+export const container = {
+  prose: '720px',
+  default: '1280px',
+  wide: '1440px',
+} as const;
+
+export const breakpoint = {
+  sm: '640px',
+  md: '768px',
+  lg: '1024px',
+  xl: '1280px',
+  '2xl': '1536px',
+} as const;
+
+/**
+ * Stacking order. Named rather than numeric at the call site so an overlay can
+ * never be given an arbitrary z-index, and so the layering relationship between
+ * a popover inside a dialog is a system decision rather than a local one.
+ */
+export const layer = {
+  base: '0',
+  raised: '10',
+  sticky: '100',
+  overlay: '1000',
+  modal: '1100',
+  popover: '1200',
+  toast: '1300',
+  tooltip: '1400',
+} as const;
+
+/**
+ * Media aspect ratios.
+ *
+ * A token scale rather than free-form ratios, for the same reason spacing is a
+ * scale: three ratios used consistently reads as a system, and eleven ratios
+ * used once each reads as whatever each author felt like that afternoon.
+ *
+ * `wide` exists because it was already in use as `aspect-[21/9]` inside a lookup
+ * map in ContentCard — the only arbitrary value in the library, and invisible to
+ * the rule that forbids them until the rule learned to read class-shaped strings
+ * outside call sites.
+ */
+export const aspect = {
+  /** Video, screenshots, most product media. */
+  video: '16 / 9',
+  /** Avatars, tiles, gallery thumbnails. */
+  square: '1 / 1',
+  /** A cinematic banner. Deliberately the only ratio wider than video. */
+  wide: '21 / 9',
+} as const;
+
+// No `portrait`. The scale holds the three ratios ContentCard actually offers;
+// a fourth added "for completeness" is a token nothing uses, and the audit
+// framework is explicit that tokens are not added to satisfy a checklist.

package/src/primitives/typography.ts

@@ -0,0 +1,184 @@
+/**
+ * Halogen — typographic primitives.
+ *
+ * Two scales, deliberately separate: a fixed UI scale for product surfaces and
+ * a fluid display scale for marketing. Mixing them is what produces interfaces
+ * where a dashboard header is accidentally 44px on a laptop.
+ */
+
+export const fontFamily = {
+  /**
+   * `Geist`, not `Geist Sans`.
+   *
+   * The family is named **Geist**. This token asked for `'Geist Sans'` — a name
+   * no face has ever carried — from Phase 1 until Phase 6, so it matched
+   * nothing and every sans glyph in the system silently painted in
+   * `ui-sans-serif`. Measured to prove it: at 600/32px the string used for the
+   * check rendered 603.45px under `'Geist Sans'` and 603.45px under bare
+   * `ui-sans-serif` — identical — against 677.05px under `'Geist'`.
+   *
+   * The comment that used to sit here claimed "self-hosted, SIL OFL,
+   * redistributable to buyers" while the showcase loaded the family from
+   * Google's CDN. Now true: the variable faces are vendored in
+   * `packages/tokens/fonts/` with the OFL text beside them.
+   *
+   * Fallbacks are system faces with similar metrics so the page does not reflow
+   * when the webfont lands.
+   */
+  sans: "'Geist', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+  mono: "'Geist Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace",
+} as const;
+
+/**
+ * The vendored faces, and what has to be true for shipping them to be legal.
+ *
+ * Geist is SIL Open Font License 1.1, Copyright (c) 2023 Vercel in
+ * collaboration with basement.studio. OFL permits bundling and sale as part of a
+ * larger work, provided the license text travels with the font and the font is
+ * not sold on its own. The copyright line declares no Reserved Font Name, so the
+ * renaming clause is moot here — and moot anyway, since the faces are shipped
+ * unmodified.
+ *
+ * Asserted in the token suite: the files exist, the license sits beside them,
+ * and the license text is really OFL 1.1.
+ */
+export const VENDORED_FONTS = [
+  { family: 'Geist', file: 'Geist-Variable.woff2', weights: '100 900', style: 'normal' },
+  { family: 'Geist Mono', file: 'GeistMono-Variable.woff2', weights: '100 900', style: 'normal' },
+] as const;
+
+export const FONT_LICENSE = {
+  file: 'LICENSE-Geist-OFL-1.1.txt',
+  spdx: 'OFL-1.1',
+  holder: 'Vercel, in collaboration with basement.studio',
+  permitsRedistribution: true,
+} as const;
+
+/**
+ * Four weights. 300 and lighter are absent by design: light weights bloom and
+ * thin on dark grounds, and this is a dark-first system.
+ */
+export const fontWeight = {
+  regular: '400',
+  medium: '500',
+  semibold: '600',
+  bold: '700',
+} as const;
+
+/**
+ * Tracking law from aesthetic direction §7 — tightens as type grows, loosens as
+ * it shrinks. Encoded as named steps so a component cannot invent one.
+ */
+export const tracking = {
+  /**
+   * 11px uppercase eyebrow.
+   *
+   * Matches the `2xs` step's own letter-spacing on purpose. Components reach for
+   * `tracking-wider` explicitly on eyebrows and table headers, which overrides
+   * whatever the size step declares — so if the two disagree, tightening the step
+   * changes nothing and the disagreement is invisible. One value, two routes to
+   * it.
+   */
+  wider: '0.015em',
+  /** <= 13px. Matches the `xs` step for the same reason. */
+  wide: '0.005em',
+  normal: '0em',
+  /** 16-20px */
+  tight: '-0.01em',
+  /** 20-32px */
+  tighter: '-0.015em',
+  /** 32-48px */
+  tightest: '-0.02em',
+  /** >= 48px */
+  display: '-0.03em',
+  /** the largest display step only */
+  displayTight: '-0.035em',
+} as const;
+
+export const lineHeight = {
+  none: '1',
+  'display-2xl': '0.95',
+  'display-xl': '1',
+  'display-lg': '1.05',
+  'display-md': '1.1',
+  'display-sm': '1.2',
+  'display-xs': '1.25',
+  snug: '1.35',
+  normal: '1.5',
+  relaxed: '1.6',
+} as const;
+
+/** Product/UI scale — fixed px. Tops out at `xl`; anything larger is display. */
+export const fontSize = {
+  '2xs': '11px',
+  xs: '12px',
+  sm: '13px',
+  base: '14px',
+  md: '16px',
+  lg: '18px',
+  xl: '20px',
+} as const;
+
+/**
+ * Line-height and tracking paired to each size step.
+ *
+ * Tailwind pairs these via `--text-<name>--line-height` and
+ * `--text-<name>--letter-spacing`. Without the pairing a `text-*` utility sets
+ * the font size and leaves line-height inherited from the document — so a 60px
+ * display headline renders at a 1.5 body leading, which is exactly what
+ * happened: the hero read as two loosely stacked lines instead of one block.
+ *
+ * Pairing also makes the tracking law from the aesthetic direction automatic.
+ * Tracking tightens as type grows; encoding it here means a heading cannot be
+ * set at the wrong tracking by forgetting a second utility.
+ */
+export const fontMetrics: Record<string, { lineHeight: string; tracking: string }> = {
+  /**
+   * The two smallest steps sit tighter than the "loosen as it shrinks" law
+   * would put them.
+   *
+   * The law is right about lowercase copy at small sizes, and wrong here: both
+   * of these steps are used almost exclusively for SHORT UPPERCASE labels —
+   * table headers, eyebrows, stat captions — and uppercase already carries its
+   * own optical spacing. At 0.06em an eleven-character header read as five
+   * separate words; 0.03em was still loose. 0.015em is the setting where an
+   * uppercase label reads as one word at 11px.
+   */
+  '2xs': { lineHeight: '16px', tracking: '0.015em' },
+  xs: { lineHeight: '16px', tracking: '0.005em' },
+  sm: { lineHeight: '20px', tracking: '0.01em' },
+  base: { lineHeight: '20px', tracking: '0em' },
+  md: { lineHeight: '24px', tracking: '0em' },
+  lg: { lineHeight: '28px', tracking: '-0.005em' },
+  xl: { lineHeight: '28px', tracking: '-0.01em' },
+};
+
+/** The display scale's own metrics. Leading tightens as the size grows. */
+export const displayMetrics: Record<string, { lineHeight: string; tracking: string }> = {
+  xs: { lineHeight: '1.25', tracking: '-0.01em' },
+  sm: { lineHeight: '1.2', tracking: '-0.015em' },
+  md: { lineHeight: '1.1', tracking: '-0.02em' },
+  lg: { lineHeight: '1.05', tracking: '-0.025em' },
+  xl: { lineHeight: '1', tracking: '-0.03em' },
+  '2xl': { lineHeight: '0.95', tracking: '-0.035em' },
+};
+
+/**
+ * Display scale — fluid. `clamp()` bounds are the min and max from aesthetic
+ * direction §7; the middle term scales with viewport width, and every step is
+ * capped so a 4K monitor does not produce a 200px headline.
+ */
+export const displaySize = {
+  xs: 'clamp(1.5rem, 1.4rem + 0.5vw, 1.5rem)',
+  sm: 'clamp(1.75rem, 1.6rem + 0.75vw, 1.875rem)',
+  md: 'clamp(2.25rem, 1.9rem + 1.5vw, 2.75rem)',
+  lg: 'clamp(2.75rem, 2.1rem + 3vw, 3.75rem)',
+  xl: 'clamp(3.5rem, 2.4rem + 5vw, 5.5rem)',
+  '2xl': 'clamp(4.5rem, 2.6rem + 8vw, 8rem)',
+} as const;
+
+/** Body copy never exceeds this measure. */
+export const measure = {
+  prose: '68ch',
+  narrow: '46ch',
+} as const;