openpetswithchatandmcp/DESIGN.md

FamiliarOS Control Center: Design System & Engineering Manual

This document outlines the visual direction, component patterns, and front-end engineering guidelines for the FamiliarOS Control Center. It serves as a practical implementation guide for migrating existing views (Settings, Plugins, Integrations, Onboarding) and building new pages using a cohesive, high-fidelity tactile design system.

---

1. Visual Direction & Heritage

The FamiliarOS Control Center blends the nostalgic, playful charm of late-90s/early-2000s desktop familiar managers with a modern, glassmorphic utility interface.

• The Core Tension: Playful nostalgia meets crisp, modern desktop productivity.
• Atmospheric Depth: Instead of flat, sterile surfaces, interfaces leverage rich color gradients, subtle mesh backdrops, structured panels, and tactile control elements.
• Physicality: Interactive components feel physical. They have distinct borders, inset highlights, drop shadows, and visual feedback on click/press.

---

2. Backgrounds & Surface Treatments

Surfaces are layered to establish clear spatial hierarchy and keep the interface readable.

Page Backdrop

• Formula: A radial ambient glow on top of a subtle linear gradient.
• Implementation:

  background: radial-gradient(circle at 12% 8%, rgba(219, 234, 254, 0.9), transparent 24%),
              linear-gradient(180deg, #f8fbff 0%, #eff7ff 54%, #e9f3ff 100%);
  

Glass Panels (.glass / GlassCard)

• Panels use semi-transparent white fills coupled with a distinct double-border look (using inset box shadows) to simulate thick, polished acrylic sheets.
• Specifications:
  • Background: rgba(255, 255, 255, 0.76)
  • Border: 1px solid rgba(126, 161, 210, 0.48)
  • Inner Highlight: inset 0 1px 0 rgba(255, 255, 255, 0.96)
  • Shadow: 0 24px 60px rgba(61, 99, 160, 0.15)
  • Blur: backdrop-blur-xl
  • Border Radius: 28px (rounded-[28px])

---

3. Page Shell, Layout & Grids

The desktop shell is designed to be self-contained, fitting exactly within the viewport height without scrolling the entire window.

• Page Shell: Max-width of 1160px centered, utilizing a full-height flexbox column (h-screen p-6).
• Hero Header: A balanced layout placing title text and description on the left (.hero-content) and the wider brand artwork (familiaros.webp) on the right (.hero-logo-container). Keep artwork large enough to feel intentional, use object-contain, and avoid rounded wrappers or distortion.
• Layout Split: A clean grid split, typically:
  • Left Gallery/List Panel: 1.25fr — for browsing, searching, and filtering.
  • Right Detail/Action Panel: 0.75fr — for contextual inspection and heavy operations.
• Scroll Containers: Sub-panels (like grids and lists) scroll internally (overflow-y-auto) with customized scrollbars so that headers, filters, and primary action bars remain pinned.

---

4. Typography & Tone

• Font Family: Refined sans-serif (e.g., Inter, system-ui) for maximum readability in body copy, labels, and metadata.
• Display Typography: Strong, characterful monospace or display-sans fonts (e.g., Lucida Console, geometric display fonts) for headers and uppercase labels to evoke retro desktop applications.
• Typographic Hierarchy:
  • Hero Title: text-5xl font-black tracking-tight
  • Panel Title: text-3xl font-black
  • Eyebrow / Section Header: text-xs font-bold uppercase tracking-[.18em] text-brand
  • Card Title: text-sm font-semibold text-navy
  • Metadata / Descriptions: text-xs text-slate-500
• Copy Tone: Conversational, clean, and helpful. Avoid overly dense technical jargon; explain state transitions clearly (e.g., "Ready to become your default familiar" instead of "State: INSTALLED, ACTIVE: FALSE").

---

5. Colors & Semantic Palette

All colors are mapped to functional roles to ensure consistency across themes.

Role	Color / Hex	Tailwind Equivalent	Semantic Usage
Brand Primary	#176df2 / #3b96ff	bg-brand / text-brand	Active filters, primary buttons, hero accents
Dark Neutral	#102149	text-navy	Main body text, card titles, heavy headings
Light Neutral	#f8fbff to #e9f3ff	bg-slate-50 / bg-blue-50	Page backdrops, card backgrounds, empty states
Slate Copy	#5c6e91	text-slatecopy	Subtitles, helper text, inactive buttons, labels
Success / Ready	#059669 / #34d399	emerald	Active indicators, successfully installed badges
Warning / Import	#d97706 / #fbbf24	amber	Codex source indicators, imports, attention states
Featured	#7e22ce / #a855f7	purple	Featured catalog filters and badges
Originals	#ca8a04 / #facc15	yellow	Original FamiliarOS catalog filters and badges
Danger / Remove	#dc2626 / #ff6b6b	red	Destructive actions, broken states, error messages

---

6. Tactile Button System

Buttons are the core interactive elements. They reject flat modern trends in favor of a chunky, tangible 3D appearance inspired by physical familiar hardware and OS controls.

Visual Architecture

• Borders: Darker semi-transparent bottom/side borders (rgba(..., 0.32)).
• Gradients: Linear vertical gradients that transition from a lighter top to a richer bottom.
• Inset Highlights: A subtle light line (inset 0 1px 0 rgba(255,255,255,0.38)) on the top edge to simulate light catching the button's crown.
• Shadows: Keep buttons grounded. Use subtle neutral depth plus inset highlights; avoid large colored glow shadows.

Interactive Rules

• Hover States: Under current design guidelines, avoid dramatic hover glows or float lifts. Hovering should simply shift the gradient/background color slightly to maintain a grounded, crisp, and predictable interface.
• Active Click State: On press, the button scales down slightly to 0.96 to provide a satisfying physical click response.
  • Constraint: Always use targeted transitions (transition-[transform,background-color,border-color,box-shadow]) instead of transition-all to prevent layout reflow stutter.

Button Variants

1. Primary (.btn-primary):
   • Gradient: #3b96ff to #176df2
   • Shadow: inset 0 1px 0 rgba(255,255,255,0.38), 0 2px 4px rgba(61,99,160,0.10)
2. Secondary (.btn-secondary):
   • Surface: rgba(255,255,255,0.76) with text #176df2
   • Border: rgba(37, 99, 235, 0.42)
3. Danger (.btn-danger):
   • Gradient: #ff6b6b to #dc2626
   • Shadow: same subtle neutral depth as primary; do not add red glow
4. Warning (.btn-warning):
   • Gradient: #fbbf24 to #d97706
5. Success (.btn-success):
   • Gradient: #34d399 to #059669
6. Compact Button (.btn-compact):
   • Designed for pagination (.pager) and secondary rows.
   • Reduces size to min-h-[30px], padding to px-2.5 py-1, and font size to text-xs with a tighter border-radius (rounded-xl).

---

7. Controls & Navigation Elements

Filters (.filter)

• Instead of simple pill badges, filters are structured as miniature tactile buttons.
• Inactive filters use a soft white-to-slate gradient with a light blue-grey border.
• Active filters swap to semantic gradients with only subtle grounded depth:
  • Brand blue for general filters (All, Installed, Western, Asian, Codex)
  • Purple for Featured
  • Amber/yellow-orange for Originals
• Match catalog v3/web gallery taxonomy where possible: Featured excludes originals, and category filters like Western/Asian exclude featured and originals.

Familiar Cards & Badges

• Card grids need inner padding so selected rings and focus states are not clipped by the scroll container.
• Use badges to expose catalog identity, not just install state:
  • Original for original/FamiliarOS familiars
  • Featured for featured non-original catalog familiars
  • Western / Asian for standard category familiars
  • Default, Installed, and Codex for local state/source
• Avoid low-value detail badges such as Available; reserve detail badges for meaningful state or catalog identity.

Search Inputs (.search)

• Rendered as soft, inset text boxes.
• Styled with bg-white/80 and shadow-inner to look recessed into the panel.
• Focus states use a visible but restrained brand ring (focus:ring-brand/15 focus:border-brand) for accessibility.

Pager (.pager)

• Placed cleanly at the bottom of list/grid containers.
• Merges compact secondary buttons with centered, bold, uppercase status text (text-xs font-bold tracking-wider).

---

8. Icons & Visual Assets

• Coherency: Use clean, outline-style vectors with a consistent stroke weight (stroke-width="2.5" or 3 for smaller shapes).
• Style Alignment: Align with the Lucide / Iconify icon libraries.
• Implementation: Embed icons as stateless, inline React SVG components or a localized icon catalog within the component file to avoid heavy runtime dependencies.
• Sizing:
  • Action/Button Icons: 16px x 16px
  • Compact/Filter Icons: 12px x 12px or 14px x 14px

---

9. React & Tailwind Implementation Notes

The Static Purge Constraint

Tailwind CSS extracts classes statically by analyzing source code strings. Do not construct class names dynamically.

// ❌ BAD: Will be purged by Tailwind in production
const color = "blue";
return <span className={`pill-${color}`}>Label</span>;

//  GOOD: Statically discoverable mapping
const statusPillToneClass = {
  blue: "pill-blue",
  green: "pill-green",
} as const;
return <span className={`pill ${statusPillToneClass[tone]}`}>Label</span>;

---

10. Migration Playbook for Future Pages

When refactoring other Control Center views, apply the following structural mapping:

A. Settings Page

• Old Layout: Long scrolling list of form controls.
• New Layout: Split-pane layout. Left side lists settings categories (General, Hotkeys, Performance) using .filter tactile navigation. Right side contains the active form wrapped in a .glass card.
• Inputs: Swap default inputs to the recessed .search input style. Use .btn-primary for the final "Save" action.

B. Plugins Page

• Old Layout: Flat list of available integrations.
• New Layout: Grid-based layout matching the .familiars-grid structure.
• Cards: Use the .familiar-card styling with a thumbnail on the left, author/description text on the right, and semantic status pills (e.g., .pill-green for "Active", .pill-slate for "Disabled").

C. Onboarding

• Old Layout: Full screen wizard.
• New Layout: Centered, floating glass card (.glass with max-w-xl shadow-glass) layered over the atmospheric radial backdrop.
• Interaction: Use staggered CSS keyframes for a smooth entrance, and a prominent .btn-primary with active scaling for the "Get Started" call to action.