@tiniestcloud/create 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiniestcloud/create",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Start an app or website for Tiniest Cloud: React, TypeScript, Vite, Tailwind CSS and shadcn/ui, or Astro.",
   "keywords": [
     "tiniest-cloud",

package/skills/tiny-design/SKILL.md

@@ -92,6 +92,14 @@ see-through over the content) and its bottom border. Keep it short — about 56
 on a phone, where an app's screens move to the bottom bar — so it doesn't eat the screen. A
 sidebar stays put the same way (`sticky top-0 h-svh`), and a detail pane beside a long list
 scrolls on its own.
+**Switching the theme crossfades.** Change light and dark only through the starter's
+`setTheme` (src/lib/theme.ts), never by toggling the class yourself: it fades the whole page
+from one theme to the other in 300ms and remembers the choice.
+**The header lines up with the page.** Its row sits in the same container as the content below
+(the same max width and side padding), so the logo starts on the page's left edge and the last
+action ends on its right. Logo, navigation and actions share one line, centred vertically. Icon
+buttons keep their size at every width (`shrink-0`, a fixed square): at a tablet's width
+(640–1024px) the navigation drops its labels or folds into a menu before anything squeezes.
 A website's header may shrink as you scroll, but stays reachable. A long list's search and
 filters stick just below the header the same way, so people can search without scrolling back
 up — on a phone, at least the search. Measure the header (a `ResizeObserver` writing
@@ -317,6 +325,10 @@ apps never come out the same. Every font here is on npm as `@fontsource/<name>`
   every other bottom bar above it; a detail screen keeps its way back and its actions pinned.
 - The header stays at the top while the page scrolls, on a laptop and a phone, with a solid
   background; a long list's search (and filters, where there's room) stays pinned under it.
+- The header's logo and last action line up with the page's edges, and nothing in it squeezes
+  at a tablet's width (768px).
+- Screens are built from components (the starter's and the app's own), with no bare
+  `<button>` or `<input>` and no hand-written stylesheet for them.
 - No control the browser draws: dates use the calendar, dropdowns the select, hints the tooltip,
   questions a dialog — all styled to the theme.
 - None of the giveaways (the design guide's "What gives generated UI away").

package/skills/tiny-design/app.md

@@ -38,6 +38,15 @@ phone-width column for the screens that are one task; anywhere else it reads as
   and the header shrinks to one row. Keep the app's name or logo, the theme switch and the
   account at the edges. The header stays pinned at the top while the page scrolls
   (`sticky top-0`, solid background).
+- **Built from components.** A screen is composed, not written out: the starter's Button,
+  Input and Card (src/components/ui), its AppHeader, SearchField and
+  FilterChips (src/components), and a component of the app's own for anything drawn more than
+  once (a product card, a list row, a stat tile). Styled with Tailwind classes and the theme's
+  colours on those components, never a stylesheet of `.card` and `.hero` rules. Anything
+  missing (a badge, tabs, a dialog, a select, a table, a sheet, a menu) comes from shadcn/ui
+  (`npx shadcn@latest add <name>`), then takes the app's style in its own file: shadcn first,
+  the app's style on top, nothing written by hand that shadcn has. The person will never ask
+  for this, and every later change depends on it.
 - **Lists are the heart.** A row per item: the main text strong, a secondary line muted,
   status as a small consistent badge, meta (date, amount) right-aligned in tabular figures.
   Search, filters and sort sit above the list and run on the server (`where`, `order`, `limit`);

package/templates/app/AGENTS.md

@@ -19,24 +19,38 @@ React, TypeScript, Vite, Tailwind CSS and shadcn/ui, deployed to Tiniest Cloud a
     platform answers every path with index.html). Keep Vite's default `base`.
     Tiniest Cloud refuses a first deploy whose screens are anywhere else (all in App.tsx, say).
   - `src/components/` — pieces the screens share; `src/components/ui/` for shadcn components.
+    Anything drawn more than once is a component here with typed props (a product card, a row,
+    a stat tile, a page heading), never markup copied between screens.
   - `src/hooks/` — the app's own `useSomething` hooks. The SDK's hooks stay in src/lib/tiny.tsx.
   - `src/lib/` — plain code: helpers, formatting, types (`types.ts`), calculations.
   - `public/` — files served as they are (images, icons), plus `_functions/`, `tiny.rules.json`
     and `tiny.brand.json`.
+  - `public/icon.svg` — the app's mark (the logo in its header), square, on its own background
+    colour. Tiniest Cloud makes it the app's icon: browser tab, home screen, sign-in page, dashboard.
   - A file past about 300 lines is doing too much: move its parts into components and hooks.
-- Components: `npx shadcn@latest add <name>` adds one to src/components/ui. They are a starting
-  point: restyle them to fit this app (radius, size, colour, spacing) in src/components/ui.
+- Components: build every screen from them. Here already: `Button`, `Input`, `Card`, `Tooltip`
+  (src/components/ui); `AppHeader`, `SearchField`, `FilterChips`, `ThemeToggle` (src/components).
+  No bare `<button>`, `<input>` or `<select>` in a screen.
+- Anything else (a badge, tabs, a dialog, a select, a table, a sheet, a menu, a toast) comes from
+  shadcn/ui, never written by hand: `npx shadcn@latest add <name>`, or without a shell the file
+  as shadcn publishes it, in src/components/ui. Then style it for this app in its own file.
+  shadcn first, the app's style on top.
+- Styling: Tailwind classes on components, colours from the theme tokens (`bg-background`,
+  `text-muted-foreground`). src/index.css holds the palette and fonts, not `.card` or `.hero`
+  rules for screens.
+- Header: keep `AppHeader` and its `PAGE` container, which the content shares, so the logo and
+  the last action line up with the page. Give it the app's name and logo; restyle, don't rewrite.
+- Theme: switch only with `setTheme` (src/lib/theme.ts), which crossfades the page. Never
+  toggle the `dark` class yourself.
 - Design: before the first screen, read the tiny-design skill — `.agents/skills/tiny-design/`
   (the same files are in `.claude/skills/` for Claude Code): SKILL.md, then app.md. Where that
   folder is missing, `tiny_guide` with topic `app` returns the same. Write what you decide in
   DESIGN.md.
 - Look: give the app its own palette in src/index.css (the `:root` and `.dark` blocks) that suits
   what it is and who uses it — never ship the default grey. Lay each screen out for what it
-  holds (a sidebar, a grid of cards, a table, a list beside its detail); the frame in App.tsx and
-  the first screen in src/pages/home.tsx are placeholders, and a narrow centred column suits only
-  one focused task. Light, dark and "match
-  device" are chosen with `ThemeToggle` (src/components/theme-toggle.tsx); keep both themes
-  looking right.
+  holds (a sidebar, a grid of cards, a table, a list beside its detail); the first screen in
+  src/pages/home.tsx is a placeholder, and a narrow centred column suits only one focused task.
+  Light, dark and "match device" are chosen with `ThemeToggle`; keep both themes looking right.
 - Their own components or brand: if the person points at a folder, a style guide or another app,
   that is the design — reuse their components and bring their colours, fonts and logo into this
   project (copied in, never linked to a path on their computer).

package/templates/app/package.json

@@ -17,6 +17,7 @@
     "radix-ui": "^1.6.7",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
+    "react-router": "^8.5.1",
     "shadcn": "^4.21.0",
     "tailwindcss": "^4",
     "tw-animate-css": "^1.4.0"

package/templates/app/src/App.tsx

@@ -1,39 +1,34 @@
-import { Button } from "@/components/ui/button"
-import { ThemeToggle } from "@/components/theme-toggle"
+import { Home as HomeIcon } from "lucide-react"
+import { BrowserRouter, Route, Routes } from "react-router"
+
+import { AppHeader, PAGE, type Screen } from "@/components/app-header"
 import { useMe } from "@/lib/tiny"
+import { cn } from "@/lib/utils"
 import Home from "@/pages/home"
 
+/**
+ * The app's screens, one line each: a file in src/pages, its address, and its name and icon in
+ * the navigation. The header and the routes below are both drawn from this list. A detail page
+ * (`/orders/:id`) is a screen too, with `hidden: true` to keep it out of the navigation.
+ */
+const screens: Screen[] = [{ path: "/", label: "Home", icon: HomeIcon, element: <Home /> }]
+
 export default function App() {
   const me = useMe()
   if (me === undefined) return null
 
   return (
-    <div className="flex min-h-svh flex-col">
-      <header className="sticky top-0 z-40 border-b bg-background">
-        <div className="mx-auto flex h-14 w-full max-w-7xl items-center justify-between gap-4 px-4 sm:px-6">
-          <h1 className="text-base font-medium">App</h1>
-          <div className="flex items-center gap-3">
-            <ThemeToggle />
-            {me ? (
-              <div className="flex min-w-0 items-center gap-3 text-sm text-muted-foreground">
-                <span className="hidden truncate sm:inline">{me.email}</span>
-                <Button variant="outline" size="sm" onClick={() => tiny.logout()}>
-                  Sign out
-                </Button>
-              </div>
-            ) : (
-              <Button size="sm" onClick={() => tiny.login()}>
-                Sign in
-              </Button>
-            )}
-          </div>
-        </div>
-      </header>
-      {/* A placeholder frame around the screens in src/pages. With more than one screen, add
-          React Router here: a route per page, the header shared by all of them. */}
-      <main className="mx-auto w-full max-w-7xl flex-1 px-4 py-6 sm:px-6">
-        <Home />
-      </main>
-    </div>
+    <BrowserRouter>
+      <div className="flex min-h-svh flex-col">
+        <AppHeader name="App" screens={screens} me={me} />
+        <main className={cn(PAGE, "flex-1 pt-6 pb-[calc(var(--nav-h)+1.5rem)]")}>
+          <Routes>
+            {screens.map((screen) => (
+              <Route key={screen.path} path={screen.path} element={screen.element} />
+            ))}
+          </Routes>
+        </main>
+      </div>
+    </BrowserRouter>
   )
 }

package/templates/app/src/components/app-header.tsx

@@ -0,0 +1,121 @@
+import type { ComponentType, ReactNode } from "react"
+import { NavLink } from "react-router"
+
+import { ThemeToggle } from "@/components/theme-toggle"
+import { Button } from "@/components/ui/button"
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"
+import { cn } from "@/lib/utils"
+
+/** A screen: a file in src/pages, listed in App.tsx. `hidden` keeps a detail page out of the navigation. */
+export type Screen = {
+  path: string
+  label: string
+  icon: ComponentType<{ className?: string }>
+  element: ReactNode
+  hidden?: boolean
+}
+
+/** The page's width and side padding, shared by the header's row and the content so their edges line up. */
+export const PAGE = "mx-auto w-full max-w-7xl px-4 sm:px-6"
+
+/**
+ * The header and navigation: one line on a laptop, the screens as icons on a tablet, and a bar
+ * at the bottom on a phone. Restyle it to fit the app; keep the structure.
+ */
+export function AppHeader({
+  name,
+  logo,
+  screens,
+  me,
+}: {
+  name: string
+  /** `<img src="/icon.svg" alt="" className="size-7" />` */
+  logo?: ReactNode
+  screens: Screen[]
+  me: Tiny.User | null
+}) {
+  const nav = screens.filter((screen) => !screen.hidden)
+  const many = nav.length > 1
+
+  return (
+    <>
+      <header className="sticky top-0 z-40 border-b bg-background">
+        <div className={cn(PAGE, "flex h-14 items-center gap-4")}>
+          <NavLink to="/" className="flex shrink-0 items-center gap-2 text-base font-medium">
+            {logo}
+            <span>{name}</span>
+          </NavLink>
+
+          {many && (
+            <TooltipProvider delayDuration={300}>
+              <nav aria-label="Screens" className="hidden min-w-0 items-center gap-1 sm:flex">
+                {nav.map(({ path, label, icon: Icon }) => (
+                  <Tooltip key={path}>
+                    <TooltipTrigger asChild>
+                      <NavLink
+                        to={path}
+                        end={path === "/"}
+                        aria-label={label}
+                        // aria-current, not a className function: that would not survive the tooltip's trigger.
+                        className={cn(
+                          "flex h-9 shrink-0 items-center gap-2 rounded-full px-3 text-sm text-muted-foreground transition-colors duration-200",
+                          "hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                          "aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
+                        )}
+                      >
+                        <Icon className="size-4 shrink-0" />
+                        <span className="hidden lg:inline">{label}</span>
+                      </NavLink>
+                    </TooltipTrigger>
+                    <TooltipContent side="bottom" sideOffset={6} className="lg:hidden">
+                      {label}
+                    </TooltipContent>
+                  </Tooltip>
+                ))}
+              </nav>
+            </TooltipProvider>
+          )}
+
+          <div className="ml-auto flex shrink-0 items-center gap-3">
+            <ThemeToggle className="shrink-0" />
+            {me ? (
+              <>
+                <span className="hidden max-w-48 truncate text-sm text-muted-foreground lg:inline">{me.email}</span>
+                <Button variant="outline" size="sm" className="shrink-0" onClick={() => tiny.logout()}>
+                  Sign out
+                </Button>
+              </>
+            ) : (
+              <Button size="sm" className="shrink-0" onClick={() => tiny.login()}>
+                Sign in
+              </Button>
+            )}
+          </div>
+        </div>
+      </header>
+
+      {/* `data-bottom-nav` sets --nav-h (index.css): the page pads its bottom by it. */}
+      {many && (
+        <nav
+          aria-label="Screens"
+          data-bottom-nav
+          className="fixed inset-x-0 bottom-0 z-40 flex border-t bg-background pb-[env(safe-area-inset-bottom)] sm:hidden"
+        >
+          {nav.slice(0, 5).map(({ path, label, icon: Icon }) => (
+            <NavLink
+              key={path}
+              to={path}
+              end={path === "/"}
+              className="group flex h-16 min-w-0 flex-1 flex-col items-center justify-center gap-1 text-xs text-muted-foreground aria-[current=page]:font-medium aria-[current=page]:text-foreground"
+            >
+              <span className="flex h-7 w-14 items-center justify-center rounded-full transition-colors duration-200 group-aria-[current=page]:bg-muted">
+                <Icon className="size-5" />
+              </span>
+              <span className="max-w-full truncate px-1">{label}</span>
+            </NavLink>
+          ))}
+        </nav>
+      )}
+    </>
+  )
+}

package/templates/app/src/components/filter-chips.tsx

@@ -0,0 +1,45 @@
+import { Button } from "@/components/ui/button"
+import { cn } from "@/lib/utils"
+
+/**
+ * One choice from a short row of chips: a list's filter ("All · Open · Done"). Each chip is as
+ * wide as its words, and the row scrolls sideways when it no longer fits. Controlled: the screen
+ * keeps the choice (in the URL, when a link should open the same view).
+ */
+export function FilterChips<T extends string>({
+  options,
+  value,
+  onChange,
+  label,
+  className,
+}: {
+  options: ReadonlyArray<T | { value: T; label: string }>
+  value: T
+  onChange: (value: T) => void
+  /** What the row filters, for a screen reader: "Status". */
+  label: string
+  className?: string
+}) {
+  return (
+    <div role="radiogroup" aria-label={label} className={cn("flex max-w-full gap-2 overflow-x-auto [scrollbar-width:none]", className)}>
+      {options.map((option) => {
+        const item = typeof option === "string" ? { value: option, label: option } : option
+        const selected = item.value === value
+        return (
+          <Button
+            key={item.value}
+            type="button"
+            role="radio"
+            aria-checked={selected}
+            variant={selected ? "secondary" : "outline"}
+            size="sm"
+            className="shrink-0 rounded-full px-3.5"
+            onClick={() => onChange(item.value)}
+          >
+            {item.label}
+          </Button>
+        )
+      })}
+    </div>
+  )
+}

package/templates/app/src/components/search-field.tsx

@@ -0,0 +1,45 @@
+import { Search, X } from "lucide-react"
+
+import { Input } from "@/components/ui/input"
+import { cn } from "@/lib/utils"
+
+/** A search box: the field every list filters by. Controlled: the screen keeps the words. */
+export function SearchField({
+  value,
+  onChange,
+  placeholder = "Search",
+  label = placeholder,
+  className,
+}: {
+  value: string
+  onChange: (value: string) => void
+  placeholder?: string
+  /** What a screen reader calls it. */
+  label?: string
+  className?: string
+}) {
+  return (
+    <div className={cn("relative w-full sm:w-64", className)}>
+      <Search className="pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2 text-muted-foreground" />
+      <Input
+        type="search"
+        inputMode="search"
+        aria-label={label}
+        placeholder={placeholder}
+        value={value}
+        onChange={(event) => onChange(event.target.value)}
+        className="h-9 rounded-full pr-9 pl-9 [&::-webkit-search-cancel-button]:hidden"
+      />
+      {value && (
+        <button
+          type="button"
+          aria-label="Clear search"
+          onClick={() => onChange("")}
+          className="absolute top-1/2 right-1.5 flex size-6 -translate-y-1/2 items-center justify-center rounded-full text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <X className="size-3.5" />
+        </button>
+      )}
+    </div>
+  )
+}

package/templates/app/src/components/ui/card.tsx

@@ -0,0 +1,102 @@
+import * as React from "react"
+import { cn } from "cn"
+
+function Card({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl bg-card py-(--card-spacing) text-sm text-card-foreground ring-1 ring-foreground/10 [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(
+        "font-heading text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-(--card-spacing)", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-xl border-t bg-muted/50 p-(--card-spacing)",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}

package/templates/app/src/components/ui/input.tsx

@@ -0,0 +1,18 @@
+import * as React from "react"
+import { cn } from "cn"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }

package/templates/app/src/index.css

@@ -8,19 +8,6 @@
 @theme inline {
     --font-heading: var(--font-sans);
     --font-sans: 'Geist Variable', sans-serif;
-    --color-sidebar-ring: var(--sidebar-ring);
-    --color-sidebar-border: var(--sidebar-border);
-    --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-    --color-sidebar-accent: var(--sidebar-accent);
-    --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-    --color-sidebar-primary: var(--sidebar-primary);
-    --color-sidebar-foreground: var(--sidebar-foreground);
-    --color-sidebar: var(--sidebar);
-    --color-chart-5: var(--chart-5);
-    --color-chart-4: var(--chart-4);
-    --color-chart-3: var(--chart-3);
-    --color-chart-2: var(--chart-2);
-    --color-chart-1: var(--chart-1);
     --color-ring: var(--ring);
     --color-input: var(--input);
     --color-border: var(--border);
@@ -67,20 +54,7 @@
     --border: oklch(0.922 0 0);
     --input: oklch(0.922 0 0);
     --ring: oklch(0.708 0 0);
-    --chart-1: oklch(0.87 0 0);
-    --chart-2: oklch(0.556 0 0);
-    --chart-3: oklch(0.439 0 0);
-    --chart-4: oklch(0.371 0 0);
-    --chart-5: oklch(0.269 0 0);
     --radius: 0.625rem;
-    --sidebar: oklch(0.985 0 0);
-    --sidebar-foreground: oklch(0.145 0 0);
-    --sidebar-primary: oklch(0.205 0 0);
-    --sidebar-primary-foreground: oklch(0.985 0 0);
-    --sidebar-accent: oklch(0.97 0 0);
-    --sidebar-accent-foreground: oklch(0.205 0 0);
-    --sidebar-border: oklch(0.922 0 0);
-    --sidebar-ring: oklch(0.708 0 0);
 }
 
 .dark {
@@ -102,19 +76,6 @@
     --border: oklch(1 0 0 / 10%);
     --input: oklch(1 0 0 / 15%);
     --ring: oklch(0.556 0 0);
-    --chart-1: oklch(0.87 0 0);
-    --chart-2: oklch(0.556 0 0);
-    --chart-3: oklch(0.439 0 0);
-    --chart-4: oklch(0.371 0 0);
-    --chart-5: oklch(0.269 0 0);
-    --sidebar: oklch(0.205 0 0);
-    --sidebar-foreground: oklch(0.985 0 0);
-    --sidebar-primary: oklch(0.488 0.243 264.376);
-    --sidebar-primary-foreground: oklch(0.985 0 0);
-    --sidebar-accent: oklch(0.269 0 0);
-    --sidebar-accent-foreground: oklch(0.985 0 0);
-    --sidebar-border: oklch(1 0 0 / 10%);
-    --sidebar-ring: oklch(0.556 0 0);
 }
 
 @layer base {
@@ -127,4 +88,23 @@
   html {
     @apply font-sans;
     }
-}
+}
+
+/* The height of the phone's bottom navigation (src/components/app-header.tsx), 0 when there is
+   none: the page pads its bottom by it, and anything else pinned to the bottom sits above it. */
+:root {
+    --nav-h: 0px;
+}
+@media (width < 40rem) {
+    :root:has([data-bottom-nav]) {
+        --nav-h: calc(4rem + env(safe-area-inset-bottom));
+    }
+}
+
+/* The theme switch crossfades the page (src/lib/theme.ts). Short, slow at both ends and quick
+   through the middle, so the halfway blend of two opposite themes never registers. */
+::view-transition-old(root),
+::view-transition-new(root) {
+  animation-duration: 300ms;
+  animation-timing-function: cubic-bezier(0.83, 0, 0.17, 1);
+}

package/templates/app/src/lib/theme.ts

@@ -21,12 +21,19 @@ function apply(theme: Theme) {
   document.documentElement.style.colorScheme = dark ? "dark" : "light"
 }
 
+/**
+ * Switch the theme with a crossfade of the whole page (timed in index.css). Where the browser
+ * has no view transitions, or the person asked for less motion, the theme just changes.
+ */
 export function setTheme(theme: Theme) {
   document.cookie =
     theme === "system"
       ? "theme=; path=/; max-age=0; samesite=lax"
       : `theme=${theme}; path=/; max-age=31536000; samesite=lax`
-  apply(theme)
+  const doc = document as Document & { startViewTransition?: (update: () => void) => unknown }
+  const still = window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  if (still || typeof doc.startViewTransition !== "function") apply(theme)
+  else doc.startViewTransition(() => apply(theme))
   window.dispatchEvent(new Event("themechange"))
 }
 

package/templates/app/src/pages/home.tsx

@@ -1,9 +1,10 @@
 /**
- * The first screen. Every screen is a file in src/pages; App.tsx frames them and, once there is
- * more than one, routes to each (React Router). Lay this one out for what it holds: a sidebar for
- * several areas, a grid of cards for things people browse, a table for records, a list with its
- * detail beside it; a narrow centred column only for one focused task. Pieces it shares with
- * other screens go in src/components, its own hooks in src/hooks.
+ * The first screen. Every screen is a file in src/pages, listed in App.tsx (its address, its name
+ * and icon in the navigation). Lay this one out for what it holds: a grid of cards for things
+ * people browse, a table for records, a list with its detail beside it; a narrow centred column
+ * only for one focused task. Build it from components: Button, Input and Card in
+ * src/components/ui (more from shadcn), SearchField and FilterChips in src/components, and a
+ * component of this app's own for anything drawn more than once. Its hooks go in src/hooks.
  */
 export default function Home() {
   return <div />