checkpoint: focus seed 1.0.1 localized dev switch

2026-06-11 23:35:49 +08:00
parent c51abdfb73
commit d06dc35ee6
72 changed files with 6155 additions and 1390 deletions
@@ -0,0 +1,57 @@
+# Focus Seed 1.0.1 Architecture
+
+## Decision
+
+Keep the app offline-first and SDK-light. Flutter renders all product UI. `shared_preferences` remains the persistence adapter because the current dataset is one small versioned document and does not require relational queries, pagination, joins, or concurrent writers.
+
+Room is Android-only and would break the iOS-compatible boundary. MMKV adds a native dependency without solving a current bottleneck. If usage grows to hundreds of timeline records or indexed queries, migrate behind `FocusSeedStore` to an embedded cross-platform database without changing feature code.
+
+## Layers
+
+```text
+lib/src/
+  app/          Material theme, ambience integration, app lifecycle
+  application/  User commands and timer lifecycle controllers
+  core/         Pure date and ambience rules
+  data/         Persistence adapters
+  models/       Serializable state and derived domain models
+  features/     Today, Journey, Me, habits, reflection, shell
+  services/     Analytics and monetization interfaces/no-op adapters
+  widgets/      Reusable visual primitives
+```
+
+Rules:
+
+- Widgets render state and forward intent; they do not perform persistence.
+- `FocusSeedController` owns durable product commands and optimistic save rollback.
+- `FocusTimerController` owns only timer lifecycle and absolute-time restoration.
+- `FocusSeedStore` is the only durable app-state boundary.
+- External analytics, ads, billing, and remote configuration remain interfaces with no-op implementations until their SDK, consent, privacy, and policy work is approved together.
+
+## Navigation
+
+Use three top-level destinations:
+
+- Today: intention, timer, habits, reflection, and immediate daily progress.
+- Journey: daily lifecycle, recent sessions, reflections, and seven-day growth.
+- Me: appearance, privacy, import/export, and reset.
+
+Timer, habits, and reflection remain independent modules. They are actions inside the daily workflow instead of equal navigation destinations. This reduces context switching and preserves one primary task per screen. A future usage study may justify configurable shortcuts, but it should not restore five equal tabs by default.
+
+## Performance Contract
+
+- No network, location, background service, broadcast receiver, or foreground service.
+- One timer ticks only while a focus session is active and is disposed with the shell.
+- Background restoration derives remaining time from an absolute end timestamp; no background polling is used.
+- Day ambience schedules one callback at the next phase boundary and refreshes on resume.
+- Growth assets are fixed 640 px transparent PNGs and only transition when the domain stage changes.
+- Timer rebuilds stay inside `FocusSessionCard`; durable state changes rebuild the shell.
+- Long content uses lazy or bounded scrolling. Today shows four habits before offering the full manager.
+- Reduced motion replaces scale transitions with a crossfade.
+
+## Compatibility And Migration
+
+- Existing version 1 JSON loads through `AppState.fromJson` and is saved as version 2.
+- The package name, signing setup, version, permissions, and privacy posture are unchanged.
+- Android is the release target; architecture and dependencies remain compatible with a later iOS build.
+- Release artifacts must pass format, analyze, tests, manifest review, app bundle build, and emulator smoke testing.
@@ -0,0 +1,117 @@
+# Focus Seed Visual Direction 1.0.1
+
+## Decision
+
+Use an editorial botanical interface with premium Soft 3D growth objects and state-driven Material Expressive motion.
+
+The interface remains a mature productivity product. Illustration and 3D are reserved for progress, state, onboarding, empty states, and completion feedback rather than ordinary controls.
+
+## Product Expression
+
+- Core metaphor: intention plants a seed; focus, habits, and reflection grow it.
+- Navigation: Today, Journey, Me.
+- Today expands the current next action and compresses completed or future stages.
+- Journey shows the relationship between daily actions and growth rather than a generic statistics dashboard.
+- Ordinary lists, forms, dialogs, and settings stay compact and familiar.
+
+## Visual Balance
+
+- 72% functional editorial UI
+- 18% Soft 3D state objects
+- 10% botanical illustration, semantic accent, and motion
+
+## Foundation Tokens
+
+- Porcelain: `#F7F8F5`
+- Ink: `#17211C`
+- Leaf: `#4D8B63`
+- Mint: `#A9E8B5`
+- Ultramarine: `#4E63D8`
+- Coral: `#EA725E`
+- Radii: `8`, `12`, `16`
+- Spacing: four-point base with an eight-point layout rhythm
+- Elevation: two restrained levels plus hairline separators
+- Body type: 14-16 logical pixels with compact headings
+
+## Growth States
+
+- Seed: no intention
+- Sprout: intention saved
+- Leaves: focus and habit progress
+- Flower: reflection complete
+
+Every state needs a non-color cue. Reduced-motion mode replaces growth animation with crossfade and an immediate state swap.
+
+## Living Ambience System
+
+Use stable structure with slowly changing ambience. Time must never move controls, change navigation, alter semantic meaning, or reduce contrast.
+
+### Local Time Modes
+
+- Dawn, `05:00-09:59`: cool porcelain, pale sky-mint surface tint, low-stimulation entrance, dew highlight on seed or sprout.
+- Day, `10:00-16:59`: clean porcelain, highest information clarity, leaf and ultramarine accents.
+- Dusk, `17:00-20:59`: restrained coral-lilac tint, softer localized shadows, reflection receives more visual priority when pending.
+- Night, `21:00-04:59`: warm graphite, off-white text, mint primary, muted violet reflection accent, no bright glow.
+
+Determine the mode from the device clock. Do not request location or network access. Re-evaluate on launch, resume, and the next time boundary; never run a background polling loop.
+
+### Priority Order
+
+1. Accessibility and contrast requirements
+2. Explicit user Light, Dark, or System appearance preference
+3. Platform reduced-motion and high-contrast settings
+4. Time ambience within the selected appearance
+5. Product growth state
+
+If the user forces Light or Dark, preserve that appearance and vary only compatible neutral tints and object lighting. System appearance always wins over an automatic day/night surface switch.
+
+### Week And Season
+
+- Weekday/weekend may adjust optional greeting copy and recommended session length, but must not rearrange the interface.
+- Do not infer physical season from month alone for a global audience because hemispheres differ.
+- Offer optional Growth Seasons as cosmetic progression chapters. They are driven by product progress or an explicit user choice, not location.
+- Avoid weather, religious, national, and holiday imagery unless the user explicitly enables a localized pack.
+
+## Motion Contract
+
+- Press response: `120ms`
+- Ordinary state transition: `180-240ms`
+- Growth transformation: `360-480ms`
+- One-time completion celebration: no more than `700ms`
+- Page transition: preserve spatial continuity and remain under `300ms`
+
+Motion events:
+
+- Intention saved: seed rises, settles, and becomes a sprout.
+- Focus starts: progress begins; plant movement is nearly imperceptible.
+- Habit completes: checkbox morphs to a leaf and one leaf unfolds.
+- Reflection saves: flower opens once, then remains still.
+- Background restoration: timer and plant immediately snap to correct data, followed by a short confirmation.
+
+Never run continuous decorative motion. Pause nonessential animation when the app is inactive, during scrolling, under battery-saving conditions, or when reduced motion is enabled. Reduced motion uses crossfade, opacity, and immediate state replacement.
+
+## Variation Budget
+
+- Structure and navigation: `0%` time-based variation
+- Semantic colors and action meaning: `0%` variation
+- Neutral surfaces and background tint: subtle variation only
+- Plant state: driven by real user progress
+- Illustration: reserved for onboarding, empty states, milestones, and completion
+- Copy: may vary by time while preserving the same meaning and action
+
+The goal is recognition with freshness, not novelty on every launch.
+
+## Guardrails
+
+- No childish faces or mascot behavior.
+- No oversized 3D hero or giant timer.
+- No card-per-section dashboard.
+- No decorative illustration without state meaning.
+- No animation that delays input or hides status.
+- Validate long localization, 200% text, dense lists, keyboard, offline restoration, loading, and recoverable errors.
+
+## Visual Reference
+
+See `focus-seed-visual-direction-v1.0.1.png` in this directory.
+
+See `focus-seed-living-ambience-v1.0.1.png` for time modes and motion behavior.