@kolkrabbi/kol-theme 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# @kolkrabbi/kol-theme
+
+Brand-neutral tokens + base CSS for the KOL (Kolkrabbi) design system. The cascade layer every other KOL package and consumer builds on — design tokens, color/opacity scales, typography, and the canonical `kol-*` component classes.
+
+## Install
+
+```sh
+npm i @kolkrabbi/kol-theme
+```
+
+## Use
+
+In a Vite + Tailwind v4 app, import the barrel after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "@kolkrabbi/kol-theme";
+```
+
+Cascade order is load-bearing — `kol-theme` must come after Tailwind so its component classes and tokens resolve correctly. Individual files are also reachable (`@kolkrabbi/kol-theme/kol-color.css`, etc.) if you need finer control.
+
+## Fonts
+
+The typography CSS references the brand fonts at absolute paths (`/fonts/Right-Grotesk/…`, `/fonts/jetbrains-mono/…`). **The package does not ship the font files** — your app must serve them from `/fonts/` (e.g. drop them in your `public/` dir). The showcase in this repo does exactly that. Without them, type falls back to system fonts.
+
+Pure CSS — no JS, no dependencies.

package/kol-base-tokens.css

@@ -0,0 +1,74 @@
+/**
+ * @kol/theme — Canonical neutral surface base (shared)
+ *
+ * The brand-NEUTRAL tokens that are identical across apps/web and apps/brand:
+ * the surface elevation tiers and theme-invariant absolutes. These are the real
+ * drift surface (page bg/fg colors) and they carry no brand identity, so they
+ * are safe to share as the single canonical source — kolkrabbi and any
+ * scaffolded client render on the same surface base.
+ *
+ * Deliberately NOT here: accent (kolkrabbi yellow in web; neutral-ink default +
+ * brand-layer rebind in brand), fonts, and brand color primitives — those are
+ * brand-specific and stay with each app's own theme layer.
+ *
+ * Plain :root (not @theme): these tokens aren't in Tailwind's --color-*
+ * namespace, so they generate no utilities either way — consumed as
+ * var(--kol-surface-*) by hand-written utilities + components in both apps.
+ * Dark selector matches brand's mechanism: [data-theme="dark"], .dark.
+ */
+
+:root {
+  /* Absolutes (theme-invariant) */
+  --kol-color-absolute-white: #ffffff;
+  --kol-color-absolute-black: #000000;
+
+  /* Surface tiers (page-level) — Light Mode (default) */
+  --kol-surface-primary: #fafafa;
+  --kol-surface-on-primary: #121215;
+
+  --kol-surface-secondary: #f2f2f2;
+  --kol-surface-on-secondary: #19191d;
+
+  --kol-surface-tertiary: #ffffff;
+  --kol-surface-on-tertiary: #0e0e11;
+
+  --kol-surface-inverse: #0e0e11;
+  --kol-surface-on-inverse: #fcfbf8;
+
+  --kol-surface-secondary-inverse: #212121;
+  --kol-surface-tertiary-inverse: #424242;
+
+  --kol-surface-contrast: #f2f2f2;
+
+  /* Surface split tokens */
+  --kol-surface-support-split: #eeeeee;
+  --kol-surface-support-split-inverse: #202026;
+  --kol-surface-absolute-split: #ffffff;
+  --kol-surface-absolute-split-inverse: #000000;
+}
+
+/* Dark Mode — surface overrides */
+:is([data-theme="dark"], .dark) {
+  --kol-surface-primary: #121215;
+  --kol-surface-on-primary: #fafafa;
+
+  --kol-surface-secondary: #19191d;
+  --kol-surface-on-secondary: #f8f8f8;
+
+  --kol-surface-tertiary: #0e0e11;
+  --kol-surface-on-tertiary: #ffffff;
+
+  --kol-surface-inverse: #fcfbf8;
+  --kol-surface-on-inverse: #0e0e11;
+
+  --kol-surface-secondary-inverse: #e0e0e0;
+  --kol-surface-tertiary-inverse: #d4d4d8;
+
+  --kol-surface-contrast: #0b0b0c;
+
+  /* Surface split tokens - Dark Mode */
+  --kol-surface-support-split: #202026;
+  --kol-surface-support-split-inverse: #eeeeee;
+  --kol-surface-absolute-split: #000000;
+  --kol-surface-absolute-split-inverse: #ffffff;
+}

package/kol-color.css

@@ -0,0 +1,280 @@
+/**
+ * KOL Color System — DS theme layer (brand-neutral).
+ *
+ * Surface tiers, ink-based accent default, ui-state, borders, opacity ramp
+ * re-declarations for surface-inverse contexts. Brand identity (hue ramps,
+ * cream ramp, brand-primary/secondary roles, accent rebind) lives in the
+ * sibling `kol-brand-color.css` and mirrors the `kol-brand` package — loaded
+ * explicitly by `index.css` for this repo (the brand showcase). A scaffolded
+ * project that does NOT pull `kol-brand` skips the brand import and renders
+ * brand-neutral with `--kol-accent-*` defaulting to surface ink.
+ *
+ * Dark mode toggle:
+ *   document.documentElement.setAttribute('data-theme', 'dark')
+ */
+
+/* =============================================================================
+ * LIGHT MODE (Default)
+ * ============================================================================= */
+
+:root {
+  /* Absolutes + surface elevation tiers now come from
+   * @kol/theme/kol-base-tokens.css (imported first by kol-theme.css) — the
+   * shared canonical neutral base, identical to apps/web. */
+
+  /* ---------------------------------------------------------------------------
+   * ACCENT (interactive role — buttons, toggles, focus rings)
+   *
+   * Brand-neutral default: points at the surface ink color so the DS works
+   * without a brand layer. kol-brand-color.css overrides these to point at
+   * --brand-primary / --brand-on-primary / a brand-strong stop.
+   * --------------------------------------------------------------------------- */
+
+  --kol-accent-primary:        var(--kol-surface-on-primary);
+  --kol-accent-on-primary:     var(--kol-surface-primary);
+  --kol-accent-primary-strong: color-mix(in srgb, var(--kol-surface-on-primary) 80%, transparent);
+
+  /* ---------------------------------------------------------------------------
+   * UI STATE — error / warning / info / success.
+   * Direct hex (not ramp-dependent). Intentionally not part of the brand layer
+   * so consumers get sensible defaults out of the box.
+   * --------------------------------------------------------------------------- */
+
+  --ui-error:    #B91C1C;
+  --ui-warning:  #EAB308;
+  --ui-info:     #1D4ED8;
+  --ui-success:  #15803D;
+
+  /* ---------------------------------------------------------------------------
+   * BORDER
+   * --------------------------------------------------------------------------- */
+
+  --kol-border-default: color-mix(in srgb, var(--kol-surface-on-primary) 8%, transparent);
+  --kol-border-focus: color-mix(in srgb, var(--kol-accent-primary) 70%, var(--kol-surface-on-primary));
+  --kol-focus-ring: var(--kol-accent-primary);
+}
+
+:root[data-theme="light"] {
+  --ui-error:    #DC2626;
+  --ui-warning:  #CA8A04;
+  --ui-info:     #2563EB;
+  --ui-success:  #16A34A;
+}
+
+/* =============================================================================
+ * DARK MODE
+ * Explicit dark-mode surface overrides ([data-theme="dark"], .dark) now come
+ * from @kol/theme/kol-base-tokens.css (shared with apps/web). The system-
+ * preference auto-dark block below stays brand-local — web has no equivalent.
+ * ============================================================================= */
+
+/* =============================================================================
+ * SYSTEM PREFERENCE (Automatic Dark Mode)
+ * ============================================================================= */
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --kol-surface-primary: #121215;
+    --kol-surface-on-primary: #FAFAFA;
+
+    --kol-surface-secondary: #19191D;
+    --kol-surface-on-secondary: #F8F8F8;
+
+    --kol-surface-tertiary: #0E0E11;
+    --kol-surface-on-tertiary: #FFFFFF;
+
+    --kol-surface-inverse: #FCFBF8;
+    --kol-surface-on-inverse: #0E0E11;
+  }
+}
+
+/* =============================================================================
+ * CONTEXT-AWARE SURFACE INVERSE
+ * ============================================================================= */
+
+.bg-surface-inverse {
+  background-color: var(--kol-surface-inverse);
+  color: var(--kol-surface-on-inverse);
+
+  --kol-surface-primary: var(--kol-surface-inverse);
+  --kol-surface-on-primary: var(--kol-surface-on-inverse);
+  --kol-surface-secondary: var(--kol-surface-secondary);
+  --kol-surface-on-secondary: var(--kol-surface-on-inverse);
+  --kol-surface-tertiary: var(--kol-surface-tertiary);
+  --kol-surface-on-tertiary: var(--kol-surface-on-inverse);
+  --kol-border-default: color-mix(in srgb, var(--kol-surface-on-inverse) 8%, transparent);
+
+  /* Re-declare fg-ramp against on-inverse so opacity tokens flip with surface.
+   * CSS substitutes inner var() at the declaration site, so the :root declarations
+   * bake the on-primary color and don't re-resolve here. Redeclaring here lets every
+   * --kol-fg-* consumer (borders, dividers, dimmed text) automatically contrast-flip. */
+  --kol-fg-01: color-mix(in srgb, var(--kol-surface-on-inverse) 1%, transparent);
+  --kol-fg-02: color-mix(in srgb, var(--kol-surface-on-inverse) 2%, transparent);
+  --kol-fg-04: color-mix(in srgb, var(--kol-surface-on-inverse) 4%, transparent);
+  --kol-fg-08: color-mix(in srgb, var(--kol-surface-on-inverse) 8%, transparent);
+  --kol-fg-12: color-mix(in srgb, var(--kol-surface-on-inverse) 12%, transparent);
+  --kol-fg-16: color-mix(in srgb, var(--kol-surface-on-inverse) 16%, transparent);
+  --kol-fg-24: color-mix(in srgb, var(--kol-surface-on-inverse) 24%, transparent);
+  --kol-fg-32: color-mix(in srgb, var(--kol-surface-on-inverse) 32%, transparent);
+  --kol-fg-40: color-mix(in srgb, var(--kol-surface-on-inverse) 40%, transparent);
+  --kol-fg-48: color-mix(in srgb, var(--kol-surface-on-inverse) 48%, transparent);
+  --kol-fg-64: color-mix(in srgb, var(--kol-surface-on-inverse) 64%, transparent);
+  --kol-fg-80: color-mix(in srgb, var(--kol-surface-on-inverse) 80%, transparent);
+  --kol-fg-88: color-mix(in srgb, var(--kol-surface-on-inverse) 88%, transparent);
+  --kol-fg-96: color-mix(in srgb, var(--kol-surface-on-inverse) 96%, transparent);
+}
+
+/* =============================================================================
+ * UTILITY CLASSES (HEAVILY USED — Based on usage audit)
+ *
+ * - .text-fg-* (594 references) live in kol-opacity.css
+ * - .border-fg-* / .bg-fg-* live in kol-opacity.css
+ *
+ * Below: surface + elevation + basic + state classes that consume the surface
+ * tier directly (not through opacity ramps).
+ * ============================================================================= */
+
+/* ---------------------------------------------------------------------------
+ * Surface Utilities
+ * --------------------------------------------------------------------------- */
+
+.bg-surface-primary {
+  background-color: var(--kol-surface-primary);
+  color: var(--kol-surface-on-primary);
+}
+
+.bg-surface-secondary {
+  background-color: var(--kol-surface-secondary);
+  color: var(--kol-surface-on-secondary);
+}
+
+.bg-surface-tertiary {
+  background-color: var(--kol-surface-tertiary);
+  color: var(--kol-surface-on-tertiary);
+}
+
+.bg-surface-inverse {
+  background-color: var(--kol-surface-inverse);
+  color: var(--kol-surface-on-inverse);
+}
+
+/* ---------------------------------------------------------------------------
+ * Elevation Utilities
+ * --------------------------------------------------------------------------- */
+
+.elevation-base {
+  background-color: var(--kol-surface-primary);
+  color: var(--kol-surface-on-primary);
+}
+
+.elevation-raised {
+  background-color: var(--kol-surface-secondary);
+  color: var(--kol-surface-on-secondary);
+}
+
+.elevation-elevated {
+  background-color: var(--kol-surface-tertiary);
+  color: var(--kol-surface-on-tertiary);
+}
+
+/* ---------------------------------------------------------------------------
+ * Basic Utilities
+ * --------------------------------------------------------------------------- */
+
+.text-auto {
+  color: var(--kol-surface-on-primary);
+}
+
+.text-inverse {
+  color: var(--kol-surface-on-inverse);
+}
+
+.bg-auto {
+  background-color: var(--kol-surface-primary);
+}
+
+.bg-fg {
+  background-color: var(--kol-surface-on-primary);
+}
+
+.border-auto {
+  border-color: var(--kol-border-default);
+}
+
+.divider-auto {
+  border-color: var(--kol-border-default);
+  border-width: 1px;
+}
+
+/* ---------------------------------------------------------------------------
+ * Surface-based Borders (for contrast on bg-fg fills)
+ * --------------------------------------------------------------------------- */
+
+.border-surface {
+  border-color: var(--kol-surface-primary);
+}
+
+.border-surface-08 {
+  border-color: color-mix(in srgb, var(--kol-surface-primary) 8%, transparent);
+}
+
+.border-surface-16 {
+  border-color: color-mix(in srgb, var(--kol-surface-primary) 16%, transparent);
+}
+
+/* ---------------------------------------------------------------------------
+ * State Utilities
+ * --------------------------------------------------------------------------- */
+
+.hover\:border-hover:hover {
+  border-color: var(--kol-border-default);
+}
+
+.focus\:border-focus:focus {
+  border-color: var(--kol-border-focus);
+}
+
+.focus-visible\:border-focus:focus-visible {
+  border-color: var(--kol-border-focus);
+}
+
+.focus-visible\:ring-focus:focus-visible {
+  outline: 2px solid var(--kol-focus-ring);
+  outline-offset: 2px;
+}
+
+/* ---------------------------------------------------------------------------
+ * Absolute Colors
+ * --------------------------------------------------------------------------- */
+
+.bg-absolute-white {
+  background-color: var(--kol-color-absolute-white);
+}
+
+.bg-absolute-black {
+  background-color: var(--kol-color-absolute-black);
+}
+
+.text-absolute-white {
+  color: var(--kol-color-absolute-white);
+}
+
+.text-absolute-black {
+  color: var(--kol-color-absolute-black);
+}
+
+/* =============================================================================
+ * TAILWIND CONTRACT — color exposures (DS layer)
+ *
+ * Tailwind v4 generates utilities from --color-* tokens. UI state lives here
+ * (DS-level). Brand role + brand ramps + cream are registered in
+ * kol-brand-color.css (loaded after this file when client branding is desired).
+ * ============================================================================= */
+
+@theme {
+  /* UI state — conventional Tailwind hexes, disconnected from brand ramps. */
+  --color-ui-error:             var(--ui-error);
+  --color-ui-warning:           var(--ui-warning);
+  --color-ui-info:              var(--ui-info);
+  --color-ui-success:           var(--ui-success);
+}