Design workflow & handoff

This page is the working agreement between Akram (design), Imad (Flutter apps) and Anis (server, back-office, reseller web). It applies from Day 1 of the design plan to the last design QA.

V1 fits in three months, design to deployment, so handoff is incremental. Each app's frames reach Ready for dev at its client checkpoint, because Imad starts building the reseller app while the back-office is still being designed. Design handoff complete (Day 21) closes the V1 design; it is not the first moment developers see a frame.

Project structureCopy Anchor Link

One Claude Design project, HOCO B2B — Design, shared by link with Anis and Imad (they take the handoff from it) and with HOCO (view and comment, through share links per checkpoint).

Rules:

• Components live only on the two component pages. Screens contain instances, never detached copies. Detaching a component needs a written reason in an annotation.
• Every colour, radius, spacing and text style is bound to a token or style. A raw hex value in a screen is a defect.
• One shared mock data set is used in every frame: one store (Bazar du Centre, REV-000123, Oran, Demi-gros), one delegate, one tour, a few orders. It is consistent across frames and in the canonical formats.
• If the project gets too large (several hundred frames with states), split it into a design-system project (Foundations plus Components) and a product project. The page names stay the same.

Frame namingCopy Anchor Link

Format: SCREEN-ID · Screen name · state, for example RA-18 · Checkout · default.

• SCREEN-ID and Screen name are exactly as in screens.json (English name).
• state is kebab-case, from this vocabulary:

Components use Family/Component with variant properties named like the code parameters: Commerce/Price block, with variant=card|detail|promo|total, state=default|locked. Layers that carry data are named after the field they show (price, availability, orderNumber), so annotations and the handoff read the same.

Design statusesCopy Anchor Link

How it shows in Claude Design:

• A status badge component (variants per status) sits at the top left of every section.
• For developers, only Ready for dev sections go into the exported design bundle of a handoff.
• A frame changed after Ready for dev carries a Changed badge with the change-request id and date, and the section returns to Ready for dev.

When each app reaches Ready for dev. The reseller app after checkpoint 3 (Reseller app designs ready for client review); the delegate app after checkpoint 4; the back-office after checkpoint 5; the reseller web after the Day-21 presentation, because WEB-01 starts once the back-office foundation exists. The build tasks are scheduled after these points in the Gantt. A frame that a developer needs earlier, such as the Day-6 onboarding for MOB-06, goes Ready for dev after the feasibility check, with HOCO's asynchronous look recorded.

Annotation conventionsCopy Anchor Link

Annotations use the annotation kit on Foundations. Each one starts with a prefix, so its meaning never depends on its colour.

Every screen frame has at least STATE, DATA and COPY. Every interactive element has an ACTION the first time it appears in a flow.

Using the handoffCopy Anchor Link

• Access. Akram shares the Claude Design project with Imad and Anis by link. The handoff is the shared link plus the exported design bundle and the token file (hoco.tokens.json).
• Filter on Ready for dev. Never build from a WIP or Client review frame. If a needed frame is not ready, ask in the team channel; the 15-minute check exists for exactly this.
• Read tokens, not values. Bound tokens are named (color/status/success/bg, space/4) in the handoff and in the token file. Use the token, not the hex.
• Units. Mobile frames are drawn at 360 × 800, so 1 px in the design = 1 dp in Flutter. Web frames are drawn at 1x CSS pixels.
• Compare changes. The Changed badge and the changelog on the Cover show what moved since a frame was marked Ready for dev. Use them together with the change request that caused the change.
• Component names are the link between the design and @hoco/ui / hoco_ui. The exported design bundle can be handed to Claude Code as a starting point, but the build always uses the existing library components.

Assets exportCopy Anchor Link

Akram sets the export settings in Claude Design and delivers the exports as one archive per release. The consuming developer commits them; Akram does not need repository access.

Tokens release processCopy Anchor Link

1. Change. Akram edits the tokens in Claude Design on Foundations. Values that are already released are never changed silently.
2. Export hoco.tokens.json (W3C DTCG format; see token delivery) and write the changelog entry on the Cover page.
3. Web. Anis commits the JSON to AnisBetehi/hoco with a Conventional Commit (chore(ui): design tokens v1.0). The build regenerates the @hoco/ui CSS variables. The release is tagged tokens-v1.0.0.
4. Mobile. Imad copies the same JSON into hoco-mobile, regenerates the Dart ThemeExtensions and commits (chore(ui): design tokens v1.0).
5. Check. A visual pass in Imad's widget gallery app (MOB-04) and on one back-office page. Akram confirms.

## tokens v1.1 — <date>
Changed: color.status.warning.fg  #B45309 → #A84C08  (contrast on new pill background)
Added:   color.whatsapp           #128C7E
Reason:  CR-014 (HOCO feedback, checkpoint 6)
Impact:  status pills (all apps); WhatsApp button (RA, RW)

Handoff checklist (Day 21)Copy Anchor Link

• Every V1 frame is Approved or Client review with its open items listed. No V1 frame is WIP.
• Every frame name follows ID · Name · state, and the states listed on the screen pages exist as frames or as STATE annotations.
• No detached components; no raw hex, radius or font values (checked in the consistency pass).
• STATE, DATA and COPY annotations on every screen frame; DECISION stickers link the decision register.
• Prototypes work end to end: reseller ordering, delegate visit day.
• Tokens v1.0 exported; changelog written; the commits are planned with Anis and Imad.
• Assets exported (custom icons, illustrations, placeholders), with app icons and splash drafts for DQA-01.
• The client presentation is held and its feedback recorded for DES-22.
• A 1-hour handoff walkthrough with Imad and Anis: questions answered or turned into change requests.

Change requests after handoffCopy Anchor Link

A frame that is Ready for dev or later changes only through a change request (CR). This covers HOCO feedback after a checkpoint, a design QA finding that needs a design decision, or a developer's proposal.

1. Raise. Open an issue in the repository of the affected app: hoco-mobile for RA and DA, AnisBetehi/hoco for BO and RW, label design-change. The title is [RA-18] Afficher le crédit disponible au-dessus des méthodes de paiement. The issue gives the screen ids, the reason, who asked, and a link to the frame (node link). HOCO's requests reach it through Anis.
2. Triage by Anis, within one working day:
   • accept, reject, or move to V2;
   • size it: S (copy or visual tweak, under an hour of design), M (a new state or component variant, up to a day), L (a new screen, flow or rule);
   • check the plan impact. L requests change the scope: they need HOCO's written approval (the cahier's scope clause) and a plan update in tasks.json.
3. Design. Akram changes the frames and adds a changelog row on the Cover, with the CR id, the date and the frames. The changed frames get the Changed badge; superseded versions move to Archive.
4. Docs. The screen's page on this site is updated in the same week. The screen pages are the written spec developers read.
5. Task. The CR becomes a task: an update of the existing build task if it is not done, or a new fix task. It links the issue and the Claude Design frame.
6. Build and QA. The developer implements the change and links the pull request to the issue; Akram checks it in the next design QA.

Rules:

• A design change announced only in chat, by voice, or as a screenshot is not a change.
• A comment on the shared design becomes a CR only when someone opens the issue.
• Frames In dev are never edited without a CR.

Design QA procedureCopy Anchor Link

Devices and settings. Staging builds. One mid-range Android phone (about 6.5 inches, 1080p, a recent Android version), one 360-dp-wide phone, and both at 130 % text size; the delegate app also outdoors at full brightness. Web: Chrome at 1440, 1280, 1920 and 1024 × 768, plus a phone width for the reseller web.

Checklist (screen by screen, against the Ready for dev frames)

Evidence. Each issue has a screenshot or a screen recording next to the Claude Design frame link, the device and build number, and the steps to reproduce.

Severity

Where issues go. GitHub issues in the app's repository (hoco-mobile or AnisBetehi/hoco), with the labels design-qa and S1…S4, and the screen id in the title ([DA-08] Bouton « Je suis arrivé » actif hors tolérance). Assumption: GitHub Issues is the tracker; Anis confirms.

Exit. The DQA task is done when no S1 or S2 issue is open on its scope and the S3 issues have an owner. Akram then marks the sections Design QA passed. Fixed S1 and S2 issues are re-checked on the next build.

ResponsibilitiesCopy Anchor Link