Tailwind 4 in this template

This project uses Tailwind CSS v4 with CSS-first configuration. Your design tokens and defaults live in app/styles/, then utilities are composed directly in JSX. Below is a quick, practical guide tailored to this template.

How it’s wired

Entry CSS: app/styles/app.css imports Tailwind via@import "tailwindcss" and loads your layers: theme, layout, typography, buttons, elements, utilities.
Tokens: app/styles/theme.css defines tokens using@theme and @theme inline. This maps CSS variables to Tailwind color names so you can use classes likebg-background, text-foreground,border-border, bg-primary, etc.
Typography: app/styles/typography.css defines a scalable system with text-default, custom size utilities, and heading styles. Prefer these over ad‑hoc sizes.
Dark mode: Controlled by the .dark class on<html> (see app/root.tsx). Usedark: variants or token classes that switch automatically.
Extras: elements.css (inputs, lists, dividers),buttons.css (the .btn system used bycustomButtons.tsx), layout.css, andutilities.css (e.g. .text-highlight,.hide-scrollbar).

Using tokens and utilities

Use semantic tokens instead of hard colors. These adapt to light/dark and can be re-themed centrally.

Example container using tokens: bg-card,text-card-foreground, border-border.

Responsive typography

Prefer the custom sizes provided in typography.css to preserve scale across breakpoints.

text-default sm:text-sm md:text-default 2xl:text-lg

2xl → 3xl → 5xl responsive text

Dark mode

Tokens switch automatically when html.dark is set. You can also use dark: variants for one-off tweaks.

<div className="bg-background text-foreground dark:shadow-[0_0_0_0.2rem_theme(colors.gray.800/30)]">...
</div>

Common patterns in this template

Structure: Use Container, VStack,HStack, Box from~/components/basic-ui/building-blocks for consistent layout.
Buttons: Use DefaultButton,OutlineButton, etc. They apply the .btn system and theme-aware colors.
Spacing: Prefer responsive spacing and viewport units (e.g.py-[6vh], gap-6) over fixed pixels.
Lists/inputs: Base styles are provided inelements.css; most inputs get sensible borders, rings, and focus states.

Extending the design tokens

Tailwind 4 lets you declare tokens in CSS. Add a token inapp/styles/theme.css, then use it immediately.

/* app/styles/theme.css */
@theme inline {
  --color-success: var(--green-500);
  --color-success-foreground: var(--white);
}

/* JSX usage */
<div className="bg-success text-success-foreground p-[2vh] rounded-xl">Saved</div>

Quick checklist

Use token classes: bg-background, text-foreground, border-border.
Prefer template typography: text-default, text-lg, headings.
Viewport-first spacing: e.g. p-[3vh], avoid hard px.
Dark mode: automatic via tokens; use dark: for overrides.
Buttons: use customButtons.tsx components.

Dev