@palate/cli 0.0.0-stage → 0.0.1

package/kb/craft/principles.md

@@ -0,0 +1,68 @@
+---
+title: Core principles (alignment, hierarchy, spacing, type, consistency, Gestalt, density)
+---
+
+# Core principles, measured where possible
+
+How to use: each item says how to detect it on a screenshot and in the DOM. Items marked **Measured** are checked by palate's `page-principles.js` (`src/principles.mjs` prints them as `[Pxx]` findings with a CSS path, a text snippet and a box). Treat a measured finding as a lead, not a verdict: open the crop and confirm it before you report it, and say when the page breaks a rule on purpose. Items without that mark need your eye.
+
+## Alignment
+
+- **[P01] Shared edges, no near misses.** **Measured:** left and right edges of text, controls, pictures and cards are clustered per section and across the page; an edge 1–6px off a line that 3+ items share is a near miss. On a screenshot, drop a vertical guide down the content's left edge and look for things that almost touch it. A 2–5px miss reads as a mistake, not a choice; on-grid alignment is what makes a page look built rather than placed. Fix: put the item on the shared edge by matching the container's padding or max-width, never with a nudge (`margin-left: 3px`). Large display type nudged left by its side bearing is optical alignment and is fine. (Source: https://www.nngroup.com/articles/using-grids-in-interface-designs/)
+- **[P02] Few alignment lines.** **Measured (as a fact):** the number of distinct left edges per section. Count the vertical lines your eye can find; every extra one is another thing to scan. Grid columns legitimately add lines, so judge the count against the layout. Fix: snap content to the content column, the grid columns and at most one indent. (Source: https://www.nngroup.com/articles/principles-visual-design/)
+- **[P03] One alignment per stack.** **Measured:** a centred block stacked directly above or below a left-aligned block in the same column. Mixed axes make the eye restart at a different place for each line. Centred multi-line text also has a ragged left edge, which is hard to read. Fix: left-align anything longer than two lines; centre only short lockups (a headline and its button), and centre the whole lockup, not half of it. (Source: https://practicaltypography.com/centered-text.html, https://www.nngroup.com/articles/horizontal-attention-leans-left/)
+- **[P04] Grid items start together.** **Measured:** rows of like items (cards, columns) whose tops, first lines or second lines start at different heights, and cards in one row with different heights. Ragged starts break the row into separate objects. Typical causes are an icon in some cards but not others, titles that wrap to different line counts, or `align-items: center` on a card row. Fix: same lead-in slot in every item, one-line titles (or a fixed title height), `align-items: stretch` with full-height cards. (Source: https://www.nngroup.com/articles/using-grids-in-interface-designs/)
+- **[P05] Optical over mathematical.** Eye only. Play icons, quotation marks, round shapes and icons next to text often look off when they are mathematically centred. Fix: hang punctuation into the margin, nudge triangular icons right, and align icon centres with the text's x-height, not its line box. (Source: https://vercel.com/design/guidelines)
+
+## Visual hierarchy
+
+- **[P06] The heading leads.** **Measured:** text, filled buttons and controls are ranked by visual weight (size × √(weight/400) × a contrast factor, with a boost for filled buttons). The page's single `<h1>` should be the heaviest thing on the first screen, and each section's heading the heaviest in its section. Squint at the screenshot: the first thing you see should be the thing the section is about. Fix: raise the heading's size or weight, or quiet the rival (smaller, lighter, lower contrast). Keep one `<h1>` per page. (Source: https://www.nngroup.com/articles/visual-hierarchy-ux-definition/)
+- **[P07] Steps you can see.** **Measured:** the ratio between the heading and the text directly under it, plus headline : subhead : body sizes. Under about ×1.2 (same weight, same colour), the levels blur together. Over about ×4.5 straight onto 16px text, the small text reads as a caption. Fix: separate levels by ×1.25 or more in size, or by two weight steps, or by a clearly quieter colour. Add a lead paragraph between a huge headline and small body text. (Source: https://m3.material.io/styles/typography/type-scale-tokens, https://www.refactoringui.com/)
+- **[P08] One focal point per view.** **Measured:** the distinct things within 15% of the top weight (one repeated style counts once), and elements as heavy as the section heading. Several equal focal points make the eye bounce, and nothing gets read first. Fix: pick the one thing, step the others down a size or a weight. A row of equal stats or titles is fine under a heading that clearly leads it. (Source: https://www.nngroup.com/articles/visual-hierarchy-ux-definition/)
+- **[P09] One primary action.** **Measured:** buttons that sit side by side are ranked by area and fill contrast. Two buttons of equal weight force a choice the design should have made. Parallel choices (download for Mac or for Windows, filter chips, icon links) are exempt. Fix: fill the primary with the accent; make the rest outline or text buttons; put the primary first. The hero's primary should outweigh the header's button. (Source: https://developer.apple.com/design/human-interface-guidelines/buttons)
+- **[P10] De-emphasise with colour and weight, not only size.** Eye and DOM: secondary text should step down in colour (about 3 text greys: primary, secondary, tertiary) before it steps down to tiny sizes. Making everything smaller to create hierarchy ends in 11px grey text no one can read. Fix: keep secondary text at a readable size, set it in the secondary text colour, and make the important item heavier instead. (Source: https://www.refactoringui.com/, https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
+- **[P11] Squint test.** Screenshot: blur or squint at the page at 25% zoom. You should still see the headline, the primary action and the section rhythm; if it all turns into an even grey, the hierarchy depends on reading. Fix: increase contrast between levels (size, weight, colour, space), not decoration. (Source: https://www.nngroup.com/articles/principles-visual-design/)
+
+## Spacing and proximity
+
+- **[P12] One spacing scale.** **Measured:** every padding, margin and gap value; the base unit (8, 4 or 2px) and the share of values off a 4px scale (half-steps under 12px allowed; fractional em or fluid values reported separately). Random values (13, 18, 22, 30px) make rhythm feel accidental, even when no single gap looks wrong. Fix: use one scale (4, 8, 12, 16, 24, 32, 48, 64, 96, 128) and round every value to it. (Source: https://m2.material.io/design/layout/spacing-methods.html, https://spec.fm/specifics/8-pt-grid)
+- **[P13] Closer to what it labels.** **Measured:** a heading, label or field label whose gap to the content above is no larger than its gap to the content it introduces. By the law of proximity, items close together are read as one group, so an evenly spaced heading belongs to nobody. Fix: put clearly more space above a heading than below it (about 2:1), and keep labels tight to their fields. (Source: https://www.nngroup.com/articles/gestalt-proximity/)
+- **[P14] Steady section rhythm.** **Measured:** where content starts and ends in each section, and the space between sections' content. Uneven section gaps feel like a missing or extra block. Fix: use one or two section spacings (e.g. 96 and 128px on desktop), set by section role, not case by case. (Source: https://m3.material.io/foundations/layout/understanding-layout/spacing)
+- **[P15] Inside smaller than between.** Eye and DOM: inside a card or group, the gaps between its parts should be smaller than the card's padding, and the padding smaller than the gap between cards. If a card's inner gap equals the gap between cards, the cards stop reading as units. Fix: tight inside (8–12px), comfortable padding (16–24px), clear outside (24–32px). (Source: https://www.nngroup.com/articles/gestalt-proximity/, https://www.refactoringui.com/)
+- **[P16] Start with too much space.** Screenshot: crowded pages usually have too little space around groups, not too much inside them. Removing space until it looks right gives better results than adding it until nothing touches. Fix: double the space between groups, then tighten where it falls apart. (Source: https://www.refactoringui.com/)
+
+## Sizing and type
+
+- **[P17] Comfortable measure.** **Measured:** characters per line of body paragraphs (13–24px text, 3+ lines) on desktop. Lines over about 85 characters lose the reader at the line break; under 35 they break too often. Fix: `max-width: 65ch` on paragraphs (45–75 characters). (Source: https://practicaltypography.com/line-length.html)
+- **[P18] Leading by size.** **Measured:** line-height ÷ font-size on wrapped text: body 1.35–1.8, small headings 1.0–1.6, display (32px+) 0.9–1.3. Tight body text is dense to read; display type at body leading drifts apart. Fix: body around 1.5, headings 1.1–1.25, display 1.0–1.1. (Source: https://practicaltypography.com/line-spacing.html)
+- **[P19] Few weights.** **Measured:** distinct font weights in use. More than about four weights look unplanned and dilute emphasis. Fix: two or three weights (e.g. 400, 500, 600); build the rest of the hierarchy with size and colour. (Source: https://practicaltypography.com/bold-or-italic.html)
+- **[P20] Tight large type.** **Measured:** positive letter-spacing on text of 28px or more that is not in capitals. Fonts are spaced for text sizes, so large sizes look loose by default and looser still with tracking added. Fix: 0 to −0.03em on display sizes; tighten more as size grows. (Source: https://practicaltypography.com/letterspacing.html)
+- **[P21] Track all caps.** **Measured:** uppercase labels of 20px or less with under 0.03em letter-spacing. Capitals set at default spacing look cramped and are slower to read. Fix: 0.05–0.12em letter-spacing on caps, and keep caps to short labels. (Source: https://practicaltypography.com/all-caps.html)
+- **[P22] A real type scale.** **Measured:** distinct sizes and the share that fit one ratio from the body size. Many unrelated sizes mean no system; a ratio (×1.2, ×1.25, ×1.333) makes steps feel related. Fix: five to seven sizes on one ratio, each mapped to a role (display, h1, h2, body, small, caption). (Source: https://m3.material.io/styles/typography/type-scale-tokens, https://alistapart.com/article/more-meaningful-typography/)
+- **[P23] Short headings.** **Measured:** `h1`–`h3` over 12 words. A heading is scanned, not read; past about ten words it turns into a paragraph set large. Fix: cut to under ten words and move the rest into the paragraph below. A deliberate statement paragraph set large is a style choice; say so instead of flagging it. (Source: https://practicaltypography.com/headings.html)
+- **[P24] No widows in headings.** **Measured:** headings whose last line is a single word. A lone word on the last line makes the shape look accidental and the line break meaningless. Fix: `text-wrap: balance` on headings (and `pretty` on paragraphs), or rewrite to fit. (Source: https://practicaltypography.com/widow-and-orphan-control.html, https://developer.mozilla.org/en-US/docs/Web/CSS/text-wrap)
+- **[P25] Tabular numbers in data.** DOM: columns of numbers, prices, timers and counters without `font-variant-numeric: tabular-nums`. Proportional digits shift as values change and misalign in columns. Fix: tabular figures for numbers that are compared or that update; never on prose. (Source: https://vercel.com/design/guidelines)
+- **[P26] Sizes far enough apart.** **Measured:** two sizes within 8% of each other both in use (13 and 14px, 15 and 16px). The eye cannot tell them apart, so the difference reads as an error. Fix: merge them, or separate them by ×1.15 or more. (Source: https://practicaltypography.com/point-size.html)
+
+## Consistency
+
+- **[P27] A radius scale, nested concentrically.** **Measured:** distinct corner radii, and nested surfaces whose inner radius is larger than outer radius − padding. A handful of near-equal radii looks unplanned; an inner corner as round as the outer one, set inside padding, makes the gap between the curves uneven. Fix: two or three radii (e.g. 6, 12, pill); inner radius = outer radius − padding (nearly square when the padding is larger than the outer radius). (Source: https://vercel.com/design/guidelines, https://m3.material.io/styles/shape/corner-radius-scale)
+- **[P28] One border colour.** **Measured:** distinct box-border colour and width pairs. Borders in several near-identical greys make the same divider look like different things. Fix: one border token for surfaces and one stronger token for inputs; crisp 1px borders. (Source: https://vercel.com/design/guidelines)
+- **[P29] Few elevations.** **Measured:** distinct box-shadow values (empty Tailwind ring layers ignored). Every unique shadow is a new height for the eye to place. Fix: two or three elevation levels (resting card, raised menu, modal), each a layered shadow, used everywhere. (Source: https://m3.material.io/styles/elevation/overview)
+- **[P30] Colours as tokens.** **Measured:** distinct colours by area, and near-duplicates within 5 per channel (#f4f4f4 vs #f5f5f5). Near-duplicates are leftovers from copy-paste and drift into visible seams on adjacent surfaces. Fix: collapse each pair into one token; name colours by role (surface, border, text-secondary, accent). (Source: https://m3.material.io/styles/color/roles)
+- **[P31] One accent, used sparingly.** **Measured:** chromatic hue families covering 0.5%+ of the page, and the accent's share. A second or third accent hue makes nothing the obvious next step; an accent covering much of the page stops meaning "act here". Fix: one accent for the primary action, links and focus (around a tenth of the surface at most); everything else neutral. (Source: https://developer.apple.com/design/human-interface-guidelines/color, https://www.refactoringui.com/)
+- **[P32] One component, one style.** **Measured:** button, card and input styles (fill, border, radius, height, font, padding), and pairs of styles that differ by one small value (40 vs 42px tall, 12 vs 14px radius). Near-identical variants are almost always accidents and make the system look untended. Fix: primary, secondary and ghost buttons at one or two sizes; one card surface; one input style. (Source: https://anthonyhobday.com/sideprojects/saferules/)
+
+## Gestalt
+
+- **[P33] Similarity means sameness.** Screenshot: things that look alike are read as alike. A link styled like body text, or two different actions styled the same, misleads. Fix: give each kind of thing one look, and give different kinds different looks. (Source: https://www.nngroup.com/articles/gestalt-similarity/)
+- **[P34] Common region groups.** Screenshot and DOM: a shared background or border groups its contents more strongly than spacing does. Boxes around everything flatten that signal; a group split across two boxes breaks it. Fix: use a container only where grouping is not already clear from space, and never split one group across two containers. (Source: https://www.nngroup.com/articles/common-region/)
+- **[P35] Continuity along edges.** Screenshot: the eye follows a shared edge or line from one block to the next; a column that starts at a new x on every row breaks the path. Fix: keep reading paths straight (one left edge per column, rows on one baseline). (Source: https://www.nngroup.com/articles/using-grids-in-interface-designs/)
+- **[P36] Clear figure and ground.** Screenshot: text and controls must separate from what is behind them. Text on photos, busy gradients or low-contrast tints sinks into the background. Fix: solid or scrimmed backgrounds behind text, contrast at least 4.5:1 for body and 3:1 for large text and controls. (Source: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html, https://www.nngroup.com/articles/principles-visual-design/)
+
+## Density
+
+- **[P37] Balanced density.** **Measured:** the share of each section covered by text, controls and pictures, compared with the page's typical section. A section much emptier than the rest feels unfinished; one much denser feels like a different product. Fix: shorten the empty section or give it content that earns the space; give the dense one more padding or fewer items per row. The right density depends on the job: dashboards run denser than landing pages. (Source: https://m2.material.io/design/layout/applying-density.html)
+- **[P38] No holes.** **Measured:** the tallest band inside a section with nothing in it, and sections with no measurable content at all. A tall blank usually means something failed to render (a lazy image, an animation that never ran, WebGL) or a scroll-pinned sequence that only works while scrolling. Fix: check the screenshot, then close the gap or fix what failed. (Source: https://developer.apple.com/design/human-interface-guidelines/layout)
+- **[P39] Use the width you have.** Screenshot and the `palate shoot` content-span number: on a 1440px screen, a page whose content spans under about half the width looks like a phone layout floating in space. Fix: widen the grid (a 1200–1280px container), add a second column, or let pictures go wider than the text column. (Source: https://developer.apple.com/design/human-interface-guidelines/layout)
+- **[P40] Product UI shown is judged as a picture.** **Measured:** framed regions full of small text (app windows, widgets, issue lists) are detected as mockups and left out of the page's type, button and grid checks. Judge a mockup on legibility at 100% and on whether it shows the product doing its job, not on its internal spacing. Fix: if its text is unreadable at 100%, crop to the part that matters and scale it up. (Source: https://vercel.com/design/guidelines)