Source Sans 3 Typography Implementation Plan
Source Sans 3 Typography Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Self-host Source Sans 3 and use it consistently for the site’s body text, headings, navigation, publication entries, and sidebar text.
Architecture: Add Adobe’s official upright and italic variable WOFF2 files plus their SIL Open Font License under assets/fonts/. Declare one shared web-font family in a focused Sass partial, then place that family first in the theme’s existing $sans-serif stack so all current consumers inherit it without layout-specific overrides.
Tech Stack: Jekyll, Sass/SCSS, PowerShell, WOFF2 variable fonts
File Map
- Create
test/typography_test.ps1: executable typography contract covering assets, license, Sass declarations, import order, and fallback stack. - Create
assets/fonts/SourceSans3VF-Upright.ttf.woff2: official upright Source Sans 3 variable web font. - Create
assets/fonts/SourceSans3VF-Italic.ttf.woff2: official italic Source Sans 3 variable web font. - Create
assets/fonts/source-sans-3-LICENSE.md: official SIL Open Font License distributed with the font files. - Create
_sass/_fonts.scss: local@font-facedeclarations only. - Modify
assets/css/main.scss: import the font declarations after variables and before base rules. - Modify
_sass/_variables.scss: replace the current Palatino-led$sans-serifstack with the approved Source Sans 3 and system/CJK fallback stack.
Task 1: Add a Failing Typography Contract
Files:
Create:
test/typography_test.ps1Step 1: Write the failing test
$ErrorActionPreference = "Stop"
$repoRoot = Split-Path -Parent $PSScriptRoot
function Assert-True {
param(
[bool]$Condition,
[string]$Message
)
if (-not $Condition) {
throw $Message
}
}
$uprightPath = Join-Path $repoRoot "assets/fonts/SourceSans3VF-Upright.ttf.woff2"
$italicPath = Join-Path $repoRoot "assets/fonts/SourceSans3VF-Italic.ttf.woff2"
$licensePath = Join-Path $repoRoot "assets/fonts/source-sans-3-LICENSE.md"
$fontsScssPath = Join-Path $repoRoot "_sass/_fonts.scss"
$variablesPath = Join-Path $repoRoot "_sass/_variables.scss"
$mainScssPath = Join-Path $repoRoot "assets/css/main.scss"
foreach ($fontPath in @($uprightPath, $italicPath)) {
Assert-True (Test-Path -LiteralPath $fontPath -PathType Leaf) "Missing font file: $fontPath"
Assert-True ((Get-Item -LiteralPath $fontPath).Length -gt 10000) "Font file is unexpectedly small: $fontPath"
}
Assert-True (Test-Path -LiteralPath $licensePath -PathType Leaf) "Missing Source Sans 3 license"
Assert-True (Test-Path -LiteralPath $fontsScssPath -PathType Leaf) "Missing font-face Sass partial"
$license = Get-Content -Raw -LiteralPath $licensePath
$fontsScss = Get-Content -Raw -LiteralPath $fontsScssPath
$variables = Get-Content -Raw -LiteralPath $variablesPath
$mainScss = Get-Content -Raw -LiteralPath $mainScssPath
Assert-True ($license -match "SIL OPEN FONT LICENSE Version 1\.1") "Unexpected font license"
Assert-True (($fontsScss | Select-String -Pattern 'font-family:\s*"Source Sans 3"' -AllMatches).Matches.Count -eq 2) "Expected upright and italic Source Sans 3 declarations"
Assert-True ($fontsScss -match "SourceSans3VF-Upright\.ttf\.woff2") "Missing upright font source"
Assert-True ($fontsScss -match "SourceSans3VF-Italic\.ttf\.woff2") "Missing italic font source"
Assert-True (($fontsScss | Select-String -Pattern "font-display:\s*swap" -AllMatches).Matches.Count -eq 2) "Both font faces must use font-display: swap"
Assert-True ($fontsScss -match "font-weight:\s*200 900") "Variable weight range is missing"
Assert-True ($mainScss -match '@import "variables";\s*@import "fonts";') "Fonts must be imported after variables"
Assert-True ($variables -match '\$sans-serif\s*:\s*"Source Sans 3", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", Arial, sans-serif;') "Unexpected sans-serif fallback stack"
Write-Output "Typography contract passed."
- Step 2: Run the test and verify the expected failure
Run:
powershell -NoProfile -ExecutionPolicy Bypass -File test/typography_test.ps1
Expected: nonzero exit with Missing font file: ...SourceSans3VF-Upright.ttf.woff2.
- Step 3: Commit the failing test
git add test/typography_test.ps1
git commit -m "test: define Source Sans typography contract"
Task 2: Add the Licensed Font Assets
Files:
- Create:
assets/fonts/SourceSans3VF-Upright.ttf.woff2 - Create:
assets/fonts/SourceSans3VF-Italic.ttf.woff2 Create:
assets/fonts/source-sans-3-LICENSE.md- Step 1: Download the official upright variable WOFF2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/adobe-fonts/source-sans/release/WOFF2/VF/SourceSans3VF-Upright.ttf.woff2" -OutFile "assets/fonts/SourceSans3VF-Upright.ttf.woff2"
Expected: assets/fonts/SourceSans3VF-Upright.ttf.woff2 exists and is larger than 10 KB.
- Step 2: Download the official italic variable WOFF2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/adobe-fonts/source-sans/release/WOFF2/VF/SourceSans3VF-Italic.ttf.woff2" -OutFile "assets/fonts/SourceSans3VF-Italic.ttf.woff2"
Expected: assets/fonts/SourceSans3VF-Italic.ttf.woff2 exists and is larger than 10 KB.
- Step 3: Download the official license
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/adobe-fonts/source-sans/release/LICENSE.md" -OutFile "assets/fonts/source-sans-3-LICENSE.md"
Expected: the downloaded file contains SIL OPEN FONT LICENSE Version 1.1.
- Step 4: Re-run the contract and verify it reaches the next missing component
Run:
powershell -NoProfile -ExecutionPolicy Bypass -File test/typography_test.ps1
Expected: nonzero exit with Missing font-face Sass partial.
- Step 5: Commit the font assets
git add assets/fonts/SourceSans3VF-Upright.ttf.woff2 assets/fonts/SourceSans3VF-Italic.ttf.woff2 assets/fonts/source-sans-3-LICENSE.md
git commit -m "assets: self-host Source Sans 3"
Task 3: Declare and Apply Source Sans 3
Files:
- Create:
_sass/_fonts.scss - Modify:
assets/css/main.scss - Modify:
_sass/_variables.scss Test:
test/typography_test.ps1- Step 1: Add the upright and italic variable font declarations
Create _sass/_fonts.scss:
/* ==========================================================================
Local web fonts
========================================================================== */
@font-face {
font-family: "Source Sans 3";
font-style: normal;
font-weight: 200 900;
font-display: swap;
src: url("../fonts/SourceSans3VF-Upright.ttf.woff2") format("woff2");
}
@font-face {
font-family: "Source Sans 3";
font-style: italic;
font-weight: 200 900;
font-display: swap;
src: url("../fonts/SourceSans3VF-Italic.ttf.woff2") format("woff2");
}
- Step 2: Import the font partial
In assets/css/main.scss, change:
@import "variables";
@import "mixins";
to:
@import "variables";
@import "fonts";
@import "mixins";
- Step 3: Replace the shared sans-serif stack
In _sass/_variables.scss, replace the commented historical system stack and current Palatino-led stack with:
$sans-serif : "Source Sans 3", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans SC", "Microsoft YaHei", Arial, sans-serif;
Leave $serif, $monospace, $sans-serif-narrow, $global-font-family, and $header-font-family otherwise unchanged so existing selectors inherit the new family.
Do not edit the type-scale variables, line heights, colors, spacing rules, _sass/vendor/font-awesome/, or code typography. These remain outside the change set, preserving the existing layout and Font Awesome/monospace declarations.
- Step 4: Run the typography contract and verify it passes
Run:
powershell -NoProfile -ExecutionPolicy Bypass -File test/typography_test.ps1
Expected:
Typography contract passed.
- Step 5: Commit the Sass implementation
git add _sass/_fonts.scss _sass/_variables.scss assets/css/main.scss
git commit -m "style: apply Source Sans 3 typography"
Task 4: Build and Inspect the Generated Site
Files:
Verify:
_site/assets/css/main.cssStep 1: Build the development site
Run:
bundle exec jekyll build --config _config.yml,_config.dev.yml
Expected: exit code 0 with done in in the final Jekyll output.
- Step 2: Verify the generated stylesheet
Run:
$css = Get-Content -Raw "_site/assets/css/main.css"
if ($css -notmatch 'font-family:\s*"Source Sans 3"') { throw "Generated CSS is missing Source Sans 3" }
if ($css -notmatch "SourceSans3VF-Upright\.ttf\.woff2") { throw "Generated CSS is missing the upright font URL" }
if ($css -notmatch "SourceSans3VF-Italic\.ttf\.woff2") { throw "Generated CSS is missing the italic font URL" }
if ($css -notmatch "font-display:\s*swap") { throw "Generated CSS is missing font-display: swap" }
Write-Output "Generated typography CSS passed."
Expected:
Generated typography CSS passed.
- Step 3: Verify the full change set
Run:
powershell -NoProfile -ExecutionPolicy Bypass -File test/typography_test.ps1
git diff --check
git status --short
Expected: typography contract passes, git diff --check has no output, and status lists only the intended font, Sass, test, specification, and plan files.
- Step 4: Commit the verified documentation
git add docs/superpowers/specs/2026-07-30-source-sans-3-typography-design.md docs/superpowers/plans/2026-07-30-source-sans-3-typography.md
git commit -m "docs: record Source Sans typography design"
