@kolkrabbi/kol-workshop 0.1.3 → 0.1.5

package/README.md

@@ -47,4 +47,12 @@ const inventory = buildInventory(modules)
 
 So the package ships the **engine + chrome**, never the content — bring your own docs.
 
+## Tailwind v4 consumers
+
+Tailwind skips `node_modules` when scanning, so point it at this package's source — otherwise the shell's grid/sidebar/toc layout utilities never generate and the docs shell collapses to a single column:
+
+```css
+@source "../node_modules/@kolkrabbi/kol-workshop/src";
+```
+
 Self-check: `node src/engine/__check.mjs`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "description": "KOL workshop/docs system — a handrolled markdown engine, search, tag system (incl. a d3 tag graph), docs viewer, and docs shell. Sits above @kolkrabbi/kol-{theme,icons,component,framework}; content is consumer-injected (the package never globs docs).",
   "license": "MIT",
@@ -14,10 +14,10 @@
   "dependencies": {
     "d3": "^7.9.0",
     "@kolkrabbi/kol-brand": "^0.1.2",
-    "@kolkrabbi/kol-component": "0.7.0",
-    "@kolkrabbi/kol-theme": "0.7.1",
-    "@kolkrabbi/kol-icons": "0.5.0",
-    "@kolkrabbi/kol-framework": "0.3.2"
+    "@kolkrabbi/kol-framework": "0.3.3",
+    "@kolkrabbi/kol-component": "0.8.0",
+    "@kolkrabbi/kol-theme": "0.7.3",
+    "@kolkrabbi/kol-icons": "0.5.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/compositions/WorkshopDefaultSidebar.jsx

@@ -27,14 +27,14 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
     <div className="space-y-4">
       {siblings.length > 1 && (
         <div>
-          <div className="shell-sidebar-label">{parentRoute.label}</div>
+          <div className="shell-sidebar-label kol-helper-10 text-meta">{parentRoute.label}</div>
           <nav className="space-y-0">
             {siblings.map(child => (
               <Link
                 key={child.id}
                 to={`${basePath}/${child.path}`}
-                className={`shell-sidebar-link block ${
-                  location.pathname === `${basePath}/${child.path}` ? 'active' : ''
+                className={`shell-sidebar-link block kol-mono-14 ${
+                  location.pathname === `${basePath}/${child.path}` ? 'text-emphasis' : 'text-body'
                 }`}
               >
                 {child.label}
@@ -46,16 +46,16 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
 
       {links && (
         <div>
-          <div className="shell-sidebar-label">Repository</div>
+          <div className="shell-sidebar-label kol-helper-10 text-meta">Repository</div>
           <div className="space-y-1">
             {links.live && (
-              <a href={links.live} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action">
+              <a href={links.live} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action kol-mono-14 text-body">
                 <Icon name="external-link" size={14} />
                 Live site
               </a>
             )}
             {links.repo && (
-              <a href={links.repo} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action">
+              <a href={links.repo} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action kol-mono-14 text-body">
                 <Icon name="external-link" size={14} />
                 GitHub
               </a>
@@ -65,15 +65,15 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
       )}
 
       <div>
-        <div className="shell-sidebar-label">Quick actions</div>
+        <div className="shell-sidebar-label kol-helper-10 text-meta">Quick actions</div>
         <div className="space-y-1">
-          <Link to={basePath} className="shell-sidebar-action">
+          <Link to={basePath} className="shell-sidebar-action kol-mono-14 text-body">
             <Icon name="layout" size={14} />
             Workshop home
           </Link>
           <button
             type="button"
-            className="shell-sidebar-action"
+            className="shell-sidebar-action kol-mono-14 text-body"
             onClick={() => navigator.clipboard.writeText(window.location.pathname)}
             title="Copy page path to clipboard"
           >

package/src/compositions/WorkshopSidebar.jsx

@@ -62,7 +62,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
   return (
     <div className="space-y-4">
       <div className="shell-sidebar-toggle shell-sidebar-label" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
-        <Link to={docHref()} className="shell-sidebar-label" onClick={(e) => {
+        <Link to={docHref()} className="shell-sidebar-label kol-helper-10 text-meta" onClick={(e) => {
           if (collapsed && onToggle) onToggle()
           if (onNavigate) onNavigate(e)
         }}>
@@ -92,7 +92,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
               <div key={major} className="shell-nav-group">
                 <button
                   type="button"
-                  className="shell-nav-group-header w-full text-left"
+                  className="shell-nav-group-header w-full text-left kol-helper-14 text-body"
                   onClick={() => toggleGroup(major)}
                 >
                   <span className="flex items-center gap-2">
@@ -103,7 +103,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
                     />
                     {categoryLabels[major] || 'Other'}
                   </span>
-                  <span className="shell-nav-group-count">({docs.length})</span>
+                  <span className="kol-helper-12 text-subtle">({docs.length})</span>
                 </button>
                 {!isCollapsed && (
                   <div className="shell-nav-items">
@@ -113,11 +113,11 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
                         <Link
                           key={d.id}
                           to={docHref(d.id)}
-                          className={`shell-nav-item shell-nav-item-doc ${isActive ? 'active' : ''}`}
+                          className={`shell-nav-item shell-nav-item-doc kol-mono-14 ${isActive ? 'text-emphasis' : 'text-body'}`}
                           onClick={onNavigate}
                         >
                           <span className="shell-nav-item-title">{cleanTitle(d.title, d.id)}</span>
-                          <span className="shell-nav-item-id">{extractDocNumber(d.id)}</span>
+                          <span className="shell-nav-item-id kol-helper-10 text-subtle">{extractDocNumber(d.id)}</span>
                         </Link>
                       )
                     })}

package/src/docs/DocsArticle.jsx

@@ -1,7 +1,7 @@
 const join = (...classes) => classes.filter(Boolean).join(' ')
 
 const DocsArticle = ({ children, className }) => (
-  <article className={join('docs-article', className)}>{children}</article>
+  <article className={join('docs-article kol-prose', className)}>{children}</article>
 )
 
 export default DocsArticle

package/src/docs/DocsFrontmatter.jsx

@@ -33,18 +33,18 @@ const DocsFrontmatter = ({ metadata, docId }) => {
 
   return (
     <div className="docs-frontmatter">
-      <p className="shell-sidebar-label">Frontmatter</p>
+      <p className="shell-sidebar-label kol-helper-10 text-meta">Frontmatter</p>
       {fields.map((key) => {
         const value = metadata[key]
         const icon = FIELD_ICONS[key]
 
         return (
           <div key={key} className="docs-frontmatter-row">
-            <span className="docs-frontmatter-key">
+            <span className="docs-frontmatter-key kol-helper-12 text-meta">
               {icon && <Icon name={icon} size={14} />}
               {key}
             </span>
-            <span className="docs-frontmatter-value">
+            <span className="kol-mono-12 text-strong">
               {key === 'tags' && Array.isArray(value) ? (
                 <span className="flex flex-wrap gap-1.5">
                   {value.map((tag) => (

package/src/docs/DocsHeader.jsx

@@ -2,10 +2,10 @@ const join = (...classes) => classes.filter(Boolean).join(' ')
 
 const DocsHeader = ({ title, subtitle, meta = [], className }) => (
   <header className={join('docs-header', className)}>
-    {title ? <h1 className="docs-title">{title}</h1> : null}
-    {subtitle ? <p className="docs-subtitle">{subtitle}</p> : null}
+    {title ? <h1 className="kol-sans-heading-02 text-strong">{title}</h1> : null}
+    {subtitle ? <p className="kol-mono-14 text-meta">{subtitle}</p> : null}
     {Array.isArray(meta) && meta.length > 0 ? (
-      <div className="docs-meta">
+      <div className="docs-meta kol-helper-10 text-body">
         {meta.map(({ label, value }) => (
           <span key={label}>
             <strong>{label}</strong> {value}

package/src/docs/DocumentationReader.jsx

@@ -13,7 +13,7 @@ const SidebarSection = ({ sectionKey, label, collapsedSections, toggleSection, c
   <div>
     <button
       type="button"
-      className="shell-sidebar-toggle shell-sidebar-label"
+      className="shell-sidebar-toggle shell-sidebar-label kol-helper-10 text-meta"
       onClick={() => toggleSection(sectionKey)}
     >
       {label}
@@ -48,23 +48,23 @@ const DocReaderSidebar = ({ toc, allTags, docId, docsIndexHref, componentsHref,
         <div className="space-y-1">
           <button
             type="button"
-            className="shell-sidebar-action"
+            className="shell-sidebar-action kol-mono-14 text-body"
             onClick={() => navigate(-1)}
           >
             <Icon name="arrow-left" size={14} />
             Back
           </button>
-          <Link to={docsIndexHref} className="shell-sidebar-action">
+          <Link to={docsIndexHref} className="shell-sidebar-action kol-mono-14 text-body">
             <Icon name="book-open" size={14} />
             All documentation
           </Link>
-          <Link to={componentsHref} className="shell-sidebar-action">
+          <Link to={componentsHref} className="shell-sidebar-action kol-mono-14 text-body">
             <Icon name="grid" size={14} />
             View components
           </Link>
           <button
             type="button"
-            className="shell-sidebar-action"
+            className="shell-sidebar-action kol-mono-14 text-body"
             onClick={() => navigator.clipboard.writeText(docFilePath(docId))}
             title="Copy file path to clipboard"
           >
@@ -243,7 +243,7 @@ const DocumentationReader = ({
     <DocsArticle>
         <DocsFrontmatter metadata={doc.metadata} docId={docId} />
         {docTitle && (
-          <h1 className="docs-title">{docTitle}</h1>
+          <h1>{docTitle}</h1>
         )}
         {/* Render intro blocks (excluding H1 which is docTitle) */}
         {introBlocks.filter(b => b.type !== 'heading1').map((block, index) => {

package/src/docs/render-tokens.jsx

@@ -83,7 +83,7 @@ export const renderInlineTokens = (
           <Link
             key={tokenKey}
             to={tagHref(token.tag)}
-            className="inline-tag-pill"
+            className="inline-tag-pill kol-helper-12 bg-fg-08 text-strong"
           >
             #{token.tag}
           </Link>

package/src/shell/ShellLayout.jsx

@@ -100,18 +100,19 @@ const ShellLayout = ({ routes = [], basePath = '/', brandLogoSrc, brandLogoAlt =
       navigate(item.href)
     }
   }
-  const brand = (
-    <Link to={basePath} className="shell-header-logo flex items-center gap-2 text-emphasis">
-      {brandLogoSrc ? (
-        <img src={brandLogoSrc} alt={brandLogoAlt} className="h-6 w-auto" />
-      ) : (
-        <>
-          <Asset name="kol-wordmark" title="Kolkrabbi" className="inline-flex [&>svg]:h-5 [&>svg]:w-auto" />
-          <span className="text-fg-24" aria-hidden="true">/</span>
-          <Asset name="wordmark-workshop" title="Workshop" className="inline-flex [&>svg]:h-4 [&>svg]:w-auto" />
-        </>
-      )}
+  const brand = brandLogoSrc ? (
+    <Link to={basePath} className="shell-header-logo flex items-center text-emphasis">
+      <img src={brandLogoSrc} alt={brandLogoAlt} className="h-6 w-auto" />
     </Link>
+  ) : (
+    // Two separate wordmarks: KOLKRABBI holds the logo slot (reserves the 256px
+    // nav column at lg+), WORKSHOP falls at the content-column edge. Both h-6.
+    <>
+      <Link to={basePath} className="shell-header-logo hidden md:flex shrink-0 items-center text-emphasis lg:w-64">
+        <Asset name="kol-wordmark" title="Kolkrabbi" className="inline-flex [&>svg]:h-6 [&>svg]:w-auto" />
+      </Link>
+      <Asset name="wordmark-workshop" title="Workshop" className="inline-flex text-emphasis [&>svg]:h-6 [&>svg]:w-auto" />
+    </>
   )
   const searchTrigger = (
     <button

package/src/shell/ShellSidebar.jsx

@@ -67,14 +67,14 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
     <div className="space-y-4">
       <div className="shell-sidebar-toggle shell-sidebar-label" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
         {labelTo ? (
-          <Link to={labelTo} className="shell-sidebar-label kol-helper-14" onClick={(e) => {
+          <Link to={labelTo} className="shell-sidebar-label kol-helper-10 text-meta" onClick={(e) => {
             if (navCollapsed && handleToggle) handleToggle()
             if (onNavigate) onNavigate(e)
           }}>
             {label}
           </Link>
         ) : (
-          <button type="button" className="kol-helper-14" onClick={handleToggle}>{label}</button>
+          <button type="button" className="kol-helper-10 text-meta" onClick={handleToggle}>{label}</button>
         )}
         <button
           type="button"
@@ -99,7 +99,7 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
             <div key={route.id} className="shell-nav-group">
               <button
                 type="button"
-                className="shell-nav-group-header w-full text-left kol-helper-14"
+                className="shell-nav-group-header w-full text-left kol-helper-14 text-body"
                 onClick={() => handleSectionClick(route)}
               >
                 <span className="flex items-center gap-2">
@@ -111,7 +111,7 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
                   {route.label}
                 </span>
                 {route.children?.length > 0 && (
-                  <span className="shell-nav-group-count kol-helper-14">({route.children.length})</span>
+                  <span className="kol-helper-12 text-subtle">({route.children.length})</span>
                 )}
               </button>
 
@@ -125,11 +125,11 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
                         to={childPath}
                         end
                         className={({ isActive }) =>
-                          `shell-nav-item${isActive ? ' active' : ''}`
+                          `shell-nav-item kol-mono-14 ${isActive ? 'text-emphasis' : 'text-body'}`
                         }
                         onClick={onNavigate}
                       >
-                        <span className="shell-nav-item-title kol-helper-14">{child.label}</span>
+                        <span className="shell-nav-item-title">{child.label}</span>
                       </NavLink>
                     )
                   })}

package/src/tags/TagGraph.jsx

@@ -217,7 +217,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
 
   if (graphData.nodes.length === 0) {
     return (
-      <div className="text-fg-48 kol-mono-xs py-4 px-2">
+      <div className="text-fg-48 kol-mono-12 py-4 px-2">
         No tags found.
       </div>
     )
@@ -232,7 +232,7 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
         className="tag-graph-svg"
       />
       {hoveredNode && (
-        <div className="tag-graph-tooltip">
+        <div className="tag-graph-tooltip kol-helper-10 text-emphasis">
           #{hoveredNode.id} ({hoveredNode.count} {hoveredNode.count === 1 ? 'doc' : 'docs'})
         </div>
       )}

package/src/tags/TagModeContext.jsx

@@ -1,7 +1,11 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react'
 import { useLocation } from 'react-router-dom'
 
-const TagModeContext = createContext(null)
+// Singleton across duplicate module instances: Vite dev can serve this file
+// under two URLs (barrel `?v=` vs direct import), which would otherwise create
+// two distinct contexts and break useTagMode. Stash on globalThis so every
+// instance shares one context object. Harmless in prod (single instance).
+const TagModeContext = (globalThis.__KOL_TAGMODE_CONTEXT__ ||= createContext(null))
 
 /**
  * Default route helpers. These are the ONLY place the old hardcoded workshop

package/src/tags/TagModeOverlay.jsx

@@ -141,7 +141,7 @@ const TagModeOverlay = () => {
                     </button>
                   ))}
                   {visibleTags.length === 0 && (
-                    <p className="text-fg-48 kol-mono-xs py-4">No tags matching "{search}"</p>
+                    <p className="text-fg-48 kol-mono-12 py-4">No tags matching "{search}"</p>
                   )}
                 </div>