Skip to content

feat(site): a setup prompt for coding assistants - #100

Merged
b4rb13 merged 2 commits into
mainfrom
site/setup-prompt
Nov 20, 2026
Merged

b4rb13 merged 2 commits into
mainfrom
site/setup-prompt

Conversation

@b4rb13

@b4rb13 b4rb13 commented Nov 20, 2026

Copy link
Copy Markdown
Owner

Summary

A prompt users paste into Claude Code, Codex, Cursor or Copilot to add Dotquilt to their project. It analyses first, asks, then implements in order.

Phase 1  Learn Dotquilt      read llms-full.txt raw (curl if the web tool summarises)
Phase 2  Analyse, then ask   stack · rendering · data layer · every place that waits for content
                             · theme / dark mode · CSP · tests · gaps
                             → findings table, plan, only the questions the code can't answer
                             → STOP until answered
Phase 3  Implement in order  install → global setup (theme, color-scheme, CSP) → most-seen place
                             end to end → the rest one at a time (state mapping, placeholder by
                             shape and size, tables, TextLoader, refresh rows, Next.js, Suspense,
                             other frameworks via native elements)
Phase 4  Verify, report      types, lint, tests, build; each place in the browser, light, dark,
                             reduced motion, server HTML; what changed and how to undo
Rules                        presentation only; leave action spinners alone; one place at a time
+apps/site/src/prompts/setup.md          the one source
+apps/site/src/pages/setup-prompt.md.ts  → /setup-prompt.md (raw, for "read this URL and follow it")
+apps/site/src/content/docs/docs/ai-setup.mdx  → /docs/ai-setup/ (Getting started), with the prompt in full
+apps/site/src/components/site/CopyPrompt.astro  one-click copy (prompt embedded, works in every browser)
 home GetStarted                         "Or let your coding assistant do it" + Copy setup prompt
 llms.txt                                links the prompt; "pre-alpha, not on npm" → install line
 lib/markdown.ts                         page Markdown drops page-only <style> blocks and <div> wrappers
 theming.mdx                             color-scheme for media-query dark modes

Evidence

Tested on a mock Next.js 16 dashboard. An agent played the user's assistant and got only the prompt. The mock app had seven loading places: a spinner KPI block, a pulse-skeleton chart, a React Query table with paging, a refresh feed, a typing bubble, a profile card and a route loading.tsx. It also had two button spinners that should be left alone.

  • Round 1 (analysis):
    • It found all seven places and left both button spinners alone.
    • It measured today's layout jumps (+38 px and +110 px), proposed a placeholder for each place, and asked six focused questions with defaults.
    • Gaps it exposed in the prompt, now fixed: table headers, dark mode without color-scheme, docs summarised by a web tool, and loading states that never end on failure.
  • Round 2 (implementation): type check and production build pass. The first HTML holds every placeholder, there are no hydration warnings, and on desktop nothing moves from the first frame to ready.
    • Prompt fixes from this round: aria-labeled header cells instead of a visually hidden <thead> (which drew a stray row of marks), room for the refresh row, matching line heights, and number columns.

Site: 73 site tests pass. New ones check that /setup-prompt.md is served, that llms.txt links it with no "not on npm", and that the copy button on /docs/ai-setup/ and / puts the exact prompt on the clipboard. The new page also passes the contrast, form-control-name and 320 px checks.

Library findings from the test (follow-ups, not in this PR):

  1. A pending TextLoader makes its line box taller.
  2. A region keeps its placeholder's height after ready, which leaves blank space around error messages.
  3. The handoff measures visually hidden text.
  4. --dotquilt-refresh-gap is missing from the React style type.
  5. SkeletonText's line gap doesn't follow the text's line height.

Merge Danger

Door: two-way

Blast Radius: docs site

One new page, one block on the home page, and the llms.txt text. Merging deploys dotquilt.dev.

🤖 Generated with Claude Code

b4rb13 and others added 2 commits November 21, 2026 00:11
One prompt that users paste into Claude Code, Codex, Cursor or Copilot to
add Dotquilt to their project. It works in four phases:
1. Learn Dotquilt from llms-full.txt (raw, not summarised).
2. Analyse the project: stack, rendering, data loading, every place that
   waits for content, theme and dark mode, CSP, tests and gaps. Report a
   table of places with proposed placeholders, a plan, and only the
   questions the code can't answer, then stop for the answers.
3. Implement in order: install, one-time setup (theme, dark mode, CSP),
   the most-seen place end to end, then one place at a time, mapping the
   app's existing state to pending, refreshing or ready without touching
   data code. It covers tables, TextLoader, refresh rows, Next.js, Suspense
   and native elements for other frameworks.
4. Verify (types, lint, tests, build, each place in the browser, light,
   dark, reduced motion, server HTML) and report how to undo.

It was tested by an agent on a mock Next.js dashboard with seven loading
places; two rounds of findings are folded in.

On the site: src/prompts/setup.md is the one source for /setup-prompt.md,
the docs page /docs/ai-setup/ (in Getting started) and a "Copy setup
prompt" button on the home page. llms.txt links it and no longer says
"pre-alpha, not on npm". Page Markdown drops page-only <style> blocks and
<div> wrappers. Theming explains color-scheme for media-query dark modes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Also records the setup prompt in AUDIT.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 20, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
dotquilt Ready Ready Preview Nov 20, 2026 8:12pm UTC

Request Review

@b4rb13
b4rb13 merged commit b0b924d into main Nov 20, 2026
7 checks passed
@b4rb13
b4rb13 deleted the site/setup-prompt branch November 20, 2026 20:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant