@telemetryos/cli 1.9.0 → 1.11.0

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

@@ -0,0 +1,325 @@
+---
+name: tos-render-ui-design
+description: Foundation for TelemetryOS Render views. MUST use FIRST before tos-render-signage-design or tos-render-kiosk-design. Covers UI scaling, rem usage, responsive layouts, and best practices for all display types.
+---
+
+# Render View UI Design (Foundation)
+
+This skill covers the foundational UI design patterns for ALL TelemetryOS Render views, whether building digital signage (display-only) or interactive kiosks (touch-enabled).
+
+> **Note:** Always read this skill FIRST, then read either `tos-render-signage-design` (display-only) or `tos-render-kiosk-design` (interactive) depending on your use case.
+
+> **Base styles:** The init project already provides base infrastructural styles in `index.css` (viewport scaling, box-sizing) and `Render.css` (`.render` class with padding, overflow, flexbox). Build on these—don't override them. But feel free to build a new visual theme.
+
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+
+---
+
+## Quick Reference
+
+| Concept | Key Points | Where Used |
+|---------|-----------|------------|
+| UI Scaling | Call `useUiScaleToSetRem(uiScale)` once in Render | All render views |
+| rem Units | All sizing in rem (not px) | All styles |
+| Title Safe Zone | Keep ~3rem padding from edges | All layouts |
+| Text Size | Minimum 2rem for body, 4rem for headlines | All text |
+| Flex Layouts | Use `min-height: 0` on flex children | All containers |
+| Text Overflow | Truncate with ellipsis or line-clamp | All text that might overflow |
+| Responsive | Use `useUiAspectRatio()` for portrait/landscape | Adaptive layouts |
+| Outside-In Layout | Divide viewport space first, components fill allocations (see signage skill) | Signage layouts |
+
+**Next steps after reading:**
+- Display-only content? → Read `tos-render-signage-design`
+- Interactive kiosk? → Read `tos-render-kiosk-design`
+
+---
+
+## UI Scale System
+
+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)
+
+Sets the document's root font-size based on viewport. **Call once in your Render view:**
+
+```typescript
+import { useUiScaleToSetRem } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+
+export function Render() {
+  const [_isLoading, uiScale] = useUiScaleStoreState()
+  useUiScaleToSetRem(uiScale)
+
+  return <div className="content">...</div>
+}
+```
+
+**How it works:**
+- At scale 1: `1rem` = 1% of viewport's longest dimension
+- At scale 2: `1rem` = 2% of viewport's longest dimension
+- A 2rem font occupies identical screen percentage on Full HD and 4K
+
+### useUiAspectRatio()
+
+Returns current aspect ratio, updating on resize:
+
+```typescript
+import { useUiAspectRatio } from '@telemetryos/sdk/react'
+
+export function Render() {
+  const aspectRatio = useUiAspectRatio()
+
+  // > 1 = landscape, < 1 = portrait, = 1 = square
+  const isPortrait = aspectRatio < 1
+
+  return (
+    <div className={isPortrait ? 'portrait-layout' : 'landscape-layout'}>
+      ...
+    </div>
+  )
+}
+```
+
+---
+
+## Layout Fundamentals
+
+### Use rem for Everything
+
+All sizing should use `rem` to scale with the UI scale setting:
+
+```css
+/* CORRECT - Scales with viewport */
+.title {
+  font-size: 4rem;
+  margin-bottom: 1rem;
+}
+
+.card {
+  padding: 2rem;
+  border-radius: 0.5rem;
+}
+```
+
+```css
+/* WRONG - Fixed pixels don't scale */
+.title {
+  font-size: 48px;
+  margin-bottom: 12px;
+}
+```
+
+### Title Safe Zone
+
+The init project's `.render` class already applies ~3rem padding from screen edges (SMPTE ST 2046-1 standard for avoiding bezel cutoff). Keep this padding when building your layout.
+
+### Constrain Layouts
+
+The init project's `index.css` and `.render` class already set up the base layout with `overflow: hidden` and flexbox. When adding child elements, use `min-height: 0` or `min-width: 0` on flex children to allow them to shrink:
+
+```css
+.my-content {
+  flex: 1;
+  min-height: 0; /* Allows flex children to shrink below content size */
+}
+```
+
+### Text Truncation
+
+When text might overflow, truncate gracefully:
+
+```css
+/* Single line truncation */
+.title {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Multi-line truncation */
+.description {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+```
+
+---
+
+## Typography
+
+### Minimum Text Size
+
+Text should be no smaller than ~2rem for comfortable viewing at typical distances (approximately 4% of screen height):
+
+```css
+.body-text {
+  font-size: 2rem; /* Minimum readable size */
+}
+
+.headline {
+  font-size: 4rem;
+}
+
+.small-label {
+  font-size: 1.5rem; /* Use sparingly */
+}
+```
+
+**Why 2rem minimum?**
+- Content is viewed from a distance (not handheld)
+- Smaller text becomes unreadable
+- 2rem ≈ 4% of screen height at scale 1
+
+---
+
+## Responsive Design
+
+### Adaptive Content for Orientation
+
+Use `useUiAspectRatio()` to adapt layouts for portrait vs landscape:
+
+```typescript
+function Dashboard() {
+  const aspectRatio = useUiAspectRatio()
+  const isPortrait = aspectRatio < 1
+
+  return (
+    <div className={`dashboard ${isPortrait ? 'dashboard--portrait' : ''}`}>
+      <PrimaryContent />
+      {/* Hide sidebar in portrait mode */}
+      {!isPortrait && <Sidebar />}
+    </div>
+  )
+}
+```
+
+```css
+.dashboard {
+  display: flex;
+  gap: 2rem;
+}
+
+.dashboard--portrait {
+  flex-direction: column;
+}
+```
+
+---
+
+## Store Hook for UI Scale
+
+Create a store hook to let admins adjust the UI scale in Settings:
+
+```typescript
+// hooks/store.ts
+import { createUseInstanceStoreState } from '@telemetryos/sdk/react'
+
+export const useUiScaleStoreState = createUseInstanceStoreState<number>('ui-scale', 1)
+```
+
+```typescript
+// Settings.tsx - Add slider control
+import { SettingsSliderFrame, SettingsField, SettingsLabel } from '@telemetryos/sdk/react'
+import { useUiScaleStoreState } from '../hooks/store'
+
+export function Settings() {
+  // Pass 0 debounce for instant slider updates
+  const [isLoading, uiScale, setUiScale] = useUiScaleStoreState(0)
+
+  return (
+    <SettingsField>
+      <SettingsLabel>UI Scale</SettingsLabel>
+      <SettingsSliderFrame>
+        <input
+          type="range"
+          min={1}
+          max={3}
+          step={0.01}
+          disabled={isLoading}
+          value={uiScale}
+          onChange={(e) => setUiScale(parseFloat(e.target.value))}
+        />
+        <span>{uiScale}x</span>
+      </SettingsSliderFrame>
+    </SettingsField>
+  )
+}
+```
+
+---
+
+## Best Practices Summary
+
+✅ **Use rem everywhere** - All sizing should use rem units, not px
+✅ **Call useUiScaleToSetRem() once** - In Render view with uiScale from store
+✅ **Respect title safe zone** - Keep the ~3rem padding from init project
+✅ **Keep text readable** - Minimum 2rem for body, 4rem for headlines
+✅ **Constrain flex layouts** - Use `min-height: 0` on flex children
+✅ **Truncate overflow** - Use ellipsis or line-clamp for text that might overflow
+✅ **Adapt to orientation** - Use `useUiAspectRatio()` for portrait/landscape layouts
+✅ **Don't override base styles** - Build on index.css, don't replace it
+
+---
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Using `px` units | Won't scale across resolutions | Use `rem` everywhere |
+| 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 uiScale |
+| Text below 2rem | Unreadable from viewing distance | Minimum 2rem for body text |
+| 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 |
+
+---
+
+## Next Steps
+
+After mastering these foundational concepts, read the appropriate specialized skill:
+
+### Building Display-Only Content (Digital Signage)?
+→ Read `tos-render-signage-design`
+- No user interaction patterns
+- No scrolling constraints
+- Auto-rotation considerations
+
+### Building Interactive Content (Kiosk)?
+→ Read `tos-render-kiosk-design`
+- Touch interaction patterns
+- Idle timeout behavior
+- Navigation state management