W06: Looking Good: Basecoat and Tailwind

Furnishing a flat, you do not build a sofa. You buy one that already looks good, then decide where it goes: against this wall, two steps from the window. Your app's look works the same way. Basecoat is the furniture shop: buttons, cards, form fields and tables that already look good, each one a class name. Tailwind is the floor plan: small class names that place things, like "a grid with gaps" or "padding all around". Together they give you a clean app without writing CSS.

CSS in One Paragraph

The look of a web page comes from CSS rules. T07: CSS Basics and T08: CSS Layout teach how it works. In this stack you rarely write CSS yourself: you write class names in the HTML, and the CSS already exists for them.

Basecoat: Components as Class Names

The kit pins Basecoat 1.0.2. Its components are classes. These lines are almost always right:

<button class="btn">Save</button>
<button class="btn" data-variant="outline">Cancel</button>
<button class="btn" data-variant="destructive">Delete</button>

<div class="card">
  <header><h2>Title</h2></header>
  <section>The content.</section>
</div>

<div class="field">
  <label class="label" for="title">Title</label>
  <input class="input" id="title" name="title">
</div>

<table class="table">...</table>

The ones you will use most:

The starter already uses several. The note form is a card with a field, an input and a btn. Each note's Delete button is a quiet btn with data-variant="ghost".

Bigger components (dialogs, dropdown menus, tabs, toasts) come as ready-made Jinja macros, with Basecoat's small script, which base.html loads.

Variants are attributes in Basecoat 1.0. Most Basecoat examples online are older, and write btn-outline or btn-ghost as classes. Those do nothing in your project: the button renders as plain text. Write class="btn" data-variant="outline".

One trap: a class name that does not exist does nothing, silently. When something looks unstyled, check the spelling against the list above. Pi Workbench will do this step for you soon: a check after every edit will catch class names that are not Basecoat's.

Tailwind: Arranging Things

Tailwind classes each do one small job. The starter's page frame is:

<main class="mx-auto max-w-2xl p-4 grid gap-6">

Left to right: centred (mx-auto), a comfortable reading width (max-w-2xl), padding (p-4), a grid of rows (grid) with space between (gap-6).

The handful that covers most layouts:

Want Classes
Items side by side flex items-center gap-4
Push to both ends flex justify-between
Rows with space grid gap-4
Two columns on wide screens, one on phones grid gap-4 md:grid-cols-2
Space inside p-4, px-4, py-2
Bigger, bolder text text-2xl font-semibold
Quieter text text-muted-foreground text-sm
Error text text-destructive

md: means "from medium screens up". Write the phone layout first, then add md: for wider screens. Every page should work at phone width (about 390 pixels) and on a big desktop screen.

The Build Step

Tailwind does not ship every possible class. It reads your templates, finds the class names you used, and writes only those into static/app.css. That is what this command from W04 does:

TAILWINDCSS_VERSION=v4.3.3 uv run tailwindcss -i styles/input.css -o static/app.css --minify

styles/input.css is short: it brings in Tailwind, then Basecoat, then tells Tailwind to look in app/templates. So a new class only works after the CSS is rebuilt. If you add md:grid-cols-2 and nothing changes, rebuild and reload. To rebuild by itself every time a template changes, run it with --watch in a second terminal while you work.

Your Own Few Rules

Sometimes you need a rule Basecoat and Tailwind do not have. The stack's rule: no second CSS framework, and your own few rules stay in one place. In the starter, that place is the end of styles/input.css. Never edit static/app.css by hand: every build rewrites it. Most apps never need their own rules. Prefer a Tailwind class first.

Asking Pi for a Look

Name the components and the layout, as you would describe furniture:

After the change, check the page yourself at two sizes: drag your browser narrow, then wide.

This Week's Exercise

  1. Read T08's flexbox and grid sections, ten minutes.
  2. In the starter, find every Basecoat class in pages/index.html and the fragments. Name what each does.
  3. Ask Pi for the two-column cards. Rebuild the CSS and check at phone width and full width.
  4. Change one button to the old style, class="btn-outline". Rebuild and look. Then put it back.

Key Takeaways

  • Basecoat 1.0.2 gives components as classes: btn, card, field, label, input, select, textarea, table, badge, alert
  • Variants and sizes are attributes: data-variant="outline", data-size="sm". Old examples with btn-outline are pre-1.0 and render plain
  • Tailwind arranges them with small classes: flex, grid, gap-4, p-4, md: for wider screens
  • A misspelled class does nothing, silently: check the name when something looks plain
  • Tailwind writes only the classes you used into static/app.css, so rebuild after adding a new one
  • Phone width first, then wider; your own rare rules go in one place, never in the built static/app.css