Courierflow Ui

Design System Tokens

Always use var(--ds-*) variables:

Variables file: app/static/css/design-system/_variables.css

Page headers in hybrid pages (Vue/Alpine + Jinja): When the page uses a JS framework that mounts in a sub-container, the .page-header-standard must be placed OUTSIDE the framework mount point so it renders immediately (no FOUC). The JS app then bridges to header elements via getElementById. See builder.html for the canonical example.

"Quiet Elegance" Principles

• Monochrome First — Slate palette dominates; color for sparing semantic emphasis
• Inter Only — One font family (--ds-font-family). No Poppins.
• White + Shadow Buttons — Primary = bg-white border shadow-sm, not bg-slate-900
• Subtle Semantic Badges — Desaturated emerald/amber/red, not pure monochrome
• Content over Chrome — Spacing and background tints separate sections, not borders

Template Blocks

Use exact names from base.html:

• extra_css — Additional stylesheets
• extra_scripts — Additional JavaScript
• page_title — Page title
• content — Main content

Cache Busting

Format: ?v=YYYYMMDD[letter] (e.g., ?v=20260306b)

When changing CSS/JS:

1. Bump ?v= param on all <link>/<script> tags referencing the file
2. Bump CACHE_NAME in app/static/sw.js

Verification after deploy: If CSS changes do not appear on the live site after deploy, first check that the ?v= param was bumped, then check Railway build status (builds may be failing silently). Use WebFetch against the live URL to compare deployed CSS with the repo version.

Logo & Favicon Asset Pipeline

Source: app/static/images/courier_transparent.png (RGBA).

Refresh procedure documented in MEMORY: pattern_logo_and_favicon_asset_pipeline.md. Key points:

• Generate variants courier{,_transparent}{,-medium,-thumbnail}.{png,webp,jpeg} so legacy filenames update together.
• macOS sips cannot output WebP — use .venv/bin/python3 + Pillow.
• Bump ?v=YYYYMMDD[letter] on every nav-logo <img> and favicon <link> in base.html. Landing pages reference assets without ?v= and pick up new files automatically.
• Logo size lives in app/static/css/components/_navigation.css (.cf-nav-logo). Anchor percentage bumps to the original baseline, not the current size.

Required favicon <link> tags in base.html

base.html MUST include the four favicon link tags (favicon.ico, favicon-16x16.png, favicon-32x32.png, apple-touch-icon.png) immediately after <link rel="manifest">. errors/404.html previously had them while base.html did not — this was a latent SEO/UX bug fixed in PR #309. Verify presence on any new layout file that doesn't extend base.html.

Service Worker

• Network-first for CSS/JS — Cache is offline fallback only
• Cache-first causes stale deploys that survive ?v= bumps

Landing Pages Exception

landing/index.html, landing/features.html, landing/pricing.html:

• Extend landing_base.html, NOT base.html
• Load their own CSS independently
• Design-system layers do not apply

CSS Grid Patterns

• Equal-width columns: Always use repeat(N, minmax(0, 1fr)) instead of repeat(N, 1fr). Plain 1fr allows content (long text, images) to inflate individual columns beyond their fair share. minmax(0, 1fr) constrains the minimum to 0, forcing truly equal widths.
• Equal-height rows: For grids that need uniform row heights (calendars, dashboards), set grid-auto-rows: minmax(<min>, 1fr) so rows do not size to content. Without this, rows with more content appear taller than empty rows.

Before Creating New CSS

Check if existing component/page file already covers the need.

Dead CSS → _archived/css/ Dead templates → _archived/templates/