@grove-dev/astro 0.5.0-next.2 → 0.5.1

package/src/server/models.ts

@@ -17,6 +17,7 @@ import {
   activeFilterChips,
   applySort,
   buildFacets,
+  configuredFacetDefs,
   effectivePage,
   effectiveSort,
   extractToc,
@@ -51,7 +52,9 @@ export interface DirectorySiteConfig {
   description?: string;
   repoUrl?: string;
   nav?: Array<{ label: string; href: string }>;
-  facets?: string[];
+  browse?: {
+    facets?: string[];
+  };
   analytics?: {
     googleAnalyticsId?: string;
   };
@@ -79,6 +82,12 @@ export interface DirectorySiteConfig {
     categories?: Array<{ id: string; name: string }>;
     stacks?: Array<{ id: string; name: string }>;
     platforms?: Array<{ id: string; name: string }>;
+    topics?: Array<{ id: string; name: string }>;
+    licenses?: Array<{ id: string; name: string }>;
+    distributionChannels?: Array<{ id: string; name: string }>;
+  };
+  contributors?: {
+    showContributionCount?: boolean;
   };
   stats?: {
     originalRepo?: string;
@@ -114,30 +123,96 @@ export function loadDirectoryContributors(root = process.cwd()): DirectoryContri
   }
 }
 
+/**
+ * Canonical taxonomy counts — the ONE algorithm every count surface
+ * uses. Counts the VISIBLE index (`items`, the same set browse
+ * filters over) with the primary+supporting stack union
+ * (`projectStackIds`), so the homepage grid, `/stacks`,
+ * `/categories`, and the browse facet counts can never disagree.
+ * (Counting `fullItems` with the singular `record.stack` was the
+ * audit's "Python 3 vs 4" drift.)
+ */
+export function countTaxonomies() {
+  const stackCounts = new Map<string, number>();
+  const categoryCounts = new Map<string, number>();
+  for (const record of items) {
+    if (record.category) categoryCounts.set(record.category, (categoryCounts.get(record.category) ?? 0) + 1);
+    if (record.kind === "project") {
+      for (const stackId of projectStackIds(record)) {
+        stackCounts.set(stackId, (stackCounts.get(stackId) ?? 0) + 1);
+      }
+    }
+  }
+  const toEntries = (
+    counts: Map<string, number>,
+    kind: "stacks" | "categories",
+  ) =>
+    [...counts]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .map(([id, count]) => ({ name: taxonomyLabel(kind, id), slug: id, count }));
+  return {
+    stacks: toEntries(stackCounts, "stacks"),
+    categories: toEntries(categoryCounts, "categories"),
+  };
+}
+
+/**
+ * Uncapped taxonomy index model for the `/stacks` and `/categories`
+ * pages — same canonical counts, no homepage display cap.
+ */
+export function getTaxonomyIndexModel() {
+  return countTaxonomies();
+}
+
 export function getHomePageModel(site: DirectorySiteConfig) {
   const slug = site.blueprintConfig?.routeSlug ?? "projects";
   const singular = site.blueprintConfig?.labelSingular ?? itemLabel();
   const plural = site.blueprintConfig?.labelPlural ?? itemLabelPlural();
   const projects = items.filter((record) => record.kind === "project");
-  const hot = filterRecords(projects, { labels: ["hot"] }).slice(0, 6);
-  const recentlyAdded = applySort(projects, "recently-added").slice(0, 6);
-  const established = filterRecords(projects, { labels: ["mature"] }).slice(0, 6);
+  // Hot: most-starred items carrying the "hot" lens label. Without an
+  // explicit sort, the filter preserves the index order, which is
+  // alphabetical — so the homepage's "Trending now" panel ends up
+  // showing the same 6 items as the "Established" panel (because
+  // ~95% of mature items also carry the "hot" label).
+  //
+  // Top-up guard: when fewer than MIN_HOT records carry the "hot"
+  // label, fill the remainder from the most-starred remaining
+  // projects so the first lens panel can always render a full
+  // three-column grid. Topped-up records are still excluded from the
+  // "Recently added" / "Established" panels below.
+  const MIN_HOT = 3;
+  const hotLabelled = applySort(filterRecords(projects, { labels: ["hot"] }), "most-starred").slice(0, 6);
+  const labelledSlugs = new Set(hotLabelled.map((r) => r.slug));
+  const hot =
+    hotLabelled.length >= MIN_HOT
+      ? hotLabelled
+      : [
+          ...hotLabelled,
+          ...applySort(projects, "most-starred")
+            .filter((r) => !labelledSlugs.has(r.slug))
+            .slice(0, MIN_HOT - hotLabelled.length),
+        ];
+  // Recently added: most recently reviewed items. We exclude items
+  // already shown in the hot panel so the three lens sections on the
+  // homepage never echo the same record card.
+  const hotSlugs = new Set(hot.map((r) => r.slug));
+  const recentlyAdded = applySort(
+    projects.filter((r) => !hotSlugs.has(r.slug)),
+    "recently-added",
+  ).slice(0, 6);
+  // Established: longest-running mature items, again excluding any
+  // record already surfaced in the hot or recently-added panel so the
+  // three sections read as distinct perspectives.
+  const recentSlugs = new Set([...hotSlugs, ...recentlyAdded.map((r) => r.slug)]);
+  const established = applySort(
+    filterRecords(projects, { labels: ["mature"] }).filter((r) => !recentSlugs.has(r.slug)),
+    "most-starred",
+  ).slice(0, 6);
 
-  const stackCounts = new Map<string, number>();
-  const categoryCounts = new Map<string, number>();
-  for (const record of fullItems) {
-    if (record.category) categoryCounts.set(record.category, (categoryCounts.get(record.category) ?? 0) + 1);
-    if (record.kind === "project" && record.stack) {
-      stackCounts.set(record.stack, (stackCounts.get(record.stack) ?? 0) + 1);
-    }
-  }
-  const stacks = [...stackCounts]
-    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
-    .slice(0, 12)
-    .map(([id, count]) => ({ name: taxonomyLabel("stacks", id), slug: id, count }));
-  const categories = [...categoryCounts]
-    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
-    .map(([id, count]) => ({ name: taxonomyLabel("categories", id), slug: id, count }));
+  // Homepage layout choice: cap the stack grid at 12. The counting
+  // itself is the canonical algorithm in `countTaxonomies`.
+  const { stacks: allStacks, categories } = countTaxonomies();
+  const stacks = allStacks.slice(0, 12);
   const contributors = loadDirectoryContributors();
   const description = site.description ??
     `A searchable directory of real ${plural} — organized by stack, category, platform, license, activity, and maturity.`;
@@ -165,39 +240,69 @@ export function getHomePageModel(site: DirectorySiteConfig) {
   };
 }
 
-const FACET_ALIASES: Record<string, "stacks" | "platforms" | "categories" | "tags" | "licenses"> = {
-  stack: "stacks",
+/**
+ * Ordered facet definitions for this site — the single registry in
+ * `@grove-dev/core` resolves `browse.facets`, so visibility, ORDER,
+ * labels, and selection mode all come from one place.
+ */
+function enabledFacetDefs(site?: DirectorySiteConfig) {
+  return configuredFacetDefs(site?.browse?.facets);
+}
+
+/** Taxonomy list that labels/orders each facet dimension. */
+const TAXONOMY_KIND_FOR_DIMENSION = {
   stacks: "stacks",
-  platform: "platforms",
   platforms: "platforms",
-  category: "categories",
   categories: "categories",
-  tag: "tags",
-  tags: "tags",
-  license: "licenses",
+  tags: "topics",
   licenses: "licenses",
-};
-
-function configuredFacets(site?: DirectorySiteConfig) {
-  return new Set((site?.facets ?? ["category", "tags"])
-    .map((facet) => FACET_ALIASES[facet])
-    .filter((facet): facet is NonNullable<typeof facet> => Boolean(facet)));
-}
+} as const;
 
 export function getDirectoryIndexModel(searchParams: URLSearchParams, site?: DirectorySiteConfig) {
   const filters = filtersFromSearchParams(searchParams);
+  // Taxonomy YAML owns option order: the generated arrays preserve
+  // file/`order:` position, so their id sequence IS the display order.
+  const taxonomyOrder = {
+    stacks: site?.taxonomy?.stacks?.map((t) => t.id),
+    platforms: site?.taxonomy?.platforms?.map((t) => t.id),
+    categories: site?.taxonomy?.categories?.map((t) => t.id),
+    tags: site?.taxonomy?.topics?.map((t) => t.id),
+    licenses: site?.taxonomy?.licenses?.map((t) => t.id),
+  };
   const rawFacets = buildFacets(items, {
-    curatedTagIds: site.taxonomy?.topics?.map((t) => t.id),
+    curatedTagIds: taxonomyOrder.tags,
     filters, // Intersection counts: each facet reflects all OTHER filters.
+    order: taxonomyOrder,
   });
-  const enabled = configuredFacets(site);
+  const defs = enabledFacetDefs(site);
+  const enabled = new Set(defs.map((def) => def.dimension));
+  const labeled = (dimension: keyof typeof TAXONOMY_KIND_FOR_DIMENSION) =>
+    rawFacets[dimension].map((option) => ({
+      ...option,
+      label: taxonomyLabel(TAXONOMY_KIND_FOR_DIMENSION[dimension], option.value),
+    }));
   const facets = {
-    stacks: enabled.has("stacks") ? rawFacets.stacks.map((option) => ({ ...option, label: taxonomyLabel("stacks", option.value) })) : [],
-    platforms: enabled.has("platforms") ? rawFacets.platforms.map((option) => ({ ...option, label: taxonomyLabel("platforms", option.value) })) : [],
-    categories: enabled.has("categories") ? rawFacets.categories.map((option) => ({ ...option, label: taxonomyLabel("categories", option.value) })) : [],
-    tags: enabled.has("tags") ? rawFacets.tags : [],
-    licenses: enabled.has("licenses") ? rawFacets.licenses : [],
+    stacks: enabled.has("stacks") ? labeled("stacks") : [],
+    platforms: enabled.has("platforms") ? labeled("platforms") : [],
+    categories: enabled.has("categories") ? labeled("categories") : [],
+    tags: enabled.has("tags") ? labeled("tags") : [],
+    licenses: enabled.has("licenses") ? labeled("licenses") : [],
   };
+  // Ordered filter groups — `browse.facets` array order is the render
+  // order; label + selection mode come from the core registry.
+  const facetGroups = defs
+    .map((def) => ({
+      id: def.id,
+      filterKey: def.dimension,
+      label: def.label,
+      single: def.single,
+      options: facets[def.dimension],
+      initial: (filters[def.dimension] ?? []) as string[],
+    }))
+    .filter((group) => group.options.length > 0);
+  const plural = site?.blueprintConfig?.labelPlural ?? itemLabelPlural();
+  // Placeholder names only the ENABLED dimensions, in config order.
+  const searchPlaceholder = `Search ${plural}, ${defs.map((def) => def.dimension).join(", ")}...`;
   const sort = effectiveSort(filters);
   const sorted = applySort(filterRecords(items, filters), sort);
   const pageCount = totalPages(sorted.length);
@@ -207,6 +312,8 @@ export function getDirectoryIndexModel(searchParams: URLSearchParams, site?: Dir
     total: items.length,
     filters,
     facets,
+    facetGroups,
+    searchPlaceholder,
     sort,
     sorted,
     pages: pageCount,
@@ -234,12 +341,16 @@ export function getContributorsPageModel(site: DirectorySiteConfig) {
     title: `Community — ${site.name}`,
     description: `The people who have contributed to ${site.name} through code, curation, and review.`,
     contributorsGraphHref: repo ? `${repo}/graphs/contributors` : null,
+    // Surface the consumer's per-user contribution-count preference to
+    // the consumer page so it can render quieter cards when the
+    // directory does not curate contributor activity.
+    showContributionCount: site.contributors?.showContributionCount ?? true,
   };
 }
 
 export function getSubmissionPageModel(site: DirectorySiteConfig) {
   const singular = site.blueprintConfig?.labelSingular ?? itemLabel();
-  const enabled = configuredFacets(site);
+  const enabled = new Set(enabledFacetDefs(site).map((def) => def.dimension));
   const values = (key: "category" | "stack") =>
     [...new Set(fullProjects.map((record) => String(record[key] ?? "")).filter(Boolean))]
       .sort((a, b) => a.localeCompare(b));
@@ -268,6 +379,9 @@ export function getSubmissionPageModel(site: DirectorySiteConfig) {
       stack: enabled.has("stacks"),
       platforms: enabled.has("platforms"),
       tags: enabled.has("tags"),
+      // The submit form mirrors the browse dimensions: a directory
+      // that filters by license also collects it at submission time.
+      license: enabled.has("licenses"),
     },
     categories,
     stacks,
@@ -275,6 +389,14 @@ export function getSubmissionPageModel(site: DirectorySiteConfig) {
     existingFullNames,
     platformOptions: site.taxonomy?.platforms?.map(({ id, name }) => ({ id, label: name })) ??
       ["ios", "android", "web", "macos", "windows", "linux"].map((id) => ({ id, label: taxonomyLabel("platforms", id) })),
+    licenseOptions: site.taxonomy?.licenses?.map(({ id, name }) => ({ id, label: name })) ?? [],
+    // Ids for client-side validation — without this the submit form's
+    // taxonomy checks silently no-op.
+    taxonomy: {
+      categoryIds: categories.map((option) => option.id),
+      stackIds: stacks.map((option) => option.id),
+      platformIds: (site.taxonomy?.platforms ?? []).map(({ id }) => id),
+    },
   };
 }
 
@@ -441,6 +563,10 @@ const tocBody = readContentFile(typeof record.content === "string" ? record.cont
     curationLabels: record.curation?.labels ?? [],
     tags,
     healthLabel,
+    // Top-level `category` so the package's RecordHeader / RecordSidebar
+    // components can render the category pill without each consumer
+    // having to destructure `record.category` themselves.
+    category: record.category,
     contentHtml: isProject ? getContentHtml(recordSlug) : null,
     // Curated summary (Open Apps-written) takes priority over the
     // raw `description` (typically copied from GitHub). Fall back to
@@ -488,7 +614,9 @@ const tocBody = readContentFile(typeof record.content === "string" ? record.cont
     // because the TOC + reading-time want the *body* (frontmatter
     // stripped), not the HTML. Re-reading is cheap and keeps the
     // pipeline self-documenting.
-    toc: tocBody ? extractToc(tocBody.body, { maxDepth: 2 }) : [],
+    // Depth 3 so subsections surface in the TOC, indented under
+    // their h2 parents.
+    toc: tocBody ? extractToc(tocBody.body, { maxDepth: 3 }) : [],
     readingMetrics: tocBody ? readingMetrics(tocBody.body) : { wordCount: 0, minutes: 1 },
     jsonLd,
   };

package/src/styles.css

@@ -62,6 +62,33 @@
   --color-popover: var(--grove-popover);
   --color-popover-foreground: var(--grove-popover-foreground);
 
+  /* ── Surfaces ───────────────────────────────────────────────────
+   * Elevation roles. `card` and `popover` above resolve to these so
+   * legacy utilities keep working while new components can name the
+   * elevation they mean.
+   */
+  --color-surface-raised: var(--grove-surface-raised);
+  --color-surface-sunken: var(--grove-surface-sunken);
+  --color-surface-overlay: var(--grove-surface-overlay);
+
+  /* ── Selection (neutral inversion) ──────────────────────────────
+   * Active filters, current lens/page, and other "you are here"
+   * states. Deliberately decoupled from the brand primary so green
+   * can mean brand action or success — never selection.
+   */
+  --color-selected: var(--grove-selected);
+  --color-selected-foreground: var(--grove-selected-foreground);
+
+  /* ── Status roles (solid fill + text-on-fill pairs) ───────────── */
+  --color-success: var(--grove-success);
+  --color-success-foreground: var(--grove-success-foreground);
+  --color-warning: var(--grove-warning);
+  --color-warning-foreground: var(--grove-warning-foreground);
+  --color-danger: var(--grove-danger);
+  --color-danger-foreground: var(--grove-danger-foreground);
+  --color-info: var(--grove-info);
+  --color-info-foreground: var(--grove-info-foreground);
+
   /* ── Accent (interactive states) ─────────────────────────────── */
   --color-accent-muted: color-mix(in oklab, var(--grove-foreground) 8%, transparent);
 
@@ -116,15 +143,20 @@
   --text-2xs: 0.6875rem;
   --text-2xs--line-height: 1rem;
 
-  /* ── Container widths (showcase rhythm) ──────────────────────── */
-  --container-container: 1140px;
+  /* ── Container widths (showcase rhythm) ──────────────────────────
+   * The default container tracks `theme.containerWidth` from
+   * grove.config.ts: BaseLayout emits `--grove-container` on <html>
+   * and the token falls back to the package default when unset. */
+  --container-container: var(--grove-container, 1160px);
   --container-wide: 1400px;
   --container-narrow: 720px;
 
-  /* ── Border radius scale ─────────────────────────────────────── */
-  --radius: 0.625rem;
-  --radius-lg: 0.5rem;
-  --radius-xl: 0.75rem;
+  /* ── Border radius scale ──────────────────────────────────────────
+   * Driven by `theme.radius` ("none" | "soft" | "round") the same
+   * way — BaseLayout emits the `--grove-radius*` overrides. */
+  --radius: var(--grove-radius, 0.625rem);
+  --radius-lg: var(--grove-radius-lg, 0.5rem);
+  --radius-xl: var(--grove-radius-xl, 0.75rem);
 
   /* ── Animations ──────────────────────────────────────────────── */
   --animate-fade-in-up: fade-in-up 0.6s ease-out both;
@@ -191,8 +223,11 @@
     --grove-gray-5: var(--color-ink-400);
     --grove-gray-6: var(--color-ink-300);
     --grove-gray-7: var(--color-ink-100);
-    --grove-primary: var(--grove-foreground);
-    --grove-primary-foreground: var(--grove-gray-7);
+    /* Brand color from `theme.primaryColor` (grove.config.ts) —
+     * BaseLayout emits `--grove-theme-primary*` on <html>; without
+     * a config the site keeps the neutral ink treatment. */
+    --grove-primary: var(--grove-theme-primary, var(--grove-foreground));
+    --grove-primary-foreground: var(--grove-theme-primary-foreground, var(--grove-gray-7));
     --grove-secondary: var(--grove-gray-7);
     --grove-secondary-foreground: var(--grove-foreground);
     --grove-muted: var(--grove-gray-7);
@@ -202,10 +237,28 @@
     --grove-border: var(--grove-gray-6);
     --grove-input: var(--grove-gray-6);
     --grove-ring: var(--grove-gray-4);
-    --grove-card: var(--grove-background);
+    /* Elevation: raised surfaces stay in the light family — cards sit
+     * on the page via border, not a dark fill. */
+    --grove-surface-raised: var(--grove-background);
+    --grove-surface-sunken: var(--color-ink-100);
+    --grove-surface-overlay: var(--grove-background);
+    --grove-card: var(--grove-surface-raised);
     --grove-card-foreground: var(--grove-foreground);
-    --grove-popover: var(--grove-background);
+    --grove-popover: var(--grove-surface-overlay);
     --grove-popover-foreground: var(--grove-foreground);
+    /* Selection: neutral inversion (vite.dev-style), never the brand
+     * primary. */
+    --grove-selected: var(--color-ink-900);
+    --grove-selected-foreground: var(--color-ink-50);
+    /* Status fills with AA text-on-fill partners. */
+    --grove-success: #15803d;
+    --grove-success-foreground: #ffffff;
+    --grove-warning: #92400e;
+    --grove-warning-foreground: #ffffff;
+    --grove-danger: #b91c1c;
+    --grove-danger-foreground: #ffffff;
+    --grove-info: #1d4ed8;
+    --grove-info-foreground: #ffffff;
   }
 
   :root.dark {
@@ -219,8 +272,11 @@
     --grove-gray-5: var(--color-ink-700);
     --grove-gray-6: var(--color-ink-800);
     --grove-gray-7: var(--color-ink-900);
-    --grove-primary: var(--grove-foreground);
-    --grove-primary-foreground: var(--grove-gray-7);
+    /* Dark mode lifts the brand color toward white (see BaseLayout's
+     * emitted `--grove-theme-primary-dark`) so contrast holds. The
+     * foreground is computed against that lifted value, never assumed. */
+    --grove-primary: var(--grove-theme-primary-dark, var(--grove-foreground));
+    --grove-primary-foreground: var(--grove-theme-primary-dark-foreground, var(--grove-gray-7));
     --grove-secondary: var(--grove-gray-6);
     --grove-secondary-foreground: var(--grove-foreground);
     --grove-muted: var(--grove-gray-6);
@@ -230,10 +286,27 @@
     --grove-border: var(--grove-gray-6);
     --grove-input: var(--grove-gray-5);
     --grove-ring: var(--grove-gray-4);
-    --grove-card: var(--grove-background);
+    /* Elevation: the dark raised surface sits just above the ink-950
+     * page (deliberate landing-page value; hover lifts to ink-900). */
+    --grove-surface-raised: #141516;
+    --grove-surface-sunken: oklch(11.5% 0 0);
+    --grove-surface-overlay: var(--grove-gray-7);
+    --grove-card: var(--grove-surface-raised);
     --grove-card-foreground: var(--grove-foreground);
-    --grove-popover: var(--grove-gray-7);
+    --grove-popover: var(--grove-surface-overlay);
     --grove-popover-foreground: var(--grove-foreground);
+    /* Selection: neutral inversion, mirrored. */
+    --grove-selected: var(--color-ink-100);
+    --grove-selected-foreground: var(--color-ink-950);
+    /* Status fills lift toward pastels with dark text-on-fill. */
+    --grove-success: #4ade80;
+    --grove-success-foreground: var(--color-ink-950);
+    --grove-warning: #fbbf24;
+    --grove-warning-foreground: var(--color-ink-950);
+    --grove-danger: #f87171;
+    --grove-danger-foreground: var(--color-ink-950);
+    --grove-info: #60a5fa;
+    --grove-info-foreground: var(--color-ink-950);
   }
 
   html {
@@ -289,9 +362,33 @@
     input[type="url"],
     input[type="email"],
     input:not([type]),
-    select,
     textarea
   ) {
+    appearance: none;
+    -webkit-appearance: none;
+  }
+
+  input[type="search"]::-webkit-search-cancel-button,
+  input[type="search"]::-webkit-search-results-button,
+  input[type="search"]::-webkit-search-results-decoration {
+    -webkit-appearance: none;
+    display: none;
+  }
+
+  /* Inputs that live INSIDE a styled shell (the hero search pill)
+   * opt out with `.grove-input-unstyled`: the shell owns the border,
+   * radius, background, and the focus treatment via `focus-within` —
+   * forcing a second background/radius/focus ring on the inner input
+   * paints a box-within-a-box. */
+  :where(
+    input[type="text"],
+    input[type="search"],
+    input[type="url"],
+    input[type="email"],
+    input:not([type]),
+    select,
+    textarea
+  ):not(.grove-input-unstyled) {
     border-color: var(--grove-input) !important;
     border-radius: var(--radius) !important;
     background-color: var(--grove-background) !important;
@@ -306,7 +403,7 @@
     input:not([type]),
     select,
     textarea
-  ):focus-visible {
+  ):not(.grove-input-unstyled):focus-visible {
     border-color: var(--grove-ring) !important;
     outline: none;
     box-shadow: 0 0 0 3px color-mix(in oklab, var(--grove-ring) 35%, transparent);
@@ -770,6 +867,21 @@
 .grove-toc summary { color: inherit; }
 .grove-toc[open] .grove-toc-chevron,
 .grove-toc > summary:hover .grove-toc-chevron { transform: rotate(90deg); }
+/* Desktop (lg+): keep the TOC contents visible even before the
+ * component script sets the `open` attribute (and with JS disabled).
+ * Closed `<details>` content lives in a hidden UA shadow slot, so
+ * both the legacy child rule and the modern `::details-content`
+ * override are needed for cross-browser coverage; the script in
+ * `TableOfContents.astro` sets `open` as the primary mechanism. */
+@media (width >= 64rem) {
+  .grove-toc:not([open]) > *:not(summary) {
+    display: block;
+  }
+  .grove-toc:not([open])::details-content {
+    content-visibility: visible;
+    display: block;
+  }
+}
 .grove-toc-item { padding: 0; }
 .grove-toc-link[data-toc-active] {
   background-color: var(--color-ink-100, #f0f0f0);

package/src/ui/Badge.astro

@@ -0,0 +1,38 @@
+---
+/**
+ * Badge — small labeled state indicator.
+ *
+ * Variant is the MEANING, not the color:
+ * - `neutral`  — plain metadata (counts, kinds).
+ * - `selected` — "you are here" (neutral inversion, never green).
+ * - `success` / `warning` / `danger` / `info` — actual status. These
+ *   use the status tokens, so green here means "healthy/succeeded",
+ *   not "brand" and not "selected".
+ */
+
+export type BadgeVariant = "neutral" | "selected" | "success" | "warning" | "danger" | "info";
+
+interface Props {
+  variant?: BadgeVariant;
+  class?: string;
+  [key: string]: unknown;
+}
+
+const VARIANTS: Record<BadgeVariant, string> = {
+  neutral: "border-border bg-secondary text-secondary-foreground",
+  selected: "border-transparent bg-selected text-selected-foreground",
+  success: "border-transparent bg-success text-success-foreground",
+  warning: "border-transparent bg-warning text-warning-foreground",
+  danger: "border-transparent bg-danger text-danger-foreground",
+  info: "border-transparent bg-info text-info-foreground",
+};
+
+const { variant = "neutral", class: className = "", ...rest } = Astro.props;
+---
+
+<span
+  class={`inline-flex min-h-5 items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium leading-none ${VARIANTS[variant]} ${className}`}
+  {...rest}
+>
+  <slot />
+</span>

package/src/ui/Button.astro

@@ -0,0 +1,42 @@
+---
+/**
+ * Button — the shared interactive control.
+ *
+ * Renders an `<a>` when `href` is given, otherwise a `<button>`.
+ * Styling comes exclusively from `buttonClass()` (ui/button.ts) so
+ * server components, consumer pages, and the client script share one
+ * definition. Pass layout-only extras (widths, one-off spacing)
+ * through `class`.
+ */
+import { buttonClass, type ButtonSize, type ButtonVariant } from "./button.js";
+
+interface Props {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  href?: string;
+  type?: "button" | "submit" | "reset";
+  rel?: string;
+  target?: string;
+  disabled?: boolean;
+  id?: string;
+  class?: string;
+  [key: string]: unknown;
+}
+
+const {
+  variant = "secondary",
+  size = "sm",
+  href,
+  type = "button",
+  class: className = "",
+  ...rest
+} = Astro.props;
+
+const classes = buttonClass(variant, size, className);
+---
+
+{href ? (
+  <a href={href} class={classes} {...rest}><slot /></a>
+) : (
+  <button type={type} class={classes} {...rest}><slot /></button>
+)}

package/src/ui/EmptyState.astro

@@ -0,0 +1,38 @@
+---
+/**
+ * EmptyState — a deliberate "nothing here" block that cannot be
+ * mistaken for normal content. Explains WHY the area is empty and
+ * offers a recovery action.
+ *
+ * Marked with `data-grove-empty-state` so quality gates can assert
+ * that empty regions render as empty states, not silent gaps.
+ */
+import { buttonClass, type ButtonVariant } from "./button.js";
+
+interface Props {
+  title: string;
+  /** Why it's empty / what will make it non-empty. */
+  description?: string;
+  /** Recovery action (rendered as a button-styled link). */
+  action?: { label: string; href: string; variant?: ButtonVariant };
+  class?: string;
+}
+
+const { title, description, action, class: className = "" } = Astro.props;
+---
+
+<div
+  data-grove-empty-state
+  class={`flex flex-col items-center gap-2 rounded-[calc(var(--radius)+0.25rem)] border border-dashed border-border bg-surface-sunken px-6 py-10 text-center ${className}`}
+>
+  <p class="m-0 text-sm font-medium text-foreground">{title}</p>
+  {description && (
+    <p class="m-0 max-w-[52ch] text-sm leading-relaxed text-muted-foreground">{description}</p>
+  )}
+  <slot />
+  {action && (
+    <a href={action.href} class={buttonClass(action.variant ?? "secondary", "sm", "mt-2")}>
+      {action.label}
+    </a>
+  )}
+</div>