# Silvie Mini Design System · v1.0

## Scope and source of truth

A compact HTML/CSS system for the current family-facing app concept. `tokens.css` defines raw tokens, semantic roles and compatibility aliases used by the prototype. The earlier Activity view is embedded with its existing styles and inherits the same foundation values; that view still has local layout styles. This is a code-based mini design system, not a published Figma library.

## Foundations

- UI font: system sans-serif; regular 400, medium 500, semibold 600.
- App titles: 31px. Metric hero: 48px. Section headings: 17–23px. UI text: 12–14px. Secondary chart labels: 9–11px in the existing prototype; production readability needs user validation.
- Spacing: 4 / 8 / 12 / 16 / 20 / 24 / 32 / 48px.
- Radius: badge 6, control 9, field 10, small card 16, card 20, dialog 22px.
- App actions target at least 44px height. Focus uses an explicit outline.
- Design workspace: one fixed 1440px composition, scaled proportionally, without mobile reflow.

## Elements and components

| Name | Anatomy and variants | States and rules |
|---|---|---|
| ActionButton | Primary, secondary; label + optional leading icon | Default, hover, focus, disabled. Label names the action. |
| StatusBadge | Symbol + concise status | Stable, slight deviation, significant deviation, unavailable, learning. Never color alone. |
| MetricCard | Category, period, value, baseline, status, navigation | Available, deviation, unavailable, learning. Missing data never rendered as zero. |
| InsightPanel | Observation, context, action | Mixed data preserved; no implied medical diagnosis. |
| SegmentedControl | Two period choices | Selected state exposed via aria-pressed. Complete periods only. |
| TrendChart | Bars, period labels, selected value | Each bar has an accessible name and keyboard focus; selected bar retains focus after rendering. |
| FollowUpForm | Contact method, note, next step | Required note, inline error, save, edit. User text is escaped before display. |
| StatePanel | Icon, heading, explanation, action | Learning, unavailable, connection failure, recovery. |
| ConfirmationPanel | Saved state, note summary, return/edit | Saving never changes the original sensor observations. |
| Dialog | Heading, content, close/action | Escape closes; native modal focus containment; labelled dialog. |
| BottomNavigation | Four category destinations | Current page exposed with aria-current. Follow-up is a contextual path. |

## Patterns

1. Review change: Overview → insight details → review → follow-up note → confirmation → Overview.
2. Recover data: Overview → unavailable Bathroom → check sensor → failed retry → retry → restored sample data.
3. Establish baseline: Learning explains that data is insufficient. The production exit criterion remains unverified.

## Governance proposal

This is a solo design exercise; no organization owner is claimed. Proposed owner: product design, with an engineering counterpart. Change semantic tokens before local overrides; update the component examples and affected screenshots together. New variants require a documented use case and a state check. Patch releases correct details, minor releases add compatible variants, major releases change meaning or anatomy. Current version 1.0 records this initial consolidation.

## Evidence and limits

All household values and device outcomes are demo data. Follow-up notes persist only until refresh. No calls, messages, reminders or device requests are sent. Browser checks verify the implementation, not user success. Research and clinical conclusions are not fabricated.

## Version 1.1 — neutral foundations and expanded specimens

The current reference is `tokens.css` and the six live panels in `../02-app.html`. Earlier green surface examples are superseded. Canvas: #FCFCFD; card: #FFFFFF; secondary surface: #EEF0F2; primary text: #252B32; secondary text: #606771. Action green: #285B40. Amber, red and blue-gray are semantic status roles, not decorative section backgrounds.

Typography: platform system sans for product UI; Georgia for brand/editorial storytelling. Reference scale: 48 / 32 / 24 / 18 / 14 / 13 / 12px. Weights: 400 / 500 / 600. Data uses tabular numerals. Spacing: 4 / 8 / 12 / 16 / 20 / 24 / 32 / 48px. Radius: 6 / 8 / 12 / 16px. Interaction targets: 44px minimum at reference scale. Focus: #375E96.

Icons: `icons.svg`, 20 symbols named `ds-home`, `ds-activity`, `ds-moon`, `ds-bathroom`, `ds-users`, `ds-phone`, `ds-check`, `ds-alert`, `ds-info`, `ds-wifi-off`, `ds-refresh`, `ds-arrow-left`, `ds-arrow-right`, `ds-close`, `ds-plus`, `ds-clipboard`, `ds-clock`, `ds-chevron-down`, `ds-search`, `ds-shield`. ViewBox 24×24, 1.75px stroke, rounded joins/caps; display 16/20/24px. Decorative icons are aria-hidden; icon-only buttons need accessible names.

Live component specimens include ActionButton, StatusBadge, MetricCard, TextField, SegmentedControl, ChoiceControl, BottomNavigation and Dialog/StatePanel. Interaction states include default, hover, pressed, focus, disabled and loading. Product states include available, deviation, learning, unavailable, empty, input error, connection error and saved. The page demonstrates local interactions; it does not contact real users or devices.

Exports: foundations.png, colors.png, icons.png, components.png, states.png, patterns.png. Read IMPECCABLE-AUDIT.md for verified checks and remaining limitations. Fixed 1440px proportional presentation does not guarantee mobile target sizes after scaling.


## v1.2 — continuous presentation
All six design-system sections are visible in a continuous scroll; the contents links jump to sections and never hide content. Wireframe viewports use the same 390:844 aspect ratio as UI captures (180 × 389.54px at the reference canvas). High-fidelity screens use a borderless image-above-caption gallery, with no card wrapper. Exports have been refreshed.