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

package/claude-plugin/skills/pit-viper/references/layout-patterns.md

@@ -0,0 +1,359 @@
+# Layout Patterns
+
+Use this reference when building page-level layouts in any output mode.
+
+## Dashboard Pattern
+
+Three-column layout with navigation sidebar, main content, and optional right panel.
+
+### Vue Example
+```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 activeNav = ref('dashboard')
+
+const navItems = [
+  { id: 'dashboard', label: 'Dashboard', icon: 'home' },
+  { id: 'users', label: 'Users', icon: 'user' },
+  { id: 'settings', label: 'Settings', icon: 'gear' },
+]
+
+const colDefs = [
+  { field: 'name', headerName: 'Name', flex: 1 },
+  { field: 'email', headerName: 'Email', flex: 1 },
+  { field: 'role', headerName: 'Role', width: 120 },
+]
+
+const rowData = [
+  { name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
+  { name: 'Bob Smith', email: 'bob@example.com', role: 'Editor' },
+]
+</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;" class="pv-flow-4">
+            <li
+              v-for="item in navItems"
+              :key="item.id"
+              class="pv-flex pv-inset-squish-8 pv-radius"
+              :class="{ 'pv-surface-highlight': activeNav === item.id }"
+              style="cursor: pointer; --flex-gap: 0.75rem;"
+              @click="activeNav = item.id"
+            >
+              <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="rowData" :colDefs="colDefs" style="height: 400px;" />
+        </div>
+      </template>
+    </PvSidePanel>
+  </div>
+</template>
+```
+
+## Form Pattern
+
+Card-based form with header, body (inputs), and footer (actions).
+
+### Vue Example
+```vue
+<script setup>
+import { ref } from 'vue'
+import { PvButton, PvInput, PvSelectButton, PvCard } from '@turquoisehealth/pit-viper/components'
+
+const formData = ref({
+  name: '',
+  email: '',
+  role: null,
+})
+
+const roleOptions = [
+  { label: 'Admin', value: 'admin' },
+  { label: 'Editor', value: 'editor' },
+  { label: 'Viewer', value: 'viewer' },
+]
+
+const handleSubmit = () => {
+  console.log('Submitting:', formData.value)
+}
+</script>
+
+<template>
+  <PvCard style="max-width: 500px;">
+    <template #header>
+      <h2 class="pv-heading-2">Create User</h2>
+    </template>
+
+    <form @submit.prevent="handleSubmit" class="pv-flow-16">
+      <div>
+        <label class="pv-text-title-sm pv-stack-4">Name</label>
+        <PvInput v-model="formData.name" placeholder="Full name" />
+      </div>
+
+      <div>
+        <label class="pv-text-title-sm pv-stack-4">Email</label>
+        <PvInput v-model="formData.email" type="email" placeholder="email@example.com" />
+      </div>
+
+      <div>
+        <label class="pv-text-title-sm pv-stack-4">Role</label>
+        <PvSelectButton v-model="formData.role" :options="roleOptions" placeholder="Select role" />
+      </div>
+    </form>
+
+    <template #footer>
+      <div class="pv-flex" style="--flex-justify: flex-end; --flex-gap: 0.5rem;">
+        <PvButton variant="ghost">Cancel</PvButton>
+        <PvButton @click="handleSubmit">Create User</PvButton>
+      </div>
+    </template>
+  </PvCard>
+</template>
+```
+
+## Settings Pattern
+
+Tabbed interface with accordion sections for complex settings.
+
+### Vue Example
+```vue
+<script setup>
+import { ref } from 'vue'
+import { PvTabs, PvAccordion, PvInput, PvSwitch, PvButton } from '@turquoisehealth/pit-viper/components'
+
+const activeTab = ref('profile')
+const profileExpanded = ref(true)
+const notificationsExpanded = ref(false)
+
+const settings = ref({
+  displayName: 'Alice Johnson',
+  email: 'alice@example.com',
+  emailNotifications: true,
+  slackNotifications: false,
+})
+</script>
+
+<template>
+  <div class="pv-inset-square-24">
+    <h1 class="pv-heading-1 pv-stack-24">Settings</h1>
+
+    <PvTabs
+      v-model="activeTab"
+      :tabs="[
+        { label: 'Profile', value: 'profile' },
+        { label: 'Notifications', value: 'notifications' },
+        { label: 'Security', value: 'security' },
+      ]"
+      class="pv-stack-24"
+    />
+
+    <div v-if="activeTab === 'profile'" class="pv-flow-16">
+      <PvAccordion v-model="profileExpanded" header="Personal Information">
+        <div class="pv-flow-16 pv-inset-square-16">
+          <div>
+            <label class="pv-text-title-sm pv-stack-4">Display Name</label>
+            <PvInput v-model="settings.displayName" />
+          </div>
+          <div>
+            <label class="pv-text-title-sm pv-stack-4">Email</label>
+            <PvInput v-model="settings.email" type="email" />
+          </div>
+        </div>
+      </PvAccordion>
+    </div>
+
+    <div v-if="activeTab === 'notifications'" class="pv-flow-16">
+      <PvAccordion v-model="notificationsExpanded" header="Notification Preferences">
+        <div class="pv-flow-16 pv-inset-square-16">
+          <div class="pv-flex pv-space-between">
+            <span class="pv-text-body-md">Email notifications</span>
+            <PvSwitch v-model="settings.emailNotifications" />
+          </div>
+          <div class="pv-flex pv-space-between">
+            <span class="pv-text-body-md">Slack notifications</span>
+            <PvSwitch v-model="settings.slackNotifications" />
+          </div>
+        </div>
+      </PvAccordion>
+    </div>
+
+    <div class="pv-stack-24">
+      <PvButton>Save Changes</PvButton>
+    </div>
+  </div>
+</template>
+```
+
+## Marketing / Landing Pattern
+
+Consumer theme with large typography, full-width sections, and prominent CTAs.
+
+### HTML Example (Consumer Theme)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Product Landing</title>
+  <link rel="stylesheet" href="https://pitviper.turquoise.health/assets/css/pit-viper-consumer.css">
+  <script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-components.iife.js"></script>
+</head>
+<body>
+  <!-- Hero Section -->
+  <section class="pv-surface-brand-accent pv-inset-square-64">
+    <div class="pv-container-md" style="margin: 0 auto; text-align: center;">
+      <h1 class="pv-heading-1 pv-stack-24">Transform Your Healthcare Data</h1>
+      <p class="pv-text-body-xl pv-text-subdued pv-stack-32" style="max-width: 600px; margin: 0 auto;">
+        Unlock insights from your healthcare data with our powerful analytics platform.
+      </p>
+      <pv-button size="lg">Get Started</pv-button>
+    </div>
+  </section>
+
+  <!-- Features Section -->
+  <section class="pv-inset-square-64">
+    <div class="pv-container-lg" style="margin: 0 auto;">
+      <h2 class="pv-heading-2 pv-stack-32" style="text-align: center;">Features</h2>
+      <div class="pv-flex pv-flex-responsive" style="--flex-gap: 2rem;">
+        <pv-card style="flex: 1;">
+          <div slot="default" class="pv-inset-square-24">
+            <h3 class="pv-heading-3 pv-stack-8">Real-time Analytics</h3>
+            <p class="pv-text-body-md pv-text-subdued">
+              Monitor your data in real-time with customizable dashboards.
+            </p>
+          </div>
+        </pv-card>
+        <pv-card style="flex: 1;">
+          <div slot="default" class="pv-inset-square-24">
+            <h3 class="pv-heading-3 pv-stack-8">Secure & Compliant</h3>
+            <p class="pv-text-body-md pv-text-subdued">
+              HIPAA-compliant infrastructure with enterprise-grade security.
+            </p>
+          </div>
+        </pv-card>
+        <pv-card style="flex: 1;">
+          <div slot="default" class="pv-inset-square-24">
+            <h3 class="pv-heading-3 pv-stack-8">Easy Integration</h3>
+            <p class="pv-text-body-md pv-text-subdued">
+              Connect to your existing systems with our REST API.
+            </p>
+          </div>
+        </pv-card>
+      </div>
+    </div>
+  </section>
+
+  <!-- CTA Section -->
+  <section class="pv-surface-brand pv-inset-square-64">
+    <div class="pv-container-md" style="margin: 0 auto; text-align: center;">
+      <h2 class="pv-heading-2 pv-text-inverse pv-stack-16">Ready to get started?</h2>
+      <p class="pv-text-body-lg pv-text-inverse pv-stack-24" style="opacity: 0.8;">
+        Join thousands of healthcare organizations using our platform.
+      </p>
+      <pv-button variant="inverse" size="lg">Contact Sales</pv-button>
+    </div>
+  </section>
+</body>
+</html>
+```
+
+## List-Detail Pattern
+
+Table with a drawer or modal for viewing/editing details.
+
+### Vue Example
+```vue
+<script setup>
+import { ref } from 'vue'
+import { PvButton, PvDrawer, PvInput } from '@turquoisehealth/pit-viper/components'
+import { PvDataTable } from '@turquoisehealth/pit-viper/components/visualizations'
+
+const selectedUser = ref(null)
+const drawerOpen = ref(false)
+
+const users = ref([
+  { id: 1, name: 'Alice Johnson', email: 'alice@example.com', role: 'Admin' },
+  { id: 2, name: 'Bob Smith', email: 'bob@example.com', role: 'Editor' },
+])
+
+const colDefs = [
+  { field: 'name', headerName: 'Name', flex: 1 },
+  { field: 'email', headerName: 'Email', flex: 1 },
+  { field: 'role', headerName: 'Role', width: 120 },
+  {
+    headerName: 'Actions',
+    width: 100,
+    cellRenderer: 'actionCell',
+  },
+]
+
+const openDetail = (user) => {
+  selectedUser.value = { ...user }
+  drawerOpen.value = true
+}
+</script>
+
+<template>
+  <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>
+
+    <PvDataTable
+      :rowData="users"
+      :colDefs="colDefs"
+      @row-clicked="openDetail($event.data)"
+      style="height: 400px;"
+    />
+
+    <PvDrawer v-model="drawerOpen" header="Edit User">
+      <template v-if="selectedUser">
+        <div class="pv-flow-16">
+          <div>
+            <label class="pv-text-title-sm pv-stack-4">Name</label>
+            <PvInput v-model="selectedUser.name" />
+          </div>
+          <div>
+            <label class="pv-text-title-sm pv-stack-4">Email</label>
+            <PvInput v-model="selectedUser.email" type="email" />
+          </div>
+        </div>
+      </template>
+
+      <template #footer>
+        <div class="pv-flex" style="--flex-justify: flex-end; --flex-gap: 0.5rem;">
+          <PvButton variant="ghost" @click="drawerOpen = false">Cancel</PvButton>
+          <PvButton>Save</PvButton>
+        </div>
+      </template>
+    </PvDrawer>
+  </div>
+</template>
+```

package/claude-plugin/skills/pit-viper/references/patterns-core.md

@@ -0,0 +1,97 @@
+# Core Patterns
+
+Universal patterns for Pit Viper utility classes. These apply to both Vue and HTML output.
+
+## Anti-Pattern: Tailwind Classes
+
+Pit Viper has its own utility system. Never use Tailwind.
+
+```html
+<!-- BAD: Tailwind -->
+<div class="flex gap-4 p-6 bg-gray-100 rounded-lg">
+  <h1 class="text-xl font-semibold mb-4">Title</h1>
+  <p class="text-sm text-gray-600">Description</p>
+</div>
+
+<!-- GOOD: Pit Viper -->
+<div class="pv-flex pv-inset-square-24 pv-surface-accent pv-radius">
+  <h1 class="pv-heading-2 pv-stack-16">Title</h1>
+  <p class="pv-text-body-sm pv-text-subdued">Description</p>
+</div>
+```
+
+| Tailwind | Pit Viper |
+|----------|-----------|
+| `flex` | `pv-flex` |
+| `gap-4` | `--flex-gap: 1rem` or spacing class |
+| `p-6` | `pv-inset-square-24` |
+| `bg-gray-100` | `pv-surface-accent` |
+| `rounded-lg` | `pv-radius` |
+| `text-xl font-semibold` | `pv-heading-2` |
+| `text-sm text-gray-600` | `pv-text-body-sm pv-text-subdued` |
+| `mb-4` | `pv-stack-16` |
+
+## Anti-Pattern: Components Without Spacing
+
+Elements jammed together without breathing room look broken.
+
+```html
+<!-- BAD: No spacing -->
+<div>
+  <h1>Settings</h1>
+  <p>Configure your preferences below.</p>
+  <pv-input placeholder="Name"></pv-input>
+  <pv-input placeholder="Email"></pv-input>
+  <pv-button label="Save"></pv-button>
+</div>
+
+<!-- GOOD: Proper spacing hierarchy -->
+<div class="pv-inset-square-24">
+  <h1 class="pv-heading-1 pv-stack-8">Settings</h1>
+  <p class="pv-text-body-md pv-text-subdued pv-stack-24">Configure your preferences below.</p>
+  <div class="pv-flex-vertical pv-stack-24" style="--flex-gap: 1rem;">
+    <pv-input placeholder="Name"></pv-input>
+    <pv-input placeholder="Email"></pv-input>
+  </div>
+  <pv-button label="Save"></pv-button>
+</div>
+```
+
+## Anti-Pattern: Hardcoded Colors
+
+Never use hex values. Use semantic color classes.
+
+```html
+<!-- BAD: Hardcoded colors -->
+<span style="color: #0E8019;">Success!</span>
+<span style="color: #DA1E28;">Error!</span>
+<div style="background: #F7F8F8;">Content</div>
+
+<!-- GOOD: Semantic classes -->
+<span class="pv-text-success">Success!</span>
+<span class="pv-text-error">Error!</span>
+<div class="pv-surface-accent">Content</div>
+```
+
+## Allowed Inline Styles
+
+These inline styles are acceptable when no pv-* class exists:
+
+| Style | Use Case |
+|-------|----------|
+| `style="max-width: 500px;"` | Constrain element width |
+| `style="width: 298px;"` | Specific width for modals |
+| `style="height: 400px;"` | Table/chart height |
+| `style="--flex-gap: 1rem;"` | Flex gap override |
+| `style="--flex-justify: flex-end;"` | Flex alignment |
+| `style="--flow-size: 16px;"` | Flow spacing override |
+| `style="text-decoration: none;"` | Link reset |
+| `style="cursor: pointer;"` | Clickable non-button elements |
+| `style="padding: 0px;"` | Reset default padding |
+
+**Not allowed:**
+- `style="color: #xxx;"` — use `pv-text-*` classes
+- `style="background: #xxx;"` — use `pv-surface-*` classes
+- `style="font-size: Xpx;"` — use `pv-heading-*` or `pv-text-*` classes
+- `style="margin-bottom: Xpx;"` — use `pv-stack-*` classes
+- `style="display: flex;"` — use `pv-flex` class

package/claude-plugin/skills/pit-viper/references/theme-guide.md

@@ -0,0 +1,149 @@
+# Theme Selection Guide
+
+Use this reference when choosing between Platform and Consumer themes or applying design tokens.
+
+## Theme Comparison
+
+| Aspect | Platform | Consumer |
+|--------|----------|----------|
+| **Use case** | Internal tools, dashboards, admin panels | Marketing sites, public pages, consumer apps |
+| **CSS file** | `pit-viper-v2.css` | `pit-viper-consumer.css` |
+| **Font** | Inter | GT Standard |
+| **Body text** | 12px (compact) | 16px (spacious) |
+| **Heading 1** | 20px | 62px |
+| **Overall density** | Compact, data-dense | Spacious, content-focused |
+| **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
+```
+
+Do NOT use the `-scoped` variants.
+
+## Auto-Detection Keywords
+
+### Platform Theme (Default)
+- "dashboard"
+- "admin"
+- "internal"
+- "tool"
+- "portal"
+- "app"
+- "settings"
+- "management"
+
+### Consumer Theme
+- "marketing"
+- "landing"
+- "public"
+- "consumer"
+- "website"
+- "customer-facing"
+- "external"
+- "hero"
+
+If none of these keywords appear, default to **Platform**.
+
+## Typography Scale
+
+### Platform Theme
+| Class | Size | Weight | Line Height |
+|-------|------|--------|-------------|
+| `.pv-heading-1` | 1.25rem (20px) | 600 | 1.2 |
+| `.pv-heading-2` | 1rem (16px) | 600 | 1.5 |
+| `.pv-heading-3` | 0.875rem (14px) | 600 | 1.43 |
+| `.pv-heading-4` | 0.75rem (12px) | 600 | 1.33 |
+| `.pv-text-body-xl` | 0.875rem (14px) | 400 | 1.14 |
+| `.pv-text-body-lg` | 0.875rem (14px) | 400 | 1.14 |
+| `.pv-text-body-md` | 0.75rem (12px) | 400 | 1.33 |
+| `.pv-text-body-sm` | 0.6875rem (11px) | 400 | 1.45 |
+
+### Consumer Theme
+Heading 1 scales up dramatically (62px). Body text is larger (16px base). Use for marketing pages where readability at a glance matters more than information density.
+
+## Spacing System
+
+4px base grid. Valid values:
+
+| Class | Value | Pixels |
+|-------|-------|--------|
+| `.pv-stack-0` | 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 |
+
+Same values exist for `.pv-inset-square-*` (padding) and `.pv-flow-*` (gap).
+
+## Color Palette
+
+### Brand Colors
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Primary Brand | `#176F6F` | Interactive elements, links, primary buttons |
+| Secondary Brand | `#02363D` | Body text, secondary buttons, dark surfaces |
+| Brand Accent Light | `#A8E6E1` | Inverse buttons, AI button, tertiary |
+| Brand Accent Bg | `#F3FCFB` | Light teal backgrounds |
+
+### Text Colors
+| Class | Usage |
+|-------|-------|
+| `.pv-text-default` | Primary body text |
+| `.pv-text-subdued` | Secondary/helper text |
+| `.pv-text-brand` | Links, brand-colored text |
+| `.pv-text-inverse` | Text on dark surfaces |
+| `.pv-text-critical` | Error messages |
+| `.pv-text-warning` | Warning text |
+| `.pv-text-success` | Success text |
+
+### Surface Colors
+| Class | Usage |
+|-------|-------|
+| `.pv-surface` | Default white background |
+| `.pv-surface-accent` | Subtle alternate backgrounds |
+| `.pv-surface-brand` | Dark brand surfaces |
+| `.pv-surface-highlight` | Selection/highlight backgrounds |
+| `.pv-surface-brand-accent` | Light teal backgrounds |
+| `.pv-surface-critical` | Error backgrounds |
+| `.pv-surface-warning` | Warning backgrounds |
+| `.pv-surface-success` | Success backgrounds |
+
+## Border Radius
+
+| Class | Value | Use Case |
+|-------|-------|----------|
+| `.pv-radius-sm` | 2px | Tight, subtle rounding |
+| `.pv-radius` | 5px | Default, most components |
+| `.pv-radius-lg` | 12px | Cards, modals, prominent elements |
+
+## Layout Classes
+
+| 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-space-between` | `justify-content: space-between` |
+| `.pv-container-sm` | Max-width 768px |
+| `.pv-container-md` | Max-width 972px |
+| `.pv-container-lg` | Max-width 1448px |
+
+Use CSS custom property `--flex-gap` to override gap.
+
+## Responsive Breakpoint
+
+Primary breakpoint: **768px**
+
+- Below 768px: Mobile layout (sidebar collapses, flex stacks)
+- 768px and above: Desktop layout
+
+Use `.pv-flex-responsive` for automatic column-to-row behavior.
+Use `.pv-stack-*-responsive` for half-size spacing on mobile.