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

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "pit-viper",
+  "version": "1.0.0",
+  "description": "Pit Viper design system tooling for Claude Code"
+}

package/claude-plugin/CLAUDE.md

@@ -0,0 +1,286 @@
+# Pit Viper Design System Reference
+
+This plugin provides tooling for Turquoise Health's Pit Viper design system. Use `/pit-viper:resolve` to find components and `/pit-viper:audit` to check compliance.
+
+## Resources
+
+- **Storybook:** https://pit-viper-storybook.netlify.app
+- **Icons:** https://pitviper.turquoise.health/visual-style/icons/
+
+### CSS Themes
+
+For complete utility class definitions, fetch the appropriate theme:
+
+| Theme | URL | Usage |
+|-------|-----|-------|
+| **Platform** (default) | https://pitviper.turquoise.health/assets/css/pit-viper-v2.css | Internal platform apps |
+| **Consumer** | https://pitviper.turquoise.health/assets/css/pit-viper-consumer.css | Marketing / consumer-facing pages |
+
+Do not use the `-scoped` variant.
+
+## Overview
+
+Pit Viper is Turquoise Health's custom design system. It exists as:
+
+1. **CSS framework** — utility classes for spacing, typography, color, layout (`pv-*` prefix)
+2. **Vue component library** — `@turquoisehealth/pit-viper`, providing 58+ components
+
+**Package:** `@turquoisehealth/pit-viper` in `node_modules/`
+**Font:** Inter (400, 500, 600)
+**Type scale:** Compact (body-md = 0.75rem / 12px)
+
+## Color Palette
+
+### Brand Colors
+| Token | Hex | Usage |
+|---|---|---|
+| Primary Brand | `#176F6F` | Interactive text, links, primary buttons, borders |
+| Secondary Brand | `#02363D` | Body text, secondary buttons, dark surfaces |
+| Brand Accent Light | `#A8E6E1` | Inverse buttons, AI button, tertiary buttons |
+| Brand Accent Bg | `#F3FCFB` | Brand accent backgrounds |
+| Brand Variant | `#16696D` | Visited links, tag primary, status success |
+| Brand Gradient | `linear-gradient(109deg, #176F6F 0%, #02363D 100%)` | Brand surface gradient |
+
+### Semantic Colors
+| Token | Hex | Usage |
+|---|---|---|
+| Error / Critical | `#DA1E28` | Error text, destructive buttons |
+| Error Hover | `#A2191F` | Error border, destructive hover |
+| Warning | `#896000` | Warning text |
+| Success | `#0E6027` | Success text |
+| Success Status | `#218C88` | Checked states, success status dots |
+| Yellow Status | `#E5A000` | Status indicators |
+
+### Text Colors
+| Class | Hex | Usage |
+|---|---|---|
+| `.pv-text-default` | `#02363D` | Primary body text |
+| `.pv-text-subdued` | `#6E7784` | Secondary/helper text |
+| `.pv-text-tertiary` | `#6E8081` | Tertiary text |
+| `.pv-text-inverse` | `#FFFFFF` | Text on dark surfaces |
+| `.pv-text-brand` | `#176F6F` | Brand-colored text, links |
+| `.pv-text-critical` | `#DA1E28` | Error messages |
+| `.pv-text-warning` | `#896000` | Warning text |
+| `.pv-text-success` | `#0E6027` | Success text |
+
+### Surface Colors
+| Class | Hex | Usage |
+|---|---|---|
+| `.pv-surface` | `#FFFFFF` | Default background |
+| `.pv-surface-accent` | `#F8F8FA` | Subtle alternate backgrounds |
+| `.pv-surface-brand` | `#02363D` | Dark brand surfaces |
+| `.pv-surface-brand-inverse` | `#176F6F` | Teal brand surfaces |
+| `.pv-surface-highlight` | `#E4F8F6` | Highlight/selection backgrounds |
+| `.pv-surface-brand-accent` | `#F3FCFB` | Light teal backgrounds |
+| `.pv-surface-inverse` | `#242626` | Dark mode surfaces |
+| `.pv-surface-warning` | `#FAECCC` | Warning backgrounds |
+| `.pv-surface-success` | `#E8FDEA` | Success backgrounds |
+| `.pv-surface-critical` | `#FFF1F1` | Error backgrounds |
+
+### Border Colors
+| Token | Hex | Usage |
+|---|---|---|
+| Default | `#DCDFE4` | Standard borders |
+| Accent | `#176F6F` | Active/focus borders |
+| Warning | `#EFC666` | Warning borders |
+| Critical | `#A2191F` | Error borders |
+| Brand | `#02363D` | Brand borders |
+
+### Data Visualization Colors (in order)
+1. `#36C5BA` 2. `#16696D` 3. `#FF7A4E` 4. `#C97AEB` 5. `#F2AD0D` 6. `#7C8AF4` 7. `#95C54C`
+
+## Typography
+
+### Headings
+| Class | Size | Line Height | Weight |
+|---|---|---|---|
+| `.pv-heading-1` | 1.25rem (20px) | 1.2 | 600 |
+| `.pv-heading-2` | 1rem (16px) | 1.5 | 600 |
+| `.pv-heading-3` | 0.875rem (14px) | 1.43 | 600 |
+| `.pv-heading-4` | 0.75rem (12px) | 1.33 | 600 |
+| `.pv-heading-5` | 0.75rem (12px) | 1.33 | 600 |
+
+### Body Text
+| Class | Size | Line Height |
+|---|---|---|
+| `.pv-text-body-xl` | 0.875rem (14px) | 1.14 |
+| `.pv-text-body-lg` | 0.875rem (14px) | 1.14 |
+| `.pv-text-body-md` | 0.75rem (12px) | 1.33 |
+| `.pv-text-body-sm` | 0.6875rem (11px) | 1.45 |
+| `.pv-text-body-xs` | 0.6875rem (11px) | 1.45 |
+
+### Title Classes (semibold variants)
+`.pv-text-title-xl`, `.pv-text-title-lg`, `.pv-text-title-md`, `.pv-text-title-sm`, `.pv-text-title-xs` — same sizes as body, weight 600.
+
+### Eyebrow Classes
+| Class | Size | Weight | Style |
+|---|---|---|---|
+| `.pv-text-eyebrow-lg` | 0.875rem | 700 | Uppercase, letter-spacing 0.0375rem |
+| `.pv-text-eyebrow-sm` | 0.75rem | 700 | Uppercase, letter-spacing 0.0375rem |
+
+## Spacing
+
+All spacing uses a 4px base grid. Classes apply `margin-bottom` (stack) or `padding` (inset).
+
+### Stack (Vertical Margin)
+| Class | Value |
+|---|---|
+| `.pv-stack-0` | 0 |
+| `.pv-stack-4` | 0.25rem (4px) |
+| `.pv-stack-8` | 0.5rem (8px) |
+| `.pv-stack-12` | 0.75rem (12px) |
+| `.pv-stack-16` | 1rem (16px) |
+| `.pv-stack-20` | 1.25rem (20px) |
+| `.pv-stack-24` | 1.5rem (24px) |
+| `.pv-stack-32` | 2rem (32px) |
+| `.pv-stack-64` | 4rem (64px) |
+| `.pv-stack-128` | 8rem (128px) |
+
+Responsive variants (e.g. `.pv-stack-16-responsive`) use half-size on mobile, full size at 768px+.
+
+### Inset (Padding)
+| Pattern | Example Classes | Description |
+|---|---|---|
+| Square (all sides) | `.pv-inset-square-8` through `-48` | Equal padding |
+| Squish (horiz > vert) | `.pv-inset-squish-8`, `-12`, `-16` | e.g. `0.75rem 1rem` |
+| Block (vertical) | `.pv-inset-block-8` through `-32` | `padding-block` only |
+| Inline (horizontal) | `.pv-inset-inline-16` through `-32` | `padding-inline` only |
+
+### Flow (Gap between children)
+`.pv-flow-8`, `.pv-flow-16`, `.pv-flow-24` — margin-bottom on all children except last.
+
+### Flex
+| Class | Description |
+|---|---|
+| `.pv-flex` | `display: flex; gap: 0.5rem; align-items: center` |
+| `.pv-flex-vertical` | Column direction |
+| `.pv-flex-responsive` | Column on mobile, row at 768px+ |
+| `.pv-flex-item` | `flex: 1` |
+| `.pv-space-between` | `justify-content: space-between` |
+
+Use CSS custom property `--flex-gap` to override gap, `--flex-justify` for justify-content.
+
+## Border Radius
+
+| Class | Value |
+|---|---|
+| `.pv-radius-sm` | 2px |
+| `.pv-radius` | 5px (default) |
+| `.pv-radius-lg` | 12px |
+| `.pv-radius-top` | 5px 5px 0 0 |
+| `.pv-radius-bottom` | 0 0 5px 5px |
+
+## Shadows & Elevation
+
+| Level | Usage | Value |
+|---|---|---|
+| Button | Default button elevation | `0px 6px 8px rgba(0,0,0,0.05), 0px 4px 6px -2px rgba(0,0,0,0.04)` |
+| Popover | Dropdowns, popovers | `0px 8px 12px -4px rgba(0,0,0,0.08), 0px 12px 16px rgba(0,0,0,0.1)` |
+| Elevated Hover | Button hover state | `0px 12px 16px rgba(0,0,0,0.1), 0px 8px 12px -4px rgba(0,0,0,0.08)` |
+| Modal | Dialogs, drawers | `0px 12px 20px rgba(0,0,0,0.25), 0px 16px 28px -8px rgba(0,0,0,0.25)` |
+
+## Responsive Breakpoints
+
+| Breakpoint | Usage |
+|---|---|
+| **768px** | Primary breakpoint — sidebar collapses, flex columns stack, responsive spacing adjusts |
+
+Container max-widths: `.pv-container-sm` (768px), `.pv-container-md` (972px), `.pv-container-lg` (1448px).
+
+Standard transition duration: **0.125s ease-in-out**.
+
+## Components
+
+### Most Commonly Used
+| Component | Purpose |
+|---|---|
+| `PvButton` | All buttons (props: `variant`, `size`, `leftIcon`, `rightIcon`, `loading`, `disabled`, `inverse`) |
+| `PvAiButton` | AI-specific action buttons |
+| `PvIcon` | SVG icon (props: `name`, `size`: 10/12/20/24/32/64) |
+| `PvSpinner` | Loading spinner (props: `variant`, `size`) |
+| `PvInput` | Text input (v-model, props: `type`, `variant`, `placeholder`, `error`, `disabled`) |
+| `PvTextArea` | Multi-line input |
+| `PvCheckbox` | Checkbox (v-model, props: `indeterminate`, `disabled`) |
+| `PvSwitch` | Toggle switch (v-model, props: `size`, `label`, `disabled`) |
+| `PvSelectButton` | Dropdown with search (v-model, props: `options`, `optionsVariant`, `label`) |
+| `PvTabs` | Tab bar (v-model, props: `tabs` array with `label`/`counter`/`icon`) |
+| `PvSegmentedControl` | Button group toggle |
+| `PvModal` | Dialog (v-model, props: `header`, `subheader`; slots: `#body`, `#footer`) |
+| `PvDrawer` | Side panel (v-model, props: `header`, `showSearchbar`; slots: `#header`, `#default`, `#footer`) |
+| `PvAccordion` | Collapsible section (v-model, props: `header`, `chevronPosition`, `counter`) |
+| `PvToast` | Notification (props: `label`, `variant`: success/error/info/dark) |
+| `PvTooltip` | Tooltip (props: `variant`, `tooltipPosition`, `interactive`; slots: `#label`, `#tooltip-content`) |
+| `PvPopoverMenu` | Dropdown menu |
+| `PvTag` | Inline tag |
+| `PvPill` | Rounded badge |
+| `PvCounterBadge` | Numeric badge |
+| `PvBanner` | Alert banner |
+| `PvAvatar` | User avatar |
+| `PvCard` | Card container |
+| `PvSkeleton` | Loading placeholder |
+| `PvProgressBar` | Progress indicator |
+| `PvTree` | Hierarchical tree |
+| `PvSidePanel` | Three-column layout |
+| `PvBreadcrumbs` | Breadcrumb nav |
+| `PvPagination` | Pagination controls |
+
+### Visualization Components
+Import from `@turquoisehealth/pit-viper/components/visualizations`:
+
+| Component | Purpose |
+|---|---|
+| `PvDataTable` | AG Grid wrapper for data tables |
+| `PvChart` | AG Charts wrapper for visualizations |
+| `PvDataTableWithChart` | Combined table and chart view |
+| `PvMapChart` | Geographic map visualization |
+
+## Import Paths
+
+```typescript
+// Base components
+import { PvButton, PvInput, PvModal } from '@turquoisehealth/pit-viper/components'
+
+// Visualization components
+import { PvDataTable, PvChart } from '@turquoisehealth/pit-viper/components/visualizations'
+```
+
+## Theme Selection
+
+Choose the appropriate theme based on the application type:
+
+| Application Type | Theme | CSS File |
+|-----------------|-------|----------|
+| Internal tools, dashboards, admin panels | Platform | `pit-viper-v2.css` |
+| Marketing pages, public websites, consumer apps | Consumer | `pit-viper-consumer.css` |
+
+### Key Visual Differences
+
+| Property | Platform | Consumer |
+|----------|----------|----------|
+| Font Family | Inter | GT Standard |
+| Heading-1 Size | 1.25rem (20px) | 3.875rem (62px) |
+| Body Text Size | 0.75rem (12px) | 1rem (16px) |
+| Overall Density | Compact | Spacious |
+| Color Warmth | Cool blue-gray | Warmer teal |
+
+### Theme URLs
+
+```
+Platform: https://pitviper.turquoise.health/assets/css/pit-viper-v2.css
+Consumer: https://pitviper.turquoise.health/assets/css/pit-viper-consumer.css
+```
+
+### Web Components (for non-Vue apps)
+
+```html
+<script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-components.iife.js"></script>
+```
+
+Web components use kebab-case: `<pv-button>`, `<pv-input>`, `<pv-card>`, etc.
+
+## Rules
+
+1. **No custom CSS** — Use only Pit Viper utility classes (see CSS Themes above)
+2. **No Tailwind** — Pit Viper has its own utility system
+3. **Prefer components** — Use Pit Viper components over raw HTML elements
+4. **Valid icons only** — Only use icon names from https://pitviper.turquoise.health/visual-style/icons/

package/claude-plugin/README.md

@@ -0,0 +1,119 @@
+# Pit Viper Claude Plugin
+
+Internal Claude Code plugin for Pit Viper design system tooling.
+
+## Installation
+
+### Claude Code CLI
+
+```bash
+claude --plugin-dir ~/claude-plugins-pit-viper
+```
+
+Or add to your Claude Code settings for persistent installation.
+
+### Cowork
+
+Contact DevTools team for managed installation.
+
+## Prerequisites
+
+Your project should have `@turquoisehealth/pit-viper` installed:
+
+```bash
+npm install @turquoisehealth/pit-viper
+```
+
+For Figma integration, authenticate via `/mcp` in Claude Code.
+
+## Available Skills
+
+### `/pit-viper:create`
+
+Build complete pages and layouts from natural language descriptions. No Vue, imports, or CSS knowledge required.
+
+**Usage:**
+```
+/pit-viper:create a dashboard with a sidebar and data table
+/pit-viper:create a login form
+/pit-viper:create a settings page with tabs for profile and notifications
+/pit-viper:create a marketing landing page with hero and features
+```
+
+**Output:** Complete Vue SFC or HTML file ready to use.
+
+**Theme Detection:**
+- Keywords like "marketing", "landing", "consumer" → Consumer theme (large typography)
+- Keywords like "dashboard", "admin", "internal" → Platform theme (compact, default)
+- Override with `--theme=consumer` or `--theme=platform`
+
+**Format Options:**
+- Default: Vue Single File Component (`<script setup>` + `<template>`)
+- Add `--format=html` for plain HTML with web components
+
+### `/pit-viper:resolve`
+
+Find the correct Pit Viper component for a UI element.
+
+**Usage:**
+```
+/pit-viper:resolve dropdown with search
+/pit-viper:resolve <figma-url>
+/pit-viper:resolve <html-snippet>
+```
+
+**Output:** Component name, import path, props, and usage example.
+
+### `/pit-viper:audit`
+
+Check files for design system compliance and auto-fix violations.
+
+**Usage:**
+```
+/pit-viper:audit                           # Audit git-changed files
+/pit-viper:audit src/components/Foo.vue    # Audit specific file
+/pit-viper:audit --all                     # Audit all Vue/HTML files
+```
+
+**Checks:**
+- Custom CSS (`<style>` blocks, inline styles)
+- Raw HTML elements that should be Pit Viper components
+- Invalid CSS class names
+- Wrong import paths
+
+## Adding Production Examples
+
+Add curated code snippets to `examples/` for the resolve skill to reference:
+
+```
+examples/
+├── PvDataTable.vue         # Common table patterns
+├── PvSelectButton.vue      # Dropdown usage
+├── PvModal.vue             # Modal with form
+└── ...
+```
+
+The resolve skill checks `examples/{ComponentName}.vue` before falling back to Storybook.
+
+## Resources
+
+- **Storybook:** https://pit-viper-storybook.netlify.app
+- **Icons:** https://pitviper.turquoise.health/visual-style/icons/
+- **Design Tokens:** See `CLAUDE.md` for full color, typography, and spacing reference
+- **MCP Server:** https://pitviper.turquoise.health/mcp
+
+## MCP Tools
+
+The plugin uses the Pit Viper MCP server for fast component lookups. Available tools:
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__pit-viper__search` | Search across CSS and Vue components |
+| `mcp__pit-viper__storybook_get_component` | Get Vue component details (props, stories, source) |
+| `mcp__pit-viper__storybook_list_components` | List all Vue components with stories |
+| `mcp__pit-viper__css_get_docs` | Get CSS component documentation |
+| `mcp__pit-viper__css_list_components` | List CSS components by category |
+| `mcp__pit-viper__css_list_tokens` | List design tokens (colors, spacing, etc.) |
+| `mcp__pit-viper__css_search_classes` | Search CSS classes by pattern |
+
+The MCP server is automatically enabled when using this plugin in the pit-viper repo.

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

@@ -0,0 +1,125 @@
+---
+name: audit
+description: Check Vue/HTML files for Pit Viper design system compliance and auto-fix violations
+argument-hint: "[file-path | --all]"
+allowed-tools: "Read, Glob, Grep, Edit, Bash"
+---
+
+# Audit Design System Compliance
+
+Check Vue and HTML files for Pit Viper design system violations and automatically fix them.
+
+## Input
+
+`$ARGUMENTS` — One of:
+- File path(s) to audit (e.g., `src/components/MyComponent.vue`)
+- `--all` to audit all `.vue` and `.html` files in the project
+- Empty: auto-detect changed files via `git diff --name-only`
+
+## Workflow
+
+### Step 1: Identify files to audit
+
+- If file path(s) provided, use those
+- If `--all`, glob for `**/*.vue` and `**/*.html`
+- If empty, run `git diff --name-only` to find changed `.vue` and `.html` files
+
+If no files to audit, report "No files to audit" and exit.
+
+### Step 2: Read each file
+
+For each file:
+- `.vue` files: check `<template>` and `<style>` sections
+- `.html` files: check all markup and inline styles
+
+### Step 3: Check for violations
+
+#### Custom CSS (auto-fix: replace with Pit Viper classes)
+
+- `<style>` blocks — remove and replace CSS rules with Pit Viper utility classes
+- `style="..."` inline attributes — remove and apply equivalent Pit Viper classes
+
+#### Raw HTML elements (auto-fix: replace with Pit Viper components)
+
+These raw elements should use Pit Viper equivalents:
+
+| Raw Element | Pit Viper Component |
+|-------------|---------------------|
+| `<button>` | `<PvButton>` |
+| `<table>` | `<PvDataTable>` |
+| `<input type="text">` | `<PvInput>` |
+| `<input type="checkbox">` | `<PvCheckbox>` |
+| `<input type="search">` | `<PvSearchInput>` |
+| `<select>` | `<PvSelectButton>` |
+| `<textarea>` | `<PvTextArea>` |
+| `<dialog>` | `<PvModal>` |
+
+**Exceptions (allowed):** Basic structural HTML is fine:
+`<div>`, `<span>`, `<p>`, `<h1>`-`<h6>`, `<a>`, `<img>`, `<ul>`, `<ol>`, `<li>`, `<section>`, `<header>`, `<footer>`, `<nav>`, `<main>`, `<article>`, `<aside>`, `<template>`, `<slot>`, `<form>`, `<label>`
+
+#### Invalid CSS class names
+
+Read the Pit Viper CSS file to validate class names:
+```
+node_modules/@turquoisehealth/pit-viper/_site/assets/css/pit-viper-v2.css
+```
+
+Flag any `class="..."` that contains classes not defined in `pit-viper-v2.css`. Suggest the closest valid class or remove invalid classes.
+
+#### Wrong import paths (Vue only)
+
+Check that Pit Viper imports use correct paths:
+- Base components: `@turquoisehealth/pit-viper/components`
+- Visualizations: `@turquoisehealth/pit-viper/components/visualizations`
+
+### Step 4: Apply fixes
+
+For each violation:
+1. Log the violation (file, line, issue)
+2. Apply the auto-fix
+3. Log what was changed
+
+### Step 5: Report
+
+Output a summary:
+
+```
+## Audit Results
+
+### src/components/MyComponent.vue
+
+**Violations found: 3**
+
+1. Line 15: `<style>` block with custom CSS
+   → Removed, applied `.pv-flex .pv-stack-16` to container
+
+2. Line 23: Raw `<button>` element
+   → Replaced with `<PvButton>`
+
+3. Line 31: Invalid class `custom-spacing`
+   → Replaced with `.pv-stack-8`
+
+---
+
+**Files audited:** 2
+**Violations found:** 5
+**Violations fixed:** 5
+```
+
+If no violations found:
+```
+## Audit Results
+
+All files pass design system compliance.
+
+**Files audited:** 3
+**Violations found:** 0
+```
+
+## Rules
+
+- Always auto-fix violations (don't just report)
+- Preserve file structure and formatting where possible
+- If a fix is ambiguous (multiple valid options), pick the most common pattern
+- If Pit Viper CSS file is not found, warn that `@turquoisehealth/pit-viper` may not be installed
+- Do not modify files outside the audit scope