Content-First Web Dev Workflow

Status: Draft structure — validated with sdc.com. Production use begins after workflow refinement.

This document is the single source of truth for the Content-First Web Dev workflow used to build sdc.com and ts.com. It covers all 6 steps plus the monorepo relationship.

The Core Insight

Web development typically starts with UI (design system, components, Tailwind) and treats content as a fill-in-later detail. This workflow inverts that: content and UX come first, formatting and code come last.

This matters because:

The 20% of content that drives 80% of outcomes is clearly identified before any code is written
AI tools are far more effective working on pure Markdown than on HTML/CSS/JSX
Role separation is enforced structurally — CMO doesn’t need to touch code; dev doesn’t need to manage content strategy

Monorepo Relationship

This workflow is a companion to the monorepo — not a replacement.

Layer	Tool	Responsibility
Content strategy & drafting	Obsidian vaults (`content-high-level`, `content-all`)	What to say and to whom
Schema enforcement	Keystatic (in monorepo)	Structured MDX, collection validation
UI & functionality	Astro + Tailwind + SvelteKit (monorepo)	How it looks and works
Testing ground	`sites/Template/` in monorepo	All components validated here before production use
Deployment	Monorepo CI/CD pipeline	Build, test, ship

The Template site (sites/Template/) is the development reference. All new components, layouts, and functionality are built and tested there first. When content is ready to render (Step 5), the monorepo already has production-ready components waiting.

Workflow at a Glance

Step	Name	Tool	Input	Output	Transition Criterion
0	Business Foundation	KB / Obsidian	—	ICP, USP, mission, brand voice	Strategy is stable
1+2	Core Content + UX	`content-high-level` vault	Step 0 outputs	Core pages + wikilink UX prototype	All core pages `status: review`
0.5	AI Content Expansion	`/content-expand` skill	`content-high-level` vault	Tighter copy, stronger CTAs	Core pages `status: approved`
3	All Content + Schema	`content-all` vault + Keystatic	Approved core pages	All pages in Astro collections, schemas valid	All pages in Keystatic; `pnpm typecheck` passes
4	Localization	GitHub Actions + Claude API	Approved MDX	`/[locale]/` MDX files	Only if/when needed
5	UI	Astro + Tailwind (monorepo)	Keystatic MDX	Rendered, styled site	Visual + responsive QA passes
6	Review	Checklist below	Live site	Sign-off	All checklist items green

Step 0 — Business Foundation

Tool: KB Obsidian vault (KB/Business/02_Strategy/) Who: Founder / CMO

Define and stabilize:

Ideal Client Profile (ICP)
Unique Selling Proposition (USP) + brand voice
Mission statement
Core business model (what, why, for whom)
Key Success Factors, SWOT

Transition: Strategy docs are stable. Extracted references placed in _00_strategy/ in the content vaults (read-only during content work).

Steps 1 + 2 — Core Content + UX Prototype

Tool: content-high-level Obsidian vault Location: D:\FSS\Websites\SDC.com\content-high-level\ Who: CMO / founder

Step 1: Core Content

Write the 20% of pages that deliver 80% of the value — in pure Markdown, no code, no UI decisions:

Homepage
Primary audience pages (advisors, investors)
About
Key educational content (e.g., smart-debt-myths)

Each page uses the standard frontmatter schema (type, audience, phase, status, slug, description, cta_primary).

Step 2: Core UX

Use wikilinks ([[page-name]]) to prototype the critical user journeys:

Stranger → visitor → interested prospect → client → happy client
Nav component links all pages
CTAs link to the next logical step

The wikilinks ARE the UX prototype. Click through pages in Obsidian as if you’re a visitor.

Transition: All core pages at status: review. Wikilinks all resolve. CMO satisfied with the narrative flow.

Step 0.5 — AI Content Expansion

Tool: /content-expand Claude Code skill Who: AI (Claude Code or Gemini CLI)

Run after Steps 1+2, before Keystatic import. AI reads the vault, tightens copy, and verifies CTA alignment.

Invoke:

/content-expand D:\FSS\Websites\SDC.com\content-high-level

What it does:

Reads all pages/ and components/ in the vault
References _00_strategy/ICP.md and USP.md for alignment
For each status: draft or review file: tightens headlines, sharpens body copy, verifies primary CTA
Reports changes per file — asks for confirmation before writing anything

Transition: All core pages at status: approved. Human has confirmed each change.

Step 3 — All Content + Schema

Tools: content-all Obsidian vault + Keystatic Locations:

Vault: D:\FSS\Websites\SDC.com\content-all\
Keystatic config: monorepo/sites/sdc.com/keystatic.config.ts Who: Junior team member or AI (CMO does not need to be involved)

3a: Secondary Content (content-all vault)

Add all remaining pages and components:

Blog index, Contact, Pricing, FAQ
Footer, social proof, email capture
Any locale-specific variants (if known in advance)

3b: Keystatic Import

Once content is approved in both vaults, import to Keystatic:

Install Keystatic: pnpm add @keystatic/core @keystatic/astro
Add Keystatic integration to astro.config.mjs
Uncomment keystatic.config.ts (currently fully commented — see file)
Run Keystatic locally: pnpm dev
Import/paste MDX content into Keystatic UI
Validate schema: pnpm typecheck

Transition: All pages in Keystatic collections. pnpm typecheck passes with no errors.

Step 4 — Localization (Skeleton — Not Yet Implemented)

Tools: GitHub Actions + Claude API Location: .github/workflows/localize.yml (manual trigger only — disabled) Who: Dev (one-time setup); AI handles translation

When to activate

Only when a second locale is needed. Current target: English only.

How it works (when activated)

Approved MDX files from Step 3 are the translation source
GitHub Action calls Claude API with the translation prompt template
Translated MDX is written to /[locale]/ routes in the monorepo
No manual side-by-side CMS translation UI needed

Prompt template: D:\FSS\Websites\SDC.com\content-all\_templates\translate-prompt.md

To activate:

Implement sites/sdc.com/scripts/translate.ts (stub in workflow comments)
Add ANTHROPIC_API_KEY secret to GitHub repo settings
Change workflow trigger from workflow_dispatch to desired branch trigger
Remove the ## DISABLED comment in the workflow file

Step 5 — UI

Tools: Astro + Tailwind (monorepo sites/sdc.com/) Who: Dev

At this point, all content is structured MDX in Keystatic. Dev renders it using Astro components that were already tested in sites/Template/.

Process:

Reference sites/Template/ for validated component patterns
Build Astro pages that consume Keystatic content collections
Apply design tokens from @smart-debt/design-tokens workspace package
Mobile-first: build at 390px, scale up

Quality bar:

Mobile responsive (390px, 768px, 1280px)
Dark mode (if applicable)
WCAG AA contrast
Lighthouse score ≥ 90

Step 6 — Review

Who: CMO + dev

Review Checklist

Content–UI Alignment

Every page’s headline matches the intent from content-high-level
All CTAs are visible above the fold on mobile
No placeholder text remains in production build

SEO / Meta

Every page has a unique <title> and <meta description>
description frontmatter field is populated for all pages
Canonical URLs correct
sitemap.xml generated

CTA Coverage

Every page has at least one primary CTA
Core pages (home, advisors, investors) have a CTA in the hero
All CTAs link to valid, live pages

Mobile / Responsive

No horizontal scroll on any page at 390px
Touch targets ≥ 44x44px
Text is readable without zooming (≥ 16px base)

Accessibility

WCAG AA color contrast on all text/background combinations
All images have descriptive alt text
Keyboard navigation works (Tab, Enter, Escape)
Screen reader: headings are in logical order (h1 → h2 → h3)

Performance

Lighthouse Performance score ≥ 90 (mobile)
No render-blocking resources
Images are optimized (Astro <Image /> component)

Compliance

Footer includes compliance/disclaimer text
No “risk-free” or guaranteed-returns language anywhere
Privacy policy linked in footer

Sign-off: All items green before launch.

A/B Testing

Content-first structure makes A/B testing far more efficient than UI-first workflows — variants are pure Markdown, drafting is fast, and the frontmatter schema carries the test metadata directly into Astro.

How It Works

Step 1: Define the hypothesis — Create a test file in _ab-tests/:

content-high-level/_ab-tests/hero-headline-advisors.md

Document: what you’re testing, why, and what “winning” looks like.

Step 2: Draft variants — Create variant files alongside the control:

# pages/advisors.md  (existing file = control)
variant: control
ab_test_id: "hero-headline-v1"

# pages/advisors-A.md  (new file = variant A)
variant: A
ab_test_id: "hero-headline-v1"

Only the tested element changes — everything else is identical.

Step 3: Import to Keystatic — Both variants appear in the Keystatic UI with their ab_test_id and variant fields.

Step 4: Astro rendering — The Astro page reads ab_test_id and variant from the content collection. The edge layer (Vercel Edge Functions, Cloudflare Workers) handles traffic splitting — 50% of visitors see control, 50% see variant A.

Step 5: Measure — PostHog or Plausible Goals tracks conversions per variant. Minimum sample sizes apply (see test files for thresholds).

Step 6: Record learnings — File a _learnings/ note. Update journey maps if the result changes your understanding of the audience.

Test Tracking

File	Purpose
`content-high-level/_ab-tests/_template.md`	Template for new tests
`content-high-level/_ab-tests/hero-headline-advisors.md`	First test (advisor hero)
`content-all/_ab-tests/_template.md`	Template for secondary page tests
`content-all/_learnings/_template.md`	Template for recording results

High-Value Tests to Run (Priority Order)

Advisor hero headline — “client-first framework” vs. “grow your book” messaging
Investor Snapshot CTA placement — hero vs. after explanation
“Borrowing to invest” vs. “$MART DEBT” — terminology preference by audience
Advisor CTA label — “Book a Call” vs. “Start Free Trial”

Journey Maps

Journey maps are strategic documents in content-high-level/_journeys/ that define the intended user paths — from stranger to happy client. They inform which content is needed at each stage and where A/B tests will have the most impact.

File	Audience	Key conversion
`_journeys/advisor-journey.md`	Financial advisors	Book a Call → platform user
`_journeys/investor-journey.md`	Individual investors	Snapshot complete → advisor referral

Read journey maps before designing any page. They answer: “what does this person need at this moment in their relationship with SDC?”

Performance Feedback Loop

The workflow completes a full cycle when live performance data feeds back into content strategy:

Strategy (Step 0) → Content (Steps 1–3) → Live Site (Steps 4–6)
                                    ↑                    |
                              _learnings/  ←  Analytics + Feedback

Where learnings live: content-all/_learnings/

Each learning file captures: what was observed, what it tells us about the audience, ICP/USP implications, and action taken. Over time, this folder becomes the institutional memory of what works — Git-tracked, AI-readable.

Feedback sources (current and future):

Source	Status	Where captured
A/B test results	Ready (at Step 5)	`_ab-tests/` + `_learnings/`
Plausible/PostHog analytics	Ready (at Step 5)	`_learnings/`
Advisor feedback	Manual	`_learnings/`
Investor Snapshot completion rates	Future	`_learnings/`
Visitor session recordings	Future (Step 7+)	`_learnings/`
Security scan results	Future (Step 7+)	Monorepo CI/CD

Future Pipeline Extensions (Step 7+)

This workflow is intentionally extensible. Planned additions after the core workflow is validated:

Extension	Purpose	When
Security scanning	Automated OWASP checks in CI/CD	Before first production deploy
Uptime monitoring	Alert on downtime, performance regression	At launch
Visitor session recording	Understand real user behavior (Hotjar, PostHog)	After 100+ visitors
Visitor feedback widget	Collect qualitative signal directly on pages	After launch
Conversion funnel analysis	Identify drop-off points in advisor/investor journeys	After 1000+ visitors
Content calendar	Schedule blog posts, test launches	When publishing velocity matters

A full end-to-end pipeline document (from content to monitoring) is planned as a separate artifact.

File Locations

Asset	Location
Core content vault	`D:\FSS\Websites\SDC.com\content-high-level\`
All content vault	`D:\FSS\Websites\SDC.com\content-all\`
Keystatic config	`monorepo/sites/sdc.com/keystatic.config.ts`
Localize workflow	`monorepo/.github/workflows/localize.yml`
Translation prompt	`D:\FSS\Websites\SDC.com\content-all\_templates\translate-prompt.md`
`/content-expand` skill	`~/.claude/commands/content-expand.md`
Template site (test ground)	`monorepo/sites/Template/`
A/B test tracking	`content-high-level/_ab-tests/`, `content-all/_ab-tests/`
Journey maps	`content-high-level/_journeys/`
Performance learnings	`content-all/_learnings/`

AI Tools in This Workflow

AI is effective at every stage:

Step	AI Use
0	Strategy refinement, ICP research
1+2	Content drafting, wikilink structure
0.5	Copy expansion, CTA alignment (`/content-expand`)
3	Secondary content generation, schema validation
4	Automated translation (Claude API)
5	Component code generation from content specs
6	Automated accessibility + SEO checks

Efficiency advantage: All AI work in Steps 1–3 is on pure Markdown — dramatically lower token cost and higher quality than working on rendered HTML/CSS.