RIFF how-to · 2026-07-06 · design: Config Cascade & Per-Org Branding

Brand Your Flow's Follow-Along Page

Give every phone line its own colors, badge, tagline — and its own caller-friendly progress labels — in one YAML block.

0 · What you get without doing anything

• The menu is already yours. "Press 1 for … 2 for …" comes from your pack's capabilities — every flow has its own.
• The progress is already yours. The page mirrors the live call: your flow's states, your intake stages, your collected (whitelisted) answers.
• A fallback look. Flows with no declared brand get a deterministic color palette derived from the flow id (distinct, but not chosen), or a legacy keyword theme (law, plumbing…). The linter reminds you: companion-brand-missing.

1 · Declare the brand (one block)

Preferred home: your company's org file, so every one of its lines matches automatically.

# orgs/capsule_law.org.yaml
org_id: capsule_law
display_name: "Capsule Law"
brand:
  name: "Capsule Law"           # header title + page <title>
  badge: "CL"                   # the little avatar chip (1–3 chars)
  tagline: "your intake, live"  # subtitle under the name
  colors:
    primary: "#c8a24a"          # accents / glow
    highlight: "#e2c56f"        # highlights / gold
    bg: "#0b0e19"               # page background (optional)
    panel: "#131730"            # card background (optional)
  journey:                      # optional — see §4
    cap_intake__stage_matter: "Your case"
    cap_intake__stage_contact: "How to reach you"

Then point each of the company's flows at it — one line in the flow/pack YAML:

org: capsule_law

config:
  brand: {name: "Riff Cafe", badge: "RC", colors: {primary: "#38bdf8"}}

2 · Which color does what

Pick primary/highlight with good contrast against your bg — a contrast lint gate is planned; until then, eyeball it in the preview (§5).

3 · What lights up as the phone reads

The page doesn't just sit there while the agent talks — three surfaces highlight in real time, and all three take your brand's highlight color automatically (no extra config):

4 · Journey labels — how your progress READS

Without journey:, the page prettifies state ids ("Cap Service Request Stage Problem"). With it, callers see your words:

journey:
  cap_service_request__stage_problem:  "Problem"
  cap_service_request__stage_location: "Address"
  cap_service_request__stage_timing:   "Time"
  cap_service_request__confirm:        "Confirm"
  cap_service_request__done:           "Booked!"

5 · Verify

1. Lint: python -m riff.flow_eval.linter <flow_id> — the companion-brand-missing warn disappears; a dangling org: is an error.
2. Tokens: python -c "from riff.branding import brand_for_flow; print(brand_for_flow('<flow_id>'))" — you should see your colors/journey, not the fallback.
3. Live: place a test call, say "text link", open the SMS'd companion URL — your colors, your badge, your step names. Org-file edits show on the page's next poll (no restart); Python changes still need a server restart.

6 · How it works (30 seconds)

The effective-config cascade (call → state → state group → flow → org → global) resolves your brand: block; brand_for_flow() projects it to public tokens only (no internal ids, no provenance) into /api/companion/state; the single companion.html template maps tokens onto its CSS variables and label lookup. Resolution order: declared → legacy keyword theme → derived palette.

7 · Gallery — the running flows, branded

These brands are LIVE in the flow YAMLs (flow-level config.brand; org files lift shared identity up in PR4). Each mock mirrors the follow-along page: header, that flow's REAL menu options, and the "heard so far" slot echo — the value renders in the brand's highlight color.

The exact block behind the plumbing card, as it appears in flows/austin_plumbing.yaml:

config:
  brand:
    name: "David Austin Plumbing Pros"
    badge: "AP"
    tagline: "plumbing service"
    colors: {primary: "#38bdf8", highlight: "#facc15"}
    journey:
      greeting: ["Welcome", "The call is getting started."]
      triage: ["Your problem", "Tell us what's going on."]
      scheduling_collect_possible_days: "Days that work"
      scheduling_collect_blocked_days: "Days to avoid"
      scheduling_request_summary: ["Request summary", "Reading your visit request back."]
      complete: ["All set!", "Our dispatcher will confirm shortly."]

8 · Troubleshooting