family_home_lab/DESIGN.md

DESIGN.md — Family Home Lab Console

Design system for the family console portal (console.home.lab). Base system: Notion marketing design language (awesome-design-md) — warm daylight document calm, one structural blue, decorative sticker palette. Stack context: server-rendered FastAPI + Jinja2 + HTMX. No SPA build chain; tokens map to CSS custom properties in portal/static/tokens.css.

Brand Personality

The console reads as a well-organised family desk: warm paper-soft canvas, near-black confident type, exactly one dependable blue for actions. Each tool gets its own sticker colour so family members can find "their" tools at a glance — colour decorates, never structures. The login screen is the single dark indigo "night band" moment; everything after login is daylight.

Colors

Surface

Token	Value	Use
{colors.canvas-soft}	#f6f5f4	App canvas / page background
{colors.canvas} / {colors.surface}	#ffffff	Cards, panels, nav bar, inputs, iframes wells
{colors.hairline}	#e6e6e6	1px borders, dividers

Text

Token	Value	Use
{colors.ink}	#000000 (~95% alpha rendered)	Headings, primary text
{colors.ink-secondary}	#31302e	Body copy
{colors.ink-muted}	#615d59	Supporting text, descriptions
{colors.ink-faint}	#a39e98	Captions, metadata, placeholders

Structural accents

Token	Value	Use
{colors.primary}	#0075de	Login/submit buttons, inline links, active tab, focus rings — the only action colour
{colors.primary-active}	#005bab	Pressed state of primary buttons
{colors.on-primary}	#ffffff	Text on primary fills
{colors.secondary}	#213183	Deep indigo — login screen background and header greeting band only

Sticker palette (decorative ONLY — never paints CTAs or structure)

Assigned permanently to tool categories:

Token	Value	Category assignment
{colors.accent-sky}	#62aef0	Chat (dsh instances)
{colors.accent-purple}	#d6b6f6	Image tools (Photopea)
{colors.accent-pink}	#ff64c8	Video tools
{colors.accent-orange}	#dd5b00	Audio tools
{colors.accent-teal}	#2a9d99	Documents (future)
{colors.accent-green}	#1aae39	Status ticks ("online", success toasts)
{colors.accent-purple-deep}	#391c57	Deep shade within illustrations only
{colors.accent-orange-deep}	#793400	Deep shade within illustrations only

Semantic status reuses stickers: green = online/saved, orange = busy/starting, faint grey = offline.

Typography

Font: Inter (self-hosted woff2 in static/fonts/; substitute for NotionInter). Fallbacks: -apple-system, system-ui, "Segoe UI", Helvetica, Arial. OpenType lnum enabled on numerals.

Token	Size	Weight	LH	Tracking	Use
{typography.display-1}	48px	700	1.05	−1.5px	Login headline ("Good evening, Sam") on indigo band
{typography.heading-1}	32px	700	1.1	−0.8px	Dashboard greeting, section headlines
{typography.heading-2}	22px	700	1.27	−0.25px	Tool category headings
{typography.title}	17px	600	1.4	−0.125px	Tool card names
{typography.body-md}	15px	400	1.5	0	Default body
{typography.body-sm}	14px	400	1.4	0	Dense UI, table rows
{typography.button}	15px	500	1.4	0	Button labels
{typography.caption}	13px	400	1.43	0	Metadata, timestamps
{typography.eyebrow}	12px	600	1.33	+0.125px	Category pills, badges

Principle: heavy 700 headlines with explicit negative tracking vs calm 400 body. No decorative typography.

Layout

• Base unit 8px. Tokens: xxs 4 · xs 8 · sm 12 · md 16 · lg 24 · xl 28 · xxl 32.
• Dashboard container: centred, max-width 1200px, generous gutters ({spacing.xxl} desktop).
• Tool grid: responsive auto-grid — 3-up desktop → 2-up tablet (≤840px) → single column mobile (≤600px).
• Whitespace groups; sections separated by large vertical gaps, no rules.
• Touch targets ≥44×44px on mobile.
• Iframe/embed view: full-width white well below a slim sticky tool bar.

Elevation

Level	Treatment	Use
0 Flat	Hairline border only	Default tool cards
1 Soft	Layered micro-shadow: rgba(0,0,0,.01) 0 .175px 1px, rgba(0,0,0,.02) 0 .8px 3px, rgba(0,0,0,.027) 0 2px 8px, rgba(0,0,0,.04) 0 4px 18px	Hovered/raised cards, floating elements
2 Elevated	Deeper stack ending rgba(0,0,0,.05) 0 23px 52px	Modals, popovers

Never hard drop-shadows.

Shapes

Token	Value	Use
{rounded.xs}	4px	Text inputs, chips
{rounded.sm}	5px	Menu items, list rows, status pills
{rounded.md}	8px	Utility buttons, smaller cards
{rounded.lg}	12px	Tool cards, iframe wells, modals
{rounded.full}	9999px	Pill CTAs, avatar circles, icon buttons

Inputs stay tight (4px); CTAs pill. Never swap.

Components

Screens

1. Login screen (ex-auth-form-card + hero-band): full-viewport deep indigo {colors.secondary} band; white display-1 greeting; centred white auth card ({rounded.lg}, Level-2 shadow) with username + password text-inputs and one button-primary "Sign in". Subtle starfield/sticker dots decoration. This is the page's only dark moment.
2. Dashboard (post-login): sticky slim nav-bar (white, wordmark left, user avatar + logout right); heading-1 time-aware greeting ("Good morning, Sam"); tool grid grouped by category with eyebrow pills in category sticker colours; each tool a tool-card.
3. Tool embed view: sticky tool bar (white, back arrow, tool title, open-in-new-tab button-utility) above a full-width white iframe well ({rounded.lg}, hairline). Falls back to link-out card if the tool forbids framing.
4. Admin panel (Sam only): same chrome; user management rows, add-user form, service status list.

Core primitives

• nav-bar — white surface, body-sm links, md padding, hairline bottom edge.
• button-primary — blue fill, on-primary text, pill, brief scale(0.97) press → {colors.primary-active}.
• button-secondary — white, ink text, pill, Level-1 shadow.
• button-utility — white, ink text, {rounded.md}, 4px 14px padding, hairline border.
• tool-card — white, {rounded.lg}, padding lg, hairline (Level-0); hover lifts to Level-1. Contains: 40px circular icon tile filled with the category's sticker colour (white glyph), title typography, caption description, status dot (green/orange/faint), and launch affordance (inline-embed vs new-tab shown as small caption chip).
• category-pill — eyebrow type, white surface, category sticker-coloured text + dot, pill, 4px 8px.
• text-input — white, ink text, body-sm, 1px rgb(221,221,221) border, {rounded.xs}, 6px+ padding; focus adds Level-1 shadow + blue ring.
• status-dot — 8px circle: {colors.accent-green} online, {colors.accent-orange} starting, {colors.ink-faint} offline.
• modal-card — feature-card chrome + Level-2 shadow (confirmations, add-user dialog).
• toast — card shape + medium shadow, green tick sticker for success.

HTMX Behaviour Notes

• Tool grid refreshes via hx-get polling every 30s (status dots update without reload).
• Login posts via standard form (full redirect — session cookie set server-side).
• Embed view swaps into <main> with hx-push-url so browser back works.
• Loading states use a subtle opacity pulse on cards (never spinners-on-stickers).

Do's and Don'ts

Do

• Keep the app on {colors.canvas-soft}; cards/fields pure white.
• Reserve {colors.primary} strictly for sign-in, submit, links, active state.
• Give each tool category its fixed sticker colour (see table) used only in icon tiles and category pills.
• Apply negative tracking explicitly on headings.
• One dark moment per session: the login screen.
• Hairlines + layered micro-shadows for depth.

Don't

• Don't paint buttons or structural fills with sticker colours.
• Don't introduce a second accent alongside {colors.primary}.
• Don't round inputs like pills or vice versa.
• Don't use heavy drop-shadows.
• Don't repeat dark bands inside the dashboard.
• Don't render pages on clinical pure-white backgrounds.