Coffee Kit: UX, source assets and design handoff

Research date: 12 November 2026. Scope: source inspection, supplied screenshot review, Mobbin references and a bounded read-only Coffeetale storefront check. No theme edits, app implementation, merchant mutations, checkout, or outreach.

Product direction

Design Coffee Kit as a coherent coffee-selling workspace: bring in a coffee, review its facts, choose how it is sold, preview the complete shopper experience, and maintain that experience as the catalog changes. The north star is the founder's replacement-worthy “#1 solution for selling coffee on Shopify.” That is a positioning ambition, not a verified market claim.

The current source provides a substantial storefront foundation. It does not provide the Coffee Kit admin, extraction/review system, subscription engine, provider integrations, loyalty ledger, or agency API. The commercially meaningful product work is connecting those storefront components to a dependable shared workflow. Assisted migration by a salesperson or AI can be a legitimate onboarding route; the ongoing result should be one manageable system, with explicit ownership of data and subscription operations.

For the first wireframes, show one complete journey from source document to a sellable coffee and subscription offer. Show existing source assets accurately. Label proposed backend actions and simulated outcomes. Do not present a subscription concept screenshot as working billing.

Evidence and reproducibility

Evidence labels: Source means actual code inspected; Live means a specific browser observation; Visual means a supplied image or Mobbin image actually viewed; Proposal means a design recommendation. None of these establish conversion uplift, demand, price acceptance, or cross-theme compatibility.

Recovered the prior thread with read_thread(includeOutputs: true). Its returned history was truncated and preserved the finding about helper-section dependencies and reference candidates. The report checks those against accessible files and viewed images instead of treating the recovered commentary as complete evidence.

Read the founder brief, relevant current sections of both context dossiers, existing study notes, theme workspace rules (local handoff artifact), Coffeetale agent guide (local handoff artifact), design contract (local handoff artifact), Hydra child-theme rules and the latest available daily theme log. The actual build takes precedence over a shorthand capability description in a historical brief.

Repository snapshot, all clean at inspection:

The source manifest (local handoff artifact) records 41 entry points, hashes, source filename candidates, direct literal dependencies and repository states. It is not a complete graph of dynamically selected blocks. The old .source-map.json predates this study; its mapping was not treated as current proof. The inventory script (local handoff artifact) reads source and produces contact sheets without modifying themes. It requires Pillow; the research run used an isolated temporary Python environment.

All 14 Coffeetale concept images and 21 representative supplied subscription screenshots were viewed in seven generated contact sheets. The screenshot manifest (local handoff artifact) identifies every original, dimensions and contact-sheet cell. Fine copy and transactional behavior are not inferred from thumbnail-sized text. Mobbin references below were also actually viewed; nine useful full-resolution files were downloaded to the reference folder (local handoff artifact).

Live check and its boundary

Used the existing local Playwright runtime and cached Chromium. The installed runtime initially expected a newer uncached browser; explicitly selecting cached Chromium 1248 resolved that. The password was used only to open a storefront session. The inspection script (local handoff artifact), browser observations (local handoff artifact), and captured screenshots (local handoff artifact) are retained.

The guessed /pages/quiz and /pages/brew-guide routes returned 404. The actual navigation uses the longer routes above; those 404s are not evidence of missing quiz or brew-guide functionality. No cart-add, payment, checkout, renewal, portal management, admin editing, accessibility audit, performance benchmark, mobile QA or external-theme installation was performed. Lack of a selling-plan input on these pages does not prove that the store has no subscription app elsewhere.

Useful live captures for the website: collection, profile finder, selected mood, open quick buy, brew guides, PDP, and completed quiz. Page captures use a 1440 × 1100 viewport; the quiz-result capture is cropped to its actual component. Crop for presentation without claiming to show untested commerce.

Existing code versus product work still needed

Paths below are relative to LOCAL/themes/FLAT-WHITE/build/ unless another root is given. Build files are evidence of delivered output, not files to edit. Future implementation belongs in the child _dev or the owning framework source.

“Implemented in source” and “verified live” remain separate. For example, a dialog's focus-handling code exists, but this study did not complete keyboard or assistive-technology testing.

Exact dependency map and portability implications

Shared presentation and commerce

The theme shell (local handoff artifact) renders head-variables, loads theme CSS and supplies shared assets. Head variables (local handoff artifact) supplies the product-form script registry entry, routes, settings, typography and CSS variables. Components call window.KROWN.loadScript or loadScripts. This is an actual runtime dependency.

Product card block
  -> content_for blocks (merchant composition)
  -> card snippet -> color tokens, language direction, image/video helpers
  -> product-card CSS + global typography/layout/token CSS
  -> child origin / notes / scale / chart / price / quick-buy blocks

Quick-buy block
  -> quick-buy-popover snippet
  -> component-quick-buy-popover.js (loaded once by theme.liquid)
  -> GET product URL ?section_id=helper-quick-buy
  -> helper-quick-buy -> product-variant-options
  -> product-variants + product-form + quantity-selector custom elements
  -> GET helper-product-variant when options change
  -> shared component-product-form.js
  -> Shopify cart endpoint + Krown cart refresh/drawer events

The quick-buy script (local handoff artifact) caches fetched helper bodies, preloads in-view cards under favorable connection conditions and loads shared scripts. It also uses Krown settings/events to show the cart sidebar. A single-variant product takes the direct form branch; a multi-variant product opens the helper-backed panel. Neither branch by itself selects a subscription plan.

The shared product-form source (local handoff artifact) serializes the form, posts to the configured cart URL and requests cart helper sections where appropriate. Variant changes use Krown events and helper rendering. Do not extract only the visible buttons and assume these behaviors travel with them.

Finder and quiz

Quiz section -> _quiz-card -> intro, progress, questions/answers, results view
  -> component-quiz.js
  -> tag route -> quiz-results-ids (first 50 products)
  -> ranked IDs -> search route -> quiz-results (first 24 results)
  -> quiz-product-card -> image, video, badges, price, card, quick-buy-popover
  -> quick-buy dependency chain above

Profile-finder section
  -> _profile-finder reads selected collection + numeric metafield keys
  -> radar-chart SVG + JSON product vectors
  -> component-chart-filter.js + component-profile-finder.js
  -> exact level matches, otherwise nearest profiles
  -> search route ?section_id=quiz-results&type=product&q=id:...
  -> quiz-product-card and quick-buy dependency chains

Source correction: the agent guide describes tag matching as AND across questions/OR within a question. Actual code supports both explicit product mappings and tags, configurable AND/OR behavior, and a closest-match fallback. In the ranking function (local handoff artifact), AND keeps the IDs matching the greatest number of questions; if no product matches every question, partial matches can remain. The UI must distinguish “matches all your choices” from “closest available.” Do not advertise strict filtering without reconciling this behavior.

The tag ID helper paginates by 50 (local handoff artifact); the result renderer paginates by 24 (local handoff artifact). This is a bounded candidate set, not proof of catalog-wide exhaustive ranking. Unknown-tag handling checks the tags Shopify actually applied so that an invalid tag does not silently become an unfiltered result.

The profile finder reads up to a 250-product page (local handoff artifact), requires at least three configured axes, skips a product missing any selected numeric axis, and clamps numbers to the configured range. It accepts direct namespace.key and one nested metaobject-field path. It does not create the source values. The JS tries exact categorical levels before distance fallback (local handoff artifact). Source has separate empty, error and closest-match UI. An import tool must not invent scores to make more products eligible.

Recipe presentation

Brew-guide section -> _brew-methods -> _brew-method -> _brew-step
  -> tabs component + tabs/brew-guide/timeline CSS
  -> theme typography, color tokens and icons

The methods parent (local handoff artifact) loads component-tabs. The step block prints the supplied time/title/text. No dedicated elapsed brew timer, pause/reset controller or automatic step progression was established in the inspected recipe code. Generic countdown blocks elsewhere do not prove that the Figma stopwatch exists.

Delivery decision

Proposal: retain two supported delivery modes behind one experience configuration: compatible Coffeetale reuses its native components through an explicit version/capability contract; another supported theme gets scoped Coffee Kit renderers and its own minimal runtime. The same coffee, matching rules and offer should survive a presentation change.

Theme app extensions provide blocks, embeds, snippets and assets. They do not package arbitrary theme helper sections as though they already existed in every host. Replacing every native product card is also a separate adapter problem. Use app-owned grids, quiz results and subscription-builder surfaces as the first reliable card placements. Shopify extension structure and constraints.

The current helper URL architecture needs deliberate replacement or a tested supported-theme dependency. Section Rendering renders existing theme sections and cannot receive arbitrary new setting values. A proposed portable renderer must specify where the markup comes from and how selected variant, availability, price and plan stay authoritative. Shopify Section Rendering API.

Actual data bindings to preserve

The agent guide describes standard attribute support; the checked demo templates demonstrate richer custom bindings. Do not collapse these into a single unverified schema.

Direct examples: PDP template (local handoff artifact), profile-finder template (local handoff artifact), homepage card (local handoff artifact). These store-specific templates contain bindings even though the distribution guide says shipping presets should omit store bindings. Treat them as inspected demo configuration, not universal installation defaults.

Source renderers also support shopify.flavor and shopify.country through product-metafield-values. Audit existing definitions and offer “use existing,” “copy once,” or “managed mapping” with a conflict policy. The proposed coffee_kit namespace in the data study is not the existing Coffeetale schema. Refer to data/discoverability report for ownership and persistence decisions; data accessibility and continued operation of paid UI after uninstall are separate promises.

Viewed supplied visuals

The screenshots contain design comments and sample data. Use them for layout and design provenance, with captions. They are not evidence of subscriptions being charged or recipes/data being verified.

Supplied roaster subscription references

These observations come from the supplied screenshots, not fresh tests of those brands. Exact originals are indexed in the screenshot manifest. Representative endpoints were viewed for all 14 supplied folders; intervening steps, backend providers and renewals were not audited.

Proposal: support a direct fixed-coffee route and a curated rotating-club route in the architecture. A mixed box, prepaid gift, office contract and personalized rotating selection require distinct offer/fulfillment rules. The existence of references does not mean all should be in the first release.

Mobbin references actually viewed

These are web screenshots used for structure only. They do not establish Shopify compatibility or coffee conversion performance. Canonical links and downloadable evidence are in the reference manifest (local handoff artifact).

Initial broad Attio and HelloFresh searches returned onboarding/table/address screens. Those were viewed, but were insufficient evidence for import-review or upcoming-delivery behavior. Refined searches produced the precise screens cited above. Stripe simulation setup was also returned; it does not evidence a customer subscription builder and is excluded from the proposed reference set.

Proposed application IA and shared workflow

Preserve the founder's main areas while making each surface part of one system:

“Design elements” must include purposeful experiences, not just a wall of blocks. A saved “Find my next coffee” experience owns its eligible catalog, rules and presentation. A saved “Filter club” offer owns commercial rules; the builder is one presentation of it. The same card and data model appear in discovery, product pages and subscription selection.

flowchart LR
  A[Existing product or supplier source] --> B[Review coffee facts and mappings]
  B --> C[Approved coffee catalog]
  C --> D[Offer: one time or recurring]
  C --> E[Discovery rules]
  D --> F[Experience preview]
  E --> F
  F --> G[Publish supported storefront placement]
  G --> H[Monitor new lots and exceptions]
  H --> B

This diagram describes a proposal. All backend states in it remain to be built. Initial onboarding should make the first approved coffee visibly useful, then let the merchant continue importing or configure an offer. A returning merchant should land on unfinished work and exceptions, not restart an install wizard.

Admin wireframe A: overview

Use real current Polaris 2 web components in the eventual interactive prototype. The parent researcher is handling detailed component/API validation. Official current App Home components and Polaris 2 guide are the authority. Legacy Polaris React 12 examples in older skills are not the target.

Coffee Kit / Overview                            [Add coffee]
Connected: shop • compatible theme • provider state

Continue setup: Review your first coffee → Preview → Publish
[resume action]                                  [dismiss]

Needs attention              Recent work
2 imports need review        Coffee approved / experience published
1 offer has no eligible lot  Source, owner, timestamp, next action

Your selling experiences
Coffee grid    Live / placement / preview
Coffee finder  Draft / eligible coffees / continue
Filter club    Provider not connected / set up

All numbers above are illustrative wireframe fixtures. After launch, metrics can include published coffees, completed import time and shopper actions. Zero data is “No activity yet,” not fabricated sales or uplift. Attributed orders must not be labeled incremental revenue.

Admin wireframe B: import review

Coffee data / Import 014               Draft • nothing published
Upload → Match products → Review facts → Preview changes

Sources                         Reviewed fields
PDF p2 or bag image              Field       Existing    Proposed
[page/region highlight]          Country     —           Ethiopia
[source excerpt]                 Process     Washed      conflict
                                Roast       —           unknown
Linked product                  Profile     —           needs assessment
Existing Ethiopia Guji
[Change match] [Open in Shopify] Each value: source / edit / keep existing

Target mapping                  Shopper preview
Existing custom.coffee fields   [Facts / card / PDP contexts]
Missing data stays hidden       Warnings describe actual omissions

[Save draft] [Next coffee]       [Apply selected reviewed changes]

A source label is untrusted evidence, not an instruction. Show extraction versus normalization versus merchant suggestion. For updates, show old/new values and resolve conflicting edits. For new products, show the proposed draft and require review of price, SKU/options and availability. Do not recreate the full Shopify product editor or silently publish commercial fields. An assisted onboarding operator should use this same review surface and leave an audit trail.

Admin wireframe C: subscription offer

Subscriptions / Filter club                     Draft [Save]
Steps: Offer → Coffees → Delivery & price → Experience → Test

Offer and provider                 Shopper summary
Internal name / public name        Filter club
Fixed coffee or rotating club      2 × 250 g • whole bean
Provider + capability status       Every 4 weeks
                                   €X per delivery, current plan price
Eligible coffees/variants          First order / subsequent charges
Included / excluded / why          Shipping and edit/cancel terms
Grind mapping / bag size

Cadence and pricing                Preview states
Read actual selling plans          Mobile / sold out / no plan
Show provider-controlled settings  Sparse data / unavailable grind

Existing subscribers: impact count and policy
New sales: on/off separately from existing contract operation
[Preview] [Run supported test] [Publish to selected placement]

The provider connection step must identify the operational owner: who bills, retries failed payment, handles skip/pause/cancel and sends mandatory messages. If Coffee Kit later owns the engine, the same IA needs real lifecycle screens. If it integrates a provider, supported operations should still feel coherent, with clear handoff only when required. This is an architectural choice for the synthesis, not a claim of provider interoperability.

Rotating clubs need a distinct lot-change review: current lot, candidate next lot, compatibility evidence, affected customers, price impact, deadline and stock responsibility. A common taste profile can suggest candidates; it does not authorize replacing a paid contract or prove equivalent taste. An empty club must block new subscription purchases and create an actionable exception. Roast logistics remains outside scope.

Admin wireframe D: experience builder

Three regions: configuration on the left; actual Coffeetale-style shopper rendering in the center; readiness/placement checks on the right. On smaller widths use a configuration tab and a preview tab. Native admin forms use Polaris; the preview uses the store's rendering and tokens.

Controls, in order: named purpose → eligible catalog/offer → content shown → purchase behavior → shared style → placement. Advanced per-element overrides remain secondary. Include a plain data/API presentation for agencies; do not fork commercial rules for a custom-designed frontend.

Status should distinguish Draft, Preview ready, Placement added and Live verified. Saving app configuration does not prove the theme block was placed or published. Each failure names what the merchant can do next. A transient toast can acknowledge a save; unresolved import/provider errors need persistent inline messages.

Shopper blueprint

Proposal: keep two entry routes, “I know my coffee” and “Help me choose.” Both resolve to the same catalog and offer; discovery should not be compulsory. Wogan and the supplied simple subscription concept support this structural choice.

1. Choose an exact coffee or a defined rotating club. Explain whether the next delivery will contain this specific lot or a roaster selection.
2. Choose brewing preference only when it affects eligible coffee or grind. Keep “whole bean, grind at home” distinct from a brewing method.
3. Choose valid grind and bag/box quantity. Display grams per bag, number of bags and total delivered weight; do not conflate two 250 g bags with one 500 g SKU.
4. Choose one-time or eligible subscription cadence. Display actual price per delivery and, where different, billing frequency, first charge and subsequent charge. Use plan allocations rather than applying a frontend-only percentage. Shopify selling-plan allocations.
5. Review an editable summary with coffee/club, grind, amount, cadence, recurring terms, shipping treatment and first-delivery expectation. Submit the selected Shopify variant and eligible plan. For a multi-item box, persist all line choices consistently; a label alone does not model a bundle.
6. After purchase, show the next delivery, exact edit cutoff, current contents and supported change/skip/pause/cancel actions. Provide the provider's customer portal where that is the operational owner. Do not invent a functioning Coffee Kit portal in the prototype.

Desktop should prefer the supplied inline form plus a sticky summary; mobile can present the same choices progressively with a persistent expandable total. A known-coffee path should preselect the product and avoid a redundant quiz. The profile chart remains an optional exploration tool with mood/text alternatives; dragging a radar vertex cannot be the only way to select a taste.

Design these states before polishing: one available coffee; sparse metadata; no exact taste match; sold-out lot; invalid grind/size combination; no eligible plan; loading/error; changed price after selection; rotating club without a next lot; expired edit window; partial import failure; theme placement not installed. User-facing language should state the reason and next action, not expose helper-section or API implementation details.

Exact visual direction, assets and tokens for Astra

Admin

Use current Polaris 2 web components, following the parent's current-documentation work. Use native page, section, table, badge, field, choice, drop-zone and action patterns after checking each component exists on the chosen App Home surface. Do not restyle merchant administration in espresso/orange or reproduce old React 12 screenshots. The storefront preview is the intentional branded region inside that admin shell.

Shopify's Polaris 2 guidance says web components adapt to the surrounding admin appearance through App Bridge. Load one Polaris bundle and match its TypeScript types; older React Polaris keeps its older appearance. The prototype must label any simulated Shopify frame, provider connection, publishing action or billing as a prototype. Polaris 2 guidance.

Coffeetale storefront and marketing examples

The design contract (local handoff artifact) defines an editorial specialty-coffee direction: warm light product surfaces, espresso text, fine dividers, square flat product cards, portrait packshots, an italic serif word in a large heading, and rounded action buttons. Tasting data supplies the detail. Use the current live captures to settle appearance where older Figma colors differ.

The table names exact existing tokens, not proposed arbitrary hex values. Values come from head variables (local handoff artifact), settings data (local handoff artifact), and compiled CSS. Preserve settings-driven inheritance. On an external theme use a scoped adapter rather than assuming these tokens exist globally. No “zero extra assets” or “zero performance cost” claim is established.

Exact local demo settings for the website prototype: section background #f8f8f5; primary text #2a1b17; product card background #F0F1EC; border palette #e7e7e7; stone palette color1: #e9e2d9; action accent color2: #b83910; pale accent surface color3: #fff7f1; brighter data accent color4: #e95625; utility dark color5: #3e3a35. Primary background is #ffffff. Fonts are headings_font: manrope_n5, body_font: dm_sans_n4, accent_font: fraunces_i3, utility_font: mono. heading_1_font uses the body family; headings 2–4 use the heading family; bodies 3–4 use utility. Product-card radius is var(--kt-border-radius-none). These are values read from the checked local demo settings, not a promise that every store or future preset shares them. Use semantic CSS variables in a prototype rather than sprinkling those values into components.

Image and icon selection

Before using an illustrative tasting file, check its exact filename: the source renderer falls back through uploaded file, built-in illustration and icon. Do not use contact sheets as the website's final imagery; they are inspection aids. Use original supplied files or retained live captures at their actual resolution. Mobbin images are reference evidence, not Coffee Kit marketing screenshots.

Website narrative and designer handoff

This is the UX contribution to the parent synthesis, not a request to implement or publish a website now. A compact Astra website handoff lists the exact assets, styling and screen requirements together.

1. Show the connected outcome. A real Coffeetale card/PDP beside an honestly labeled proposed import review. Explain: coffee source material becomes reviewed facts that power how it is discovered and sold.
2. Walk one coffee through the system. Source → review → presentation → purchase configuration → new-lot maintenance. Retain the same coffee and values across panels.
3. Show recurring selling as a product workflow. Offer setup and shopper summary together; distinguish fixed coffee and rotating club. Do not use a UI screenshot to imply renewal or substitution infrastructure exists.
4. Show current visual assets with their real status. Cards, facts, finder and recipe tabs have source evidence; selected interactions have live evidence; subscription layouts and stopwatch are proposed enhancements.
5. Explain fit and migration. A coherent destination after assisted migration, theme/version compatibility, data ownership, supported provider and agency presentation options. “Works with every theme/provider” is not established.
6. Use the synthesis's actual scope and commercial decision. Pricing and launch commitments remain the parent report's decision. Keep planned, prototype and available functionality distinct in every section.

Astra's first reviewable set should contain four admin screens (overview, import review, offer editor, experience builder), two shopper paths (known coffee and guided selection), a next-delivery concept tied to a clearly identified operational owner, and mobile layouts for the builder/review. Use real Polaris components for admin where possible; invented storefront screens must use current Coffeetale styling. Every sample number, source document, provider operation and sales result must be labeled as sample or proposed.

Acceptance checks before calling this a working Coffee Kit

Source: ux-assets-evidence.md The complete Markdown handoff and private datasets remain in the local project. This web edition includes selected supporting visuals and scenario downloads.