@kolkrabbi/kol-theme 0.42.2 → 0.43.0

package/kol-color.css

@@ -92,6 +92,20 @@
   --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);
+  /* The QUIET ring — 1px, inset, for dense rows where the loud ring's 2px
+   * offset would bloom over its neighbours (nav rail leaves today).
+   *
+   * It exists so the pair is a real OFF SWITCH (FocusRingsInConsumers, kol-fxr
+   * 2026-08-15, user ruling): --kol-focus-ring alone was only ever half of one,
+   * because the rails hardcoded --kol-fg-32 and never read it, so a consumer
+   * setting it transparent lost button rings and kept rail rings. Set BOTH to
+   * transparent and the system is genuinely off — no `outline: none !important`
+   * in consumer CSS, which is the local override this replaces.
+   *
+   * Default is --kol-fg-32, exactly what the rails already drew, so minting
+   * this changes NOTHING visually. Both rings are white (--kol-accent-primary
+   * resolves to --kol-surface-on-primary); the two differ in weight, not hue. */
+  --kol-focus-ring-quiet: var(--kol-fg-32);
 }
 
 :root[data-theme="light"] {

package/kol-components-atoms.css

@@ -706,6 +706,23 @@
   padding: 4px 0 4px;
 }
 
+/* The rail leaf had NO focus treatment at all (ThreeColumnEditorShell §3,
+ * kol-fxr 2026-08-15) — only .is-active and its dot — so it fell through to
+ * the browser's default ring, which a user reported as "a weird highlight bug".
+ *
+ * INSET 1px, matching its sibling .shell-nav-item (kol-components-workshop.css)
+ * rather than .kol-btn's `2px / offset 2px`: an offset ring blooms OUTSIDE a
+ * dense nav row and collides with the rows above and below. Same element role,
+ * same treatment — this closes an inconsistency, it does not mint a policy.
+ *
+ * NB this is deliberately NOT an answer to FocusRingsInConsumers, which asks
+ * whether a consumer can switch the whole focus system off with one token.
+ * That is a live ruling; this rule only stops one leaf being the odd one out. */
+.kol-sidenav-link:focus-visible {
+  outline: 1px solid var(--kol-focus-ring-quiet);
+  outline-offset: -1px;
+}
+
 .kol-sidenav-link.is-active {
   color: var(--kol-surface-on-primary);
 }
@@ -787,20 +804,82 @@ a:hover .icon-hover,
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  padding: 0.5rem;
+  /* PINNED SQUARE — the box never moves with glyph size (user law 2026-07-28,
+   * the same rule .kol-icon-frame-{sm,md,lg} obeys at 28/32/36). This class
+   * derived its size from `padding: 0.5rem` + whatever glyph it was handed, so
+   * a 14px icon silently produced a 30px control off the ladder. 32px is md on
+   * both the icon-frame squares and the button ladder (26/32/40), and it is
+   * exactly what 0.5rem + a 16px glyph already measured — CodeBlock's button
+   * does not move. */
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  /* rungs below; the base stays md so a class used without one still lands
+   * on the ladder rather than collapsing to its content */
   background: color-mix(in srgb, var(--kol-surface-on-primary) 2%, transparent);
   border: none;
   border-radius: var(--kol-radius-sm);
-  color: color-mix(in srgb, var(--kol-surface-on-primary) 72%, transparent);
+  /* ink on the OPAQUE scale (user ruling 2026-08-15): a 72%-transparent glyph
+   * over a photograph lets the image through the strokes and reads as mush.
+   * oq is a baked grey — same value, nothing bleeds through. */
+  color: var(--kol-oq-72);
   cursor: pointer;
   transition: background-color var(--kol-transition-base), color var(--kol-transition-base);
 }
 
 .kol-copy-btn:hover {
   background: color-mix(in srgb, var(--kol-surface-on-primary) 8%, transparent);
+  /* FULL ink on hover — no mix, no stop below 100% */
   color: var(--kol-surface-on-primary);
 }
 
+/* the click step, missing since this class was written — hover had a stop,
+ * pressed had none, so the button gave no feedback on the way down. */
+.kol-copy-btn:active {
+  background: color-mix(in srgb, var(--kol-surface-on-primary) 12%, transparent);
+  color: var(--kol-surface-on-primary);
+}
+
+/* --grey's ladder runs DOWN, not up (user ruling 2026-08-15). oq mixes ink
+ * INTO the surface, so a higher stop is a LIGHTER box — the wrong direction for
+ * a control that has to hold its own against a bright image. Rest is oq-12,
+ * hover steps darker to oq-08, and the click lands on --kol-surface-primary
+ * itself: fully opaque, no mix, the strongest the scale goes. */
+.kol-copy-btn--grey:hover {
+  background: var(--kol-oq-08);
+  color: var(--kol-surface-on-primary);
+}
+.kol-copy-btn--grey:active {
+  background: var(--kol-surface-primary);
+  color: var(--kol-surface-on-primary);
+}
+
+/* --grey — the same control, over MEDIA instead of over a surface
+ * (user ruling 2026-08-15). The base rule and every fg-scale variant are
+ * TRANSLUCENT, so they are content-dependent: a light wash vanishes on a light
+ * photo, a dark scrim vanishes on a dark one. There is no stop that survives
+ * both, because the problem is the transparency, not the value.
+ *
+ * `oq` is the answer and kol-opaque.css:11 already says so — "use oq when you
+ * need an OPAQUE grey (cover layer, CHIP OVER A PHOTO, any fill that must hide
+ * what's behind it)". It mixes into the surface instead of into transparent, so
+ * the control reads identically whatever the image does.
+ *
+ * The 12 / 16 / 24 ladder is not new — it is exactly .kol-btn-grey's, and
+ * `grey` is already this system's name for an oq fill (kol-btn-grey,
+ * kol-dd-trigger--grey, kol-icon-frame-grey). Same name, same stops. */
+/* the same three squares as .kol-icon-frame-{sm,md,lg}. The SOLO glyph ladder
+ * (16/20/24) pairs 1:1 with them and ActionButton resolves it — the pairing is
+ * never re-typed at a call site. */
+.kol-copy-btn-sm { width: 28px; height: 28px; }
+.kol-copy-btn-md { width: 32px; height: 32px; }
+.kol-copy-btn-lg { width: 36px; height: 36px; }
+
+.kol-copy-btn--grey {
+  background: var(--kol-oq-12);
+}
+
+
 /* ─────────────────────────────────────────────────────────────────────
  * Figure — atoms/Figure.jsx
  *   Caption'd media shell for long-form prose (label above, aspect-locked

package/kol-components-molecules.css

@@ -517,8 +517,14 @@
   color: var(--kol-fg-emphasis);
 }
 
+/* Reads the quiet ring token so the segmented strip is part of the system-wide
+ * focus off switch (FocusRingsInConsumers, 2026-08-15). This is the LAST
+ * hardcoded focus colour in the theme — with it, `--kol-focus-ring` +
+ * `--kol-focus-ring-quiet` set to transparent turns every ring off, which is
+ * the whole point of the pair. Offset stays -2px: the cell's own inset, not
+ * the rails' -1px. */
 .kol-seg-cell:focus-visible {
-  outline: 1px solid var(--kol-fg-emphasis);
+  outline: 1px solid var(--kol-focus-ring-quiet);
   outline-offset: -2px;
 }
 
@@ -692,13 +698,51 @@
   margin-block-end: 0.75rem;
 }
 
-/* in-frame position only — the button IS the CopyButton atom (.kol-copy-btn
- * carries the 32×32 look, promoted there 2026-08-09); offset 0.75rem into
- * the 1rem pad. */
+/* ─────────────────────────────────────────────────────────────────────
+ * FRAME CONTROL — a control that floats in a host frame's corner
+ * (user ruling 2026-08-15).
+ *
+ * Position only. The control IS an existing atom — CopyButton (.kol-copy-btn
+ * carries the 32×32 look, promoted 2026-08-09) or IconFrame — and this rule
+ * says nothing about how it looks, only where it sits.
+ *
+ * It exists because the same 12px corner was hand-written three times and
+ * shared zero times: `.kol-codeblock-copy` as `0.75rem`, and MediaCard twice
+ * inline as `absolute top-3 right-3` (download) and `absolute top-3 left-3`
+ * (select). Same value, two spellings, three copies — the 4px-five-ways
+ * problem one layer up.
+ *
+ * NOT `overlay`. That word is ruled below (:704) and means the ONE floating
+ * surface; this is in-frame chrome, which is a different thing.
+ *
+ * The inset spells --kol-spacing-3 (12px) rather than a literal, per the
+ * tokens law. Default corner is top-right; the modifiers move it.
+ *
+ * `.kol-codeblock-copy` is kept as a DEPRECATED ALIAS so existing callers do
+ * not break — it is the same rule, not a second one. New hosts use
+ * `.kol-frame-control`. */
+.kol-frame-control,
 .kol-codeblock-copy {
   position: absolute;
-  top: 0.75rem;
-  right: 0.75rem;
+  top: var(--kol-spacing-3);
+  right: var(--kol-spacing-3);
+}
+
+.kol-frame-control--top-left {
+  right: auto;
+  left: var(--kol-spacing-3);
+}
+
+.kol-frame-control--bottom-right {
+  top: auto;
+  bottom: var(--kol-spacing-3);
+}
+
+.kol-frame-control--bottom-left {
+  top: auto;
+  right: auto;
+  bottom: var(--kol-spacing-3);
+  left: var(--kol-spacing-3);
 }
 
 /* ─────────────────────────────────────────────────────────────────────
@@ -744,3 +788,31 @@
    * another product. --kol-shadow-overlay was added for this an hour earlier
    * and is deleted with it: it solved the wrong problem. */
 }
+
+/* ── Section — .kol-section-* ─────────────────────────────────────────────
+ * Between-siblings rhythm for stacked inspector sections (InspectorSectionRhythm,
+ * filed from kol-fxr 2026-08-15).
+ *
+ * Section's own anatomy — the label and the `gap-2` inner stack — stays as
+ * Tailwind utilities in Section.jsx. Only the BETWEEN-siblings rule lives here,
+ * because `+` cannot be expressed as a utility class: every consumer stacking
+ * sections in a rail was therefore forced to invent a hook class and retype
+ * this rule. kol-fxr's `.kol-params-section` block is the evidence, and it
+ * dies on adopt.
+ *
+ * The rule is on the ADJACENT PAIR, not on the element, so the first section
+ * in a stack never carries a stray top border and no consumer needs
+ * `:not(:first-child)`.
+ *
+ * DENSITY WAS NOT ADDED. The ticket asked for a `density` prop wanting "a
+ * tighter inner gap than gap-2" — but the consumer's own override is
+ * `gap: 0.5rem`, which IS `gap-2`. The rule it maintains locally is a no-op
+ * against Section's shipped default, so there is no second density to name
+ * until a consumer produces a value that actually differs. */
+.kol-section--divided + .kol-section--divided {
+  border-top: 1px solid var(--kol-fg-08);
+  /* 20px below the rule; the 20px above falls out of the rail body's own
+   * gap-5, so a symmetric space–divider–space lands without this file
+   * knowing anything about the rail. */
+  padding-top: var(--kol-spacing-5);
+}

package/kol-components-organisms.css

@@ -614,3 +614,16 @@
 .kol-table-sort svg { opacity: 0.25; transition: opacity var(--kol-transition-fast); }
 .kol-table-sort:hover svg { opacity: 0.6; }
 [aria-sort] .kol-table-sort svg { opacity: 1; }
+
+/* ─────────────────────────────────────────────────────────────────────
+ * ContentCollection — src/organisms/ContentCollection.jsx (2026-08-15)
+ * The enter stagger the collection owns; cards never animate themselves.
+ * Delay is set per item inline; the curve is the house token. */
+.kol-collection-item {
+  animation: kol-collection-in 300ms var(--kol-ease-house) both;
+}
+
+@keyframes kol-collection-in {
+  from { opacity: 0; transform: translateY(6px); }
+  to   { opacity: 1; transform: none; }
+}

package/kol-components-workshop.css

@@ -364,8 +364,11 @@
   color: var(--kol-surface-on-primary);
 }
 
+/* Reads the quiet ring token, not --kol-fg-32 directly, so this rail is part
+ * of the system-wide focus off switch (FocusRingsInConsumers, 2026-08-15).
+ * Same value as before — this is a rewiring, not a restyle. */
 .shell-nav-item:focus-visible {
-  outline: 1px solid var(--kol-fg-32);
+  outline: 1px solid var(--kol-focus-ring-quiet);
   outline-offset: -1px;
 }
 

package/kol-theme.css

@@ -87,6 +87,17 @@
    * indent instead of retyping it. */
   --kol-pad-rail-row-x: 1.25rem;
 
+  /* CARD padding (2026-08-15, content-card ruling) — flat, stepped by the
+   * card's `size` prop, never by breakpoint. 12/16/24. */
+  --kol-pad-card-sm: 0.75rem;
+  --kol-pad-card-md: 1rem;
+  --kol-pad-card-lg: 1.5rem;
+
+  /* The house curve (2026-08-15) — the easing the cards actually use; was
+   * hardcoded in 5 files before this token existed. Curve only, no duration:
+   * it pairs with whatever duration the motion needs. */
+  --kol-ease-house: cubic-bezier(0.16, 1, 0.3, 1);
+
   /* Content widths (2026-07-28; panel added 2026-07-30) — ONE frame, three
    * inner caps (chess law). Every page: mx-auto max-w-shell + the one padding
    * rhythm, content LEFT-ANCHORED inside. Width is a content decision, never a

package/kol-typography.css

@@ -815,8 +815,14 @@
   font-weight: 600;
 }
 
-/* .kol-sans-display-03 deferred — orphan in current consumers. Token defined.
- * Add the class when a consumer needs it. */
+/* display-03 shipped 2026-08-15 — its consumer arrived: ContentText's `work`
+ * row title (the ruled size-only step down from display-02). */
+.kol-sans-display-03 {
+  font-family: var(--kol-font-family-sans-narrow);
+  font-size: var(--kol-text-display-03);
+  line-height: 100%;
+  font-weight: 600;
+}
 
 /* =============================================================================
  * DISPLAY TIGHT — the condensed-caps display voice: the Tight cut by NAME

package/kol-utilities.css

@@ -123,3 +123,22 @@
     transition: none;
   }
 }
+
+/* Placeholder prose — the ONE gate (GatedEmptyState, kol-fxr 2026-08-15).
+ *
+ * "Select a layer", "No effects yet", "This layer has no parameters" — prose
+ * that narrates a surface the user already understands. The ruling is that it
+ * is OFF unless asked for, so the suppression is the DEFAULT and the attribute
+ * is the opt-IN; a consumer that never wires the toggle simply never sees it.
+ *
+ * Written as :not() on the root rather than a display:none + revert pair, so
+ * the element keeps whatever display it had — flex, grid, inline — instead of
+ * being forced back to block on reveal.
+ *
+ * The attribute is stamped by usePlaceholders() in kol-component. The class is
+ * here, in utilities, because it is not EmptyState's chrome: a consumer puts
+ * it on its OWN prose and gets the same switch. That is the whole point — one
+ * concept, one gate, not a per-component prop each app re-invents. */
+:root:not([data-kol-placeholders]) .kol-placeholder {
+  display: none;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-theme",
-  "version": "0.42.2",
+  "version": "0.43.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",