@kolkrabbi/kol-theme 0.2.0 → 0.4.0

package/README.md

@@ -19,6 +19,8 @@ In a Vite + Tailwind v4 app, import the barrel after Tailwind:
 
 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.
 
+All KOL rule CSS lives in the `components` cascade layer, so your Tailwind utility classes always win over KOL chrome (`<Input className="hidden sm:block">` behaves as written). Your own unlayered CSS wins over everything KOL ships.
+
 ## 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.

package/kol-components-atoms.css

@@ -737,3 +737,114 @@ a:hover .icon-hover,
   color: var(--kol-surface-on-primary);
   border-color: var(--kol-fg-48);
 }
+
+/* ─────────────────────────────────────────────────────────────────────
+ * Figure — atoms/Figure.jsx
+ *   Caption'd media shell for long-form prose (label above, aspect-locked
+ *   frame, figcaption below). Ported from the monorepo prose sheet; the
+ *   label's text-transform:uppercase was dropped per the KOL no-auto-
+ *   casing rule — author labels in their final case.
+ * ───────────────────────────────────────────────────────────────────── */
+.kol-prose-figure {
+  margin-block: 2rem;
+}
+
+.kol-caption-label {
+  font-family: var(--kol-font-family-mono);
+  font-size: 12px;
+  font-weight: 500;
+  letter-spacing: 0.05em;
+  color: color-mix(in srgb, var(--kol-surface-on-primary) 48%, transparent);
+  margin-block-end: 0.5rem;
+}
+
+.kol-caption-text {
+  font-family: var(--kol-font-family-mono);
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 140%;
+  color: color-mix(in srgb, var(--kol-surface-on-primary) 64%, transparent);
+  margin-block-start: 0.75rem;
+}
+
+/* ── target-file: packages/theme/kol-components-atoms.css ──────────────
+ * Append directly after the .kol-btn-quiet block
+ * (after `.kol-btn-quiet:not(:disabled):hover { opacity: 1; }`). */
+
+/* .kol-btn-pressed — toggle-on state (Button `pressed` prop, aria-pressed).
+ * Hover-level fill held at rest so a pressed toggle reads as lit. Pairs
+ * with `quiet`: Button drops kol-btn-quiet while pressed, giving the
+ * tool-palette dim-at-rest → lit-when-active idiom. */
+.kol-btn-pressed {
+  background-color: var(--kol-fg-08);
+  color: var(--kol-surface-on-primary);
+}
+
+/* ─────────────────────────────────────────────────────────────────────
+ * Type-specimen kit — TARGET: packages/theme/kol-components-atoms.css
+ *   (the two .kol-prose-* rules may alternatively land in the prose
+ *   section of packages/theme/kol-typography.css per the ProsePreview
+ *   lobby spec — pick one home, not both.)
+ *
+ * Ported from kol-monorepo apps/brand/src/components/framework/
+ * kol-framework.css. NOT ported (already in kol-typography.css, richer
+ * DS versions win): .kol-prose pre, .kol-prose code, .kol-prose pre code.
+ * Also already in kol-components-atoms.css: .kol-prose-figure,
+ * .kol-caption-label, .kol-caption-text.
+ * No text-transform rules existed in the source CSS; the components'
+ * Tailwind `uppercase` classes were dropped per the KOL no-auto-casing
+ * rule — author labels/pullouts in their final case.
+ * ───────────────────────────────────────────────────────────────────── */
+
+/* ─── TypeSample — atoms/TypeSample.jsx ───
+   Wrapper padding inlined in the component; adjacent-sibling hairline
+   separates stacked samples. */
+.kol-type-sample + .kol-type-sample {
+  border-top: 1px solid var(--kol-fg-08);
+}
+
+/* ─── TypeSpecCard — atoms/TypeSpecCard.jsx ───
+   Layout inlined in the component; descendant <p> overrides give sample
+   prose 16px rhythm (Preflight zeroes <p> margin). */
+.kol-type-spec-sample p { margin: 0 0 16px; }
+.kol-type-spec-sample p:last-child { margin-bottom: 0; }
+
+/* ─── ProsePreview — atoms/ProsePreview.jsx ───
+   Prose chrome beyond the base .kol-prose contract. */
+.kol-prose-indented {
+  padding-left: 32px;
+  border-left: 1px solid var(--kol-fg-16);
+}
+
+.kol-prose-pullout {
+  padding: 16px 0;
+  margin: 32px 0;
+  border-top: 1px solid var(--kol-fg-08);
+  border-bottom: 1px solid var(--kol-fg-08);
+}
+
+/* =============================================================================
+ * TextPressure  (atom)
+ * append to packages/theme/kol-components-atoms.css
+ *
+ * Only the outlined-ghost layer lives here — it needs a ::after pseudo-element
+ * and -webkit-text-stroke, neither expressible in Tailwind or inline style.
+ * Everything else (layout, sizing, weight) is Tailwind utilities / inline vars
+ * on the JSX. Stroke color comes in through the inline `--kol-text-pressure-
+ * stroke` custom property (defaulted here so the rule is standalone-safe).
+ * ============================================================================= */
+
+.kol-text-pressure--stroke .kol-text-pressure-char {
+  position: relative;
+}
+
+.kol-text-pressure--stroke .kol-text-pressure-char::after {
+  content: attr(data-char);
+  position: absolute;
+  left: 0;
+  top: 0;
+  color: transparent;
+  z-index: -1;
+  -webkit-text-stroke-width: 3px;
+  -webkit-text-stroke-color: var(--kol-text-pressure-stroke, var(--kol-accent-primary));
+}

package/kol-components-molecules.css

@@ -303,3 +303,49 @@
   outline: 1px solid var(--kol-fg-emphasis);
   outline-offset: -2px;
 }
+
+/* =============================================================================
+ * Color-doc widget chrome — ColorRamp · SpectrumGrid
+ *
+ * Almost everything is Tailwind/inline in the components; only the ONE bit
+ * Tailwind can't express against a dynamic grid template lives here: the
+ * SpectrumGrid responsive narrowing. Fold into packages/theme (e.g.
+ * kol-components-organisms.css) when these graduate from the lobby.
+ *
+ * How it works: SpectrumGrid declares its template inline with var() fallbacks —
+ *   grid-template-columns: var(--kol-sg-label-w, 100px) repeat(N, minmax(0,1fr));
+ *   gap: var(--kol-sg-gap, 4px);
+ * so it renders correctly with NO stylesheet loaded. On narrow viewports we just
+ * re-declare those two custom properties on the grid CLASS; the inline var()
+ * reads pick them up (the class provides the value, so a media-query override
+ * cascades — there's no competing inline *set* of the same property). The
+ * per-cell hex readout is hidden separately via Tailwind `max-[900px]:hidden`.
+ * ============================================================================= */
+
+@media (max-width: 900px) {
+  .kol-spectrum-grid {
+    --kol-sg-label-w: 72px;
+    --kol-sg-gap: 2px;
+  }
+}
+
+/* SwatchControls chrome — the only bespoke CSS the component needs.
+ *
+ * The paint chips + sample chip reuse ColorSwatch's `halo` variant for the
+ * tuned double-ring, so the ONLY rule left is the NoneMarker's "set to none"
+ * affordance: a red diagonal slash on white (a two-stop 45° gradient) over a
+ * themed 1px ring. Neither is a Tailwind utility, so it lands here.
+ *
+ * Append to packages/theme/kol-components-molecules.css. */
+.kol-swatch-none-marker {
+  background: linear-gradient(
+    45deg,
+    #fff 0%,
+    #fff 42%,
+    #DC2626 42%,
+    #DC2626 58%,
+    #fff 58%,
+    #fff 100%
+  );
+  box-shadow: 0 0 0 1px var(--kol-fg-32);
+}

package/kol-components-organisms.css

@@ -45,6 +45,17 @@
   scrollbar-width: none;
   border: 1px solid var(--kol-fg-08);
   border-radius: 4px;
+  /* Scroll affordance: with the scrollbar hidden, a clipped table reads as
+   * cut-off data on narrow viewports. Edge shadows appear only on the
+   * scrollable side (surface-colored covers ride the content and mask them
+   * at the extremes). */
+  background:
+    linear-gradient(to right, var(--kol-surface-primary) 40%, transparent) left / 32px 100%,
+    linear-gradient(to left, var(--kol-surface-primary) 40%, transparent) right / 32px 100%,
+    linear-gradient(to right, var(--kol-fg-16), transparent) left / 14px 100%,
+    linear-gradient(to left, var(--kol-fg-16), transparent) right / 14px 100%;
+  background-repeat: no-repeat;
+  background-attachment: local, local, scroll, scroll;
 }
 
 .kol-table-wrapper::-webkit-scrollbar { display: none; }
@@ -218,3 +229,192 @@
     padding: 6px 10px;
   }
 }
+
+/*
+ * ─────────────────────────────────────────────────────────────────────
+ * FeatureSplit — src/components/organisms/FeatureSplit.jsx
+ * ─────────────────────────────────────────────────────────────────────
+ *
+ * Destined for kol-components-organisms.css.
+ *
+ * Structural (applied by FeatureSplit.jsx; do not use directly):
+ *   .kol-feature-split                  section — surface bg + ink
+ *   .kol-feature-split-kicker           mono eyebrow, accent color
+ *   .kol-feature-split-pull             display pull headline
+ *   .kol-feature-split-pull em          italic accent inside the pull
+ *   .kol-feature-split-body             lede paragraph, 72% ink
+ *   .kol-feature-split-meta             stats strip — hairline top border
+ *   .kol-feature-split-meta-num         stat number
+ *   .kol-feature-split-meta-label       stat label — mono, 48% ink
+ *   .kol-feature-split-visual img       cover-fit media
+ *   .kol-feature-split-visual-veil      bottom gradient (caption legibility)
+ *   .kol-feature-split-visual-caption   mono caption over the media
+ *
+ * Port notes (from apps/brand kol-site.css `.site-feature*`):
+ *   - text-transform: uppercase DROPPED from kicker / meta-label / caption —
+ *     KOL rule: author casing at the call site.
+ *   - Hardcoded "Right Grotesk" / "Right Grotesk Text" / "Right Grotesk Wide"
+ *     families → var(--kol-font-family-sans) (this theme tokenizes only
+ *     sans / sans-narrow / sans-compact; no Text/Wide tokens).
+ *   - App `--kol-pad-page-*` padding and the shared `.site-*` full-bleed
+ *     rule moved to Tailwind utilities in the JSX (`fullBleed` prop).
+ */
+
+/* =============================================================================
+ * FeatureSplit
+ * ============================================================================= */
+
+.kol-feature-split {
+  background: var(--kol-surface-primary);
+  color: var(--kol-surface-on-primary);
+}
+
+.kol-feature-split-kicker {
+  font-family: var(--kol-font-family-mono, monospace);
+  font-size: 18px;
+  font-weight: 600;
+  letter-spacing: 0.14em;
+  color: var(--kol-accent-primary);
+}
+
+.kol-feature-split-pull {
+  margin: 0;
+  font-family: var(--kol-font-family-sans);
+  font-weight: 700;
+  font-size: clamp(40px, 5.5vw, 72px);
+  line-height: 1.05;
+  letter-spacing: -0.02em;
+  color: var(--kol-surface-on-primary);
+}
+
+.kol-feature-split-pull em {
+  font-family: var(--kol-font-family-sans);
+  font-feature-settings: "liga", "dlig";
+  font-weight: 700;
+  font-style: italic;
+  color: var(--kol-accent-primary);
+}
+
+.kol-feature-split-body {
+  margin: 0;
+  font-family: var(--kol-font-family-sans);
+  font-weight: 400;
+  font-size: 16px;
+  line-height: 1.6;
+  color: color-mix(in srgb, var(--kol-surface-on-primary) 72%, transparent);
+}
+
+.kol-feature-split-meta {
+  border-top: 1px solid color-mix(in srgb, var(--kol-surface-on-primary) 8%, transparent);
+}
+
+.kol-feature-split-meta-num {
+  font-family: var(--kol-font-family-sans);
+  font-weight: 900;
+  font-size: 32px;
+  line-height: 1;
+  letter-spacing: -0.02em;
+  color: var(--kol-surface-on-primary);
+}
+
+.kol-feature-split-meta-label {
+  font-family: var(--kol-font-family-mono, monospace);
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.14em;
+  color: color-mix(in srgb, var(--kol-surface-on-primary) 48%, transparent);
+}
+
+.kol-feature-split-visual img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.kol-feature-split-visual-veil {
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    180deg,
+    transparent 0%,
+    transparent 60%,
+    color-mix(in srgb, var(--kol-surface-primary) 48%, transparent) 100%
+  );
+  pointer-events: none;
+}
+
+.kol-feature-split-visual-caption {
+  position: absolute;
+  left: 24px;
+  bottom: 24px;
+  font-family: var(--kol-font-family-mono, monospace);
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.14em;
+  color: color-mix(in srgb, var(--kol-surface-on-primary) 80%, transparent);
+}
+
+/*
+ * ─────────────────────────────────────────────────────────────────────
+ * FullBleedHero — src/components/organisms/FullBleedHero.jsx
+ * ─────────────────────────────────────────────────────────────────────
+ *
+ * Destined for kol-components-organisms.css.
+ *
+ * Structural (applied by FullBleedHero.jsx; do not use directly):
+ *   .kol-full-bleed-hero          section root — surface bg behind the media
+ *   .kol-full-bleed-hero-media    cover-fit media layer (Image / HlsVideo /
+ *                                 plain <video> / caller-supplied node)
+ *
+ * Why CSS and not Tailwind for the media layer: the Image molecule bakes
+ * `max-w-full h-auto` into every <img>; an inline `h-full` utility can't
+ * reliably out-cascade `h-auto` (same utilities layer — stylesheet order,
+ * not class order, decides). This unlayered rule wins over Tailwind's
+ * layered utilities and pins cover-fill identically for img, video, and
+ * caller-supplied media nodes.
+ */
+
+/* =============================================================================
+ * FullBleedHero
+ * ============================================================================= */
+
+.kol-full-bleed-hero {
+  background: var(--kol-surface-primary);
+}
+
+.kol-full-bleed-hero-media {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: center;
+}
+
+/* =============================================================================
+ * FeaturedCarousel — src/components/organisms/FeaturedCarousel.jsx
+ * =============================================================================
+ *
+ * Append to packages/theme/kol-components-organisms.css.
+ *
+ * FeaturedCarousel rebuilds on the shared Carousel *core* — it reuses the
+ * `.kol-embla*` chrome verbatim (viewport / container / slide / controls /
+ * `.is-slides` wide-slide width), so NONE of that is redefined here. Frame,
+ * progress bar, and glass positioning are Tailwind utilities on the JSX.
+ *
+ * The one rule that can't be a utility: the media layer. The Image molecule
+ * bakes `h-auto` (a Tailwind layer utility), so an inline `h-full` can't
+ * reliably out-cascade it — the same reason FullBleedHero uses a theme rule.
+ * This unlayered rule wins and pins image / video / caller-node media as a
+ * cover-fit background over the frame.
+ */
+
+.kol-featured-carousel-media {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: center;
+}

package/kol-theme.css

@@ -25,19 +25,25 @@
  *   (NEW)                 → kol-utilities.css   (curated slice of _new-css/utilities.css)
  */
 
-@import "./kol-base-tokens.css";
-@import "./kol-color.css";
-@import "./kol-opacity.css";
-@import "./kol-opaque.css";
-@import "./kol-typography.css";
-@import "./kol-typography-mono.css";
-@import "./kol-type-mono-classes.css";
-@import "./kol-utilities.css";
-@import "./kol-components-atoms.css";
-@import "./kol-components-molecules.css";
-@import "./kol-components-organisms.css";
+/* Everything KOL ships lives in the `components` cascade layer. Tailwind v4
+ * declares `@layer theme, base, components, utilities` — layering here means
+ * consumer utility classes (a later layer) can always override KOL chrome,
+ * while KOL still beats preflight (`base`). Unlayered consumer CSS wins over
+ * all of it, as it should. */
+@import "./kol-base-tokens.css" layer(components);
+@import "./kol-color.css" layer(components);
+@import "./kol-opacity.css" layer(components);
+@import "./kol-opaque.css" layer(components);
+@import "./kol-typography.css" layer(components);
+@import "./kol-typography-mono.css" layer(components);
+@import "./kol-type-mono-classes.css" layer(components);
+@import "./kol-utilities.css" layer(components);
+@import "./kol-components-atoms.css" layer(components);
+@import "./kol-components-molecules.css" layer(components);
+@import "./kol-components-organisms.css" layer(components);
 
 /* Theme-level design tokens */
+@layer components {
 :root {
   /* Spacing scale (4px base) */
   --kol-spacing-1: 0.25rem;    /* 4px */
@@ -108,3 +114,4 @@
   --kol-shadow-xl: 0 20px 25px rgba(255, 255, 255, 0.1);
   --kol-shadow-inner: inset 0 2px 4px rgba(255, 255, 255, 0.04);
 }
+}

package/kol-typography.css

@@ -1088,3 +1088,45 @@
   --font-narrow:  'Right Grotesk Narrow', 'Right Grotesk', sans-serif;
   /* --font-mono lives in kol-typography-mono.css — keeps mono concerns in one file. */
 }
+
+/* TARGET: packages/theme/kol-typography.css — append to the `.kol-prose` section
+ * ---------------------------------------------------------------------------
+ * PortableTextRenderer (organism) leans on three prose hooks this repo's prose
+ * sheet is missing. Figure's `.kol-prose-figure` / `.kol-caption-label` /
+ * `.kol-caption-text` already exist; these three do not. The renderer degrades
+ * gracefully without them (segmentTitle → plain inline text, caption → normal
+ * paragraph, links → inherited color), so this is polish, not a hard dep.
+ *
+ * NOTE ON PLACEMENT: these are prose *typography* classes, so their home is
+ * kol-typography.css, NOT the kol-components-{atoms,molecules,organisms}.css
+ * component-chrome sheets. Flagged so it lands in the right file.
+ */
+
+/* inline mark — emphasised run inside a paragraph */
+.kol-segment-title {
+  font-family: var(--kol-font-family-sans-compact);
+  font-weight: 500;
+  color: var(--kol-surface-on-primary);
+}
+
+/* standalone caption block (the `caption` block type) */
+.kol-prose .caption {
+  margin: -12px 0 24px;
+  font-family: var(--kol-font-family-mono);
+  font-size: 12px;
+  line-height: 16px;
+  letter-spacing: 0.02em;
+  color: var(--kol-fg-48, color-mix(in srgb, var(--kol-surface-on-primary) 48%, transparent));
+}
+
+/* inline links (the `link` mark) */
+.kol-prose a {
+  color: inherit;
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  text-decoration-color: var(--kol-fg-32, color-mix(in srgb, var(--kol-surface-on-primary) 32%, transparent));
+  transition: text-decoration-color 0.15s ease;
+}
+.kol-prose a:hover {
+  text-decoration-color: currentColor;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-theme",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "KOL (Kolkrabbi) design-system tokens + base CSS — brand-neutral. The canonical token/cascade layer every other KOL package and consumer builds on.",
   "license": "MIT",
   "type": "module",