Section 08
Product Design Brief
This chapter defines the product design intent for v1. It translates the frozen product requirements, journey flows, functional specification, and architecture rules into design constraints for UI, Hybrid, API, CLI, and handoff work.
The brief uses the Happy Color app as an interaction reference for clarity, immediacy, and a low-friction tap-to-fill loop. It does not authorise copying Happy Color’s visual identity, catalogue strategy, advertising model, monetisation pressure, or retention mechanics. Ochre & Soul remains a calm, culturally grounded colouring book experience.
8.1 — Authority and source inputs
This chapter is binding for design direction and implementation handoff. If it conflicts with architecture, accessibility, trust-boundary, or v1 freeze rules, the stricter source wins.
| Source | What it contributes |
|---|---|
| /spec/02-product/ | Product positioning, Happy Color lineage, cultural focus, tone of voice, banned copy, and banned UI conventions. |
| /prd/03-user-journey-flows/ | Journey steps and reserved UI IDs for the future UI inventory. |
| /prd/04-v1-feature-set-selection/ | Frozen feature selection, trade-offs, and v1 gates. |
| /prd/06-prd-v1/ | Personas, journeys, requirements, acceptance gates, metrics, risks, and release boundaries. |
| /prd/07-functional-spec-v1/ | Behavioural modules, state transitions, data contracts, command contracts, and error handling. |
| /architecture/01-architecture-decisions/ | System boundaries, approved dependencies, disallowed patterns, and ADR constraints. |
| /spec/12-accessibility/ | Colour-vision, screen-reader, motion, Dynamic Type, and tap-target requirements. |
| /spec/20-open/ | Open design decisions for founder note, starter artwork, and notification pre-permission treatment. |
Design work is complete only when it can be traced back to one of these sources or to an approved Six-Dimension Change Exception in /prd/05-feature-freeze/ §5.5.
8.2 — UX and DX objectives
| Objective | Design requirement | Evidence of success |
|---|---|---|
| Reach value before account or payment | The first session must move from welcome to personalised starter artwork to first satisfying fill without sign-up, payment, or a feature tour. | JRN-P01 completes through first fill with no forced account or paywall surface. |
| Make the core loop self-evident | Numbered palette, visible regions, tap feedback, and progress state must be clear without a tutorial carousel. | A first-time user understands select colour, tap matching region, see picture emerge. |
| Keep the mood calm and culturally specific | Visual hierarchy, motion, copy, and monetisation surfaces must feel closer to an editorial colouring book than a free-to-play game. | No banned copy, countdowns, streaks, daily rewards, badges, or interstitial adverts appear. |
| Make accessibility part of the default canvas | Numbers, contrast, pattern fills, semantics, reduce motion, and forgiving taps are baseline behaviours, not settings-only enhancements. | Accessibility gates in /prd/06-prd-v1/ §6.6 pass before release. |
| Preserve offline confidence | Download, cache, and local progress states must reassure users that downloaded artwork remains playable offline. | Downloaded artwork opens offline and progress continues locally. |
| Support trustworthy cultural presentation | Artwork cards and detail screens must show artist credit, cultural context where approved, and child-safe presentation. | Published artwork has recorded cultural review and required metadata. |
| Make operator tooling predictable | Admin, validator, and CLI surfaces must be deterministic, traceable, and safe by default. | Tooling refuses unsafe partial writes, service-role leakage, and publish without approval. |
8.3 — Product design principles
| Principle | Apply this | Avoid this |
|---|---|---|
| Canvas first | Let the artwork and filling interaction deliver delight. Use UI chrome only where it helps selection, progress, accessibility, or recovery. | Dense dashboards, achievement panels, heavy character mascots, or game HUD patterns. |
| Calm over compulsion | Use gentle prompts, clear choices, and user-controlled return paths. | Urgency, scarcity, countdowns, streak pressure, completion nagging, or repeated interruption. |
| Cultural specificity over generic diversity | Name the artist, theme, tradition, place, or pack. Let the work be particular. | Flattening content into “diverse”, “inclusive”, or token category labels. |
| Try before trust ask | Ask for account, permission, or purchase only after value is visible or when a user action requires it. | Signup walls, permission prompts before explanation, or paywall during welcome. |
| Colour is not the only signal | Pair colour with number labels, contrast, shape, pattern, semantic labels, and clear state text. | Colour-only status badges, colour-only palette selection, or hidden numbers. |
| Designed recovery | Every failure should preserve user work and offer a next step. | Generic “something went wrong” messages, broken playable states, or silent data loss. |
| Developer empathy is product quality | APIs, CLI commands, validation reports, and admin errors should be as designed as user-facing screens. | Ambiguous errors, implicit defaults, hidden side effects, or docs that require source-code reading. |
8.4 — Happy Color inspiration, borrow rules, and avoid rules
Happy Color is useful because its core loop is immediately understood: pick a numbered colour, tap matching spaces, watch the image emerge. Ochre & Soul borrows that legibility and immediacy, then deliberately changes the surrounding product tone.
| Reference behaviour | Borrow for Ochre & Soul | Do not borrow |
|---|---|---|
| Numbered colour palette | Clear swatches, selected state, remaining-region count, completed-colour state, and easy return to active colour. | Palette designs that rely on colour alone, make numbers optional in default play, or hide numbers behind a “premium” toggle. |
| Tap-to-fill feedback | Immediate fill, light haptic where appropriate, gentle wrong-colour feedback, and visible progress. | Loud error sounds, punitive feedback, animation that blocks play, “watch a video to colour this region” gates, or reward explosions on every fill. |
| Image emerges region by region | Let the artwork be the reward. Maintain visible line art and satisfying fill transitions. | Completion-confetti loops, level-up metaphors, streak badges, “daily login reward” framing, or “share your masterpiece for bonus colours” prompts. |
| Low-friction artwork start | Keep first starter route short and guided inside the canvas. | Static feature tour, mandatory account, interstitial video before first artwork open, or paywall before the first satisfying fill. |
| Catalogue clarity | Make free, downloaded, in-progress, completed, and pack-owned states visually distinct. | Cluttered ad-like cards, “limited time” countdown ribbons on packs, dark patterns around paid packs, fake discounts, or generic catalogue walls. |
| Repeatable play pattern | Keep the main interaction consistent across starter, free, and paid pack artwork. | Introducing different controls, ad gates, or pressure mechanics on paid or “premium membership” surfaces. |
The borrowing rule is narrow: borrow the affordance clarity, not the business model. Anything that increases pressure, advertising density, or game-like compulsion fails the product brief even if it resembles a successful colouring app pattern. Concrete examples of patterns to reject: interstitial video adverts between artwork opens, “watch a video to unlock this artwork” gates, daily-streak rewards, “premium membership” upsell prompts, completion-confetti loops, limited-time pack offers with countdowns. None of these may appear in v1.
8.5 — Accessibility and responsive behaviour
Accessibility is a launch quality bar. It cannot be deferred to polish work because the core interaction depends on distinguishing numbered regions, palette state, and completion status.
| Area | v1 design rule | Trace |
|---|---|---|
| Colour vision | Always-show numbers is on by default; numbers carry a high-contrast halo; pattern fills remain available. | /spec/12-accessibility/ §12.1. |
| Palette semantics | Swatches announce colour number, colour name, selected state, and remaining cells. | /spec/12-accessibility/ §12.2. |
| Canvas semantics | Canvas exposes region count and completion percentage. Avoid relying on visual progress alone. | /spec/12-accessibility/ §12.2. |
| Motion | Respect system reduce-motion. Fill transitions become instant or materially calmer when reduce motion is enabled. | /spec/12-accessibility/ §12.3. |
| Dynamic Type | Non-canvas screens support OS font scaling. Canvas number labels scale with artwork zoom. | /spec/12-accessibility/ §12.3. |
| Touch target forgiveness | Small regions are supported by snap-to-nearest behaviour within the specified radius. | /spec/12-accessibility/ §12.4. |
| Error accessibility | Errors must be readable as text, announced by assistive technology where relevant, and paired with a clear recovery action. | /prd/07-functional-spec-v1/ §7.5. |
Responsive design is phone-first for v1. Tablet layouts may be designed when economical, but they must not expand v1 scope unless a release gate explicitly requires them.
| Surface | Phone behaviour | Larger screen behaviour |
|---|---|---|
| Onboarding | Single-column, one decision per screen, visible progress only where useful. | Maintain focus; use extra width for artwork preview or explanatory copy, not additional questions. |
| Library | Vertical feed with continue, chosen-for-you, new, downloaded, and pack sections. | Allow denser card grids while preserving card metadata and touch targets. |
| Artwork detail | Preview-first with clear primary action and artist/cultural context below. | Split preview and metadata only if it improves readability. |
| Canvas | Artwork viewport owns the screen; palette and toolbar stay reachable with one hand where possible. | Wider layout may place palette as side rail if it improves reach and does not reduce canvas legibility. |
| Paywall | Sheet or contained route with one pack story, clear price, restore, and dismiss. | Avoid expanding into comparison-table upsell patterns. |
| Account upgrade | Single-column with provider buttons (Email, Apple, Google) and an explanation of why sign-in is being requested at this moment. | Maintain focus; do not add side content or marketing copy on larger screens. |
| Settings | List-style sections (account, accessibility, preferences, child mode, notifications, restore, support). | Side-rail layout permitted on larger screens; section headers must remain scannable. |
| Notifications (pre-permission) | Full-screen value explanation with one sample notification card and clear opt-in/decline. | Keep focus; the sample card may render larger but the screen must not gain additional CTAs. |
| Restore | Sheet or settings section showing the in-flight state and result (success, no purchases found, store unavailable). | Inherits the host surface’s larger-screen layout — no special responsive behaviour required. |
| Admin preview | Internal-only layout can prioritise diagnostics, validator status, and review controls. | Larger screens may show preview and validator report side by side. |
Open responsive details, including exact breakpoints, portrait or landscape handling, and tablet-specific canvas controls, remain design-system decisions and must be confirmed before UI implementation.
8.6 — UI and Hybrid visual direction
Ochre & Soul should feel like a refined digital colouring book with editorial confidence. The UI should frame the artwork rather than compete with it. Cultural artwork, artist credit, and tactile colouring feedback provide the richness; the interface provides calm structure.
| Dimension | Direction | Constraint |
|---|---|---|
| Visual mood | Warm, polished, joyful, calm, culturally specific. | Avoid default mobile-game gloss, generic wellness minimalism, and loud free-to-play colour noise. |
| Palette | Use a restrained product palette that lets artwork carry the colour. Accent colours should support state and accessibility. “Ochre & Soul” names the brand identity (warm, grounded, culturally specific) — it does not dictate a single chromatic hue. | Do not let the app become one-note beige, orange, brown, or purple. Do not rely on colour alone for meaning. |
| Typography | Editorial, legible, and friendly. Text should feel crafted but must remain readable at scale. | Avoid novelty display fonts for functional UI and avoid cramped mobile type. |
| Motion | Smooth fills, short transitions, and loading states that echo colouring. | No reward explosions, heavy animation, autoplay distraction, or motion that ignores reduce-motion settings. |
| Surfaces | Cards, sheets, and toolbars should feel tactile and stable. | Avoid glassy over-decoration that reduces contrast or distracts from artwork. |
| Imagery | Use approved artwork previews, thumbnails, and cultural detail as the primary visual signal. Any cultural motif used in UI ornament must clear the cultural review gate in /spec/14-culture/ §14.2. | No generic stock diversity imagery. No unreviewed cultural motifs in UI ornament. |
| Monetisation | Paid pack surfaces should explain the pack story and price with restraint. | No countdowns, scarcity messaging, fake discounts, or “unlock” language. |
8.7 — Brand and copy constraints
The tone rules in /spec/02-product/ §2.5 apply to every designed surface, including onboarding, notifications, paywalls, error states, empty states, and admin tooling where user-facing copy may later be adapted.
| Constraint | Design implication |
|---|---|
| No “unlock”, “level up”, “boost”, “supercharge”, “epic”, or urgency copy. | CTAs must use plain action language such as “Start colouring”, “Download”, “Buy pack”, “Restore purchases”, or “Continue”. |
| Avoid “premium content” as a noun phrase to users. | Use named packs, for example “Carnival Queens pack” or “Adinkra Symbols pack”. |
| No streaks, badges, daily rewards, countdowns, or interstitial adverts. | Retention design must use the first-steps checklist and opt-in reminders only. |
| Artist credit and cultural context are trust surfaces. | Artwork detail and pack pages must reserve space for approved credit and context. |
| Child-mode safety is visible but not alarmist. | Restricted actions should explain what is unavailable and how a parent or carer can proceed. |
| Calm error copy is required. | Errors must state what happened, what is preserved, and what the user can do next. |
Example copy patterns:
| Surface | Avoid | Use instead |
|---|---|---|
| Starter CTA | ”Unlock your first masterpiece" | "Start this artwork” |
| Paywall CTA | ”Unlock all premium content now" | "Buy the Carnival Queens pack” |
| Offline error | ”Oops, something went wrong" | "Couldn’t reach the library. Downloaded artwork is still ready to colour.” |
| Restore empty state | ”No premium purchases found" | "We couldn’t find a pack on this account.” |
| Notification sample | ”Hurry, new art just dropped" | "Three new portraits added to your chosen themes.” |
| Child-mode restricted action | ”Action blocked” / “You don’t have permission" | "Purchases need a parent or carer to continue.” |
8.8 — Screen inventory inputs
The UI inventory should replace the reserved UI placeholders in /prd/03-user-journey-flows/ without changing journey IDs. Each screen needs success, loading, empty, error, offline, child-mode, and accessibility states where relevant. The FEAT IDs column lets implementation work trace each screen back to the §02 catalogue and the §06.4 functional rows.
| Screen | Reserved UI ID | FEAT IDs | Primary design job | Required states |
|---|---|---|---|---|
| Animated welcome | UI-ONB-001 | FEAT-ONB-001 | Sell the outcome through an artwork filling itself, not a feature tour. | Default, reduce-motion, loading, continue. |
| Cultural themes | UI-ONB-002 | FEAT-ONB-002 | Let users choose one or more cultural interests. | None selected, selected, validation, reduced motion. |
| Audience | UI-ONB-003 | FEAT-ONB-003 | Capture self, child, or both and explain child-mode implications. | Self, child, both, child-mode explanation. |
| Accessibility quick-set | UI-ONB-004 | FEAT-ONB-004 | Confirm always-show numbers, inherited reduce motion, and optional pattern fills. | Defaults, changed settings, screen-reader labels. |
| Library home | UI-LIB-001 | FEAT-LIB-001 to FEAT-LIB-004, FEAT-RET-001, FEAT-DATA-002, FEAT-API-001 | Show chosen-for-you, continue, featured, new, downloaded, completed, and the first-steps retention checklist. | Fresh, personalised, offline cached, empty, filtered empty, loading, error, checklist-visible, checklist-dismissed. |
| Artwork detail | UI-ART-001 | FEAT-ART-001, FEAT-ART-002, FEAT-DATA-002 | Explain artwork, progress, artist, cultural context, and action state. | Free, downloaded, in progress, completed, paid pack, owned, unavailable. |
| Download state | UI-DL-001 | FEAT-DL-001, FEAT-DL-002, FEAT-CACHE-001, FEAT-CACHE-002, FEAT-NET-001 | Make download, verification, retry, and cache status legible. | Queued, downloading, verifying, failed, expired URL, cached, offline unavailable. |
| Canvas | UI-CAN-001 | FEAT-CAN-001 to FEAT-CAN-004, FEAT-ACC-001 to FEAT-ACC-003, FEAT-DATA-003 | Provide full-screen colouring with zoom, pan, labels, fills, and recovery. | First-tap guide, active play, wrong colour, no hit, completed, reduce motion, offline. |
| Palette | UI-PAL-001 | FEAT-PAL-001, FEAT-PAL-002, FEAT-ACC-002 | Make selected colour, remaining cells, completed colours, and accessibility cues clear. | Selected, unselected, completed, highlighted, pattern-fill mode, screen-reader focus. |
| Founder’s note | UI-NOTE-001 (new — reserve in /prd/03-user-journey-flows/) | FEAT-ONB-007, FEAT-PROG-003, FEAT-PROG-004, FEAT-OPEN-001 | Show the handwritten-feel founder’s note after first completion (or qualifying milestone) and offer the soft account prompt. | First show, dismissed, reduce motion, screen-reader focus, child mode. |
| Pre-permission notification | UI-NOT-001 (new — reserve in /prd/03-user-journey-flows/) | FEAT-ONB-009, FEAT-NOT-001, FEAT-OPEN-003 | Explain the value of new-artwork notifications and show a sample card before the OS prompt fires. | Default, sample shown, opt-in, decline, reduce motion, screen-reader focus, child mode. |
| Paywall | UI-IAP-001 | FEAT-IAP-001 to FEAT-IAP-004, FEAT-DATA-005, FEAT-API-004 | Present named pack value, price, account requirement, purchase, restore, and dismissal. | Anonymous, signed-in, purchase in progress, success, failed validation, restore none, child mode. |
| Account upgrade | UI-ID-001 | FEAT-ID-001 to FEAT-ID-003, FEAT-DATA-001, FEAT-API-003 | Explain sync and purchase account need without blocking non-purchase play. | Email, Apple, Google, existing-account merge, cancelled, failed auth. |
| Settings | UI-SET-001 | FEAT-SET-001 to FEAT-SET-003 | Manage account, themes, accessibility, child mode, notifications, restore, support, and reporting. | Anonymous, signed-in, child mode, offline, restore success, restore failure. |
| Admin preview | UI-ADM-001 | FEAT-CONT-001 to FEAT-CONT-003, FEAT-CULT-001, FEAT-ADMIN-001, FEAT-DATA-006, FEAT-API-005 | Let operators inspect bundle, validator report, review status, and publish controls. | Draft, validation errors, warnings, review requested, approved, rejected, published. |
8.9 — Component inventory inputs
Components should be designed as reusable product primitives, not one-off screen fragments. Each component needs visual states, accessibility semantics, event hooks where applicable, and error or empty behaviour.
| Component | Used by | Design requirements |
|---|---|---|
| Artwork card | Library, pack, continue row | Thumbnail, title, theme, free or pack state, progress, downloaded state, child-safe semantics. |
| Artwork detail header | Artwork detail | Large preview, title, artist credit, cultural context slot, difficulty, estimated time, region count. |
| Theme chip | Onboarding, library filters, settings | Selected, unselected, disabled, multi-select count, accessible label. |
| Audience selector | Onboarding, settings | Self, child, both, child-mode explanation, platform-safe copy. |
| Accessibility toggle row | Onboarding, settings | Always-show numbers, pattern fills, reduce motion state, explanatory helper text. |
| Palette swatch | Palette | Number, colour name, remaining cells, selected state, completed state, pattern-fill indicator. |
| Canvas toolbar | Canvas | Zoom, pan reset, highlight regions, accessibility shortcuts, exit state. |
| Progress indicator | Library, detail, canvas | Percentage, completed count, per-colour progress, accessible text equivalent. |
| Download status | Detail, library | Queued, downloading, verifying, cached, retry, offline-limited. |
| Paywall pack card | Paywall | Pack name, artwork count, representative preview, price, clear purchase action, restore link. |
| Error and recovery banner | Library, detail, download, paywall, admin | Specific error, preserved state, next action, retry or support path. |
| Founder note card | Post-aha flow | Short handwritten-feel note, respectful signature treatment, dismissible, no marketing language. |
| Notification sample card | Pre-permission screen | Theme-aware sample message, opt-in and decline choices before OS prompt. |
| Validator report row | Admin preview, CLI docs | Severity, code, affected asset, actionable fix, docs link. |
| Review status pill | Admin preview | Draft, review requested, changes requested, approved, published, unpublished. |
8.10 — API, CLI, and developer experience design
Developer experience is part of product quality because v1 depends on a reliable content pipeline, safe backend contracts, and repeatable release gates.
| DX principle | API implication | CLI/tooling implication |
|---|---|---|
| Deterministic by default | Same request and auth context should produce predictable response classes. | Commands should avoid hidden mutable defaults and support repeatable validation. |
| Traceable failures | Errors should include stable codes, human-readable messages, and safe hints. | Validator and command failures should identify file, field, rule, and suggested fix. |
| Safe privilege boundaries | Service-role operations stay behind functions and role checks. | Admin tooling must never require service-role keys on a local machine. |
| Machine-readable output | API errors and admin responses should be structured. | Validation should support JSON output for CI and readable output for humans. |
| Dry-run before mutation | Mutating admin actions should expose preflight validation where practical. | Publish, upload, and review commands should support validate or dry-run behaviour. |
| Documentation as interface | Endpoint docs must include auth, request, response, error, and retry guidance. | Command help must be complete enough to run without reading source. |
API documentation UX
Each API or function in /prd/07-functional-spec-v1/ §7.6.2 needs:
| Documentation item | Requirement |
|---|---|
| Purpose | State who calls the endpoint and why it exists. |
| Auth and role | Name anonymous, signed-in, admin, or webhook requirements. |
| Request example | Show minimum valid payload and one realistic payload. |
| Success response | Show shape, important fields, and user-facing consequence. |
| Error taxonomy | List stable error code, HTTP status, retryability, and safe message. |
| Privacy notes | Explain child-mode suppression, receipt redaction, and cultural-note exclusions where relevant. |
| Idempotency and retries | State whether the endpoint is idempotent. Mutating endpoints must document an explicit idempotency-key contract (header name, scope, retention window) or an alternative strategy (e.g. operation-id with state check), not just “retry is safe”. |
| Webhook contract (webhooks only) | For /spec/08-api/ §8.4 receivers (Apple ASSN v2 / Google RTDN, POST /functions/store-notification): signature verification method, payload schema, delivery-retry semantics from the platform, and the response codes that signal accept-and-stop vs ask-the-platform-to-retry. |
CLI documentation UX
Each command in /prd/07-functional-spec-v1/ §7.6.3 needs:
| Documentation item | Requirement |
|---|---|
| Synopsis | One-line command shape with required flags. |
| Inputs | Accepted files, directories, auth context, and environment variables. |
| Outputs | Generated files, database changes, storage paths, report shape, or preview link. |
| Exit codes | 0 success, non-zero failure classes, and CI meaning. |
| Dry-run or validate mode | Available for validation, upload preflight, review request, and publish preflight. |
| JSON mode | Machine-readable output for CI and release-gate evidence. |
| Failure examples | At least one blocking error, one warning, and one permission failure where relevant. |
Error message design
| Audience | Pattern | Example |
|---|---|---|
| User | Plain language, preserved state, next action. | ”Couldn’t verify this download. We removed the partial file, so your saved artwork is safe. Try downloading again.” |
| Parent or carer | Explain restriction without blame. | ”Purchases need a parent or carer to continue.” |
| Content operator | Name the failing asset and fix. | ”regions.bin.br failed validation: region 218 is below the minimum target size. Merge it or mark the warning for review.” |
| Developer | Stable code, hint, docs link. | download.url_expired: signed URL expired during transfer. Request a fresh URL and resume from the last verified byte. |
| Reviewer/admin | State gate and required decision. | ”This artwork cannot publish until cultural review is approved.” |
8.11 — Handoff notes for UI subflows
The first UI handoff should focus on the onboarding-to-first-fill subflow because it is the highest-leverage activation path and exercises the product’s core positioning.
flowchart TD
Brief["Product design brief"] --> Inventory["Screen and component inventory"]
Inventory --> Flow["Onboarding to first fill UI subflow"]
Flow --> States["Success, loading, empty, error, offline, child-mode, accessibility states"]
States --> Specs["Component specs and copy deck"]
Specs --> Build["Implementation-ready UI stories"]
Build --> QA["Accessibility, tone, journey, and release-gate review"]| Subflow | Include in handoff | Acceptance bar |
|---|---|---|
| Onboarding to first fill | Welcome, themes, audience, accessibility quick-set, personalised library reveal, starter artwork, first-tap guide, first satisfying fill, founder note, account prompt. | Completes JRN-P01 without account, payment, or feature tour. |
| Library to cached canvas | Library card, detail, download, verification, cached state, canvas open, offline continuation. | Downloaded artwork opens offline and progress is visibly preserved. |
| Paid pack purchase | Locked artwork, named pack paywall, account requirement, native purchase, server validation, restore, failure recovery. | No entitlement is granted client-side and user copy stays calm. |
| Content operator publish | Validator report, review status, internal preview, publish/unpublish controls. | Publish is blocked without validator pass and cultural approval. |
Handoff package requirements:
- Each screen must carry its reserved UI ID until the final UI inventory replaces it.
- Each component must include default, selected, disabled, loading, error, offline, and accessibility states where applicable.
- Each screen must ship with a copy deck — including empty, loading, error, offline, and child-mode strings — reviewed against the banned-word and banned-pattern list in /spec/02-product/ §2.5 before implementation begins.
- Copy must be checked against the banned-word and banned-pattern list in /spec/02-product/ §2.5.
- All paywall and purchase surfaces must show restore access and avoid urgency or scarcity.
- Canvas, palette, and artwork cards must include non-colour cues and screen-reader semantics.
- Admin and CLI surfaces must include validator error codes, review status, and safe next actions.
- Any design decision that changes v1 scope, release gates, or architecture constraints must go through the Six-Dimension Change Exception process.
8.12 — Traceability matrix
| Design area | Primary source | Required downstream artefact |
|---|---|---|
| Happy Color-inspired core loop | /spec/02-product/ §2.1, /prd/07-functional-spec-v1/ §7.3.3 | Canvas and palette UI spec. |
| Onboarding and first value | /spec/09-user-flows/ §9.7, JRN-P01 | Onboarding-to-first-fill UI subflow. |
| Accessibility baseline | /spec/12-accessibility/, ADR-012 | Accessibility annotations in every relevant screen and component. |
| Offline play and recovery | JRN-P02, JRN-P03, JRN-F04 to JRN-F08 | Download, cache, offline, and sync recovery states. |
| Paid packs | ADR-008, JRN-P04, JRN-F01 to JRN-F03 | Paywall, restore, purchase failure, and entitlement states. |
| Cultural trust | /spec/14-culture/, ADR-009 | Artwork detail, pack detail, admin review, and publish-state designs. |
| Banned UI conventions (cross-cutting) | /spec/02-product/ §2.5 | Negative-pattern review applied to every UI surface during QA. |
| Tone of voice and copy patterns | /spec/02-product/ §2.5, §8.7 of this chapter | Copy deck per screen, banned-words check before implementation. |
| Notifications | /spec/20-open/ OD-07, OD-12; §06.4 Notifications row; §07.2 Notifications module | Pre-permission screen (UI-NOT-001), notification sample component, settings notification controls. |
| Settings and child-mode | /spec/13-observability/ §13.3, JRN-F10, EDGE-002 | Settings IA, child-mode toggle, restricted-action copy, parental-gate behaviour. |
| Developer experience | /prd/07-functional-spec-v1/ §7.6 | API docs, CLI docs, validator report, and admin preview UI. |
| Release gates | /prd/06-prd-v1/ §6.6, /spec/17-phases/ | QA checklist and release-readiness evidence. |
8.13 — Open design decisions
These decisions can shape the UI brief, but they do not authorise scope expansion. The first three rows are formal Open Decisions tracked in /spec/20-open/; the last two are design-system-level concerns that don’t have OD-XX entries and live with the design team until /brand/ lands.
| ID | Type | Decision | Current recommendation | Handoff impact |
|---|---|---|---|---|
| OD-10 | Formal OD in /spec/20-open/ | Founder’s note copy and signature treatment. | Short, warm, signed in the founder’s own handwriting, no marketing language (no “unlock”, “premium experience” — see /spec/02-product/ §2.5). | UI needs a note card component (UI-NOTE-001) with dismiss and accessibility text. |
| OD-11 | Formal OD in /spec/20-open/ | Starter artwork selection. | Mid-complexity portrait or family scene (~300 regions) with broad cultural resonance. | UI needs a starter artwork slot that can accept final artwork late without layout change. |
| OD-12 | Formal OD in /spec/20-open/ | Pre-permission notification treatment. | Theme-aware value screen (UI-NOT-001) with one sample notification card before OS prompt. | UI needs sample notification component and clear decline path. |
| Brand system | Design-system tracked — not in /spec/20-open/ | Palette, type, spacing, and component tokens. | Brand chapters are still pending. | UI work should create provisional tokens and then migrate them into /brand/ when approved. |
| Responsive rules | Design-system tracked — not in /spec/20-open/ | Breakpoints, tablet layout, and orientation behaviour. | Phone-first; tablet enhancement only if scope-neutral. | UI specs must mark any tablet-only behaviour as optional unless release-critical. |
The next public artefact should be the UI inventory or design system foundations chapter. This Product Design Brief is the constraint layer those artefacts must satisfy.