@webjsdev/cli 0.10.40 → 0.10.41

package/templates/.claude/skills/webjs-design-review/SKILL.md

@@ -1,84 +0,0 @@
----
-name: webjs-design-review
-description: >-
-  Render-and-look review for ANY UI work in a WebJs app. Invoke after building
-  or changing a page, layout, or component, and before you report the work done.
-  Triggers: "build", "create", "add a page", "component", "layout", "style",
-  "design", "UI", "screen", "board", "form", "dashboard", "make it look".
----
-
-# Render the app and LOOK before you call UI work done
-
-You write CSS blind. You never see the pixels, so a whole class of defects ships
-silently: `webjs check` passes, `webjs typecheck` passes, the server boots, and
-the app still looks broken. A collapsed component, cells of unequal size, a
-layout that resizes as it fills with content, text that overflows its box, an
-app that just kept the scaffold's colors and chrome, none of these fail a test.
-The only thing that catches them is rendering the app and looking at it.
-
-So for ANY work that touches a page, layout, or component, this is the loop:
-
-## 1. Run the app and open what you changed
-
-```sh
-webjs dev            # or: webjs start, for the production render
-```
-
-Open every route you touched in a real browser. Use the browser MCP
-(`mcp__playwright__*` or `mcp__chrome-devtools__*`) if available so you can drive
-and screenshot it; otherwise open it yourself and take screenshots.
-
-## 2. Drive EVERY state, not just the first paint
-
-The first paint is the easy case. Bugs hide in the states you reach by
-interacting. Play the app the way a user will:
-
-- A game board: play a full game. Fill it. Win. Draw. Reset. Watch whether the
-  board or its cells change size as marks appear (they must NOT).
-- A list: empty, one item, many items, an item long enough to wrap.
-- A form: empty, invalid, submitted, error returned, success.
-- Anything async: loading, loaded, error, refetch.
-
-Reload each state. Resize the window narrow (mobile) and wide.
-
-## 3. Confirm the things a test can't
-
-Look at each state and confirm, with your eyes:
-
-1. **Nothing collapses, overflows, or resizes.** A container is the size it
-   should be (not 0-height, not collapsed to its content when it should fill).
-   Grid/flex children that should be equal ARE equal, and STAY equal as content
-   changes. Text stays inside its box.
-2. **The design is this app's OWN.** Not the scaffold shell, not its default
-   color tokens. The palette (real `oklch`/hex values, not just shadcn token
-   NAMES), the typography, the layout, and the chrome are chosen for THIS app.
-   "It still looks like the starter" is a defect to fix, not ship.
-3. **Light AND dark both look right.** Toggle the theme. Check contrast, that
-   nothing disappears against its background, that borders and shadows read.
-4. **It still renders with JavaScript OFF.** WebJs is SSR + progressive
-   enhancement, so the page must read and look right with no JS (disable it in
-   devtools, or load in a JS-off context). Content shows, `<a>` navigates,
-   forms submit, and CRUCIALLY the CSS is fully applied (the app links a static
-   compiled `public/tailwind.css`, so utilities resolve with no JS). An app that
-   goes unstyled or blank with JS off is a broken first paint, not a design to
-   ship.
-
-## 4. Iterate until it holds, then say what you saw
-
-If any of the above is wrong, fix it and re-render. Do not stop on the first
-render. When it holds, state in your final message WHAT you rendered and WHAT
-you confirmed (which states, light + dark), so the review is on the record.
-
----
-
-**Why this is a skill and not just a test:** a real-browser test
-(`webjs test --browser`) catches the mechanical failures (collapse, uneven
-cells, reflow) and you SHOULD ship one. There is no framework helper for this; a
-layout-stability check is a few lines you write against your own component (in a
-`*/test/**/browser/*.test.js`): measure `getBoundingClientRect()` on the grid
-children and assert they stay equal-sized before AND after a move, so a collapse
-or reflow FAILS the test. But "looks like the scaffold", "the
-palette is bland", "the spacing is off", "it's ugly in dark mode" are judgment
-calls no assertion makes for you. That is what this human-in-the-loop look is
-for. Do both: the test for the mechanical floor, the look for everything above
-it. See CONVENTIONS item 6 and `agent-docs/styling.md`.

package/templates/LAYOUT-REFERENCE.md

@@ -1,96 +0,0 @@
-# Layout reference
-
-`app/layout.ts` ships as a **minimal shell**: it wires the theme, design tokens,
-and the linked static Tailwind stylesheet, then renders `${children}` in a bare full-height
-container with no chrome. That is on purpose. A delivered app should design its
-own layout from what the app IS, not inherit a generic header and footer.
-
-This file is the **reference** for how to build a real layout: read it to learn
-the patterns (a fixed header, a brand mark, a nav, a theme toggle, a reading
-column, a footer), then write the layout your app actually needs in
-`app/layout.ts`. Decide from scratch: does a tic-tac-toe game want a header at
-all? Does a dashboard want a sidebar instead? Does a landing page want a
-full-bleed hero? Keep only what fits.
-
-> **This is ONE example, not a template to reproduce.** Reproducing this exact
-> header (a slim bar with a mark on the left and a theme toggle on the right)
-> just recreates the old scaffold look under a new name. It is here to show the
-> mechanics (how a header, nav, theme toggle, or footer are wired), not the
-> design. Design a layout that fits what THIS app is: a game might be a
-> full-bleed centered stage with no header; a tool might have a compact command
-> bar; a reader might have a wide sidebar. Take the mechanics, invent the form.
-
-You do not import from this file. Copy the mechanics you want into
-`app/layout.ts`'s returned template, inside the `<main>` (or replacing it), and
-restyle them into your own design.
-
-## A complete worked layout
-
-This is the chrome the scaffold used to ship inline. It goes in the body of
-`RootLayout`, after the `<script>`/`<style>` infrastructure blocks. `navLink` is a
-small SSR helper you would declare above `RootLayout`.
-
-```ts
-// Declare above RootLayout: a nav-link helper (SSR-time, no client runtime).
-const navLink = (href: string, label: string) => html`
-  <a href=${href} class="text-muted-foreground no-underline font-medium text-[13px] leading-none tracking-[0.005em] transition-colors duration-fast hover:text-foreground">${label}</a>
-`;
-
-// Inside RootLayout's returned html``, in place of the minimal <main>:
-
-// A fixed header (NOT sticky: a sticky header flickers on iOS WebKit during a
-// client-router nav). --header-h reserves its height for the content below; the
-// header-measure script already in app/layout.ts sets --header-h to the real
-// height the moment a <header> exists.
-<header class="fixed inset-x-0 top-0 z-20 flex items-center gap-6 px-4 sm:px-6 py-3 border-b border-border bg-[color-mix(in_oklch,var(--background)_75%,transparent)] backdrop-blur-[18px]">
-  <a href="/" class="mr-auto inline-flex items-center gap-2 no-underline text-foreground font-semibold text-[15px] leading-none tracking-tight">
-    <!-- Your brand or logo mark goes here. A glyph, a wordmark, the real product name. -->
-    <span>{{APP_NAME}}</span>
-  </a>
-  <nav class="flex gap-4 items-center">
-    <!-- Your app's real navigation (or drop the nav entirely for a single-page app). -->
-    ${navLink('/', 'Home')}
-    <theme-toggle></theme-toggle>
-  </nav>
-</header>
-
-// A content shell. The max-w-[760px] cap is a comfortable READING width, right
-// for prose, forms, and marketing. For a full-bleed app, dashboard, or board,
-// widen the cap (for example max-w-[1400px]) or drop the cap and mx-auto for an
-// edge-to-edge layout. A wide layout left in the 760px column overflows into a
-// horizontal scrollbar.
-<div class="flex flex-col min-h-[calc(100dvh-var(--header-h))]">
-  <main class="flex-1 w-full max-w-[760px] mx-auto px-4 sm:px-6 pt-[72px] pb-12">
-    ${children}
-  </main>
-  <!-- Your footer. Do NOT ship a "Built with webjs" footer: write your app's own. -->
-  <footer class="border-t border-border">
-    <div class="max-w-[760px] mx-auto px-4 sm:px-6 py-6 flex items-center justify-center">
-      <span class="text-sm text-muted-foreground">Your footer</span>
-    </div>
-  </footer>
-</div>
-```
-
-## The `theme-toggle` element
-
-The scaffold ships `components/theme-toggle.ts` (already imported by
-`app/layout.ts` as a side effect, so the element is registered). Place
-`<theme-toggle></theme-toggle>` wherever you want the light/dark switch, or delete
-the import and the theme apparatus in `app/layout.ts` for a single-theme app.
-
-## What stays in `app/layout.ts` no matter what
-
-The infrastructure above the `<main>` is not chrome and should stay:
-
-- the theme-detection `<script>` (light/dark apparatus) and the header-measure
-  script,
-- the `<link rel="stylesheet" href="/public/tailwind.css">` (the STATIC stylesheet
-  compiled from `public/input.css` by `css:build`, so the app is styled with JS
-  off),
-- the `<style>` block of design-token VALUES (`:root` / dark / light), which
-  carries its own `webjs-scaffold-placeholder` marker, so own the colors. The
-  Tailwind `@theme` maps that turn those tokens into utilities live in
-  `public/input.css`.
-
-Design the chrome; keep the plumbing.

package/templates/lib/utils/ui.ts

@@ -1,83 +0,0 @@
-/**
- * Shared UI helpers for pages, layouts, and components.
- *
- * When the same bundle of Tailwind classes repeats in 2+ places, extract
- * it here. The helper runs at SSR time inside `html\`\``, so the browser
- * receives fully materialised HTML: no client-side runtime, identical
- * output to writing the classes inline.
- *
- * When to extract:
- *   • Classes repeat 2+ times identically → extract.
- *   • Varies by 1–2 props → extract with a small parameter.
- *   • Radically different per call site → keep inline.
- *
- * This file lives under `_utils/`: any folder whose name starts with `_`
- * is ignored by the router, so it can never accidentally become a route.
- */
-import { html } from '@webjsdev/core';
-
-/** `● label` kicker: small caps, brand colour, above headings. */
-export function rubric(label: string, mb: 'sm' | 'md' = 'md') {
-  const mbCls = mb === 'sm' ? 'mb-3' : 'mb-4';
-  return html`
-    <span class="block font-mono text-[11px] leading-none font-semibold tracking-[0.2em] uppercase text-primary ${mbCls}">● ${label}</span>
-  `;
-}
-
-/** Monospaced small-caps label: for stats, counts, bylines. */
-export function stat(content: unknown, extraCls = '') {
-  return html`
-    <span class="font-mono text-[11px] leading-none font-medium tracking-[0.15em] uppercase text-fg-subtle ${extraCls}">${content}</span>
-  `;
-}
-
-/** "← label" back link. */
-export function backLink(href: string, label: string, mb: 'sm' | 'md' = 'md') {
-  const mbCls = mb === 'sm' ? 'mb-6' : 'mb-12';
-  return html`
-    <a href=${href} class="inline-block ${mbCls} text-fg-subtle no-underline font-mono text-[11px] leading-none font-medium tracking-[0.15em] uppercase transition-colors duration-fast hover:text-fg">← ${label}</a>
-  `;
-}
-
-/** Large display heading: home / detail hero. */
-export function displayH1(content: unknown) {
-  return html`
-    <h1 class="font-serif text-display leading-[1.02] tracking-[-0.035em] font-bold m-0 mb-6 text-balance">${content}</h1>
-  `;
-}
-
-/** Clamp-scale H1: login, compose, etc. */
-export function clampH1(content: unknown) {
-  return html`
-    <h1 class="font-serif text-[clamp(2rem,1.5rem+1.6vw,2.8rem)] leading-[1.08] tracking-[-0.03em] font-bold m-0 mb-6">${content}</h1>
-  `;
-}
-
-/** Section H2: serif subheading. */
-export function sectionH2(content: unknown, mb: 'sm' | 'md' = 'sm') {
-  const mbCls = mb === 'sm' ? 'mb-2' : 'mb-4';
-  return html`
-    <h2 class="font-serif text-[1.6rem] tracking-[-0.02em] font-bold m-0 ${mbCls}">${content}</h2>
-  `;
-}
-
-/** Notice / banner paragraph: soft card above primary content. */
-export function banner(content: unknown) {
-  return html`
-    <p class="p-6 bg-[color-mix(in_oklch,var(--bg-elev)_50%,transparent)] border border-border rounded-[10px] text-sm my-6 mb-12 text-fg-muted">${content}</p>
-  `;
-}
-
-/** Inline brand link: used inside body copy and banners. */
-export function accentLink(href: string, label: unknown) {
-  return html`
-    <a href=${href} class="text-primary font-semibold no-underline hover:underline hover:underline-offset-[3px]">${label}</a>
-  `;
-}
-
-/** Small code chip: inline monospaced token with a tinted surface. */
-export function codeChip(text: string) {
-  return html`
-    <code class="font-mono text-[0.88em] px-1.5 py-0.5 rounded-md bg-bg-subtle border border-border break-words [overflow-wrap:anywhere]">${text}</code>
-  `;
-}