Instruction file imported from Ctrl-Alt-GG/homepage (.github/instructions/tailwind-css.instructions.md). Copyright stays with the author.

Tailwind CSS v4

Entry point

assets/css/main.css is the single source file. Keep these at the top:

@import "tailwindcss";
@plugin "@tailwindcss/typography";

The compiled output lives under assets/css/compiled/ and is git-ignored. Never edit compiled files, never commit them.

Design tokens

Shared tokens live in the @theme block at the top of main.css:

• Brand palette: --color-brand-* (cross-site red, mirrored across care, homepage, and spawn).
• Typography: --font-sans (Inter-first fallback chain).
• Radius / elevation: --radius-*, --shadow-*.

Don't introduce parallel token systems, ad-hoc hexes in templates, or !important overrides. Add or rename tokens here so all three CAG properties stay visually coherent.

Shortcode styling contract

The shortcode library uses semantic class prefixes (cag-intro, cag-features, cag-grid, cag-faq, and so on). Treat these as a public API: content authors may target them from custom CSS snippets, and existing content may rely on them. Style them via @layer components:

@layer components {
  .cag-features {
    @apply my-12 grid gap-6;
  }
  .cag-features-heading {
    @apply text-2xl font-bold mb-4;
  }
}

Never rename an existing cag-* class; extend by adding new ones.

Prefer utilities over new custom CSS

Before adding a rule to cag.css, check whether Tailwind utility classes applied directly in the template/shortcode already solve it; most layout, spacing, flex/grid, and color needs do. Reach for cag.css only for things utilities can't express cleanly: pseudo-elements (::before), background-image icons, multi-declaration hover/focus states tied to a semantic component name, or values that must stay in sync across many selectors (e.g. a brand colour used in both a badge and its border). Adding a new one-off custom class for something four utility classes already cover is technical debt; it was the root cause of most of the css/markup churn on the location page (see git history around content/location/).

Dark mode

Dark mode is expressed with the dark: variant (declared via @custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *))). Do not add prefers-color-scheme media queries alongside it.

Typography

The typography plugin is enabled; style Markdown output via .prose selectors under @layer components, not by decorating individual elements in templates.

Build

npm run build:css runs the CLI once; npm run dev:css watches. Both are wired from package.json, so do not invoke the Tailwind binary directly.