@telemetryos/cli 1.9.0 → 1.11.0

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

@@ -0,0 +1,515 @@
+---
+name: tos-render-signage-design
+description: Design patterns for display-only TelemetryOS digital signage. Use AFTER reading tos-render-ui-design. Covers no-interaction constraints, no-scrolling requirements, and auto-rotation patterns.
+---
+
+# Digital Signage Design (Display-Only)
+
+For TelemetryOS render views where content is **viewed from a distance** with **no user interaction**.
+
+> **Prerequisites:** Read `tos-render-ui-design` first for foundation concepts (rem scaling, safe zones, text sizing, responsive layouts).
+
+---
+
+## What is Digital Signage?
+
+**Use for:** Information displays, dashboards, menu boards, announcements
+
+Digital signage is display-only content with these characteristics:
+
+- 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
+
+**Examples:**
+- Restaurant menu boards that show daily specials
+- Airport flight status displays
+- Office lobby dashboards showing company metrics
+- Retail price displays
+- Weather and news displays
+
+---
+
+## Core Constraints
+
+### No User Interaction
+
+Assume **no mouse, keyboard, or touch input**:
+
+```css
+/* WRONG - No one will hover on digital signage */
+.button:hover {
+  background: blue;
+}
+
+/* WRONG - No one will focus elements */
+.input:focus {
+  outline: 2px solid blue;
+}
+```
+
+**Why avoid interaction states?**
+- Display-only apps have no input devices
+- `:hover`, `:focus`, `:active` pseudo-classes will never trigger
+- CSS for these states wastes bytes and creates confusion
+
+Avoid `:hover`, `:focus`, `:active`, and similar interaction pseudo-classes for display-only apps.
+
+### No Scrolling
+
+Content **must fit the viewport**. There's no user to scroll:
+
+```css
+/* WRONG - Creates scrollbar no one can use */
+.container {
+  overflow-y: scroll;
+}
+
+/* WRONG - Content disappears off-screen */
+.content {
+  height: 150vh;
+}
+```
+
+```css
+/* CORRECT - Content contained */
+.container {
+  height: 100vh;
+  overflow: hidden;
+}
+```
+
+**What to do instead:**
+- Use text truncation (ellipsis, line-clamp)
+- Conditionally hide less important elements
+- Paginate content with timer-based rotation
+- Adapt layout for portrait/landscape (see `tos-render-ui-design`)
+
+If content might overflow, truncate it or conditionally hide elements—never show a scrollbar.
+
+> **See "Layout Philosophy: Outside-In Design"** below for the architectural approach that prevents overflow by design.
+
+---
+
+## Layout Philosophy: Outside-In Design
+
+### The Signage Layout Mindset
+
+Digital signage requires a fundamentally different layout approach than typical web development.
+
+**Typical Web (Inside-Out):**
+- Content determines its size first
+- Elements demand the space they require
+- Containers grow to fit content
+- Overflow is handled with scrollbars
+
+**Digital Signage (Outside-In):**
+- Viewport dimensions are fixed and known upfront
+- Available space is divided among components
+- Components size themselves to fit allocated space
+- Overflow is prevented by design
+
+### Why No Overflow Is Acceptable
+
+In signage, **overflow is NOT ACCEPTABLE** because:
+- There's no user to scroll
+- Content cut off looks unprofessional and broken
+- You cannot add scrollbars (violates no-scrolling constraint)
+- Prevention through design is the only solution
+
+**Solution:** Combine outside-in space allocation with graceful degradation techniques (text truncation, conditional hiding) to ensure content always fits elegantly.
+
+### The Outside-In Pattern
+
+Build layouts in three steps:
+
+1. **Start with viewport** - Your container is `100vw × 100vh` (fixed)
+2. **Divide space** - Use flexbox/grid to partition available real estate among top-level components
+3. **Fill allocations** - Inside components size themselves to use the space they've been given
+
+This is opposite from typical web development where elements size themselves based on content first.
+
+### CSS Techniques for Space Division
+
+| Technique | Purpose | Example |
+|-----------|---------|---------|
+| `flex: 1` | Component takes proportional share of remaining space | Main content area |
+| `fr` units | Grid tracks divide available space | `grid-template-columns: 2fr 1fr` |
+| `min-height: 0` | Allow flex children to shrink below content size | Prevents overflow |
+| `min-width: 0` | Allow flex children to shrink below content size | Prevents overflow |
+| Container queries | Text sizes itself to fit allocated container space | `font-size: min(10cqh, 6cqw)` |
+| Text truncation | Gracefully handle text that might not fit | `text-overflow: ellipsis`, `line-clamp` |
+| Conditional rendering | Hide less important elements when space is tight | `{isLandscape && <Sidebar />}` |
+
+### Dynamic Text Sizing with Container Queries
+
+Use CSS container queries with `cqw` (container query width) and `cqh` (container query height) units to size text based on its container dimensions. This is useful for two scenarios:
+
+1. **Maximizing text size** - Make text as large as possible while fitting the container
+2. **Calculated space allocation** - Divide container space among parts by calculating cq values based on known content
+
+The key advantage: cq values are **calculated based on your content** (number of lines, characters) and how much container space you want to allocate.
+
+**How it works:**
+1. Container receives allocated space from flexbox/grid (outside-in)
+2. Set `container-type: size` on the container
+3. Content uses `cqw`/`cqh` units for font sizing
+4. Use `min()` to constrain by both dimensions
+
+**Calculating cq values based on content:**
+
+Container query values should be calculated based on your content and space allocation goals:
+
+| Content | Goal | Calculation | Result |
+|---------|------|-------------|--------|
+| 2 lines of text | Occupy 50% of container height | 50% ÷ 2 lines | `25cqh` |
+| 8 characters | Occupy 100% of container width | 100% ÷ 8 chars | `12.5cqw` |
+| Result | Fit both dimensions | Use smaller value | `min(25cqh, 12.5cqw)` |
+
+**Example calculation:**
+```css
+/* Content: "CODE-123" (8 characters, 1 line) */
+/* Goal: Full width, 40% of height */
+.code {
+  font-size: min(
+    40cqh,      /* 40% height ÷ 1 line */
+    12.5cqw     /* 100% width ÷ 8 characters */
+  );
+}
+```
+
+This makes container queries a **precise space allocation tool**, not just a "make it big" tool.
+
+**Example: Grid of cards with large text**
+
+```css
+.card {
+  container-type: size; /* Enable container queries */
+  flex: 1; /* Outside-in: Accept allocated space */
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  padding: min(3cqh, 2cqw); /* Padding scales with container */
+  gap: min(1.5cqh, 1cqw);
+}
+
+.card-title {
+  font-size: min(10cqh, 6cqw); /* Constrained by container dimensions */
+  flex-shrink: 0;
+}
+
+.card-number {
+  font-size: min(55cqh, 25cqw); /* Large text that fits container */
+  font-weight: 900;
+  line-height: 1;
+  flex-shrink: 1;
+  min-height: 0;
+}
+
+.card-subtitle {
+  font-size: min(8cqh, 5cqw);
+  flex-shrink: 0;
+}
+```
+
+**How these values were chosen:**
+- `card-title`: 10cqh = ~10 characters width, 1 line height
+- `card-number`: 55cqh = ~4 characters width, 1 line at ~55% height
+- `card-subtitle`: 8cqh = ~12 characters width, 1 line height
+
+These are calculated based on expected content and desired space allocation.
+
+**Why `min(cqh, cqw)`?**
+- Takes the smaller of the two values
+- Ensures text fits both width AND height
+- Prevents overflow in either dimension
+
+**When to use:**
+- Large display text that should fill its space (numbers, codes, headlines)
+- Grids/cards where text prominence is important
+- Known content length (works best with predictable text)
+- **Precise space allocation** - When you want to divide container space proportionally based on content
+
+**When NOT to use:**
+- Body text or paragraphs (use rem + line-clamp instead)
+- Unknown/variable content length (truncation is safer)
+- Complex text layouts with multiple font sizes
+
+**Browser support:** Container queries are widely supported in modern browsers (Chrome 105+, Safari 16+, Firefox 110+). For TelemetryOS signage on updated devices, this is safe to use.
+
+### Outside-In Example
+
+```typescript
+// Render.tsx - Outside-in layout pattern
+export function Render() {
+  return (
+    <div className="render"> {/* Fixed: 100vh */}
+      <header className="render__header"> {/* Allocated: fixed height */}
+        <h1 className="render__title">Dashboard</h1>
+      </header>
+
+      <main className="render__content"> {/* Allocated: remaining space */}
+        <PrimaryPanel /> {/* Works within allocated space */}
+      </main>
+    </div>
+  )
+}
+```
+
+```css
+/* Outside-in: Divide the viewport's available space */
+.render {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.render__header {
+  flex-shrink: 0; /* Fixed allocation */
+  height: 10rem;
+}
+
+.render__title {
+  font-size: 4rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis; /* Graceful degradation for long titles */
+}
+
+.render__content {
+  flex: 1; /* Takes remaining space after header */
+  min-height: 0; /* Critical: allows shrinking if needed */
+}
+```
+
+### Anti-Patterns (Inside-Out Thinking)
+
+```css
+/* WRONG - Content dictates size */
+.content {
+  height: auto; /* Size based on content */
+  min-height: 800px; /* Fixed demand that might overflow */
+}
+
+/* WRONG - No space division */
+.container {
+  display: block; /* Elements stack naturally */
+  /* Content grows unbounded */
+}
+
+/* CORRECT - Outside-in approach */
+.content {
+  flex: 1; /* Accept allocated space */
+  min-height: 0; /* Can shrink if needed */
+}
+
+.container {
+  display: flex; /* Divide space */
+  flex-direction: column;
+}
+
+/* CORRECT - Graceful degradation for content that might not fit */
+.text {
+  overflow: hidden;
+  text-overflow: ellipsis; /* Show ... instead of cutting off */
+  white-space: nowrap;
+}
+
+.optional-element {
+  /* Use conditional rendering: {hasSpace && <OptionalElement />} */
+}
+```
+
+**Key principle:** Build outside-in. Use flexbox and grid to divide available real estate, not to accommodate content demands. When content might not fit, use graceful degradation (truncation, conditional hiding) instead of hard cutoff.
+
+---
+
+## Layout Patterns
+
+### Full Viewport Content
+
+Digital signage layouts should fill the viewport completely:
+
+```typescript
+import { useUiScaleToSetRem, useUiAspectRatio } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+
+export function Render() {
+  const [isLoading, uiScale] = useUiScaleStoreState()
+  const aspectRatio = useUiAspectRatio()
+
+  useUiScaleToSetRem(uiScale)
+
+  if (isLoading) return null
+
+  const isPortrait = aspectRatio < 1
+
+  return (
+    <div className="render">
+      {/* Content that fills viewport */}
+      <header>...</header>
+      <main>...</main>
+    </div>
+  )
+}
+```
+
+```css
+/* The init project's .render class handles this */
+.render {
+  /* Already set: width: 100vw, height: 100vh, overflow: hidden */
+  /* Just add your content layout */
+  display: flex;
+  flex-direction: column;
+}
+```
+
+### Auto-Rotation Considerations
+
+Digital signage content may rotate in/out of playlists or compositions:
+
+```typescript
+export function Render() {
+  const [isLoading, uiScale] = useUiScaleStoreState()
+
+  useUiScaleToSetRem(uiScale)
+
+  // Clean up timers/subscriptions on unmount
+  useEffect(() => {
+    const interval = setInterval(() => {
+      // Refresh data
+    }, 60000)
+
+    return () => clearInterval(interval)
+  }, [])
+
+  if (isLoading) return null
+
+  return <div className="render">...</div>
+}
+```
+
+**Best practices for auto-rotation:**
+- Use `useEffect` cleanup to clear timers/subscriptions
+- Don't rely on user interaction to trigger updates
+- Content should be meaningful from the moment it appears
+- Use store subscriptions for real-time data updates
+
+---
+
+## Complete Example
+
+### Digital Signage Dashboard
+
+```typescript
+// Render.tsx - Display-only dashboard
+import { useUiScaleToSetRem, useUiAspectRatio } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+import './Render.css'
+
+export function Render() {
+  const [isLoading, uiScale] = useUiScaleStoreState()
+  const aspectRatio = useUiAspectRatio()
+
+  useUiScaleToSetRem(uiScale)
+
+  if (isLoading) return null
+
+  const isPortrait = aspectRatio < 1
+
+  return (
+    <div className="render">
+      <header className="render__header">
+        <h1 className="render__title">Dashboard</h1>
+      </header>
+
+      <main className={`render__content ${isPortrait ? 'render__content--portrait' : ''}`}>
+        <div className="render__primary">
+          <MainDisplay />
+        </div>
+
+        {!isPortrait && (
+          <aside className="render__sidebar">
+            <SecondaryInfo />
+          </aside>
+        )}
+      </main>
+    </div>
+  )
+}
+```
+
+```css
+/* Render.css - Display-only styles */
+.render__header {
+  flex-shrink: 0;
+  margin-bottom: 2rem;
+}
+
+.render__title {
+  font-size: 4rem;
+  margin: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.render__content {
+  flex: 1; /* Outside-in: Takes remaining space after header */
+  min-height: 0; /* Critical: prevents overflow */
+  display: flex;
+  gap: 2rem;
+}
+
+.render__content--portrait {
+  flex-direction: column;
+}
+
+.render__primary {
+  flex: 1; /* Outside-in: Proportional space allocation */
+  min-width: 0; /* Allows shrinking */
+  min-height: 0; /* Allows shrinking */
+}
+
+.render__sidebar {
+  width: 25rem; /* Outside-in: Fixed allocation */
+  flex-shrink: 0; /* Maintains fixed size */
+}
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Adding `:hover` styles on digital signage | No mouse on display-only apps | Remove interaction states for display-only |
+| Using `overflow: scroll` | No user to scroll | Use `overflow: hidden`, truncate content |
+| Creating scrollbars | No one can use them | Fit content to viewport, hide overflow |
+| Fixed content height > 100vh | Content disappears off-screen | Use `flex: 1` and `min-height: 0` |
+| Using `height: auto` on containers | Content dictates size (inside-out) | Use `flex: 1` to accept allocated space |
+| Forgetting `min-height: 0` on flex children | Prevents shrinking, causes overflow | Always add `min-height: 0` to flex children |
+| Setting `min-height` in px on main containers | Creates fixed demand that can overflow viewport | Use `flex: 1` instead of fixed minimums |
+
+---
+
+## Tips for Digital Signage
+
+✅ **Think outside-in** - Start with viewport dimensions, divide space with flex/grid, let components fill their allocations
+✅ **Use container queries for dynamic text sizing** - `min(cqh, cqw)` makes text as large as possible while fitting the container
+✅ **Preview at multiple aspect ratios** - Test portrait and landscape in dev host
+✅ **Test text truncation** - Verify ellipsis works correctly
+✅ **Ensure content fits** - Nothing should require scrolling
+✅ **Use timer-based updates** - Content can rotate/refresh automatically
+✅ **Subscribe to store changes** - Content updates when Settings change
+✅ **Clean up effects** - Clear timers/subscriptions on unmount
+✅ **No interaction states** - Remove `:hover`, `:focus`, `:active` CSS
+
+---
+
+## See Also
+
+- `tos-render-ui-design` - Foundation concepts for all render views (UI scaling, rem usage, responsive layouts)
+- `tos-render-kiosk-design` - If you need to add interaction later (touch, onClick, idle timeout)