Skip to content

DESIGN.md

Latest commit

 

History

History
94 lines (72 loc) · 4.83 KB

DESIGN.md

File metadata and controls

94 lines (72 loc) · 4.83 KB
Raw

Perception Learning Design System

Product Context

  • Product: A curriculum-linked reading, prediction, simulation, and reflection environment.
  • Audience: Learners from upper elementary through introductory college.
  • UX goal: Make a science text feel like a living field guide whose diagrams can be tested.
  • Brand attributes: curious, tactile, rigorous, generous, playful.

Aesthetic Direction

  • Primary direction: Living field guide — an editorial library with paper, ink, subject-colored book cloth, margin notes, and laboratory instruments.
  • Secondary influences: modern children’s science museums, beautifully indexed reference books, and restrained game HUDs.
  • One memorable visual moment: a textbook section opens into a split-page “proof desk,” while the account page reads like a dark field-guide cover opening onto a precise paper sign-in form.
  • Explicitly avoid: dark AI dashboards, purple gradients, generic card grids, excessive pills, fake chat interfaces, reward confetti, and decorative gamification without learning value.

Layout System

  • Grid: 12-column desktop; 8-column tablet; single-flow mobile.
  • Breakpoints: 600px, 860px, 1100px, 1380px.
  • Container widths: library 1480px; reader 1560px; prose column 720px.
  • Section rhythm: 24px compact, 48px standard, 80px major transitions.

Spacing Scale

  • Base unit: 8px.
  • Scale: 4, 8, 12, 16, 24, 32, 40, 48, 64, 80.
  • Dense reader controls use 8–16px; book/library compositions use 24–48px.

Typography

  • Display font: Literata Variable — book titles, lesson questions, reflective writing.
  • Body font: Manrope Variable — navigation, labels, controls, accessible reading.
  • Monospace font: ui-monospace — equations, model checks, experiment telemetry.
  • Type scale: 12, 14, 16, 18, 22, 28, 40, 64, 88.
  • Body copy: 17–19px, line-height 1.65, maximum 72 characters.
  • Labels: uppercase only for short metadata, never prose.

Color Tokens

  • Background: warm paper #fbfaf5.
  • Surface: white #ffffff.
  • Elevated surface: parchment #f3efe3.
  • Primary text: ink #1b1b17.
  • Secondary text: graphite #68675f.
  • Accent: ultramarine #1647d8.
  • Subject colors: biology #2e6a52; physics #1b4a75; chemistry #b8512e; earth science #9a6b24.
  • Accent contrast: white.
  • Border: linen #d9d5c9.
  • Success: #1d7253.
  • Warning: #a15f16.
  • Error: #d8452f.

Radius, Border, Shadow

  • Radius scale: 3px for paper controls, 8–12px for tools, and 20–30px only for major page surfaces.
  • Borders: 1px neutral rule; 2px subject-color selection; stitched/dashed rules for drafts.
  • Shadows: book shadow (offset layered paper), floating instrument shadow, no ambient card shadows.

Motion System

  • Durations: 120ms controls, 220ms panels, 480ms page/stage transitions.
  • Easing: cubic-bezier(.2,.75,.25,1).
  • Page-load choreography: title, shelf, then tools; never animate reading paragraphs.
  • Hover/focus: book lifts 4px; instrument controls increase contrast; 3px visible focus ring.
  • Reduced motion: stop page lifts and run the lab without interpolation.

Components

  • Buttons: rectangular, decisive labels, visible icon only when meaningful.
  • Inputs: paper-white, strong labels, 44px minimum touch targets.
  • Book cards: physical spine/cover composition with subject color and progress bookmark.
  • Navigation: library, lab, notes, trail, and a dedicated account page; mobile bottom bar keeps learning destinations separate from account controls.
  • Account page: editorial “learning passport” composition, with a dark field-guide story panel and a quiet paper form; never use a floating auth modal.
  • Empty states: suggest one concrete next action and one curriculum example.
  • Errors: plain-language recovery beside the failed tool.
  • Loading: model-building status with progress checkpoints, never a fake AI chat stream.

Accessibility Rules

  • Minimum body size: 16px; teacher metadata may be 12–14px.
  • Contrast: WCAG AA minimum.
  • Focus style: 3px translucent ultramarine outline with 3px offset.
  • Keyboard navigation: every book, reader section, note action, account control, and lab challenge is reachable.
  • 3D lab: equivalent text state through render_game_to_text; no visual-only success condition.

Implementation Notes

  • Framework: React 19 + TypeScript + Vite + Cloudflare Worker.
  • Styling: project CSS tokens and component classes.
  • Rendering: Three.js canvas for the demo lab; deterministic fixed-step simulation hooks for automated testing.
  • Persistence: InsForge owns authentication; the authenticated user UUID scopes Cloudflare D1 notes, experiments, assessments, lesson guides, and progress so learning restores with the account.
  • Curriculum content: link and attribute OpenStax. Do not ingest entire books into Workers AI; use teacher-reviewed briefs and authored summaries.
  • Targets: current evergreen browsers, iPad/tablet landscape, 390px mobile minimum.