design-token-css

name	design-token-css
description	Styling for the server-rendered / no-build stacks (php, vanilla-flask): a token-driven CSS sheet themed per-run by editing one `:root` variable block. Invoke on these stacks to give each lab a distinctive, coherent, believable look — different every run — without a build step.

design-token-css skill

Applies to php and vanilla-flask — no build step, so styling is one shared CSS sheet driven by CSS variables.

Goal: each lab should look like a real product with a genuinely different look every run — not the same default blue, not generic AI slop.

Commit to ONE bold direction first (before coding)

Pick one aesthetic direction and execute it with intentionality. Refined minimalism and bold maximalism both win — what matters is a clear point-of-view. Options (full hex token/font/texture recipes in references/aesthetic-directions.md):

refined/luxury · brutally minimal · brutalist/raw · retro-futuristic · organic/natural · editorial/magazine · playful/toy · industrial/utilitarian · soft/pastel · art-deco/geometric · glassmorphism · claymorphism · dark academia · memphis/80s-pop · signal (deep-navy & gold)

Decide up front: light or dark, the dominant brand color + one sharp accent, the radius scale, and a font pairing (display + body). Then encode those decisions in the token block. Never converge on the same choices run to run.

Where the styling lives (already in the template — don't re-create)

• php: public/app.css, linked from the single shared layout render_page() in src/auth.php. Every page uses it.
• vanilla-flask: static_assets/style.css, linked from index.html.

Both ship a canonical sheet whose component rules (nav, .card, .btn, input, table, .alert) consume an AGENT THEME TOKENS :root block.

Theme per-run via tokens (the only thing you edit to re-skin)

Edit only the :root { … } token block. The component rules stay fixed. Tokens are hex/value based (not HSL):

--font-sans     /* a serif/display stack changes the feel most */
--radius        /* small = crisp, large = soft (0px..22px) */
--bg --surface --text --muted --border
--brand --brand-hover            /* primary / nav / CTA */
--on-brand --on-brand-muted      /* text ON the brand-colored nav */

Set the product brand name: the $brand arg to render_page() (php) or the .brand text in index.html (vanilla) — invent a domain-fitting name, not the spec's lab id.

Allowed creative edits, beyond the colors: a single web-font @import at the top of the CSS file (+ optional --font-display token used by a global heading rule); a few extra tokens added to :root (e.g. --accent, --shadow, --app-bg) referenced from global rules; and atmosphere (gradient-mesh --app-bg, grain overlay) instead of a flat background — all in references/aesthetic-directions.md and references/component-snippets.md.

Vary the composition, not just the color

Same data, different shape. references/component-snippets.md is a copy-paste library of token-only building blocks — hero/header treatments, stat tiles, card variations, list rows (vs tables), badges/pills, empty states, split auth screens, and a one-shot staggered page-load reveal. Mix a different selection each run so two labs with the same data don't look the same.

Icons & imagery

These stacks can't npm install an icon pack, but real photos make a lab feel like a product — use both:

• Icons → inline SVG. Paste small <svg> glyphs (a 20–24px viewBox, fill="none" stroke="currentColor") directly into the markup; currentColor tints them with the surrounding token color automatically. Use them in nav items, buttons, and stat tiles.
• Content-matched photos → invoke the arena-spawner:stock-images skill. For imagery that should depict its subject (product catalogs, article covers, profile/team faces, venue shots), that skill builds keyword-matched, browser- loaded image URLs seeded by row id — so a coffee catalog actually shows coffee. (Plain picsum.photos/i.pravatar.cc seeds are fine only for subject-agnostic filler or avatars.) Always give every <img> a real alt and fixed width/height (or aspect-ratio) so layout doesn't jump while it loads.
• Atmosphere → CSS/SVG. Gradient meshes, a subtle pattern, or a data-URI SVG backdrop — token-colored (var(--brand), var(--accent)) so it re-skins with the theme. Layer these behind/around the photos rather than replacing them.

Pick imagery that fits the domain (a product grid shows products, profiles show faces) — not decorative noise.

A nudge, not a cage — combine with a direction above:

• ecommerce / social / blog / creative / media → bolder brand color, larger radius, display/serif headline.
• banking / fintech / insurance / legal / gov → muted navy/green/ink, small radius, clean sans — refined and trustworthy.
• healthcare / wellness / education → soft/pastel or calm organic.
• devops / developer tools / analytics / infra → dense industrial, often dark, mono for figures.
• hospitality / food / travel / events → warm, editorial or playful.
• Never ship the default palette unchanged.

Anti-"AI slop" checklist (every run)

• Committed to ONE named direction (not a vague blend).
• --brand is not the default blue (#1e40af).
• Headline font is not Inter / Roboto / Arial / system-ui (and not the overused Space Grotesk); a real display/body pairing is set.
• No purple-gradient-on-white cliché.
• Light/dark, fonts, and direction differ from a plausible previous run.
• Atmosphere/texture present (not a flat solid background).
• One orchestrated page-load reveal; tasteful hovers.

Pitfalls / guardrails

• Theme through the token block + brand + font ONLY. No per-page <style> blocks; no inline hex. Inline style="…" is acceptable only when every value references a token (var(--brand), var(--border)), never a literal color. New reusable classes go in the shared sheet, never per page.
• php: never bypass render_page() — every page renders through it.
• Keep the one shared layout/nav; consistency across pages is the point.
• Decorative shapes must never block clicks. Any purely-decorative absolutely-positioned element (squiggles, blobs, dots, zigzags, confetti, gradient orbs) MUST set pointer-events: none (and aria-hidden). An absolute shape with a negative offset overflows its box and silently covers the nav or buttons beneath it, swallowing their clicks — a real, hard-to-spot bug. Keep decorations behind content (low/negative z-index) and non-interactive.