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

package/claude-plugin/skills/pit-viper/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: pit-viper
+description: Use for all frontend work in a Turquoise Health codebase — UI building, Vue/HTML editing, component usage, and visual interface work.
+allowed-tools: Read Glob Grep Write Edit WebFetch
+---
+
+# Pit Viper Design System
+
+Use Pit Viper for all frontend work. This skill grounds you in what actually exists in the design system — no hallucinating components or inventing variants.
+
+## Workflow
+
+### Step 0: Detect Output Mode
+
+Read context signals to determine the appropriate output:
+
+| Mode | Signals | Output |
+|------|---------|--------|
+| **Engineer** | Editing .vue files, mentions "props", "emit", "component", Vue project context | Idiomatic Vue 3 Composition API code |
+| **Prototype** | "Quick prototype", "HTML", "no framework", non-technical user, unclear technical level | Plain HTML with pv-* classes and web components |
+| **Design Review** | "What component for...", "does this work with...", design discussion | Component selection rationale only — no code |
+
+If unclear, ask. If still unclear, default to **Prototype Mode** (most portable).
+
+### Step 1: Search for Components
+
+Search across Vue components and CSS utilities:
+
+```
+WebFetch https://pitviper.turquoise.health/llm/search?q=dropdown
+WebFetch https://pitviper.turquoise.health/llm/search?q=data%20table
+```
+
+Returns matching components with names, descriptions, and categories.
+
+### Step 2: Get Component Details
+
+Get props, argTypes, stories, and source code for a specific component:
+
+```
+WebFetch https://pitviper.turquoise.health/llm/component/PvSelectButton
+WebFetch https://pitviper.turquoise.health/llm/component/PvDataTable
+```
+
+For web components, add `?web_component=true`:
+```
+WebFetch https://pitviper.turquoise.health/llm/component/PvButton?web_component=true
+```
+
+### Step 3: Fetch CSS Utilities
+
+Get CSS component documentation:
+
+```
+WebFetch https://pitviper.turquoise.health/llm/css/flex
+WebFetch https://pitviper.turquoise.health/llm/css/spacing
+WebFetch https://pitviper.turquoise.health/llm/css/buttons
+```
+
+Get design tokens (colors, spacing, typography):
+
+```
+WebFetch https://pitviper.turquoise.health/llm/tokens
+WebFetch https://pitviper.turquoise.health/llm/tokens?category=color
+WebFetch https://pitviper.turquoise.health/llm/tokens?category=spacing
+```
+
+### LLM Endpoints Reference
+
+Base URL: `https://pitviper.turquoise.health`
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /llm` | API index |
+| `GET /llm/search?q={query}` | Search Vue + CSS components |
+| `GET /llm/component` | List all Vue components |
+| `GET /llm/component/{name}` | Get component details (props, stories, source) |
+| `GET /llm/css` | List all CSS components |
+| `GET /llm/css/{component}` | Get CSS component docs |
+| `GET /llm/css/themes` | Get theme CDN URLs |
+| `GET /llm/tokens` | List design tokens |
+| `GET /llm/tokens?category={cat}` | Filter tokens (color, spacing, typography, border, shadow) |
+
+Add `?web_component=true` to component endpoints for web component variants.
+
+### Step 4: Generate Output
+
+Based on detected mode, read the appropriate reference and generate:
+
+- **Engineer Mode**: Read `references/vue-guidelines.md`, produce Vue 3 SFC
+- **Prototype Mode**: Read `references/html-patterns.md`, produce HTML with pv-* classes
+- **Design Review Mode**: Read `references/design-language.md`, explain component selection
+
+For page-level layouts, also read `references/layout-patterns.md`.
+For theme decisions, also read `references/theme-guide.md`.
+
+## Anti-Patterns
+
+These are non-negotiable. Do not:
+
+- **Reach for Tailwind** — Pit Viper has its own utility system (pv-* classes)
+- **Invent component variants** — If it's not in Storybook, it doesn't exist. Search first.
+- **Use raw HTML form elements** — `<button>`, `<input>`, `<select>` have Pv equivalents
+- **Build custom tables** — Use PvDataTable (Vue) or pv-table classes (HTML). Never raw `<table>` with custom styling.
+- **Use third-party charting** — Use PvChart or PvDataTableWithChart (Vue only). No D3, Chart.js, or ApexCharts.
+- **Write custom CSS** — If a pv-* class doesn't exist, verify twice before adding styles
+- **Write custom table/chart CSS** — Tables and charts have complete Pit Viper styling. No custom styles.
+- **Guess icon names** — Verify at https://pitviper.turquoise.health/visual-style/icons/
+- **Import from barrel exports** — Import directly from component paths
+
+## When a Component Doesn't Exist
+
+If `/llm/search` returns no match for a legitimate UI need:
+
+1. Use the **closest existing component** + pv-* utility classes
+2. **Flag the gap** to the user: "Pit Viper doesn't have a dedicated X component — using PvY with custom layout. Consider requesting this from the design system team."
+3. Do NOT invent a fake component or silently use raw HTML
+
+## References
+
+Load these only when the specific condition applies:
+
+| File | Load when... |
+|------|--------------|
+| `references/design-rules.md` | **ALWAYS** — mandatory rules for spacing, typography, colors, layout |
+| `references/patterns-core.md` | **ALWAYS** — universal utility class patterns and anti-patterns |
+| `references/vue-guidelines.md` | Engineer Mode — Vue setup, patterns, and anti-patterns |
+| `references/html-patterns.md` | Prototype Mode — HTML/web component patterns and anti-patterns |
+| `references/design-language.md` | Design Review Mode — validating tokens or explaining layout rationale |
+| `references/layout-patterns.md` | Building a full page or multi-component layout (not single components) |
+| `references/theme-guide.md` | Choosing between Platform/Consumer CSS, or token values are ambiguous |
+
+**Important:** `design-rules.md` and `patterns-core.md` must be loaded for ANY code generation (Engineer or Prototype mode). Mode-specific files (`vue-guidelines.md` or `html-patterns.md`) contain both patterns and anti-patterns for that output format.
+
+## Quick Component Map
+
+Common UI needs and their Pit Viper equivalents:
+
+| Need | Component | Import | Notes |
+|------|-----------|--------|-------|
+| Button | `PvButton` | `@turquoisehealth/pit-viper/components` | |
+| Text input | `PvInput` | `@turquoisehealth/pit-viper/components` | |
+| Dropdown (single) | `PvSelectButton` | `@turquoisehealth/pit-viper/components` | |
+| Dropdown (multi) | `PvMultiSelectButton` | `@turquoisehealth/pit-viper/components` | |
+| Checkbox | `PvCheckbox` | `@turquoisehealth/pit-viper/components` | |
+| Toggle | `PvSwitch` | `@turquoisehealth/pit-viper/components` | |
+| Data table | `PvDataTable` | `@turquoisehealth/pit-viper/components/visualizations` | AG Grid wrapper — sorting, filtering, grouping |
+| Table + chart | `PvDataTableWithChart` | `@turquoisehealth/pit-viper/components/visualizations` | Combined table with integrated chart |
+| Chart | `PvChart` | `@turquoisehealth/pit-viper/components/visualizations` | AG Charts wrapper — bar, line, pie, etc. |
+| Modal | `PvModal` | `@turquoisehealth/pit-viper/components` | |
+| Drawer | `PvDrawer` | `@turquoisehealth/pit-viper/components` | |
+| Tabs | `PvTabs` | `@turquoisehealth/pit-viper/components` | |
+| Card | `PvCard` | `@turquoisehealth/pit-viper/components` | |
+| Toast | `PvToast` | `@turquoisehealth/pit-viper/components` | |
+| Tooltip | `PvTooltipV2` | `@turquoisehealth/pit-viper/components` | |
+
+**Tables & Charts (Vue only):** Always use PvDataTable for tabular data. Use PvChart for standalone charts. Use PvDataTableWithChart when you need both together. Never use D3, Chart.js, ApexCharts, or custom `<table>` markup.
+
+**Tables (HTML/Prototype):** Use `.pv-table` CSS classes for static tables. Charting is NOT available in HTML mode — charts require Vue components.
+
+Always verify with `/llm/component/{name}` before using — props and APIs may have changed.
+
+## Rules Summary
+
+1. **Pit Viper first** — Always use Pit Viper components and classes
+2. **Search before assuming** — Use `/llm/search` to verify components exist
+3. **Match the audience** — Engineer gets Vue, prototype gets HTML, design review gets rationale
+4. **No custom CSS** — Only pv-* utility classes
+5. **No guessing** — Verify icons, classes, and component names exist
+
+## Resources
+
+| Resource | URL |
+|----------|-----|
+| Storybook (setup, component docs) | https://pit-viper-storybook.netlify.app/?path=/docs/introduction--documentation |
+| CSS Documentation | https://pitviper.turquoise.health/ |
+| Icons | https://pitviper.turquoise.health/visual-style/icons/ |
+| LLM API | https://pitviper.turquoise.health/llm |
+| Vue + Vite Sandbox | https://stackblitz.com/edit/pv-sandbox-vue-vite |
+| Vue Browser Sandbox | https://stackblitz.com/edit/pv-sandbox-vue-browser |

package/claude-plugin/skills/pit-viper/references/design-language.md

@@ -0,0 +1,80 @@
+# Design Language Reference
+
+Use this reference in Design Review Mode — when validating designs or explaining layout rationale without generating code.
+
+For component selection, use `/llm/search` first. This reference covers layout patterns and token validation.
+
+## Layout Patterns
+
+| Pattern | Structure | Best For |
+|---------|-----------|----------|
+| **Dashboard** | `PvSidePanel` (nav) + main content area | Multi-page apps with persistent navigation |
+| **Form** | `PvCard` with header/body/footer slots | Data entry, settings, editing |
+| **List-detail** | Table on left, `PvDrawer` or `PvModal` for details | Browse-and-edit workflows |
+| **Settings** | `PvTabs` with `PvAccordion` sections | Complex configuration with many options |
+| **Marketing** | Full-width sections, Consumer theme | Public-facing, consumer-oriented pages |
+
+## Token Validation
+
+When reviewing designs for Pit Viper compliance:
+
+### Colors
+
+Fetch current palette:
+```
+WebFetch https://pitviper.turquoise.health/llm/tokens?category=color
+```
+
+Key values:
+- Primary Brand: `#176F6F` (interactive elements, links)
+- Secondary Brand: `#02363D` (body text, dark surfaces)
+- Error: `#DA1E28`
+- Warning: `#896000`
+- Success: `#0E6027`
+
+### Spacing
+
+4px base grid. Valid values: 4, 8, 12, 16, 20, 24, 32, 64, 128 pixels.
+
+| Value | Use Case |
+|-------|----------|
+| 4-8px | Tight spacing, icons, inline elements |
+| 12-16px | Component padding, section spacing |
+| 24-32px | Major sections, page-level spacing |
+| 64-128px | Hero sections, large separators |
+
+### Typography
+
+| Style | Platform Size | Consumer Size | Weight |
+|-------|---------------|---------------|--------|
+| Heading 1 | 20px | 62px | 600 |
+| Heading 2 | 16px | 16px | 600 |
+| Body MD | 12px | 16px | 400 |
+| Body SM | 11px | 11px | 400 |
+
+### Border Radius
+
+- Small: 2px
+- Default: 5px
+- Large: 12px
+
+### Shadows
+
+Four elevation levels exist (button, popover, elevated hover, modal). Don't invent custom shadows.
+
+## Review Checklist
+
+1. **Does the component exist?** Search `/llm/search?q={name}` first.
+2. **Are tokens valid?** Check colors, spacing, typography against values above.
+3. **Is the pattern established?** Match to layout patterns table.
+4. **Is the 4px grid respected?** Flag spacing values that aren't multiples of 4.
+
+## When to Escalate
+
+Flag for design system review if the design requires:
+- Colors not in the palette
+- Spacing values not on the 4px grid
+- Components that don't exist in Pit Viper
+- Patterns that diverge significantly from established layouts
+
+Don't silently work around these — they indicate a design system gap.

package/claude-plugin/skills/pit-viper/references/design-rules.md

@@ -0,0 +1,254 @@
+# Design Rules
+
+Prescriptive rules for consistent visual output. These are mandatory — follow them exactly.
+
+## Spacing
+
+Use pv-* spacing classes. Never use raw `padding`, `margin`, `gap`, or pixel values.
+
+### Vertical Spacing (pv-stack-*)
+
+| Context | Class | When |
+|---------|-------|------|
+| Page sections | `pv-stack-32` | Between major content blocks |
+| Within sections | `pv-stack-24` | Between card/groups inside a section |
+| Related elements | `pv-stack-16` | Between form fields, list items |
+| Tight coupling | `pv-stack-8` | Label to input, heading to description |
+| Minimal | `pv-stack-4` | Icon to text, inline elements |
+
+### Padding (pv-inset-*)
+
+| Context | Class |
+|---------|-------|
+| Page wrapper | `pv-inset-square-24` |
+| Card body | `pv-inset-square-16` |
+| Compact card | `pv-inset-square-12` |
+| Button-like elements | `pv-inset-squish-8` or `pv-inset-squish-12` |
+| Dense lists | `pv-inset-square-8` |
+
+### Flow (pv-flow-*)
+
+Use `pv-flow-*` for horizontal/flex gaps:
+
+| Context | Class |
+|---------|-------|
+| Button groups | `pv-flow-8` |
+| Card grids | `pv-flow-16` or `pv-flow-24` |
+| Nav items | `pv-flow-4` or `pv-flow-8` |
+
+## Typography
+
+Use pv-* typography classes. Never use raw `font-size`, `font-weight`, or `line-height`.
+
+### Heading Hierarchy
+
+| Level | Class | Use |
+|-------|-------|-----|
+| Page title | `pv-heading-1` | One per page, top of content |
+| Section title | `pv-heading-2` | Major sections within page |
+| Card/panel title | `pv-heading-3` | Card headers, modal titles |
+| Subsection | `pv-heading-4` | Nested sections, accordion headers |
+| Small heading | `pv-heading-5` | Rarely used |
+
+### Body Text
+
+| Context | Class |
+|---------|-------|
+| Default body | `pv-text-body-md` |
+| Secondary info | `pv-text-body-sm` |
+| Fine print | `pv-text-body-xs` |
+| Large intro | `pv-text-body-lg` (Consumer theme only) |
+
+### Labels & Titles
+
+| Context | Class |
+|---------|-------|
+| Form label | `pv-text-title-sm` |
+| Card header text | `pv-text-title-md` |
+| Emphasized inline | `pv-text-title-sm` |
+
+### Text Modifiers
+
+| Purpose | Class |
+|---------|-------|
+| De-emphasize | `pv-text-subdued` |
+| On dark backgrounds | `pv-text-inverse` |
+| Brand color | `pv-text-brand` |
+| Error message | `pv-text-error` |
+| Success message | `pv-text-success` |
+| Warning message | `pv-text-warning` |
+
+## Colors
+
+Use semantic classes. Never hardcode hex values.
+
+### Backgrounds (pv-surface-*)
+
+| Purpose | Class |
+|---------|-------|
+| Default page | `pv-surface` |
+| Elevated card | `pv-surface-raised` |
+| Subtle highlight | `pv-surface-accent` |
+| Brand header | `pv-surface-brand` |
+| Error state | `pv-surface-error` |
+| Success state | `pv-surface-success` |
+| Warning state | `pv-surface-warning` |
+| Code/mono areas | `pv-surface-gray` or background token |
+
+### Status Colors
+
+| State | Text Class | Background Class |
+|-------|------------|------------------|
+| Success | `pv-text-success` | `pv-surface-success` |
+| Error | `pv-text-error` | `pv-surface-error` |
+| Warning | `pv-text-warning` | `pv-surface-warning` |
+| Info | `pv-text-brand` | `pv-surface-accent` |
+
+## Layout
+
+### Page Structure
+
+Every page should follow this structure:
+
+```html
+<body class="pv-surface">
+  <header class="pv-surface-brand pv-inset-square-24">
+    <!-- Header content -->
+  </header>
+  
+  <main class="pv-container-lg pv-inset-square-24">
+    <!-- Page content -->
+  </main>
+</body>
+```
+
+### Container Widths
+
+| Size | Class | Use |
+|------|-------|-----|
+| Small | `pv-container-sm` | Forms, narrow content |
+| Medium | `pv-container-md` | Articles, single-column |
+| Large | `pv-container-lg` | Dashboards, data tables |
+
+Always center containers: add `style="margin: 0 auto;"` or wrap in flex parent.
+
+### Flex Layouts
+
+| Pattern | Classes |
+|---------|---------|
+| Horizontal row | `pv-flex` |
+| Vertical stack | `pv-flex pv-flex-vertical` |
+| Space between | `pv-flex pv-space-between` |
+| Centered | `pv-flex pv-center` |
+| Responsive wrap | `pv-flex pv-flex-responsive` |
+
+Set flex gap with `pv-flow-*` or `--flex-gap` custom property.
+
+## Cards
+
+Always use proper card structure:
+
+```html
+<div class="pv-card">
+  <div class="pv-card-header">
+    <h3 class="pv-heading-3">Title</h3>
+  </div>
+  <div class="pv-card-body pv-flow-16">
+    <!-- Content -->
+  </div>
+  <div class="pv-card-footer pv-flex pv-flow-8" style="justify-content: flex-end;">
+    <!-- Actions -->
+  </div>
+</div>
+```
+
+Don't use:
+- Raw `<div>` with padding for card-like containers
+- Inline styles for card padding
+- Custom border/shadow styles
+
+## Forms
+
+### Field Structure
+
+```html
+<div>
+  <label class="pv-text-title-sm pv-stack-4">Label</label>
+  <pv-input placeholder="..."></pv-input>
+</div>
+```
+
+- Always use `pv-stack-4` between label and input
+- Use `pv-flow-16` or `pv-stack-16` between fields
+- Group related fields in `<fieldset>` with `pv-stack-24` between groups
+
+### Actions
+
+```html
+<div class="pv-flex pv-flow-8" style="--flex-justify: flex-end;">
+  <pv-button variant="ghost" label="Cancel"></pv-button>
+  <pv-button label="Submit"></pv-button>
+</div>
+```
+
+- Primary action on right
+- Secondary/cancel on left
+- Use `pv-flow-8` between buttons
+
+## Tables
+
+For data tables, always use `PvDataTable` (Vue) or `pv-table` classes (HTML).
+
+HTML table structure:
+```html
+<table class="pv-table">
+  <thead>
+    <tr>
+      <th>Header</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Cell</td>
+    </tr>
+  </tbody>
+</table>
+```
+
+Never add custom styling to tables.
+
+## Borders & Radius
+
+| Purpose | Class |
+|---------|-------|
+| Subtle divider | `pv-border-bottom` |
+| Card-like border | `pv-border` |
+| Rounded corners | `pv-radius` (default 5px) |
+| Small radius | `pv-radius-sm` (2px) |
+| Large radius | `pv-radius-lg` (12px) |
+
+## Allowed Inline Styles
+
+Only these inline styles are acceptable (when no class exists):
+
+- `style="max-width: Npx;"` — constrain element width
+- `style="height: Npx;"` — set explicit height (tables, charts)
+- `style="flex: 1;"` — flex grow in layouts
+- `style="margin: 0 auto;"` — center container
+- `style="justify-content: flex-end;"` — align flex children
+- `style="--flex-gap: Nrem;"` — set flex gap
+
+Everything else must use pv-* classes. If you need a style that doesn't exist, flag it as a design system gap.
+
+## Checklist
+
+Before finalizing output, verify:
+
+1. [ ] No raw `padding`, `margin`, `font-size`, `color` in styles
+2. [ ] No hardcoded hex colors
+3. [ ] No `<style>` blocks
+4. [ ] Headings follow hierarchy (h1 > h2 > h3)
+5. [ ] Cards use `pv-card` + `pv-card-header` + `pv-card-body`
+6. [ ] Page wrapped in `pv-container-*` with `pv-inset-square-24`
+7. [ ] Spacing uses `pv-stack-*` or `pv-flow-*`
+8. [ ] Status colors use semantic classes, not hardcoded values