@telemetryos/cli 1.9.0 → 1.11.0

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

@@ -0,0 +1,384 @@
+---
+name: tos-render-kiosk-design
+description: Design patterns for interactive TelemetryOS kiosks. Use AFTER reading tos-render-ui-design. Covers touch interaction, onClick handlers, idle timeout, touch targets, and navigation state.
+---
+
+# Interactive Kiosk Design (Touch-Enabled)
+
+For TelemetryOS render views where users **interact with the screen** via touch or click.
+
+> **Prerequisites:** Read `tos-render-ui-design` first for foundation concepts (rem scaling, safe zones, text sizing, responsive layouts).
+
+---
+
+## What is an Interactive Kiosk?
+
+**Use for:** Wayfinding, directories, check-in systems, search interfaces
+
+Interactive kiosks allow user interaction with these characteristics:
+
+- 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)
+
+**Examples:**
+- Wayfinding kiosks in shopping malls
+- Hotel check-in systems
+- Building directory search
+- Product catalog browsers
+- Information lookup stations
+
+---
+
+## Interaction Patterns
+
+### onClick Handlers
+
+Add click handlers to interactive elements:
+
+```typescript
+import { useState } from 'react'
+
+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>
+  )
+}
+```
+
+**Key points:**
+- Use standard React `onClick` handlers
+- Manage screen/navigation state with `useState` or device store
+- Provide clear navigation (back buttons, home button)
+- Keep navigation shallow (avoid deep nested screens)
+
+### 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
+- Shows user their tap was registered
+
+**Feedback strategies:**
+- Scale down slightly (0.95-0.98)
+- Darken background color
+- Change border/shadow
+- Keep transition fast (0.1s)
+
+### 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 */
+}
+
+/* Gap between interactive elements */
+.button-group {
+  display: flex;
+  gap: 1rem; /* Minimum 1rem spacing */
+}
+```
+
+**Touch target guidelines:**
+
+| Element | Min Height | Min Padding | Font Size | Gap |
+|---------|-----------|-------------|-----------|-----|
+| Button | 8rem | 2rem | 3rem | 1rem |
+| Nav item | 8rem | 2rem | 3rem | 1rem |
+| Input field | 8rem | 2rem | 3rem | 1rem |
+
+**Why large targets?**
+- Users tap with fingers, not precise mouse cursor
+- Prevents accidental taps on adjacent elements
+- Reduces user frustration
+- Improves accessibility
+
+---
+
+## State Management
+
+### Idle Timeout Pattern
+
+Return to home screen after inactivity to prevent kiosks from staying on user's screen:
+
+```typescript
+import { useState, useEffect } from 'react'
+
+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>
+  )
+}
+```
+
+**Key points:**
+- Track last interaction timestamp
+- Clear timeout on cleanup
+- Configurable timeout duration (typically 15-60 seconds)
+- Update timestamp on any interaction
+- Only reset if not already on home screen
+
+### Device Store 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
+import { useKioskScreenState } from '../hooks/store'
+
+export function Render() {
+  const [_isLoading, screen, setScreen] = useKioskScreenState()
+
+  return (
+    <div className="render">
+      {screen === 'home' && <HomeScreen />}
+      {screen === 'search' && <SearchScreen />}
+    </div>
+  )
+}
+```
+
+**Why device store for kiosk navigation?**
+- Persists state on the device (survives composition changes)
+- Doesn't sync to other devices (screen state is device-local)
+- Maintains kiosk state during playlist rotation
+- Each physical device has independent navigation
+
+**Don't use instance store** - That syncs across all devices. For kiosk navigation, use device store so each kiosk has independent state.
+
+---
+
+## Complete Example
+
+### Interactive Kiosk with Navigation
+
+```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;
+}
+```
+
+---
+
+## Touch Interaction Guidelines
+
+### Visual Feedback Requirements
+
+Every interactive element should provide visual feedback:
+
+✅ Use `:active` state (not `:hover`)
+✅ Visual change must be immediate (< 100ms)
+✅ Change should be obvious (scale, color, shadow)
+✅ Feedback on tap down, not just tap up
+
+### Touch Target Checklist
+
+- [ ] All buttons are at least 8rem height
+- [ ] Padding is at least 2rem
+- [ ] Font size is at least 3rem
+- [ ] Gap between buttons is at least 1rem
+- [ ] Touch targets don't overlap
+- [ ] `:active` states provide visual feedback
+
+---
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Using `:hover` on interactive kiosks | No hover on touch devices | Use `:active` instead for touch feedback |
+| 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 |
+| Using instance store for navigation | State syncs to other devices | Use device store for local navigation |
+
+---
+
+## Testing Your Kiosk
+
+✅ **Test on touch devices** - Not just mouse, verify touch works
+✅ **Verify idle timeout** - Confirm it returns to home after inactivity
+✅ **Check touch targets** - Ensure all buttons are large enough
+✅ **Ensure :active feedback** - Visual response should be obvious
+✅ **Test navigation flow** - Complete user journeys should work
+✅ **Verify state persistence** - State should survive composition rotation
+
+---
+
+## See Also
+
+- `tos-render-ui-design` - Foundation concepts for all render views (UI scaling, rem usage, responsive layouts)
+- `tos-render-signage-design` - For display-only patterns without interaction