@kolkrabbi/kol-component 0.1.2 → 0.3.0

package/src/molecules/ArticleCard.jsx

@@ -0,0 +1,178 @@
+import Pill from '../atoms/Pill.jsx'
+import Image from './Image.jsx'
+
+/**
+ * Optional link wrapper — the one place routing lives. `http*`/`mailto` hrefs
+ * open in a new tab; any other href renders a plain same-tab anchor with an
+ * `onNavigate(event)` seam an SPA consumer intercepts (preventDefault + its
+ * router). No `href` → the bare content, no anchor.
+ */
+function CardLink({ href, onNavigate, className, children }) {
+  if (!href) return <div className={className}>{children}</div>
+  const isExternal = href.startsWith('http') || href.startsWith('mailto')
+  return (
+    <a
+      href={href}
+      onClick={isExternal ? undefined : onNavigate}
+      target={isExternal ? '_blank' : undefined}
+      rel={isExternal ? 'noreferrer noopener' : undefined}
+      className={className}
+    >
+      {children}
+    </a>
+  )
+}
+
+/** Cover-fit thumbnail (or fg-token placeholder box when no src). */
+function Thumb({ src, alt }) {
+  if (!src) return null
+  return (
+    <Image
+      src={src}
+      alt={alt}
+      className="object-cover"
+      style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+    />
+  )
+}
+
+/**
+ * ArticleCard — one blog-card family with three sizes (`default` / `hero` /
+ * `mini`), collapsing what were three byte-identical duplicate components. All
+ * three share the flat view-model (title, excerpt, thumbnail, tags, meta) and
+ * the link seam; `size` picks the layout.
+ *
+ * - **default** — grid tile: thumbnail (landscape/portrait) over tag Pills, a
+ *   mono title, an excerpt, and a `date • readingTime` meta Pill.
+ * - **hero** — index masthead: an optional header row (`label` + `meta`),
+ *   a big 16/9 image that zooms on hover, then kicker → title → summary.
+ * - **mini** — sidebar row: a fixed 120×120 thumbnail beside title → summary →
+ *   meta.
+ *
+ * De-Sanitized flat props, no router import. Placeholder thumbnails use
+ * fg-opacity tokens (theme-aware — no `.dark` style injection). Every string
+ * is authored at the call site in its final case — no `text-transform`, no JS
+ * casing (the kicker/meta `uppercase` are presentational classes only).
+ *
+ * @param {'default'|'hero'|'mini'} size  layout preset (default 'default')
+ * @param {string}   title       card title
+ * @param {string}   excerpt     summary/excerpt paragraph (alias: `summary`)
+ * @param {string}   summary     alias for `excerpt` (hero/mini call it this)
+ * @param {string}   kicker      hero-only eyebrow above the title
+ * @param {string}   label       hero header label (was the hardcoded "Featured")
+ * @param {string[]} meta        hero header chips / mini meta line (joined ` • `)
+ * @param {string}   date        default meta — left of the `•`
+ * @param {string}   readingTime default meta — right of the `•`
+ * @param {string[]} tags        default: rendered as Pills; hero/mini: `data-tags` only
+ * @param {string}   thumbnail   image src (omit → fg-token placeholder)
+ * @param {'landscape'|'portrait'} aspect  default thumbnail ratio (default 'landscape')
+ * @param {boolean}  showHeader  hero: show the label/meta header row (default true)
+ * @param {string}   href        link target; `http*`/`mailto` → new tab, else same-tab seam
+ * @param {Function} onNavigate  (event) => void — same-tab click seam (SPA intercept)
+ * @param {string}   className   extra classes on the root
+ */
+export default function ArticleCard({
+  size = 'default',
+  title,
+  excerpt,
+  summary,
+  kicker,
+  label,
+  meta,
+  date,
+  readingTime,
+  tags = [],
+  thumbnail,
+  aspect = 'landscape',
+  showHeader = true,
+  href,
+  onNavigate,
+  className = '',
+}) {
+  const body = excerpt ?? summary
+  const dataTags = tags?.length ? tags.join(' ') : undefined
+
+  if (size === 'hero') {
+    return (
+      <CardLink href={href} onNavigate={onNavigate} className={`block group ${className}`.trim()}>
+        <article className="w-full" data-tags={dataTags}>
+          {showHeader && (label || meta?.length) && (
+            <div className="flex justify-between items-center mb-4">
+              {label && <div className="kol-helper-14 text-fg-64">{label}</div>}
+              {meta?.length > 0 && (
+                <div className="flex gap-3 kol-helper-12 text-fg-48">
+                  {meta.map((item, i) => <span key={i}>{item}</span>)}
+                </div>
+              )}
+            </div>
+          )}
+          <div className="aspect-[16/9] mb-4 overflow-hidden w-full bg-fg-04 border border-fg-08 hover:border-fg-16 rounded">
+            {thumbnail && (
+              <Image
+                src={thumbnail}
+                alt={title}
+                className="object-cover transition-transform duration-300 group-hover:scale-105"
+                style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+              />
+            )}
+          </div>
+          <div className="space-y-3">
+            {kicker && (
+              <div className="kol-helper-16 uppercase tracking-wide text-fg-64">{kicker}</div>
+            )}
+            <h2 className="kol-sans-heading-03 transition-opacity duration-200 group-hover:opacity-70 line-clamp-2">
+              {title}
+            </h2>
+            {body && <p className="kol-mono-14 text-fg-48 line-clamp-3">{body}</p>}
+          </div>
+        </article>
+      </CardLink>
+    )
+  }
+
+  if (size === 'mini') {
+    const metaText = Array.isArray(meta) ? meta.join(' • ') : meta
+    return (
+      <CardLink
+        href={href}
+        onNavigate={onNavigate}
+        className={`group flex gap-6 items-start transition-opacity hover:opacity-80 ${className}`.trim()}
+      >
+        <div className="flex-shrink-0 w-[120px] h-[120px] overflow-hidden rounded bg-fg-12" data-tags={dataTags}>
+          <Thumb src={thumbnail} alt={title} />
+        </div>
+        <div className="flex-1 min-w-0 flex flex-col gap-2.5">
+          <h4 className="kol-mono-14 line-clamp-2 transition-opacity group-hover:opacity-80">{title}</h4>
+          {body && <p className="kol-mono-14 text-fg-64 line-clamp-2">{body}</p>}
+          {metaText && <div className="kol-helper-12 text-fg-80 uppercase">{metaText}</div>}
+        </div>
+      </CardLink>
+    )
+  }
+
+  // size === 'default'
+  return (
+    <CardLink href={href} onNavigate={onNavigate} className={`block group cursor-pointer w-full max-w-full ${className}`.trim()}>
+      <article className="w-full max-w-full" data-tags={dataTags}>
+        <div
+          className="mb-4 overflow-hidden w-full rounded bg-fg-04 border border-fg-08"
+          style={{ aspectRatio: aspect === 'portrait' ? '3/4' : '16/9' }}
+        >
+          <Thumb src={thumbnail} alt={title} />
+        </div>
+        {tags.length > 0 && (
+          <div className="flex flex-wrap gap-2 mb-2">
+            {tags.map((tag, i) => (
+              <Pill key={i} variant="inverse" size="sm">{tag}</Pill>
+            ))}
+          </div>
+        )}
+        <h3 className="mb-2 kol-mono-20 transition-opacity duration-200 group-hover:opacity-70">{title}</h3>
+        {body && <p className="mb-2 kol-mono-14 text-fg-64">{body}</p>}
+        {(date || readingTime) && (
+          <Pill variant="subtle" size="sm">{[date, readingTime].filter(Boolean).join(' • ')}</Pill>
+        )}
+      </article>
+    </CardLink>
+  )
+}

package/src/molecules/CardFeatureItem.jsx

@@ -0,0 +1,130 @@
+import { Icon } from '@kolkrabbi/kol-loader'
+
+/* taxonomy-ok: nests only kol-loader's Icon (a package import the
+ * relative-import check can't see). */
+
+/**
+ * CardFeatureItem — fixed-height feature card: a title + optional icon
+ * header, a flexible visual middle, and a mono description footer. The
+ * card's visual is polymorphic: an `.svg` URL string renders as a
+ * `mask-image` block tinted with `currentColor` (theme-correct line-art),
+ * any other string renders as a cover-fit `<img>`, a ReactNode renders
+ * as-is, and no visual falls back to a large 96px `Icon` (the header's
+ * `icon` name). The grid child of FeaturesCardSection.
+ *
+ * Optionally the whole card is a link. `http*` / `mailto` hrefs open in a
+ * new tab; any other href renders a plain same-tab anchor with an
+ * `onNavigate(event)` seam — an SPA consumer intercepts there
+ * (preventDefault + its router) instead of this component importing one.
+ *
+ * Title and description render exactly as authored — no casing transforms;
+ * author strings in their final case at the call site.
+ *
+ * @param {ReactNode} title            header heading (kol-helper-16)
+ * @param {string}    icon             Icon name for the header (16px); also the 96px no-visual fallback
+ * @param {string|ReactNode} visual    image URL, `.svg` mask URL, or inline node
+ * @param {ReactNode} description      footer line (kol-mono-12, muted)
+ * @param {string}    backgroundColor  card background utility class
+ * @param {string}    href             link target; `http*`/`mailto` → new tab, else plain same-tab anchor
+ * @param {Function}  onNavigate       (event) => void — click seam on the same-tab anchor (SPA intercept)
+ * @param {'auto'|'9/6'|'10/6'|'16/9'|'1/1'} imageAspectRatio  aspect class on the visual middle
+ * @param {string}    imagePosition    `<img>` object-position
+ */
+export default function CardFeatureItem({
+  title,
+  icon,
+  visual,
+  description,
+  backgroundColor = 'bg-surface-primary',
+  href,
+  onNavigate,
+  imageAspectRatio = 'auto',
+  imagePosition = 'center',
+}) {
+  const isSvgUrl = typeof visual === 'string' && visual.endsWith('.svg')
+
+  const aspectClasses = {
+    'auto': '',
+    '9/6': 'aspect-[9/6]',
+    '10/6': 'aspect-[10/6]',
+    '16/9': 'aspect-video',
+    '1/1': 'aspect-square',
+  }
+  const aspectClass = aspectClasses[imageAspectRatio] || ''
+
+  const content = (
+    <>
+      <div className="w-full flex items-center justify-between gap-2">
+        <h3 className="kol-helper-16">{title}</h3>
+        {icon && <Icon name={icon} size={16} className="shrink-0" />}
+      </div>
+
+      <div className={`w-full flex-1 flex items-center justify-center overflow-hidden ${aspectClass}`.trim()}>
+        {visual ? (
+          typeof visual === 'string' ? (
+            isSvgUrl ? (
+              /* currentColor line-art: the SVG paints as a mask over bg-current */
+              <div
+                className="w-full h-full bg-current rounded"
+                style={{
+                  maskImage: `url(${visual})`,
+                  maskSize: 'contain',
+                  maskRepeat: 'no-repeat',
+                  maskPosition: 'center',
+                  WebkitMaskImage: `url(${visual})`,
+                  WebkitMaskSize: 'contain',
+                  WebkitMaskRepeat: 'no-repeat',
+                  WebkitMaskPosition: 'center',
+                }}
+              />
+            ) : (
+              <img
+                src={visual}
+                alt={typeof title === 'string' ? title : ''}
+                className="w-full h-full object-cover rounded"
+                style={{ objectPosition: imagePosition }}
+              />
+            )
+          ) : (
+            visual
+          )
+        ) : (
+          <Icon name={icon} size={96} />
+        )}
+      </div>
+
+      <p className="kol-mono-12 text-fg-48">{description}</p>
+    </>
+  )
+
+  const baseClasses = `w-full flex-1 h-[304px] md:h-72 p-4 md:p-6 gap-4 ${backgroundColor} rounded border border-fg-08 flex flex-col justify-between items-start overflow-hidden`
+
+  if (href) {
+    const isExternal = href.startsWith('http') || href.startsWith('mailto')
+
+    if (isExternal) {
+      return (
+        <a
+          href={href}
+          className={`${baseClasses} hover:border-fg-32 transition-colors duration-300`}
+          target="_blank"
+          rel="noreferrer noopener"
+        >
+          {content}
+        </a>
+      )
+    }
+
+    return (
+      <a
+        href={href}
+        onClick={onNavigate}
+        className={`${baseClasses} hover:border-fg-24 transition-colors duration-300`}
+      >
+        {content}
+      </a>
+    )
+  }
+
+  return <div className={baseClasses}>{content}</div>
+}

package/src/molecules/CodeBlock.jsx

@@ -0,0 +1,11 @@
+import CopyButton from '../atoms/CopyButton.jsx'
+
+export default function CodeBlock({ children, language }) {
+  return (
+    <div className="kol-codeblock">
+      {language && <span className="kol-codeblock-lang">{language}</span>}
+      <CopyButton text={String(children)} className="kol-codeblock-copy" />
+      <pre><code>{children}</code></pre>
+    </div>
+  )
+}

package/src/molecules/ColorInputRow.jsx

@@ -0,0 +1,179 @@
+import { useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-loader'
+import ColorSwatch from './ColorSwatch'
+import Input from '../atoms/Input'
+import LabeledControl from '../atoms/LabeledControl'
+import { usePopover, PopoverPanel } from '../atoms/Popover'
+
+const HEX6 = /^[0-9A-F]{6}$/
+
+/** '#f0a' / 'F0A' / '#ff00aa' → 'FF00AA'; anything unparseable → null. */
+function normalizeDigits(raw) {
+  if (typeof raw !== 'string') return null
+  let d = raw.replace(/^#/, '').trim().toUpperCase()
+  if (/^[0-9A-F]{3}$/.test(d)) d = d.replace(/./g, (c) => c + c)
+  return HEX6.test(d) ? d : null
+}
+
+/**
+ * ColorInputRow — swatch chip + `#` hex input row. The single merged form of
+ * the brand editor's ColorField (layer color assignment: palette-ref popover
+ * behind the swatch) and SwatchRow (palette-slot editing: trailing extras) —
+ * one core, optional trailing affordances instead of two overlapping
+ * molecules.
+ *
+ * The input keeps a local draft while typing and commits on blur/Enter:
+ * digits are filtered to hex as typed, shorthand `F0A` expands to `FF00AA`,
+ * and only a valid 6-digit hex fires `onChange('#RRGGBB')` — invalid drafts
+ * revert to the current value. Picking a palette-ref swatch fires the ref's
+ * (pre-resolved) hex and closes the popover.
+ *
+ * Composition only — no color math, no store coupling. Palette entries come
+ * in pre-resolved via `paletteRefs`; the app-side `resolveColor`/PALETTE_REFS
+ * and `tokenNameFor` seams stay in the consumer. SwatchRow's `edited` prop
+ * was dead in the source render and is dropped ([dead-prop] handled);
+ * `transparentTone` is an explicit prop, not inferred from the label string.
+ *
+ * @param {string|null} value           current color, '#RRGGBB' (3-digit accepted, normalized); null → transparent "None" swatch
+ * @param {Function}    onChange        (hex: string) => void — normalized '#RRGGBB' on commit or palette pick
+ * @param {string}      label           optional label; when set the row wraps in LabeledControl
+ * @param {Array}       paletteRefs     [{ id, label, value }] pre-resolved entries → swatch becomes a popover trigger with a ref grid (omit for a plain preview chip)
+ * @param {Function}    onRemove        () => void — renders a trailing remove (×) button
+ * @param {ReactNode}   trailing        extra trailing affordances (lock toggle, token name, …)
+ * @param {number}      swatchSize      chip size in px (default 24)
+ * @param {string}      transparentTone TransparentX stroke tone for the null-value swatch: 'warning' (default) | 'error' | 'info' | 'success'
+ * @param {string}      inputVariant    Input chrome: 'filled' (default) | 'ghost' | 'outline'
+ * @param {boolean}     disabled        dims the row, blocks pointer, aria-disabled
+ */
+export default function ColorInputRow({
+  value,
+  onChange,
+  label,
+  paletteRefs,
+  onRemove,
+  trailing,
+  swatchSize = 24,
+  transparentTone = 'warning',
+  inputVariant = 'filled',
+  disabled = false,
+  className = '',
+}) {
+  const digits = normalizeDigits(value)
+  const hasRefs = Array.isArray(paletteRefs) && paletteRefs.length > 0
+
+  /* Local typing draft, re-synced whenever the controlled value changes
+   * (render-time reset — no effect, no flicker). */
+  const [draft, setDraft] = useState(digits ?? '')
+  const [prevValue, setPrevValue] = useState(value)
+  if (value !== prevValue) {
+    setPrevValue(value)
+    setDraft(normalizeDigits(value) ?? '')
+  }
+
+  const [open, setOpen] = useState(false)
+  const popover = usePopover({ open, onOpenChange: setOpen, placement: 'bottom-start', offset: 4 })
+
+  const commit = () => {
+    const next = normalizeDigits(draft)
+    if (next == null) {
+      setDraft(digits ?? '') // invalid or empty → revert, never emit
+      return
+    }
+    setDraft(next)
+    if (next !== digits) onChange?.('#' + next)
+  }
+
+  const pick = (ref) => {
+    onChange?.('#' + (normalizeDigits(ref.value) ?? ''))
+    setOpen(false)
+  }
+
+  /* Swatch subtitle for the trigger's aria-label: the matching ref's label
+   * when the value is a palette color, else the hex, else 'None'. */
+  const refLabel = hasRefs
+    ? paletteRefs.find((r) => normalizeDigits(r.value) === digits)?.label
+    : undefined
+  const subtitle = digits == null ? 'None' : (refLabel ?? '#' + digits)
+
+  const swatch = (
+    <ColorSwatch
+      hex={digits ? '#' + digits : null}
+      size={hasRefs ? 'stretch' : swatchSize}
+      showTransparent={digits == null}
+      transparentTone={transparentTone}
+      hoverable={false}
+    />
+  )
+
+  const row = (
+    <div
+      className={`flex items-center gap-2 ${disabled ? 'opacity-30 pointer-events-none' : ''} ${className}`}
+      aria-disabled={disabled || undefined}
+    >
+      {hasRefs ? (
+        <button
+          type="button"
+          ref={popover.refs.setReference}
+          {...popover.getReferenceProps()}
+          aria-label={`${label ?? 'Color'}: ${subtitle}`}
+          className="inline-flex items-center shrink-0"
+          style={{ width: swatchSize, height: swatchSize }}
+        >
+          {swatch}
+        </button>
+      ) : (
+        swatch
+      )}
+      <Input
+        variant={inputVariant}
+        size="sm"
+        prefix="#"
+        chars={6}
+        maxLength={6}
+        uppercase
+        value={draft}
+        onChange={(e) => setDraft(e.target.value.replace(/[^0-9a-fA-F]/g, '').toUpperCase().slice(0, 6))}
+        onBlur={commit}
+        onKeyDown={(e) => { if (e.key === 'Enter') commit() }}
+        disabled={disabled}
+        aria-label={label ? `${label} hex` : 'Hex color'}
+      />
+      {trailing}
+      {onRemove && (
+        <button
+          type="button"
+          onClick={onRemove}
+          aria-label="Remove"
+          title="Remove"
+          className="inline-flex items-center justify-center w-6 h-6 shrink-0 rounded text-meta hover:text-emphasis hover:bg-fg-08 transition-colors"
+        >
+          <Icon name="x" size={12} />
+        </button>
+      )}
+      {hasRefs && (
+        <PopoverPanel
+          popover={popover}
+          panel={false}
+          focus={false}
+          className="bg-surface-secondary border border-fg-08 rounded p-2 shadow-lg"
+          style={{ minWidth: 200 }}
+        >
+          <div className="grid grid-cols-6 gap-1">
+            {paletteRefs.map((ref) => (
+              <ColorSwatch
+                key={ref.id}
+                hex={'#' + (normalizeDigits(ref.value) ?? '')}
+                size="fill"
+                selected={normalizeDigits(ref.value) === digits && digits != null}
+                title={ref.label}
+                onClick={() => pick(ref)}
+              />
+            ))}
+          </div>
+        </PopoverPanel>
+      )}
+    </div>
+  )
+
+  return label ? <LabeledControl label={label}>{row}</LabeledControl> : row
+}

package/src/molecules/ColorRamp.jsx

@@ -0,0 +1,114 @@
+import { useEffect, useState } from 'react'
+import ColorSwatch from './ColorSwatch.jsx'
+import { resolveCssVar, isLight } from '../hooks/cssVar.js'
+
+/**
+ * ColorRamp — one specimen row of color chips for a token-doc page. A label
+ * (+ optional note) above a run of ColorSwatch chips, each captioned with its
+ * name and resolved value. Merges the former Ramp (static hex) + ColorRamp
+ * (live CSS var) widgets into one component with two mutually-exclusive inputs:
+ *
+ *   live  — `vars` (custom-property names) or the `ramp` + `stops` sugar. Each
+ *           chip resolves `--{token}` on mount via resolveCssVar and prints the
+ *           declared value; the swatch fill reads the same var() live, so the
+ *           theme file stays the single source of truth.
+ *   static — `colors` (literal color strings). No resolution; the literal is
+ *            both the fill and the printed value. This is the old Ramp mode.
+ *
+ * Precedence: colors > vars > ramp/stops. The local Chip/Swatch dups the two
+ * source files carried are gone — every chip is a DS ColorSwatch. The anchor
+ * marker is a dot whose fill flips black/white through isLight so it reads on
+ * any stop.
+ *
+ * Presentational — resolves once on mount; no theme subscription.
+ *
+ * @param {string}   label   row heading (defaults to `ramp`); omit in vars/colors mode to hide
+ * @param {string}   ramp    ramp key sugar → each chip resolves `--{ramp}-{stop}`
+ * @param {number[]} stops   stop list for the `ramp` sugar (default 100–500)
+ * @param {Array<string|[string,string]>} vars    live custom-property names (bare, or [name, token])
+ * @param {Array<string|[string,string]>} colors  static literal colors (bare, or [name, color])
+ * @param {string|number} anchor  chip that gets the anchor dot + ★ — matches a stop, name, or index
+ * @param {string}   note    right-aligned italic caption
+ */
+
+/** Flatten any of the three inputs into a uniform chip list. */
+function buildChips({ ramp, stops, vars, colors }) {
+  if (colors) {
+    return colors.map((c, i) => {
+      const [name, literal] = Array.isArray(c) ? c : [c, c]
+      return { key: `c-${i}-${literal}`, name, literal }
+    })
+  }
+  if (vars) {
+    return vars.map((v, i) => {
+      const [name, raw] = Array.isArray(v) ? v : [v.replace(/^--/, ''), v]
+      const token = raw.startsWith('--') ? raw : `--${raw}`
+      return { key: `v-${i}-${token}`, name, token }
+    })
+  }
+  return stops.map((s) => ({
+    key: `r-${ramp}-${s}`,
+    name: `${ramp}-${s}`,
+    token: `--${ramp}-${s}`,
+    stop: s,
+  }))
+}
+
+export default function ColorRamp({
+  label,
+  ramp,
+  stops = [100, 200, 300, 400, 500],
+  vars,
+  colors,
+  anchor,
+  note,
+}) {
+  const chips = buildChips({ ramp, stops, vars, colors })
+  const [values, setValues] = useState({})
+
+  useEffect(() => {
+    const next = {}
+    for (const c of chips) {
+      if (c.token) next[c.key] = resolveCssVar(c.token)
+    }
+    setValues(next)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ramp, JSON.stringify(stops), JSON.stringify(vars), JSON.stringify(colors)])
+
+  const rampLabel = label ?? ramp
+  const cols = Math.min(chips.length, 10)
+
+  return (
+    <div className="flex flex-col gap-3 py-5 border-b border-fg-08 last:border-b-0">
+      {(rampLabel || note) && (
+        <div className="flex items-baseline justify-between gap-6 flex-wrap">
+          {rampLabel && <span className="kol-helper-12 tracking-widest text-emphasis">{rampLabel}</span>}
+          {note && <span className="kol-mono-12 text-meta italic max-w-[60ch] text-right">{note}</span>}
+        </div>
+      )}
+      <div className="grid gap-2" style={{ gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))` }}>
+        {chips.map((c, i) => {
+          const value = c.literal ?? values[c.key] ?? ''
+          const fill = c.literal ?? `var(${c.token})`
+          const isAnchor = anchor != null && (anchor === c.stop || anchor === c.name || anchor === i)
+          return (
+            <div key={c.key} className="flex flex-col gap-1.5">
+              <div className="relative">
+                <ColorSwatch hex={fill} size="fill" radius="sm" title={`${c.name} ${value}`} />
+                {isAnchor && value && (
+                  <span className="absolute inset-0 flex items-center justify-center" aria-hidden="true">
+                    <span className="w-2.5 h-2.5 rounded-full" style={{ background: isLight(value) ? '#000' : '#fff' }} />
+                  </span>
+                )}
+              </div>
+              <div className="flex flex-col items-start gap-0.5 leading-tight">
+                <span className="kol-helper-10 text-emphasis">{c.name}{isAnchor && ' ★'}</span>
+                <span className="kol-helper-10 text-meta">{value}</span>
+              </div>
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/src/{atoms → molecules}/ColorSwatch.jsx

@@ -34,7 +34,7 @@
  *   onClick         — if provided, renders as <button>; else <span>.
  *   title           — passes through.
  */
-import TransparentX from './TransparentX'
+import TransparentX from '../atoms/TransparentX'
 
 const SIZE_CLASSES = {
   fill:    'w-full aspect-square',

package/src/molecules/Dropdown.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-loader'
 import { MenuDropdownItem } from './MenuItem.jsx'
-import { PopoverPanel, usePopover } from './Popover.jsx'
+import { PopoverPanel, usePopover } from '../atoms/Popover.jsx'
 
 const SIZE_MAP = {
   sm: { fontSize: 12, paddingY: 4, paddingX: 12, radius: 14, panelRadius: 14, icon: 10 },
@@ -17,9 +17,10 @@ const Dropdown = ({
   onChange,
   size,
   variant = 'default',
+  defaultOpen = false,
   className = ''
 }) => {
-  const [isOpen, setIsOpen] = useState(false)
+  const [isOpen, setIsOpen] = useState(defaultOpen)
   const [resolvedSize, setResolvedSize] = useState('md')
   const [dropdownWidth, setDropdownWidth] = useState('100px')