docs: add visual system planning contract

2026-06-12 03:56:22 +08:00
parent e7e4c78865
commit 2e0bf3c784
1 changed files with 147 additions and 0 deletions
@@ -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.