← Tous les designs

gauth-0001-plans-and-billing-v3 · frontend/src/pages/account/admin/billing

RandomCoffee — Plans, Add-ons & Billing

Specification and implementation instructions

Version 5 · August 2026

Files in this project

Frame ids in §6 match the annotations in the V4 file. The prototype covers the same states through its control rail.

---

1. Model

Two independent axes, plus one Enterprise-only supplement:

1. Plan — Free, Pro, Pro+, Enterprise. Sets quotas: members, admin licenses, audiences, engagement features.
2. Add-ons — Mentoring (live), Onboarding (coming soon). Grant capabilities: program types and their features.
3. Engagement Suite — an Enterprise-only supplement that lifts engagement and audience quotas to unlimited. On self-serve those quotas come from the tier itself, so it never appears on Free, Pro or Pro+.

No plan bundles an add-on. A Pro+ or Enterprise customer still unlocks and pays for Mentoring separately. The design states this deliberately: PAGE 4 (Pro+) renders the Mentoring card unpurchased and payable, exactly as PAGE 2 (Pro) does.

Entitlement resolution: plan quotas ∪ add-on capabilities. Quotas are numeric and come only from the plan, or from Engagement Suite on Enterprise. Capabilities are boolean and come only from add-ons. An add-on must never raise a quota; a plan must never grant a program type.

---

2. Plans

\* Placeholders. Pricing is per seat bracket, never "per user/month" — always render the bracket sentence: $200/month · for 50 users · billed annually.

Free and Pro differ only on members and admin licenses. Audiences, engagement caps, matching rules and integrations are identical. Any Free→Pro upsell must therefore claim only real deltas: unlimited Coffee Connect programs, unlimited members and flexible tiers, 3 admin seats instead of 1, customizable sending domains, HRIS integrations, priority support, access to paid add-ons.

Plan card contents (identical wherever the card appears):

Free — 1 Coffee Connect program · 2 Surveys · 2 Broadcasts · 2 Notes · Advanced matching rules · Customizable session schedule · Customizable communications · Slack & Microsoft Teams integrations · Google / Outlook calendar integrations

Pro — Unlimited Coffee Connect programs · Unlimited members · flexible tiers · 3 admin seats · 2 audiences · 2 Surveys · 2 Broadcasts · 2 Notes · Customizable sending domains · HRIS integrations · Priority support

Pro+ — everything in Pro, plus: Unlimited Surveys · Unlimited Broadcasts · Unlimited Notes · Unlimited audiences · 5 admin seats

Enterprise — SAML SSO · 2FA · SCIM & API provisioning · Team permissions · Service Level Agreement · Dedicated Account Manager & Support · Custom reports analysis · Security questionnaire review · Onboarding & training sessions

No plan card mentions add-on availability: add-ons are universally paid, so it differentiates nothing.

Tier icons. Each plan has an illustrated icon at 34px, placed before the plan name, in the plan card and in the current-plan block: Free = coffee beans, Pro = paper cup, Pro+ = coffee pot, Enterprise = espresso machine. They give the tier list a visible sense of progression. Assets: assets/plan-{free,pro,proplus,enterprise}.png.

---

3. Add-ons and the Engagement Suite

3.1 Mentoring — live

Adds a second program type alongside Coffee Connect. Feature list, verbatim and identical everywhere it appears:

1. Custom program architecture and funnels
2. All Mentoring use cases library unlocked
3. Mentor / Mentee advanced matching rules
4. Goals and milestones per mentor-mentee pairing
5. Mentor / Mentee shared space

Price in the mockups: +$100/month for 50 users. The price is never shown on the add-on card — only inside the activation modal (MODAL B1), where the full breakdown makes it meaningful.

3.2 Onboarding — coming soon

Not sellable. Renders with a purple Coming soon badge, no price, no Activate CTA and no explanatory alert — the badge carries it. Announced features: automated welcome journeys · milestone-based onboarding steps · new-joiner check-ins & nudges · onboarding progress analytics.

3.3 Engagement Suite — Enterprise only

A supplement on the contract that lifts Surveys, Broadcasts, Notes and audiences to unlimited. It exists because existing Enterprise customers were never billed for those unlimited quotas, and being on Enterprise does not by itself grant them.

It is not an add-on card. It surfaces as a status on the limits block:

• Purchased — a green tag on the limits header: ✓ Unlimited unlocked with Engagement Suite, and the four quotas read Unlimited.
• Not purchased — an antd Alert type="info" compact at the top right of the limits block: thunderbolt icon, "Unlock unlimited Surveys, Broadcasts, Notes and audiences with Engagement Suite", and a primary Contact my CSM button. The four quotas read 1/2.

Never appears on Free, Pro or Pro+.

---

4. Copy and naming rules

Mandatory vocabulary

• Add-on — never "module", including in code, API fields and analytics events.
• Coffee Connect — the classic program type. Never "Classic", "Standard" or "Coffee Meetup".
• Mentoring, Onboarding, Engagement Suite — never abbreviated.
• Surveys, Broadcasts, Notes — never "Forms".
• Pro, Pro+ — never "Connect" / "Network" (working names used during design).
• "Contact my CSM" — the single reference wording on every CSM action button. Descriptive text may still use the second person ("Your Customer Success Manager", "activated by your CSM").

Writing rules

• No em dashes (—) in product copy. Use a comma, a colon or a full stop.
• Prices always contextualised to the seat bracket. Never a bare unit price.
• Gate wording is plan-agnostic: "The Mentoring add-on isn't included in your plan", not "requires the Pro plan", so one string works on Pro, Pro+ and Enterprise.
• A delta-framed list ("You will unlock access to") may only contain genuine differences — see the Free/Pro warning in §2.

---

5. UX principles

5.1 Show what is locked, never hide it

Locked add-ons stay visible with a neutral icon tile, a grey status badge naming what is required, and their full feature list. Clicking any locked element opens the matching gate modal.

5.2 Every gate has an exit

No modal is a dead end. There is always a secondary action: Not now, Dismiss, or a constructive alternative such as Continue with Coffee Connect.

5.3 Sell the right thing to the right plan

• Free → sell the plan. Never show an add-on price to a Free user; the first step is Free → Pro. Free has no Manage plan button and no cancel path — it shows Change Subscription, which routes to the plan grid.
• Pro → sell the add-on (Mentoring) or the tier (Pro+ for quotas), priced on their seat bracket.
• Pro+ → sell the add-on only; quotas are already unlimited.
• Enterprise → sell nothing. No price, no pay button, no lower tier. The only exit is Contact my CSM, with the CSM's name and photo.

5.4 Quota gates never destroy

Hitting a cap blocks creation only. Existing items stay visible and functional. When a cap is introduced retroactively, items created before enforcement are grandfathered with a Legacy · kept badge and the counter reads 4 kept · limit is now 2. Enforcement compares creation date to the enforcement date, never the count.

5.5 Anti-churn: demote the exit

• Add-on and plan cards expose a neutral Manage plan / Manage your add-on button. Never a red "Deactivate" on the card.
• Inside the management panel, positive actions are large rows; Cancel or downgrade is a small underlined text link at the bottom.
• Cancelling passes through a retention step (MODAL B5) before any destructive confirmation.

5.6 Enterprise is nudged, never blocked

Contract customers may legitimately exceed quota. The over-quota treatment is amber, not red: warm border, amber counter, saturated gauge, a short overage note (142 over your contract) and a **secondary Contact my CSM button inside the affected card**. The action sits on the quota that is actually over, not in a page-level banner. Nothing is blocked, because an Enterprise customer over contract is a conversation with their CSM, not an error.

5.7 Card layout rules

• Plan cards and add-on cards in the same row are equal height (align-items:stretch, card height:100%).
• A card's button is always last and bottom-aligned (margin-top:auto), whatever it does, so buttons line up across a row.
• Each add-on card carries exactly one status badge, top right: purple when coming soon, grey when locked or not active, green when active.

---

6. Screens

6.1 Pages — Settings › Plan & Billing

Shared structure: app chrome (top bar, Workspace settings menu with Billing selected) → breadcrumb → title → tabs Subscription / Billing / Invoices history → current-plan block → billing-cycle and currency Segmented → plan grid → Add-ons → Your current limits → Need help.

The Billing tab owns the payment card and invoices; they never appear on Subscription.

Current-plan block — tier icon, plan name, blue Current plan badge, price bracket, renewal or contract end date, and a neutral Manage plan button on the right (paying plans only). No "Subscription" eyebrow: the name and icon are enough.

Your current limits — two groups. Plan & seats: Active users (continuous gauge), Admin licenses (segmented gauge, one cell per licence), Audiences. Engagement features: Surveys, Broadcasts, Notes. Values must match §2 exactly for the plan shown; this was the most frequent inconsistency during design.

6.2 Modals — gating and upsell

6.3 Modals — activation, management, churn

---

7. Ant Design implementation

Both design files are built on antd 5 with the theme already in the codebase — layouts/config.tsx:

<ConfigProvider
  prefixCls="rc"
  componentSize="large"
  theme={{ cssVar: { prefix: 'rc' }, token: { colorPrimary: '#4451EA', borderRadius: 6, /* … */ } }}
>

Nothing in the design is bespoke UI: every element maps to an antd component, and the class names in the files are the ones antd emits, so a developer can read a frame and know the component.

Icons. @ant-design/icons, rendered as antd renders them: <span role="img" class="anticon anticon-check" data-icon="CheckOutlined">. 27 of the 29 glyphs are native antd components. **All feature-list checkmarks are CheckOutlined in --rc-color-primary**, uniformly.

Two glyphs are not in antd and come from Lucide (MIT): a graduation cap for Mentoring and a waving hand (tilted +18°) for Onboarding. Both must be added to components/icons/index.tsx, alongside the existing custom icons such as MagicWandIcon.

Add-on icon tiles are neutral — white fill, 1px --rc-color-border, glyph in --rc-color-text-secondary — with no per-add-on accent colour, so the two cards read as siblings rather than as competing brands.

Token usage

Radius 6px controls, 8px cards, 4px tags. Type: Roobert. No gradients in functional UI.

---

8. Implementation notes

Pro+ needs a fourth tier. classes/plans.tsx models three plan types (0 Free, 1 Pro, 2 Enterprise). Plan.type and getAllFeatures() must gain Pro+ between Pro and Enterprise. PAGE 4 and MODAL A7 depend on it.

Engagement Suite needs a contract flag. A boolean on the Enterprise subscription that switches the four quotas to unlimited and drives the limits-header status. It must not exist on self-serve plans.

Grandfathering. Enforcement compares creation date to the enforcement date, not the count. Items created before remain editable and sendable forever; the counter reports them separately.

Deactivation. End of billing period. Mentoring programs move to paused; over-quota engagement items become read-only. Reactivation restores everything with no migration.

Cancellation. 90-day retention window before deletion. The UI promises it, so the backend must honour it.

Enterprise. Never expose self-serve purchase endpoints. Every add-on and quota action routes to the CSM contact channel (billing/sendEnterpriseNote).

---

9. Open questions

• Final pricing per seat bracket for every plan, for Mentoring, and for Engagement Suite. All figures in the design are placeholders.
• Onboarding add-on: launch date, pricing, and whether it lands as a paid add-on or as a tier inclusion.
• Engagement Suite: how existing Enterprise customers are migrated and re-billed, and whether there is a grace period before the caps apply.
• Whether the retention discount in MODAL B5 is granted automatically or needs approval.
• Seat-bracket boundaries and what happens when a workspace crosses one mid-period.
• An explicit signal on PAGE 6 that the unlimited tier was paid for, beyond the limits-header tag.