Phase 4 — Companies House
Build sequence — click any feature to inspect
Technology stack
Every component, its purpose, and who chose it
Frontend
React + Tailwind
Customer dashboard, onboarding wizard, transaction review, submission screens
Cloudflare Pages
Backend functions
Supabase Edge Functions
Business logic, API orchestration, webhook handlers. TypeScript / Deno runtime.
Serverless
Database
Supabase PostgreSQL
All customer data, transactions, submissions, filings. Row-level security mandatory.
UK data residency
Authentication
Supabase Auth
Email/password sign-up, session management, protected routes, password reset via Resend.
JWT sessions
Hosting
Cloudflare Pages
React app deployment. Cloudflare also handles CDN, HTTPS enforcement, and rate limiting.
Primary hosting
Open Banking
Yapily / TrueLayer
FCA-regulated bank feed connections. UK banks only. OAuth token flow, daily sync.
FCA regulated
AI categorisation
Claude API
Transaction categorisation into HMRC-recognised expense categories. Batched 50/call.
claude-sonnet-4
HMRC submission
HMRC MTD APIs
MTD Income Tax quarterly updates, Obligations API, fraud prevention headers.
Production approval req.
CH filing
Companies House API
Public Data API for lookups + Filing API (OAuth 2.0) for CS01 submissions.
OAuth 2.0
Billing
Stripe
Subscription billing, 30-day free trials, webhooks, Customer Portal, invoices.
5 products
Email
Resend
Transactional email: reminders, submission confirmations, onboarding, payment alerts.
Generous free tier
Scheduling
Supabase pg_cron
Daily bank sync at 6am UTC. Deadline reminder dispatch at 8am UK time.
Built into Supabase
External API reference
Every third-party integration, its purpose, and cost model
HMRC MTD API
Quarterly income tax submissions, obligations retrieval, fraud headers
FreeCompanies House Public
Company search, profile lookup, filing history, deadline dates
FreeCompanies House Filing
CS01 confirmation statement submission via OAuth 2.0
FreeYapily / TrueLayer
Open Banking — UK bank account connection, daily transaction sync
Usage-basedClaude API (Anthropic)
AI transaction categorisation — batched 50 transactions per call
Per tokenStripe
Subscription management, checkout, webhooks, Customer Portal
1.4% + 20p/txnResend
All transactional email — reminders, confirmations, alerts
Free tier
Environment variables required
All must be set in Cloudflare Pages environment before deployment
SUPABASE_URL
Supabase project URL
SUPABASE_ANON_KEY
Public anon key for frontend
SUPABASE_SERVICE_ROLE_KEY
Server-side Edge Functions only — never in frontend
YAPILY_CLIENT_ID
Open Banking — Yapily application ID
YAPILY_CLIENT_SECRET
Open Banking — Yapily secret (server-side only)
HMRC_CLIENT_ID
HMRC Developer Hub application client ID
HMRC_CLIENT_SECRET
HMRC OAuth secret (server-side only)
CH_API_KEY
Companies House Public Data API key
CH_OAUTH_CLIENT_ID
Companies House Filing API OAuth client
CH_OAUTH_CLIENT_SECRET
Companies House Filing API OAuth secret
ANTHROPIC_API_KEY
Claude API — transaction categorisation (server-side only)
STRIPE_SECRET_KEY
Stripe server-side secret key
STRIPE_PUBLISHABLE_KEY
Stripe frontend publishable key
STRIPE_WEBHOOK_SECRET
Stripe webhook signing secret
RESEND_API_KEY
Resend transactional email API key
TOKEN_ENCRYPTION_KEY
AES-256 key for bank/HMRC token encryption — never in DB
APP_URL
Production URL e.g. https://clearfile.co.uk
⚡ How to use these prompts
Each prompt has a unique reference number (e.g. CF-001). Paste the full prompt into Emergent exactly as written. Run prompts in order — do not start a prompt until all its dependencies are marked complete. When done, click Mark complete, log your time, and add any notes. If Emergent returns with questions, append: "Do not ask clarifying questions — make a reasonable assumption and note it at the end of your output."
Master system context — prepend to every Emergent session:
"You are building ClearFile, a UK accounting SaaS for sole traders and limited company directors. Stack: React + Tailwind CSS frontend hosted on Cloudflare Pages. Backend: Supabase Edge Functions (TypeScript). Database: Supabase PostgreSQL. Brand colours: navy #1B3A6B and teal #0D7377. Domain: clearfile.786i.com (dev), clearfile.app (production). Always use UK English. Never ask clarifying questions — make assumptions and state them. Every function must include error handling. All sensitive tokens must be encrypted before database storage."
Brand identity guidelines
ClearFile brand system — logo, colour, typography, tone of voice, spacing, motion. Version 1.0 · May 2026
Logo system
✓
Approved backgrounds
Navy, light grey (#f8f9fc), teal, or white only.
✓
Minimum clear space
Equal to the height of the "C" in ClearFile on all sides.
✓
Minimum size
Wordmark: 120px wide. Icon only: 24px.
✗
Never recolour the mark
Teal panel and amber check must always appear as shown.
✗
Never stretch or distort
Scale proportionally only. No shadows, outlines, or effects.
✗
No busy backgrounds
No photography or patterned backgrounds behind the logo.
Stacked files
Three layered document shapes represent the core product — tax records, MTD submissions, company filings. Each layer slightly offset to show organisation and depth.
Teal action layer
The front document is teal — the active, working layer. Horizontal lines represent transactions being processed. Teal signals forward motion and digital precision.
Amber check mark
The gold circle with a tick is the compliance moment — submission confirmed, deadline met. Positioned bottom-right as a "done" badge. The product's core promise made visual.
Colour system
Primary palette
Navy
#1B3A6B
Primary brand, headings, nav, dark CTAs
Teal
#0D7377
Actions, links, active states, logo mark
Amber
#F0A500
Accent only — logo check, highlights
Teal light
#14a0a5
Hero subheadings on navy, hover
Navy dark
#122854
Hover on navy, footer
Neutral & surface
Off-white
#f8f9fc
Page background
Surface
#f2f5f9
Cards, sidebar, stat backgrounds
Border
#dde3ed
Card borders, dividers, inputs
Text secondary
#4a5568
Body text, labels, descriptions
Text muted
#8896a8
Captions, metadata, placeholders
Semantic (status & feedback)
Success
#059669
Confirmed, submitted, active, paid
Warning
#d97706
Due soon, needs review, flagged
Danger
#dc2626
Overdue, error, payment failed
Info
#2563eb
Informational, in-progress states
Filing
#7c3aed
CS01 / Companies House contexts
✓
Navy on white or off-white
Primary text and headings use navy (#1B3A6B) on white/off-white.
✓
White text on navy or teal
Any reversed-out text is always pure white (#ffffff).
✓
Semantic colours for status only
Green, amber, red and blue are reserved for status and alerts — never decorative.
✗
Never use teal as a surface
Teal is an action colour — buttons and links only, not large background fills.
✗
Never use amber as a CTA
Amber is the brand accent and logo detail — not a button colour.
✗
Never mix navy and teal as text
Navy is body text. Teal is interactive. Never both on the same line.
Approved colour combinations
ClearFile
MTD compliance made simple
Navy bg · White primary · White 65% secondary
Hero sections, navigation, dark cards
Submit to HMRC
Primary action button
Teal bg · White text
Primary CTA buttons only
Income this quarter
£8,240.00 confirmed
Off-white bg · Navy heading · Grey-70 body
Main content area, dashboard
Submission confirmed
HMRC reference: MTD-2025-Q2
Green-50 bg · Green-900 heading · Green-600 detail
Success states, confirmed badges
Action needed
14 days until MTD deadline
Amber-50 bg · Amber-900 heading · Amber-600 detail
Warning states, deadline alerts
Sole Trader MTD
£9.99/month
White card · Navy heading + price · Muted label
Pricing cards, feature cards
Typography
Primary typeface
DM Sans
Variable weight · Google Fonts · Free for commercial use
Aa Bb Cc Dd Ee Ff Gg Hh Ii Jj
Kk Ll Mm Nn Oo Pp Qq Rr Ss Tt
0 1 2 3 4 5 6 7 8 9 £ % & @ !
Monospace (code & data)
DM Mono
For UTRs, NINOs, company numbers, API keys, amounts
UTR 1234567890
NI AB 12 34 56 C
CH 12345678 · £9.99/mo
Display40px / 600 / −0.03em
MTD compliance made simple.
H1 — page title24px / 600 / −0.02em
Good morning, Sarah
H2 — section18px / 600 / −0.01em
Q2 2025 quarterly submission
H3 — card title14px / 600 / 0
Income breakdown
Body15px / 400 / 1.6lh
Making Tax Digital is mandatory from April 2026. ClearFile connects to your bank, categorises your transactions automatically, and submits quarterly updates to HMRC on your behalf.
Label / small12px / 600 / +0.04em
INCOME THIS QUARTER
Mono data13px / 400 / DM Mono
UTR 1234567890 · NI AB 12 34 56 C · CH 12345678
Tone of voice
👑
Plain-spoken
No jargon. Explain things as a knowledgeable friend — not an accountant writing to clients.
🔔
Calm urgency
Deadlines matter, but panic helps nobody. Clear about stakes without being alarming.
🔑
Trustworthy
Financial data is sensitive. Always reassure. Never oversell. Be specific about what we do and don't do.
🚀
Empowering
We're on the customer's side. Frame compliance as effortless — a win for them.
HeadlinesShort, benefit-first, no jargon
Do
"MTD compliance for £9.99/month. No accountant required."
"We handle your quarterly HMRC submissions automatically."
Don't
"Unlock seamless MTD-compliant digital tax transformation."
"Leveraging AI to optimise your tax compliance workflow."
UI copy — actionsVerbs first, clear outcome
Do
"Submit to HMRC" · "Review transactions" · "Connect your bank" · "File confirmation statement" · "Start free trial"
Don't
"Proceed" · "Continue to next step" · "Initiate submission" · "Execute filing" · "Commence your journey"
Deadline remindersCalm, factual, action-oriented
Do
"Your Q2 2025 MTD submission is due in 7 days (5 August). Your transactions are ready to review — this takes about 5 minutes."
Don't
"URGENT: You MUST submit your Making Tax Digital return IMMEDIATELY to avoid HMRC penalties and potential prosecution!"
Error messagesExplain what happened and what to do next
Do
"We couldn't connect to your bank. Check your internet connection and try again. If the problem continues, contact
[email protected]"
Don't
"Error 502: Bank connection failed. Code: YAPILY_AUTH_ERR_4. Please retry or contact technical support with your user ID."
Spacing scale
xs
4px
Icon-to-label gaps, badge padding, tight inline spacing
sm
8px
Between list items, form field internal padding, badge groups
md
12px
Card internal gap, between form fields, table row padding
lg
16px
Card padding (mobile), sidebar item padding, grid gutters
xl
24px
Card padding (desktop), section gaps, page margins (mobile)
2xl
32px
Page content padding, major section breaks, modal padding
3xl
48px
Hero padding, between major landing page sections
Border radius
sm · 4px
Badges, pills, chips
md · 8px
Buttons, inputs, rows
lg · 10px
Feature, stat cards
xl · 12px
Dashboard cards, modals
pill · 20px+
Tags, status badges
Icon library — Tabler outline (approved set)
All icons must use the Tabler outline set (prefix ti ti-). Never use filled variants. Always pair with a text label except in established icon-button patterns with aria-label.
home
transactions
submissions
filings
settings
help
bank
AI
deadline
time
confirmed
warning
submit
sync
secure
protected
income
expense
billing
download
external
account
email
reminder
Motion & animation
Micro — hover
100ms ease
Button hover, nav item highlight, card border colour change
Micro — active
80ms ease-in
Button press scale(0.98), checkbox tick appear
Standard
200ms ease
Accordion open/close, tab switch, modal appear
Page transition
150ms ease-out
Route change fade. Never slide — this is not a mobile app.
Progress bar
600ms ease-out
Transaction confirmation progress, onboarding step advance
Success flash
300ms / 2s hold
HMRC confirmed, CS01 filed — green flash then settle
Animate only opacity, transform, and color. Never animate layout properties. Always respect prefers-reduced-motion: reduce.
Writing rules — quick reference
✓
UK English always
"Recognise" not "recognize". "Organised" not "organized". "Colour" not "color". The product is UK-only.
✓
Sentence case for all UI copy
"Submit to HMRC" not "Submit To HMRC". Exception: product names (HMRC, MTD, CS01, Companies House).
✓
£ before numbers, no space
£9.99 · £1,200.00 · £29/year. Always include pence for prices. Commas for thousands.
✓
Dates: D Month YYYY
5 August 2025 · 6 April 2026. Never 05/08/2025 or Aug 5. Always spell the month in UI copy.
✗
Never claim to be an accountant
ClearFile is software. Never say "our accountants" or "we'll file your tax return". Say "we submit your MTD quarterly update".
✗
Never give tax advice
Tax estimates must carry "Estimated — not tax advice." Never say "you owe £X". Say "estimated tax liability ~£X".
✗
Never use passive voice for CTAs
"Your submission will be sent" → "Submit to HMRC". Active verbs only. The system does things.
✗
Never abbreviate on first mention
Always write "Making Tax Digital" in full on first mention per page. MTD acceptable thereafter. Never "M.T.D." or "mtd".