Ulas
ddb8294eff
- BACKLOG: add completed features from v0.7.1 through v0.16.3 (shopping widget, priority none, kanban persistence, meal visibility, currency, custom categories, recipe links, Spanish/FR/TR/RU/EL/ZH locales, settings tabs, CNY/TRY/RUB currencies) - SPEC: add recipe_url field to Meals table (v0.13.0) - SPEC: add shopping_categories table (v0.12.0) - SPEC: fix i18n fallback language from de to en (v0.16.1) - SPEC: update locale file list to include all 10 languages - SPEC: document Settings tab navigation (v0.16.0) - design/system.md: fix priority levels from 4 to 5 (none added v0.9.0)
7.5 KiB
Oikos Design System
Intent
Who: A parent or family member managing their household. They open this at the kitchen table, on the couch, on the phone while grocery shopping. They are juggling meals, tasks, calendars, budgets, and contacts - often simultaneously, often distracted.
What they do: Plan the week's meals. Check what to buy. See what's due today. Track the family budget. Coordinate schedules. Quick in, quick out.
Feel: Like a well-organized family kitchen - warm, practical, never sterile. Things have their place. Not a corporate dashboard, not a developer tool. Closer to a handwritten planner than a spreadsheet.
Domain
Family household management. The physical references: a cork pinboard with notes, the family calendar on the fridge, a grocery list on paper, a budgeting notebook, ceramic tiles and warm wood, natural kitchen light.
Signature
Each module owns a semantic accent color tied to its life domain - not arbitrary, but meaningful. Meals = warm orange (kitchen warmth). Tasks = green (checkmarks, completion). Calendar = violet (time, planning). Budget = teal (financial stability). Notes = gold (pinboard, paper). In standalone/PWA mode, the device status bar shifts color to match the active module.
Palette
Neutrals
Warm-tinted gray scale (not pure gray). Evokes linen, unbleached paper, natural materials. The warmth is subtle - you feel it more than see it.
| Token | Light | Dark | Role |
|---|---|---|---|
--neutral-50 |
#FAFAF8 |
#1A1A18 |
Lowest surface |
--neutral-100 |
#F5F4F1 |
#222220 |
Canvas / background |
--neutral-150 |
#EFEEE9 |
#2A2A28 |
Subtle border, surface-3 |
--neutral-200 |
#E8E7E2 |
#333331 |
Default border |
--neutral-300 |
#D1D0CB |
#48484A |
Disabled text |
--neutral-500 |
#8E8D89 |
#8E8D89 |
Mid-tone (same both modes) |
--neutral-600 |
#6C6B67 |
#AEADB0 |
Secondary text |
--neutral-900 |
#1C1C1A |
#F5F4F1 |
Primary text |
Semantic Aliases
| Token | Value | Role |
|---|---|---|
--color-bg |
neutral-100 |
Page canvas |
--color-surface |
#FFFFFF / #2A2A28 |
Card, modal, dropdown |
--color-surface-2 |
neutral-50 |
Inset, secondary surface |
--color-surface-3 |
neutral-150 |
Tertiary surface |
--color-border |
neutral-200 |
Standard separation |
--color-border-subtle |
neutral-150 |
Softer separation |
Module Accents
Each module has a dedicated color reflecting its life domain:
| Module | Light | Dark | Why |
|---|---|---|---|
| Dashboard | #2563EB |
#60A5FA |
Blue - overview, neutral hub |
| Tasks | #15803D |
#4ADE80 |
Green - completion, progress |
| Calendar | #8250DF |
#A78BFA |
Violet - time, planning |
| Meals | #B45309 |
#F59E0B |
Orange - food, kitchen warmth |
| Shopping | #D4511E |
#FB923C |
Red-orange - action, movement |
| Notes | #BF8700 |
#FCD34D |
Gold - pinboard, paper |
| Contacts | #0969DA |
#60A5FA |
Bold blue - people |
| Budget | #1A7F5A |
#34D399 |
Teal - financial stability |
| Settings | #6E7781 |
#94A3B8 |
Gray - neutral configuration |
Semantic Colors
| Token | Light | Dark | Role |
|---|---|---|---|
--color-success |
#15803D |
#4ADE80 |
Positive states |
--color-warning |
#B45309 |
#F59E0B |
Caution |
--color-danger |
#DC2626 |
#FCA5A5 |
Destructive, errors |
--color-info |
#54AEFF |
- | Informational |
Depth Strategy
Subtle shadows - three levels. No harsh borders for elevation. Borders define edges quietly; shadows provide lift.
| Level | Token | Use |
|---|---|---|
| Resting | --shadow-sm |
Cards, default surfaces |
| Raised | --shadow-md |
Dropdowns, hover states |
| Floating | --shadow-lg |
Modals, FAB, toasts |
Dark mode: stronger shadow opacity to compensate for reduced contrast against dark backgrounds. Borders become more important for definition.
Typography
System font stack (-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto...). Familiar to each platform, zero load time, never feels foreign. A family planner should feel native to the device - not branded.
| Level | Size | Weight | Use |
|---|---|---|---|
| Caption | --text-xs (12px) |
Regular | Badges, nav labels, metadata |
| Small | --text-sm (13px) |
Regular/Medium | Secondary text |
| Body | --text-base (14px) |
Regular | Default content (desktop) |
| Body mobile | --text-md (16px) |
Regular | Default content (mobile), inputs |
| Section title | --text-lg (18px) |
Semibold | Card/section headers |
| Subtitle | --text-xl (20px) |
Semibold | Page subtitles |
| Page title | --text-2xl (24px) |
Bold | Page headers |
| Hero | --text-4xl (36px) |
Bold | Dashboard greeting |
Spacing
4px base grid. Consistent across all components.
| Token | Value | Use |
|---|---|---|
--space-1 |
4px | Icon gaps, micro spacing |
--space-2 |
8px | Tight component padding |
--space-3 |
12px | Standard component padding |
--space-4 |
16px | Card padding, section gaps |
--space-6 |
24px | Section spacing |
--space-8 |
32px | Major separation |
Border Radius
Friendly but not bubbly. Cards are rounded enough to feel approachable, inputs slightly less.
| Token | Value | Use |
|---|---|---|
--radius-xs |
4px | Small badges, pills |
--radius-sm |
8px | Inputs, buttons |
--radius-md |
12px | Cards, dropdowns |
--radius-lg |
16px | Modals, large cards |
--radius-xl |
24px | Feature panels |
--radius-full |
9999px | Avatars, toggles |
Layout
Mobile (< 1024px)
- Bottom navigation bar with swipeable two-page layout (5 modules per page)
- Dot indicator for current nav page
- Content area scrolls above fixed bottom nav
Desktop (1024-1279px)
- Collapsed sidebar (56px) with icon-only navigation
- Content fills remaining width
Wide Desktop (1280px+)
- Expanded sidebar (220px) with icons and labels
- Content max-width: 1280px
Navigation
- Sidebar and canvas share the same background color (separated by border, not color)
- Active module indicated via
aria-current="page"and accent color
Transitions
| Speed | Duration | Use |
|---|---|---|
| Fast | 150ms | Micro-interactions, hover |
| Base | 250ms | Standard transitions |
| Slow | 400ms | Page transitions, modals |
Easing: cubic-bezier(0.16, 1, 0.3, 1) for out-expo (page slides), cubic-bezier(0.4, 0, 0.2, 1) for standard ease-in-out.
Dark Mode
Inverted warm neutrals (not cold). Surfaces get slightly lighter at higher elevation. Semantic colors shift to lighter/less saturated variants for readability on dark backgrounds. Shadows increase in opacity. Module accents shift to lighter variants.
Two triggers: prefers-color-scheme: dark (system) or data-theme="dark" (manual override). data-theme="light" forces light mode.
Patterns to Preserve
- Skeleton loading: Cards show pulsing skeleton placeholders while data loads, then swap to real content
- Module-specific CSS: Each page has its own stylesheet loaded dynamically - keeps initial bundle minimal
- Page transitions: Directional slide animations based on navigation order (left/right)
- Glass overlays:
rgba(255, 255, 255, 0.18)surfaces for elements on colored backgrounds (e.g., action buttons on module headers) - Priority system: Five levels (none/low/medium/high/urgent) with dedicated color + translucent background tokens. "None" is the default for new tasks and hides the priority badge entirely.
- Swipe gestures: Touch-friendly item interactions (swipe to delete/complete) on mobile