codeply-cli 0.5.5 → 0.6.0

package/skills/codeply-taste/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` §7.
+
+## 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.

package/skills/codeply-taste/references/type.md

@@ -0,0 +1,170 @@
+# Type
+
+Typography is most of what a visitor sees and most of what makes a page look designed or assembled.
+The direction sheet deals you a type system (faces, weights, settings). This file is how to use it.
+
+## Contents
+
+1. What the study measured
+2. The scale: few sizes, far apart
+3. Setting display type
+4. Setting text
+5. Loading the fonts properly
+6. One family or two
+7. Details that separate set type from typed text
+8. Mistakes the inspector cannot see
+
+## 1. What the study measured
+
+From 202 measurable sites out of the 247 studied (Chrome, 1440×900 and 390×844):
+
+| | Median | Middle half | Note |
+| --- | --- | --- | --- |
+| Hero headline size | 72px (5.0vw) | 43–109px | Top-scored sites: 6.0vw median |
+| Largest type on the page | 6.4vw | up to 10.4vw | Top-scored sites 8.4vw, weak sites 5.0vw |
+| Hero headline on a phone | 40px | 32–59px | |
+| Hero tracking | -0.01em | -0.03 to 0 | Tighter as size grows |
+| Hero leading | 1.0 | 0.95–1.1 | |
+| Body size | 16px | 14–18px | |
+| Headline ÷ body size | 4.3 | | Top-scored sites 4.7 |
+| Typefaces in real use | 2 | 31% use one, 45% two, 22% three | |
+| Hero weight | regular 48%, medium 18%, bold or heavier 22% | | Big type does not need to be bold |
+| Hero in capitals | 24% | | |
+| Hero centred | 39% | | 52% on the weak sites |
+
+Two things to take from it. First, size contrast is the main lever and the best sites pull it harder.
+Second, weight is not: half of the heroes are set in a regular weight. Scale and spacing make type
+confident; bold is one option among several.
+
+## 2. The scale: few sizes, far apart
+
+The panel described about 30 of the 114 strongest sites as using two or three type sizes with nothing
+in between, and none as using a graded five- or six-step scale. So: one display size, one text size
+and a small size carry the page; a lead size and a heading size exist for when they are needed. Five
+is the ceiling. The common failure is nine sizes that are all near each other (16, 18, 20, 24, 28,
+32…), which reads as mush. Choose steps that are clearly different:
+
+```css
+:root {
+  --step-small: clamp(0.8125rem, 0.79rem + 0.1vw, 0.875rem);   /* 13–14px  captions, legal */
+  --step-body:  clamp(1.0625rem, 1rem + 0.25vw, 1.1875rem);    /* 17–19px  paragraphs */
+  --step-lead:  clamp(1.25rem, 1.1rem + 0.7vw, 1.625rem);      /* 20–26px  supporting line, large body */
+  --step-head:  clamp(2rem, 1.3rem + 3.2vw, 4rem);             /* 32–64px  section headings */
+  --step-display: clamp(3rem, 1rem + 9vw, 9rem);               /* set by the hero blueprint */
+}
+```
+
+- `--step-display` belongs to the direction. A monument wordmark is 16–24vw; a quiet instrument's
+  headline is 28px. Use the size the hero blueprint gives, as a `clamp()` so it scales with the
+  viewport but is bounded on phones and very wide screens.
+- Keep the gap: the display size should be at least four times the body size on desktop, and nothing
+  should sit between `--step-lead` and `--step-head` unless the design truly needs a sixth size.
+- Resist a "subheading" size for every card and label. If two sizes look almost the same, make them
+  the same.
+
+## 3. Setting display type
+
+Large type exposes spacing that is invisible at text size. Apply all of these to anything over 40px:
+
+```css
+.display {
+  font-size: var(--step-display);
+  line-height: 0.95;              /* 0.85–1.05; tighter for capitals and condensed faces */
+  letter-spacing: -0.035em;       /* -0.02 to -0.05em; use the value on the direction sheet */
+  font-kerning: normal;
+  text-wrap: balance;
+  max-width: 14ch;                /* choose the measure so lines break where you want */
+  margin: 0;
+}
+```
+
+- **Tracking scales with size.** The larger the type, the tighter it needs to be; a value right for
+  120px will choke 32px. Set tracking per step, not once for all headings.
+- **Leading below 1.0 needs checking.** Look for collisions between descenders and the ascenders or
+  accents of the next line. Two-line headlines make this easy to verify by eye.
+- **All capitals** want slightly open tracking (0 to +0.03em) even at display size, and leading around
+  0.9.
+- **Optical alignment.** Big letters with round or diagonal left edges (O, C, A, T, W) look indented.
+  Pull the headline left by about 0.04–0.06em (`margin-left: -0.05em`) so it aligns optically with the
+  text beneath it.
+- **Viewport-wide type.** For a line that must span the screen, size it in `vw` and verify at 390 and
+  1440; set `white-space: nowrap` and let the container clip rather than wrap. Calculate the size from
+  the character count: `font-size ≈ container width ÷ (characters × k)` with k from `copy.md` §2.
+- Never add a text shadow, an outline stroke, or a gradient fill to display type.
+
+## 4. Setting text
+
+```css
+body { font-size: var(--step-body); line-height: 1.5; font-kerning: normal; text-rendering: optimizeLegibility; }
+p { max-width: 62ch; text-wrap: pretty; margin: 0; }
+p + p { margin-top: 0.9em; }
+.lead { font-size: var(--step-lead); line-height: 1.35; max-width: 40ch; }
+small, .caption { font-size: var(--step-small); line-height: 1.45; }
+```
+
+- Measure: 45–75 characters. Wider than that and the eye loses the next line; the inspector warns
+  past about 88.
+- Leading: 1.45–1.6 for body, tighter (1.3–1.4) for the larger lead size, looser for long reading.
+- Secondary text is the same face in a softer ink (`--muted`), not a lighter weight and not smaller
+  than 13px.
+- Do not centre paragraphs longer than three lines. Do not justify.
+- Light text on a dark ground looks heavier: drop one weight step or add 0.01em tracking, and raise
+  leading slightly.
+
+## 5. Loading the fonts properly
+
+The sheet gives a `<link>` tag. Use it exactly; do not swap in a face you prefer.
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="…from the direction sheet…" rel="stylesheet">
+```
+
+```css
+:root {
+  --font-display: "Family From Sheet", "Helvetica Neue", Arial, sans-serif;
+  --font-text: "Family From Sheet", Georgia, serif;
+}
+```
+
+- Request only the weights you use (usually two or three in total).
+- Always give a fallback stack of the same broad kind (sans for sans, serif for serif).
+- In a framework, use its font loader with the same family and weights (`next/font/google`, or a
+  self-hosted `@font-face` with `font-display: swap`). Fontshare faces load from the
+  `api.fontshare.com` stylesheet on the sheet.
+- After building, `inspect.mjs` reports the families that actually rendered. If it warns that a face
+  did not load, the screenshots show a fallback and nothing you judge from them is real. Fix the link
+  first.
+
+## 6. One family or two
+
+A third of the studied sites use a single family for everything, and it is the safest way to look
+coherent. When the dealt system has two faces:
+
+- Give each a job and never swap them: one sets headlines, the other sets everything else.
+- Do not introduce a third face for labels, numbers or quotes.
+- Do not mix two faces inside one headline.
+- Italic is for titles of works and real emphasis inside paragraphs, never as decoration.
+
+## 7. Details that separate set type from typed text
+
+- Curly quotes and apostrophes, real dashes, a real ellipsis (see `copy.md` §7).
+- `font-variant-numeric: tabular-nums` for prices, tables, dates in columns; `oldstyle-nums` suits
+  serif body text.
+- `text-underline-offset: 0.18em; text-decoration-thickness: 0.07em` on links, so underlines clear the
+  descenders.
+- `hyphens: none` on headings. `overflow-wrap: anywhere` only on long URLs or emails.
+- A heading belongs to the text after it: space above a heading is at least twice the space below.
+- `::selection { background: var(--accent); color: var(--accent-ink); }` and a visible
+  `:focus-visible` outline in the accent, so even the browser's own states belong to the design.
+- Do not change weight on hover; the line reflows.
+
+## 8. Mistakes the inspector cannot see
+
+- A headline that passes the two-line rule but breaks badly: one orphan word on line two, or a break
+  that splits a phrase ("Stools for small / kitchens"). Author the break.
+- Display type so tight that letters touch, or so loose it falls apart.
+- A confident hero followed by section headings almost as large. Keep one size dominant per screen.
+- Body text set in the display face when that face was drawn for large sizes only.
+- Everything bold. If every line is emphasised, none is.