@kolkrabbi/kol-framework 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @kolkrabbi/kol-framework
+
+The KOL app shell — sidenav, layout, theme toggle, footer, and heroes, plus the brand color layer. Site chrome shared across KOL apps.
+
+`SideNav` takes its nav data as props (`navTree` + `getActivePage`) so the navigation tree stays app-local.
+
+## Install
+
+```sh
+npm i @kolkrabbi/kol-framework @kolkrabbi/kol-component @kolkrabbi/kol-theme
+# react, react-dom, react-router-dom are peers
+```
+
+## Use
+
+```css
+@import "tailwindcss";
+@import "@kolkrabbi/kol-theme";
+@import "@kolkrabbi/kol-framework/kol-brand-color.css";
+@import "@kolkrabbi/kol-framework/kol-framework.css";
+```
+
+```jsx
+import { AppShell } from '@kolkrabbi/kol-framework'
+import { NAV_TREE, getActivePage } from './sidebars.config'
+
+<AppShell navTree={NAV_TREE} getActivePage={getActivePage} />
+```
+
+Exports: `AppShell`, `SideNav`, `ThemeToggle`, `Layout`, `PageSection`, `PortalFooter`, `ScrollToTop`, `BrandHero`, `SubPageHero`.

package/kol-brand-color.css

@@ -0,0 +1,151 @@
+/**
+ * kol-brand-color.css — Kolkrabbi brand color layer (the `apps/brand` identity).
+ *
+ * Layers ON TOP of `kol-color.css` (the DS theme): the DS ships brand-neutral
+ * (accent defaults to ink-on-surface), this file binds the Kolkrabbi identity.
+ * Imported explicitly by `index.css` after the theme umbrella.
+ *
+ * Token naming: "brand" is the APP (`apps/brand`), never a token prefix. Hue
+ * ramps are DS palette primitives (`--kol-color-{hue}-*`); the identity roles
+ * are the DS accent (`--kol-accent-*`), rebound here from neutral to Kolkrabbi
+ * yellow. In a scaffolded project this file is added by `init-client`.
+ *
+ * Anchors: ★ marks the canonical stop matching the source design references.
+ * Anchors vary per ramp — intentional, not a symmetry rule.
+ */
+
+/* =============================================================================
+ * PALETTE PRIMITIVES — hue ramps (DS palette layer)
+ *
+ * Five hue families, 5 stops each (100-500). Cream is a utility neutral, not
+ * identity but project-flavored. Grey lives here too as the project's fixed
+ * neutral ramp (theme-independent — used by the slide-deck system); consumers
+ * that need a theme-aware opaque grey use the canonical `--kol-oq-*` scale.
+ * ============================================================================= */
+
+:root {
+  /* Yellow — pure-yellow lock, no orange contamination. ★ anchor at 300. */
+  --kol-color-yellow-100: #FFEA57;
+  --kol-color-yellow-200: #FFDF43;
+  --kol-color-yellow-300: #FFCF33; /* anchor */
+  --kol-color-yellow-400: #FFBC1F;
+  --kol-color-yellow-500: #FFA113;
+
+  /* Red — rust / terracotta. ★ anchor at 200 (light-side). */
+  --kol-color-red-100: #CC7762;
+  --kol-color-red-200: #AD5038; /* anchor */
+  --kol-color-red-300: #913F2B;
+  --kol-color-red-400: #662C1E;
+  --kol-color-red-500: #522418;
+
+  /* Blue — saturated steel into deep navy. ★ anchor at 400. */
+  --kol-color-blue-100: #497DA2;
+  --kol-color-blue-200: #3F6485;
+  --kol-color-blue-300: #314152;
+  --kol-color-blue-400: #222D3D; /* anchor */
+  --kol-color-blue-500: #181F29;
+
+  /* Orange — hybrid: light tints + canonical anchor at 300. */
+  --kol-color-orange-100: #F5CF81;
+  --kol-color-orange-200: #E3A054;
+  --kol-color-orange-300: #DF760B; /* anchor */
+  --kol-color-orange-400: #A54209;
+  --kol-color-orange-500: #7C2900;
+
+  /* Teal — cool counterpoint. ★ anchor at 300. */
+  --kol-color-teal-100: #9BCCCD;
+  --kol-color-teal-200: #6FB6B7;
+  --kol-color-teal-300: #49A0A2; /* anchor */
+  --kol-color-teal-400: #387E7F;
+  --kol-color-teal-500: #275A5B;
+
+  /* Cream — utility neutral, project-flavored. */
+  --kol-color-cream-100: #FAF7F0;
+  --kol-color-cream-200: #F5F0E6;
+  --kol-color-cream-300: #F5EBD8;
+  --kol-color-cream-400: #F0E0C0;
+  --kol-color-cream-500: #EBD5A9;
+
+  /* Grey — fixed 10-stop neutral (theme-independent; slide-deck scale). */
+  --grey-50:  #FCFBFB;
+  --grey-100: #EBEBEB;
+  --grey-200: #DBDBDB;
+  --grey-300: #A3A3A4;
+  --grey-400: #5B5B5D;
+  --grey-500: #363639;
+  --grey-600: #2E2E30;
+  --grey-700: #242427;
+  --grey-800: #1B1B1E;
+  --grey-900: #131316;
+}
+
+/* =============================================================================
+ * IDENTITY — DS accent rebind (theme pairs)
+ *
+ * kol-color.css defaults --kol-accent-* to ink-on-surface (brand-neutral).
+ * This file rebinds the accent role to the Kolkrabbi yellow identity. Edit
+ * these lines to rebrand without touching any consumer — buttons, focus rings,
+ * sidenav active dots all switch from ink to brand once this loads.
+ * Pairs ensure ink-on-fill contrast holds across the system.
+ * ============================================================================= */
+
+:root {
+  --kol-accent-primary:        var(--kol-color-yellow-300); /* dominant identity color */
+  --kol-accent-on-primary:     var(--kol-color-blue-400);   /* ink on accent-primary */
+  --kol-accent-primary-strong: var(--kol-color-yellow-400); /* hover/active */
+  --kol-accent-secondary:      var(--kol-color-red-200);    /* secondary identity color */
+  --kol-accent-on-secondary:   var(--kol-color-cream-100);  /* ink on accent-secondary */
+}
+
+/* =============================================================================
+ * TAILWIND CONTRACT — palette + accent exposures
+ *
+ * Tailwind v4 reads @theme blocks from any imported CSS. Generates
+ * `bg-kol-yellow-300`, `bg-kol-accent-primary`, etc.
+ * ============================================================================= */
+
+@theme {
+  /* Identity (accent) */
+  --color-kol-accent-primary:     var(--kol-accent-primary);
+  --color-kol-accent-on-primary:  var(--kol-accent-on-primary);
+  --color-kol-accent-secondary:   var(--kol-accent-secondary);
+  --color-kol-accent-on-secondary: var(--kol-accent-on-secondary);
+
+  /* Palette ramp access — direct stops for one-off / data-viz / chart needs. */
+  --color-kol-yellow-100:     var(--kol-color-yellow-100);
+  --color-kol-yellow-200:     var(--kol-color-yellow-200);
+  --color-kol-yellow-300:     var(--kol-color-yellow-300);
+  --color-kol-yellow-400:     var(--kol-color-yellow-400);
+  --color-kol-yellow-500:     var(--kol-color-yellow-500);
+
+  --color-kol-red-100:        var(--kol-color-red-100);
+  --color-kol-red-200:        var(--kol-color-red-200);
+  --color-kol-red-300:        var(--kol-color-red-300);
+  --color-kol-red-400:        var(--kol-color-red-400);
+  --color-kol-red-500:        var(--kol-color-red-500);
+
+  --color-kol-blue-100:       var(--kol-color-blue-100);
+  --color-kol-blue-200:       var(--kol-color-blue-200);
+  --color-kol-blue-300:       var(--kol-color-blue-300);
+  --color-kol-blue-400:       var(--kol-color-blue-400);
+  --color-kol-blue-500:       var(--kol-color-blue-500);
+
+  --color-kol-orange-100:     var(--kol-color-orange-100);
+  --color-kol-orange-200:     var(--kol-color-orange-200);
+  --color-kol-orange-300:     var(--kol-color-orange-300);
+  --color-kol-orange-400:     var(--kol-color-orange-400);
+  --color-kol-orange-500:     var(--kol-color-orange-500);
+
+  --color-kol-teal-100:       var(--kol-color-teal-100);
+  --color-kol-teal-200:       var(--kol-color-teal-200);
+  --color-kol-teal-300:       var(--kol-color-teal-300);
+  --color-kol-teal-400:       var(--kol-color-teal-400);
+  --color-kol-teal-500:       var(--kol-color-teal-500);
+
+  /* Cream — utility neutral. */
+  --color-kol-cream-100:      var(--kol-color-cream-100);
+  --color-kol-cream-200:      var(--kol-color-cream-200);
+  --color-kol-cream-300:      var(--kol-color-cream-300);
+  --color-kol-cream-400:      var(--kol-color-cream-400);
+  --color-kol-cream-500:      var(--kol-color-cream-500);
+}