MOB-04 — Flutter design system — tokens, theme, components
hoco_ui: Akram's tokens as ThemeData + ThemeExtensions, typography, the mobile component library and a widget gallery app for design QA.
| Field | Details |
|---|---|
| Task code | MOB-04 |
| Phase | P0 — Foundations (cadrage, UX/UI, architecture & contract) |
| Product scope | V1 |
| Status | Planned |
| Start | Wed 21 Oct 2026 |
| Due | Sun 25 Oct 2026 |
| Responsible | Imad — Mobile developer (Flutter) |
| Co-responsible | — |
| Effort | 2.5 person-day(s) planned · 8 from scratch · size M |
| Area · app | Mobile foundation · mobile |
| Depends on | DES-03, MOB-01 |
| Unblocks | MOB-05 |
| Milestones | — |
Summary
hoco_ui: Akram's tokens as ThemeData + ThemeExtensions, typography, the mobile component library and a widget gallery app for design QA.
Description
Akram designs every mobile screen on one component library (DES-03), and the Flutter apps must reproduce it exactly so design QA checks screens rather than re-litigating buttons. Scope: hoco_ui with tokens generated from Akram's Claude Design tokens (the exported token file), ThemeData plus ThemeExtensions, typography, the full mobile component set (inputs, steppers, chips, status badges, product/order/visit/KPI cards, list rows, app bars, bottom nav, tabs, sheets, dialogs, snackbars, skeletons, empty/error states) and a widget gallery Akram can install. Business logic and screens are out of scope. It needs DES-01…03 from Akram (tokens export, components, icons, font files) and no server work. Components bake in two product rules: availability is a pill without quantities (STK-07) and a price can be locked for guests (AUTH-10). Every screen task builds on this package and DQA reviews start from the gallery.
Subtasks
| # | Subtask | Owner |
|---|---|---|
| 1 | Token pipeline: token file exported from Claude Design (JSON) → tool/gen_tokens.dart → colors, spacing scale, radii, elevation and typography as generated Dart | Imad |
| 2 | HocoTheme (ThemeData + ThemeExtension<HocoColors>, <HocoStatusTones>) with a high-contrast variant for the delegate app's outdoor use, agreed with Akram | Imad |
| 3 | Bundle the DES-01 font family with an Arabic-capable fallback; TextTheme mapping and a text-scale clamp (1.0–1.3) | Imad |
| 4 | Inputs: HocoButton (primary, secondary, ghost, destructive, loading), HocoTextField, HocoPhoneField (+213), HocoPasswordField, HocoOtpField (6 digits), HocoSearchablePicker (wilaya/commune), HocoQuantityStepper (min, step, max) | Imad |
| 5 | Display: HocoStatusBadge driven by enum tone, AvailabilityPill taking only StockAvailability (« En stock » / « En rupture »), PriceText (HT/TTC, promo strike-through, locked state « Créez un compte pour voir les prix »), ProductCard, OrderCard with progress tracker, VisitCard, KpiTile, ListRow | Imad |
| 6 | Containers and feedback: HocoAppBar, HocoBottomNav with badges, HocoTabs, HocoBottomSheet, HocoDialog, HocoSnackbar, skeleton loaders, EmptyState, ErrorState (retry + requestId), OfflineBanner, SyncStatusPill (synced / pending / error) | Imad |
| 7 | Icon set exported by Akram as SVG (flutter_svg) or an icon font, with semantic labels | Imad |
| 8 | Widget gallery app (packages/hoco_ui/example or Widgetbook) built as an APK by CI for design QA | Imad |
| 9 | Design QA pass on the gallery against DES-03 with written findings | Akram |
| 10 | Golden tests for every component in default, disabled, error and loading states, LTR and RTL | Imad |
Deliverables
- packages/hoco_ui/lib/src/tokens/ (generated), theme/, components/
- packages/hoco_ui/example gallery app and its CI APK artifact
- packages/hoco_ui/test/goldens/ baseline images
Acceptance criteria
- Every DES-03 component exists in hoco_ui under the Claude Design name and is shown in the gallery
- Tokens regenerate from a new Claude Design token export with one command and no hand edits
- Touch targets are at least 48 dp and text/background token pairs reach 4.5:1 contrast (NFR-07)
- AvailabilityPill has no quantity parameter; PriceText renders the lock state when the price is null
- Akram signs off the gallery with no blocking finding
Requirements covered
| Requirement | Title | Release |
|---|---|---|
| NFR-07 | Accessibility: readable contrast, reachable buttons, consistent text sizes, explicit messages | V1 |
Test measures
- Golden tests (alchemist or golden_toolkit) per component, LTR and RTL, run on the Linux CI runner with bundled fonts
- Widget tests of HocoQuantityStepper bounds (min, step, max) and HocoOtpField paste handling
- Unit test computing contrast ratios of the token pairs used for text
Risks
- DES-03 changes after implementation — build tokens first and keep component APIs stable so visual changes are token edits; weekly 30-minute sync with Akram
- Golden images differ between developer machines and CI — generate and compare goldens on CI only
KPI
- Delivered by Sun 25 Oct 2026 within 2.5 person-day(s).
- Every acceptance criterion above demonstrated before hand-off; linked requirements' acceptance criteria pass.
- Zero open critical defects, permission gaps or data-integrity regressions at sign-off.
Generated from content/plan/tasks.json by scripts/generate-team-tasks.mjs. Dates are computed by the scheduler (Sunday–Thursday weeks, holidays excluded) — change the plan, not this page.
MOB-07 — Localisation & formatting
ARB files (fr now; ar and en scaffolded), RTL-safe layouts, DZD money and date formatting helpers.
MOB-03 — API client from the OpenAPI contract + mock server workflow
hoco_api generated from openapi.json (models + dio client), regeneration script, Prism mock server for local development, contract version pinned.