QwenVoice / website
CLAUDE.md388 starsChanged 21 days agoMITView on GitHub
This file adds website-specific guidance to the root ../CLAUDE.md. The website is a React/Vite marketing surface deployed by Vercel with website/ as the project root. It is a non-native zone: do not run Swift, iOS, macOS, Xcode, or native-app UI workflows for website-only changes. Inside website/, omit --prefix website. npm run check is the final deterministic verdict. The parent CI uses the Node/npm identities in ../config/toolchain.json. Client and transient SSR build outputs are generated; do not hand-edit them. - Read…
In this repository8 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- vocello-benchmarkSkill
- vocello-debugSkill
- vocello-device-diagnosticsSkill
- vocello-ios-validationSkill
- vocello-macos-uiSkill
- vocello-release-readinessSkill
- vocello-ui-autonomySkill
The file
We split this CLAUDE.md into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Read PRODUCT.md and DESIGN.md before visual or copy work.
- Very specific: line 26
Use current primary React/Vite/library documentation.
- Distinctive: line 33
Use browser automation only for the website.
- Distinctive: line 58
Keep content in the existing boundaries:
- Very specific: line 113
Every interactive control in the bar and the menu keeps a 44 px target (--tap).
- Very specific: line 128
Use grid-template-columns: minmax(0, 1fr) for narrow single-column grids.
- Distinctive: line 156
Use sentence case. All caps are reserved for tiny labels.
- Distinctive: line 159
No emoji, celebration copy, hype, unsupported superlatives, or first-person-plural voice.
- Distinctive: line 160
No gradient text, decorative glassmorphism, repetitive identical-card grids, repeated uppercase eyebrow scaffolding, or card side stripes …
- Very specific: line 193
Add assets under a category directory in public/assets/ and reference them through the data layer, not directly from unrelated JSX.
- Distinctive: line 208
Every image needs meaningful alt text or deliberate decorative handling.
- Distinctive: line 214
Do not hide product limitations or replace precise copy with vague marketing language.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md — Vocello website
This file adds website-specific guidance to the root ../CLAUDE.md. The website is a React/Vite
marketing surface deployed by Vercel with website/ as the project root. It is a non-native zone:
do not run Swift, iOS, macOS, Xcode, or native-app UI workflows for website-only changes.
Commands
npm --prefix website run dev # localhost:5173 (the desktop app's browser pane: preview_start website)
npm --prefix website run lint # site contract, ESLint (eslint.config.js), tsc --checkJs (jsconfig.json)
npm --prefix website test # Node contract fixtures + rendered contract
npm --prefix website run build # client + SSR + prerender -> website/dist/
npm --prefix website run check # lint + test + build + Playwright browser tests
# (needs Chromium and WebKit once: npx --prefix website playwright install --with-deps chromium webkit)
npm --prefix website run preview # serve production build (the browser pane: preview_start website-preview, port 4174)Inside website/, omit --prefix website. npm run check is the final deterministic verdict.
The parent CI uses the Node/npm identities in ../config/toolchain.json. Client and transient SSR
build outputs are generated; do not hand-edit them.
Tool routing
- Read
PRODUCT.mdandDESIGN.mdbefore visual or copy work. - Use current primary React/Vite/library documentation; Context7 may assist when callable.
- For visual, responsive, interactive and accessibility inspection, drive the local dev or preview
server in the Claude desktop app's browser pane (
../.claude/launch.json:website,website-preview) or with Claude in Chrome or the chrome-devtools MCP when they are connected; otherwise rely on Playwright output fromnpm run check. Browser evidence supplements rather than replacesnpm run check. Prefer a fresh tab; reuse an existing signed-in tab only when that state is explicitly needed. - Image generation is optional and only appropriate when the user requests new bitmap artwork.
- Use browser automation only for the website. Never use computer-use, Xcode, Simulator, or native UI automation to validate the site.
Architecture
The site has three React pages, listed in scripts/site-pages.mjs:
| Page | Entry | Content |
/ | index.html | the home page, for people who make voices |
/cli/ | cli/index.html | the full command line guide |
/engineering/ | engineering/index.html | engine, speed and every current limitation |
The support and privacy pages (/support/, /privacy/) are static HTML under public/, listed as
STATIC_PAGES in the same file; the layout matrix covers them too.
- Each entry names its page on
<div id="root" data-page="...">.src/App.jsxcomposes the skip link, bar, page (PAGESfromsrc/pages/), footer and analytics. vite.config.jsbuilds every entry.scripts/prerender.mjsrenders each page into its HTML. The site contract checks each page's head, and the rendered contract checks each page's landmarks.- Home sections the other pages link to are
/#id. Ids outlive redesigns, so old anchors still land: the privacy section keeps#how-it-runs(its comparison#why-not-cloud-tts), and the For developers tiles keep#cliand#engineering.
Keep content in the existing boundaries:
src/sections/: page sections. The home page (src/pages/HomePage.jsx) renders, in order:Hero,Modes(#workflows, the mode switcher),Listen,Privacy(#how-it-runs),Capabilities,IphoneBeta,WhatsNew(#whats-new, "What's new in 3.0"),Developers(the#cliand#engineeringtiles),Limitations(summary) andFinalCTA(#download).CommandLine.jsx:CommandLineGuide(/cli/);Engineering.jsx:EngineeringDetail(/engineering/), with the HTML speed chart;Limitations.jsx: asummaryon the home page and thefulllist on/engineering/.
src/components/Icon.jsx: shared SVG vocabulary and deterministic waveform-bar generator.src/components/Waveform.jsx: Listen-row waveform primitive.src/data/workflows.js: the three modes the switcher shows, with the app's short tab names.src/data/samples.js: samples, delivery labels and groups, and colors. The samples predate 3.0; never present them as 3.0 takes.src/data/whatsnew.js: the release's What's new entries, drawn from../docs/releases/.src/data/cli.js: the command line section's install, uninstall, and MCP setup commands, quoted from../docs/reference/cli.md.src/data/credits.js: technology, GitHub, release, and TestFlight URLs, plus the tagged Mac DMG, CLI package, CLI folder DMG, and release notes links derived from the stable tag.src/data/release.js: the stable and fallback Mac release mirror (see below).src/site.cssandsrc/tokens.css: global styling and design tokens. Do not add CSS modules or styled-component systems without an explicit redesign request.
App.jsx mounts cookieless Vercel Analytics and owns scroll reveal, including immediate reveal for
anchor jumps. The privacy page must continue to disclose website analytics.
Responsive layout
Four layout tiers, defined in DESIGN.md and at the top of src/site.css:
| Tier | Widths | Layout |
| Phone | below 600 px | one column; 56 px bar |
| Small tablet | 600 to 899 px, and landscape phones | one column; side-panel menu |
| Tablet | 900 to 1199 px | two-column sections; the hero stacks |
| Desktop | 1200 px and up | full layout; a 1320 px container from 1600 px |
- Media queries use exactly
max-width: 599.98px,899.98pxand1199.98px, ormin-width: 1200pxand1600px. A short landscape screen,(orientation: landscape) and (max-height: 500px), also tightens the bar and the display type, and caps screenshots at 80% of the height. - Sizes come from the layout tokens in
src/site.css:--fs-display(the home hero),--fs-hero,--fs-section,--fs-band,--fs-cta,--fs-quote,--section-y,--gutter,--nav-hand--tap. Display type and section rhythm scale withclamp(), so do not add a per-tier font size or section padding. The bar (
src/sections/Nav.jsx) is opaque. Each section link names the narrowest tier that shows it:Tier Bar contents Desktop all six links, plus Open source from 1320 px Tablet four section links (Voices, Listen, Privacy, iPhone), Download and the menu button Below 900 px brand, Download and the menu button The menu is a native modal
<dialog>(#site-menu) listing every section. It locks the page and hands focus back to the menu button when it closes. The former-name clarification shows only from 1200 px.- Every interactive control in the bar and the menu keeps a 44 px target (
--tap). Hover styles live only inside@media (hover: hover) and (pointer: fine), so a tap never leaves a control looking active. - The hero, the closing call to action and short section intros over a centered control or grid (the mode switcher, the privacy facts) are centered. Body text, lists and tables stay left-aligned at every width.
htmlsetsscroll-padding-top, so anchor jumps land below the bar. The body clips sideways overflow (overflow-x: clip), but the layout matrix measures every element regardless, so fix overflow where it starts.tests/layout-matrix.spec.mjschecks every page on every tier edge and three landscape sizes in Chromium, plus real iPhone and iPad descriptors in WebKit. It checks that no element extends past the viewport, the bar's items neither overlap nor escape, tap targets are 44 px, the menu behaves and anchor jumps land below the bar. Its widths, devices and pure checks live inscripts/browser-smoke-contract.mjs.
Use grid-template-columns: minmax(0, 1fr) for narrow single-column grids. A bare 1fr allows
intrinsic-width children such as max-content point lists to overflow.
Content accuracy
Existing copy is not evidence. Verify every product claim against the parent repository:
| Claim | Authority |
| Release, beta status, platform support, minimum hardware | ../config/public-product-facts.json and ../project.yml |
| Models, variants, speakers, languages, revisions | ../Sources/Resources/qwenvoice_contract.json and the complete production model catalog |
| Delivery presets and measured-best tiers | ../Sources/QwenVoiceCore/EmotionPreset.swift |
| Canonical performance hardware | ../benchmarks/hardware-profiles.json |
| Performance statements | compatible clean records under ../benchmarks/runs/ and generated ../benchmarks/HISTORY.md |
| Architecture, privacy, distribution | ../CLAUDE.md, ../docs/ARCHITECTURE.md, and machine-readable contracts |
| Release contents and known limitations | the tag's notes under ../docs/releases/ |
Command line, its install, and vocello mcp | ../docs/reference/cli.md, ../Sources/VocelloCLI, and ../scripts/cli_package.py |
Voice Cloning has no instruction channel. Its delivery banks select verified reference clips,
not engine emotion/intensity instructions. Keep public language aligned with
../config/public-product-facts.json; do not infer
availability from an old page or release note.
Brand and copy rules
PRODUCT.md owns brand voice and DESIGN.md owns visual constraints.
- Say local, not offline or on-device, unless the technical distinction matters.
- Use sentence case. All caps are reserved for tiny labels.
- Visible copy contains no em dash character. Use commas, colons, semicolons, periods, or parentheses. The website contract enforces this.
- No emoji, celebration copy, hype, unsupported superlatives, or first-person-plural voice.
- No gradient text, decorative glassmorphism, repetitive identical-card grids, repeated uppercase eyebrow scaffolding, or card side stripes wider than 1 px.
- Performance claims require compatible repository evidence and must keep their hardware/context qualification.
Design tokens and assets
- Built-in Voice/custom: gold (
--mode-custom). - Voice Design: lavender (
--mode-design). - Voice Cloning: terracotta (
--mode-clone). - Canvas: charcoal (
--charcoal-900). - Type: SF Pro Text for body, SF Pro Rounded for the wordmark, and New York/system serif for large editorial display moments.
Pass mode colors through existing CSS custom properties such as --row-mode and --mode-current;
do not hard-code duplicate hex values.
Asset ownership:
public/assets/screens/: product screenshots, includingios-studio.png.- Each PNG ships with an AVIF sibling:
sips -s format avif -s formatOptions 80 x.png --out x.avif. - A 2080 px Mac capture also ships
x-1040.avif:sips -Z 1040to a temporary PNG, then the AVIF command; commit only the AVIF. No 1560 px copy: sips encoded that width with a structure Linux WebKit could not decode. The layout matrix fails on any image that does not decode. - Screenshots render through
src/components/Screenshot.jsxwith their pixel size and a srcset of those widths; only the hero loads eagerly.
- Each PNG ships with an AVIF sibling:
public/assets/voice-samples/: WAV samples referenced bysrc/data/samples.js. When audio changes, regenerate waveform arrays withwebsite/scripts/render-waveforms.mjs.public/assets/favicon-32.png,apple-touch-icon.png(180 px),vocello-header-mark.png, andsocial_preview.png: brand art.src/data/release.jsmirrors the stable and fallback releases in../config/public-product-facts.json; download links name the stable tag.
Add assets under a category directory in public/assets/ and reference them through the data layer, not directly
from unrelated JSX.
Interaction and accessibility
- There is no client-side router. Internal navigation uses plain hash anchors and links between the three pages.
- Listen uses one shared
<audio>element withpreload="none"and source swapping for mutual exclusion. - Motion uses
panelSettle(the menu sheet and the mode switcher's panels) andrise(the hero's one-time entrance), with--ease-standard; inside a revealed section its facts and tiles follow in turn (--i). Animate only opacity, transform, border-color, and box-shadow, never layout properties. The hero animates in CSS, so it plays without JavaScript; the reduced-motion block removes every animation. - Preserve the single
prefers-reduced-motion: reduceblock. - Every image needs meaningful alt text or deliberate decorative handling.
- External
target="_blank"links requirerel="noreferrer"; internal targets must resolve. - Maintain semantic heading order, keyboard-operable controls, focus visibility, and sufficient
contrast across all breakpoints.
npm run lint(scripts/site-contract.mjs) holds every text token (--fg-primary,--fg-secondary,--fg-tertiary) at WCAG AA 4.5:1 or more on every surface token in both themes. - Do not hide product limitations or replace precise copy with vague marketing language.
Definition of done
- Cross-check changed claims against authoritative parent-repository sources.
- Run
npm --prefix website run check. - For visual or interaction changes, run the local server and inspect a phone (390 px), a phone on its side (844 x 390), a tablet (1024 px) and a desktop (1440 px) in the browser pane or with the Chrome browser tools when callable; the layout matrix covers every tier edge.
- Confirm reduced motion, keyboard navigation, anchors, audio mutual exclusion, and external-link safety when those surfaces changed.
- Refresh repository documentation/generated artifacts only when their registered inputs changed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

