@mthanh/vespercli 2.2.1 → 2.3.0

package/assets/copilot/packs/frontend/skills/design-taste-frontend/references/research.md

@@ -0,0 +1,356 @@
+# The study
+
+Everything numeric in this skill comes from here. Cite these figures; do not round them up or invent
+others.
+
+## Contents
+
+1. Method and its limits
+2. Scores
+3. Where the idea comes from
+4. Headlines
+5. Type
+6. Devices: what separates strong from weak, and what does not
+7. Colour and shape
+8. Imagery and page structure
+9. What the inspector says about the gallery itself
+10. The 25 highest-scored sites and their ideas
+11. How the skill was tested
+12. The October 2026 study: 100 Sites of the Day
+13. The app-screen study
+
+## 1. Method and its limits
+
+- **Sample.** 248 sites collected on 5 October 2026: 156 from One Page Love (the latest gallery pages
+  and the category listings) and 92 Awwwards Sites of the Day (the three most recent listing pages).
+  247 loaded; 246 were re-measured with the final probe.
+- **Capture.** Headless Chrome at 1440×900 and 390×844. For each site: the first viewport, five more
+  frames while scrolling with real wheel input, the mobile first viewport, and a measurement pass in
+  the page (computed styles, text geometry, colours, fonts actually loaded).
+- **Panel.** 21 model reviewers each studied about 12 sites from the screenshots and the measurements,
+  described them (idea, hero, type, colour, imagery, layout, sections) and scored them the Awwwards
+  way: design 40%, usability 30%, creativity 20%, content 10%. These are model judgements from still
+  frames, not human jurors and not the real Awwwards scores. Batches mixed both sources so each
+  reviewer saw a spread.
+- **Usable sets.** 235 sites were usable for the panel (12 showed only a preloader, an entry gate or a
+  bot wall). 202 were measurable for typography (a page with at least 25 words and a detectable
+  headline). "Top" below means panel score 7.5 or higher (82 measurable sites); "weak" means under 6.5
+  (23 measurable sites).
+- **Limits.** One capture per site on one day. Some heroes were caught mid-animation or behind a cookie
+  notice. WebGL-heavy sites are under-described by text measurements. The eyebrow detector counts any
+  small short label directly above a large heading, so it over-counts against the panel's stricter
+  reading (60% measured against 35% observed). Motion was inferred from frames, not watched. The sample
+  is whatever the two galleries had recently featured; it is fashion as much as quality.
+
+## 2. Scores
+
+| | All 235 | One Page Love (151) | Awwwards (84) |
+| --- | --- | --- | --- |
+| Median overall | 7.2 | 7.1 | 7.5 |
+| Middle half | 6.8–7.6 | | |
+| 8.0 or higher | 25 sites (11%) | | |
+| 7.5 or higher | 90 sites (38%) | | |
+| Under 6.5 | 29 sites | | |
+
+Median by criterion: design 8, usability 7, creativity 7, content 7. Among the top 25: design 9,
+usability 7, creativity 8, content 8. Usability is the one line that does not rise with the rest: the
+best sites are no easier to use than the average one. Do not copy their gates, preloaders, tiny text
+or hidden navigation.
+
+## 3. Where the idea comes from
+
+The clearest pattern in the panel's notes: high scores go with a concept taken from the subject, and
+low scores go with its absence. The weakest entries' ideas were recorded in words like "none beyond the
+standard dark SaaS launch formula", "no visual idea beyond clarity", "no strong idea". The strongest
+were sentences only that subject could own (section 10).
+
+Recurring engines among the 7.3+ sites, each the basis of a direction in the library:
+
+- **The product demonstrates itself.** A colour picker's loupe reads the page's own background; a list
+  tool is sold with tiny working lists; a photo app's page is a wall of its own output.
+- **The page is an artefact from the subject's world.** A wedding site that is the invitation; an
+  archive as tabbed folders; a coupon with a cut line; a portfolio as a contact sheet.
+- **The name is the hero.** Wordmarks as wide as the screen, a photograph set inside the name like a
+  letter, a name split to opposite corners with the page between.
+- **One motif from the subject drives everything.** A tool's octagonal section as button, mask and
+  loader; two circles for two accounts; a café's stripes.
+- **Dressed as another category.** A money app as a streetwear drop; an industrial roaster as a design
+  object; a parcel service as a fairground.
+- **The place carries it.** One full-bleed view and a name along the bottom edge.
+- **A fixed stage.** A title or object stays put while content swaps beneath it.
+- **One section, one colour.** Flat fields as chapters.
+- **Radical understatement.** A 27px headline and tiny live demonstrations, carried through completely.
+
+Hero types, by the panel's classification (top sites against weak sites): full-bleed media with type
+over it 16% / 10%; giant wordmark 14% / 0%; typographic poster 13% / 7%; text beside media 10% / 3%;
+**centred statement with media below 7% / 24%**. The centred headline over a screenshot is the weak
+sites' signature layout.
+
+## 4. Headlines
+
+| Hero headline | All | Top | Weak |
+| --- | --- | --- | --- |
+| Words, median | 5 | 5 | 5 |
+| Words, middle half | 3–9 | 2–8 | 3–8 |
+| Characters, median | 32 | | |
+| One line at 1440 | 47% | | |
+| Two lines or fewer at 1440 | 70% | 71% | 83% |
+| Two lines or fewer at 390 | 57% | | |
+| Three lines or fewer at 390 | 82% | | |
+
+Awwwards heroes are shorter (median 4 words, 76% within two lines) than One Page Love's (6 words, 66%).
+Section headings have a median of 3 words. Length does not separate strong from weak; nearly everyone
+in the gallery writes short headlines. The two-line limit in this skill is a house rule that most of
+the gallery already meets on desktop and that takes care to meet on a phone.
+
+## 5. Type
+
+| | All | Top | Weak |
+| --- | --- | --- | --- |
+| Hero size, median | 72px (5.0vw) | 6.0vw | 4.7vw |
+| Hero size, middle half | 3.0–7.6vw | 2.5–9.7vw | 2.7–6.1vw |
+| Largest text on the page, median | 6.4vw | 8.4vw | 5.0vw |
+| Largest text, upper quarter starts at | 10.4vw | 12.5vw | 6.7vw |
+| Hero on a phone, median | 40px | | |
+| Hero tracking, median (middle half) | -0.01em (-0.03 to 0) | | |
+| Hero leading, median (middle half) | 1.0 (0.95–1.1) | | |
+| Body size, median (middle half) | 16px (14–18) | | |
+| Headline ÷ body, median | 4.3 | 4.7 | 4.0 |
+| Typefaces carrying 3%+ of text | one 31%, two 45%, three 22% | | |
+| Distinct font sizes, median | 8 | | |
+
+Hero weight: regular 48%, medium 18%, semibold 6%, bold or heavier 22%, light 6%. Capitals 24%.
+Centred 39% overall, 52% on weak sites. Display classes by the panel: neo-grotesk 48%, transitional
+serif 11%, geometric sans 10%, condensed 6%, extended 6%, old-style serif 4%, custom lettering 4%.
+
+Strong sites push the extremes: their biggest type is bigger and their range is wider. Weak sites
+cluster in the middle.
+
+## 6. Devices: what separates strong from weak, and what does not
+
+Measured in the page unless marked (panel).
+
+**More common on weak sites (the data supports avoiding them):**
+
+| Device | Top | Weak |
+| --- | --- | --- |
+| Icon-topped feature cards (panel) | 1% | 28% |
+| Rows of identical cards with a small icon (measured) | 7% | 26% |
+| Pill badges (panel) | 14% | 34% |
+| Pill-shaped label above a heading (measured) | 5% | 26% |
+| Tiny uppercase letter-spaced labels, any | 16% | 57% |
+| Tiny uppercase letter-spaced labels, three or more | 6% | 43% |
+| Gradient fills (not counting scrims) | 22% | 52% |
+| Gradient text | 2% | 13% |
+| Shadows on resting elements, any | 24% | 48% |
+| Shadows, five or more | 10% | 30% |
+| Emoji in the page | 10% | 26% |
+| Eyebrow labels (panel) | 32% | 45% |
+
+**No real difference:**
+
+| Device | Top | Weak |
+| --- | --- | --- |
+| Backdrop blur anywhere | 32% | 39% |
+| Italic-serif accent word (panel) | 4% | 7% |
+| Thin rules, any | 61% | 52% |
+
+**More common on strong sites (banned here anyway, as house style):**
+
+| Device | Top | Weak |
+| --- | --- | --- |
+| Monospace labels (panel) | 44% | 24% |
+| Monospace anywhere outside code (measured) | 45% | 26% |
+| Index numbering (panel) | 38% | 21% |
+
+Monospace captions, index numbers and ruled grids are the present fashion of award sites. They are
+excluded from this skill by the owner's choice, not by the data: they are the devices generators copy
+first, and a page that cannot lean on them has to find structure in space, tone and scale.
+
+## 7. Colour and shape
+
+- Dark page ground 41%; pure white 25%; pure black 12%; a warm off-white 13%.
+- Scheme (panel): monochrome plus one accent 23%, light neutral 22%, dark neutral 14%, several flat
+  colours 13%, two-tone 12%, photographic 9%, one colour field 6%.
+- Primary buttons are neutral (black, white, grey) on 52% of sites. One site in 246 has a terracotta
+  button; none has a violet one.
+- Median number of distinct section grounds: 2 on top sites, 1 on weak sites.
+- Button shape: top sites square (0–2px) 52%, fully round 23%, small radius 19%, medium (9–16px) 6%.
+  Weak sites fully round 59%, medium 24%, square 18%.
+- Media corners are square on 73% of sites; where rounded, the median radius is 12px.
+- Buttons in the first viewport: none on 55% of top sites and 39% of weak ones.
+
+## 8. Imagery and page structure
+
+- Hero media covers at least half the first viewport on 60% of sites (top 68%, weak 48%) and nearly
+  all of it on 50% (top 56%, weak 39%). No hero media: 15%.
+- Video is present on 49% of sites and a canvas element on 49% (top 62%, weak 35%).
+- Images per page, median: 24 overall, 37 on top sites, 5 on weak ones.
+- Imagery kind (panel): mixed 32%, photography 14%, generative or WebGL 13%, product interface 12%,
+  3D render 11%, illustration 9%, video 6%, type only 3%. Median panel score is lowest for
+  illustration-led (6.9) and product-interface-led (7.1) pages and highest for video and type-only
+  (7.5).
+- Page length, median: 8.7 screens and 575 words (middle half 1.6–14.4 screens, 250–956 words). A
+  quarter of the sites are a single screen or two.
+- Navigation: a median of 3 links; fixed or sticky on 66%.
+- Density (panel): airy 46%, balanced 45%, dense 9%. Alignment: centred 33%, mixed 31%, left-anchored
+  17%, modular grid 13%, free 6%.
+- Asked to describe each site's most interesting sections, the panel picked a pricing, testimonial or
+  FAQ section only 7, 12 and 9 times across 235 sites. Where strong sites have them at all, they are
+  not where the design effort goes, and they avoid the stock form.
+
+**From the panel's written notes on the 114 sites scoring 7.3 or more** (hand tallies, approximate;
+`layout.md` turns these into practice):
+
+- Outer margins of 32px or less on about 45; 80px or more on about 8. A centred 700–1300px container
+  on about 15, several of them the pages the panel called stock.
+- Text anchored to a fixed off-centre line on about 22. Text docked in corners or at opposite ends of
+  a baseline on about 25 and 15.
+- Two or three type sizes with nothing between on about 30; no note describes a graded five-step
+  scale.
+- One thing per screen on about 20. A full background colour per section on about 20; alternating
+  light and dark on about 12.
+- Every section recomposed on about 14; one planned exception to the page's own system on about 14.
+- No conventional top navigation bar on about 45; small corner links on about 22; a single link or
+  button on about 10.
+- Endings: the name at full width about 18, the hero repeated inverted about 12, a closing scene of
+  its own about 14, no footer or a single line about 22. Link-column footers are mentioned only as
+  criticism.
+- Motion (inferred from frames): autoplaying video about 50; pinned or fixed stages about 40; text
+  reveals about 30 (blur-in 10, masked line rises 8, scroll-tied word colouring 7); horizontal strips
+  about 27; marquees about 26; media swapped behind a fixed element about 15; scroll-linked scaling
+  about 12. Rare: hover effects (4 mentions), parallax (6), accordions (5), bounce or spring motion
+  (none). About 10 strong sites show little or no motion at all.
+- How weak sites fail (54 sites under 6.8): the category's stock template about 20; centred headline,
+  pill badge, two buttons and a screenshot about 9; stock modules after a distinctive hero about 8,
+  plus about 17 in the middle band; a characterless default typeface about 13; text too small or too
+  faint about 13; never saying what the thing is about 12.
+- Faults of the best sites (90 at 7.5 or more), not to be copied: text at 9–13px about 24;
+  information hidden behind the concept about 20; the idea running out mid-page about 15; text over
+  footage with no scrim about 12; gates, preloaders and blank first paints about 12.
+
+## 9. What the inspector says about the gallery itself
+
+Running this skill's own `inspect.mjs` rules over the 202 measurable gallery sites: the median site
+has 4 `FAIL`s and only 4% have none. The rules that fire most: headline over two lines somewhere on
+the page 60%, eyebrow-like label 60%, thin rules 50%, monospace 37%, shadows 32%, gradients 29%, index
+numbering 29%.
+
+So the house style is deliberately stricter than the gallery. It is not a description of award sites;
+it is a narrower target inside what they do: their scale, their ideas, their imagery and restraint,
+without the ornaments that have since become a uniform.
+
+## 10. The 25 highest-scored sites and their ideas
+
+The panel's one-sentence reading of each. Notice that every one names something only that subject
+could own. (Several use devices this skill bans; take the idea, not the ornament.)
+
+| Site | Source | Score | Idea |
+| --- | --- | --- | --- |
+| PP Neue Montreal | Awwwards | 8.6 | A typeface specimen dressed as a vintage city travel guide: the font named after Montreal is sold through guidebook titling, postcards and old tourist footage. |
+| Seasats | Awwwards | 8.4 | Calm, dusk-lit seascapes sell autonomous boats as serene instruments, and the navigation is a column of stacked colour swatches taken from that sea-and-sand palette. |
+| AI in Design Report 2026 | Awwwards | 8.4 | A research report laid out like a colour-blocked print annual: a video collage on top, an oversized tight grotesk title, and flat orange, lilac, sage and black blocks carrying stats, quotes and chapters. |
+| House of Honey | Awwwards | 8.4 | A block-heavy wordmark pierced by a fine script: the bold-against-delicate contrast is repeated at every scale, with giant pink script behind quiet serif statements. |
+| White Desert | Awwwards | 8.4 | One word, the destination, set a third of the screen tall over footage like a film title card; sheer scale stands in for remoteness. |
+| Applied Imagination | One Page Love | 8.3 | An essay conceived on a flight is read as a descent: an altimeter ticks from 30,000 ft to zero while you scroll down through clouds to mountains at ground level. |
+| Cursor Compile | One Page Love | 8.3 | The event name drawn as seven looping one-line curves in seven colours, more signature than logotype, on an otherwise whisper-quiet off-white page. |
+| The New Industrials | One Page Love | 8.3 | A long-read essay laid out inside a drafting grid, where colour fields shift as you read and machine parts drift through the margins and finally assemble into the publisher's initials. |
+| Wild | One Page Love | 8.3 | A studio essay in which everything decorative is drawn on one square-pixel grid: the hero heatmap, the icons, the diagrams, the lettering and the footer. |
+| Hildén & Kaira | Awwwards | 8.3 | The agency name is cast in liquid chrome across the full width, and the same chrome becomes the objects that float through the page, tying the pitch to one material. |
+| PX Push | Awwwards | 8.2 | A design subscription presented as a retro broadcast: the entire site is seen through a CRT screen, with a chrome logo token as its mascot. |
+| Illoca | Awwwards | 8.2 | Software for architects sold as a drafting table: a two-colour illustrated studio on graph paper that the scroll pushes into until the drawing fills the screen. |
+| Aspen Search | Awwwards | 8.2 | The page is a tile system with no margins: the two-word name is split across cells that alternate type, dithered image, black and one mint green. |
+| Dragonfly Redux | Awwwards | 8.2 | A crypto fund presented as a terminal artefact: every picture is rendered in characters, framed by four letters of the name pinned to the viewport corners. |
+| Monolog | Awwwards | 8.2 | A studio pitch run as an asymmetric sheet: a narrow left column carries the sales talk while a wide right column stacks a very heavy headline and the proof. |
+| The Queue | One Page Love | 8.1 | An essay on queueing where the queue is the ornament: a line of drawn figures stands along the bottom of the hero and returns between chapters in changing period dress. |
+| Paul Kalkbrenner | Awwwards | 8.1 | Swiss poster typography for a techno artist: the name as one black line with a photo set inside it like a glyph, then every chapter gets its own flat colour. |
+| Vero New York | Awwwards | 8.1 | A keepsake treated like couture: a slow close-up film opens, then a white sculpture of a dress stays pinned at centre while one sentence passes over it. |
+| Depo Luxe | Awwwards | 8.1 | A film production roster shown as a full-screen reel in which every step is one film with only a title, a director and a client, set like credits at body size. |
+| Longbow | Awwwards | 8.1 | The page is built on a visible four-column construction grid, and cars, cards and a giant condensed marquee are slotted into its cells like objects on an artboard. |
+| Mosby's Files | Awwwards | 8.0 | An archive of architects presented as a physical stack of coloured index-tab file folders that you flip through. |
+| Sarah & Matt Wedding | One Page Love | 8.0 | The site is the invitation: a letterpress-style card opens the page, and its ornaments and small typographic parts become the components for everything after it. |
+| Zara Webb | One Page Love | 8.0 | A one-woman newborn-care practice presented like a hand-made keepsake: a mascot rabbit, scalloped and flower-shaped cut-outs, candid film photographs. |
+| Noho | Awwwards | 8.0 | Furniture sold through people misusing it (wearing, balancing on, hiding behind chairs on flat colour backdrops) while the interface stays quiet. |
+| Juggle | One Page Love | 8.0 | The headline literally drowns: a flat blue field rises to half height and the lines below the waterline change colour. |
+
+Full notes on any studied site: `node scripts/draw.mjs --site <id>` (ids appear on direction sheets).
+
+## 11. How the skill was tested
+
+Six client briefs (an invoicing tool, a restaurant, a designer's portfolio, a ceramic product, a
+guesthouse, a design conference), each with no photographs. For every brief a fresh agent built the
+page three ways: with no skill (baseline), with another published design skill (atelier, three briefs)
+and with this skill. Every build was photographed by `inspect.mjs` in the same way and judged blind
+by a separate agent with the juror brief (Awwwards weights, anonymous A/B/C folders, screenshots
+only). The skill was revised after each round from the jurors' reasons and the builders' notes.
+
+| Round | Briefs | This skill | Baseline | Atelier | Wins |
+| --- | --- | --- | --- | --- | --- |
+| 1 | 4 | 6.6 | 7.7 | 6.8 | 1 of 4 |
+| 2 | 3 | 7.1 | 8.0 | | 0 of 3 |
+| 3 | 3 | 7.5 | 7.5 | | 1 of 3 |
+| 4 (unseen briefs) | 3 | 6.9 | 7.9 | 7.5 | 0 of 3 |
+| 5 (same three) | 3 | 7.7 | 7.8 | 7.2 | 2 of 3 |
+
+Under the inspector, the final builds measured 0 FAIL each; the baselines measured 8 to 13 FAIL each
+(eyebrows, monospace labels, 01/02/03 numbering, hairlines, gradients, shadows, three-line headlines,
+text under 13px).
+
+What the jurors rewarded, in the order they named it: an idea that belongs to this client and not to
+the category (the competitor test); one live thing on the page; full content at a readable size; a
+first screen with one dominant element and a real button; drawings of the subject with detail. What
+they punished: a quiet page that read as empty, a small headline, text sliding over pictures or cut
+at the top, a page recoloured mid-section, rows cut at the right edge, a large sentence over three or
+more lines (read as a long headline whatever its markup), navigation that took over the first screen.
+Each of these is now a rule in SKILL.md or a check in the inspector.
+
+Limits: one juror per brief per round, so single scores carry about half a point of noise; the round-5
+briefs had been seen in round 4; jurors are models, not people.
+
+## 12. The October 2026 study: 100 Sites of the Day
+
+A second study, made for v2.1, of the latest 100 Awwwards Sites of the Day (10 July to 17 October
+2026), with a different aim from the first: where the pictures and footage sit, how pages move, and
+the frame (margins, balance, empty space, titles). About three in four of these sites were also in
+the first study.
+
+- **Capture.** Headless Chrome at 1440×900 and 390×844 on 18 October 2026: four frames of the first
+  4.5 seconds after load, every screen while scrolling with real wheel input (one frame at rest per
+  step; the mid-step frames were cut from the top of the document instead of the viewport, so they
+  were not used), five phone screens, and a measurement pass in the page: every picture and
+  clip with its box, ratio, fit and corners; every section's content edges and pictures; blank runs;
+  the CSS that loaded (curves, durations, keyframes, breakpoints, feature counts); the animations,
+  transitions and script-driven moves that actually ran; GSAP tweens and scroll triggers where the
+  page exposed them. Nothing a site owns (code, copy, pictures) is reproduced in the skill; only
+  measurements and descriptions in our own words.
+- **Panel.** One model reader per site studied its frames and measurements, described the idea, the
+  first screen, the frame, every section, where each picture sits, the motion and what not to copy,
+  and scored it the Awwwards way. 91 of 99 captures were usable (the rest showed a gate, a bot wall or
+  a firewall page). Scores ran 6.7 to 7.9 (median 7.45); "top" means 7.5 or more (36 sites), "lowest"
+  under 7.3 (16).
+- **What it changed.** Where pictures and footage go: `imagery.md` §12. What strong pages do with
+  motion, new tokens, recipes and the gimmicks to avoid: `motion.md` §2, §4–6 and §9–10. Empty space
+  and the frame: `layout.md` §4–5. New compositions in `library/heroes.json` and `sections.json` and
+  notes on media and motion in `library/sites.json` (`draw.mjs --site <id>`).
+- **Headline numbers.** Pictures fill a median 16% of a scrolled screen, but in whole screens: 42% of
+  screens hold none and 19% are 90% picture or more. The median page carries 7 pictures (top 8,
+  lowest 2) and 42% carry footage (half of the top sites, one of the 16 lowest). 94% of pictures have
+  square corners. Strong ease-outs are the curves that ran (expo and quint out); the median of all
+  that ran on a site is 420ms. 60 of 99 open on a loading screen, and a third of the usable pages were
+  still unreadable 4.5 seconds after load, with no gain in the design marks. About 1 text section in
+  100 leaves half the width empty; the outer margins of strong pages match to a few pixels; 82% of
+  text sections open with a heading; 15 of 97 first screens never say what the thing is, and those
+  lose usability points.
+- **Limits.** One capture per site on one day; a WebGL scene can render blank in a headless browser;
+  the scroll-linked frames are partly an artefact of smooth-scroll libraries; one reader per site, so
+  single scores carry about half a point of noise.
+
+## 13. The app-screen study
+
+For dashboards and app screens (v2.1), a separate study of 23 real product screens chosen by the
+owner (17 products, 17 light and 6 dark, at 1440–1512px): each screen measured from its pixels by a
+reader with full-resolution crops, six cross-cutting reports (shell, data and charts, tables and
+forms, visual language, taste, styles), and a synthesis into `references/app-screens.md` and
+`library/app.json` (seven styles, five shells, screen patterns). The screenshots stay private; the
+skill carries only the measurements and the rules. Blind test rounds of app screens built with and
+without the skill then shaped the warnings at the top of that file.

package/assets/copilot/packs/frontend/skills/design-taste-frontend/references/scenes.md

@@ -0,0 +1,174 @@
+# Scroll scenes
+
+The big moments of a page: stretches of scroll where the page stops being a column of sections and
+becomes a scene. A camera flies through a field of pictures, a picture grows from a window to the whole
+screen, a word buckles under the scroll, a set of photographs orbits and lands in a grid. These are what
+visitors remember from award sites, and what a page built from tidy sections alone never has.
+
+The scene library is taken apart from recent Awwwards Sites of the Day (October 2026: 43 sites recorded
+frame by frame while scrolling, 261 scenes described, 30 types), rebuilt from scratch in our own code,
+tested frame by frame at desktop and phone width and under reduced motion, and reviewed against the
+scenes it came from. Nothing a site owns is in them. Until `library/scenes.json` ships the draw deals
+none; a page that needs a scene builds one on the stage (section 8), with every rule here.
+
+## Contents
+
+1. What a scene is
+2. Putting a scene on a page
+3. Filling it
+4. Fitting it to the page
+5. The phone, reduced motion, no script
+6. Checking it
+7. Rules for scenes
+8. When no scene in the library fits
+9. The catalogue
+
+## 1. What a scene is
+
+A tall section whose stage holds still while the page scrolls past it. The stage is
+`position: sticky`; the section is (hold + 1) screens tall, so the stage is held for `hold` screens;
+a GSAP timeline is scrubbed from 0 to 1 by that scroll. Nothing captures the wheel: the scrollbar always
+tells the truth, the keyboard and the trackpad work as everywhere else, and the scene ends.
+
+What a scene is not: a fade-up, a small parallax, a sticky footer, a marquee. Those are the quiet layer
+(`references/motion.md`). A scene changes the whole screen.
+
+The direction sheet deals two or three (section 9 of the sheet), from different families, each placed
+on the section of the argument it can carry. Build them in step 6, with that section: a scene is
+composition, not decoration added at the end.
+
+## 2. Putting a scene on a page
+
+Copy the shared stage and the dealt scene's files into the project (`assets/scenes/stage.css`,
+`stage.js`, `<id>.css`, `<id>.js`). Each scene file's header comment lists the markup it expects and
+its options; `assets/scenes/demo/<id>.html` is a complete working page to read beside it.
+
+```html
+<head>
+  <script>document.documentElement.classList.add('js')</script>
+  <link rel="stylesheet" href="scenes/stage.css">
+  <link rel="stylesheet" href="scenes/<id>.css">
+</head>
+<body>
+  …
+  <section class="scene" data-scene="<id>" data-options='{"hold": 3}' aria-label="…">
+    <div class="scene-stage">
+      <!-- the markup from the scene file's header, filled with this page's content -->
+    </div>
+  </section>
+  …
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/gsap.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/ScrollTrigger.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/lenis@1.3.26/dist/lenis.min.js"></script>
+  <script src="scenes/stage.js"></script>
+  <script src="scenes/<id>.js"></script>
+  <script>Stage.smooth(); Stage.init();</script>
+</body>
+```
+
+- Load SplitText (`gsap@3.15.0/dist/SplitText.min.js`) only when a scene file says it needs it.
+- `Stage.smooth()` adds weighted wheel scrolling (Lenis at lerp 0.12). It stays off for touch and for
+  reduced motion. Leave it out on a quiet page; the scenes work either way.
+- `Stage.init()` starts every `[data-scene]` on the page. A page with two scenes loads both files.
+- The versions are pinned. Do not change them to `@latest` or an unpinned major.
+
+## 3. Filling it
+
+A scene is only as strong as what goes in it. The scene file's header and the sheet's "Content" line
+say how many pictures and words it takes; these hold for all of them:
+
+- **Pictures of one family.** Same light, same grade, same kind of subject: a field of mismatched stock
+  photographs breaks the illusion of one space faster than any timing error. Real pictures of the
+  subject's world (`assets.mjs`), the project's own, or the dealt photographs, in that order
+  (`references/imagery.md`). Size each to its largest display size, set `width` and `height`.
+- **Words that read in a breath.** A held statement is 4 to 12 words; captions are one to four words in
+  the text face, sentence case. One statement on screen at a time.
+- **The scene says something about the subject.** A fly-through of the studio's work, the route a
+  shipment really takes, the four rooms of the house, the product's change of state. A scene filled
+  with unrelated pictures is a gimmick and reads as one.
+- **Real content only.** If the scene needs eight pictures of the subject and there are three, take the
+  `--redraw scenes`, never pad it with stand-ins.
+
+## 4. Fitting it to the page
+
+- The scene files read the page's tokens: `--ground`, `--ink`, `--muted`, `--accent`,
+  `--font-display`, `--font-text` (with fallbacks). Set them on `:root` from the sheet and the scene
+  takes the page's colour and type. Check the demo against your page, not the other way round.
+- Display type in a scene uses the dealt display face and the two-line headline rule; statements stay
+  at statement size.
+- Leave a quiet section between two scenes (a text section, a list, a plain picture) so each one lands.
+  Two scenes back to back read as one long ride and the second loses.
+- A scene on the first screen must be readable at progress 0: the title, the sentence and the action are
+  there on the first frame (motion rule 1), and the scene starts moving only when the visitor scrolls.
+- Give the section a heading. If the design has no visible heading in the scene, the section still
+  carries one (`aria-label` on the section and a real heading in the finished composition).
+
+## 5. The phone, reduced motion, no script
+
+- **The phone.** Each scene has a phone plan in its file: the same scene with changed numbers, a
+  simpler version, or `phone: 'rest'`, where the phone shows the finished composition. Touch scrolling
+  is never smoothed. Look at the phone sheet as carefully as the desktop one.
+- **Reduced motion and no script.** The section is an ordinary section showing the finished
+  composition: the same content, laid out to read without motion. Nothing is hidden waiting for a
+  script. The inspector's `reduced-hidden` check and the reduced sheet of `scenes.mjs` show it.
+- **A failed CDN** falls back to the finished composition too (the stage adds `.is-rest`). The
+  inspector fails a scene that rests on desktop (`scene-not-live`), so a broken script cannot pass.
+
+## 6. Checking it
+
+```bash
+node <skill>/scripts/scenes.mjs <page>        # every scene at 0, 10 … 100%, desktop and phone, and reduced motion
+node <skill>/scripts/inspect.mjs <page>       # the gate; with scenes on the sheet it also films the scroll
+```
+
+`scenes.mjs` writes one contact sheet per scene and width to `.taste-skill/scenes/`. Read every one.
+At every frame ask: is there one clear thing to look at; can the statement on screen be read; is
+anything popping, blank, cut off or crossing the words; is it as bold as it should be? The inspector's
+`desktop-film-NN.jpg` shows the whole page's scroll a third of a screen at a time: check that the
+scenes and the quiet sections between them make a rhythm, and that nothing between them is empty.
+
+## 7. Rules for scenes
+
+1. **Two or three per page,** from different families, a quiet section between them. The inspector
+   warns over four (`many-scenes`) and when scenes hold more than 60% of the page (`scene-heavy`).
+2. **Each holds one to four screens:** about one screen per beat of the story; a hold with nothing new
+   to show is cut, not padded.
+3. **Native scroll only.** No wheel capture, no locking the page, no scenes that only run on a click.
+   Smoothing only through `Stage.smooth()`.
+4. **Readable at its rest points.** The statement on screen reads whole; nothing passes over text while
+   it is being read; text on a picture has a flat scrim or a calm area under it.
+5. **Inside a scene the scene's numbers apply** (motion rule 7): a picture may grow from a window to the
+   whole screen, type may cross the stage, a camera may fly through pictures. Outside scenes, the quiet
+   limits of `references/motion.md` hold.
+6. **Transform, opacity, clip-path.** Nothing that forces layout on every frame. Pictures decoded before
+   they move.
+7. **The house rules hold inside scenes:** no monospace captions, no 01/07 counters (a plain "3 of 7" if
+   a count is needed), no gradients (flat scrims), no shadows or glows, no hairline decoration, no
+   decorative particles, no violet.
+8. **The finished composition is designed,** not an afterthought: it is what reduced motion, a failed
+   script and some phones see.
+
+## 8. When no scene in the library fits
+
+Redraw first (`--redraw scenes`). If the brief really needs a scene the library does not have, build it
+on the same stage so it inherits the guards:
+
+```js
+Scenes['my-scene'] = (root, opts = {}) => Stage.scene(root, {
+  hold: opts.hold ?? 2,          // screens the stage is held for
+  scrub: opts.scrub ?? true,     // true when Lenis runs; 0.4-0.8 without it reads as weight
+  phone: 'same',                 // or 'rest', or { hold, build } for a phone plan
+  build(tl, { q, phone }) {      // positions are fractions of the scene, 0-1
+    tl.fromTo(q('.picture'), { clipPath: 'inset(30% 30% 30% 30%)' }, { clipPath: 'inset(0% 0% 0% 0%)', duration: 0.6 }, 0)
+      .to(q('.title'), { yPercent: -40, autoAlpha: 0, duration: 0.25 }, 0.7);
+  },
+});
+```
+
+and write its CSS finished composition first, then the live layout under `.scene.is-live`. Check it
+with `scenes.mjs` like any other.
+
+## 9. The catalogue
+
+(Generated from `library/scenes.json`; the draw deals from it. `node <skill>/scripts/draw.mjs --list
+scenes` prints it.)

package/assets/copilot/packs/frontend/skills/design-taste-frontend/references/tells.md

@@ -0,0 +1,115 @@
+# Tells — the dated registry
+
+A tell is a device that makes a page read as generated. Tells are not bad design in themselves; most
+began as good ideas on good sites. They became tells by being produced by default, everywhere, without
+a reason. That is why this registry is dated, and why it never names a replacement font, colour or
+component: every published "use this instead" list has become the next wave of tells within months.
+Replacements here are procedures (draw from the library, derive from the subject), not products.
+
+`scripts/inspect.mjs` and `scripts/lint.mjs` detect most entries. Status: **banned** means the
+inspector fails the page; **warned** means it flags it and you need a reason.
+
+## Contents
+
+1. First wave (2023–2024)
+2. Second wave (2025)
+3. Third wave (2025–2026): the "fix" that became the look
+4. Gallery fashion, banned as house style
+5. Structural tells
+6. Copy tells
+7. Motion tells
+8. Why removal is not enough
+
+## 1. First wave (2023–2024)
+
+| Tell | Status | Do instead |
+| --- | --- | --- |
+| Violet / indigo gradients on hero, buttons and glows | banned | The dealt palette; flat colour |
+| Gradient-filled headline text | banned | Solid ink |
+| Glass panels: backdrop blur, translucent cards | warned (2 or more) | Opaque surfaces one tone step from the ground |
+| Glowing or gradient "Get started" button | banned | Flat button named for its action |
+| Soft grey drop shadow under every card | banned | Tone step, or no box |
+| Three identical feature cards, each with an icon in a rounded square | banned | The dealt section blueprint |
+| Emoji as icons or bullets | banned | Words, or a real picture |
+| Centred headline, subtitle, two buttons, screenshot below | no rule; the draw avoids it | The dealt hero |
+| The same typeface on every generated page | warned (lint: default-font) | The dealt type system |
+
+## 2. Second wave (2025)
+
+| Tell | Status | Do instead |
+| --- | --- | --- |
+| Eyebrow / kicker: tiny tracked uppercase label above every heading | banned | Fold it into the heading, or delete |
+| Pill badge above the hero headline ("New", "Beta", "Introducing") | banned | Say it in the supporting sentence |
+| One word of the headline in italic serif, colour or underline | warned | One face, one colour |
+| Bento grid of rounded tiles as the feature section | warned as card rows | A composed section; tiles only in the dense-tiles direction, filled, strict sizes |
+| Near-black ground with one neon accent and a glow | banned via shadow, gradient | A dealt dark palette, no glow |
+| Floating rounded pill navigation with blur | warned | A plain bar |
+| Fake dashboard hero built from grey bars and donut charts | no rule; see imagery.md §7 | A real interface fragment, or no image |
+| Decorative status dot ("Available for work", pulsing "live") | lint: bounce | Remove |
+| Fade-and-rise on every section | no rule; see motion.md | One signature move |
+
+## 3. Third wave (2025–2026): the "fix" that became the look
+
+The remedy published for the first two waves was "warm it up and make it editorial". Models adopted
+the remedy wholesale and it is now the most recognisable generated look of all.
+
+| Tell | Status | Do instead |
+| --- | --- | --- |
+| Yellow-cream ground + terracotta / rust / clay accent | banned together; terracotta banned alone; cream warned | The dealt palette. Warmth from a low-chroma stone, a deep ink, a photograph, or a full warm field |
+| High-contrast or soft serif display as the shortcut to "premium" | no rule | The dealt type system, whatever class it is |
+| Oversized italic serif headline | no rule | As dealt |
+| Broadsheet cosplay: hairline rules everywhere, zero radius, dense columns | banned via hairline | Structure from space and tone |
+| "Field notes", "Quietly trusted by", "On our desks": performative labels | lint: copy | Plain section names |
+
+## 4. Gallery fashion, banned as house style
+
+These are common on award sites right now. In the study they appear *more* often on the top-scored
+sites than on the weak ones (panel observations: monospace labels 44% against 24%, index numbering 38%
+against 21%; measured thin rules 61% against 52%). They are banned here regardless, by the owner's
+decision: they are the first things a generator copies from the gallery, they carry no information,
+and a page built without them has to find real structure.
+
+| Tell | Status | Do instead |
+| --- | --- | --- |
+| Monospace micro-labels, mono as a "technical" voice, mono captions | banned | The text face; tabular figures for data |
+| Index numbering: 01 / 02 / 03, (001), "Step 02", numbered section markers | banned | Order by position, scale, or the words; `<ol>` when it is truly a list |
+| Thin rules: hairline dividers, ruled grids, 1px outlined boxes and tiles | banned (boxes: 3 or more) | Space, tone steps, filled shapes, a thick bar if a bar is the idea |
+| Design-tool chrome as ornament: crosshairs, crop marks, selection handles, dashed guides, rulers | banned via hairline, dashed | Remove |
+| Agency micro-meta: local time, coordinates, weather, version stamps, "©2026 — Scroll", middle-dot strings | lint: copy; micro-label | Remove |
+| Tiny uppercase letter-spaced captions scattered around the viewport | banned (3 or more) | Sentence case at readable size, placed with the content it describes |
+
+Tiny tracked capitals are the one item in this group the data condemns as well: 16% of top sites
+against 57% of weak ones.
+
+## 5. Structural tells
+
+| Tell | Status | Do instead |
+| --- | --- | --- |
+| Headline as a full sentence at display size, three or four lines | banned (over two lines) | A title of about five words; the rest goes below |
+| Stock section order: hero, logos, features, testimonial, pricing, CTA | no rule; see copy.md §1 | The order of the argument |
+| Every section the same layout family | critique.md pass 9 | Different composition per section, from the sheet |
+| Everything centred | warned over 72% | Left-anchored, one centred moment |
+| One medium border radius (12–16px) on everything | none | Square or fully round, chosen once |
+| Nine nearly equal font sizes | warned over 9 | Five sizes, far apart |
+| Invented social proof: logos, quotes, star rows, "10,000+ teams" | copy.md §5 | Real proof, or none |
+| Text or a CSS box where a picture belongs | critique.md cap | A real picture, or a design that needs none |
+
+## 6. Copy tells
+
+Flagged by `lint.mjs`: the genre's verbs and adjectives (unlock, supercharge, seamless, elevate,
+effortless, cutting-edge, all-in-one …); the correction ("not just X, it's Y"); tricolon headlines;
+"Get started" and "Learn more" as labels; more than a handful of em dashes; lorem ipsum. See
+`copy.md` §6.
+
+## 7. Motion tells
+
+Identical fade-up on every block; a dozen staggered hero entrances; hover lift on every card; bounce
+easing; infinite loops that mean nothing; reveals that fail and leave a blank band. See `motion.md` §9.
+
+## 8. Why removal is not enough
+
+A page with every tell removed and nothing put in their place is an empty page with good manners, and
+that is a tell too (the "avoidance aesthetic": anyone could guess it from the category plus the list of
+things to avoid). The tells were filling a gap where an idea should have been. The order of work in
+`SKILL.md` exists to fill that gap first: the idea from the subject, the dealt composition, real
+pictures or committed type, and only then the checks.