From 2e0bf3c7842a53e92410eae1b712fce2bdcd6f26 Mon Sep 17 00:00:00 2001 From: leavy Date: Fri, 12 Jun 2026 03:56:22 +0800 Subject: [PATCH] docs: add visual system planning contract --- .../design/focus-seed-visual-system-v1.0.2.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/design/focus-seed-visual-system-v1.0.2.md diff --git a/docs/design/focus-seed-visual-system-v1.0.2.md b/docs/design/focus-seed-visual-system-v1.0.2.md new file mode 100644 index 0000000..8bec3f4 --- /dev/null +++ b/docs/design/focus-seed-visual-system-v1.0.2.md @@ -0,0 +1,147 @@ +# Focus Seed Visual System v1.0.2 + +Status: planning contract. Do not treat this document as an implementation diff. + +## Product Thesis + +Focus Seed is an offline-first personal focus companion. It helps users choose one important thing, complete focused sessions, keep daily habits, write a short reflection, and review visible progress. + +The product should not be plant-only. "Seed" means intention, momentum, craft, discipline, and progress. Plant visuals are allowed only as one mature motif, mostly for growth, empty states, or reward moments. + +## Recommended Direction + +Use a hybrid direction: + +- Base: Editorial Focus Companion. +- Structure: Soft Bento Productivity. +- Focus mode: Precision Dark as an optional immersive screen language. +- Warmth: Light editorial or tactile illustration for empty states, rewards, and growth. + +Working name: Calm Modular Editorial. + +This direction is global-friendly, feasible in Flutter, serious enough for productivity users, warm enough for retention, and flexible enough for future subscription features. + +## Primary Product Loop + +1. Pick today's main focus. +2. Start or continue a focus session. +3. Complete daily habits. +4. Write one short reflection. +5. Review growth and adjust tomorrow. + +## Target App Structure + +Preferred primary navigation: + +- Today: daily action hub. +- Focus: immersive timer and active session. +- Habits: habit list, completion, weekly rhythm. +- Growth: reflection, history, trends, milestones. + +Settings should move behind a top-right profile/settings entry or a More sheet. It should not compete with the daily loop unless account, billing, or preferences become a core product surface. + +## Screen Hierarchy + +| Screen | User goal | First visible content | Primary action | Secondary content | Scroll behavior | +| --- | --- | --- | --- | --- | --- | +| Today | Know what to do now | Date, greeting, main focus | Start focus or set focus | Habit summary, reflection prompt, small growth cue | Natural vertical scroll; P0 remains near top | +| Focus | Stay in one session | Current task and timer | Pause/complete/start | Duration, mode, next break, session stats | Minimal scroll; controls stable | +| Habits | Complete and manage habits | Today progress and filters | Toggle habit / add habit | Weekly dots, streaks, edit/reorder | Dense list; sticky section controls optional | +| Growth | Understand progress | Reflection entry or weekly summary | Reflect today / view timeline | Sessions, habits, records, trend charts | Timeline + cards; history can go to detail | +| Settings | Adjust app and privacy | Local data, appearance, language | Change preference | Privacy, clear data, version | Compact grouped list | + +## Visual System + +Palette: + +- Primary: mature green or teal for progress and focus. +- Secondary: restrained blue/violet for reflection or insight. +- Warm neutral surfaces instead of pure white where appropriate. +- Semantic colors for success, warning, destructive, disabled, offline. +- Dark mode must be designed, not inverted. + +Typography: + +- Use highly readable system UI for body and dense data. +- Optional expressive display style only for brand/page title, not dense content. +- Timer and stats need tabular, stable numeric rendering. + +Spacing and surfaces: + +- Use an 8 px base rhythm with 4 px fine adjustments. +- Cards should have roles: hero, action, stat, list container, warning, reward. +- Avoid stacking identical large rounded cards. +- Prefer compact rows for dense data. + +Motifs: + +- Focus ring, anchor point, path, window/light, notebook, timeline, gentle growth. +- Use illustration in empty states, onboarding, growth, and rewards. +- Do not decorate every card. + +## Interaction And Motion + +Motion budget: + +- 80% functional feedback: press, select, save, toggle. +- 15% spatial motion: tab/page/sheet/list transitions. +- 5% reward: session complete, streak, milestone. + +Required behavior: + +- Tap feedback within 100 ms. +- Page transitions preserve direction. +- Timer updates must not rebuild entire pages. +- Completion should be rewarding but non-blocking. +- Reduced motion must disable decorative effects. +- Bottom tabs preserve state and scroll position. + +## Component System + +Create or consolidate: + +- AppScaffold and AppTopBar. +- AppNavigation. +- AppButton variants. +- AppCard role variants. +- SectionHeader. +- CompactStatCard. +- DenseListRow. +- HabitRow. +- TimelineItem. +- EditableTextCard. +- EmptyState and ErrorState. +- OfflineBadge and SaveStateIndicator. +- AnimatedNumber, AnimatedProgressBar, AnimatedProgressRing. +- RewardMoment. + +## Content Rules + +- English-first for release; Chinese supported for development/testing. +- Visible text must be user-facing, not developer-facing. +- Avoid words like JSON, debug, select result, internal, export/import unless a real user feature needs them. +- Empty states should guide one action. +- Destructive actions must state impact clearly. + +## Flutter Execution Plan + +1. Create design, component, and motion foundations. +2. Prototype Today and Focus first; review screenshots and interaction. +3. Add the Habits screen as a real first-class surface. +4. Rework Growth into reflection plus progress timeline. +5. Move Settings out of primary navigation or make it compact. +6. Add empty/dense/error/offline/restored states. +7. Verify light/dark, English/Chinese, small phone, large text. +8. Build and test Android release after each large module. + +## Risk Notes + +- Navigation changes can affect user familiarity; do it on a development branch, not the already submitted release. +- More visual richness can reduce performance if blur/shadow/ambient animation is overused. +- Too much plant imagery may feel childish or narrow. +- Too much bento/card structure may look generic. +- Too much dark precision may feel cold. + +## Decision For v1.0.2 + +Use Calm Modular Editorial unless the user chooses a stronger expressive direction. Start with Today and Focus because they define whether the product feels real.