feat(genesis): add GnDocsBadge primitive

.changeset/gn-docs-badge.md

@@ -0,0 +1,5 @@
+---
+"@paper/genesis": minor
+---
+
+feat(GnDocsBadge): add a static label/tag primitive for skill levels, modes, category tags, and similar docs-site chrome. Icon is slot-injected (no icon-name string), matching the GnPeek/GnDocsExampleTabs icon strategy; the icon wrapper is aria-hidden and slotted icons keep their own dimensions.

packages/genesis/SPEC.md

@@ -4,7 +4,7 @@
 
 A focused **docs-primitives library**: Vue 3 components that documentation sites need (live examples, callouts, code groups, API tables, atomic primitives). Headless on the parts that vary across consumers — code highlighting and icons are slot-injected.
 
-Genesis is a **thin component layer over v0's theme system**. Components consume `var(--v0-*)` tokens directly so they inherit whatever theme v0 has applied to the page. There is no Genesis-specific token namespace, no Genesis-specific theme plugin, no Genesis-specific stylesheet. Drop the package into any v0-themed app and components blend with the page's chrome.
+Genesis is a **thin component layer over v0's theme system**. Components consume `var(--v0-*)` tokens directly so they inherit whatever theme v0 has applied to the page. There is no Genesis-specific *theme* token namespace (the few `--gn-*` custom properties are consumer-tunable layout knobs, not tokens), no Genesis-specific theme plugin, no Genesis-specific stylesheet. Drop the package into any v0-themed app and components blend with the page's chrome.
 
 ## Package shape
 
@@ -16,21 +16,18 @@ packages/genesis/
 │   ├── index.ts          # re-exports components
 │   └── components/
 │       ├── index.ts
-│       ├── GnDocsExample/
-│       ├── GnDocsExampleDescription/
-│       ├── GnDocsExamplePreview/
-│       ├── GnDocsExampleCode/
-│       ├── GnDocsExampleTabs/
-│       ├── GnDocsExamplePanel/
-│       ├── GnDocsExampleActions/
+│       ├── GnActionButton/
+│       ├── GnDocsBadge/
+│       ├── GnDocsExample/    # GnDocsExample.vue + Description / Preview / Code / Tabs / Panel / Actions SFCs
+│       ├── GnDotGrid/
 │       └── GnPeek/
 ```
 
 No `GnDocsIcon`, no `adapter.ts`, no `plugin.ts`, no `theme.ts`. Genesis is just components.
 
 ## Theme inheritance
 
-Every component's scoped `<style>` references v0 tokens with sensible standalone fallbacks. Examples:
+Every component's `<style>` (scoped, except where a multi-root child blocks scoping — see `GnActionButton`) references v0 tokens with sensible standalone fallbacks; purely structural sub-components (`GnDocsExamplePanel`, `GnDocsExampleActions`) have no chrome to theme and reference no tokens. Tokens can also enter through prop defaults — `GnDotGrid`'s `color` prop defaults to `var(--v0-on-background)` while its style block is token-free. Examples:
 
 ```css
 .genesis-docs-example {
@@ -51,6 +48,7 @@ When v0's theme plugin is installed (any paper-DS-or-v0-themed app), `--v0-surfa
 | `--v0-primary` | Active tab, filename badge, peek pill |
 | `--v0-on-primary` | Text on primary |
 | `--v0-pre` | Code pane background |
+| `--v0-on-background` | `GnDotGrid` dots/lines (via its `color` prop default, not its stylesheet) |
 
 ## Components
 
@@ -65,11 +63,14 @@ interface GnDocsExampleProps {
   files?: GnDocsExampleFile[]  // multi-file (overrides code/language/fileName)
   fileOrders?: (number | undefined)[]
   title?: string               // description heading
-  collapse?: boolean           // collapsible description
+  collapse?: boolean           // accepted for API compatibility; the description always collapses
   peek?: boolean               // truncated code with expand button
   peekLines?: number           // default 6
   disableResize?: boolean      // skip splitter affordance
   hideWidthIndicator?: boolean // hide drag-width indicator
+  theme?: string               // scope a v0 theme to the preview (via data-theme)
+  showPlayground?: boolean     // "open in playground" button (multi-file toolbar)
+  showBin?: boolean            // "open in bin" button (multi-file toolbar)
 }
 ```
 
@@ -80,7 +81,7 @@ interface GnDocsExampleProps {
 | `GnDocsExampleDescription` | Heading + optional collapsible body; emits anchor-click |
 | `GnDocsExamplePreview` | Wraps preview slot in `Splitter.Root` unless `disableResize`; exposes `reset()`; surfaces drag width on the consumer slot |
 | `GnDocsExampleCode` | Single code pane; peek truncation; `<slot :code :language :file-name>` for highlighter (default: `<pre>` fallback) |
-| `GnDocsExampleTabs` | Tab list + overflow dropdown for hidden tabs; reset and combine action buttons; `<slot name="reset-icon">`, `<slot name="combine-icon">`, `<slot name="split-icon">` with inline-SVG defaults |
+| `GnDocsExampleTabs` | Tab list + overflow dropdown for hidden tabs; reset, combine, and opt-in playground/bin action buttons; `<slot name="reset-icon">`, `<slot name="playground-icon">`, `<slot name="bin-icon">`, `<slot name="combine-icon">`, `<slot name="split-icon">` with inline-SVG defaults |
 | `GnDocsExamplePanel` | Wraps one file's code pane content; provides the structural row inside a tab |
 | `GnDocsExampleActions` | Toolbar host; renders an `aria-label`-ed group around action buttons |
 
@@ -97,15 +98,59 @@ interface GnPeekProps {
 
 `v-model:expanded` drives state. The default slot exposes `{ expanded }` for the label; a separate `icon` slot defaults to an inline chevron that rotates 180° when expanded. Both slots are overridable.
 
+### `GnDocsBadge` — static label/tag
+
+A non-interactive `<span>` for skill levels, skill modes, category tags, and similar docs-site chrome. No business logic, no icon-name resolution.
+
+```ts
+interface GnDocsBadgeProps {
+  color?: string             // any CSS color (e.g. var(--v0-primary)); drives background+text tint via color-mix. Omit for neutral.
+  backgroundOpacity?: number // default: 15 (color-mix percentage, 0-100)
+  shape?: 'rounded' | 'pill' // default: 'rounded'
+  title?: string              // native tooltip
+}
+```
+
+Default slot is the label. An `icon` slot (no default) renders an optional leading icon — same "slot, not string" pattern as every other Genesis icon surface. The icon wrapper is `aria-hidden` (the icon is decorative by contract — the label is the accessible content), and slotted icons keep their own dimensions — the badge does not resize them.
+
+### `GnActionButton` — toolbar action affordance
+
+A 32px icon action button for docs chrome (copy, reset, open-in). Wraps v0's `Button.Root` + `Button.Icon`; ships an unscoped `<style>` because a scoped rule's data-v never lands on `Button.Root`'s multi-root `<button>`.
+
+```ts
+interface GnActionButtonProps {
+  ariaLabel?: string                     // forwarded to Button.Root's ariaLabel (solo icon buttons)
+  title?: string                         // native tooltip
+  type?: 'button' | 'submit' | 'reset'   // default: 'button'
+}
+```
+
+The icon goes in the default slot, rendered inside `Button.Icon`.
+
+### `GnDotGrid` — decorative backdrop
+
+An `aria-hidden`, absolutely-positioned dot-grid layer with a radial fade mask.
+
+```ts
+interface GnDotGridProps {
+  color?: string     // default: 'var(--v0-on-background)' — any CSS color
+  coverage?: number  // default: 15 — % of the radial fade kept transparent
+  density?: number   // default: 20 — grid cell size in px
+  lines?: number     // default: 0 — connecting-line alpha %; 0 = dots only
+  origin?: string    // default: 'bottom left' — fade origin
+}
+```
+
 ## Icon strategy
 
 Action buttons expose icon slots with inline `<svg>` defaults using MDI paths.
 
 | Component | Slots | Default icon |
 |---|---|---|
 | `GnDocsExample` | `reset-icon` (single-file mode reset button) | refresh |
-| `GnDocsExampleTabs` | `reset-icon`, `combine-icon`, `split-icon` | refresh / unfold-less / unfold-more |
+| `GnDocsExampleTabs` | `reset-icon`, `playground-icon`, `bin-icon`, `combine-icon`, `split-icon` | refresh / play / open-in-new / unfold-less / unfold-more |
 | `GnPeek` | `icon` (chevron, rotates when expanded) | chevron-down |
+| `GnDocsBadge` | `icon` | none — no generic badge icon to default to |
 
 ```vue
 <GnDocsExampleTabs>
@@ -126,40 +171,40 @@ Consumer-injected via the default slot on `GnDocsExampleCode`:
 </GnDocsExampleCode>
 ```
 
-Genesis ships a `<pre>` fallback only. The dev workspace's `DevShikiBlock.vue` and apps/docs's `useHighlightCode` both demonstrate Shiki integration.
+Genesis ships a `<pre>` fallback only. apps/docs's `useHighlightCode` demonstrates Shiki integration.
 
 ## Non-goals
 
-- Genesis-specific token namespace — components consume v0 tokens via the cascade
+- Genesis-specific *theme* token namespace — components consume v0 tokens via the cascade (the few `--gn-*` properties — `--gn-docs-example-sticky-top`, `--gn-docs-example-toggle-h` — are per-component layout knobs, not theme tokens)
 - Genesis plugin / adapter / theme — none shipped; v0's theme system is the source of truth
-- Playground / Bin / "open in" actions — docs-site concern
+- Playground / Bin / "open in" actions — `GnDocsExampleTabs` ships the opt-in buttons (`showPlayground` / `showBin`) and emits `playground` / `bin` with the current files; URL construction and navigation stay a docs-site concern
 - Bundled Shiki — slot consumption only
 - Icon library — slot defaults with inline SVG
 - Paper composables / V0Paper — not used
-- Buttons / forms / dialogs — out of scope
+- General-purpose buttons / forms / dialogs — out of scope (`GnActionButton` is docs-toolbar chrome wrapping v0's Button, not a general-purpose button offering)
 - Tests — only when explicitly requested
 
-## Future — per-example theme override
+## Per-example theme override
 
-The next architectural step (not yet implemented):
+Shipped:
 
 ```vue
 <GnDocsExample theme="corporateIndigo">
   <!-- preview slot renders as if v0's theme were corporateIndigo, regardless of the page's theme -->
 </GnDocsExample>
 ```
 
-Implementation sketch: `GnDocsExample` wraps its preview slot in `<div :data-theme="theme">` when the `theme` prop is set, scoping the v0 cascade for that subtree. The available theme names come from v0's `useTheme()` registry.
+`GnDocsExample` forwards `theme` to `GnDocsExamplePreview`, which sets `data-theme="<name>"` on the preview panel, scoping the v0 cascade for that subtree. Theme names come from v0's theme registry.
 
 ## Phase 2 roadmap
 
 In priority order:
 
 1. `GnDocsCallout` (TIP / WARNING / ERROR / INFO admonitions)
 2. `GnDocsCodeGroup` (tabbed code blocks)
-3. `GnDocsKbd`, `GnDocsBadge`, `GnDocsCard` (atomic primitives)
+3. `GnDocsKbd`, `GnDocsCard` (atomic primitives — `GnDocsBadge` shipped, see `## Components`)
 4. `GnDocsApi` (API reference tables with prop / event / slot sections + hover popovers)
-5. Per-example theme override prop on `GnDocsExample`
+5. Per-example theme override prop on `GnDocsExample` (shipped, see `## Per-example theme override`)
 
 ## Architectural lessons (Phase 1 → revised)
 

packages/genesis/src/components/GnDocsBadge/GnDocsBadge.vue

@@ -0,0 +1,79 @@
+<script lang="ts">
+  // Utilities
+  import { toRef } from 'vue'
+
+  export interface GnDocsBadgeProps {
+    /** Any CSS color value (e.g. `var(--v0-primary)`) driving the tinted background + matching text. Omit for a neutral badge. */
+    color?: string
+    /** Background tint strength as a color-mix percentage (0-100). */
+    backgroundOpacity?: number
+    /** Badge shape. */
+    shape?: 'rounded' | 'pill'
+    /** Native tooltip text. */
+    title?: string
+  }
+</script>
+
+<script setup lang="ts">
+  defineOptions({ name: 'GnDocsBadge' })
+
+  const {
+    color,
+    backgroundOpacity = 15,
+    shape = 'rounded',
+    title,
+  } = defineProps<GnDocsBadgeProps>()
+
+  const badgeStyle = toRef(() => {
+    if (!color) return undefined
+    return {
+      background: `color-mix(in srgb, ${color} ${backgroundOpacity}%, transparent)`,
+      color,
+    }
+  })
+</script>
+
+<template>
+  <span
+    class="genesis-docs-badge"
+    :data-shape="shape"
+    :style="badgeStyle"
+    :title
+  >
+    <span v-if="$slots.icon" aria-hidden="true" class="genesis-docs-badge__icon">
+      <slot name="icon" />
+    </span>
+
+    <slot />
+  </span>
+</template>
+
+<style scoped>
+  .genesis-docs-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding: 0.125rem 0.5rem;
+    border-radius: 0.25rem;
+    color: var(--v0-on-surface-variant, rgb(0 0 0 / 0.6));
+    background: color-mix(in srgb, var(--v0-on-surface, #1a1c1e) 8%, transparent);
+    font-size: 0.75rem;
+    font-weight: 600;
+    line-height: 1rem;
+    white-space: nowrap;
+  }
+
+  .genesis-docs-badge[data-shape='pill'] {
+    border-radius: 9999px;
+  }
+
+  .genesis-docs-badge__icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .genesis-docs-badge__icon:empty {
+    display: none;
+  }
+</style>

packages/genesis/src/components/GnDocsBadge/index.ts

@@ -0,0 +1,2 @@
+export type { GnDocsBadgeProps } from './GnDocsBadge.vue'
+export { default as GnDocsBadge } from './GnDocsBadge.vue'

packages/genesis/src/components/index.ts

@@ -1,4 +1,5 @@
 export * from './GnActionButton'
+export * from './GnDocsBadge'
 export * from './GnDocsExample'
 export * from './GnDotGrid'
 export * from './GnPeek'