@codefast/ui 0.3.16-canary.3 → 0.4.0-canary.5

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 "./neutral.css";
+@import "./themes/neutral.css";
 @import "./preset.css";

package/src/css/{amber.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/{blue.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/{cyan.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/{emerald.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/{fuchsia.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/{gray.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/{green.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/{indigo.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 */
 

package/src/css/{lime.css → themes/lime.css}

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Lime theme
+ *
+ * Color tokens for the lime 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.85 0.21 129); /* --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.65 0.18 132); /* --color-lime-600 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.92 0.004 286.32); /* --color-zinc-200 */
   --sidebar-ring: oklch(0.85 0.21 129); /* --color-lime-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: oklch(0.9 0.18 127); /* --color-lime-300 */
   --chart-2: oklch(0.85 0.21 129); /* --color-lime-400 */
   --chart-3: oklch(0.77 0.2 131); /* --color-lime-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.65 0.18 132); /* --color-lime-600 */
   --chart-5: oklch(0.53 0.14 132); /* --color-lime-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/{neutral.css → themes/neutral.css}

@@ -1,4 +1,16 @@
+/* -------------------------------------------------------------------------
+ * Neutral theme
+ *
+ * Color tokens for the neutral 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-neutral-50 */
   --foreground: oklch(0.145 0 0); /* --color-neutral-950 */
 
@@ -22,10 +34,18 @@
   --card: oklch(1 0 0); /* --color-neutral-50 */
   --card-foreground: oklch(0.145 0 0); /* --color-neutral-950 */
 
+  /* ----------------------------------------------------------------------
+   * Form & focus
+   * ---------------------------------------------------------------------- */
+
   --border: oklch(0.922 0 0); /* --color-neutral-200 */
   --input: oklch(0.922 0 0); /* --color-neutral-200 */
   --ring: oklch(0.708 0 0); /* --color-neutral-400 */
 
+  /* ----------------------------------------------------------------------
+   * Sidebar
+   * ---------------------------------------------------------------------- */
+
   --sidebar: oklch(0.985 0 0); /* --color-neutral-50 */
   --sidebar-foreground: oklch(0.145 0 0); /* --color-neutral-950 */
   --sidebar-primary: oklch(0.205 0 0); /* --color-neutral-900 */
@@ -35,6 +55,10 @@
   --sidebar-border: oklch(0.922 0 0); /* --color-neutral-200 */
   --sidebar-ring: oklch(0.708 0 0); /* --color-neutral-400 */
 
+  /* ----------------------------------------------------------------------
+   * Charts
+   * ---------------------------------------------------------------------- */
+
   --chart-1: var(--color-blue-300); /* --color-blue-300 */
   --chart-2: var(--color-blue-500); /* --color-blue-500 */
   --chart-3: var(--color-blue-600); /* --color-blue-600 */
@@ -43,6 +67,8 @@
 }
 
 .dark {
+  /* Dark variant — overrides the light tokens above. */
+
   --background: oklch(0.145 0 0); /* --color-neutral-950 */
   --foreground: oklch(0.985 0 0); /* --color-neutral-50 */
 
@@ -85,8 +111,11 @@
   --chart-4: var(--color-blue-700); /* --color-blue-700 */
   --chart-5: var(--color-blue-800); /* --color-blue-800 */
 }
+
 @media (prefers-color-scheme: dark) {
   :root:not(.light) {
+    /* System-preference dark — applied when no explicit .light is set. */
+
     --background: oklch(0.145 0 0); /* --color-neutral-950 */
     --foreground: oklch(0.985 0 0); /* --color-neutral-50 */