Sitewright

---

What it does

You tell Claude which pieces you want and describe your brand. Sitewright writes a complete Next.js 15 project: pages, API routes, database schema, file storage, middleware and a README. Your colours, your words, your data. It then builds the project and drives it in Chromium at desktop and phone sizes, and tells you exactly what passed.

you     Use Sitewright to make a landing page, a dashboard and a connect page
        for my coffee roastery, Bean & Barrel.

claude  Which modules do you want?
        [x] Landing page    [ ] Publishing page    [x] Dashboard
        [x] Connect to phone    [x] Sign in    [ ] MFA accounts
        ...

The output is an ordinary project that you own. It has no runtime dependency on this skill.

What it makes

Everything below was generated from a short JSON config, built, and exercised in a browser. The brands, names, prices and photos are fictional demo data.

On a phone

Every page is checked at 390 px and 360 px wide: no sideways scrolling, tables that scroll inside their card, filters in one swipeable row, controls at least 44 px tall on touch screens.

Light and dark

Give it a primary and an accent colour. It derives the washes, the text colours (contrast-checked) and a lighter dark-mode variant. Dark follows the device, with a toggle in every header.

One kit, any brand

Design themes

Generated sites speak one of two design languages, set with design.theme in site.json. Colours, words and modules are yours either way.

	studio (the default)	classic
Surfaces	warm paper and ink neutrals that do not take your brand's hue, so your two colours are the only colour on the page	pale, cool surfaces tinted by the primary
Depth	hairline borders, nearly flat	soft brand-tinted shadows
Type	a display face for headlines (Bricolage Grotesque), Inter for text, JetBrains Mono	Montserrat throughout
Logo default	a letter mark	a hexagon

"design": { "theme": "studio" }          // or "classic"
"brand": { "font": { "display": "Fraunces" } }   // optional: any Google Font; leave out to take the theme's

The palette for both themes is derived from your two brand colours and every text colour is contrast-checked, in light and dark. The studio rules are one block of CSS (skill/sitewright/templates/design/studio.css).

Modules

Pick any combination. Dependencies are added for you (publishing brings mfa; dashboard and connect bring signin and the ingest API).

Module	What you get	Needs
landing	Public home page: animated mark, scroll story with phone mock-ups, proof numbers, features, FAQ, download card with QR code and team code, release list	none
signin	Shared-password gate in front of private pages: signed cookie, constant-time compare, safe ?next= redirect, edge middleware	none
mfa	Named accounts with password and authenticator-app codes (TOTP), first-run setup, single-use invites, lockout, activity log	none
publishing	Upload versions, rich release notes, stable/testing channels, testers with codes, update-check endpoint, public download. Real APK parsing, or any file types you list	mfa
dashboard	Stat cards, filters, search, record cards, detail page with files, line items and status actions	signin, api
connect	A page with the link (address + key) to paste into your app, a copy button and a curl example	signin, api
fxgallery	A public /effects page: every animated effect live on a sample hero, a colour picker, and the config to copy	none

Internally there are two more: base (design system, database, storage) and api (ingest, signed uploads, file serving, health), added automatically when needed.

Effects (optional)

Add motion without adding a library. Ask for one in plain words ("use aurora behind the hero") and Claude builds it into the site; or let Claude pick a fitting preset. scaffold.mjs --list-effects prints the whole menu, and the generated site gets only what was chosen. Change your mind later and it takes a second, without touching anything you edited: scaffold.mjs --apply-effects ./my-site --hero-bg stars. 10 animated hero backgrounds, 8 headline text animations, 4 button and 4 card micro-interactions, 5 scroll-reveal styles and 4 extras (cursor glow, scroll progress, click sparks, count-up numbers). Seven presets bundle sensible combinations: calm, aurora-glass, tech-grid, playful, cosmic, editorial, minimal.

Try every effect live: pick a combination, change the brand colours, and copy the exact config. The same page can be generated for your own site with the fxgallery module.

"effects": {
  "preset": "aurora-glass",
  "heroBackground": "aurora",
  "headline": "split-words",
  "buttons": "glow-border",
  "cards": "spotlight",
  "reveal": "blur",
  "extras": ["cursor-glow", "count-up"]
}

The backgrounds, headline animations and micro-interactions are original, dependency-free code (no GSAP or Three.js). It honours prefers-reduced-motion, skips pointer-follow effects on touch screens, pauses canvases that are off screen, and keeps the real headline text for screen readers. See reference/effects.md for the full catalogue.

Icons

Say icons: "auto" and the navigation, stat cards, status chips, features list and story steps get icons where a title clearly names one (an order is a box, a delivery a truck, a warning a triangle); or name them yourself. They are inline SVG from the open sets behind Iconify (200,000+ icons in 150+ sets; better-icons is the tool that finds them), in the colour of the text around them, and a site carries only the ones it uses: no icon font, no library, no request at run time.

In your own pages there is nothing to set up. Write the icon where you want it, and the project brings it in by itself (while npm run dev runs, and before every build):

<Icon name="rocket" />          // 120 of these on a page are found and added in a fraction of a second
<Icon name="tabler:home" />     // any other set
<Icon for="Shipped orders" />   // or describe it, and the fitting icon is chosen

Your own words are set once and apply everywhere ("icons": { "map": { "roast": "coffee" } }). A typo is reported with the file and a suggestion. For the places the generator fills (navigation, stat cards, chips...), icons: auto or:

node scaffold.mjs --config site.json --out ./my-site --icons auto
node scaffold.mjs --apply-icons ./my-site --icon stats.0=package       # change one later, in a second

Each set keeps its licence (written into the site's icons/NOTICE.md; a CC BY set also gets a ready-made credit line, and a licence that is not for products is refused). Every icon is rebuilt from an allow-list of drawing elements before it is written, so icon data from the network cannot add a script to your pages. Details, places and licences: reference/icons.md.

Figures: little drawings that answer the pointer

22 small isometric line figures, placed where they mean something. Say figures: "auto" and every place the site has gets its fitting figure, or choose them one by one:

Place	Where	auto puts
hero	beside the landing headline	exploded
releases	beside the "what's new" list	parcel
signin	the shared-password card	padlock
mfa	every account sign-in step	vault
connect	the "connect a phone" page	scanner
empty	an empty list, or a search that finds nothing	bars
notfound	the 404 page	dish

node scaffold.mjs --config site.json --out ./my-site --figures auto
node scaffold.mjs --apply-effects ./my-site --figures hero=bars        # change one place later, in a second

Put one anywhere in your own pages by name, nothing to register: <Figure name="padlock" /> is found and brought in by itself (while npm run dev runs, and before every build). They wear your brand colours and follow light and dark mode, answer touch as well as a mouse, hold still under reduced motion, and ship only the figures you chose. Nineteen are Hairline by Lucas Marques (MIT, its licence travels with the files); bars, scanner and parcel are new here, drawn on the same engine to Hairline's ten rules. Which figure fits where, and how to add your own: reference/figures.md.

The idea comes from animated-component libraries such as React Bits. Their licence (MIT with the Commons Clause) does not allow redistributing the components inside another package, so these effects are written from scratch for this kit.

Components (optional)

A library of 368 small interactive components you import by name from @/components/fx/ui. They are original code (except the ten glass-* pieces, ported from Tactile Glass UI, MIT, and the nine BoardUI-style pieces and one template adapted from the BoardUI free tier, MIT; see THIRD_PARTY_NOTICES.md) with no animation or chart library, respect prefers-reduced-motion, and work with touch and keyboard. Choose them in site.json ("effects": { "components": "all" } or a list) or with --components, and change the set later in place with --apply-effects.

Group	Components
Buttons	tactile, glossy, hold-to-confirm, dynamic, tear-off, bell, pull cord, look-at-you pay, folding subscribe, hungry delete, rolling publish, radial share, liquid upload, neon send, neumorphic play, rippling download
Inputs	one-time-code field, command input, wheel picker, detent dial, option selector, invite code, drop zone, spring toggle, upload progress, flipping search bar, ring-to-rope upload, magic tree QR (paste a link: a scannable code that tap-flips into a 3D tree, with seasons and your own colours)
Cards and layout	payment card, chat thread, glass carousel, perforated ticket, stamp, playing cards, scroll-fade list, shared-element gallery, gesture card, draggable card
Motion	stagger grid, line draw, shape morph, motion path, scroll timeline, timeline sequence, spring playground, presence list, drag to reorder
Navigation	nav tabs, glow sidebar, liquid-glass nav (stretching pill), underline nav
Hover interactions	rotating, magnetic and rolling-text buttons, expanding fill, arrow relay, spotlight border, waving hand, image list preview, image stack, blinds, image accordion, cursor reveal, peel, caption reveal, layer explorer, jelly text, holographic and parallax cards, orbiting accents, hover marquee, text shadow, squishy labels, repelling dots
Frosted glass	frosted button, card, prompt input, switch, tabs, audio player, panel and backdrop: the glass pieces as pure CSS (backdrop blur, grain, lit edge, pointer-following sheen), no WebGL
3D and shaders	shader gradient and waves, particle sphere, wire terrain, plasma orb, tilt card, cube carousel, globe with arcs, 3D phone, lit torus (raw WebGL and CSS 3D, no three.js; static fallback when WebGL is missing)
Feedback	toast (call toast('Saved') from anywhere; mount <Toaster /> once)
Loaders and text	seasons tree, step loader, logo-trace loader, animated signature, scramble text, plucked text, receipt printer
Charts (SVG, accessible)	area, bar, line, live line, profit/loss, composed, scatter, candlestick, pie, ring, radar, funnel, gauge, heatmap, sankey, US tile map

Templates (optional)

Dashboards and pages are not components, so they have their own catalogue: 18 full-screen templates chosen with effects.templates ("all" or a list) or --templates, listed in reference/templates.md. Eight dashboards (analytics, finance, sales pipeline, projects, support inbox, operations, AI assistant, and a BoardUI-style shop overview adapted from the BoardUI free tier, MIT) share one app-style kit or its container-query approach: container-query responsive layout, tabular numerals, working tables, boards and charts with keyboard support. Pages: art marketplace, restaurant landing, wind 404, lamp login, a brand bento board and five original hero landing pages. Browse them at /dashboards/.

Try the components live · the catalogue, with what each is for, is reference/components.md. Their ideas come from Kitchen, Kokonut UI, Anime.js, Motion, Bklit, Sileo and @code.xr, and nine (stat cards, revenue and orders chart cards, segmented control, notification center, data table, dashboard sidebar, auth card, badges and chips) are adapted from the BoardUI free tier (MIT); all code is written for this kit (see THIRD_PARTY_NOTICES.md).

Audits

The verifier answers "does it work". scripts/audit.mjs answers "is it good": it opens a running site in a real browser, in light and dark, at phone, tablet and desktop width, and reports what a careful reviewer would, each finding with the exact fix.

node skill/sitewright/scripts/audit.mjs --url http://localhost:3000 --out ./audit-out

• Accessibility (WCAG 2.2 AA): every text run's contrast is measured against its real background and the nearest passing colour is suggested (Text #a3a9b8 on #006fe6 is 2.02:1 ... set it to #f9fafb (4.55:1)); names, alt text, headings, language, viewport, tap targets and keyboard focus.
• Design critique, ranked blocking / important / polish: text and body size, hierarchy, line length and leading, spacing rhythm, inconsistent buttons.
• Responsive: sideways scroll with the element to blame, clipped text, columns that never stack, input zoom on iPhones, plus a picture of each page at phone width next to desktop.

You get report.md, report.json, fixes.css (suggestions, never applied) and the pictures; the exit code is 1 when anything blocking is found. tools/regress.mjs runs it on every site it builds, and tools/audit-test.mjs tests it against a page that is wrong in known ways. It is not a screen-reader test and cannot score text over a photo. See reference/audits.md, and reference/better-interface.md for the checklist behind it.

Install

You need Claude Code and Node.js 20 or newer. A skill is a folder that Claude Code reads when a session starts, so installing means copying one folder.

macOS / Linux

git clone https://github.com/raj742133/sitewright
cd sitewright
./install.sh        # or: bash install.sh   (if you downloaded a zip, which does not keep the executable bit)

Windows (PowerShell)

git clone https://github.com/raj742133/sitewright
cd sitewright
.\install.ps1

If PowerShell blocks the script: powershell -ExecutionPolicy Bypass -File .\install.ps1

Only for one project

Installs into .claude/skills/ of the current folder, so you can commit it and share it with your team.

cd your-project
/path/to/sitewright/install.sh --project          # macOS / Linux
C:\path\to\sitewright\install.ps1 -Project         # Windows

Manual

mkdir -p ~/.claude/skills
cp -R sitewright/skill/sitewright ~/.claude/skills/

On Windows the target is %USERPROFILE%\.claude\skills\sitewright.

Browser tests (once)

The verification step uses Playwright. Install it wherever you will run the verifier:

npm i playwright
npx playwright install chromium

Check that it worked

• ~/.claude/skills/sitewright/SKILL.md exists.
• Start a new Claude Code session and type /sitewright. The skill should appear in the list.

Use it

Ask in plain words:

Use Sitewright to make a landing page and a dashboard for my business.

I need a publishing page where my team uploads releases, with MFA sign-in.

Give the landing page an aurora background and a split-words headline.

/sitewright

Claude will ask which modules you want, then your brand name, two colours, logo style and what you call things (orders, cases, scans), and whether you want an animated style (a preset, piece by piece, or a look at the live gallery first). It writes a site.json, runs the generator, installs, builds, and runs the verifier. It reports what passed and what it could not check.

Without Claude

The generator is plain Node. Even a brand name is enough:

echo '{"brand":{"name":"Acme Co"}}' > site.json
node ~/.claude/skills/sitewright/scripts/scaffold.mjs --config site.json --out ./my-site
cd my-site && npm install && npm run build && npm start

The generator prints the development password and ingest key it created (they are also in .env.local).

Then verify it:

node ~/.claude/skills/sitewright/scripts/verify.mjs --site ./my-site --port 4010 --out ./verify-shots

Examples

Seven complete configs ship in skill/sitewright/examples:

Config	Brand	Modules	Shows
coffee.json	Bean & Barrel	all six	PDF/ZIP publishing, testers, every landing section
fitness.json	PulseFit	all six	Android APK publishing with real manifest parsing
legal.json	Halden Legal	landing, sign-in, dashboard, connect	monogram logo, navy and gold, "matters" vocabulary
studio.json	Pixel Studio	landing, MFA	square logo, purple and cyan
minimal.json	Acme Co	defaults	a brand name and nothing else
coffee-effects.json	Bean & Barrel	all six	coffee.json plus an effects block (aurora-glass preset, beams on the sign-in page, line figures in six places)
gallery.json	Effect Lab	fxgallery	just the live effects gallery

The full list of config keys is in reference/config.md.

What you get under the hood

• Layered sign-in. A shared-password cookie, named MFA accounts, a bearer ingest token and per-tester codes. They are four separate layers and are never merged.
• Direct-to-storage uploads. Clients get short-lived signed URLs and PUT files straight to storage. Local disk, S3 / R2 or Azure Blob.
• Idempotent ingest. Re-sending a record id updates it instead of duplicating it, so a phone that retries after losing signal does no harm.
• Postgres with zero setup. Embedded Postgres (PGlite) out of the box; set DATABASE_URL for production.
• Secure defaults. Scrypt password hashes, HMAC-signed cookies, constant-time compares, authenticator codes that cannot be reused, lockout after five failures, user text sanitised before it reaches source files.
• Your vocabulary. Call a record an order, a matter or a loaf, and every label, heading and empty state follows.
• No invented facts. Sections that need real numbers (proof, features, compatibility) stay off until you supply them.

How it is tested

Each example was scaffolded from its config, type-checked, built for production and driven with Playwright in Chromium at 1280, 390 and 360 px. Checks include sign-in and open-redirect refusal, full MFA enrolment with an independent TOTP implementation, replay refusal, single-use invites, publishing with build-number ordering and byte-identical downloads, ingest auth and idempotency, filters, no horizontal scroll, finger-sized controls, repeated warm-cache loads of every page type for hydration errors, and console errors. For the effects it also checks that headline text stays readable to assistive technology, that canvas backgrounds stop drawing when scrolled off screen, that reduced-motion shows the final state, and that touch screens skip hover effects.

Site	What it exercises	Result
Bean & Barrel	all six modules, PDF/ZIP publishing, testers	88/88
PulseFit	all six modules; its 12 real-APK checks need the APK files and are skipped without them	65/65
Halden Legal	landing, sign-in, dashboard, connect; monogram logo, navy and gold	61/61
Pixel Studio	landing and MFA only	35/35
Sunny Side Bakery	near-white brand colours (contrast adjustment)	76/76
Midnight Courier	near-black brand colours, other fonts, PDF/CSV publishing	76/76
Quotes, tags, braces	a brand name full of ", <b>, {x}, backticks and a backslash	76/76
Orbit Labs	a single module: landing only	13/13
Field Notes Press	a single module: publishing only (brings MFA and the API)	25/25
Acme Co	just a brand name, everything else defaulted	76/76
Bean & Barrel + effects	aurora-glass preset, beams behind the sign-in card, cursor glow, scroll progress, count-up	113/113
Play House	particles, split letters, ripple buttons, tilt cards, click sparks, stars on sign-in	70/70
Ripple Works	waves, rotating headline word, magnetic buttons, glow-border cards, slide reveal	60/60
Grid Labs	tech-grid preset: perspective grid, decode headline, spotlight cards	65/65
Harbour Books	the classic design theme	55/55
Four single-module sites	sign-in only, MFA only, dashboard only, connect only	16/16, 15/15, 39/39, 27/27
Effect Lab	the live effects gallery: every background, headline, button, card, reveal, extra and embed page	12/12

26 site builds (13 example runs, plain and with every layer on, plus 13 stress and single-module fixtures), 1,607 checks, all passing, each audited for accessibility and responsive problems (none blocking) and followed by a smoke test of npm run dev. The table lists the plain run of each site; node tools/regress.mjs prints every run. The real-Android-APK checks need the APK files and are skipped, and reported as skipped, when they are absent.

Details of every check are in reference/testing.md.

Not covered

• npm run dev is only smoke-tested (the first page must render without a server error); the browser checks run against the production build.
• Real phones, Safari, Firefox and tablets. Only Chromium at three widths.
• S3 and Azure storage against a real bucket, and a real Postgres server.
• Brand names longer than about 24 characters in the phone header.
• The authentication code follows common practice but has not had an independent security audit. Review it before putting anything sensitive behind it.

Repository layout

skill/sitewright/      the skill: SKILL.md, scripts, templates, examples, reference docs
  scripts/             scaffold.mjs (generator), verify.mjs (browser verifier), effects.mjs, ui.mjs + ui/ (component registry), modules.mjs, defaults.mjs
  templates/           base + one folder per module, mirroring the generated project
  templates/fx/        the effects: backgrounds, headline animations, micro-interactions, figures, css; fx/ui is the component library
  templates/design/    the studio theme's stylesheet (classic is the base stylesheet)
  examples/            seven complete configs
  reference/           config keys, modules, design system, effects, testing, gotchas
site/                  the website (static HTML/CSS/JS) plus demo/, the exported live effects gallery; deployed on Vercel
launch/                the launch video (mp4, poster, plan) and the Hyperframes project that renders it
tools/                 regress.mjs (builds and drives every example, plain and with every layer on, in one table), site-test.mjs (the website), and how the screenshots, banner and social image were made
install.sh, install.ps1

After any change to the generator, the templates or the verifier, run node tools/regress.mjs: it scaffolds, type-checks, builds and drives every example (plain, and with figures, icons and effects switched on) and prints one table.

To regenerate the screenshots: build the example sites, then run tools/showcase.mjs for each (see the header of that file).

Contributing

Issues and pull requests are welcome. A new module is a folder under skill/sitewright/templates/modules/<id>/ that mirrors the output tree, plus an entry in scripts/modules.mjs. Please run the verifier on at least one generated site before opening a pull request, and say which sites you ran.

Licence

MIT