@deepraxis/app-template 0.1.0-dev.3c36146 → 0.1.0-dev.660f2cc

package/SKILL.md

@@ -58,8 +58,6 @@ cd <name>
 Read `README.md` in the new project once. It has the folder map and the recipes below in more detail.
 
 ### 3. Develop
-Before you write pages, read the [design guide](references/design.md): it says how to choose the look, which layout fits the kind of app, and how it must work on phones and in Chinese. Before you build anything beyond plain pages, forms and tables (a calendar, charts, maps, rich text, export, payments …), follow [find before you build](references/research.md): look at how others do it, pick an existing library or shadcn/ui component, and prove it with a short spike.
-
 - **Tables**: add `migrations/0002_<what>.sql` using `CREATE TABLE IF NOT EXISTS …`. Import it with `?raw` and append it to the list in `lib/migrations.ts`, then describe the table in `lib/schema.ts`. Migrations run once, in order, on the first request after a deploy. **Never edit a migration that has already been deployed**; add a new one instead.
 - **Rules** (prices, availability, who owns what) go in `lib/`. Pages and route handlers only call them.
 - **Pages**: `app/<path>/page.tsx`. Protect them with `await requireUser("/<path>")` or `await requireAdmin("/<path>")` from `lib/guard.ts`.
@@ -67,7 +65,7 @@ Before you write pages, read the [design guide](references/design.md): it says h
 - **Uploads**: follow `app/api/images/route.ts` and `lib/storage.ts`. That code checks type and size, stores the file under the owner and records it in D1. For an upload that belongs to a record (a pet photo on a booking, a cover on a book), read the file from the same form, call `checkImage` and `saveImage`, and store the returned `key` in a column of your row. Images are served by `/images/<key>` to their owner and admins only. If something must be public (a gallery, product photos), add a separate route that serves only keys you have marked public in your table, and leave `/images` private.
 - **New bindings**: declare them in `wrangler.jsonc` (`d1_databases`, `kv_namespaces`, `r2_buckets`, `vars`), add the type to `env.d.ts`, and read them with `import { env } from "cloudflare:workers"`.
 - **Secrets**: add them to `praxis.jsonc` `secrets`. `"generate"` creates a random value on the first deploy and keeps it on every later deploy. Never write a secret value into a file.
-- **UI**: use the components in `components/ui/` and the semantic Tailwind classes (`bg-primary`, `text-muted-foreground` …). Change the look through the tokens in `app/globals.css`, never with raw colors in pages. Change the site name, home page, navigation and colors freely; keep the sign-in, sign-up, account and admin pages working.
+- **UI**: use the components in `components/ui/` and Tailwind classes. Change the site name, home page, navigation links and colors freely; keep the sign-in, sign-up, account and admin pages working.
 
 ### 4. Check before deploying
 ```bash
@@ -82,7 +80,7 @@ praxis app deploy
 It builds, uploads only the changed files, creates a version, deploys it, keeps or creates the secrets and calls the `healthcheck` path. The build log comes first; the result comes last and contains the URL. With `--json` the last line is a JSON object with `url`, `worker_id`, `version_id` and `secrets_created`. A deploy takes about one to two minutes.
 
 ### 6. Verify it like a user
-- Open the URL. If the `control-browser` skill is available, use it, and walk through the main flow: register, sign in, do the main task, and check the admin page. Take screenshots at 390 px and 1280 px wide and fix what looks off before you report (design guide, section 8).
+- Open the URL. If the `control-browser` skill is available, use it, and walk through the main flow: register, sign in, do the main task, and check the admin page.
 - Without a browser, check over HTTP. Forms post `application/x-www-form-urlencoded` (uploads: `multipart/form-data`) and answer `303` with a `Location`; protected pages answer a redirect to `/login` when signed out.
   ```bash
   U=<url>; J=$(mktemp)

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@deepraxis/app-template",
-  "version": "0.1.0-dev.3c36146",
+  "version": "0.1.0-dev.660f2cc",
   "description": "The standard Praxis application template: vinext + D1 + R2 + end-user auth + admin area.",
   "license": "Apache-2.0",
   "files": [
     "template",
     "README.md",
-    "SKILL.md",
-    "references"
+    "SKILL.md"
   ],
   "publishConfig": {
     "access": "public"

package/template/README.md

@@ -25,16 +25,12 @@ lib/                server-only code and business rules
   session.ts        session rows + cookie strings    users.ts  user rules (first user = admin)
   guard.ts          getCurrentUser / requireUser / requireAdmin
   storage.ts        image rules and R2/D1 access
-components/ui/      Button, Input, Label, Card, Badge
+components/ui/      Button, Input, Label, Card
 migrations/         numbered SQL files
 ```
 
 Keep business rules in `lib/`; pages and route handlers only call them.
 
-## Look
-
-The look lives in the design tokens at the top of `app/globals.css` (colors, radius) and the font stack in `tailwind.config.ts`. Pages and components use only semantic classes (`bg-primary`, `text-muted-foreground`, `text-destructive`), never raw palette classes or hex colors, so restyling means editing the tokens. `bun test` enforces it: `lib/design-tokens.test.ts` fails on a raw color class and on any text/background token pair under 4.5:1 contrast.
-
 ## Common changes
 
 - **Add a page**: create `app/<name>/page.tsx`. Call `await requireUser("/<name>")` or `requireAdmin` from `lib/guard.ts` to protect it.

package/template/app/account/page.tsx

@@ -1,5 +1,3 @@
-import { Badge } from "@/components/ui/badge";
-import { formatBytes } from "@/lib/format";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
@@ -17,16 +15,16 @@ export default async function Account({ searchParams }: { searchParams: Promise<
     <div className="space-y-6">
       <Card>
         <CardHeader><CardTitle>{user.username}</CardTitle></CardHeader>
-        <CardContent className="text-sm"><Badge variant={user.role === "admin" ? "default" : "secondary"}>{user.role}</Badge></CardContent>
+        <CardContent className="text-sm">Role: {user.role}</CardContent>
       </Card>
       <Card>
         <CardHeader><CardTitle>Upload an image</CardTitle></CardHeader>
         <CardContent>
-          <form action="/api/images" method="post" encType="multipart/form-data" className="flex flex-col gap-3 sm:flex-row sm:items-center">
+          <form action="/api/images" method="post" encType="multipart/form-data" className="flex items-center gap-3">
             <Input name="image" type="file" accept="image/jpeg,image/png,image/webp" required />
             <Button type="submit">Upload</Button>
           </form>
-          {error && <p role="alert" className="mt-2 text-sm text-destructive">{error}</p>}
+          {error && <p role="alert" className="mt-2 text-sm text-red-600">{error}</p>}
         </CardContent>
       </Card>
       <Card>
@@ -36,7 +34,7 @@ export default async function Account({ searchParams }: { searchParams: Promise<
             {mine.map(img => (
               <li key={img.id} className="text-xs">
                 <a href={`/images/${img.key}`}><img src={`/images/${img.key}`} alt="" className="h-32 w-full rounded-md border object-cover" /></a>
-                <span className="text-muted-foreground">{formatBytes(img.size)}</span>
+                <span className="text-slate-500">{img.contentType} · {img.size} bytes</span>
               </li>
             ))}
           </ul>

package/template/app/admin/page.tsx

@@ -1,8 +1,6 @@
 import { count, desc } from "drizzle-orm";
-import { Badge } from "@/components/ui/badge";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { getDb } from "@/lib/db";
-import { formatBytes, formatDateTime } from "@/lib/format";
 import { requireAdmin } from "@/lib/guard";
 import { images, users } from "@/lib/schema";
 
@@ -23,29 +21,27 @@ export default async function Admin() {
       <Card>
         <CardHeader><CardTitle>Users ({userCount!.n})</CardTitle></CardHeader>
         <CardContent>
-          <div className="overflow-x-auto"><table className="w-full text-left text-sm [&_td]:py-2 [&_td]:pr-4 [&_th]:pb-2 [&_th]:pr-4 [&_th]:font-medium [&_th]:text-muted-foreground">
+          <table className="w-full text-left text-sm">
             <thead><tr><th>Username</th><th>Role</th><th>Created</th></tr></thead>
             <tbody>
               {allUsers.map(u => (
-                <tr key={u.id}><td>{u.username}</td><td><Badge variant={u.role === "admin" ? "default" : "secondary"}>{u.role}</Badge></td><td className="whitespace-nowrap">{formatDateTime(u.createdAt)}</td></tr>
+                <tr key={u.id}><td>{u.username}</td><td>{u.role}</td><td>{new Date(u.createdAt).toISOString()}</td></tr>
               ))}
             </tbody>
-          </table></div>
+          </table>
         </CardContent>
       </Card>
       <Card>
         <CardHeader><CardTitle>Images ({imageCount!.n})</CardTitle></CardHeader>
         <CardContent>
-          {allImages.length === 0 ? (
-            <p className="text-sm text-muted-foreground">No uploads yet. Members add images from their account page.</p>
-          ) : <div className="overflow-x-auto"><table className="w-full text-left text-sm [&_td]:py-2 [&_td]:pr-4 [&_th]:pb-2 [&_th]:pr-4 [&_th]:font-medium [&_th]:text-muted-foreground">
-            <thead><tr><th>Owner</th><th>Image</th><th>Type</th><th>Size</th></tr></thead>
+          <table className="w-full text-left text-sm">
+            <thead><tr><th>Owner</th><th>Key</th><th>Type</th><th>Size</th></tr></thead>
             <tbody>
               {allImages.map(i => (
-                <tr key={i.id}><td>{nameOf.get(i.ownerId) ?? i.ownerId}</td><td><a href={`/images/${i.key}`} aria-label={`Open image from ${nameOf.get(i.ownerId) ?? "a member"}`}><img src={`/images/${i.key}`} alt="" className="h-12 w-12 rounded-md border border-border object-cover" /></a></td><td>{i.contentType}</td><td className="whitespace-nowrap">{formatBytes(i.size)}</td></tr>
+                <tr key={i.id}><td>{nameOf.get(i.ownerId) ?? i.ownerId}</td><td><a className="underline" href={`/images/${i.key}`}>{i.key}</a></td><td>{i.contentType}</td><td>{i.size}</td></tr>
               ))}
             </tbody>
-          </table></div>}
+          </table>
         </CardContent>
       </Card>
     </div>

package/template/app/globals.css

@@ -1,45 +1,3 @@
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
-
-/* The look of the app lives here. Values are HSL triplets (hue saturation lightness) used as hsl(var(--x)).
-   Every *-foreground must keep at least 4.5:1 contrast on its background; the design test checks it. */
-@layer base {
-  :root {
-    --background: 0 0% 99%;
-    --foreground: 222 25% 12%;
-    --card: 0 0% 100%;
-    --card-foreground: 222 25% 12%;
-    --muted: 220 14% 96%;
-    --muted-foreground: 220 9% 38%;
-    --border: 220 13% 88%;
-    --input: 220 13% 78%;
-    --ring: 222 47% 11%;
-    --primary: 222 47% 11%;
-    --primary-foreground: 0 0% 98%;
-    --accent: 220 14% 93%;
-    --accent-foreground: 222 47% 11%;
-    --destructive: 0 70% 38%;
-    --destructive-foreground: 0 0% 100%;
-    --success: 142 70% 22%;
-    --success-foreground: 0 0% 100%;
-    --warning: 40 95% 55%;
-    --warning-foreground: 30 80% 10%;
-    --radius: 0.5rem;
-  }
-
-  body {
-    @apply bg-background text-foreground antialiased;
-    font-size: 16px;
-    line-height: 1.7;
-  }
-
-  h1, h2, h3, h4, h5, h6 {
-    @apply font-bold;
-  }
-
-  :focus-visible {
-    outline: 2px solid hsl(var(--ring));
-    outline-offset: 2px;
-  }
-}

package/template/app/layout.tsx

@@ -9,21 +9,21 @@ export default async function RootLayout({ children }: { children: React.ReactNo
   const user = await getCurrentUser();
   return (
     <html lang="en">
-      <body className="min-h-screen">
-        <header className="border-b border-border bg-card">
-          <nav className="mx-auto flex max-w-4xl flex-wrap items-center gap-x-4 gap-y-1 px-4 py-2 text-sm">
-            <Link href="/" className="inline-flex min-h-11 items-center font-semibold">Praxis App</Link>
-            <span className="hidden flex-1 sm:block" />
+      <body className="min-h-screen bg-slate-50 text-slate-900 antialiased">
+        <header className="border-b border-slate-200 bg-white">
+          <nav className="mx-auto flex max-w-4xl items-center gap-4 px-4 py-3 text-sm">
+            <Link href="/" className="font-semibold">Praxis App</Link>
+            <span className="flex-1" />
             {user ? (
               <>
-                <Link href="/account" className="inline-flex min-h-11 items-center">Account</Link>
-                {user.role === "admin" && <Link href="/admin" className="inline-flex min-h-11 items-center">Admin</Link>}
-                <form action="/logout" method="post"><button className="inline-flex min-h-11 items-center text-muted-foreground underline-offset-4 hover:underline">Sign out ({user.username})</button></form>
+                <Link href="/account">Account</Link>
+                {user.role === "admin" && <Link href="/admin">Admin</Link>}
+                <form action="/logout" method="post"><button className="text-slate-600 hover:underline">Sign out ({user.username})</button></form>
               </>
             ) : (
               <>
-                <Link href="/login" className="inline-flex min-h-11 items-center">Sign in</Link>
-                <Link href="/register" className="inline-flex min-h-11 items-center">Sign up</Link>
+                <Link href="/login">Sign in</Link>
+                <Link href="/register">Sign up</Link>
               </>
             )}
           </nav>

package/template/app/login/page.tsx

@@ -16,7 +16,7 @@ export default async function Login({ searchParams }: { searchParams: Promise<{
           <input type="hidden" name="next" value={next ?? ""} />
           <div className="space-y-1.5"><Label htmlFor="username">Username</Label><Input id="username" name="username" autoComplete="username" required /></div>
           <div className="space-y-1.5"><Label htmlFor="password">Password</Label><Input id="password" name="password" type="password" autoComplete="current-password" required /></div>
-          {error && <p role="alert" className="text-sm text-destructive">{error}</p>}
+          {error && <p role="alert" className="text-sm text-red-600">{error}</p>}
           <Button type="submit" className="w-full">Sign in</Button>
         </form>
         <p className="mt-4 text-sm"><Link className="underline" href="/register">Create an account</Link></p>

package/template/app/register/page.tsx

@@ -15,7 +15,7 @@ export default async function Register({ searchParams }: { searchParams: Promise
         <form action="/api/auth/register" method="post" className="space-y-4">
           <div className="space-y-1.5"><Label htmlFor="username">Username</Label><Input id="username" name="username" autoComplete="username" required /></div>
           <div className="space-y-1.5"><Label htmlFor="password">Password</Label><Input id="password" name="password" type="password" autoComplete="new-password" required /></div>
-          {error && <p role="alert" className="text-sm text-destructive">{error}</p>}
+          {error && <p role="alert" className="text-sm text-red-600">{error}</p>}
           <Button type="submit" className="w-full">Create account</Button>
         </form>
         <p className="mt-4 text-sm"><Link className="underline" href="/login">Already have an account?</Link></p>

package/template/components/ui/button.tsx

@@ -3,15 +3,15 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "@/lib/utils";
 
 const buttonVariants = cva(
-  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 disabled:pointer-events-none disabled:opacity-50",
   {
     variants: {
       variant: {
-        default: "bg-primary text-primary-foreground hover:bg-primary/90",
-        outline: "border border-input bg-card text-card-foreground hover:bg-accent",
-        ghost: "hover:bg-accent hover:text-accent-foreground",
+        default: "bg-slate-900 text-white hover:bg-slate-800",
+        outline: "border border-slate-300 bg-white hover:bg-slate-50",
+        ghost: "hover:bg-slate-100",
       },
-      size: { default: "h-11 px-5 py-2", sm: "h-11 px-4" },
+      size: { default: "h-9 px-4 py-2", sm: "h-8 px-3" },
     },
     defaultVariants: { variant: "default", size: "default" },
   },

package/template/components/ui/card.tsx

@@ -4,7 +4,7 @@ import { cn } from "@/lib/utils";
 type DivProps = React.HTMLAttributes<HTMLDivElement>;
 
 export function Card({ className, ...props }: DivProps) {
-  return <div className={cn("rounded-lg border border-border bg-card text-card-foreground shadow-sm", className)} {...props} />;
+  return <div className={cn("rounded-lg border border-slate-200 bg-white shadow-sm", className)} {...props} />;
 }
 export function CardHeader({ className, ...props }: DivProps) {
   return <div className={cn("flex flex-col gap-1.5 p-6", className)} {...props} />;

package/template/components/ui/input.tsx

@@ -5,7 +5,7 @@ export function Input({ className, ...props }: React.InputHTMLAttributes<HTMLInp
   return (
     <input
       className={cn(
-        "flex h-11 w-full rounded-md border border-input bg-card px-3 py-2 text-base shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50",
+        "flex h-9 w-full rounded-md border border-slate-300 bg-white px-3 py-1 text-sm shadow-sm placeholder:text-slate-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-400 disabled:opacity-50",
         className,
       )}
       {...props}

package/template/tailwind.config.ts

@@ -1,35 +1,7 @@
 import type { Config } from "tailwindcss";
 
-const token = (name: string) => `hsl(var(--${name}) / <alpha-value>)`;
-const pair = (name: string) => ({ DEFAULT: token(name), foreground: token(`${name}-foreground`) });
-
 export default {
   content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
-  theme: {
-    extend: {
-      colors: {
-        background: token("background"),
-        foreground: token("foreground"),
-        card: pair("card"),
-        muted: pair("muted"),
-        border: token("border"),
-        input: token("input"),
-        ring: token("ring"),
-        primary: pair("primary"),
-        accent: pair("accent"),
-        destructive: pair("destructive"),
-        success: pair("success"),
-        warning: pair("warning"),
-      },
-      borderRadius: {
-        lg: "var(--radius)",
-        md: "calc(var(--radius) - 2px)",
-        sm: "calc(var(--radius) - 4px)",
-      },
-      fontFamily: {
-        sans: ["-apple-system", '"PingFang SC"', '"Hiragino Sans GB"', '"Microsoft YaHei"', '"Noto Sans SC"', "sans-serif"],
-      },
-    },
-  },
+  theme: { extend: {} },
   plugins: [],
 } satisfies Config;

package/references/design.md

@@ -1,113 +0,0 @@
-# Designing the app's interface
-
-Read this before you build or restyle pages. The people who use these apps are the merchant's own customers and staff, not developers. Most customers arrive on a phone, often inside WeChat's in-app browser. Staff use the admin area on a laptop. The goal is an interface that looks like it was made for this business, works with one thumb, and never makes a customer wonder what to do next.
-
-## 1. Decide the look before writing markup
-
-Write a five-line design brief for yourself, grounded in the business, not in "modern and clean":
-- **Who and where**: for example "pet owners booking on their phone between errands" or "front-desk staff checking today's list on a laptop".
-- **Feel**: two or three adjectives taken from the business itself. A pet groomer is warm and playful, a law office calm and formal, a bakery homemade and appetizing.
-- **Palette**: 4–6 colors with names and hex values. One brand color for the primary action and the current selection, one neutral family for text and surfaces, and the status colors (success, warning, danger). Pick the brand color from the business (its sign, its product, its logo), not purple by default.
-- **Type**: see section 4. Mostly size, weight and spacing; the font family is fixed.
-- **One memorable thing**: choose the single element that carries the personality, such as a big photo on the home page, an illustrated service card, or a bold headline. Keep everything else quiet.
-
-Put the palette into the design tokens in `app/globals.css` and `tailwind.config.ts` (section 2). Never scatter hex values through pages.
-
-### Looks that read as "generated"
-Avoid these unless the user asks for them:
-- a purple-to-blue gradient hero;
-- every section chopped into identical rounded cards with the same grey shadow;
-- a small all-caps label above every heading;
-- one word in a headline highlighted in another color;
-- emoji used as icons;
-- fade-and-slide-up animation on every section;
-- "→" appended to every button.
-
-## 2. Tokens: change the look in one place
-
-The template's colors and radius live as CSS variables in `app/globals.css` (`--background`, `--foreground`, `--muted`, `--muted-foreground`, `--border`, `--primary`, `--primary-foreground`, `--accent`, `--destructive`, `--success`, `--warning`, `--radius`). `tailwind.config.ts` maps them to classes such as `bg-primary`, `text-muted-foreground` and `border-border`.
-
-- Pages and components use only these semantic classes, never raw palette classes such as `bg-slate-900` or `text-pink-500`.
-- To rebrand, edit the variables. A site name, a brand color and a radius change should touch only `globals.css`, `tailwind.config.ts` and `app/layout.tsx`.
-- Every background color has a matching foreground for text on it, with at least 4.5:1 contrast. Check the brand color against white text before you use it on buttons.
-
-## 3. Layouts by kind of app
-
-Pick the pattern that matches the request, then adapt it.
-
-**Booking and services** (groomer, salon, clinic, class, repair):
-- Home: what the business offers, a photo, and one primary button, "Book now".
-- Service list: cards with name, price, duration and a one-line description.
-- Booking flow:
-  1. Choose a service.
-  2. Pick a day from a horizontal strip of the next days, with the weekday shown.
-  3. Pick a time from a grid of tappable time chips. Show full slots as disabled; do not hide them.
-  4. Add details.
-  5. Confirm.
-  Never use a plain `<select>` for dates or times.
-- Confirmation page: a summary of what, when, where and the price, plus what happens next.
-- "My bookings": upcoming first, each with a status badge and the actions that are allowed.
-
-**Store and catalog** (shop, menu, product list):
-- A grid of product cards, two columns on phones, with photo, name and price.
-- A detail page with a large photo and one primary action.
-- The cart or order summary is reachable from every page.
-
-**Membership and content** (club, community, course):
-- A feed or list of items with clear ownership ("added by …").
-- A profile or account page with the member's own items.
-- Creating content is one obvious button.
-
-**Admin area** (every app has one):
-- Laptop first. A left sidebar or top tabs for sections.
-- Up top, the few numbers that matter today (today's bookings, pending, new members), each linking to the filtered list.
-- Tables with filters by status, a search box, status badges, and row actions on the right.
-- Put the next action first: "3 bookings waiting for confirmation" with a button, not just a chart.
-- Destructive actions (cancel, delete) ask for confirmation.
-
-**Lead or registration form** (event sign-up, enquiry):
-- One column with only the fields that are needed.
-- A clear thank-you page that says what happens next.
-
-## 4. Phones and Chinese text
-
-- **Mobile first.** Design at 390 px wide first, then widen. Use one column on phones. The primary action on long forms and booking steps sits in a bar fixed to the bottom of the screen.
-- **Tap targets** are at least 44×44 px, with at least 8 px between them. Nothing may depend on hover.
-- **Inputs** use the right type (`tel`, `email`, `number`, `date`) so phones show the right keyboard. Labels sit above fields, never only as a placeholder.
-- **WeChat in-app browser**: avoid fixed headers taller than 56 px, do not rely on new tabs or pop-ups, and keep pages fast because the network may be slow. Use no web fonts for Chinese (section below) and compress uploaded images.
-- **Chinese type**:
-  - Use the system font stack only: `-apple-system, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans SC", sans-serif`. Chinese web fonts weigh several megabytes, so do not load them.
-  - Body text is 16 px on phones with line height 1.7.
-  - Headings are bold, not huge (20–28 px on phones).
-  - Do not use letter-spacing, italics or all-caps on Chinese text.
-  - Use Chinese punctuation in Chinese sentences.
-- **Language**: write the interface in the user's language. For a Chinese request, every label, button, message and date is Chinese, and `app/layout.tsx` sets `<html lang="zh-CN">`. Show dates as `10月28日 周三`, times as `14:00`, money as `¥228`. Format dates, times and sizes through `lib/format.ts` (set its `LOCALE` and `TIME_ZONE` for the audience), never by printing raw ISO strings or byte counts.
-
-## 5. Every screen has four states
-
-- **Empty**: say why it is empty and offer the next action ("还没有预约 · 去预约第一次洗护"). Never show an empty table with headers only.
-- **Loading**: keep the layout steady; use skeleton blocks for lists.
-- **Error**: say what went wrong and how to fix it, next to the thing that failed. Keep what the user typed: when a form fails validation, re-render the form with the values and the field errors, instead of redirecting to an empty form.
-- **Success**: confirm with the same verb as the button. "确认预约" leads to "预约已确认", followed by where to go next.
-
-Disable a submit button while it is submitting, so a double tap cannot create two bookings.
-
-## 6. Words on the screen
-
-- Name things the way customers say them ("预约", "我的宠物"), not the way the code does ("appointment record", "entity").
-- Buttons say exactly what happens: "确认预约", not "提交".
-- Never show ids, raw status codes, English enum values or stack traces to customers. Map statuses to words and colors: 待确认 (warning), 已确认 (primary), 已完成 (success), 已取消 (muted).
-- No filler paragraphs that explain the interface.
-
-## 7. Quality floor
-
-- Contrast is at least 4.5:1 for text.
-- Focus is visible for keyboard users.
-- Every image has an `alt`.
-- Buttons are `<button>` and links are `<a>`.
-- Forms work without JavaScript, which the template's plain form posts already do.
-- Pages use no horizontal scroll at 360 px.
-
-## 8. Look at it before you report
-
-If the `control-browser` skill is available, take screenshots of the home page, the main flow and the admin area at 390 px and at 1280 px wide, and fix what looks off: overflowing text, cramped buttons, misaligned columns, an empty state that shows nothing. Remove one decoration before you finish. Without a browser, at least fetch every page over HTTP and check that it renders the real content and the Chinese text you expect.

package/references/research.md

@@ -1,56 +0,0 @@
-# Find before you build: research and spike
-
-Before you build anything beyond plain pages, forms and tables, find out how others solve it, pick an existing library or component, and prove it works here with a small spike. Typical cases:
-- a date or time picker, calendar view or scheduling grid;
-- charts;
-- maps or address input;
-- rich text or Markdown editing;
-- drag and drop;
-- image cropping;
-- QR codes;
-- CSV or Excel export;
-- PDF output;
-- search;
-- payments;
-- notifications.
-
-Hand-writing these costs hours and usually ends up worse than an existing library.
-
-## 1. Look for the pattern (5 minutes)
-
-- **How do well-known products present it?** With the `control-browser` skill, open one or two products that do the same job and take screenshots. A booking flow might come from a salon or clinic booking site; an order list from a delivery or shop admin. Note what to copy: step order, which fields, how errors and empty states look. Copy the structure, never the brand.
-- **Is it already in the template?** Check `components/ui/` and `lib/` first, and reuse what is there.
-
-## 2. Pick a candidate (5 minutes)
-
-Prefer, in this order:
-1. **shadcn/ui components and blocks** (ui.shadcn.com). Copy the component source into `components/ui/`. They match the template's Tailwind and token setup. Most rely on Radix UI primitives (`@radix-ui/react-*`); install the ones a component imports.
-2. **A focused, popular npm package** for the job, for example `date-fns` for dates, `react-day-picker` for calendars, `recharts` for charts, `qrcode` for QR codes, `papaparse` for CSV, and `@tiptap/react` for rich text. These names are starting points, not rules: check them with the questions below.
-3. **Your own code**, only when the job is small or nothing passes the checks.
-
-For each candidate, answer these questions. If any answer is "no", drop it:
-
-| Question | How to check |
-|---|---|
-| Does it run on Cloudflare Workers (server parts) or in the browser (client parts)? | No native modules, no `fs` or `child_process` at runtime, no long-lived servers. Browser-only libraries go in `"use client"` components. |
-| Is it maintained? | A release in the last 12 months (`npm view <pkg> time.modified`), and real usage (weekly downloads). |
-| Is the license usable? | MIT, Apache-2.0, BSD or ISC. Avoid GPL and AGPL in the merchant's app. |
-| Is it small enough? | Check the bundle size (bundlephobia, or the build output). The whole Worker must stay well under 10 MB. Prefer libraries that tree-shake. |
-| Does it work for the users' region? | For users in mainland China, avoid anything that loads from Google (Maps, Fonts, reCAPTCHA) or other blocked hosts at runtime. Use regional services instead, for example AMap or Tencent Maps for maps. |
-| Does it support the language? | Chinese labels and locale for dates (`date-fns/locale/zh-CN`), numbers and calendars. |
-
-## 3. Spike it (10–15 minutes)
-
-1. Install only the chosen package.
-2. Build the smallest real use on a scratch page (for example `app/_spike/page.tsx`): the actual component with real data shapes, not a toy.
-3. Run `bun run build`. The build must pass and must not grow by more than you expected; compare the size of `dist/` before and after.
-4. If it has a server part, call it from a route handler and run `bun run dev` to see it work.
-5. If the user gave a deploy target, a spike can go live with `praxis app deploy`, but remove the scratch page before the real release.
-
-If the spike fails, try the next candidate. **Two failed candidates means stop and tell the user** what you tried and what you suggest instead (a simpler feature, or your own code), rather than fighting the platform.
-
-## 4. Adopt and record
-
-- Move the spike into the real feature and delete the scratch page.
-- Add one line per adopted library under "## Libraries" in the project's `README.md`: name, what it is for, and why it was chosen ("react-day-picker: booking calendar; Workers-safe, 12 kB, zh-CN locale").
-- In the report to the user, mention a library only when it affects them, for example a map provider that needs their own key.

package/template/components/ui/badge.tsx

@@ -1,26 +0,0 @@
-import * as React from "react";
-import { cva, type VariantProps } from "class-variance-authority";
-import { cn } from "@/lib/utils";
-
-const badgeVariants = cva(
-  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold",
-  {
-    variants: {
-      variant: {
-        default: "border-transparent bg-primary text-primary-foreground",
-        secondary: "border-transparent bg-accent text-accent-foreground",
-        success: "border-transparent bg-success text-success-foreground",
-        warning: "border-transparent bg-warning text-warning-foreground",
-        destructive: "border-transparent bg-destructive text-destructive-foreground",
-        outline: "border-border text-foreground",
-      },
-    },
-    defaultVariants: { variant: "default" },
-  },
-);
-
-export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {}
-
-export function Badge({ className, variant, ...props }: BadgeProps) {
-  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
-}

package/template/lib/design-tokens.test.ts

@@ -1,90 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import fs from "node:fs";
-import path from "node:path";
-
-const root = path.join(import.meta.dir, "..");
-
-/** WCAG 2.x contrast ratio between two HSL triplets written as "H S% L%". */
-export function hslToRgb(triplet: string): [number, number, number] {
-  const m = triplet.trim().match(/^(-?[\d.]+)\s+([\d.]+)%\s+([\d.]+)%$/);
-  if (!m) throw new Error(`not an HSL triplet: "${triplet}"`);
-  const h = ((Number(m[1]) % 360) + 360) % 360, s = Number(m[2]) / 100, l = Number(m[3]) / 100;
-  const k = (n: number) => (n + h / 30) % 12;
-  const a = s * Math.min(l, 1 - l);
-  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
-  return [f(0), f(8), f(4)];
-}
-export function contrast(fg: string, bg: string): number {
-  const lum = (t: string) => {
-    const [r, g, b] = hslToRgb(t).map(c => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)) as [number, number, number];
-    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-  };
-  const [hi, lo] = [lum(fg), lum(bg)].sort((x, y) => y - x) as [number, number];
-  return (hi + 0.05) / (lo + 0.05);
-}
-
-function tokens(): Record<string, string> {
-  const css = fs.readFileSync(path.join(root, "app/globals.css"), "utf8");
-  const block = css.match(/:root\s*\{([^}]*)\}/)?.[1] ?? "";
-  return Object.fromEntries([...block.matchAll(/--([\w-]+):\s*([^;]+);/g)].map(m => [m[1]!, m[2]!.trim()]));
-}
-
-const REQUIRED = [
-  "background", "foreground", "card", "card-foreground", "muted", "muted-foreground", "border", "input", "ring",
-  "primary", "primary-foreground", "accent", "accent-foreground", "destructive", "destructive-foreground",
-  "success", "success-foreground", "warning", "warning-foreground", "radius",
-];
-// [foreground token, background token] pairs that carry text.
-const PAIRS: [string, string][] = [
-  ["foreground", "background"], ["card-foreground", "card"], ["muted-foreground", "background"], ["muted-foreground", "card"],
-  ["muted-foreground", "muted"], ["primary-foreground", "primary"], ["accent-foreground", "accent"],
-  ["destructive-foreground", "destructive"], ["success-foreground", "success"], ["warning-foreground", "warning"],
-  ["destructive", "background"], ["destructive", "card"],
-];
-
-describe("design tokens", () => {
-  const t = tokens();
-  test("every required token is defined", () => {
-    expect(REQUIRED.filter(k => !(k in t))).toEqual([]);
-  });
-  for (const [fg, bg] of PAIRS) {
-    test(`${fg} on ${bg} has at least 4.5:1 contrast`, () => {
-      const ratio = contrast(t[fg]!, t[bg]!);
-      expect(ratio, `${fg} (${t[fg]}) on ${bg} (${t[bg]}) is ${ratio.toFixed(2)}:1`).toBeGreaterThanOrEqual(4.5);
-    });
-  }
-  test("contrast function matches known values", () => {
-    expect(contrast("0 0% 0%", "0 0% 100%")).toBeCloseTo(21, 1);
-    expect(contrast("0 0% 100%", "0 0% 100%")).toBeCloseTo(1, 5);
-  });
-});
-
-const PALETTE = "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
-const RAW_COLOR = new RegExp(`\\b(?:bg|text|border|ring|from|to|via|fill|stroke|outline|divide|placeholder|decoration|shadow)-(?:${PALETTE})-\\d+\\b`, "g");
-const HEX_IN_CLASS = /className\s*=\s*(?:"[^"]*|'[^']*|\{[^}]*)#[0-9a-fA-F]{3,8}\b|\[(?:#[0-9a-fA-F]{3,8})\]/g;
-
-function sources(dir: string): string[] {
-  const out: string[] = [];
-  const abs = path.join(root, dir);
-  if (!fs.existsSync(abs)) return out;
-  for (const e of fs.readdirSync(abs, { recursive: true, withFileTypes: true })) {
-    if (e.isFile() && /\.(ts|tsx)$/.test(e.name)) out.push(path.relative(root, path.join(e.parentPath, e.name)));
-  }
-  return out;
-}
-
-export function findRawColors(file: string, text: string): string[] {
-  return [...(text.match(RAW_COLOR) ?? []), ...(text.match(HEX_IN_CLASS) ?? [])].map(c => `${file}: ${c}`);
-}
-
-describe("semantic classes only", () => {
-  test("detector flags palette classes and hex colors", () => {
-    expect(findRawColors("x.tsx", `<p className="bg-slate-900 hover:text-pink-500">`)).toHaveLength(2);
-    expect(findRawColors("x.tsx", `<p className="bg-[#ff0000]">`)).toHaveLength(1);
-    expect(findRawColors("x.tsx", `<p className="bg-primary text-muted-foreground">`)).toEqual([]);
-  });
-  test("app/ and components/ use no raw palette class or hex color", () => {
-    const hits = [...sources("app"), ...sources("components")].flatMap(f => findRawColors(f, fs.readFileSync(path.join(root, f), "utf8")));
-    expect(hits, `Use semantic classes (bg-primary, text-muted-foreground, text-destructive...) or edit the tokens in app/globals.css:\n${hits.join("\n")}`).toEqual([]);
-  });
-});

package/template/lib/format.test.ts

@@ -1,12 +0,0 @@
-import { expect, test } from "bun:test";
-import { formatBytes, formatDateTime } from "./format";
-
-test("dates show minutes in the app time zone, not raw ISO", () => {
-  expect(formatDateTime(Date.UTC(2026, 9, 25, 15, 3, 49))).toBe("2026-10-25 23:03");
-});
-
-test("sizes use readable units", () => {
-  expect(formatBytes(70)).toBe("70 B");
-  expect(formatBytes(12_595)).toBe("12.3 KB");
-  expect(formatBytes(4_718_592)).toBe("4.5 MB");
-});

package/template/lib/format.ts

@@ -1,18 +0,0 @@
-// How dates and sizes read on screen. Change TIME_ZONE and LOCALE for the app's audience.
-export const TIME_ZONE = "Asia/Shanghai";
-export const LOCALE = "en-GB";
-
-/** 2026-10-25 23:03 in TIME_ZONE; never a raw ISO string on screen. */
-export function formatDateTime(ms: number): string {
-  const parts = Object.fromEntries(new Intl.DateTimeFormat(LOCALE, {
-    timeZone: TIME_ZONE, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23",
-  }).formatToParts(new Date(ms)).map(p => [p.type, p.value]));
-  return `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute}`;
-}
-
-/** 70 B, 12.3 KB, 4.5 MB. */
-export function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-}