@erclx/canon 4.90.0 → 4.92.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.90.0",
+  "version": "4.92.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/design-taste/REQUIREMENT.md

@@ -0,0 +1,78 @@
+---
+name: design-taste
+description: Why a design round needs a stated layer ordering and a taste catalog, and why neither half works without the other
+---
+
+# Design taste requirement
+
+## Gap
+
+Without this skill, a design round has no vocabulary to declare what it is varying and no standard of quality once it has. Both halves failed together and each is measured.
+
+The failure was measured on a real page. Four `draft-and-pick` rounds ran against one landing page in a single working session, and three changed nothing the operator could see. Each varied a property at Surface, being palette, figure treatment, heading separation and underline reach, against a page whose defect sat at composition.
+
+The instruction against that already existed. `draft-and-pick` Step 1 says to name the layer and Step 2 says a palette cannot be picked ahead of a composition. All four rounds skipped both, and nothing reported it. A session told to name a layer has no catalog to name from, so the rule had nothing behind it.
+
+The second half is the output itself. A model with no stated direction draws the population average of its training data, which produces interfaces that satisfy every craft rule and still read templated.
+
+Prose is already governed in two halves and design is governed in neither. Banned words ship as data a command reads, and the shapes no closed word set can match needed a skill of their own, because each is a pattern rather than a token. `standards/design.md` governs the shape of a project's design document and is silent on whether its values are any good.
+
+Importing an external catalog wholesale fails on what those catalogs turn out to carry. The largest is 1,206 lines in one file, pinned to one framework, one styling library and one animation package, and it scopes itself out of dashboards, data tables and multi-step product UI. A second bans default fonts by name and prescribes a component library.
+
+A session handed either one unfiltered adopts a stack the project does not use, or silently ignores the item. No later reader can tell which happened, which is why the adopted-and-declined record exists.
+
+## Must
+
+- Require a declared read in the output before any candidate is authored, naming the kind, the audience, the overriding constraint and the layer, since a layer named privately is a layer nobody can check
+- Enumerate the layers in settle order, so an instruction to name one has a catalog behind it
+- State that a round varies one layer, and that a complaint is worked at the lowest layer it reaches rather than the cheapest one to change
+- Carry grey-boxing as the operational form of the ordering rule, since removing the higher layers from view is what makes a lower one judgeable
+- Cite the correctness floor rather than restating it. `400-ui`, `410-a11y`, `420-forms` and `430-ux-completeness` already carry accessibility, keyboard, forms, states and rendered copy on the rendered paths, and a second copy here drifts with nothing comparing the two.
+- Hold in the body what every design moment pays for, being the read, the layers, the ordering, grey-boxing and the locks, and defer everything a single moment needs.
+- State what has to stay constant across a whole surface, since coherence is a property of the whole and each of those is broken one section at a time.
+- Detect the mode before reading anything when a surface already exists, and name what cannot change silently, since a slug, a field name or an analytics event breaks something outside the surface.
+- Carry a final filter the session runs against its own output, with every item tracing to a rule stated here, since an unenforced rule and an unchecked one fail the same way.
+- Name the machine defaults as a catalog of shapes with replacements, held behind a stated trigger so a round that needs none pays no read
+- Record which external patterns were adopted, which declined, and the measurement behind each, so a later session extends the position instead of re-deriving it
+- Stay general-purpose across kinds, naming what a kind optimizes for rather than which packages to install
+- Say when a read names a kind the references do not cover, rather than inventing guidance for it
+
+## What earns a place
+
+A rule belongs in this skill only when all four hold. Three of the four reject most design advice, which is the point: a criterion admitting everything is not a criterion.
+
+1. **An unguided model gets it wrong.** The model already knows a control needs padding, so writing that down costs a read and buys nothing. It does not know to avoid three equal cards. Only the second kind earns a line.
+2. **Nothing else owns it.** A `ui` rule, a standard, or a sibling skill owning the topic makes this a pointer rather than a rule.
+3. **It is judgment rather than a threshold.** A contrast ratio has a number and belongs to the floor. Whether a palette reads cheap has no number and belongs here.
+4. **One line states it, and something could violate that line.** "Use whitespace intentionally" fails, since nothing could break it. "No three consecutive image-and-text splits" passes, since it can be counted.
+
+A rule failing any of the four is recorded as considered and declined rather than argued again, in the reference where it would have gone.
+
+## Must not
+
+- Name a framework, a styling library, an animation package, a component library or an icon set as a default. A rule that survives only inside one stack is not a taste rule.
+- Ship a frozen corpus of palettes, font pairings or product examples. A copy becomes a file some sync reconciles forever, and a traced reference is current by construction where a frozen one is not.
+- Restate the banned words, characters or spellings, which `markdown.md` states and `canon markdown audit` gates from package data
+- Express intensity as a numeric scale. A session picks a middle value and reports compliance, which satisfies the rule and decides nothing.
+- Claim the reported failure is closed. Nothing measures whether a round follows these rules, so this skill states them and the measurement is owed separately.
+- Duplicate a rule a surface already states for itself, such as slide layout or terminal color, where pointing at that surface is the whole of the correct answer
+- Be reached only by an author typing its name. `standards/skill.md` makes this a review criterion rather than a check, since nothing answers it before the skill has run. The intended non-author caller is the declared read in `draft-and-pick`'s output. A round producing no read, with this skill never loaded, is the evidence that the description's triggers are too weak.
+
+## Guards
+
+- A kind with no per-kind guidance gets the body's rules and a stated absence, never invented guidance
+- A grey-boxed set is announced as grey-boxed, since an unannounced grey page reads as unfinished work rather than as the question being asked
+- Accessibility and the state set outrank an aesthetic preference wherever the two collide, rather than being traded against it
+
+## Out of scope
+
+- Accessibility, keyboard interaction, ARIA and alt text, which `410-a11y` owns on every rendered path
+- State coverage, empty and loading treatment, destructive confirmation and truncation, which `430-ux-completeness` owns
+- Validation timing, error placement and save blocking, which `420-forms` owns
+- Rendered copy casing, button labels and error wording, which `400-ui` owns
+- The candidate loop, the arm set, the render and the pick, which `draft-and-pick` owns and which this skill is loaded alongside rather than inside
+- Tracing a reference's color, type and spacing values, which is `sketch-design`
+- The shape of the project's design document, its sections and its token tables, which `standards/design.md` governs
+- Spatial layout and interaction intent of one named surface, which `standards/wireframes.md` governs
+- Prose on the surface being designed, which `write-human` and `markdown.md` govern between them
+- Measuring whether finished output followed these rules, which needs a check this skill does not carry and which no command reaches while a render is an image rather than a parse

package/claude/skills/design-taste/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: design-taste
+description: Carries the layer model that decides which design decision settles first, the rules that keep a surface coherent across sections, and the catalog of defaults a model reaches for when nothing states a direction. Use when drafting or judging an interface, a page, or any rendered surface, when output reads generic or templated, when redesigning something that already exists, or when asked to "make this look designed", "why does this look like AI made it", "give it taste", "what layer is this decision at", or "grey-box this first". Do NOT use for accessibility, forms, or state coverage, which the `ui` governance rules carry, for the shape of the project's design document, which `design.md` governs, to run the candidate loop, which is `draft-and-pick`, or to trace a reference's values, which is `sketch-design`.
+---
+
+# Design taste
+
+A model with no stated direction draws the population average of what it has seen. That is why unguided design output reads as templated while satisfying every rule of craft it was given, and it is why adding more craft rules does not fix it. This skill carries the direction: where a decision sits, what settles before it, and which defaults to reach past.
+
+Load this before drafting rather than after. A revision pass recovers a color and never recovers the composition the draft already settled.
+
+Skip it for work that does not change how something looks, feels, moves, or is interacted with.
+
+## The defaults you are reaching past
+
+This is what the population average looks like. Each one is what gets drawn when nothing states otherwise, and each is recognizable on sight:
+
+- Three equal cards in a row under a heading.
+- A centered headline over a dark gradient wash, with two buttons under it.
+- A violet-to-blue gradient used as the accent.
+- Numbered labels above sections: `001 / Capabilities`, `Phase 02`, `Step 1`.
+- A scroll cue at the bottom of the first screen.
+- A colored dot before every navigation item, row or badge.
+- A glow standing in for elevation, on a pure black or pure white ground.
+- A product screenshot built out of styled rectangles.
+- Placeholder that announces itself: `Acme`, a stock person name, 99.9%, one portrait used twice.
+- Verbs chosen for warmth rather than for meaning, of the `elevate` and `unleash` family.
+
+Reaching past a default means choosing something else on purpose, not avoiding the word. A brief that genuinely calls for one of these gets it, and the difference is that somebody decided.
+
+`${CLAUDE_SKILL_DIR}/references/tells.md` holds the full catalog, of which these ten are the most common. Read it on the trigger stated below rather than now.
+
+## Declare the read
+
+State one line before authoring any candidate, page, or component, and put it in the output rather than holding it privately. Where the surface already exists, name the mode first, since the mode decides how much of the read is yours to set:
+
+> Reading this as: `<kind>` for `<audience>`, `<the constraint that overrides taste>`, working at `<layer>`.
+
+Two worked examples:
+
+> Reading this as: an application surface for an operator who already knows the domain, density beats first impression, working at composition.
+
+> Reading this as: a marketing page for a stranger who has never run the tool, every claim must be a thing the tool did, working at content.
+
+The read fixes the kind, which decides which rules apply, and names the layer, which decides what may vary. A round that cannot state its read has not decided what it is doing.
+
+Put the read to the operator through the structured question surface where it genuinely forks, per `005-behavior`. Where context settles it, declare and proceed rather than asking.
+
+## The layers, and the order they settle
+
+A lower layer constrains every layer above it. Two consequences follow, they run in opposite directions, and collapsing them is the mistake worth avoiding.
+
+Settling a higher layer over a broken lower one changes nothing, which is why a palette round against a broken composition is wasted. Judging a lower layer through a finished higher one is nearly impossible, which is why grey-boxing works.
+
+The model is Jesse James Garrett's five planes from _The Elements of User Experience_ (2000), subdivided to the granularity a drafting round works at.
+
+| Order | Layer       | The question it answers                                                    |
+| ----- | ----------- | -------------------------------------------------------------------------- |
+| 1     | Content     | What is actually here, and what does it say                                |
+| 2     | Composition | Which sections exist, in what order, carrying what relative weight         |
+| 3     | Layout      | How a section divides its space: grid, columns, alignment, container width |
+| 4     | Space       | Rhythm and proximity, meaning what groups with what                        |
+| 5     | Typography  | Scale, weight, measure, casing, pairing                                    |
+| 6     | Surface     | Elevation, border, radius, fill, depth                                     |
+| 7     | Palette     | Ground, accent, saturation, contrast                                       |
+| 8     | Imagery     | What a picture carries, and where it sits                                  |
+| 9     | Motion      | What moves, why, and how far                                               |
+
+### What follows from the order
+
+- Work at the lowest layer the complaint reaches. A complaint is voiced at the layer a person can name and usually lives lower. "It feels gloomy" reads as palette and is frequently composition, since a page with one section shape reads flat whatever color it is.
+- A round varies one layer and says which. Varying three answers nothing, because the pick cannot say which difference decided it.
+- Never settle a higher layer before the one below it. Imagery and palette are the one pair that settle together, since a real photograph sets a ground rather than accepting one.
+- Content leads the order and is frequently absent when drafting starts. Draft against real copy where it exists, stand in for it where it does not, and treat the composition as unsettled until real copy has run through it.
+- Name the layer the complaint sits at, then check the layers below are settled. Where one is not, that is the round, and say so rather than drafting the requested one.
+
+## Grey-box when judging layers 1 to 4
+
+Judging content, composition, layout or space through a finished surface is the failure the ordering exists to prevent. Remove the higher layers from view instead:
+
+- Draw every element as a flat neutral block with no fill variation, no accent color, no imagery, no motion.
+- Keep real text at real length. Placeholder text hides whether the composition survives the copy it will carry, so greek only what does not exist yet and never what does.
+- Mark a region with no content yet as FPO at its true size, so nobody reads a placeholder as a decision.
+- Return to the finished surface once the layer under judgment is settled. A grey-box is a stage, not a deliverable.
+
+Say when a set is grey-boxed and why. An operator meeting an unannounced grey page reads it as unfinished work rather than as the question being asked.
+
+## Lock what must not vary across a surface
+
+Coherence is a property of the whole and every one of these is broken one section at a time:
+
+- **One accent.** Chosen once, used everywhere. A warm-grey surface does not grow a blue action in its seventh section.
+- **One radius system.** Mixed radii are allowed only under a stated rule applied everywhere, such as pill actions over square containers.
+- **One theme.** No inverted section dropped between its neighbors. A reader must not feel they walked into a different product mid-scroll.
+- **One copy register.** Technical, editorial and promotional voices do not mix in one composition unless the brand states that they do.
+- **One light source.** Every shadow on the surface falls the same way, and a shadow is tinted toward the ground rather than pure black.
+
+## Working on something that already exists
+
+Name the mode before reading anything, since misclassifying it is the largest source of bad redesign work:
+
+- **Greenfield:** nothing rendered yet, or a full replacement is agreed.
+- **Preserve:** modernize without breaking the brand. Extract what exists before proposing anything.
+- **Overhaul:** new visual language over existing content and structure.
+
+Apply the cheapest lever that satisfies the brief, in this order: typography, then space and rhythm, then color recalibration, then motion, then recomposing key sections, then replacing a block outright.
+
+Never change these without saying so and getting agreement, because each one breaks something outside the surface: URL and route slugs, primary navigation labels, form field names and their order, the logo, and legal or consent copy.
+
+## Setting up the scales
+
+Read `${CLAUDE_SKILL_DIR}/references/systems.md` when establishing or revising what a surface draws from, being the space scale, the type scale, and the relationships a palette holds. Every other reference here is read against a draft. That one is read before there is one, so a project reaches for it at the start and on a system revision rather than on an ordinary round.
+
+It states no values. A value belongs to the project's own design document.
+
+## The rest of the catalog
+
+Read `${CLAUDE_SKILL_DIR}/references/tells.md` before handing over anything a model drafted, and whenever output satisfies every rule here and still reads generic. The ten above are the common cases. It holds the rest, plus the countable composition limits, the first-screen budget, and the record of which external items were adopted, which declined, and why.
+
+Skip it on a small change to a surface with a settled direction. The catalog is a diagnostic and costs a read on every invocation that does not need one.
+
+## When it reads almost right
+
+Read `${CLAUDE_SKILL_DIR}/references/craft.md` when a layout is correct and still looks off. It covers optical rather than mathematical alignment, alignment across side-by-side items, hierarchy built from weight rather than size, and the small failures that survive every structural rule.
+
+## Rules that differ by kind
+
+Read `${CLAUDE_SKILL_DIR}/references/kinds.md` once the read names a kind. A read naming a kind it does not cover gets the body's rules and a stated absence, never invented guidance.
+
+## Naming a pattern
+
+Read `${CLAUDE_SKILL_DIR}/references/vocabulary.md` when a shape needs a name, whether to ask for it, to compare two arms, or to record a pick.
+
+## Before handing anything over
+
+Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the last filter and every box traces to a rule stated here or in a reference. An item that cannot be honestly ticked is unfinished work rather than a judgment call.
+
+## What this delegates
+
+- Focus, keyboard, ARIA, alt text, and every accessibility floor: the `ui` governance rules, which fire on the same paths this skill does and are the single source
+- States, empty and loading coverage, destructive confirmation, truncation: the same rules
+- Rendered copy casing, button labels, error message shape: the same rules
+- The candidate loop, the arm set, the render, and the pick: `draft-and-pick`
+- Tracing a reference's color, type and spacing values: `sketch-design`
+- The shape of the project's design document and its token tables: `${CLAUDE_SKILL_DIR}/../../standards/design.md`
+- Spatial layout and interaction intent of one surface: `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`
+- Reading source for roughness: `ux-audit`. Measuring what a running interface costs to paint: `ux-measure`
+- Prose on the surface being designed: the `write-human` skill

package/claude/skills/design-taste/references/craft.md

@@ -0,0 +1,58 @@
+---
+title: Craft
+description: The failures that survive every structural rule, where a layout is correct by measurement and still reads wrong to the eye
+---
+
+# Craft
+
+Read this when a layout satisfies the ordering, the locks and the tells, and still looks amateur. Everything here is a property of the eye rather than of the markup, so no measurement catches any of it.
+
+## Optical against mathematical
+
+The eye and the arithmetic disagree, and the eye is the one being served.
+
+- **Centering by the numbers is not centering.** A triangle inside a circle, an icon beside a label, a glyph inside a round button all sit visually left or low when centered by their bounding box. Nudge until it looks right, usually a pixel or two.
+- **Equal vertical padding reads bottom-heavy.** A block with matching top and bottom padding looks like it is sinking. Give the bottom slightly more.
+- **Optical size beats declared size.** A circle and a square at the same declared size do not read as the same size. The circle needs to be larger.
+- **Type alignment follows the letterform, not the box.** A quotation mark, a bullet or an opening parenthesis at the start of a line should hang outside the text edge so the text itself lines up.
+
+## Alignment across siblings
+
+A row of cards is judged as a row, so every shared element has to land on the same line.
+
+- Titles, values, descriptions and actions align across all items in a row. One card with a two-line title pushing everything below it down is the most common version of this failure.
+- Pin actions to the bottom of each card so they form one horizontal line whatever the content above them does.
+- Feature lists in comparison columns start at the same vertical position. Fix with a fixed-height header block rather than by hoping the copy matches.
+- Equal-height cards forced by the layout engine are the wrong fix. Either allow variable heights deliberately or align the shared elements.
+
+## Hierarchy without scale
+
+Reaching for size is the first instinct and the weakest tool.
+
+- A page carrying only regular and bold has two levels. Introducing the weights between them gives four, at no cost in space.
+- Color, spacing and position all carry hierarchy. A heading set in a muted tone above tighter spacing reads as a level without being larger.
+- An enormous heading over uniform body text is shouting rather than structuring, and it flattens every level under it.
+
+## Type detail
+
+- **Orphans.** A single word alone on the last line of a heading. Let the renderer balance short headings rather than forcing the break by hand.
+- **Measure.** Body text running the full width of a wide container is unreadable however good the type is.
+- **Figures in columns.** Numbers that change, in a table, a price or a timer, need tabular figures or the column jitters.
+- **Tracking by size.** Large type wants tighter letter spacing, small uppercase labels want looser. Body text wants whatever the face was drawn with.
+- **Casing.** Sentence case for headings and labels. Title case on every heading reads as a template.
+
+## Depth and texture
+
+- A shadow is tinted toward the surface it falls on. Pure black at low opacity reads as dirt.
+- Flat with zero texture reads sterile at large sizes. A trace of noise or a soft gradient gives a large ground something to be.
+- An even linear gradient across a whole section is the laziest depth available. Break it or drop it.
+- Elements sitting flat beside each other with no overlap read as a diagram. Let something cross a boundary.
+
+## Small things that read as unfinished
+
+- A link or action that goes nowhere.
+- Navigation with no indication of where the reader currently is.
+- The same portrait used for several different people.
+- Every item dated identically, which no real collection ever is.
+- An exclamation mark in a success message. Confidence is quieter than that.
+- An error opening on an apology rather than on what to do next.

package/claude/skills/design-taste/references/kinds.md

@@ -0,0 +1,52 @@
+---
+title: Rules by kind
+description: What each broad surface kind optimizes for, where a rule written for one is wrong for another, and which surface governs the kinds this file does not cover
+---
+
+# Rules by kind
+
+Read this once the declared read names a kind. The body's rules hold on every kind. This file holds only what differs, because a rule that holds everywhere belongs in the body and a rule stated twice drifts.
+
+## Marketing and promotional
+
+Landing pages, campaign pages, portfolios. The reader has never used the thing and owes it no attention.
+
+- **Optimizes for** comprehension in the first screen, then one clear next action.
+- **Composition carries the weight.** A marketing page is judged on section order and variation before anything else, which is why a palette round against a flat composition changes nothing a reader notices.
+- **Vary the section shape.** Alternate alignment, container width and the ratio between sections. A page where every section is a centered heading over centered body reads as a template regardless of its values.
+- **Low density.** Whitespace is the argument that the thing is considered. This is the one kind where less information on screen is usually better.
+- **Every claim names a real thing.** A page asserting what a tool does, illustrated by something the tool did not produce, breaks its own thesis in the place it is making it.
+- **Motion is permitted and rationed.** Entrance motion for what genuinely leads the eye, nothing looping forever.
+- **Where a rule from another kind is wrong here:** dense tabular comparison, persistent chrome, and state indicators all read as product UI leaking onto a marketing page.
+
+## Application and product UI
+
+Dashboards, tools, admin surfaces, agentic and assistant interfaces. The reader is mid-task and already knows the domain.
+
+- **Optimizes for** throughput and state legibility. How fast can the reader see what is happening and act on it.
+- **High density is correct.** Cramming is a failure and spaciousness is also a failure, since a surface that shows six rows where thirty fit costs the reader a scroll per glance.
+- **The states carry the design weight.** Loading, empty, error, partial and stale are not edge cases on this kind, they are most of what the reader sees, so they are composed rather than handled. Whether each exists at all is the `ui` rules' question and not this one.
+- **An agentic surface adds three states of its own:** work in progress with something to read while it runs, work that needs the person before it continues, and work that finished with a result to inspect. Each needs a visible resting place and none should be a spinner.
+- **Chrome is persistent and quiet.** Navigation, status and context stay put and stay recessive, since they are read constantly and looked at rarely.
+- **Motion is feedback, not entrance.** A thing moving should be reporting that something changed.
+- **Where a rule from another kind is wrong here:** generous whitespace, entrance animation on every panel, and hero-scale typography all read as a marketing page wearing a product's clothes.
+
+## Content and long-form
+
+Documentation, articles, reference pages, learning material. The reader arrived to read and will stay if reading is comfortable.
+
+- **Optimizes for** sustained reading and for finding one thing without reading everything.
+- **Measure is capped** so the eye reaches the next line without hunting.
+- **Hierarchy comes from weight and space** rather than from size. A page of large headings reads as shouting and flattens the levels below.
+- **Navigation is a map.** A reader who cannot see where they are in the whole cannot judge whether to keep going, which is what a scrollspy or a persistent outline buys.
+- **Code, tables and figures are first-class.** They are what the reader scans for, so they are styled as content rather than as interruptions.
+- **Motion is almost always wrong.** Movement during reading competes with reading.
+- **Where a rule from another kind is wrong here:** density tuned for an application surface makes long prose unreadable, and marketing whitespace between every paragraph breaks a section into unrelated fragments.
+
+## Kinds this file does not cover
+
+- **Transactional flows** such as checkout, sign-up and settings are read as application UI. Their distinctive rules are state coverage and error recovery, which the `ui` governance rules already carry.
+- **Presentation surfaces** such as slide decks are governed by `${CLAUDE_SKILL_DIR}/../../standards/slides.md` and drafted by `draft-slides`. Take the layer ordering and the floor from the body and the rest from there.
+- **Terminal and text-mode surfaces** have no layout engine and their own color rules, stated where the writing surface is decided rather than here.
+
+A read naming any of the three above takes the body's rules and says it has no per-kind guidance, naming the surface that governs it. A read naming a kind this file does not list at all says so rather than borrowing the nearest section.

package/claude/skills/design-taste/references/preflight.md

@@ -0,0 +1,77 @@
+---
+title: Pre-flight
+description: The last filter before handing design work over, one box per rule stated in the body or a reference
+---
+
+# Pre-flight
+
+Run this against the output before handing it over. Every box traces to a rule stated in the skill body or one of its references, so a box that cannot be honestly ticked names unfinished work rather than a judgment call.
+
+Skip nothing on the ground that it is obviously fine. A rule is on this list because it was obviously fine to somebody who shipped it broken.
+
+## The read
+
+- [ ] The read is stated in the output, naming kind, audience, overriding constraint and layer
+- [ ] The arms or the change vary the layer the read named, not a cheaper one
+- [ ] Every layer below the one under judgment is settled
+- [ ] Mode named where the surface already exists, and nothing on the never-change list moved without agreement
+
+## Coherence
+
+- [ ] One accent across every section
+- [ ] One radius system, or a stated rule applied everywhere
+- [ ] One theme, with no inverted section between its neighbors
+- [ ] One copy register
+- [ ] Every shadow falls the same way and is tinted toward its ground
+
+## Composition
+
+- [ ] No layout family used twice. Eight sections carry at least four families
+- [ ] No three consecutive sections sharing the image-and-text split
+- [ ] Small uppercase labels above headings number no more than one per three sections
+- [ ] At most one horizontal marquee
+- [ ] Grid cells equal content items, with no blank tile filling a gap
+- [ ] Lists over five items use something other than a longer list
+- [ ] The first screen carries the point and the primary action without scrolling
+- [ ] The first screen carries at most four text elements
+
+## Systems
+
+Skip this group where the surface draws on a system already settled.
+
+- [ ] Every gap comes from one scale, and the distinct spacing values number under about eight
+- [ ] Space between groups exceeds space within them
+- [ ] The type scale carries five to seven steps, each visibly different from its neighbors
+- [ ] The accent is rare enough to read as an accent
+- [ ] Neutrals sit in one family at one temperature
+- [ ] Adjacent surfaces separate by a little and content separates from ground by a lot
+- [ ] No semantic color borrows the accent
+
+## Craft
+
+- [ ] Shared elements align across every item in a row, and actions form one line
+- [ ] Nothing centered by arithmetic that reads off-center
+- [ ] No orphaned word closing a heading
+- [ ] Body text measure is capped
+- [ ] Changing numbers set in tabular figures
+- [ ] Hierarchy carried by weight, color and space rather than size alone
+
+## Content
+
+- [ ] Every visible string re-read in one pass, with anything broken, unclear or performatively clever rewritten
+- [ ] Every number either real, labeled as sample, or removed
+- [ ] No placeholder that reads as placeholder: generic names, generic company names, reused portraits, identical dates
+- [ ] No filler verbs
+- [ ] Sentence case throughout
+- [ ] Every claim about what the product does is a thing it does
+
+## Motion
+
+- [ ] Every animation justified in one sentence naming hierarchy, sequence, feedback or state change
+- [ ] Nothing loops forever without input
+- [ ] Motion claimed is motion present, and motion absent is not claimed
+
+## Handover
+
+- [ ] The weakest thing on the surface is named out loud, per `draft-and-pick` Step 3, and fixed where naming it would embarrass the work
+- [ ] The floor the `ui` governance rules carry has been applied, not assumed

package/claude/skills/design-taste/references/systems.md

@@ -0,0 +1,49 @@
+---
+title: Systems
+description: The scales and relationships set once for a project rather than judged per draft, being space, type and palette
+---
+
+# Systems
+
+Read this when establishing or revising the scales a surface draws from. Every other reference here is read against a draft. This one is read before there is a draft, which is why it sits apart from them.
+
+Nothing below states a value. A value belongs to the project's own design document, and these are the relationships that decide whether the values work.
+
+## Space
+
+An unguided model reaches for whatever number looks right at each point, which produces a surface with thirty spacing values and no rhythm.
+
+- **Every gap comes from one scale.** Count the distinct spacing values on a finished surface. More than about eight means there is no scale, only arithmetic.
+- **The steps grow, they do not add.** A scale stepping 4, 8, 12, 16, 24, 32, 48, 64 gives usable distinctions at both ends. One stepping 10, 20, 30, 40 gives four values that all read the same at large sizes and none that work at small.
+- **Space between groups exceeds space within them.** This is the one spacing rule carrying real meaning, since proximity is what tells a reader which things belong together. A surface with one gap everywhere has told the reader nothing, and it is the most common spacing failure in generated output.
+- **Section rhythm is two or three tiers, not a value per section.** Pick the tiers, then assign each section to one.
+- **Space responds to viewport, type mostly does not.** A layout that scales every value together arrives at a phone reading like a shrunken desktop.
+
+## Type
+
+- **One scale, with fewer steps than feels sufficient.** Five to seven covers a surface. A scale with twelve steps has several nobody can tell apart.
+- **Adjacent steps are visibly different.** Two steps two pixels apart read as a mistake rather than as a level. If two steps are hard to distinguish side by side, one of them is not a step.
+- **Body size anchors the scale and everything derives from it.** Picking a display size first and working down produces body text sized by whatever was left.
+- **Line height moves opposite to size.** Large type wants it tighter, small type wants it looser, so one value across the scale is wrong at both ends.
+- **The scale carries weights beside sizes.** A scale of sizes alone forces every hierarchy decision to be a size decision, which is the failure `craft.md` names.
+
+## Palette
+
+The layer a model is worst at, and the layer where rules are hardest to make falsifiable. Everything below is a relationship, since a rule naming a value is a value ban and values belong to the project.
+
+- **An accent is defined by rarity, not by hue.** A color used on a third of the surface is a ground, whatever it was chosen as. If the accent appears more than a handful of times per screen, there is no accent.
+- **Neutrals are one family at one temperature.** Warm grays beside cool grays read as a mistake rather than as a decision, and it is a mistake a model makes by pulling neutrals from different sources.
+- **Adjacent surfaces separate by a little, content separates from ground by a lot.** Generated output routinely inverts this: cards that shout against the page, and text that does not.
+- **A semantic color is not the accent.** Error, success and warning carry meaning. Borrowing the accent for one of them makes the accent mean something, and it stops being available for anything else.
+- **Dark mode is re-derived, not inverted.** The relationships above are what carry across, and the values are settled again. A palette flipped by algorithm gets the relationships wrong in both directions.
+- **Saturation has a budget across the surface, not per color.** Several colors each individually reasonable produce a surface that reads loud, which is why the rule is about the total rather than about any one value.
+
+## Considered and declined
+
+Each failed the test in `REQUIREMENT.md`. Recorded so they are not argued again.
+
+- **Control sizing and proportion.** An unguided model produces reasonable controls without instruction, so it fails the first question.
+- **Specific ratios for a type scale**, such as a named musical interval. Falsifiable and arbitrary, and a project picking a different ratio is not wrong.
+- **Named palettes or banned hues.** A value ban, which belongs to the project's design document. This is where every external catalog of this kind ends up, and it is why theirs cannot be imported.
+- **A minimum contrast figure.** A threshold with a number, which the accessibility rules own.
+- **Imagery as a system.** There is no scale to establish. What a model gets wrong about images is using fake ones, which `tells.md` already covers, so the layer stays thin on purpose rather than by oversight.

package/claude/skills/design-taste/references/tells.md

@@ -0,0 +1,101 @@
+---
+title: Machine tells in design
+description: The visual defaults a model reaches for when nothing states a direction, each with what to do instead, plus the record of which external items were adopted, which were declined, and why
+---
+
+# Machine tells in design
+
+Each item below is a shape rather than a value, which is why no ban list of colors or fonts reaches any of them. Read this before handing over anything a model drafted. Skip it on a small change to a surface that already has a settled direction.
+
+The skill body carries the ten most common of these. This is the same catalog at full length, so an item appearing in both is one list rather than two.
+
+An item is a default to reach past, not a prohibition. A brief that explicitly asks for one gets it, and the point is that it was chosen rather than defaulted into.
+
+## Composition
+
+- **The three equal cards.** Three identical boxes in a row under a heading is the most-reached-for feature section in existence. Reach for a two-column alternation, an asymmetric grid, a list with one item given weight, or a single worked example.
+- **One section shape repeated down the page.** A page where every section is a centered heading over a centered body reads flat whatever its palette. Vary alignment, container width and the ratio between sections.
+- **The centered hero over a dark wash.** Centered headline, centered subhead, two buttons, gradient behind. Reach for an asymmetric split, a full-bleed artifact, or content that starts immediately.
+- **Decoration standing in for structure.** Hairline grids, crosshairs, floating rules and corner marks added so a page feels designed. Use them where they organize real content and remove them where they do not.
+- **The corner floater.** A large left-aligned section heading with a small explanatory paragraph floating in the top right, aligned to nothing. Put the sub-text under the heading or build a real two-column header.
+
+## Content and labels
+
+- **Enumerated eyebrows.** `001 / Capabilities`, `Phase 02`, `Step 1`, `Stage One`. The content is the label. Where progression genuinely matters, use the verb.
+- **Poetic section labels.** "From the field", "On our desks", "Currently on the bench". Use the plain functional label or drop the label.
+- **Atmospheric strips.** City, time zone, temperature, coordinates, build version, last-sync time, placed for texture rather than information. Keep one only where it carries real state a reader acts on.
+- **Scroll cues.** "Scroll", an animated wheel, a downward arrow with a label. A reader looking at the top of a page knows what scrolling is.
+- **Decorative status dots.** A coloured dot before every nav item, list row or badge. Keep it only where it reports genuine state, and then sparingly.
+- **Filler verbs.** A verb chosen for its warmth rather than for what it reports, such as `elevate`, `unleash`, `empower` or `next-generation`. Name the thing the surface does.
+- **Placeholder that reads as placeholder.** Generic person names, egg avatars, invented company names of the `Acme` family, one portrait reused for several people, every item dated identically. Real collections are uneven and specific.
+- **Invented precision.** A figure like 4.1x or 48k either came from real data, is marked as sample, or does not appear. There is no fourth case. Inventing a number to look engineered is the version of this that gets shipped, because it reads as confidence.
+- **The fake screenshot built from boxes.** A product UI simulated out of styled rectangles inside a hero. Show the real thing, a real capture, or nothing.
+- **Copy nobody re-read.** Read every visible string once as a reader rather than as its author, before handing anything over. Rewrite what is grammatically broken, what carries a pronoun with no antecedent on the page, and what reaches for charm it has not earned. Plain beats clever and wrong, which is what a model drafting copy produces by default.
+
+## Surface and palette
+
+- **Glow as depth.** Outer glows and neon rims standing in for elevation. Use a border, a tint, or a real shadow with direction.
+- **Pure black and pure white as grounds.** Both are harsher than nearly any surface wants. Move off the extreme.
+- **Saturation everywhere.** An accent at full saturation next to neutrals that are also tinted leaves nothing to anchor on. Desaturate the neutrals and let one accent carry.
+- **The gradient as a substitute for a decision.** A gradient covering a section, a heading, or a button set, applied because the flat version looked plain. Flat is usually the fix for flat composition, not gradient.
+- **Uniform radius and uniform elevation.** Every card at the same radius with the same shadow flattens hierarchy. Let the thing that matters differ.
+
+## Typography
+
+- **Scale as the only hierarchy.** An enormous heading over uniform body text. Weight, color, spacing and measure carry hierarchy at lower cost.
+- **One family doing every job.** Pairing is not decoration. A second family, or a real weight range, separates roles that scale alone cannot.
+- **Unbounded measure.** Body text running the full width of a wide container. Cap the line length.
+- **Caps and letter-spacing as a texture.** Small caps with wide tracking on every label reads as a template. Use it where the label is genuinely a different kind of thing.
+
+## Motion
+
+- **Motion nobody can justify.** Before adding any animation, say in one sentence what it communicates: hierarchy, sequence, feedback, or a state that changed. "It looked good" is not one of those. A sentence that will not come is the answer, and the animation goes.
+- **The permanent loop.** Anything animating forever with no input. It costs attention on every frame and earns none back.
+- **Motion on arrival for everything.** Every section fading up on scroll. Reserve entrance motion for what genuinely needs the eye.
+- **Motion claimed but not present, or present but not claimed.** A surface described as restrained that animates on every scroll, or one described as fluid that sits still, has decided nothing. Ship the motion or drop the claim.
+- **Motion that ignores a reduced-motion preference.** Not a taste failure at all. It is a correctness failure the `ui` governance rules own, listed here only so a motion pass does not read this catalog as the whole of what motion owes.
+
+## The countable limits
+
+These are the rules with numbers, so they are checked by counting rather than by judging. Every one came out of production testing by people shipping model-drafted pages.
+
+- **A layout family appears once.** Once a section uses a shape, no other section on the surface uses it. Eight sections need at least four distinct families.
+- **Two consecutive splits, never three.** Alternating image-left and image-right reads as considered twice and as filler by the third. Break it with a full-width section, a vertical stack, a grid, or anything else.
+- **One small uppercase label per three sections.** The tiny wide-tracked line above a heading is the single most over-reached default in model output. Count them: more than `ceil(sections / 3)` is too many, and the first screen counts as one. The fix is usually to delete it, since a section's position already says what it is.
+- **One marquee.** Two sliding strips on one surface read as filler rather than as a device.
+- **Cells equal items.** A grid with a hole in it, or a blank tile at the end, means the grid was shaped before the content was counted. Reshape it.
+- **Over five items wants a different component.** A longer list is the lazy answer. Group into clusters, split into columns, give each item a card, make them scrollable, or collapse the tail behind a disclosure.
+
+## The first screen
+
+- **It fits.** The point and the primary action are both visible without scrolling. If the copy will not fit, the copy is too long or the type is too large, and the second is the more common cause.
+- **At most four text elements.** A label or a brand strip, a headline, a short supporting line, and the actions. That is the whole budget.
+- **Everything else moves down.** A small tagline under the actions, a trust strip, a pricing hint, a feature list, a row of faces. Each of those is a section of its own below, not a fifth element above.
+- **Plan the type scale against the asset.** A headline wrapping to four lines is a size error rather than a length error.
+- **Logos go under it, never inside it.** A credibility row shares no space with the point.
+
+## Adopted, declined, and why
+
+External catalogs were read and filtered rather than imported. This section is the record, and a later session extends it rather than re-deriving it.
+
+### Adopted
+
+**Adopted with no change.** The three equal cards, the centered hero over a wash, enumerated eyebrows, scroll cues, decorative status dots, atmospheric strips, the fake screenshot built from boxes, filler verbs, and placeholder that reads as placeholder. Each names a shape, each carries a replacement, and none depends on a stack.
+
+**Adopted with the stack removed.** Source items naming an icon set, a component library, a font by name, or an animation package were rewritten to state what the rule is about. "Do not use Inter" became one family doing every job, since the defensible claim is about pairing and role separation rather than about one typeface.
+
+### Declined
+
+**Banned fonts by name.** A font ban is a value ban, and a value belongs to the project's own design document rather than to a skill that loads everywhere. A project that wants a typeface ruled out rules it out there.
+
+**Numeric intensity dials.** Every external source carries a 1-to-10 scale for variance, motion and density. A session picks a middle value and reports compliance. That satisfies the rule, decides nothing, and leaves no trace a later reader could check it by. The declared read carries the same information in a sentence somebody can argue with.
+
+**The em dash ban as a design rule.** One source bans the character on a page as a visual tell. The markdown standard already bans it for prose reasons and `canon markdown audit` gates that from package data, so restating it here would put a second copy of an enforced rule behind an unenforced pointer.
+
+**The official-package map.** A table routing a brief to Fluent, Material, Carbon, Polaris, Primer or a government design system. It is real advice and it is a stack decision a project takes once, so it belongs in that project's own records rather than in a skill that loads on every design round.
+
+**Scoping out application UI.** The largest source covers landing pages, portfolios and redesigns, and excludes dashboards, data tables and multi-step product UI. Those exclusions are most of what software projects actually build, so the kinds reference carries application UI as a first-class kind.
+
+### Carried as a caution
+
+**Greeking.** Placeholder text is correct while judging space and wrong once an arm is judged on content, since real copy length is what breaks a composition. State which of the two a set is doing.