codeply-cli 0.5.5 → 0.6.0

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

@@ -0,0 +1,141 @@
+# Colour
+
+The direction sheet deals a palette with named roles. This file is how to apply it so the page looks
+decided rather than tinted.
+
+## Contents
+
+1. What the study measured
+2. The roles
+3. Proportion
+4. Surfaces without lines or shadows
+5. Colour fields
+6. Dark pages
+7. Colour and photographs
+8. Contrast
+9. Banned families, and what "warm" means here
+
+## 1. What the study measured
+
+- 41% of the studied pages are dark, 59% light. A quarter sit on pure white; 12% on pure black.
+- Schemes, as the panel classed them: monochrome plus one accent 23%, light neutral 22%, dark neutral
+  14%, several flat colours 13%, strictly two-tone 12%, colour carried by photographs 9%, one saturated
+  field 6%.
+- Buttons are neutral (black, white, grey) on 52% of sites. A coloured button is a choice, not a
+  requirement.
+- Gradient fills appear on 22% of the top-scored sites and 52% of the weak ones; gradient text on 2%
+  against 13%.
+- One site in 246 has a terracotta primary button and none has a violet one. Those are colours of
+  generated pages, not of the gallery. Warm off-white grounds do occur (32 sites), nearly always with
+  a dark or green ink rather than an orange accent.
+- Top-scored sites change the page's field colour between sections more often (a median of two section
+  grounds against one).
+
+## 2. The roles
+
+```css
+:root {
+  --bg: …;          /* the ground: most of the surface */
+  --surface: …;     /* one tone step from the ground: filled panels, form fields, tiles */
+  --ink: …;         /* main text and the strongest marks */
+  --muted: …;       /* secondary text; still passes contrast on --bg */
+  --accent: …;      /* the one accent */
+  --accent-ink: …;  /* text on the accent */
+  /* --field-1 … --field-n and their inks, when the palette has section fields */
+}
+```
+
+Use the tokens for every colour in the build. A raw hex in a component is a second palette starting.
+Do not add greys between the roles: if you need a quieter text, it is `--muted`; if you need a quieter
+surface, it is `--surface`.
+
+## 3. Proportion
+
+Decide the shares before colouring anything and check them in the screenshot:
+
+- **Ground:** 70–90% of the page.
+- **Ink:** text and perhaps one inverted section (ink as ground, ground as ink).
+- **Accent:** under 5% of any screen. It marks the action and at most one other recurring thing. The
+  moment it appears in five places it stops meaning "here".
+
+Palettes with fields (flat-loud, pastel) work differently: each section is one field at full strength
+and the proportion rule applies inside each section (field, its ink, nothing else).
+
+The accent is not for headings, icons, bullets, borders or underlines unless the direction sheet says
+so. A headline is ink.
+
+## 4. Surfaces without lines or shadows
+
+With rules and shadows banned, a surface is told apart from the ground by tone alone:
+
+```css
+.panel { background: var(--surface); }          /* 2–6 lightness points from --bg */
+.field { background: var(--surface); border: 0; } /* inputs: filled, with a clear focus state */
+.field:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+```
+
+- One step is enough. If a panel does not read, increase padding or separate with space before
+  reaching for a second tone.
+- Do not nest a panel inside a panel.
+- Images do not need a frame. If a light photograph melts into a light ground, change the crop or set
+  it on `--surface`, do not outline it.
+- A thick bar (4px or more) in ink or accent is a graphic element, allowed where the direction uses
+  it. A 1px line is not.
+
+## 5. Colour fields
+
+A section that changes the whole ground colour is the strongest colour move available, and it replaces
+dividers, cards and background decoration at once.
+
+- Fields meet edge to edge with a hard line. Nothing fades.
+- Every field has its own assigned ink from the palette. Never put `--muted` on a coloured field; use
+  the field's ink at full strength, or at 70% opacity for secondary text if it still passes contrast.
+- Neighbouring fields should differ in lightness, not only in hue, or the page vibrates.
+- Order them like chapters: open strong, rest, surprise, close dark or very light.
+- The page's meta theme colour and the navigation follow the first field.
+
+## 6. Dark pages
+
+- Put `color-scheme: dark` on the root so form controls and scrollbars follow.
+- The ground is a deep tone with a slight tint from the palette, and the ink is a soft light, not
+  `#fff` on `#000`, unless the palette deals exactly that for a stark two-tone direction.
+- Secondary text is where dark pages fail: check `--muted` against the ground (4.5:1).
+- Depth on dark comes from a lighter surface step, never from glows or coloured light.
+- Use lighter font weights than you would on a light page.
+
+## 7. Colour and photographs
+
+- When photographs carry the colour, the interface stays neutral and takes its ink from the darkest
+  tone in the imagery.
+- Do not wash a photograph with the brand colour. Either leave it alone, or commit to a real treatment
+  for every image on the page (all greyscale, or all untouched).
+- Text over a photograph needs a calm region. If there is none, move the text off the image. A neutral
+  scrim (black or the ink colour, 30–55% opacity, flat or fading over the text area only) is the one
+  gradient the inspector allows.
+- A flat field sampled from a photograph (its sky, its shadow) makes a section sit with that image.
+
+## 8. Contrast
+
+- Body text 4.5:1 or better; display type and large numerals 3:1 or better; the dealt palettes meet
+  7:1 for ink on ground.
+- `inspect.mjs` computes contrast for text on flat grounds and fails anything under 2.6:1. It cannot
+  see text over photographs: check those in the screenshots yourself.
+- Do not lower opacity on text to make it "soft" unless you have checked the resulting ratio.
+- Focus states and hover states increase contrast, never reduce it.
+
+## 9. Banned families, and what "warm" means here
+
+The inspector fails these:
+
+- **Cream with terracotta.** A yellow-cream ground (roughly hue 22–62, light and noticeably
+  saturated) with a rust, clay or burnt-orange accent is the house look of AI assistants and of the
+  pages they generate. Either half alone is suspect; together they are unmistakable.
+- **Violet and indigo.** The first wave of generated pages was purple; it still reads that way.
+
+If the brief wants warmth, get it from a low-chroma stone, bone or putty ground (saturation under
+about 15%), from a deep green, brown or oxblood ink, from photographs, or from a full warm field
+(mustard, tomato red, pink) used flat and with conviction. Warmth is not beige.
+
+If the brand itself owns one of the banned colours, it is the brand's and you keep it: use
+`--keep palette`, pass `--allow palette-purple` (or the relevant rule) to the inspector, and note it in
+the report.

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

@@ -0,0 +1,177 @@
+# Words
+
+Copy is the first design decision. A headline that needs four lines cannot be rescued by typography,
+and a page of slogans cannot be rescued by layout. Write the page as plain text before any markup.
+
+## Contents
+
+1. Write the argument first
+2. The two-line headline (with the character budget)
+3. Headline shapes that work
+4. Supporting line, body, buttons
+5. Proof without inventing it
+6. Things that read as generated
+7. Micro-typography
+
+## 1. Write the argument first
+
+Answer in one line each, in a scratch note:
+
+- Who is reading, and what do they already know?
+- What is this, said the way its maker would say it to a friend?
+- What single thing should the reader believe after one screen?
+- What would make them believe it (a picture of the thing, a number, a name, a demonstration)?
+- What do they do next?
+
+Then list the page as claims, one per section, each with its proof:
+
+```
+1. It is a three-legged oak stool, made to order.             → the stool, large
+2. Each seat is cut from one board, so the grain is yours.    → three close-ups
+3. It takes six weeks, and you can follow it.                 → the stages, photographed
+4. It costs 240 and is delivered by the maker.                → price, button
+```
+
+A section with no claim is filler; delete it. This is also how you escape the stock order of
+hero, logos, features, testimonial, pricing, call to action: the order of the argument is the order of
+the page.
+
+## 2. The two-line headline
+
+A headline is a title. It is held in one glance. On the studied gallery sites the hero headline has a
+median of 5 words and 70% sit on one or two lines at desktop width. Every headline on your page, at
+every viewport, fits in **two lines or fewer**. `inspect.mjs` measures this at 1440, 768 and 390 pixels
+and fails the page otherwise.
+
+The constraint is arithmetic, so do it before you fall in love with a sentence:
+
+```
+characters per line ≈ line width in px ÷ (font size in px × k)
+
+k ≈ 0.40  condensed faces
+k ≈ 0.50  most grotesks and serifs at display size, tight tracking
+k ≈ 0.58  wide / extended faces, all-caps settings
+```
+
+| Where | Line width | Size | Per line | Two-line budget |
+| --- | --- | --- | --- | --- |
+| Phone 390, 20px gutters | 350px | 44px | ~16 | **~32 characters** |
+| Phone 390, 20px gutters | 350px | 34px | ~21 | ~42 characters |
+| Tablet 768 | 690px | 64px | ~22 | ~44 characters |
+| Desktop, 12-col measure | 1100px | 104px | ~21 | ~42 characters |
+| Desktop, half width | 620px | 72px | ~17 | ~34 characters |
+
+So a hero headline of **about 32 characters or fewer** (four to six words) survives everywhere at a
+confident size. Up to about 42 works if the phone size comes down to the mid-30s. Past that you are
+writing a sentence; move the rest into the supporting line.
+
+Controlling the break:
+
+- Give the headline a `max-width` in `ch` so it breaks where you intend, and add
+  `text-wrap: balance` so two lines come out even.
+- Where the break matters (it usually does), author it: `Stools for<br> small kitchens`. Check the
+  phone screenshot; if an authored line wraps there, hide the `<br>` under a breakpoint or shorten.
+- Never fix a long headline only by shrinking it. A timid 28px headline of nine words is worse than
+  five words at 64px.
+- Avoid a single orphan word on line two. Rebalance by cutting a word, not by nudging the width.
+
+Section headings follow the same rule and are shorter: two to five words.
+
+**A statement is not a headline.** An intro sentence or a quotation set large (the manifesto line
+after the hero, a testimonial) is a paragraph: mark it up as `<p>` or `<blockquote>`, keep it to about
+25 words, and set it at statement size, which the inspector takes as 36px or less on desktop, 32px on
+a tablet and 24px on a phone. It may then run to about three lines (four on a phone). Set larger than
+that, or marked up as a heading, or placed as the main line of the first screen, it is a headline and
+gets two lines. In blind judging, a sentence set big over three or more lines was read as a long
+headline every time, whatever its markup; if the words matter that much, cut them to a two-line
+headline instead.
+
+## 3. Headline shapes that work
+
+All seen repeatedly on the gallery sites. Pick the plainest one that is true.
+
+- **The name.** The brand or the person, set very large, with a one-line description elsewhere.
+  Strongest when the name is short and the subject is visual (studios, restaurants, hotels, people).
+- **What it is.** "A vinyl shelf in your pocket." "Furniture for small rooms." Category, stated with
+  one specific word.
+- **The claim.** "Your bank won't do this." One sentence a competitor could not sign.
+- **The instruction.** "Understand your money." Verb first, short.
+- **The place or the moment.** "Antarctica." "Lisbon, since 1984." For hospitality, events, travel.
+
+Shapes to avoid, because they are the average of every landing page:
+
+- The mad-lib: "The AI-powered platform for modern teams".
+- The tricolon: "Fast. Simple. Secure." or "Plan. Build. Ship."
+- The correction: "It's not just a tool, it's a workflow". Also "More than a …".
+- "X, reimagined / redefined / made simple". "Welcome to …". "Meet …" for a product nobody has met.
+- A question the reader did not ask.
+- A headline that needs its colon: "Ledgerly: invoicing for freelancers". Drop the name, it is in the
+  navigation.
+- One word of the headline styled differently (italic, serif, coloured, underlined, in a pill).
+
+Sentence case. No full stop unless the direction's voice uses them everywhere.
+
+## 4. Supporting line, body, buttons
+
+**Supporting line.** One sentence, at most about 22 words, that says concretely what the thing is and
+who it is for. It is where the detail cut from the headline goes. It never repeats the headline in
+other words.
+
+**Body.** Short paragraphs of plain statements. Prefer the specific noun and the real number: "ships
+in a week" over "fast delivery"; "38 seats" over "intimate". Read every sentence and ask whether a
+different company could print it unchanged; if so, sharpen it or cut it.
+
+**Buttons.** Name the action or the thing: "Book a table", "See the plans", "Download for Mac".
+One to three words. The primary action keeps one name everywhere on the page. One primary button per
+screen; a second action is a plain text link. No arrow glyph on every link and button; at most one
+arrow, on the primary action, if the direction uses arrows at all.
+
+**Navigation.** The wordmark, up to five plain links, one action. Link labels are single nouns.
+
+## 5. Proof without inventing it
+
+Never invent customers, quotes from named people, press logos, user counts, ratings or benchmarks.
+Invented proof is both dishonest and a recognised tell.
+
+When the brief supplies no proof, use what is true by construction:
+
+- Show the thing itself, large. A real demonstration outranks any quote.
+- State how it works, specifically.
+- Use facts from the brief (price, place, year, materials, what is included).
+- If a testimonial or logo section is explicitly requested and no real ones exist, build the section
+  with plainly fictional sample content and say so in your final report so it is replaced before
+  launch. Do not put real company names or real people in it.
+
+**Sample details are different from proof, and they are expected.** Where the brief gives the shape of
+the content but not every detail (six rooms "from €140", "a short menu", twelve speakers), write the
+full set of plausible details: each room with a name, a bed, a view and its own rate; each dish with
+its price; each speaker with a talk title. A design can only be judged at its real density, and a page
+that shows one rate where six rooms exist looks unfinished. List every sample detail in the report so
+the client confirms or replaces it.
+
+## 6. Things that read as generated
+
+`lint.mjs` flags most of these.
+
+- Verbs and adjectives of the genre: unlock, unleash, supercharge, elevate, empower, streamline,
+  seamless, effortless, robust, cutting-edge, next-generation, world-class, all-in-one, blazing fast.
+- Labels pretending to be editorial: "Field notes", "The details", "Our philosophy", "Quietly trusted
+  by". A section heading can simply be "Pricing".
+- Furniture text: locale or time strips, "Est. 2024", coordinates, version stamps, "Scroll", "(Scroll
+  to explore)", fake photo credits, status lines such as "Available for work" with a dot, strings of
+  words separated by middle dots or slashes.
+- The em dash as a habit. One or two on a page read as writing; ten read as a model. Use a full stop.
+- Explainer captions that narrate the design: "A clean, minimal layout for…".
+- Step labels that duplicate numbers: "Step 1", "Phase 02".
+- Three parallel items everywhere: three features, three stats, three steps. Use the number the
+  content has.
+
+## 7. Micro-typography
+
+- Curly quotes and apostrophes (“ ” ’), a real ellipsis (…), an en dash for ranges (9–5).
+- Non-breaking space between a number and its unit, and before the last short word of a headline
+  when it would otherwise orphan (`&nbsp;`).
+- `font-variant-numeric: tabular-nums` where numbers line up in columns (prices, tables).
+- `text-wrap: balance` on headings, `text-wrap: pretty` on paragraphs.
+- No all-caps for anything longer than three words; if you set caps, add 0.02–0.06em tracking.
+- No text under 13px. No centred paragraphs longer than three lines. No justified text.

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

@@ -0,0 +1,171 @@
+# Critique — judging the render
+
+`inspect.mjs` passing means nothing banned or broken was measured. It says nothing about whether the
+page is good. This file is how you find out. Use it on the screenshots, never on the code: you wrote
+the code, so you will read your intentions into it. The pictures only show what is there.
+
+## Contents
+
+1. How to look (fourteen passes, a few minutes)
+2. The score
+3. Caps
+4. Writing the critique
+5. What to fix first
+6. When to stop
+
+## 1. How to look
+
+Open `desktop-fold.jpg`, then the `desktop-page-*.jpg` sheets, then `mobile-fold.jpg` and the mobile
+sheets. Make each pass on its own; do not blend them.
+
+1. **One second.** Glance and look away. What did you see? There should be exactly one answer: a
+   word, an image, an object. If the answer is "a website", there is no focal point.
+2. **Squint.** Blur your attention until text becomes grey bars. The page should reduce to two or
+   three large masses with clear size differences. Many small similar masses means everything is
+   medium and nothing leads.
+3. **Cover the logo.** Could this first screen belong to a competitor, or to a different industry?
+   If swapping the name and the noun in the headline would produce an equally valid page, the page has
+   no idea. Go back to the direction sheet; the idea is written there. Then scroll: does the idea reach
+   the pricing, the FAQ and the footer, or does the page turn into stock blocks after the first screen?
+4. **Edges.** Follow the left edge of every text block down the page. Count the distinct x positions.
+   A composed page has two or three, reused on purpose. Six means things were placed one at a time.
+5. **Space.** Are related things close and unrelated things far? Is the gap between sections clearly
+   larger than any gap inside a section? Is any region empty by accident (a hole) rather than by
+   decision (a rest)? A hole usually sits beside a short column or under a removed decoration.
+6. **Type.** Is the jump from body text to headline decisive (three times or more)? Do you see more
+   than five sizes? Any headline with one orphan word on its last line? Any paragraph wider than about
+   75 characters or centred over more than three lines?
+7. **Colour.** Name the proportions: which colour holds most of the surface, which supports, where is
+   the accent? An accent that appears in ten places means nothing. One that appears on the single
+   action and one detail means "here".
+8. **Images.** Count the real pictures: are there at least four, and is there a moving one? A page of
+   drawings only, or of type only, looks unfinished next to one with real photographs and footage.
+   Is every image doing a job (showing the thing, setting the place, proving the claim)?
+   Do the crops share ratios? Is anything a grey box, a stretched photo, a fake screen made of bars?
+   Does the photography share one light and one grade, or is it a stock mix?
+9. **Sameness.** Write one word for each section's layout (split, list, full-bleed, grid, statement,
+   index …). The same word twice in a row, or three times on the page, is the template showing.
+10. **Phone.** Is the mobile screen a composition of its own, with its own crop and its own line
+    breaks, or the desktop page squeezed? Is the first screen still one clear thing?
+11. **Fullness.** Go through the desktop sheets screen by screen. Is each screen a composed poster, or
+    is it a narrow column of small text with dead ground either side? Is any statement held on screen
+    for three screens? An austere page is not a restrained one: if the page could be mistaken for an
+    unfinished wireframe (grey shapes, grey text, one small column), it is underbuilt. A single motif or
+    drawing blown up to fill a whole screen with nothing to read is a hole too, however bold it looks.
+12. **Substance.** Does every section the brief asked for deliver its information completely and at a
+    readable size (the full menu, each room, every speaker, the price and what it includes)? Would the
+    visitor leave knowing what they came to find out? Is the primary action a real button on the first
+    screen?
+13. **Collisions.** Is anything lying on top of a headline, a statement or a button at any scroll
+    position? Does any element run off the edge of the phone screen? A row that scrolls sideways on
+    the phone reads as cut off in a screenshot and to most visitors; wrap it unless the cut is
+    plainly deliberate (a partial card showing at the edge).
+14. **The competitor and the live thing.** Put the nearest competitor's name on the page: does the
+    idea still work? Then name the one live thing (what the visitor can do or what differs each visit).
+    If either answer is weak, that is the first problem of the round, ahead of any detail.
+
+A note from testing: in blind comparisons a richer page full of template devices beat a cleaner page
+that was thin, every time. The house rules remove the devices; passes 11–13 are where you make sure the
+page did not lose its substance with them.
+
+## 2. The score
+
+Score like an Awwwards juror: four criteria, 1–10 each, weighted **design 40%, usability 30%,
+creativity 20%, content 10%**.
+
+**Design (40%)** — composition, typography, colour, imagery, craft.
+- 9–10: every screen holds as a poster. Nothing could be removed or moved.
+- 8: confident and coherent; one or two soft spots a designer would notice.
+- 7: clean and professional, a clear system, little tension.
+- 6: tidy but anonymous. Reads as a kit.
+- 5 or less: weak hierarchy, accidental spacing, default type, mismatched images.
+
+**Usability (30%)** — orientation in three seconds, readable text, obvious actions, honest mobile.
+- 9–10: you know what it is, who it is for and what to do without scrolling; flawless on a phone.
+- 8: clear and comfortable; minor friction (a long section, a small target).
+- 7: works, with one real problem (weak contrast somewhere, a cramped phone layout).
+- 6 or less: you have to hunt, or something breaks.
+
+**Creativity (20%)** — an idea you can state in a sentence, carried through.
+- 9–10: a concept specific to this subject that you have not seen applied this way.
+- 8: a clear idea with one memorable move.
+- 7: a tasteful execution of a known approach.
+- 6 or less: the category default.
+
+**Content (10%)** — words and pictures that are specific, true-sounding and edited.
+- 9–10: every line could only be about this subject; imagery is the subject.
+- 7–8: clear and concrete, some generic lines.
+- 6 or less: slogans, filler, stock.
+
+`overall = 0.4·design + 0.3·usability + 0.2·creativity + 0.1·content`
+
+For calibration: real Sites of the Day land around 7.5–8.0 overall from the jury. An honest 8.5 is
+rare. If your first score for your own work is 9, score it again as the juror who did not build it.
+
+## 3. Caps
+
+These override the arithmetic.
+
+- Any `FAIL` still reported by `inspect.mjs`: overall cannot exceed **6.0**.
+- A headline of three or more lines at any viewport, an eyebrow label, monospace labels, 01/02/03
+  numbering, a decorative gradient, a shadow on a resting element, or a decorative hairline visible in
+  a screenshot: overall cannot exceed **6.5**, whatever else is true.
+- Pass 3 fails (the page could belong to anyone): creativity cannot exceed **6**.
+- The idea passes for the nearest competitor (pass 14): creativity cannot exceed **7**.
+- Fewer than four real pictures (photographs, archival images, footage; drawings do not count):
+  design cannot exceed **6.5**.
+- A page that barely moves (the inspector's `still-page`), or motion that is one identical fade on
+  every block: design cannot exceed **7**.
+- No live thing (pass 14): creativity cannot exceed **7.5**.
+- Any placeholder (grey box, lorem, "Image here"): content cannot exceed **5**.
+- Two or more desktop screens that are mostly empty ground, or a page whose running text is small and
+  grey: design cannot exceed **6.5**.
+- A section the brief asked for that is missing or reduced to a few words: content cannot exceed **6**.
+- No real button for the primary action on the first screen: usability cannot exceed **7**.
+- Anything covering a headline at any scroll position: usability cannot exceed **6**.
+- A blank band where a reveal did not fire, or content clipped off-screen: usability cannot exceed **5**.
+
+## 4. Writing the critique
+
+Write it down; do not just think it. Use exactly this shape so rounds can be compared:
+
+```
+ROUND n
+Seen in one second: …
+Idea (one sentence): …
+Live thing: …
+Layout words by section: hero=… / …=… / …
+Scores: design _ · usability _ · creativity _ · content _ → overall _._
+Caps applied: …
+Top three problems (most visible first), each with the screenshot it shows in and the fix:
+1. …
+2. …
+3. …
+```
+
+Name problems the way a designer would to a colleague: "the supporting paragraph starts 40px left of
+the headline's edge", "the testimonial section is the third split layout in a row", "the phone hero
+crops the bottle out of frame". "Could be more polished" is not a finding.
+
+## 5. What to fix first
+
+Fix in this order; later items cannot rescue earlier ones.
+
+1. **The idea.** If pass 3 fails, change the hero concept, not the details.
+2. **Hierarchy.** One dominant element per screen. Make the big thing bigger and the small things
+   fewer before touching anything else.
+3. **Composition.** Shared edges, section spacing, variety of layout between sections, holes.
+4. **Typography.** Scale contrast, line breaks, measure, leading.
+5. **Imagery.** Replace weak pictures, unify crops and grade.
+6. **Colour.** Proportion and accent discipline.
+7. **Detail.** States, focus, small alignments, mobile refinements.
+8. **Motion.** Last.
+
+When removing something leaves a gap, do not refill it with an ornament. Close the gap, enlarge what
+remains, or let a picture or a colour field take the space.
+
+## 6. When to stop
+
+Run at most three rounds: critique → fix the top three → re-inspect → critique. Stop early when a round
+finds no problem a stranger would notice. If round three still scores under 7.5, say so plainly in
+your report, with the remaining problems listed; do not round up.