Builder Handbook · Edition I

Everything you need to build The Care Loop.

A single source of truth for designers, engineers and partners: roles, journeys, features, the design system, and how we sound. Read top to bottom, or jump to a section.

Mission

What The Care Loop is

The Care Loop helps people and organisations keep products in use for longer, closing the loop between buying, caring, repairing and recirculating. It connects shoppers, brands, service providers, retailers and cities around a shared, evidence-led Care Loop Score.

Keep things alive

Make care, repair and reuse the obvious path, not the hard one.

Earn trust with evidence

Every claim carries a signal and a confidence level. No greenwashing.

Connect the ecosystem

One loop linking owners, brands, repairers, retailers and regions.

Jobs to be done

What users hire us for

  • “When I buy something, help me understand its real impact, with evidence.”
  • “Help me keep what I own working and valuable for as long as possible.”
  • “When something breaks, get it repaired instead of replaced.”
  • “When I'm done with an item, route it to its best next life.”
  • “As a brand, show me how my products live in the real world.”
  • “As a city, show me circular progress across my region.”
Audiences

User roles & portals

Roles live in a dedicated table and are resolved server-side. After sign-in, users are routed to the right portal automatically.

Shopper / Consumer

consumer/app

Anyone who buys, owns and cares for products.

  • Scan or look up a product and read its Care Loop Score
  • Claim ownership and build a private timeline
  • Log care events, repairs and next-life routes
  • Generate a public Care Pass (Digital Product Passport)
  • Share reviews, repair knowledge and flag greenwashing

Brand

brand_admin/brand

Sustainability, product and compliance teams at a brand.

  • Manage products, scores and certifications
  • Track compliance panels and transparency signals
  • See how customers care for, repair and recirculate items

Service provider

service_provider/provider

Repair, refurbish, resale, recycle, rental and donation partners.

  • Publish capabilities into the repair & reuse network
  • Receive and manage repair requests
  • Be discovered as a next-life route for owned items

Retailer

retailer/retailer

Retailers turning point-of-sale into circular outcomes.

  • Link sales to ownership records
  • Surface trade-in and take-back programmes
  • Report on circular outcomes across the catalogue

City / Municipality

city_admin/city

Local governments tracking regional circular progress.

  • Monitor circular activity across the region
  • Understand waste diverted and value retained
  • Coordinate with brands and providers locally
Flows

User journeys

Shopper · scan → own → care → pass

  1. 1Discover a product by barcode scan, search or filtered Discover grid
  2. 2Read the Care Loop Score (health · planet · ethics · longevity) plus verified evidence
  3. 3Claim “I own this” to start a private ownership log
  4. 4Schedule reminders and log care on the care timeline, request repairs, route to next life
  5. 5Publish a Care Pass and share the public passport link

Brand · onboard → publish → observe

  1. 1Sign up as a Brand, and an org is provisioned automatically
  2. 2Manage products, scores and certifications
  3. 3Watch real-world care, repair and recirculation signals

Provider · list → match → fulfil

  1. 1Register capabilities and service type
  2. 2Get matched to repair requests and next-life routes
  3. 3Fulfil work and feed outcomes back into the loop

Auth · role-aware routing

  1. 1One sign-in form for everyone (no role toggle)
  2. 2Role resolved server-side after sign-in
  3. 3Routed to the matching portal, or the shopper app
Surface area

Features

Scan & lookup

Find a product by barcode or search and surface its Care Loop Score.

External registry

Real product data from Open Facts registries first, with a barcode lookup fallback.

Discover filters

Browse 150+ products (incl. Nordic brands) filtered by category and subcategory.

Care Loop Score

Composite of health, planet, ethics, longevity, with a confidence signal.

Verified evidence

Each product shows what we verified (score signals) and what we couldn't (unknowns).

Ownership log

Private record of items a user owns and their status.

Care events

Clean, store, rotate, service, kept on the item timeline.

Care timeline

Upcoming reminders and completed care across self, brand, retailer and services.

Care network

End-to-end care: who made it, who sold it, and who keeps it alive.

Repair requests

Route an item to a service provider for repair or refurb.

Next-life routes

Reuse, resell, donate, refurbish or recycle at end of life.

Care Pass (DPP)

Shareable Digital Product Passport with a QR-coded PDF export.

Community signals

Owner reviews and opt-in repair knowledge tips.

Greenwashing flags

Flag misleading claims. Public only after moderation.

Impact

Items kept alive, value retained and planet averages.

Design system

Colour

Tech-luxury on a deep midnight canvas. Colours are defined as OKLCH tokens in src/styles.css, never hard-code hex in components, use the semantic tokens.

#020026
Canvas / background
oklch(0.125 0.05 270)
--background · --tl-canvas
#0E0E2B
Raised surface
oklch(0.175 0.045 270)
--card · --tl-canvas-2
#F2F3DA
Cream ink (text)
oklch(0.957 0.02 109)
--foreground · --tl-text
#7FB069
Accent · green
oklch(0.705 0.112 136)
--tl-accent · --ring
#C26F6D
Accent · dusty rose
oklch(0.633 0.106 22)
--tl-accent-2 · --coral
#DC9D81
Accent · warm ochre
oklch(0.75 0.085 45)
--accent · --ochre

Score dimensions

Health--dim-health
Planet--dim-planet
Ethics--dim-ethics
Longevity--dim-longevity
Design system

Typography

Clash Display--font-display
Display / headingsEditorial grotesque. Uppercase h1–h3 with tight leading.
Clash Display--font-logo
Logo / mega displayUppercase wordmark and oversized display headlines.
Neutiva--font-sans
BodyWorkhorse UI and paragraph text (Helvetica fallback).
SF Mono--font-mono
Metadata / labelsUppercase, wide-tracked eyebrows, chips and labels.
Design system

Core components & utilities

Built on shadcn/ui primitives and the DS library, themed with custom Tailwind utilities (the tl- family). Every specimen below is the live component: change it once and the pages and dashboards change with it.

tl-card

Primary surface, flat panel with a 1px cream hairline border. No gradient, shadow or glow.

tl-glass

Solid raised panel on --canvas-2. Flat, no blur, kept for backwards-compatible markup.

tl-btn / tl-btn-glow

Flat ochre pill. Press nudges translate(1px,1px); no halo.

tl-btn-ghost

Outlined ochre pill for secondary actions.

tl-chip

Uppercase mono-label pill for metadata and tags.

eyebrow / label-mono

Uppercase, +0.05em tracked mono kicker above headings.

tl-divider

1px hairline rule between sections.

container-editorial

Centred editorial max-width wrapper with responsive gutters.

Everything below is the running component, not a screenshot. Each specimen imports from the same module the pages and dashboards use, so a change to a component or a token in src/styles.css lands here and on every screen at the same time.

Buttons

@/components/ds · Button

Used on landing, scan flow, every dashboard action

shadcn button

@/components/ui/button

Used on forms, admin panels, dialogs

Badges & tags

@/components/ds · Badge, Tag

Used on product pages, review queue, filters

OutlineContrastOchreCoralLongevityRepairable

Score stamp

@/components/ds · ScoreStamp

Used on app home, product page, ownership detail

THE CARE LOOPTRUST SCORE92EVIDENCE-LED7441

Confidence badge

@/components/ds · ConfidenceBadge

Used on every score readout and generated answer

HIGH92% COVERAGEMEDIUM64% COVERAGEESTIMATED

Dimension bars

@/components/ds · DimensionBar

Used on Trust Score breakdown

HEALTH· Low-tox82 /100
PLANET· Recycled inputs64 /100
ETHICS· Partial audit48 /100
LONGEVITY· Repairable91 /100

Evidence rows

@/components/ds · EvidenceRow

Used on score explainer, methodology

Bluesign certified fabric
Verified · 2025
+8
Repair program available
Verified · brand site
+5
Living wage in supply chain
Unverifiable
?
Air-freight shipping
Verified · logistics
-6

Product cards

@/components/ds · ProductCard

Used on search results, brand catalogue

[ photo ]
HIGH
Fjäll Merino
Base Layer LS
92 /100View →
[ photo ]
MEDIUM
Nordic Denim
Selvage 14oz
74 /100View →

Cards & index rows

@/components/ds · Card, IndexRow

Used on dashboards, Care Pass, handbook

Trust score
Merino base layer
Evidence-led rating across health, planet, ethics and longevity.
Care timelineP. 07
Community signalsP. 12

Form fields

@/components/ds · Input, Select, Checkbox, Switch, Radio

Used on onboarding, scan flow, settings

Navigation

@/components/ds · Tabs, MetaBar

Used on product detail, portal headers

Builder handbookComponentsThe Care Loop 2026

Feedback

@/components/ds · Toast, Tooltip

Used on care logging, publishing, assistant

Care Pass published
Hover me

tl- utilities

src/styles.css

Used on marketing pages and shared chrome

mono chipEyebrow label
tl-card · hover me
tl-glass panel
Design system

DS component library

Editorial primitives ported from the Care Loop design system. Import from @/components/ds, they theme automatically via the DS role tokens (--canvas, --ink, --ochre…) and are showcased live at /design-system.

Button / IconButton

Flat pill actions in primary, accent, outline and ghost variants.

Badge / Tag

Uppercase status pills (outline, contrast, ochre, coral).

Card

Bordered surface with eyebrow / title / footer slots and tint tones.

MetaBar / IndexRow

Editorial header chrome and dotted index rows from the deck.

ScoreStamp

Circular Care Loop Score stamp used on product and pass views.

PhotoSlot

Framed image placeholder for product and editorial imagery.

ConfidenceBadge

Confidence pill (high/medium/estimated) with coverage %, showing how much of a score is verified.

DimensionBar

Segmented bar for one score dimension (health/planet/ethics/longevity) with verdict + value.

EvidenceRow

One verified or unverifiable claim behind a score, with a signed delta chip.

ProductCard

Discover-grid unit: thumb, confidence badge, brand/name, Trust Score and view link.

Forms

Field, Input, Checkbox, Radio, Select, Switch, sharp corners, hairline borders.

Feedback

Dialog, Toast, Tooltip and Tabs matching the flat DS specs.

Layout

Responsiveness

Every page and dashboard is verified across mobile and tablet. Design mobile-first, then promote to multi-column at sm / md / lg.

Mobile

< 640px (base)

Single column. Stack cards, badges and dimension bars full-width.

Tablet

sm 640 · md 768px

Two-up card grids; TOC still inline chips, not the sidebar.

Desktop

lg 1024px+

Sticky sidebar TOC (220px) plus content. Up to 3-up grids.

  • Multi-item header rows use a grid + min-w-0 (text) + shrink-0 (icons) so labels never clip on mobile.
  • Add min-w-0 to flex/grid text containers and truncate to single-line headings.
  • Scale display type with clamp / responsive text-* steps, display-xl floors at 2rem so long words don't overflow.
  • Verify every public page and dashboard is free of horizontal overflow at 390px and 820px.

MarketingFooter

Public site footer: logo lockup, a responsive 3-column website menu (Platform · Company · Legal) and the light/dark ThemeToggle.

AppFooter

Compact footer for authenticated dashboards: quick links plus the same mode switch, wired into the _authenticated layout.

Mode switching

Theme is driven by the ThemeToggle (Light / Dark), flipping .light / .dark on the root so the DS tokens re-resolve. Toggle wrappers use items-start so buttons never stretch full-width on wide viewports.

Brand

Voice & tone

We sound like a trusted, investigative friend, clear, warm and evidence-led.

Do

  • Plain, confident, investigative
  • Evidence-led, name the signal
  • Warm and human, never preachy
  • Concrete verbs: scan, log, repair, route

Don't

  • Hype, jargon, vague eco-claims
  • Unbacked superlatives (“the greenest”)
  • Guilt-tripping or moralising
  • Abstract corporate filler
AI in the product

AI patterns

AI assists judgement, it never stands in for it. Five rules govern every generated surface.

Rule 01

Labelled at the point of reading

Generated text carries a meta strip naming it as generated, with the confidence tier and data completeness behind it. No label, no generated text.

Rule 02

Grounded or silent

The model answers from stored records only. When a fact is missing it says so. An unknown is a finding, not a gap to fill with prose.

Rule 03

Draft, then accept

Suggestions never write to a person's data. Each step carries accept, edit and discard, and the panel states that nothing is saved yet.

Rule 04

Work shown on request

Tool calls are visible but collapsed. The reader sees which sources were touched without being handed a transcript they did not ask for.

Rule 05

Opt in, never ambient

No panel generates on page load. A person presses a button, and can dismiss the result back to that button.

Where AI shows up

  • Care assistant at /app/assistant. Answers from the catalog, your ownership log and the provider network, with tool calls visible but collapsed.
  • Explain this score on a product page. A plain reading of the four dimensions plus what is still unknown.
  • Suggest a care plan on an owned item. Drafted steps you accept, edit or discard one by one.
Public record

Decision log

What we chose, what we turned down, and why. Kept public so the reasoning can be argued with.

D-01
Assistant is grounded in tools, not in the model's memory

Every answer comes from a tool call against the catalog, ownership log or provider network, and the system prompt forbids inventing a score or a certification.

Rejected A general chatbot with the product description pasted into the prompt. It reads fluently and quietly fabricates evidence, which is the one failure this product cannot absorb.

D-02
Unknowns are a first-class output

Score explanations return a caveats block, and an empty caveats list is a claim we stand behind rather than a formatting accident.

Rejected Hiding gaps behind confident summaries. Confidence tiers already exist in the data model, so the interface has no excuse to flatten them.

D-03
Suggestions are drafts with per-step consent

The care plan writes nothing. Each step is accepted, edited or discarded individually, and only accepted steps become reminders.

Rejected Auto-scheduling the plan with an undo. Undo puts the burden of correction on the person after the fact and trains them to distrust the whole surface.

D-04
Tool activity is collapsed by default

Tool headers show a plain-language label and status. Parameters and raw output stay behind a disclosure.

Rejected Streaming the full reasoning trace. It raises perceived rigour and actual cognitive load at the same time, which is a bad trade for a shopper.

D-05
No ambient generation

Nothing generates on page load. AI panels start as a button and can be dismissed back to it, so the non-AI path is always complete on its own.

Rejected An always-on summary at the top of every product page. It spends credits and attention on people who did not ask, and makes the generated text look like a fact of the record.

D-06
One model, chosen for latency

Chat, explanations and plans all run on a single fast general model, so behaviour stays consistent and answers land inside a few seconds.

Rejected Routing per task to larger models. The gain in prose quality did not survive the grounding constraints, and the added wait did more damage than the polish repaired.

Language

Shared vocabulary

Use these terms consistently across UI copy, code and conversation.

Care Loop
The lifecycle a product travels: buy → care → repair → next life.
Care Loop Score
Composite rating across health, planet, ethics and longevity, with confidence.
Score signals
What we verified about a product, the evidence behind each score dimension.
Unknowns
What we couldn't verify yet, declared openly alongside the score.
Ownership log
A user's private record of an owned item and its status.
Care event
A logged action keeping an item alive (clean, store, service…).
Care timeline
Per-item view of upcoming reminders and completed care across all sources.
Care network
The end-to-end map of who made, sold and keeps an item alive.
Care Pass
The shareable Digital Product Passport (DPP) for an item.
Next life / EOL route
Where an item goes at end of life: reuse, resell, donate, refurbish, recycle.
Community signals
Owner reviews, repair knowledge and greenwashing flags.
Confidence
How much evidence backs a score, shown alongside it, never hidden.
Portal
Role-specific workspace: brand, provider, retailer or city.

Getting set up

The platform runs on TanStack Start (React 19) with Lovable Cloud for database, auth, storage and server functions. App logic lives in createServerFn handlers; roles are enforced with RLS and security-definer helpers. Start at the home page, then explore each portal.