@telemetryos/cli 1.9.0 → 1.11.0

package/templates/vite-react-typescript/_claude/skills/tos-render-design/SKILL.md

@@ -1,33 +1,63 @@
 ---
 name: tos-render-design
-description: Design patterns for TelemetryOS Render views. Use when building or reviewing Render view layouts, handling responsive scaling, or ensuring digital signage best practices.
+description: Design patterns for TelemetryOS Render views. Use when building display-only digital signage OR interactive kiosks. Covers responsive scaling, UI patterns, and interaction handling for both models.
 ---
 
 # Render View Design
 
-TelemetryOS Render views display on digital signage—TVs, video walls, and displays viewed from a distance with no user interaction. This fundamentally shapes how to design them.
+TelemetryOS Render views support both **digital signage** (display-only) and **interactive kiosks** (touch-enabled). Understanding which pattern you're building determines how you handle user interaction and state management.
 
 > **Note:** The init project already provides base styles in `index.css` (viewport scaling, box-sizing) and `Render.css` (`.render` class with padding, overflow, flexbox). Build on these—don't override them.
 
-## Digital Signage Constraints
+---
+
+## Interaction Models
+
+TelemetryOS render views support two interaction models. Both use `@telemetryos/sdk` with the same architecture—the difference is whether the render view includes onClick handlers.
+
+### Digital Signage (Display-Only)
+
+**Use for:** Information displays, dashboards, menu boards, announcements
+
+- Content updates automatically via store subscriptions
+- No user interaction (no mouse, keyboard, touch input)
+- No onClick handlers in render view
+- Viewed from a distance
+- Updates driven by timers, external data, or Settings changes
+
+### Interactive Kiosk (Touch-Enabled)
+
+**Use for:** Wayfinding, directories, check-in systems, search interfaces
+
+- Users can touch/click elements on screen
+- onClick handlers for buttons, navigation, forms
+- Idle timeout returns to home screen after inactivity
+- Touch feedback with :active states (not :hover)
+- Manages interaction state (current screen, navigation history)
+
+---
+
+## Digital Signage Pattern (Display-Only)
+
+For apps where users only **view** content from a distance.
 
 ### No User Interaction
 
-Unless building for kiosk/touchscreen scenarios, assume **no mouse, keyboard, or touch input**:
+Assume **no mouse, keyboard, or touch input**:
 
 ```css
-/* WRONG - No one will hover */
+/* WRONG - No one will hover on digital signage */
 .button:hover {
   background: blue;
 }
 
-/* WRONG - No one will focus */
+/* WRONG - No one will focus elements */
 .input:focus {
   outline: 2px solid blue;
 }
 ```
 
-Avoid `:hover`, `:focus`, `:active`, and similar interaction pseudo-classes.
+Avoid `:hover`, `:focus`, `:active`, and similar interaction pseudo-classes for display-only apps.
 
 ### No Scrolling
 
@@ -55,8 +85,150 @@ Content **must fit the viewport**. There's no user to scroll:
 
 If content might overflow, truncate it or conditionally hide elements—never show a scrollbar.
 
+---
+
+## Interactive Kiosk Pattern (Touch-Enabled)
+
+For apps where users **interact** with the screen via touch or click.
+
+### onClick Handlers
+
+Add click handlers to interactive elements:
+
+```typescript
+function Render() {
+  const [screen, setScreen] = useState('home')
+
+  return (
+    <div className="render">
+      {screen === 'home' && (
+        <button
+          className="kiosk-button"
+          onClick={() => setScreen('search')}
+        >
+          Search Directory
+        </button>
+      )}
+      {screen === 'search' && (
+        <SearchScreen onBack={() => setScreen('home')} />
+      )}
+    </div>
+  )
+}
+```
+
+### Touch Feedback (:active states)
+
+Use `:active` pseudo-class for touch feedback (NOT `:hover`):
+
+```css
+.kiosk-button {
+  padding: 2rem 4rem;
+  font-size: 3rem;
+  background: blue;
+  color: white;
+  border: none;
+  border-radius: 1rem;
+  transition: transform 0.1s, background 0.1s;
+}
+
+/* Touch feedback - user sees visual response when tapping */
+.kiosk-button:active {
+  transform: scale(0.95);
+  background: darkblue;
+}
+```
+
+**Why :active instead of :hover?**
+- Touch devices don't have hover
+- :active triggers on touch/click
+- Provides immediate visual feedback
+
+### Idle Timeout Pattern
+
+Return to home screen after inactivity:
+
+```typescript
+function Render() {
+  const [screen, setScreen] = useState('home')
+  const [lastInteraction, setLastInteraction] = useState(Date.now())
+
+  // Return to home after 30 seconds of inactivity
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      const elapsed = Date.now() - lastInteraction
+      if (elapsed > 30000 && screen !== 'home') {
+        setScreen('home')
+      }
+    }, 30000)
+
+    return () => clearTimeout(timeout)
+  }, [lastInteraction, screen])
+
+  const handleInteraction = (newScreen: string) => {
+    setScreen(newScreen)
+    setLastInteraction(Date.now())
+  }
+
+  return (
+    <div className="render">
+      {screen === 'home' && (
+        <button onClick={() => handleInteraction('search')}>
+          Search
+        </button>
+      )}
+    </div>
+  )
+}
+```
+
+### Touch Target Sizing
+
+Make touch targets large enough to tap accurately:
+
+```css
+/* Minimum sizes for touch targets */
+.kiosk-button {
+  min-width: 15rem;  /* Large enough to tap */
+  min-height: 8rem;
+  padding: 2rem 4rem;
+  font-size: 3rem;   /* Large, readable text */
+}
+```
+
+**Guidelines:**
+- Minimum 8rem height for buttons
+- 2rem padding minimum
+- 3rem font size minimum for buttons
+- Gap of at least 1rem between interactive elements
+
+### Store State for Navigation
+
+Use device store to persist state across composition changes:
+
+```typescript
+// hooks/store.ts
+import { createUseDeviceStoreState } from '@telemetryos/sdk/react'
+
+export const useKioskScreenState = createUseDeviceStoreState<string>(
+  'kiosk-screen',
+  'home'
+)
+
+// Render.tsx
+const [_isLoading, screen, setScreen] = useKioskScreenState()
+```
+
+**Why device store?**
+- Persists state on the device (survives composition changes)
+- Doesn't sync to other devices (screen state is device-local)
+
+---
+
 ## UI Scale Hooks
 
+**Applies to both digital signage and interactive kiosks.**
+
 Displays range from tablets to 8K video walls. Standard CSS pixels create inconsistent sizing. The SDK provides hooks that redefine `rem` as viewport-relative:
 
 ### useUiScaleToSetRem(uiScale)
@@ -101,8 +273,12 @@ export function Render() {
 }
 ```
 
+---
+
 ## Best Practices
 
+**Applies to both digital signage and interactive kiosks.**
+
 ### Use rem for Everything
 
 All sizing should use `rem` to scale with the UI scale setting:
@@ -200,10 +376,14 @@ function Dashboard() {
 }
 ```
 
-## Complete Example
+---
+
+## Complete Examples
+
+### Digital Signage Example (Display-Only)
 
 ```typescript
-// Render.tsx - Building on the init project's .render class
+// Render.tsx - Display-only dashboard
 import { useUiScaleToSetRem, useUiAspectRatio } from '@telemetryos/sdk/react'
 import { useUiScaleStoreState } from '../hooks/store'
 import './Render.css'
@@ -241,7 +421,7 @@ export function Render() {
 ```
 
 ```css
-/* Render.css - Add to existing styles, don't override .render base */
+/* Render.css - Display-only styles */
 .render__header {
   flex-shrink: 0;
   margin-bottom: 2rem;
@@ -278,6 +458,112 @@ export function Render() {
 }
 ```
 
+### Interactive Kiosk Example (Touch-Enabled)
+
+```typescript
+// Render.tsx - Interactive kiosk with navigation
+import { useState, useEffect } from 'react'
+import { useUiScaleToSetRem } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+import './Render.css'
+
+export function Render() {
+  const [isLoading, uiScale] = useUiScaleStoreState()
+  const [screen, setScreen] = useState('home')
+  const [lastInteraction, setLastInteraction] = useState(Date.now())
+
+  useUiScaleToSetRem(uiScale)
+
+  // Idle timeout - return to home after 30 seconds
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      const elapsed = Date.now() - lastInteraction
+      if (elapsed > 30000 && screen !== 'home') {
+        setScreen('home')
+      }
+    }, 30000)
+
+    return () => clearTimeout(timeout)
+  }, [lastInteraction, screen])
+
+  const handleInteraction = (newScreen: string) => {
+    setScreen(newScreen)
+    setLastInteraction(Date.now())
+  }
+
+  if (isLoading) return null
+
+  return (
+    <div className="render">
+      {screen === 'home' && (
+        <div className="kiosk-home">
+          <h1 className="kiosk-home__title">Welcome</h1>
+          <button
+            className="kiosk-button"
+            onClick={() => handleInteraction('search')}
+          >
+            Search Directory
+          </button>
+          <button
+            className="kiosk-button"
+            onClick={() => handleInteraction('map')}
+          >
+            View Map
+          </button>
+        </div>
+      )}
+
+      {screen === 'search' && (
+        <SearchScreen onBack={() => handleInteraction('home')} />
+      )}
+
+      {screen === 'map' && (
+        <MapScreen onBack={() => handleInteraction('home')} />
+      )}
+    </div>
+  )
+}
+```
+
+```css
+/* Render.css - Interactive kiosk styles */
+.kiosk-home {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 3rem;
+  height: 100%;
+}
+
+.kiosk-home__title {
+  font-size: 6rem;
+  margin: 0;
+}
+
+/* Touch-friendly button with :active feedback */
+.kiosk-button {
+  min-width: 20rem;
+  min-height: 8rem;
+  padding: 2rem 4rem;
+  font-size: 3rem;
+  background: #0066cc;
+  color: white;
+  border: none;
+  border-radius: 1rem;
+  cursor: pointer;
+  transition: transform 0.1s, background 0.1s;
+}
+
+/* Touch feedback - scales down when tapped */
+.kiosk-button:active {
+  transform: scale(0.95);
+  background: #0052a3;
+}
+```
+
+---
+
 ## Store Hook for UI Scale
 
 Create a store hook to let admins adjust the UI scale:
@@ -318,15 +604,21 @@ export function Settings() {
 }
 ```
 
+---
+
 ## Common Mistakes
 
 | Mistake | Problem | Fix |
 |---------|---------|-----|
 | Using `px` units | Won't scale across resolutions | Use `rem` everywhere |
-| Adding `:hover` styles | No mouse on digital signage | Remove interaction states |
+| Adding `:hover` styles on digital signage | No mouse on display-only apps | Remove interaction states for display-only |
+| Using `:hover` on interactive kiosks | No hover on touch devices | Use `:active` instead for touch feedback |
 | Using `overflow: scroll` | No user to scroll | Use `overflow: hidden`, truncate content |
 | Fixed heights in `px` | Breaks on different aspect ratios | Use `vh`, `%`, or flex |
-| Forgetting `useUiScaleToSetRem()` | `rem` units won't scale properly | Call it once in Render view with the uiScale from `useUiScaleStoreState()` |
+| Forgetting `useUiScaleToSetRem()` | `rem` units won't scale properly | Call it once in Render view with uiScale |
 | Text below 2rem | Unreadable from viewing distance | Minimum 2rem for body text |
+| Small touch targets on kiosks | Hard to tap accurately | Minimum 8rem height, 2rem padding, 3rem font |
+| No idle timeout on kiosks | Kiosk stays on user's screen | Add useEffect timeout logic |
+| No touch feedback on kiosks | User unsure if tap registered | Add :active state animations |
 | Removing `.render` padding | Content cut off by bezels | Keep the ~3rem padding from init project |
 | Overriding `index.css` base styles | Breaks viewport scaling | Add new styles, don't modify base setup |