@lo-tek/interfaces 0.0.0 → 0.37.0

package/src/tokens/matrix-cells.ts

@@ -0,0 +1,375 @@
+// Generated by scripts/generate-matrix.ts from the core and color-contract.json. Do not edit.
+
+/** The families LO-TEK ships itself. A consumer can have others. */
+export const FAMILIES = ["accent","visited","brand1","brand2","brand3","neutral","danger","warning","success"] as const
+
+export type Family = (typeof FAMILIES)[number]
+
+/** LO-TEK's own brand colours. */
+export const LOTEK_BRANDS: Record<Family, string> = {
+  "accent": "#1362ae",
+  "visited": "#5a77a8",
+  "brand1": "#0d7a5f",
+  "brand2": "#5b3fa0",
+  "brand3": "#b04c5c",
+  "neutral": "#24272b",
+  "danger": "#a82e39",
+  "warning": "#896508",
+  "success": "#316f2a"
+}
+
+/** A role is a job a colour does, and it is the same in every family. */
+export type Role = "surface" | "borderSubtle" | "border" | "borderStrong" | "fill" | "text" | "textStrong" | "textSubtle" | "content"
+
+/** Light or dark. A theme is one or the other, never both. */
+export type Appearance = "light" | "dark"
+
+type Spec = { lightness: Record<Appearance, number>; chroma: number }
+
+/** Lightness and chroma share per role, in each appearance. */
+export const ROLES: Record<Role, Spec> = {
+  "surface": {
+    "lightness": {
+      "light": 0.96,
+      "dark": 0.26
+    },
+    "chroma": 0.22
+  },
+  "borderSubtle": {
+    "lightness": {
+      "light": 0.88,
+      "dark": 0.34
+    },
+    "chroma": 0.35
+  },
+  "border": {
+    "lightness": {
+      "light": 0.575,
+      "dark": 0.625
+    },
+    "chroma": 0.55
+  },
+  "borderStrong": {
+    "lightness": {
+      "light": 0.48,
+      "dark": 0.74
+    },
+    "chroma": 0.6
+  },
+  "fill": {
+    "lightness": {
+      "light": 0.53,
+      "dark": 0.65
+    },
+    "chroma": 1
+  },
+  "text": {
+    "lightness": {
+      "light": 0.42,
+      "dark": 0.82
+    },
+    "chroma": 0.85
+  },
+  "textStrong": {
+    "lightness": {
+      "light": 0.28,
+      "dark": 0.93
+    },
+    "chroma": 0.5
+  },
+  "textSubtle": {
+    "lightness": {
+      "light": 0.485,
+      "dark": 0.73
+    },
+    "chroma": 0.7
+  },
+  "content": {
+    "lightness": {
+      "light": 0.99,
+      "dark": 0.16
+    },
+    "chroma": 0.04
+  }
+}
+
+/** The page and the raised surface, which only the neutral family has. */
+export const NEUTRAL_LAYERS: Record<"canvas" | "raised", Spec> = {
+  "canvas": {
+    "lightness": {
+      "light": 1,
+      "dark": 0.18
+    },
+    "chroma": 0.08
+  },
+  "raised": {
+    "lightness": {
+      "light": 0.92,
+      "dark": 0.32
+    },
+    "chroma": 0.12
+  }
+}
+
+/** The contrast requirements, with a margin above WCAG. Text is 4.5 and graphics 3. */
+export const REQUIREMENT = {"text":4.6,"graphic":3.1} as const
+
+/** Every name the matrix emits. */
+export type MatrixToken =
+  | "--lt-color-accent-surface"
+  | "--lt-color-accent-border-subtle"
+  | "--lt-color-accent-border"
+  | "--lt-color-accent-border-strong"
+  | "--lt-color-accent-fill"
+  | "--lt-color-accent-text"
+  | "--lt-color-accent-text-strong"
+  | "--lt-color-accent-text-subtle"
+  | "--lt-color-accent-content"
+  | "--lt-color-visited-surface"
+  | "--lt-color-visited-border-subtle"
+  | "--lt-color-visited-border"
+  | "--lt-color-visited-border-strong"
+  | "--lt-color-visited-fill"
+  | "--lt-color-visited-text"
+  | "--lt-color-visited-text-strong"
+  | "--lt-color-visited-text-subtle"
+  | "--lt-color-visited-content"
+  | "--lt-color-brand1-surface"
+  | "--lt-color-brand1-border-subtle"
+  | "--lt-color-brand1-border"
+  | "--lt-color-brand1-border-strong"
+  | "--lt-color-brand1-fill"
+  | "--lt-color-brand1-text"
+  | "--lt-color-brand1-text-strong"
+  | "--lt-color-brand1-text-subtle"
+  | "--lt-color-brand1-content"
+  | "--lt-color-brand2-surface"
+  | "--lt-color-brand2-border-subtle"
+  | "--lt-color-brand2-border"
+  | "--lt-color-brand2-border-strong"
+  | "--lt-color-brand2-fill"
+  | "--lt-color-brand2-text"
+  | "--lt-color-brand2-text-strong"
+  | "--lt-color-brand2-text-subtle"
+  | "--lt-color-brand2-content"
+  | "--lt-color-brand3-surface"
+  | "--lt-color-brand3-border-subtle"
+  | "--lt-color-brand3-border"
+  | "--lt-color-brand3-border-strong"
+  | "--lt-color-brand3-fill"
+  | "--lt-color-brand3-text"
+  | "--lt-color-brand3-text-strong"
+  | "--lt-color-brand3-text-subtle"
+  | "--lt-color-brand3-content"
+  | "--lt-color-neutral-surface"
+  | "--lt-color-neutral-border-subtle"
+  | "--lt-color-neutral-border"
+  | "--lt-color-neutral-border-strong"
+  | "--lt-color-neutral-fill"
+  | "--lt-color-neutral-text"
+  | "--lt-color-neutral-text-strong"
+  | "--lt-color-neutral-text-subtle"
+  | "--lt-color-neutral-content"
+  | "--lt-color-danger-surface"
+  | "--lt-color-danger-border-subtle"
+  | "--lt-color-danger-border"
+  | "--lt-color-danger-border-strong"
+  | "--lt-color-danger-fill"
+  | "--lt-color-danger-text"
+  | "--lt-color-danger-text-strong"
+  | "--lt-color-danger-text-subtle"
+  | "--lt-color-danger-content"
+  | "--lt-color-warning-surface"
+  | "--lt-color-warning-border-subtle"
+  | "--lt-color-warning-border"
+  | "--lt-color-warning-border-strong"
+  | "--lt-color-warning-fill"
+  | "--lt-color-warning-text"
+  | "--lt-color-warning-text-strong"
+  | "--lt-color-warning-text-subtle"
+  | "--lt-color-warning-content"
+  | "--lt-color-success-surface"
+  | "--lt-color-success-border-subtle"
+  | "--lt-color-success-border"
+  | "--lt-color-success-border-strong"
+  | "--lt-color-success-fill"
+  | "--lt-color-success-text"
+  | "--lt-color-success-text-strong"
+  | "--lt-color-success-text-subtle"
+  | "--lt-color-success-content"
+  | "--lt-color-neutral-canvas"
+  | "--lt-color-neutral-raised"
+
+/** LO-TEK's own colours in the light theme. */
+export const lightCells: Record<MatrixToken, string> = {
+  "--lt-color-accent-surface": "#e9f3ff",
+  "--lt-color-accent-border-subtle": "#c1daf8",
+  "--lt-color-accent-border": "#577ca6",
+  "--lt-color-accent-border-strong": "#39608c",
+  "--lt-color-accent-fill": "#226dba",
+  "--lt-color-accent-text": "#0d4e8c",
+  "--lt-color-accent-text-strong": "#0b2a4a",
+  "--lt-color-accent-text-subtle": "#336195",
+  "--lt-color-accent-content": "#f9fcff",
+  "--lt-color-visited-surface": "#ebf2ff",
+  "--lt-color-visited-border-subtle": "#cdd8eb",
+  "--lt-color-visited-border": "#697a95",
+  "--lt-color-visited-border-strong": "#4d5e7a",
+  "--lt-color-visited-fill": "#4f6c9c",
+  "--lt-color-visited-text": "#364d74",
+  "--lt-color-visited-text-strong": "#1d293e",
+  "--lt-color-visited-text-subtle": "#4c6080",
+  "--lt-color-visited-content": "#fafcfe",
+  "--lt-color-brand1-surface": "#e4f7ef",
+  "--lt-color-brand1-border-subtle": "#c2dfd4",
+  "--lt-color-brand1-border": "#578474",
+  "--lt-color-brand1-border-strong": "#386958",
+  "--lt-color-brand1-fill": "#157e63",
+  "--lt-color-brand1-text": "#005b46",
+  "--lt-color-brand1-text-strong": "#073125",
+  "--lt-color-brand1-text-subtle": "#316c59",
+  "--lt-color-brand1-content": "#f9fdfb",
+  "--lt-color-brand2-surface": "#f2efff",
+  "--lt-color-brand2-border-subtle": "#d8d2f8",
+  "--lt-color-brand2-border": "#7a70a6",
+  "--lt-color-brand2-border-strong": "#5f538c",
+  "--lt-color-brand2-fill": "#7156ba",
+  "--lt-color-brand2-text": "#513b8b",
+  "--lt-color-brand2-text-strong": "#2b204a",
+  "--lt-color-brand2-text-subtle": "#625295",
+  "--lt-color-brand2-content": "#fcfbff",
+  "--lt-color-brand3-surface": "#ffecee",
+  "--lt-color-brand3-border-subtle": "#f4cccf",
+  "--lt-color-brand3-border": "#9f676d",
+  "--lt-color-brand3-border-strong": "#844a51",
+  "--lt-color-brand3-fill": "#a94656",
+  "--lt-color-brand3-text": "#7e2e3c",
+  "--lt-color-brand3-text-strong": "#431920",
+  "--lt-color-brand3-text-subtle": "#8b4750",
+  "--lt-color-brand3-content": "#fffafb",
+  "--lt-color-neutral-surface": "#f1f2f3",
+  "--lt-color-neutral-border-subtle": "#d6d7d9",
+  "--lt-color-neutral-border": "#77797c",
+  "--lt-color-neutral-border-strong": "#5c5e60",
+  "--lt-color-neutral-fill": "#696c71",
+  "--lt-color-neutral-text": "#4a4d51",
+  "--lt-color-neutral-text-strong": "#27292b",
+  "--lt-color-neutral-text-subtle": "#5d5f62",
+  "--lt-color-neutral-content": "#fbfcfc",
+  "--lt-color-danger-surface": "#ffedec",
+  "--lt-color-danger-border-subtle": "#facac8",
+  "--lt-color-danger-border": "#a66363",
+  "--lt-color-danger-border-strong": "#8b4647",
+  "--lt-color-danger-fill": "#b53b43",
+  "--lt-color-danger-text": "#87232c",
+  "--lt-color-danger-text-strong": "#481518",
+  "--lt-color-danger-text-subtle": "#934244",
+  "--lt-color-danger-content": "#fffafa",
+  "--lt-color-warning-surface": "#f9f1e1",
+  "--lt-color-warning-border-subtle": "#e3d6bc",
+  "--lt-color-warning-border": "#8a7650",
+  "--lt-color-warning-border-strong": "#6f5a31",
+  "--lt-color-warning-fill": "#896508",
+  "--lt-color-warning-text": "#644800",
+  "--lt-color-warning-text-strong": "#352604",
+  "--lt-color-warning-text-subtle": "#735b29",
+  "--lt-color-warning-content": "#fdfcf9",
+  "--lt-color-success-surface": "#e8f7e6",
+  "--lt-color-success-border-subtle": "#c9dfc5",
+  "--lt-color-success-border": "#63835e",
+  "--lt-color-success-border-strong": "#466841",
+  "--lt-color-success-fill": "#3f7d37",
+  "--lt-color-success-text": "#285a22",
+  "--lt-color-success-text-strong": "#163013",
+  "--lt-color-success-text-subtle": "#426b3d",
+  "--lt-color-success-content": "#fafdfa",
+  "--lt-color-neutral-canvas": "#ffffff",
+  "--lt-color-neutral-raised": "#e4e4e5"
+}
+
+/** LO-TEK's own colours in the dark theme. */
+export const darkCells: Record<MatrixToken, string> = {
+  "--lt-color-accent-surface": "#192533",
+  "--lt-color-accent-border-subtle": "#253951",
+  "--lt-color-accent-border": "#668bb6",
+  "--lt-color-accent-border-strong": "#85aedf",
+  "--lt-color-accent-fill": "#4992e2",
+  "--lt-color-accent-text": "#99c8ff",
+  "--lt-color-accent-text-strong": "#d8eaff",
+  "--lt-color-accent-text-subtle": "#7aabe4",
+  "--lt-color-accent-content": "#0c0d10",
+  "--lt-color-visited-surface": "#1f242d",
+  "--lt-color-visited-border-subtle": "#2f3847",
+  "--lt-color-visited-border": "#7888a4",
+  "--lt-color-visited-border-strong": "#99accb",
+  "--lt-color-visited-fill": "#7290c2",
+  "--lt-color-visited-text": "#aac5f3",
+  "--lt-color-visited-text-strong": "#dbe9ff",
+  "--lt-color-visited-text-subtle": "#93a9cd",
+  "--lt-color-visited-content": "#0c0d0f",
+  "--lt-color-brand1-surface": "#192822",
+  "--lt-color-brand1-border-subtle": "#253e35",
+  "--lt-color-brand1-border": "#669382",
+  "--lt-color-brand1-border-strong": "#85b7a5",
+  "--lt-color-brand1-fill": "#45a386",
+  "--lt-color-brand1-text": "#8bd6bc",
+  "--lt-color-brand1-text-strong": "#c8f3e3",
+  "--lt-color-brand1-text-subtle": "#7bb6a1",
+  "--lt-color-brand1-content": "#0c0e0d",
+  "--lt-color-brand2-surface": "#242133",
+  "--lt-color-brand2-border-subtle": "#393351",
+  "--lt-color-brand2-border": "#897eb6",
+  "--lt-color-brand2-border-strong": "#aca0df",
+  "--lt-color-brand2-fill": "#937be2",
+  "--lt-color-brand2-text": "#c6b8ff",
+  "--lt-color-brand2-text-strong": "#e8e4ff",
+  "--lt-color-brand2-text-subtle": "#aa9be4",
+  "--lt-color-brand2-content": "#0d0d10",
+  "--lt-color-brand3-surface": "#311e20",
+  "--lt-color-brand3-border-subtle": "#4d2e31",
+  "--lt-color-brand3-border": "#af767c",
+  "--lt-color-brand3-border-strong": "#d7979d",
+  "--lt-color-brand3-fill": "#d26a79",
+  "--lt-color-brand3-text": "#ffa8b1",
+  "--lt-color-brand3-text-strong": "#ffdee1",
+  "--lt-color-brand3-text-subtle": "#db9098",
+  "--lt-color-brand3-content": "#0f0c0d",
+  "--lt-color-neutral-surface": "#232425",
+  "--lt-color-neutral-border-subtle": "#373839",
+  "--lt-color-neutral-border": "#86888a",
+  "--lt-color-neutral-border-strong": "#a9abae",
+  "--lt-color-neutral-fill": "#8c8f94",
+  "--lt-color-neutral-text": "#c1c4c9",
+  "--lt-color-neutral-text-strong": "#e6e8eb",
+  "--lt-color-neutral-text-subtle": "#a5a8ab",
+  "--lt-color-neutral-content": "#0d0d0d",
+  "--lt-color-danger-surface": "#331d1d",
+  "--lt-color-danger-border-subtle": "#512c2c",
+  "--lt-color-danger-border": "#b67271",
+  "--lt-color-danger-border-strong": "#e09392",
+  "--lt-color-danger-fill": "#df6165",
+  "--lt-color-danger-text": "#ffa9a8",
+  "--lt-color-danger-text-strong": "#ffdfde",
+  "--lt-color-danger-text-subtle": "#e58b8a",
+  "--lt-color-danger-content": "#100c0c",
+  "--lt-color-warning-surface": "#292317",
+  "--lt-color-warning-border-subtle": "#413621",
+  "--lt-color-warning-border": "#99855f",
+  "--lt-color-warning-border-strong": "#bea87d",
+  "--lt-color-warning-fill": "#ae893a",
+  "--lt-color-warning-text": "#e0bf7f",
+  "--lt-color-warning-text-strong": "#f9e6c0",
+  "--lt-color-warning-text-subtle": "#bea471",
+  "--lt-color-warning-content": "#0e0d0b",
+  "--lt-color-success-surface": "#1d271b",
+  "--lt-color-success-border-subtle": "#2b3e29",
+  "--lt-color-success-border": "#71926d",
+  "--lt-color-success-border-strong": "#91b78c",
+  "--lt-color-success-fill": "#62a15b",
+  "--lt-color-success-text": "#9ed597",
+  "--lt-color-success-text-strong": "#d2f3cd",
+  "--lt-color-success-text-subtle": "#8ab684",
+  "--lt-color-success-content": "#0c0e0c",
+  "--lt-color-neutral-canvas": "#111212",
+  "--lt-color-neutral-raised": "#323333"
+}

package/src/tokens/matrix.ts

@@ -0,0 +1,32 @@
+/**
+ * The matrix, as `@lo-tek/interfaces/matrix`: family times role, as finished
+ * tokens.
+ *
+ * No palette, no steps, no pins: the role *is* the colour. The names follow
+ * the namespaces of Tailwind and daisyUI: system prefix, kind and path.
+ *
+ * The colours are computed by the core. Here are LO-TEK's colours, and the
+ * names. A matrix for other brand colours is `light` and `dark` in the theme
+ * `buildTheme` returns.
+ */
+
+import type { Role } from "./matrix-cells.js"
+
+export {
+  darkCells,
+  FAMILIES,
+  type Family,
+  LOTEK_BRANDS,
+  lightCells,
+  type MatrixToken,
+} from "./matrix-cells.js"
+
+/** The role name as it is written in CSS. `textSubtle` becomes `text-subtle`. */
+export function roleToCss(role: Role): string {
+  return role.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+}
+
+/** The token name for one cell in the matrix. */
+export function tokenName(family: string, role: string): string {
+  return `--lt-color-${family}-${role}`
+}

package/src/tokens/theme-check.ts

@@ -0,0 +1,51 @@
+import { defaultCore } from "../diagnostics/default-core.js"
+
+/**
+ * Checks a theme a consumer has written by hand.
+ *
+ * The generator keeps the promises by construction. When someone writes in
+ * values of their choosing, keeping the promises is up to them, and then we
+ * owe them an answer about which cell breaks. Without this, "you can override
+ * anything" is a trap.
+ *
+ * All that matters is which `--lt-color-*` is in which block, and whether the
+ * block is light or dark, read from `color-scheme` or the selector. A value
+ * that cannot be computed is reported as exactly that instead of being
+ * skipped, and missing values are filled from LO-TEK's default theme, so
+ * someone who has overridden a single cell gets it checked against the rest
+ * of the system.
+ *
+ * The check is the core, written in Rust, the same one `lotek check-theme`
+ * uses.
+ */
+
+export type ThemeReport = {
+  problems: ThemeProblem[]
+  /** Blocks that were actually read. */
+  blocks: number
+  /**
+   * Values the consumer wrote, and that were understood.
+   *
+   * The promise count alone is no proof of work: the defaults fill the gaps,
+   * so one line gives as many promises as a whole theme. This number counts
+   * what the file actually contained.
+   */
+  declarations: number
+  /** Promises that were actually checked. */
+  promises: number
+}
+
+export type ThemeProblem = {
+  selector: string
+  message: string
+}
+
+/** Reads a theme and checks every promise in every block. */
+export function inspectTheme(css: string): ThemeReport {
+  return defaultCore().inspectTheme(css)
+}
+
+/** Only the problems, for anyone who does not need the counts. */
+export function checkTheme(css: string): ThemeProblem[] {
+  return inspectTheme(css).problems
+}

package/src/tokens/theme.ts

@@ -0,0 +1,104 @@
+import type { Violation } from "../diagnostics/core.js"
+import { defaultCore } from "../diagnostics/default-core.js"
+import type { Family } from "./matrix.js"
+
+export type { Violation }
+
+/**
+ * Builds a complete colour theme from a few brand colours.
+ *
+ * The theme is the contract applied to the consumer's hues. The hue comes
+ * from the consumer, the lightness from the role, and the promises hold by
+ * construction. That is why there is no adjustment pass here: there is
+ * nothing to move.
+ *
+ * ```ts
+ * const theme = buildTheme({ accent: "#7c3aed", danger: "#b3261e" })
+ * console.log(theme.css)
+ * ```
+ */
+
+export type ThemeTypography = {
+  /** The font stack the whole theme uses, written as in CSS. */
+  fontFamily?: string
+  /** The weights, as numbers or keywords. */
+  weights?: {
+    regular?: string | number
+    medium?: string | number
+    semibold?: string | number
+    bold?: string | number
+  }
+  /** Line heights for controls, headings, body text and small surfaces. */
+  lineHeights?: {
+    default?: string | number
+    heading?: string | number
+    article?: string | number
+    compact?: string | number
+  }
+}
+
+/**
+ * The shape of the theme: corners and borders.
+ *
+ * The button, the field and the surfaces are set separately. The distinction
+ * is worth keeping: another Norwegian design system has fully round buttons
+ * and fields with almost square corners, and one shared number would have
+ * turned the fields into capsules.
+ *
+ * The checkbox, the badge, the tag, the toggle group, the avatar and the
+ * skeleton are left out on purpose. There the corner is not a style choice
+ * but the shape itself: a checkbox that turns round looks like a radio
+ * button, and a badge that turns square looks like a button.
+ */
+export type ThemeShape = {
+  /** Corners on the button, the pagination and the skip link. */
+  buttonRadius?: string
+  /** Corners on the field, the text area and the select. */
+  fieldRadius?: string
+  /**
+   * Corners on the card, dialog, popover, alert, accordion, error summary,
+   * file upload, session timeout, suggestion list, toast and tooltip.
+   */
+  surfaceRadius?: string
+  /** The border width of the button. */
+  buttonBorderWidth?: string
+  /** The font weight of the button text. */
+  buttonFontWeight?: string | number
+}
+
+/**
+ * The brand colours.
+ *
+ * Each family is optional on its own, and one you leave out inherits
+ * LO-TEK's default hue. Leave them all out, and the theme only sets type and
+ * shape.
+ */
+export type ThemeColors = Partial<Record<Family, string>>
+
+export type ThemeInput = ThemeColors & {
+  /** Type and line height. Left out, LO-TEK's default typography stays. */
+  typography?: ThemeTypography
+  /** Corners and borders. Left out, LO-TEK's default shape stays. */
+  shape?: ThemeShape
+}
+
+export type Theme = {
+  light: Record<string, string>
+  dark: Record<string, string>
+  /** Promises that do not hold. Empty when the theme is sound. */
+  violations: Violation[]
+  css: string
+}
+
+/**
+ * Builds the theme, and checks every promise while it is built.
+ *
+ * The arithmetic happens in the core, written in Rust, which `lotek theme` and
+ * LO-TEK for Kotlin use. The typography and shape values are written straight
+ * into a CSS rule, so a value that could break out of it, such as
+ * `4px; } html {`, an unclosed parenthesis or `</style>`, is rejected with an
+ * explanation that names the field in the recipe.
+ */
+export function buildTheme(input: ThemeInput): Theme {
+  return defaultCore().buildTheme(input)
+}