@codefast/ui 0.4.0-canary.4 → 0.4.0-canary.6

package/src/css/foundation/tokens.css

@@ -1,12 +1,28 @@
+/* -------------------------------------------------------------------------
+ * Design tokens
+ *
+ * Bridges the raw theme variables (`--background`, `--primary`, …) defined by
+ * each theme into Tailwind's `@theme inline` namespace, minting the
+ * `bg-*`, `text-*`, `border-*`, and `rounded-*` utilities the components use.
+ * ------------------------------------------------------------------------- */
+
 :root {
   --radius: 0.375rem;
 }
 
 @theme inline {
+  /* ----------------------------------------------------------------------
+   * Typography
+   * ---------------------------------------------------------------------- */
+
   --font-sans: var(--font-sans);
   --font-heading: var(--font-heading);
   --font-mono: var(--font-mono);
 
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --color-background: var(--background);
   --color-foreground: var(--foreground);
 
@@ -30,10 +46,18 @@
   --color-card: var(--card);
   --color-card-foreground: var(--card-foreground);
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --color-sidebar: var(--sidebar);
   --color-sidebar-foreground: var(--sidebar-foreground);
   --color-sidebar-primary: var(--sidebar-primary);
@@ -43,12 +67,20 @@
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-ring: var(--sidebar-ring);
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --color-chart-1: var(--chart-1);
   --color-chart-2: var(--chart-2);
   --color-chart-3: var(--chart-3);
   --color-chart-4: var(--chart-4);
   --color-chart-5: var(--chart-5);
 
+  /* ----------------------------------------------------------------------
+   * Code & selection
+   * ---------------------------------------------------------------------- */
+
   --color-surface: var(--surface);
   --color-surface-foreground: var(--surface-foreground);
 
@@ -60,6 +92,10 @@
   --color-selection: var(--selection);
   --color-selection-foreground: var(--selection-foreground);
 
+  /* ----------------------------------------------------------------------
+   * Radius scale — derived from --radius (6 = base unit)
+   * ---------------------------------------------------------------------- */
+
   --radius-xs: calc(var(--radius) * 2 / 6);
   --radius-sm: calc(var(--radius) * 4 / 6);
   --radius-md: var(--radius);

package/src/css/foundation/variants.css

@@ -1,13 +1,14 @@
-/*
- * Custom Tailwind variants for @codefast/ui.
+/* -------------------------------------------------------------------------
+ * Variants
+ *
+ * Custom Tailwind variants for @codefast/ui. Prefer these over verbose
+ * arbitrary variants (`data-[state=open]:`, `data-[side=left]:`).
  *
  * Shorthand usage (composes with group-, peer-, in-, has- modifiers):
  *   data-open:           → [data-state="open"] or [data-open]:not([data-open="false"])
  *   group-data-disabled: → ancestor .group with matching data-disabled
  *   in-data-side-left:   → ancestor with [data-side="left"]
- *
- * Prefer these over verbose arbitrary variants (data-[state=open]:, data-[side=left]:).
- */
+ * ------------------------------------------------------------------------- */
 
 /* -------------------------------------------------------------------------
  * Theme
@@ -73,6 +74,13 @@
   }
 }
 
+@custom-variant data-indeterminate {
+  &:where([data-state="indeterminate"]),
+  &:where([data-indeterminate]:not([data-indeterminate="false"])) {
+    @slot;
+  }
+}
+
 /* data-selected only matches explicit true, not bare data-selected. */
 @custom-variant data-selected {
   &:where([data-state="selected"]),

package/src/css/preset.css

@@ -1,3 +1,11 @@
+/* -------------------------------------------------------------------------
+ * Foundation preset
+ *
+ * Aggregates the foundation layers in cascade order. Import this from an app
+ * after `tailwindcss` and a theme to pull in @codefast/ui's variants, tokens,
+ * motion, and base styles.
+ * ------------------------------------------------------------------------- */
+
 @import "./foundation/source.css";
 @import "./foundation/variants.css";
 @import "./foundation/tokens.css";

package/src/css/style.css

@@ -1,3 +1,11 @@
+/* -------------------------------------------------------------------------
+ * Entry stylesheet
+ *
+ * The default, batteries-included entry point: Tailwind core, the neutral
+ * theme, and the @codefast/ui foundation preset. Apps that want a different
+ * theme import `tailwindcss`, their chosen theme, and `./preset.css` directly.
+ * ------------------------------------------------------------------------- */
+
 @import "tailwindcss";
 @import "./themes/neutral.css";
 @import "./preset.css";

package/src/css/themes/amber.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Amber theme
+ *
+ * Color tokens for the amber palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(1 0 0); /* --color-zinc-50 */
   --foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-zinc-50 */
   --card-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --input: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --ring: oklch(0.84 0.16 84); /* --color-amber-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-zinc-50 */
   --sidebar-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --sidebar-primary: oklch(0.67 0.16 58); /* --color-amber-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.84 0.16 84); /* --color-amber-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.88 0.15 92); /* --color-amber-300 */
   --chart-2: oklch(0.77 0.16 70); /* --color-amber-500 */
   --chart-3: oklch(0.67 0.16 58); /* --color-amber-600 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.56 0.15 49); /* --color-amber-700 */
   --chart-5: oklch(0.47 0.12 46); /* --color-amber-800 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
     --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 

package/src/css/themes/blue.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Blue theme
+ *
+ * Color tokens for the blue palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(1 0 0); /* --color-zinc-50 */
   --foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-zinc-50 */
   --card-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --input: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --ring: oklch(0.708 0 0); /* default ring */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-zinc-50 */
   --sidebar-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --sidebar-primary: oklch(0.546 0.245 262.881); /* --color-blue-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.708 0 0); /* default sidebar ring */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.809 0.105 251.813); /* --color-blue-300 */
   --chart-2: oklch(0.623 0.214 259.815); /* --color-blue-500 */
   --chart-3: oklch(0.546 0.245 262.881); /* --color-blue-600 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.488 0.243 264.376); /* --color-blue-700 */
   --chart-5: oklch(0.424 0.199 265.638); /* --color-blue-800 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
     --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 

package/src/css/themes/cyan.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Cyan theme
+ *
+ * Color tokens for the cyan palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(1 0 0); /* --color-zinc-50 */
   --foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-zinc-50 */
   --card-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --input: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --ring: oklch(0.8 0.13 212); /* --color-cyan-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-zinc-50 */
   --sidebar-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --sidebar-primary: oklch(0.61 0.11 222); /* --color-cyan-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.8 0.13 212); /* --color-cyan-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.87 0.12 207); /* --color-cyan-300 */
   --chart-2: oklch(0.8 0.13 212); /* --color-cyan-400 */
   --chart-3: oklch(0.71 0.13 215); /* --color-cyan-500 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.61 0.11 222); /* --color-cyan-600 */
   --chart-5: oklch(0.52 0.09 223); /* --color-cyan-700 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
     --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 

package/src/css/themes/emerald.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Emerald theme
+ *
+ * Color tokens for the emerald palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(1 0 0); /* --color-zinc-50 */
   --foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-zinc-50 */
   --card-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --input: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --ring: oklch(0.77 0.15 163); /* --color-emerald-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-zinc-50 */
   --sidebar-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --sidebar-primary: oklch(0.6 0.13 163); /* --color-emerald-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.77 0.15 163); /* --color-emerald-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.85 0.13 165); /* --color-emerald-300 */
   --chart-2: oklch(0.77 0.15 163); /* --color-emerald-400 */
   --chart-3: oklch(0.7 0.15 162); /* --color-emerald-500 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.6 0.13 163); /* --color-emerald-600 */
   --chart-5: oklch(0.51 0.1 166); /* --color-emerald-700 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
     --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 

package/src/css/themes/fuchsia.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Fuchsia theme
+ *
+ * Color tokens for the fuchsia palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(1 0 0); /* --color-zinc-50 */
   --foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-zinc-50 */
   --card-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --input: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --ring: oklch(0.75 0.21 322); /* --color-fuchsia-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-zinc-50 */
   --sidebar-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --sidebar-primary: oklch(0.59 0.26 323); /* --color-fuchsia-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.75 0.21 322); /* --color-fuchsia-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.83 0.13 321); /* --color-fuchsia-300 */
   --chart-2: oklch(0.75 0.21 322); /* --color-fuchsia-400 */
   --chart-3: oklch(0.67 0.26 322); /* --color-fuchsia-500 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.59 0.26 323); /* --color-fuchsia-600 */
   --chart-5: oklch(0.52 0.23 324); /* --color-fuchsia-700 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
     --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 

package/src/css/themes/gray.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Gray theme
+ *
+ * Color tokens for the gray palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(0.98 0 248); /* --color-gray-50 */
   --foreground: oklch(0.13 0.03 262); /* --color-gray-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(0.98 0 248); /* --color-gray-50 */
   --card-foreground: oklch(0.13 0.03 262); /* --color-gray-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.93 0.01 265); /* --color-gray-200 */
   --input: oklch(0.93 0.01 265); /* --color-gray-200 */
   --ring: oklch(0.71 0.02 261); /* --color-gray-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.98 0 248); /* --color-gray-50 */
   --sidebar-foreground: oklch(0.13 0.03 262); /* --color-gray-950 */
   --sidebar-primary: oklch(0.21 0.03 265); /* --color-gray-900 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.93 0.01 265); /* --color-gray-200 */
   --sidebar-ring: oklch(0.71 0.02 261); /* --color-gray-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.646 0.222 41.116); /* --color-orange-600 */
   --chart-2: oklch(0.6 0.118 184.704); /* --color-teal-600 */
   --chart-3: oklch(0.398 0.07 227.392); /* --color-cyan-900 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.13 0.03 262); /* --color-gray-950 */
   --foreground: oklch(0.98 0 248); /* --color-gray-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.627 0.265 303.9); /* --color-purple-500 */
   --chart-5: oklch(0.645 0.246 16.439); /* --color-rose-500 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.13 0.03 262); /* --color-gray-950 */
     --foreground: oklch(0.98 0 248); /* --color-gray-50 */
 

package/src/css/themes/green.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Green theme
+ *
+ * Color tokens for the green palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(1 0 0); /* --color-zinc-50 */
   --foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-zinc-50 */
   --card-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --input: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --ring: oklch(0.841 0.238 128.85); /* --color-lime-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-zinc-50 */
   --sidebar-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --sidebar-primary: oklch(0.648 0.2 131.684); /* --color-lime-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.841 0.238 128.85); /* --color-lime-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.871 0.15 154.449); /* --color-green-300 */
   --chart-2: oklch(0.723 0.219 149.579); /* --color-green-500 */
   --chart-3: oklch(0.627 0.194 149.214); /* --color-green-600 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.527 0.154 150.069); /* --color-green-700 */
   --chart-5: oklch(0.448 0.119 151.328); /* --color-green-800 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
     --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 

package/src/css/themes/indigo.css

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Indigo theme
+ *
+ * Color tokens for the indigo palette across the light (`:root`),
+ * `.dark`, and system-preference variants. Trailing comments note the source
+ * palette swatch for each value.
+ * ------------------------------------------------------------------------- */
+
 :root {
+  /* ----------------------------------------------------------------------
+   * Surfaces & semantic colors
+   * ---------------------------------------------------------------------- */
+
   --background: oklch(1 0 0); /* --color-zinc-50 */
   --foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-zinc-50 */
   --card-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --input: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --ring: oklch(0.68 0.16 277); /* --color-indigo-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-zinc-50 */
   --sidebar-foreground: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --sidebar-primary: oklch(0.51 0.23 277); /* --color-indigo-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.68 0.16 277); /* --color-indigo-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.79 0.1 275); /* --color-indigo-300 */
   --chart-2: oklch(0.68 0.16 277); /* --color-indigo-400 */
   --chart-3: oklch(0.59 0.2 277); /* --color-indigo-500 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
   --foreground: oklch(0.985 0 0); /* --color-zinc-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: oklch(0.51 0.23 277); /* --color-indigo-600 */
   --chart-5: oklch(0.46 0.21 277); /* --color-indigo-700 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.141 0.005 285.823); /* --color-zinc-950 */
     --foreground: oklch(0.985 0 0); /* --color-zinc-50 */