@outsidedata/dolex 0.1.0

package/src/theme/spacing.ts

@@ -0,0 +1,176 @@
+/**
+ * Dolex Design System — Spacing Tokens
+ *
+ * Consistent spacing scales for chart margins, padding, and layout gaps.
+ * Three size modes accommodate different container sizes and information density.
+ *
+ * All values are in pixels. SVG renderers use them directly;
+ * CSS-based renderers can convert as needed.
+ */
+
+// ─── BASE SPACING SCALE ──────────────────────────────────────────────────────
+//
+// 4px base unit. Powers of 2 progression keeps ratios harmonious.
+// Named by their pixel value for clarity in a visualization context.
+
+export const space = {
+  0: 0,
+  1: 1,
+  2: 2,
+  4: 4,
+  6: 6,
+  8: 8,
+  12: 12,
+  16: 16,
+  20: 20,
+  24: 24,
+  32: 32,
+  40: 40,
+  48: 48,
+  64: 64,
+} as const;
+
+export type SpaceKey = keyof typeof space;
+
+// ─── CHART MARGINS ────────────────────────────────────────────────────────────
+//
+// Margin presets for SVG charts. The `top` accommodates the title;
+// `bottom` accommodates the x-axis label; `left` accommodates the y-axis label.
+// `right` is minimal unless a legend is present.
+
+export interface ChartMargins {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export const margins = {
+  /** For sparklines, small-multiples, and tight dashboard tiles */
+  compact: {
+    top: 24,
+    right: 16,
+    bottom: 32,
+    left: 40,
+  },
+  /** Standard chart margins — room for title, axis labels, ticks */
+  default: {
+    top: 40,
+    right: 30,
+    bottom: 50,
+    left: 60,
+  },
+  /** Large charts with subtitles, annotations, and detailed axis labels */
+  spacious: {
+    top: 56,
+    right: 40,
+    bottom: 64,
+    left: 76,
+  },
+} as const satisfies Record<string, ChartMargins>;
+
+export type MarginMode = keyof typeof margins;
+
+// ─── PADDING ──────────────────────────────────────────────────────────────────
+//
+// Internal padding for containers, tooltips, and panels.
+
+export const padding = {
+  /** Tooltip padding */
+  tooltip: { x: 12, y: 8 },
+  /** Legend container padding */
+  legend: { x: 12, y: 8 },
+  /** Card / panel padding */
+  card: { x: 16, y: 12 },
+  /** Inline badge / chip padding */
+  badge: { x: 8, y: 4 },
+} as const;
+
+// ─── GAP SCALES ───────────────────────────────────────────────────────────────
+//
+// Spacing between repeated elements.
+
+export const gap = {
+  /** Between legend color swatch and label text */
+  legendSwatch: 6,
+  /** Between legend items (vertical stack) */
+  legendItem: 4,
+  /** Between legend items (horizontal row) */
+  legendItemHorizontal: 16,
+  /** Between small-multiple panels */
+  smallMultiple: 12,
+  /** Between label and its data mark */
+  labelOffset: 4,
+  /** Between title and subtitle */
+  titleSubtitle: 4,
+  /** Between chart title area and plot area */
+  titleToPlot: 8,
+  /** Between adjacent bars in grouped bar charts */
+  barGroup: 2,
+  /** Between tick label and axis line */
+  tickPadding: 8,
+  /** Between annotation callout and target point */
+  annotationOffset: 8,
+} as const;
+
+// ─── BORDER RADIUS ────────────────────────────────────────────────────────────
+
+export const radius = {
+  /** No rounding */
+  none: 0,
+  /** Subtle rounding for bars, marks */
+  sm: 2,
+  /** Default for cards, containers */
+  md: 6,
+  /** Larger rounding for panels, modals */
+  lg: 8,
+  /** Rounded pill shape for badges */
+  full: 9999,
+} as const;
+
+// ─── STROKE WIDTHS ────────────────────────────────────────────────────────────
+
+export const stroke = {
+  /** Hairline — grid lines, subtle separators */
+  hairline: 0.5,
+  /** Thin — axis lines, borders */
+  thin: 1,
+  /** Default — lines in line charts, mark outlines */
+  default: 1.5,
+  /** Medium — emphasized lines, hover outlines */
+  medium: 2,
+  /** Thick — primary trend line, active selections */
+  thick: 3,
+} as const;
+
+// ─── CHART SIZE PRESETS ───────────────────────────────────────────────────────
+//
+// Suggested dimensions for common chart container sizes.
+
+export const chartSize = {
+  /** Dashboard tile, sparkline */
+  thumbnail: { width: 300, height: 200 },
+  /** Small panel in a grid */
+  small: { width: 480, height: 320 },
+  /** Standard standalone chart */
+  medium: { width: 640, height: 420 },
+  /** Full-width chart */
+  large: { width: 800, height: 500 },
+  /** Presentation / export */
+  xlarge: { width: 1080, height: 640 },
+} as const;
+
+export type ChartSizeKey = keyof typeof chartSize;
+
+// ─── ANIMATION ────────────────────────────────────────────────────────────────
+//
+// Duration and easing tokens for transitions.
+
+export const animation = {
+  /** Fast micro-interactions: hover, focus */
+  fast: { duration: 150, easing: 'ease-out' },
+  /** Default transitions: enter, exit */
+  default: { duration: 300, easing: 'ease-in-out' },
+  /** Slow/dramatic: layout shifts, data updates */
+  slow: { duration: 600, easing: 'ease-in-out' },
+} as const;

package/src/theme/typography.ts

@@ -0,0 +1,170 @@
+/**
+ * Dolex Design System — Typography Tokens
+ *
+ * Consistent type scale for chart titles, labels, annotations, and UI elements.
+ * Designed for data-dense visualizations where readability at small sizes is critical.
+ *
+ * Font stack: Inter is the primary face (excellent tabular figures, narrow at small sizes).
+ * Falls back through system-ui to ensure consistent metrics cross-platform.
+ */
+
+// ─── FONT FAMILIES ────────────────────────────────────────────────────────────
+
+export const fontFamily = {
+  /** Primary sans-serif stack for all chart text */
+  sans: 'Inter, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  /** Monospace stack for data values, code, and tabular figures */
+  mono: '"JetBrains Mono", "Fira Code", "SF Mono", Menlo, Consolas, monospace',
+} as const;
+
+// ─── FONT SIZES ───────────────────────────────────────────────────────────────
+//
+// Pixel values. SVG text uses these directly; CSS renderers can convert to rem.
+// Scale is tighter than typical UI because chart text lives inside constrained space.
+
+export const fontSize = {
+  /** Chart title — the largest text element in a visualization */
+  title: 14,
+  /** Chart subtitle, section headers within legends */
+  subtitle: 12,
+  /** Axis labels, legend items, tick labels */
+  label: 11,
+  /** Annotations, footnotes, data source attribution */
+  annotation: 10,
+  /** Sparkline labels, dense small-multiples, compact mode ticks */
+  micro: 9,
+} as const;
+
+export type FontSizeKey = keyof typeof fontSize;
+
+// ─── FONT WEIGHTS ─────────────────────────────────────────────────────────────
+
+export const fontWeight = {
+  /** Body text, tick labels, legend items */
+  regular: 400,
+  /** Axis titles, emphasized labels */
+  medium: 500,
+  /** Chart titles, highlighted values */
+  semibold: 600,
+} as const;
+
+export type FontWeightKey = keyof typeof fontWeight;
+
+// ─── LINE HEIGHTS ─────────────────────────────────────────────────────────────
+//
+// Unitless multipliers relative to font-size. Tighter for chart elements
+// (single-line), looser for multi-line annotations.
+
+export const lineHeight = {
+  /** Single-line chart elements: titles, labels, ticks */
+  tight: 1.2,
+  /** Default for most text */
+  normal: 1.4,
+  /** Multi-line annotations, tooltip content, descriptions */
+  relaxed: 1.6,
+} as const;
+
+export type LineHeightKey = keyof typeof lineHeight;
+
+// ─── LETTER SPACING ───────────────────────────────────────────────────────────
+//
+// Em values. Slight tracking aids legibility at small sizes.
+
+export const letterSpacing = {
+  /** Default — no adjustment */
+  normal: '0em',
+  /** Slight expansion for labels at micro size */
+  wide: '0.02em',
+  /** Uppercase text or very small elements */
+  wider: '0.04em',
+} as const;
+
+// ─── COMPOSITE TEXT STYLES ────────────────────────────────────────────────────
+//
+// Pre-composed styles for common chart text roles. Each combines size, weight,
+// and line-height into a single token that renderers can spread onto elements.
+
+export interface TextStyle {
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: number;
+  lineHeight: number;
+  letterSpacing: string;
+}
+
+export const textStyles = {
+  /** Chart title */
+  chartTitle: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.title,
+    fontWeight: fontWeight.semibold,
+    lineHeight: lineHeight.tight,
+    letterSpacing: letterSpacing.normal,
+  },
+  /** Chart subtitle or legend header */
+  chartSubtitle: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.subtitle,
+    fontWeight: fontWeight.medium,
+    lineHeight: lineHeight.tight,
+    letterSpacing: letterSpacing.normal,
+  },
+  /** Axis titles */
+  axisTitle: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.subtitle,
+    fontWeight: fontWeight.medium,
+    lineHeight: lineHeight.tight,
+    letterSpacing: letterSpacing.normal,
+  },
+  /** Tick labels, legend item text */
+  axisLabel: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.label,
+    fontWeight: fontWeight.regular,
+    lineHeight: lineHeight.tight,
+    letterSpacing: letterSpacing.normal,
+  },
+  /** Data labels placed on or near marks */
+  dataLabel: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.label,
+    fontWeight: fontWeight.medium,
+    lineHeight: lineHeight.tight,
+    letterSpacing: letterSpacing.normal,
+  },
+  /** Annotations and footnotes */
+  annotation: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.annotation,
+    fontWeight: fontWeight.regular,
+    lineHeight: lineHeight.relaxed,
+    letterSpacing: letterSpacing.wide,
+  },
+  /** Very small text for dense layouts */
+  micro: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.micro,
+    fontWeight: fontWeight.regular,
+    lineHeight: lineHeight.tight,
+    letterSpacing: letterSpacing.wider,
+  },
+  /** Monospace data values (tables, tooltips) */
+  dataValue: {
+    fontFamily: fontFamily.mono,
+    fontSize: fontSize.label,
+    fontWeight: fontWeight.regular,
+    lineHeight: lineHeight.normal,
+    letterSpacing: letterSpacing.normal,
+  },
+  /** Tooltip text */
+  tooltip: {
+    fontFamily: fontFamily.sans,
+    fontSize: fontSize.subtitle,
+    fontWeight: fontWeight.regular,
+    lineHeight: lineHeight.relaxed,
+    letterSpacing: letterSpacing.normal,
+  },
+} as const satisfies Record<string, TextStyle>;
+
+export type TextStyleKey = keyof typeof textStyles;