From 4b7d28772b44f73f72d1d41d950c4c78fb43f742 Mon Sep 17 00:00:00 2001 From: t Date: Tue, 7 Jul 2026 11:09:58 +0530 Subject: [PATCH 1/2] docs: tell scaffold agents to use a unique design, not mimic the scaffold Every per-agent rule file already says to replace the example content but none said to give the app a DISTINCT look, so agents kept shipping the scaffold's palette/layout with new copy. Add a UI-scoped unique-design guideline alongside the scaffold-is-reference guidance in all five prose surfaces (AGENTS.md, CONVENTIONS.md, .cursorrules, copilot-instructions, .agents/rules/workflow.md) so every agent on every platform gets it. The api template has no UI, so the guideline is a natural no-op there. --- packages/cli/templates/.agents/rules/workflow.md | 5 +++++ packages/cli/templates/.cursorrules | 6 ++++++ packages/cli/templates/.github/copilot-instructions.md | 6 ++++++ packages/cli/templates/AGENTS.md | 8 +++++++- packages/cli/templates/CONVENTIONS.md | 10 +++++++++- 5 files changed, 33 insertions(+), 2 deletions(-) diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md index f510b1f8..39295902 100644 --- a/packages/cli/templates/.agents/rules/workflow.md +++ b/packages/cli/templates/.agents/rules/workflow.md @@ -19,6 +19,11 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**. the example `User` model, the example users module, etc. with the app the user actually asked for. Do not ship "Hello from " as the deliverable. +- **Use a unique design (UI apps).** When the app has a UI, give it a design of + your own (palette, layout, typography, chrome) that fits what the user asked + for. Do NOT mimic the scaffold's example look (its warm colors, the 760px + reading column, the example header/nav). Keep the design tokens and theme + setup in `app/layout.ts`, those are infrastructure, and restyle on top of them. - **Only three templates exist:** `webjs create ` (default full-stack), `--template api`, `--template saas`. The CLI rejects any other `--template` value. Pick: diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules index 34d2f735..124b73c4 100644 --- a/packages/cli/templates/.cursorrules +++ b/packages/cli/templates/.cursorrules @@ -18,6 +18,12 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**. `app/page.ts`, the example `User` model, the example users module, etc. with the app the user actually asked for. Don't ship "Hello from " as the deliverable. +- **Use a unique design (UI apps).** When the app has a UI, give it a + design of your own (palette, layout, typography, chrome) that fits what + the user asked for. Do NOT mimic the scaffold's example look (its warm + colors, the 760px reading column, the example header/nav). Keep the + design tokens and theme setup in `app/layout.ts`, those are + infrastructure, and restyle on top of them. - **Only three templates exist:** `webjs create ` (default full-stack), `--template api`, `--template saas`. The CLI rejects any other `--template` value. Pick: diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md index c5b38fdf..2f0c9bc6 100644 --- a/packages/cli/templates/.github/copilot-instructions.md +++ b/packages/cli/templates/.github/copilot-instructions.md @@ -18,6 +18,12 @@ the full hosted docs are at **https://docs.webjs.com**. `app/page.ts`, the example `User` model, the example users module, etc. with the app the user actually asked for. Don't ship "Hello from " as the deliverable. +- **Use a unique design (UI apps).** When the app has a UI, give it a + design of your own (palette, layout, typography, chrome) that fits what + the user asked for. Do NOT mimic the scaffold's example look (its warm + colors, the 760px reading column, the example header/nav). Keep the + design tokens and theme setup in `app/layout.ts`, those are + infrastructure, and restyle on top of them. - **Only three templates exist:** `webjs create ` (default full-stack), `--template api`, `--template saas`. The CLI rejects any other `--template` value. Pick: diff --git a/packages/cli/templates/AGENTS.md b/packages/cli/templates/AGENTS.md index 563aefaf..ea633b39 100644 --- a/packages/cli/templates/AGENTS.md +++ b/packages/cli/templates/AGENTS.md @@ -20,7 +20,13 @@ example `Home` nav, and pick a content-width container that fits. The default `
` is a reading column for prose and forms, so for a full-bleed app, dashboard, or board, widen the cap or remove it (keep the theme tokens). A wide layout left in the 760px -reading column overflows into a horizontal scrollbar. This is ENFORCED: +reading column overflows into a horizontal scrollbar. **Give the app a +unique design.** When it has a UI, choose its palette, layout, typography, +and chrome to fit what the user asked for, rather than mimicking the +scaffold's example look (the warm accent, the reading column, the serif +display, the example header/nav) or just recoloring the same layout. The +`api` template has no UI, so this does not apply there. The design tokens +and theme wiring are infrastructure to keep and restyle on top of. This is ENFORCED: the example `app/page.ts` and `app/layout.ts` carry a `webjs-scaffold-placeholder` marker comment, and `webjs check` fails while any marker remains, so this freshly scaffolded app fails the check diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md index 956554cf..b8aea701 100644 --- a/packages/cli/templates/CONVENTIONS.md +++ b/packages/cli/templates/CONVENTIONS.md @@ -333,7 +333,15 @@ When the user asks the agent to build their actual app: dashboard, or board, or a wide layout overflows into an unnecessary horizontal scrollbar. Keep the design tokens and theme setup, those are infrastructure. -6. **Keep:** the Drizzle setup, the test config, the agent config files +6. **Use a unique design (UI apps).** Give the app a look of its own that + fits what the user asked for. Choose the palette, layout, typography, + spacing, and chrome deliberately. Do NOT mimic the scaffold's example + look (its warm accent, the 760px reading column, the serif display, the + example header/nav), and do not just recolor the same layout. The + `api` template has no UI, so this does not apply there. The design + tokens and theme wiring in `app/layout.ts` are infrastructure to keep + and restyle on top of, not the example look to preserve. +7. **Keep:** the Drizzle setup, the test config, the agent config files (`AGENTS.md`, `CONVENTIONS.md`, `CLAUDE.md`, `.cursorrules`, etc.), `db/connection.server.ts` + `db/columns.server.ts`, the directory conventions, the design tokens in `app/layout.ts`. These are the From 3e4aebb1a56797a9b33197e8ee1aabb7a572db65 Mon Sep 17 00:00:00 2001 From: t Date: Tue, 7 Jul 2026 11:19:47 +0530 Subject: [PATCH 2/2] docs: add the api-template carve-out to the three rule-file variants AGENTS.md and CONVENTIONS.md scoped the unique-design guideline with an explicit 'the api template has no UI, so this does not apply there', but the three condensed rule files (.cursorrules, copilot-instructions, workflow.md) ended with an unconditional app/layout.ts reference. Add the same carve-out so an agent building an api app (no layout, no UI) is not misdirected, keeping all five surfaces consistent. --- packages/cli/templates/.agents/rules/workflow.md | 5 +++-- packages/cli/templates/.cursorrules | 7 ++++--- packages/cli/templates/.github/copilot-instructions.md | 7 ++++--- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/packages/cli/templates/.agents/rules/workflow.md b/packages/cli/templates/.agents/rules/workflow.md index 39295902..28afb1f6 100644 --- a/packages/cli/templates/.agents/rules/workflow.md +++ b/packages/cli/templates/.agents/rules/workflow.md @@ -22,8 +22,9 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**. - **Use a unique design (UI apps).** When the app has a UI, give it a design of your own (palette, layout, typography, chrome) that fits what the user asked for. Do NOT mimic the scaffold's example look (its warm colors, the 760px - reading column, the example header/nav). Keep the design tokens and theme - setup in `app/layout.ts`, those are infrastructure, and restyle on top of them. + reading column, the example header/nav). The `api` template has no UI, so this + does not apply there. Keep the design tokens and theme setup in + `app/layout.ts`, those are infrastructure, and restyle on top of them. - **Only three templates exist:** `webjs create ` (default full-stack), `--template api`, `--template saas`. The CLI rejects any other `--template` value. Pick: diff --git a/packages/cli/templates/.cursorrules b/packages/cli/templates/.cursorrules index 124b73c4..07c536b9 100644 --- a/packages/cli/templates/.cursorrules +++ b/packages/cli/templates/.cursorrules @@ -21,9 +21,10 @@ cover what you need, the full hosted docs are at **https://docs.webjs.com**. - **Use a unique design (UI apps).** When the app has a UI, give it a design of your own (palette, layout, typography, chrome) that fits what the user asked for. Do NOT mimic the scaffold's example look (its warm - colors, the 760px reading column, the example header/nav). Keep the - design tokens and theme setup in `app/layout.ts`, those are - infrastructure, and restyle on top of them. + colors, the 760px reading column, the example header/nav). The `api` + template has no UI, so this does not apply there. Keep the design tokens + and theme setup in `app/layout.ts`, those are infrastructure, and + restyle on top of them. - **Only three templates exist:** `webjs create ` (default full-stack), `--template api`, `--template saas`. The CLI rejects any other `--template` value. Pick: diff --git a/packages/cli/templates/.github/copilot-instructions.md b/packages/cli/templates/.github/copilot-instructions.md index 2f0c9bc6..2b4c1bf4 100644 --- a/packages/cli/templates/.github/copilot-instructions.md +++ b/packages/cli/templates/.github/copilot-instructions.md @@ -21,9 +21,10 @@ the full hosted docs are at **https://docs.webjs.com**. - **Use a unique design (UI apps).** When the app has a UI, give it a design of your own (palette, layout, typography, chrome) that fits what the user asked for. Do NOT mimic the scaffold's example look (its warm - colors, the 760px reading column, the example header/nav). Keep the - design tokens and theme setup in `app/layout.ts`, those are - infrastructure, and restyle on top of them. + colors, the 760px reading column, the example header/nav). The `api` + template has no UI, so this does not apply there. Keep the design tokens + and theme setup in `app/layout.ts`, those are infrastructure, and + restyle on top of them. - **Only three templates exist:** `webjs create ` (default full-stack), `--template api`, `--template saas`. The CLI rejects any other `--template` value. Pick: