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:
- Buttons:
btn. Its look is an attribute,data-variant:outline,secondary,ghost,destructive(for dangerous actions) orlink. Its size isdata-size:sm,lg, oriconfor a button that is only an icon. - Cards:
card, with aheader, asectionand an optionalfooterinside. - Forms:
fieldaround each label and input;label,input,select,textarea. - Tables:
table. - Small labels:
badge, with the samedata-variantvalues. - Messages:
alert, anddata-variant="destructive"for errors.
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:
- "Show the notes as cards in two columns on wide screens and one column on phones."
- "Make the Delete button red, with Basecoat's destructive style."
After the change, check the page yourself at two sizes: drag your browser narrow, then wide.
This Week's Exercise
- Read T08's flexbox and grid sections, ten minutes.
- In the starter, find every Basecoat class in
pages/index.htmland the fragments. Name what each does. - Ask Pi for the two-column cards. Rebuild the CSS and check at phone width and full width.
- 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