@boopkit/cap-web 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,131 @@
+# @boopkit/cap-web
+
+**Part of [Boop](https://www.npmjs.com/package/@boopkit/cli)** — a bootstrap platform for AI-first builders. `boop init` scaffolds a running Node/TypeScript web app from composable **capabilities**, each one bundling the code, dependencies, middleware wiring, and agent skills needed for a feature. You pick the capabilities; `boop add` handles the rest.
+
+`cap-web` is the UI layer. It gives your Express app a Handlebars view engine, Tailwind CSS with a semantic-class convention, static asset serving, and a lightweight request logger — everything needed to render server-side pages with a clean HTML UI.
+
+## What You Get
+
+### Scaffold files
+
+Copied into your project on install:
+
+- `views/` — Handlebars templates (`home.hbs`, `about.hbs`, `404.hbs`) and `layouts/main.hbs`
+- `public/` — static assets served at `/` (`css/`, `favicon.svg`)
+- `styles/styles.css` — Tailwind input file with semantic class definitions using `@apply`
+- `tailwind.config.ts` — Tailwind configuration
+- `src/controllers/pages.ts` — example page controllers (`home`, `about`)
+- `src/routes/pages.ts` — Express router mounting the example pages
+- `reference/web-ui.ref.md` — reference doc describing the UI conventions
+
+### Scripts added to `package.json`
+
+| Script | Command |
+|--------|---------|
+| `tailwind:build` | `npx @tailwindcss/cli -i styles/styles.css -o public/css/style.css --minify` |
+| `tailwind:watch` | `npx @tailwindcss/cli -i styles/styles.css -o public/css/style.css --watch` |
+
+### Server hooks
+
+Wired into `src/server.ts` at install time:
+
+```ts
+import { configureViewEngine, configureStatic, requestLogger } from '@boopkit/cap-web';
+import pageRoutes from './routes/pages';
+
+// ...
+
+app.use(requestLogger());   // order 12 — logs method, URL, status, timing
+configureViewEngine(app);   // order 40 — Handlebars engine + layouts
+configureStatic(app);       // order 45 — serve ./public with cache headers
+app.use(pageRoutes);        // order 50 — mount the example pages
+```
+
+Order numbers are the `preRoutes` phase ordering; other capabilities slot themselves around these (for example, `cap-api`'s error handler mounts after route handlers).
+
+### Skills installed
+
+- `design.web-ui-design.skill.md` — teaches agents the semantic-CSS convention and view-rendering patterns used in boop web apps.
+
+### Post-install
+
+Run `npm run tailwind:build` once after install to compile `styles/styles.css` into `public/css/style.css`. `boop status` reminds you of this.
+
+## Requirements
+
+**Other capabilities:** none — `cap-web` is self-contained.
+
+**npm dependencies added to your project:**
+
+- `express-handlebars` — view engine binding
+- `tailwindcss` — utility-first CSS framework
+- `@tailwindcss/cli` (devDependency) — CSS compilation
+
+**Peer dependencies** (already provided by the `web-app` kernel):
+
+- `express >=4.0.0`
+- `express-handlebars >=7.0.0`
+- `handlebars >=4.0.0`
+
+**Environment variables:** none required. `NODE_ENV=production` enables a 1-day cache on static assets; otherwise caching is disabled.
+
+## Usage
+
+A page in a boop web app is three small files plus styles. Here's how to add one from scratch:
+
+**1.** Create a view at `views/dashboard.hbs`:
+
+```handlebars
+<main class="dashboard-page">
+  <h1 class="page-title">Dashboard</h1>
+  <p class="page-subtitle">Welcome back, {{user.name}}.</p>
+</main>
+```
+
+**2.** Add a controller in `src/controllers/pages.ts`:
+
+```ts
+export function dashboard(_req: Request, res: Response): void {
+  res.render('dashboard', { user: { name: 'Ada' } });
+}
+```
+
+**3.** Mount the route in `src/routes/pages.ts`:
+
+```ts
+router.get('/dashboard', pages.dashboard);
+```
+
+**4.** Add semantic styles in `styles/styles.css`:
+
+```css
+.dashboard-page {
+    @apply px-6 py-4;
+
+    .page-title { @apply text-2xl font-bold; }
+    .page-subtitle { @apply text-sm text-gray-600 mt-2; }
+}
+```
+
+**5.** Rebuild CSS and restart the dev server:
+
+```bash
+npm run tailwind:build
+npm run dev
+```
+
+Visit `/dashboard`.
+
+### CSS convention
+
+`cap-web` favours **semantic CSS classes** (e.g. `page-title`, `dashboard-page`) defined in `styles.css` with Tailwind's `@apply`, over presentational utility classes in the markup. Templates stay readable as the UI grows, and visual changes happen in one place. See `reference/web-ui.ref.md` for the full rationale.
+
+## Added by
+
+Included by default in the `web-app` profile.
+
+Add to an existing project with:
+
+```bash
+boop add web
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-web",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Express view engine configuration, Handlebars helpers, and static asset middleware",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,6 +8,7 @@
     "dist/",
     "scaffold/",
     "skills/",
+    "styles/",
     "capability.json"
   ],
   "boopkit": {

package/styles/base.css

@@ -0,0 +1,27 @@
+/* @boopkit/cap-web — Base semantic classes backed by @theme tokens.
+ * Override tokens in your project's @theme block to restyle all components. */
+
+.app-shell {
+  background-color: var(--color-surface);
+  color: var(--color-on-surface);
+  @apply min-h-screen flex flex-col;
+}
+
+.btn-primary {
+  background-color: var(--color-brand-600);
+  border-radius: var(--radius-lg);
+  @apply px-5 py-2.5 text-white font-medium transition-colors;
+
+  &:hover {
+    background-color: var(--color-brand-700);
+  }
+}
+
+.btn-secondary {
+  border-radius: var(--radius-lg);
+  @apply px-5 py-2.5 border border-gray-300 font-medium transition-colors;
+
+  &:hover {
+    background-color: var(--color-surface-alt);
+  }
+}

package/styles/theme.css

@@ -0,0 +1,35 @@
+/* @boopkit/cap-web — Default design tokens for boop projects.
+ * Override any token in your project's styles.css with a later @theme block. */
+@theme {
+  /* Brand color scale — emerald base, override for your brand */
+  --color-brand-50: #ecfdf5;
+  --color-brand-100: #d1fae5;
+  --color-brand-200: #a7f3d0;
+  --color-brand-300: #6ee7b7;
+  --color-brand-400: #34d399;
+  --color-brand-500: #10b981;
+  --color-brand-600: #059669;
+  --color-brand-700: #047857;
+  --color-brand-800: #065f46;
+  --color-brand-900: #064e3b;
+
+  /* Surface & text — warm neutrals that complement emerald */
+  --color-surface: #fafaf9;
+  --color-surface-alt: #f5f5f4;
+  --color-on-surface: #1c1917;
+  --color-on-surface-muted: #78716c;
+
+  /* Typography */
+  --font-sans: "Inter", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, monospace;
+
+  /* Border radii */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+
+  /* Layout spacing */
+  --spacing-page: 2rem;
+  --spacing-section: 3rem;
+}