How might we make products lovable by design?
The purpose of this open source monorepo isn't just to answer this question; it's to provide a functional human-centered design philosophy that helps you build the answer for yourself.
Status: Active Development License: MIT Philosophy: Read DESIGN-PHILOSOPHY.md — The North Star
This ecosystem expresses one unified vision through multiple products:
- Portfolio — The proof of philosophy. A living showcase of human-centered design with the Customizer as its centerpiece.
- Sage Design Studio — Interactive documentation platform for the design system. Makes design tokens, components, and design decisions publicly explorable.
- Creative Powerup — Community platform and experiment gallery for purpose-driven innovators (in development)
- Sage Stocks — AI-powered investment intelligence that respects user agency (migration pending)
- SageOS — Personal operating system for creative work (future)
The unifying element: A shared design system that embodies human-centered principles into every component, token, and interaction.
# Clone and install
git clone https://github.com/shalom-ormsby/ecosystem.git
cd ecosystem
pnpm install
# Build design system and start portfolio
pnpm build
pnpm dev --filter portfolio
# Open http://localhost:3000
# Look for the Customizer button in the bottom-right cornerFirst time here? Read AGENTS.md for orientation (written for AI agents but useful for humans too).
This ecosystem is built on four principles:
- Emotionally Resonant — Touch hearts, not just solve problems. Design should delight.
- User Control & Freedom — Users customize their experience. Motion intensity, themes, everything.
- Transparent by Design — Show the receipts. Users see how things work, including AI collaboration.
- Generous by Design — Open source, teachable, accessible. Code that teaches as it works.
The heart of this ecosystem. Every app imports from it. Version 1.0 — Production Ready
The design system follows atomic design principles with a clear component hierarchy:
-
Atoms (11 families) — Primitives with no internal dependencies
- Button, Input family (TextField, TextArea, Select, Checkbox, Radio, Switch), Card, Badge, Avatar, Link, Icon, Code, Spinner, ProgressBar, Motion components
-
Molecules (8 components) — Composed from atoms
- FormField, SearchBar, CheckboxGroup, RadioGroup, Dropdown, Tooltip, Breadcrumbs, ThemeToggle
-
Organisms (8 components) — Complex compositions
- Header, SecondaryNav, TertiaryNav, Footer, Modal, Toast, PageLayout, CollapsibleCodeBlock
Each theme has a unique personality and embodies different design values:
-
Studio — Professional, balanced, modern (inspired by Framer/Vercel/Linear)
- Cool blues and grays, clean sans-serif typography (Outfit, Manrope, Fira Code)
- Smooth, professional motion curves
-
Sage — Calm, organic, thoughtful
- Warm earth tones, muted sage greens, terracotta accents
- Serif headings (Lora), clean body text (Instrument Sans)
- Slower, flowing motion curves
-
Volt — Bold, electric, energetic
- Electric blues, vibrant cyans, high contrast
- Geometric sans-serif (Space Grotesk), technical mono (Fira Code)
- Fast, snappy motion curves
All themes support both light and dark modes with WCAG AA contrast ratios.
Design decisions as code, not locked in design tools:
- Colors — Semantic color system with foreground variants for proper light/dark mode support
- Typography — 10 size scales (xs-8xl), complete type presets (display, headings, body, caption)
- Spacing — 4px base grid with semantic aliases (xs-3xl)
- Motion — Duration presets and easing curves that scale with user preference
- Syntax Highlighting — 14 token types for automatic code highlighting (comment, keyword, function, string, number, boolean, operator, property, className, tag, attribute, variable, punctuation, plain)
Every animation respects user preference:
- Motion intensity slider (0-10 scale)
- Automatic sync with system
prefers-reduced-motion - Zero animation when disabled (instant state changes only)
- Scaled durations based on user preference and theme personality
User control made tangible. A floating panel that gives users ownership of their experience:
- Motion intensity — 0-10 scale with system preference sync
- Theme switching — Studio, Sage, or Volt with distinct personalities
- Color mode — Light or dark mode
- X-Ray Mode — Toggle for transparency features (in development)
All preferences persist to localStorage and survive page reloads.
Built-in automatic syntax parser (~2KB) for beautiful code examples:
- Zero configuration — Just pass plain code strings
- 14 token types — Comprehensive TypeScript/JavaScript/JSX tokenization
- Theme-aware colors — Adapts to light/dark mode with WCAG AA contrast
- No dependencies — Completely self-contained
- CollapsibleCodeBlock organism — Full-featured code display with copy, collapse, and syntax highlighting
- WCAG AA compliance — All color combinations meet 4.5:1 contrast minimum
- Keyboard navigation — Full support with visible focus indicators
- Screen reader compatible — Semantic HTML and proper ARIA attributes
- Motion preferences — Complete respect for reduced motion settings
- Focus management — Proper focus ring styling with CSS variables
- Zustand stores with localStorage persistence
- Theme state — Current theme name and color mode
- Customizer state — Motion intensity, x-ray mode, system preferences
- Toast context — Notification system with provider
Three custom React hooks for common patterns:
- useTheme() — Theme and mode control with toggle functions
- useMotionPreference() — Motion settings and system preference sync
- useForm() — Generic form state with validation and dirty tracking
- React 18/19 (peerDependency supports both)
- TypeScript 5 (strict mode)
- Tailwind CSS 3 (via CSS variables)
- Framer Motion 12 (all animations respect preferences)
- Zustand 5 (with localStorage persistence)
- tsup (ESM + CJS outputs for npm publishing)
The Sage Design Studio app (apps/sage-design-studio) provides:
- Component playground with live prop controls
- Token visualization for all design tokens across themes
- Code examples with automatic syntax highlighting
- LLM-optimized documentation with JSON-LD structured data
- Accessibility notes for every component
- GitHub source links for transparency
Visit the live documentation at https://studio.shalomormsby.com/
Full Design System Documentation →
ecosystem/
├── apps/ # Next.js applications
│ ├── portfolio/ # Proof of philosophy (production-ready)
│ ├── sage-design-studio/ # Interactive design system docs (production)
│ ├── creative-powerup/ # Experiment gallery (in development)
│ ├── sage-stocks/ # Migration pending
│ └── sageos/ # Future
├── design-system/ # The heart (at root, not in packages/)
│ ├── tokens/ # Design decisions as code
│ │ ├── base.ts # Shared scales
│ │ ├── studio.ts # Studio theme
│ │ ├── sage.ts # Sage theme
│ │ ├── volt.ts # Volt theme
│ │ ├── typography.ts # Type system
│ │ └── syntax.ts # Code highlighting
│ ├── atoms/ # 11 primitive component families
│ ├── molecules/ # 8 composed components
│ ├── organisms/ # 8 complex compositions
│ ├── hooks/ # useTheme, useMotionPreference, useForm
│ ├── features/ # Customizer (philosophy-embodying)
│ ├── providers/ # ThemeProvider, ToastProvider
│ ├── store/ # Zustand state management
│ └── utils/ # Validation, animations, colors, syntax parser
├── docs/ # Guides and documentation
└── packages/ # Shared config and utilities
Why design-system at root? It signals importance and is structured for npm publishing from day one.
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript 5 (strict) |
| Styling | Tailwind CSS 3 |
| Animation | Framer Motion 12 |
| State | Zustand 5 + localStorage |
| Monorepo | Turborepo + pnpm workspaces |
| Deployment | Vercel |
- DESIGN-PHILOSOPHY.md — The North Star. Read this first to understand why this exists.
- AGENTS.md — Comprehensive guide for AI agents (and humans) working on this codebase.
- CHANGELOG.md — What's been built, what's changed, and when.
- design-system/README.md — Design system architecture, components, tokens, and usage.
- apps/portfolio/README.md — Portfolio app setup and context.
- docs/mcp-setup.md — Configure MCP servers for AI coding assistants.
If you're building here (human or AI):
- Read DESIGN-PHILOSOPHY.md to understand the vision
- Read AGENTS.md for technical setup, patterns, and conventions
- Check CHANGELOG.md to see what's been done recently
User control made tangible. A floating panel that lets users customize:
- Motion intensity (0-10, syncs with system preferences)
- Theme (Studio, Sage, or Volt)
- Color mode (Light or dark)
- X-Ray Mode (planned)
All preferences persist to localStorage. This isn't a settings panel hidden in a menu—it's a hero feature.
Visual properties defined in code, not locked in Figma. Colors, spacing, typography, motion—all exposed as importable JavaScript.
import { spacing, typography } from '@ecosystem/design-system/tokens'Every animation checks useMotionPreference(). When motion = 0 or user has prefers-reduced-motion, animations are instant. No exceptions.
# Development
pnpm dev # Start all apps
pnpm dev --filter portfolio # Start specific app
# Building
pnpm build # Build everything
pnpm build --filter <app> # Build specific app
# Quality
pnpm lint # Lint all packages
pnpm typecheck # Check TypeScript- Node.js 20+
- pnpm 8.15.0+
- Git
This isn't aspirational—it's implemented:
- Customizer = User Control & Freedom in action
- Design tokens = Transparency (view source on any component)
- Motion system = Generous by Design (accessibility first)
- Open source = Generous by Design (anyone can learn from this)
- AI Notes feature (planned) = Transparency (document AI collaboration)
The work is the proof. Every component, every interaction, every line of code demonstrates that human-centered design can be baked into architecture, not just claimed in marketing.
Production Ready (v1.0):
- Design system — Complete with 27 components, 3 themes, comprehensive token system
- Sage Design Studio — Interactive documentation with LLM optimization (Phase 7 complete)
- Portfolio app — Living showcase with Customizer integration
In Active Development:
- Creative Powerup — Experiment gallery (9 live experiments: games, visualizations, animations, tools)
- X-Ray Mode — Toggle exists, UI overlay implementation pending
- AI Notes component — Transparency feature for documenting AI collaboration
Planned:
- Sage Stocks migration — Existing 15k LOC app to be integrated into monorepo
- SageOS — Personal operating system for creative work
- Testing suite — Vitest + Testing Library for comprehensive test coverage
- Additional organisms — Advanced layout patterns and compositions
MIT © Shalom Ormsby
Building something human-centered? Learning from this codebase? Have questions?
Open an issue or start a discussion. This is Generous by Design—the code teaches as it works.
Remember: The best documentation is working code that makes people feel seen, capable, and empowered.