feat(templates): migrate portfolio to the semantic theme-token architecture (emdash-cms#1733)

* feat(templates): migrate portfolio to the semantic theme-token architecture

Same treatment as blog/marketing: tokens move to src/styles/tokens.css
as @layer base defaults with light-dark() colors and a @supports
fallback for pre-light-dark browsers; theme.css becomes a pure override
file; the theme switcher pins color-scheme instead of maintaining
triplicated palettes. Semantic names: --font-heading (was --font-serif,
incl. astro.config cssVariable in both variants), --font-body (was
--font-sans), --color-brand (was --color-accent) with --color-on-brand
and --color-brand-ring replacing hardcoded white and the frozen violet
focus ring, and --color-danger fixing form errors that ignored the
theme toggle. Adds weight/leading/tracking tokens, drops the unused
--color-accent-muted and --font-mono, and strips ProjectCard's inline
var() fallbacks that would mask a broken token.

* fix(templates): guard portfolio color-scheme pins behind @supports

Same fix as on the blog/marketing branch: without the guard, browsers
on the plain-light fallback palette get dark UA form controls when the
toggle sets the dark cookie.

Author: ascorbic

templates/portfolio-cloudflare/AGENTS.md

@@ -71,30 +71,34 @@ The `gallery` field on `projects` is a JSON field, not an EmDash image field. It
 
 ## Visual character
 
-Typography is the design. The display face is **Playfair Display** (serif) on the `--font-serif` CSS variable; the body face is the system sans stack on `--font-sans`. The serif is used for the site title, hero titles, project titles, page titles, and contact column labels. Everything else is the sans.
+Typography is the design. The display face is **Playfair Display** (serif) on the `--font-heading` CSS variable; the body face is the system sans stack on `--font-body`. The serif is used for the site title, hero titles, project titles, page titles, and contact column labels. Everything else is the sans. Serif weight is calm on purpose (`--font-weight-heading` and `--font-weight-display` both default to 500).
 
-The accent colour is barely visible by design -- the only saturated colour on the page should be inside images. The default `--color-accent` (`#7c3aed`) is used sparingly for link hover and focus states.
+The brand colour is barely visible by design -- the only saturated colour on the page should be inside images. The default `--color-brand` (`#7c3aed`) is used sparingly for link hover and focus states.
 
 Whitespace is generous. Sections breathe. Don't fight that.
 
 ## Customisation
 
-`src/styles/theme.css` is the only file to edit for visual changes. Every CSS variable from `Base.astro` is listed there as a commented default -- uncomment and change to override. The dark mode palette is defined inside `Base.astro` itself; light-mode overrides in `theme.css` won't affect dark mode. To customise dark mode, add `@media (prefers-color-scheme: dark)` and `:root.dark` rules in `theme.css`.
+Design tokens live in `src/styles/tokens.css` with their default values. To restyle the site, override tokens in `src/styles/theme.css` -- declarations there are unlayered, so they always beat the `@layer base` defaults. Don't edit `tokens.css` or `Base.astro` for visual changes.
 
-Fonts are configured in `astro.config.mjs` under `fonts:` (the Astro Fonts API). To change the display face, swap the `name:` for any Google Fonts serif and keep `cssVariable: "--font-serif"`. Good pairings: Cormorant Garamond, Fraunces, EB Garamond, DM Serif Display. Avoid changing the body font unless you have a reason -- system sans is deliberately quiet here.
+Colours are defined with `light-dark(<light>, <dark>)`, so each token carries both modes. Overriding with a plain colour changes light and dark at once; use `light-dark()` in the override to keep them distinct. There is no separate dark palette to maintain.
 
-CSS variables worth knowing:
+The display face is configured in `astro.config.mjs` under `fonts:` (the Astro Fonts API). To change it, swap the `name:` for any Google Fonts serif and keep `cssVariable: "--font-heading"`. Good pairings: Cormorant Garamond, Fraunces, EB Garamond, DM Serif Display. The body face (`--font-body`) is a plain token in `tokens.css` -- system sans, deliberately quiet; override it in `theme.css` only if you have a reason.
 
-- `--color-accent` / `--color-accent-muted` -- the single accent, used very sparingly
+CSS variables worth knowing (see `tokens.css` for the full list):
+
+- `--color-brand`, `--color-on-brand`, `--color-brand-ring` -- the single accent, used very sparingly
 - `--color-bg`, `--color-surface`, `--color-text`, `--color-muted`, `--color-border` -- neutral palette
-- `--font-serif`, `--font-sans` -- bound to the Fonts API entries in `astro.config.mjs`
+- `--color-danger` -- form errors
+- `--font-heading` (Fonts API entry in `astro.config.mjs`), `--font-body` (token)
+- `--font-weight-heading` / `--font-weight-display` (both 500) -- raise for a heavier serif voice
 - `--font-size-4xl` -- the size of the homepage title and project titles
 - `--max-width` (720px), `--wide-width` (1200px) -- column widths
 
 ## What not to do
 
 - Don't introduce gradients, drop shadows on cards, or coloured section backgrounds. The template's voice is calm and editorial; those break it.
-- Don't change `--font-sans` to a display font. Two display faces fight each other.
+- Don't change `--font-body` to a display font. Two display faces fight each other.
 - Don't add more than one accent colour.
 - Don't write generic copy like "Welcome to my portfolio" or "Crafting beautiful experiences". The work should speak; the words should be specific (a client name, a discipline, a year).
 - Don't pack the home page with every project. The "Selected Work" framing is intentional -- 3-6 is plenty.

templates/portfolio-cloudflare/astro.config.mjs

@@ -22,7 +22,7 @@ export default defineConfig({
 		{
 			provider: fontProviders.google(),
 			name: "Playfair Display",
-			cssVariable: "--font-serif",
+			cssVariable: "--font-heading",
 			weights: [400, 500, 600, 700],
 			fallbacks: ["serif"],
 		},

templates/portfolio-cloudflare/src/components/ProjectCard.astro

@@ -56,23 +56,23 @@ const allTags = [...(categories || []), ...(tags || [])];
 	.card-link {
 		display: flex;
 		flex-direction: column;
-		gap: var(--spacing-lg, 1.5rem);
+		gap: var(--spacing-lg);
 		text-decoration: none;
 		color: inherit;
 	}
 
 	.card-image {
 		position: relative;
 		overflow: hidden;
-		border-radius: var(--radius, 4px);
+		border-radius: var(--radius);
 	}
 
 	.card-image img {
 		width: 100%;
 		height: auto;
 		aspect-ratio: 4 / 3;
 		object-fit: cover;
-		transition: transform var(--transition-slow, 300ms ease);
+		transition: transform var(--transition-slow);
 	}
 
 	.card-overlay {
@@ -82,21 +82,22 @@ const allTags = [...(categories || []), ...(tags || [])];
 		align-items: center;
 		justify-content: center;
 		background: rgba(0, 0, 0, 0);
-		transition: background var(--transition-base, 200ms ease);
+		transition: background var(--transition-base);
 	}
 
+	/* Over-image chip: white regardless of theme */
 	.card-view {
-		font-family: var(--font-serif, Georgia, serif);
-		font-size: var(--font-size-sm, 0.875rem);
+		font-family: var(--font-heading);
+		font-size: var(--font-size-sm);
 		color: white;
-		padding: var(--spacing-sm, 0.5rem) var(--spacing-md, 1rem);
+		padding: var(--spacing-sm) var(--spacing-md);
 		border: 1px solid white;
-		border-radius: var(--radius, 4px);
+		border-radius: var(--radius);
 		opacity: 0;
 		transform: translateY(10px);
 		transition:
-			opacity var(--transition-base, 200ms ease),
-			transform var(--transition-base, 200ms ease);
+			opacity var(--transition-base),
+			transform var(--transition-base);
 	}
 
 	.project-card:hover .card-image img {
@@ -115,33 +116,33 @@ const allTags = [...(categories || []), ...(tags || [])];
 	.card-content {
 		display: flex;
 		flex-direction: column;
-		gap: var(--spacing-xs, 0.25rem);
+		gap: var(--spacing-xs);
 	}
 
 	.card-title {
-		font-family: var(--font-serif, Georgia, serif);
-		font-size: var(--font-size-xl, 1.5rem);
-		font-weight: 500;
-		transition: color var(--transition-fast, 150ms ease);
+		font-family: var(--font-heading);
+		font-size: var(--font-size-xl);
+		font-weight: var(--font-weight-heading);
+		transition: color var(--transition-fast);
 	}
 
 	.project-card:hover .card-title {
-		color: var(--color-accent, #7c3aed);
+		color: var(--color-brand);
 	}
 
 	.card-meta {
-		font-size: var(--font-size-sm, 0.875rem);
-		color: var(--color-muted, #6b7280);
+		font-size: var(--font-size-sm);
+		color: var(--color-muted);
 	}
 
 	.card-separator {
-		margin: 0 var(--spacing-xs, 0.25rem);
+		margin: 0 var(--spacing-xs);
 	}
 
 	.card-summary {
-		font-size: var(--font-size-sm, 0.875rem);
-		color: var(--color-muted, #6b7280);
-		line-height: 1.6;
+		font-size: var(--font-size-sm);
+		color: var(--color-muted);
+		line-height: var(--leading-normal);
 		display: -webkit-box;
 		-webkit-line-clamp: 2;
 		-webkit-box-orient: vertical;
@@ -151,17 +152,17 @@ const allTags = [...(categories || []), ...(tags || [])];
 	.card-categories {
 		display: flex;
 		flex-wrap: wrap;
-		gap: var(--spacing-sm, 0.5rem);
-		margin-top: var(--spacing-sm, 0.5rem);
+		gap: var(--spacing-sm);
+		margin-top: var(--spacing-sm);
 	}
 
 	.card-category {
-		font-size: 0.75rem;
+		font-size: var(--font-size-xs);
 		text-transform: uppercase;
-		letter-spacing: 0.05em;
-		color: var(--color-muted, #6b7280);
-		padding: var(--spacing-xs, 0.25rem) var(--spacing-sm, 0.5rem);
-		border: 1px solid var(--color-border, #e5e7eb);
-		border-radius: var(--radius, 4px);
+		letter-spacing: var(--tracking-wide);
+		color: var(--color-muted);
+		padding: var(--spacing-xs) var(--spacing-sm);
+		border: 1px solid var(--color-border);
+		border-radius: var(--radius);
 	}
 </style>