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.