@turquoisehealth/pit-viper 2.179.0 → 2.179.1-dev.0

package/claude-plugin/skills/create/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: create
+description: Build complete Pit Viper pages and layouts from natural language descriptions
+argument-hint: "<what you want to build>"
+allowed-tools: "Read, Glob, Grep, WebFetch, Write, Edit, mcp__pit-viper__search, mcp__pit-viper__storybook_get_component, mcp__pit-viper__css_get_docs, mcp__pit-viper__css_list_tokens, mcp__pit-viper__css_search_classes"
+---
+
+# Create Pit Viper Pages
+
+Build complete, working pages from natural language descriptions. No Vue, imports, or CSS knowledge required.
+
+## Input
+
+`$ARGUMENTS` — Natural language description of what to build:
+- "a dashboard with a sidebar and data table"
+- "a login form for the marketing site"
+- "a settings page with tabs for profile and notifications"
+
+### Optional Flags
+
+- `--theme=platform` or `--theme=consumer` — Override auto-detected theme
+- `--format=html` — Output plain HTML with web components instead of Vue SFC
+
+## Workflow
+
+### Step 1: Parse User Intent
+
+Extract from the description:
+1. **Page type:** dashboard, form, settings, landing page, list view, detail view
+2. **Components needed:** tables, charts, inputs, modals, etc.
+3. **Theme preference:** detect from keywords or use override
+
+### Step 2: Detect Theme
+
+**Consumer theme triggers:** marketing, consumer, public, landing, website, customer-facing, external
+**Platform theme triggers:** dashboard, admin, internal, platform, tool, portal, app (default)
+
+| Theme | CSS URL | Font | Heading-1 |
+|-------|---------|------|-----------|
+| Platform | `https://pitviper.turquoise.health/assets/css/pit-viper-v2.css` | Inter | 1.25rem (compact) |
+| Consumer | `https://pitviper.turquoise.health/assets/css/pit-viper-consumer.css` | GT Standard | 3.875rem (large) |
+
+### Step 3: Detect Output Format
+
+**HTML output triggers:** HTML, static site, no framework, plain, vanilla JS, web component
+**Vue SFC output:** Default for all other cases
+
+### Step 4: Select Layout Pattern
+
+Match the description to one of these patterns:
+
+#### Dashboard Pattern
+```
+PvSidePanel (showLeftSidebar=true)
+├── #left-sidebar: Navigation menu with links
+└── #main:
+    ├── Header: h1.pv-heading-1 + optional PvBreadcrumbs
+    ├── Toolbar: PvSearchInput + PvSelectButton filters
+    └── Content: PvDataTable or PvDataTableWithChart
+```
+
+#### Form Pattern
+```
+PvCard
+├── Header: h2.pv-heading-2
+├── Body: Form fields in .pv-flow-16
+│   ├── PvInput (text fields)
+│   ├── PvSelectButton (dropdowns)
+│   ├── PvCheckbox / PvSwitch (toggles)
+│   └── PvTextArea (multi-line)
+└── Footer: .pv-flex with PvButton (primary) + PvButton (ghost)
+```
+
+#### Settings Pattern
+```
+PvTabs (v-model bound to activeTab)
+└── Tab panels
+    ├── PvAccordion sections for grouping
+    └── Form elements within each section
+```
+
+#### List View Pattern
+```
+Container
+├── Header: h1.pv-heading-1 + PvButton (add new)
+├── Filters: PvSearchInput + PvSelectButton
+├── Table: PvDataTable with actions column
+└── Footer: PvPagination
+```
+
+#### Detail View Pattern
+```
+Container
+├── Header: PvBreadcrumbs + h1.pv-heading-1
+├── Metadata: .pv-flex with PvTag, PvPill, status
+└── Content: PvCard sections with data
+```
+
+#### Marketing/Landing Pattern (Consumer theme)
+```
+Page container
+├── Hero: .pv-surface-brand-accent
+│   ├── h1.pv-heading-1 (large in consumer theme)
+│   ├── p.pv-text-body-xl
+│   └── PvButton (size="lg")
+├── Features: .pv-flex grid of PvCard
+└── CTA: .pv-surface-brand
+    ├── h2.pv-heading-2.pv-text-inverse
+    └── PvButton (inverse)
+```
+
+### Step 5: Generate Code
+
+#### Vue SFC Output (Default)
+
+Generate a complete `<script setup>` + `<template>` file:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+// Import base components
+import { PvButton, PvInput, PvIcon } from '@turquoisehealth/pit-viper/components'
+// Import visualization components (if needed)
+import { PvDataTable, PvChart } from '@turquoisehealth/pit-viper/components/visualizations'
+// Import layout components (if needed)
+import PvSidePanel from '@turquoisehealth/pit-viper/components/layout/PvSidePanel/PvSidePanel.vue'
+
+// Reactive state
+const someValue = ref('')
+</script>
+
+<template>
+  <!-- Complete markup with Pit Viper components and classes -->
+</template>
+```
+
+#### HTML Output (Web Components)
+
+Generate complete HTML with CDN links:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Page Title</title>
+  <!-- Pit Viper CSS (Platform or Consumer) -->
+  <link rel="stylesheet" href="https://pitviper.turquoise.health/assets/css/pit-viper-v2.css">
+  <!-- Pit Viper Web Components -->
+  <script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-components.iife.js"></script>
+</head>
+<body>
+  <!-- Web components use kebab-case: pv-button, pv-input, etc. -->
+  <pv-button label="Click me"></pv-button>
+</body>
+</html>
+```
+
+### Step 6: Validate Output
+
+Before presenting the code:
+1. Verify all imports use correct paths
+2. Ensure all CSS classes exist (pv-* prefix)
+3. Check component props match the API
+4. Include sample data so the code runs immediately
+
+### Step 7: Present Output
+
+Return:
+1. The complete code (Vue SFC or HTML)
+2. A note about which CSS file to include (if Vue)
+3. Brief explanation of what was generated
+
+## Component Quick Reference
+
+### Base Components (from `@turquoisehealth/pit-viper/components`)
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `PvButton` | All buttons | `variant`, `size`, `leftIcon`, `loading`, `disabled` |
+| `PvInput` | Text inputs | `v-model`, `type`, `placeholder`, `error`, `disabled` |
+| `PvTextArea` | Multi-line input | `v-model`, `placeholder`, `rows` |
+| `PvSelectButton` | Dropdown | `v-model`, `options`, `label`, `placeholder` |
+| `PvMultiSelectButton` | Multi-select dropdown | `v-model`, `options`, `label` |
+| `PvCheckbox` | Checkbox | `v-model`, `label`, `disabled` |
+| `PvSwitch` | Toggle switch | `v-model`, `label`, `size` |
+| `PvSearchInput` | Search field | `v-model`, `placeholder` |
+| `PvTabs` | Tab navigation | `v-model`, `tabs` (array of {label, value}) |
+| `PvAccordion` | Collapsible section | `v-model`, `header` |
+| `PvModal` | Dialog | `v-model`, `header`; slots: `#body`, `#footer` |
+| `PvDrawer` | Side panel | `v-model`, `header`; slots: `#default`, `#footer` |
+| `PvCard` | Card container | slots: `#header`, `#default`, `#footer` |
+| `PvToast` | Notification | `label`, `variant` (success/error/info) |
+| `PvIcon` | SVG icon | `name`, `size` (12/16/20/24) |
+| `PvBreadcrumbs` | Navigation | `items` (array of {label, href}) |
+| `PvPagination` | Page controls | `v-model`, `totalPages` |
+| `PvTag` | Inline tag | `label`, `variant` |
+| `PvPill` | Rounded badge | `label`, `variant` |
+| `PvAvatar` | User avatar | `name`, `src`, `size` |
+| `PvBanner` | Alert banner | `variant`, `message` |
+| `PvSpinner` | Loading spinner | `size`, `variant` |
+| `PvSkeleton` | Loading placeholder | `width`, `height` |
+
+### Visualization Components (from `@turquoisehealth/pit-viper/components/visualizations`)
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `PvDataTable` | Data grid | `rowData`, `colDefs`, `pagination` |
+| `PvChart` | Charts | `type`, `data`, `options` |
+| `PvDataTableWithChart` | Combined view | `rowData`, `colDefs`, `chartType` |
+
+### Layout Components
+
+| Component | Import Path | Purpose |
+|-----------|-------------|---------|
+| `PvSidePanel` | `@turquoisehealth/pit-viper/components/layout/PvSidePanel/PvSidePanel.vue` | 3-column layout |
+
+## CSS Quick Reference
+
+### Typography
+- `.pv-heading-1` through `.pv-heading-5` — Headings
+- `.pv-text-body-xl`, `-lg`, `-md`, `-sm` — Body text
+- `.pv-text-title-md`, `-sm` — Semibold titles
+
+### Spacing
+- `.pv-stack-8`, `-16`, `-24`, `-32` — Vertical margin (margin-bottom)
+- `.pv-inset-square-8`, `-16`, `-24` — Padding (all sides)
+- `.pv-flow-8`, `-16`, `-24` — Gap between children
+
+### Layout
+- `.pv-flex` — Flexbox with 0.5rem gap
+- `.pv-flex-vertical` — Column direction
+- `.pv-space-between` — Justify space-between
+
+### Colors
+- `.pv-text-default`, `.pv-text-subdued`, `.pv-text-brand` — Text colors
+- `.pv-surface`, `.pv-surface-accent`, `.pv-surface-brand` — Backgrounds
+
+### Borders
+- `.pv-radius`, `.pv-radius-sm`, `.pv-radius-lg` — Border radius
+
+## Rules
+
+1. **Always generate complete, runnable code** — No placeholders or "add your code here"
+2. **Include sample data** — Tables should have 3-5 sample rows, forms should have default values
+3. **Use only valid Pit Viper classes** — No custom CSS, no Tailwind
+4. **Match theme to use case** — Marketing = Consumer, Dashboard = Platform
+5. **Prefer Vue SFC unless HTML requested** — Vue is the primary framework
+6. **Use semantic component choices** — PvSelectButton for dropdowns, not raw `<select>`
+
+## Examples
+
+### Example 1: Simple Login Form
+
+**Input:** "create a login form"
+
+**Output:**
+```vue
+<script setup>
+import { ref } from 'vue'
+import { PvButton, PvInput, PvCard } from '@turquoisehealth/pit-viper/components'
+
+const email = ref('')
+const password = ref('')
+const loading = ref(false)
+
+const handleLogin = () => {
+  loading.value = true
+  // Add login logic here
+}
+</script>
+
+<template>
+  <div class="pv-flex" style="min-height: 100vh; align-items: center; justify-content: center;">
+    <PvCard style="width: 400px;">
+      <template #header>
+        <h1 class="pv-heading-2">Sign In</h1>
+      </template>
+      
+      <form @submit.prevent="handleLogin" class="pv-flow-16">
+        <div>
+          <label class="pv-text-title-sm pv-stack-4">Email</label>
+          <PvInput v-model="email" type="email" placeholder="you@example.com" />
+        </div>
+        
+        <div>
+          <label class="pv-text-title-sm pv-stack-4">Password</label>
+          <PvInput v-model="password" type="password" placeholder="Enter password" />
+        </div>
+        
+        <PvButton type="submit" :loading="loading" style="width: 100%;">
+          Sign In
+        </PvButton>
+      </form>
+      
+      <template #footer>
+        <p class="pv-text-body-sm pv-text-subdued">
+          Don't have an account? <a href="#" class="pv-text-brand">Sign up</a>
+        </p>
+      </template>
+    </PvCard>
+  </div>
+</template>
+```
+
+### Example 2: Dashboard with Sidebar
+
+**Input:** "create a dashboard with sidebar navigation and a user table"
+
+**Output:**
+```vue
+<script setup>
+import { ref } from 'vue'
+import { PvButton, PvSearchInput, PvIcon } from '@turquoisehealth/pit-viper/components'
+import { PvDataTable } from '@turquoisehealth/pit-viper/components/visualizations'
+import PvSidePanel from '@turquoisehealth/pit-viper/components/layout/PvSidePanel/PvSidePanel.vue'
+
+const searchQuery = ref('')
+
+const users = ref([
+  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin', status: 'Active' },
+  { id: 2, name: 'Bob Smith', email: 'bob@example.com', role: 'Editor', status: 'Active' },
+  { id: 3, name: 'Carol White', email: 'carol@example.com', role: 'Viewer', status: 'Pending' },
+])
+
+const colDefs = [
+  { field: 'name', headerName: 'Name', flex: 1 },
+  { field: 'email', headerName: 'Email', flex: 1 },
+  { field: 'role', headerName: 'Role', width: 120 },
+  { field: 'status', headerName: 'Status', width: 100 },
+]
+
+const navItems = [
+  { label: 'Dashboard', icon: 'home', active: true },
+  { label: 'Users', icon: 'user' },
+  { label: 'Settings', icon: 'gear' },
+]
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <PvSidePanel :showLeftSidebar="true" :showRightSidebar="false">
+      <template #left-sidebar>
+        <nav class="pv-inset-square-16">
+          <p class="pv-text-title-md pv-stack-24">My App</p>
+          <ul style="list-style: none; padding: 0; margin: 0;">
+            <li 
+              v-for="item in navItems" 
+              :key="item.label"
+              class="pv-flex pv-inset-squish-8 pv-radius"
+              :class="{ 'pv-surface-highlight': item.active }"
+              style="cursor: pointer; --flex-gap: 0.75rem;"
+            >
+              <PvIcon :name="item.icon" :size="16" />
+              <span class="pv-text-body-md">{{ item.label }}</span>
+            </li>
+          </ul>
+        </nav>
+      </template>
+      
+      <template #main>
+        <div class="pv-inset-square-24">
+          <div class="pv-flex pv-space-between pv-stack-24">
+            <h1 class="pv-heading-1">Users</h1>
+            <PvButton leftIcon="plus">Add User</PvButton>
+          </div>
+          
+          <div class="pv-stack-16">
+            <PvSearchInput 
+              v-model="searchQuery" 
+              placeholder="Search users..." 
+              style="max-width: 300px;"
+            />
+          </div>
+          
+          <PvDataTable 
+            :rowData="users" 
+            :colDefs="colDefs"
+            style="height: 400px;"
+          />
+        </div>
+      </template>
+    </PvSidePanel>
+  </div>
+</template>
+```
+
+**Note:** Include `pit-viper-v2.css` in your app's HTML or main entry file.

package/claude-plugin/skills/resolve/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: resolve
+description: Find the correct Pit Viper component for a UI element
+argument-hint: "<description | figma-url | html-snippet>"
+allowed-tools: "Read, Glob, Grep, WebFetch, mcp__figma__get_code_connect_map, mcp__figma__get_code_connect_suggestions, mcp__figma__get_design_context, mcp__claude_ai_Figma__get_code_connect_map, mcp__claude_ai_Figma__get_code_connect_suggestions, mcp__claude_ai_Figma__get_design_context, mcp__pit-viper__search, mcp__pit-viper__storybook_get_component, mcp__pit-viper__storybook_list_components, mcp__pit-viper__css_get_docs, mcp__pit-viper__css_list_components"
+---
+
+# Resolve Pit Viper Component
+
+Given a UI element description, Figma URL, or HTML snippet, find the correct Pit Viper component with props and usage example.
+
+## Input
+
+`$ARGUMENTS` — One of:
+- Text description (e.g., "dropdown with search", "data table with pagination")
+- Figma URL (extracts component via MCP)
+- HTML/code snippet to convert
+
+## Resolution Order
+
+### 1. Code Connect (Figma URLs only)
+
+If input is a Figma URL:
+1. Extract `fileKey` and `nodeId` from the URL
+2. Call `get_code_connect_map` to check for direct Figma-to-code mappings
+3. If a mapping exists, use it and skip to output
+
+### 2. Component Mapping Rules
+
+Apply these built-in mappings before searching external sources:
+
+| Design Element | Component | Import Path |
+|----------------|-----------|-------------|
+| Any table or data grid | `PvDataTable` | `@turquoisehealth/pit-viper/components/visualizations` |
+| Any chart or visualization | `PvChart` | `@turquoisehealth/pit-viper/components/visualizations` |
+| Dropdown (single select) | `PvSelectButton` | `@turquoisehealth/pit-viper/components` |
+| Dropdown (multi select) | `PvMultiSelectButton` | `@turquoisehealth/pit-viper/components` |
+| Modal or dialog | `PvModal` | `@turquoisehealth/pit-viper/components` |
+| Side panel or drawer | `PvDrawer` | `@turquoisehealth/pit-viper/components` |
+| Tabs | `PvTabs` | `@turquoisehealth/pit-viper/components` |
+| Segmented control | `PvSegmentedControl` | `@turquoisehealth/pit-viper/components` |
+| Search input | `PvSearchInput` | `@turquoisehealth/pit-viper/components` |
+| Text input | `PvInput` | `@turquoisehealth/pit-viper/components` |
+| Toggle or switch | `PvSwitch` | `@turquoisehealth/pit-viper/components` |
+| Checkbox | `PvCheckbox` | `@turquoisehealth/pit-viper/components` |
+| Button | `PvButton` | `@turquoisehealth/pit-viper/components` |
+| Tag or badge | `PvTag` or `PvPill` | `@turquoisehealth/pit-viper/components` |
+| Loading skeleton | `PvSkeleton` | `@turquoisehealth/pit-viper/components` |
+| Spinner | `PvSpinner` | `@turquoisehealth/pit-viper/components` |
+| Tooltip | `PvTooltipV2` | `@turquoisehealth/pit-viper/components` |
+| Accordion | `PvAccordion` | `@turquoisehealth/pit-viper/components` |
+| Breadcrumbs | `PvBreadcrumbs` | `@turquoisehealth/pit-viper/components` |
+| Pagination | `PvPagination` | `@turquoisehealth/pit-viper/components` |
+| Avatar | `PvAvatar` | `@turquoisehealth/pit-viper/components` |
+| Icon | `PvIcon` | `@turquoisehealth/pit-viper/components` |
+| Card | `PvCard` | `@turquoisehealth/pit-viper/components` |
+| Banner or alert | `PvBanner` | `@turquoisehealth/pit-viper/components` |
+| Toast notification | `PvToast` | `@turquoisehealth/pit-viper/components` |
+| Progress bar | `PvProgressBar` | `@turquoisehealth/pit-viper/components` |
+| Date picker | `PvDatePicker` | `@turquoisehealth/pit-viper/components` |
+
+### 3. MCP Lookup (Preferred)
+
+Use the Pit Viper MCP tools for fast, structured component data:
+
+**For Vue components:**
+1. Call `mcp__pit-viper__storybook_get_component` with the component name (e.g., "PvButton")
+2. Returns: props, argTypes, stories, and source code
+
+**For CSS components:**
+1. Call `mcp__pit-viper__css_get_docs` with the component name (e.g., "buttons")
+2. Returns: classes, documentation, and examples
+
+**For general search:**
+1. Call `mcp__pit-viper__search` with a query
+2. Returns: matches across both CSS and Vue components
+
+### 4. Plugin Examples (Fallback)
+
+Check if a curated example exists in the plugin's `examples/` directory:
+
+```
+examples/{ComponentName}.vue
+```
+
+If found, read the file for usage patterns.
+
+### 5. Storybook Web Lookup (Fallback)
+
+If the component is identified but you need props and usage:
+
+1. Fetch the Storybook index: `https://pit-viper-storybook.netlify.app/index.json`
+2. Find the matching component story by name
+3. Fetch docs page: `https://pit-viper-storybook.netlify.app/?path=/docs/{story-id}`
+4. Extract props, variants, and code examples
+
+### 6. Installed Package Types
+
+If the project has `@turquoisehealth/pit-viper` installed, read type definitions for exact prop types:
+
+```
+node_modules/@turquoisehealth/pit-viper/pv-components/dist/vue/{ComponentName}.vue.d.ts
+node_modules/@turquoisehealth/pit-viper/pv-components/dist/vue/{ComponentName}/types.d.ts
+```
+
+## Output
+
+Return a structured result:
+
+```
+## Component: PvSelectButton
+
+**Import:**
+import { PvSelectButton } from '@turquoisehealth/pit-viper/components'
+
+**Key Props:**
+- `v-model` — Selected value
+- `options` — Array of { label, value } objects
+- `optionsVariant` — 'default' | 'checkbox' | 'radio'
+- `label` — Input label text
+- `placeholder` — Placeholder when empty
+- `searchable` — Enable search filtering (default: true)
+
+**Usage Example:**
+<PvSelectButton
+  v-model="selected"
+  :options="options"
+  label="Select an option"
+  placeholder="Choose..."
+/>
+
+**Confidence:** high (built-in mapping)
+**Storybook:** https://pit-viper-storybook.netlify.app/?path=/docs/components-pvselect--docs
+```
+
+## Confidence Levels
+
+- **high** — Code Connect match or built-in mapping rule
+- **medium** — Storybook match with clear props
+- **low** — Best guess, recommend verification
+
+If no matching Pit Viper component exists, say so explicitly and suggest the user check if it should be added to the design system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turquoisehealth/pit-viper",
-  "version": "2.179.0",
+  "version": "2.179.1-dev.0",
   "description": "Turquoise Health's design system.",
   "main": "README.md",
   "publishConfig": {
@@ -16,7 +16,8 @@
     "_site/assets/js/pit-viper.js",
     "_src/assets/sprite.svg",
     "_src/assets/sprite-v2.svg",
-    "pv-components/dist"
+    "pv-components/dist",
+    "claude-plugin"
   ],
   "engines": {
     "node": ">=24.0.0"
@@ -137,6 +138,8 @@
     "build:eleventy": "eleventy",
     "build:pagefind": "pagefind --site _site",
     "build:pv-components": "pnpm --filter pv-components run build",
+    "build:mcp": "pnpm --filter pit-viper-mcp run build",
+    "build:mcp-index": "pnpm --filter pit-viper-mcp run build:index",
     "start": "npm-run-all build:sass --parallel watch:*",
     "build": "npm-run-all build:*",
     "test": "pnpm --filter pv-components run test && pnpm --filter pv-storybook run test:e2e",