@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/ui-craft/rules/motion-is-rare.md

@@ -0,0 +1,31 @@
+---
+# concepts: ui-markup, ui-styles
+paths:
+  - "placeholder"
+---
+
+# Motion is rare, interruptible and optional
+
+<constraints>
+Always do:
+- Honour `prefers-reduced-motion`: a reduced variant, or none.
+- Animate `transform` and `opacity` only, and list the properties in a transition.
+- Let input interrupt any animation.
+- Spend motion on one moment: a single page-load sequence or one reveal lands better than an effect on every section. Decelerate smoothly.
+- Give anything that moves on its own for over 5 seconds a pause, stop or hide control.
+- Ask first: how often is it seen (hundreds of times: no animation), and what is it for? "It looks nice" is valid only for one signature moment.
+- Use ease-out for what enters or leaves, ease-in-out between two places, linear for scroll-linked motion. Never ease-in: the first frames barely move.
+- Time it: press 100-160ms, hover 150-200ms, menus 150-250ms, dialogs 250-450ms, reveals 500-900ms. Leaving takes about 70% of arriving.
+- Reduce motion to fewer and gentler, not none: keep opacity and colour, drop travel, scale, parallax and autoplay.
+- Paint the headline, the sentence and the picture on the first frame. Vary entrances with the content, in reading order, and fire them once.
+- Pause loops when off screen or when the tab is hidden.
+
+Never do:
+- `transition: all` (`ui-no-transition-all`).
+- Bounce or elastic easing (`ui-no-bounce-easing`).
+- Fade-and-slide every section in, loop a marquee, or pulse a status dot for decoration.
+- Hide content until an animation reveals it: the text must be there at rest.
+- Animate layout properties (`ui-no-animate-layout`): width, height, top, left, margin and padding force layout on every frame.
+- Capture the wheel or lock scrolling (`ui-no-scroll-hijack`). No preloader, no counter, no gate.
+- Move anything across text being read.
+</constraints>

package/packs/ui-craft/rules/no-generated-look.md

@@ -0,0 +1,37 @@
+---
+# concepts: ui-markup, ui-styles
+paths:
+  - "placeholder"
+---
+
+# No generated look: every default is a choice or it goes
+
+Generated UI clusters around the same traits. Each is fine when a brief asks for it; the fault is reaching for it without choosing. The brief's own words and a project's design system always win.
+
+<constraints>
+Never do, unless the brief or the design system asks:
+- Purple or violet gradients, or cyan on dark (`ui-no-ai-palette`).
+- A warm cream ground with a serif display and a terracotta accent; near-black with one acid accent.
+- Gradient text (`ui-no-gradient-text`), or one accented word in a headline.
+- A tiny uppercase tracked label above a heading (`ui-no-eyebrow`), or a pill badge above the headline.
+- Index numbers beside headings: 01, 02, 03 (`ui-no-index-numbering`).
+- A thick coloured border down one side of a card (`ui-no-side-tab`).
+- Cards inside cards, rows of identical cards, an icon in a rounded tile above every heading.
+- The same soft shadow under everything, coloured glows, one border radius regardless of hierarchy.
+- Glass panels, floating pill navigation, decorative blobs, grid-line backgrounds.
+- Fake dashboards of grey bars, a placeholder where a picture should be: no image is better.
+- The overused faces by reflex: Inter, Roboto, Fraunces, Geist, Plus Jakarta Sans, Space Grotesk.
+- The assistant palette: a yellow-cream ground with terracotta or clay (`ui-no-assistant-palette`). It was the published fix for the earlier tells, and became the most recognisable look of all.
+- Emoji as icons or bullets (`ui-no-emoji-as-ui`).
+- Micro-UI clutter: fake status pills, pseudo-system labels ("00 orchestration layer"), decorative code-like tags, filler metadata rows.
+- Box inside box inside box: one framing move, then alignment and space.
+
+Always do:
+- Spend your boldness in one place. Let one element be memorable and keep the rest quiet.
+- Fill the space ornament leaves with scale, full content or a real picture, not another ornament.
+- Use structure that carries information: an outline, a number or a divider earns its place by saying something.
+- Replace a tell with a procedure, never a product: derive it from the subject. Every published "use this instead" list becomes the next wave of tells.
+- Put an idea in first. A page with every tell removed and nothing in their place is an empty page with good manners, and that is a tell too.
+
+On the taste-skill study of 247 sites: those scored 7.5 or higher used icon feature cards 1% of the time against 28% for sites under 6.5, pill badges 14% against 34%, gradients 22% against 52%, shadows 24% against 48%, tiny tracked caps 16% against 57%.
+</constraints>

package/packs/ui-craft/rules/page-holds-its-frame.md

@@ -0,0 +1,28 @@
+---
+# concepts: ui-markup
+paths:
+  - "placeholder"
+---
+
+# A page holds its frame: a title, equal margins, no accidental holes
+
+For pages people read once: landing, marketing, portfolio, product.
+
+<constraints>
+Always do:
+- Say on the first screen what this is, in a real `h1`, and give every section a heading.
+- Keep one pair of equal outer margins. Readers name unequal margins first, before any detail.
+- Answer a void: every empty area is closed by something on its far side, or it is a deliberate rest, once per page.
+- Keep the gap between sections clearly larger than any gap inside one.
+- Give neighbouring sections different compositions. A repeated module is for archives only: a menu, a schedule, a work index.
+- Carry the idea to the last section, pricing and FAQ included: most pages turn into stock blocks after the hero.
+- Make the phone a composition of its own, with its own crop and line breaks.
+- Keep to the order of the argument, not the stock order of hero, logos, features, testimonial, pricing, CTA.
+
+Never do:
+- Pad a short page: a quarter of the studied sites are one or two screens.
+- Stretch thin content over many screens. In blind tests a richer page full of template devices beat a cleaner page that was thin, every time.
+- Put a gate, a preloader or an entry pop-up before the content.
+- Let anything cover a headline at any scroll position.
+- Set a statement over three lines at headline size: it reads as a long headline.
+</constraints>

package/packs/ui-craft/rules/page-proved-rendered.md

@@ -0,0 +1,19 @@
+---
+# concepts: ui-markup
+paths:
+  - "placeholder"
+---
+
+# A page is proved rendered, not read
+
+Reading markup proves nothing about contrast, overflow or layout. A grep passes cleanly in exactly the failing case.
+
+<constraints>
+Always do:
+- Name the gate that proves it in `.claude/layout.json`: `"gates": { "a11y": "<command>" }`, or `"none: <reason>"` to decline. `doctor` is red for UI code without one. The `prove-page` skill builds it.
+- Run it on what the visitor receives: the production build, not only the dev server.
+- Treat it as a floor: automated checks catch only part of accessibility, so keyboard and screen-reader passes stay by hand.
+
+Never do:
+- Call a page done from its source.
+</constraints>

package/packs/ui-craft/rules/pictures-do-a-job.md

@@ -0,0 +1,25 @@
+---
+# concepts: ui-markup
+paths:
+  - "placeholder"
+---
+
+# Pictures: real things first, one strong image over six small ones
+
+The top-scored sites in taste-skill's study show, and the weak ones tell: a median of 37 images against 5.
+
+<constraints>
+Always do:
+- Choose in order: the project's own images; ones generated this session; real pictures from open collections, with credit; drawings of the subject itself; type and colour alone, on purpose.
+- Let one dominant image lead: on the top sites hero media covers at least half the first screen 68% of the time.
+- Give every image a job: show the thing, set the place, prove the claim.
+- Keep crops to one or two ratios and one treatment, and share one light and grade.
+- Put a flat scrim or a calm area under any text on a picture. Text lost over a busy image is a named failure.
+- Use a real interface fragment to show software, marked up as the product's own.
+- Download found pictures into the project, credit them, and list them for the owner.
+
+Never do:
+- Ship a placeholder or a grey box: no image is better (`ui-no-empty-image`).
+- Present a found picture as the client's own product, room or team.
+- Use an unrelated stock photograph where a drawing of the real subject would do.
+</constraints>

package/packs/ui-craft/rules/pointer-feedback.md

@@ -0,0 +1,28 @@
+---
+# concepts: ui-markup, ui-styles
+paths:
+  - "placeholder"
+---
+
+# Everything the pointer can act on says so
+
+a hovered element MUST show it is interactable by changing the cursor to match the action, and should usually do something that fits it.
+
+<constraints>
+Always do:
+- Change the cursor to name the action: `pointer` to activate, `text` to edit, `grab` and `grabbing` to drag, `col-resize` or `row-resize` to resize, `zoom-in` to enlarge, `not-allowed` for what is truly disabled.
+- Give the hovered thing itself a small effect that fits it: a tone step, a colour, a slight growth, an underline. Hover colour in 180-200ms, a hover that moves in 300-400ms.
+- Press answers too: a small change in 100-160ms, so a click is felt.
+- Use one hit test for hover and press: one function or element, never a second list.
+- Keep the disabled look for what is truly disabled. Something that responds gets the hover.
+- Give a new screen its hover in the same change that makes it interactive.
+- Make hover and focus-visible agree, so a keyboard user sees what a mouse user sees.
+- Prove it: name the hover gate in `.claude/layout.json`, `"gates": { "hover": "<command>" }`, or `"none: <reason>"` to decline. `doctor` is red for UI code without one. The `hover-state` skill says how.
+- Build the hover into the template, so every instance has it and it is changed and tested once (`test-the-template-once`).
+
+Never do:
+- A `pointer` cursor on something inert, or no change on something that acts.
+- A custom cursor image (`ui-no-custom-cursor`).
+- Let the effect shift the layout or the neighbours: transform, shadow or colour, never size or margin.
+- Lift or zoom every card: the effect means "this acts", so an element that does nothing gets none.
+</constraints>

package/packs/ui-craft/rules/screen-answers-one-question.md

@@ -0,0 +1,24 @@
+---
+# concepts: ui-markup
+paths:
+  - "placeholder"
+---
+
+# A screen answers one question, and the biggest thing on it is the answer
+
+For application screens: dashboards, admin, settings, inboxes. The `app-screen` skill is the method. The numbers are from taste-skill's study of 23 product screens.
+
+<constraints>
+Always do:
+- Write the screen's one question in a line ("Which deploy broke?", "Who is waiting for a reply?"). It decides what is biggest, what comes first, and what is left out.
+- Name the one finding in today's data ("the 23:28 deploy doubled the error rate") and put it where it is read first, next to the action it drives.
+- List the blocks as answers to the next questions. A block with no question is deleted: this is how to escape KPI row, big chart, two small charts, table.
+- Put the most frequent job one click away, where the answer shows. A screen with no control for its main job is a report, not a tool.
+- Show the evidence beside the answer: one annotated line on the event that matters beats a second chart.
+- Show everything the brief names on the first screen; cap long lists at 4-6 rows with "View all".
+- Size each block to its question, not to the data the product hopes for. A new account's small numbers are drawn at their real size.
+
+Never do:
+- Let a secondary figure out-shout the answer: the largest number answers the title's sentence.
+- Copy a well-known product's arrangement: take the structure from this product's own things.
+</constraints>

package/packs/ui-craft/rules/survives-real-data.md

@@ -0,0 +1,23 @@
+---
+# concepts: ui-markup, ui-styles
+paths:
+  - "placeholder"
+---
+
+# Every screen survives real data: long, empty, loading and failed
+
+<constraints>
+Always do:
+- Design for short, average and very long input. Text containers truncate, clamp or wrap; a flex child that holds text gets `min-width: 0`.
+- Give every list an empty state that says what goes here and offers the action that fills it.
+- Show loading in the place the content will appear, and end the words with "..." or the ellipsis the design system uses.
+- Say what failed and what to do next, where the person is looking: inside the block that failed, with when the data was last good and a Retry. Never a full-screen banner.
+- Keep an empty section's frame and header, with one sentence spanning it. On a first run, put the first action where the data will appear.
+- Load with the final layout: each value a flat bar at its real size, labels shown at once, nothing shifting when the data lands. A refresh keeps the old values and updates a freshness stamp.
+- Show limits as a bar at the true ratio with both ends labelled ("12.7k of 20.0k").
+- Reserve space for what arrives late, so nothing jumps.
+
+Never do:
+- Render a broken screen for an empty string or an empty array.
+- Show a spinner with no end: a slow request says so, and offers a way out.
+</constraints>

package/packs/ui-craft/rules/touch-and-small-screens.md

@@ -0,0 +1,19 @@
+---
+# concepts: ui-markup, ui-styles
+paths:
+  - "placeholder"
+---
+
+# Touch, zoom and small screens are not an afterthought
+
+<constraints>
+Always do:
+- Make touch targets at least 24 by 24 CSS pixels (WCAG 2.2), and about 44 for a primary action.
+- Give drag, swipe and pinch a tap and a keyboard alternative.
+- Use `env(safe-area-inset-*)` on full-bleed layouts, `overscroll-behavior: contain` in modals and drawers, and `touch-action: manipulation` on controls.
+- Set `color-scheme` and a matching `theme-color`, so scrollbars and inputs follow a dark theme.
+
+Never do:
+- Disable zoom (`ui-no-zoom-lock`).
+- `autoFocus` on a phone: it opens the keyboard over the page.
+</constraints>

package/packs/ui-craft/rules/type-space-colour.md

@@ -0,0 +1,26 @@
+---
+# concepts: ui-markup, ui-styles
+paths:
+  - "placeholder"
+---
+
+# Type, space and colour: a few strong choices, measured
+
+Numbers from taste-skill's study of 247 gallery sites, unless marked.
+
+<constraints>
+Always do:
+- Type: two or three sizes do the work, five is the ceiling. One family is normal, two the limit. Body text 16-20px, line height 1.45-1.6, 45-75 characters per line. A real scale: a headline-to-body ratio around 4.3 on the studied sites.
+- Space: one grid and one pair of margins, equal on both sides. The gap between sections is clearly larger than any gap inside one, and spacing has rhythm: tight inside a group, loose between groups.
+- Headings: one `h1`, no skipped levels, more space above a heading than below it.
+- Colour: one ground, one ink, one accent, the accent on the action and perhaps one other thing. Running text in the full ink. Separate surfaces by a small step in tone.
+- Align left by default; centre at most one moment.
+- Align everything horizontally and vertically. What looks grouped is a group: the same size, the same spacing, shared edges. Repeated things are one size.
+- Name colours as tokens by role: ground, surface, ink, muted, accent, accent ink. A raw hex in a component is a second palette starting.
+- Headlines: size contrast is the lever, not weight. Half of the studied heroes are regular weight.
+- Stay above the floors: text at 12px or more, contrast 4.5:1 for body and 3:1 for large text (WCAG).
+
+Never do:
+- Justify narrow columns, or set long passages in capitals.
+- Put grey text on a coloured background: use a darker shade of that colour.
+</constraints>

package/packs/ui-craft/rules/url-holds-the-state.md

@@ -0,0 +1,19 @@
+---
+# concepts: ui-markup
+paths:
+  - "placeholder"
+---
+
+# The URL holds the state, and a destructive action can be taken back
+
+<constraints>
+Always do:
+- Keep filters, tabs, pagination and open panels in the URL, so a view can be shared, reloaded and reached with Back.
+- Use real links for navigation, so Cmd-click and middle-click work.
+- Give a destructive action a confirmation that names what dies, or an undo window.
+- Send focus somewhere sensible on a route change, and keep a sticky header from covering what has focus.
+
+Never do:
+- Navigate from `onClick` on something that is not a link.
+- Delete on one click with no way back.
+</constraints>

package/packs/ui-craft/skills/app-screen/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: app-screen
+description: Use when building or changing an application screen, a dashboard, an admin or analytics view, settings, an inbox or a list screen.
+---
+
+# Build an app screen from its data (one job: a screen that answers its question)
+
+A page is read once; a screen is read every day. `apps-are-not-pages` says what changes.
+
+<constraints>
+Always do:
+1. Inventory, in 8 to 12 lines: the objects and fields with units; real magnitudes, including how small they are for a new account; who opens this, how often, on what device; what they do next, and which job comes up most; the product's own things (its name, the people, what people recognise by sight).
+2. Write the data first: a small dataset the screen renders from, with believable names, amounts that add up and a unit on every figure. Totals are computed from the rows. Assert in the data file what must agree, and read the console.
+3. Write the screen's one question and one finding (`screen-answers-one-question`), then list the blocks as answers to the next questions.
+4. Pick the shell: a sidebar on the page's own ground, or a top bar only if it carries something. One left edge and one right edge for every block.
+5. Set the KPIs: default to one container split by 1px dividers; values 16-40px, about 1.7 times the label; label above the value, grey, sentence case. Nothing else in the tile. The answer figure is 30-36px and at least 1.3 times its siblings. A figure appears in one place only.
+6. Set tables: rows 36-53px, 56-92px with media; 12px grey sentence-case headers, no band; numbers right-aligned with their header; one status mark; a sort glyph on the active column only. Overview lists show 2-5 rows.
+7. Forms: label above the field, 14px; no floating labels; one control height per context. Disabled controls stay legible and say why. Beside a setting, show what it produces.
+8. Build every block's empty, zero, loading and error state, and every row's hover, selected, focus and disabled state. A screen that works only with full data is half built.
+9. Check the rendered screen at 1440, 768 and 390 (`prove-page`), and answer in writing:
+   - Is the question answered by the biggest thing, and read first?
+   - Do all blocks share the screen's edges, with no dead strip or stretched card?
+   - Is colour only on data, status and the one action?
+   - Do the numbers add up and line up, and does every fact shown twice agree?
+   - Does every zero look like a zero, and every missing value like a dash?
+   - Does each legend match its mark, with no label colliding?
+   - On the phone, is the navigation folded, and does each block still answer?
+10. Fix the worst three, look again, three rounds at most. If a problem shows in a screenshot it is real, whatever the code says.
+
+Never do:
+- Shrink the type and keep the padding: density is row pitch, padding and type moved together.
+- Mix save models on one view.
+</constraints>

package/packs/ui-craft/skills/build-from-reference/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: build-from-reference
+description: Use when a screenshot, mockup or design image is the source for a page or component, or when asked to match or copy a look.
+---
+
+# Build from a reference image (one job: the code looks like the picture)
+
+The common failure is drift: a strong reference, and a coded result that became generic.
+
+<constraints>
+Always do:
+1. Read it like a specification before writing code. Extract:
+   - **Text:** every readable word: headline, supporting line, button labels, navigation, section headings.
+   - **Type:** character, the scale between sizes, line counts, where lines wrap, alignment.
+   - **Space:** section gaps, padding, gutters, the grid, card proportions.
+   - **Components:** button shapes and hierarchy, border radius, strokes, icons, shadows.
+   - **Colour:** the palette, the accent, background and image treatment.
+   - **Structure:** section order, density, repeated motifs.
+2. Say why it looks strong, in a few lines, and list what is unclear.
+3. Build to it section by section, comparing a screenshot with the reference at the same width. A photograph is evidence of the design: draw the object straight on and aligned, never its camera angle or its wear.
+4. Resolve what is unclear in this order: the visible design language, the layout and spacing logic, the component family, the polish level, then the most faithful option that can be built.
+5. Report every place the code differs from the reference, and why.
+
+Never do:
+- Improve it into a default layout, or swap a distinctive section for a generic row.
+- Compress generous spacing, or merge sections into a repeated pattern the reference does not have.
+- Fill an unclear detail with a default before going through step 4.
+</constraints>

package/packs/ui-craft/skills/chart-choice/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: chart-choice
+description: Use when a screen needs a chart or a figure, or a chart looks wrong, cluttered or unclear.
+---
+
+# Pick the chart from the question (one job: the plainest form that answers it)
+
+| Question | Form |
+|---|---|
+| Is it moving over time? | One 2px line, straight, no markers; an area only with a fill of 15% or less |
+| How much per period? | Columns with square corners |
+| How is it distributed? | A histogram with equal bins |
+| Who ranks? | A sorted horizontal bar list |
+| What share? | A thin ring, or a 100% stacked bar; five parts at most, legend as a table |
+| How far to the target? | A progress bar, both ends labelled, the fill the true ratio |
+| Has it drifted from target? | One row per part: a bar with a 1px tick at the target |
+| Where? | A map with a list beside it; the list carries the magnitudes |
+| Which way did it flow? | Columns above and below one zero line, the axis signed and captioned |
+
+<constraints>
+Always do:
+- Ask whether it needs a chart: four of the 23 studied screens draw none, because a few numbers say it.
+- Show one series per chart, three at most; switch metrics with a control, not by overlaying lines.
+- Use 3-5 faint gridlines, no y-axis line, round ticks above the maximum, no legend for a single series.
+- Draw a plot about 112-264px tall. A series flat except for one event gets two-thirds of the width, with the event annotated.
+- Dash a forecast after today, and label its end value.
+- Encode it in the chart if a caption has to say which bars are which.
+- Draw an empty chart: the zero line, missing bars for empty periods, one sentence.
+
+Never do:
+- Use a hue per bar, or more than four hues on a screen.
+- Smooth a line with a spline, or put a dot on every point.
+- Use a fat donut with labels on the slices.
+</constraints>

package/packs/ui-craft/skills/hover-state/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: hover-state
+description: Use when a button, link, tab, row, card or any clickable element is added or changed in the web app, when something does not react under the mouse, or when a hover gate is written or fails.
+---
+
+# Hover state (one job: every clickable thing answers the pointer, and a gate proves it)
+
+The law is the rule `web-hover-every-pressable`: a cursor naming the interaction, and a small visible effect on the hovered element itself.
+
+## Add the hover to a new element
+1. Use a real `button` or `a` (or give a custom element a role and both of the next two).
+2. Set `cursor` from the interaction: `pointer` for a press or link, `text` for a field, `grab` or a resize cursor for a drag, `not-allowed` only when truly disabled.
+3. Add a `:hover` (and `:focus-visible`) style on that element: a lift, a ring, a brighten, an underline; a transition of about 100 ms. Change transform, shadow or colour, never size or margin, so the neighbours stay still.
+4. Define it once on the shared component, so every use gets it; do not restyle per page.
+
+## Prove it: the hover walk
+A browser test (Playwright, in the project's own test folder) that, for one element of each component and every one-off on each screen (`button, a[href], [role=button], [role=tab], input, select, textarea, [tabindex]`):
+1. moves the pointer to its centre;
+2. reads `getComputedStyle(el).cursor` and requires the interaction's cursor, never `auto` or `default`;
+3. screenshots the element's box and a ring round it before and after: the box changes by a floor, the ring does not;
+4. moves away and requires the box back to rest.
+Plant the faults so it is seen red: remove the hover style from one component, remove its cursor, leave one clickable `div` bare.
+
+## Declare it
+`layout.json`: `"gates": { "hover": "<the command>" }` (for example `npm run test:hover`). `doctor` is red while the web app has code and no gate is declared, or the command names a file that is not there. `"hover": "none: <reason>"` declines with its reason.
+
+## Worked example
+Stellix (a drawn window, not a page): `tools/gates/hover_gate.sh`, `lib/app/gates/editor_hoverwalk_read.h`, `tools/gates/hover_judge.py`. The same five steps, with the page's pointer in place of the window's.

package/packs/ui-craft/skills/page-critique/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: page-critique
+description: Use when judging a rendered page, when a page feels generic or flat, or when design-review needs a deeper pass on a marketing or landing page.
+---
+
+# Critique a rendered page (one job: find what a stranger would notice, and fix in the right order)
+
+Make each pass on its own, on the screenshots at desktop and phone. App screens use the checks in `app-screen`.
+
+<constraints>
+Always do:
+1. **One second, then five.** Glance away: there should be one answer, a word, an image, an object. "A website" means no focal point. Then five seconds as a stranger: what is this, who is it for, what do I do?
+2. **Squint.** The page reduces to two or three large masses. Many similar masses means nothing leads.
+3. **Cover the logo.** Could this belong to a competitor? Swap the name and the noun: an equally valid page has no idea. Does the idea reach the pricing, the FAQ and the footer?
+4. **Edges.** Count the distinct left edges of text blocks. Two or three reused on purpose; six means things were placed one at a time.
+5. **Space and frame.** Equal outer margins? Any section huddled on one side? A hole, or a rest? Any blank stretch over half a screen?
+6. **Type.** Is the jump from body to headline decisive, three times or more? More than five sizes? Orphan words? Lines over 75 characters?
+7. **Colour.** Name the proportions. An accent in ten places means nothing.
+8. **Images.** Is every image doing a job? Do crops share ratios? Any grey box or fake screen?
+9. **Sameness.** One word per section's layout. The same word twice in a row, or three times on the page, is the template showing.
+10. **Phone.** A composition of its own, or the desktop squeezed?
+11. **Fullness.** Is each screen composed, or a narrow column with dead ground? An austere page is not a restrained one.
+12. **Substance.** Does every section deliver its information at a readable size? Is the primary action a real button on the first screen?
+13. **Collisions.** Anything on a headline or a button at any scroll position? Anything off the edge of the phone?
+14. **The competitor.** Put the nearest competitor's name on it. Then name the one live thing the visitor can do.
+15. **Cap the score.** Any placeholder caps content at 5. A blank band where a reveal failed caps usability at 5. No clear title, or anything covering a headline, caps usability at 6. An idea that fits anyone caps creativity at 6. Unequal margins or a huddled section cap design at 6.5.
+16. **Fix in this order:** the idea, hierarchy, composition, typography, imagery, colour, detail, motion. Later items cannot rescue earlier ones.
+17. **Three rounds at most:** critique, fix the top three, look again. Stop when nothing is left that a stranger would notice. Report the real score: never round up.
+
+Never do:
+- Refill a gap with an ornament: close it, enlarge what remains, or let a picture take the space.
+- Trust a page because the checks passed.
+</constraints>

package/packs/ui-craft/skills/prove-page/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: prove-page
+description: Use when a project has UI code and no page gate, when doctor asks for gates.a11y, or when a page needs proof before it ships.
+---
+
+# Build the gate that proves a page, rendered
+
+<constraints>
+Always do:
+1. Use the test runner the project has. Playwright is the usual one: pin it through `latest-versions`, with `@axe-core/playwright` for accessibility.
+2. Open each key page in a real browser, on the production build, at three widths: 1440, 768 and 390.
+3. Measure with `.claude/tools/page-measure.mjs`: `const facts = await page.evaluate(measure)`, then `expect(judge(facts)).toEqual([])`. Then assert, per page and width:
+   - no axe violations at the WCAG A and AA levels, in both colour schemes;
+   - no horizontal overflow, and no text clipped or covered;
+   - headlines at two lines or fewer, and a single `h1`;
+   - no broken images, no uncaught script errors, and text visible at rest.
+4. Seed a planted fault for each kind and see the gate red before trusting it (`hooks-and-gates`).
+5. Name the command in `.claude/layout.json` as `"gates": { "a11y": "<command>" }`.
+
+Never do:
+- Run it only on the dev server: minifiers and bundlers change what ships.
+- Treat a pass as "accessible": automated checks catch only part of it. Keyboard and screen-reader passes stay by hand.
+</constraints>

package/packs/ui-craft/skills/redesign-page/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: redesign-page
+description: Use when asked to redesign, restyle or review an existing page or screen.
+---
+
+# Redesign what exists without breaking it (one job: better, with the same things still working)
+
+<constraints>
+Always do:
+1. Record the before: run the project, screenshot it at every width, and take its measurements (`prove-page`). Read the code: the framework, the styling method, the components, and what must survive: routes, forms, data, behaviour, the brand's own assets.
+2. A review stops here: critique the screenshots (`page-critique`), list the findings with their measurements, and name the three changes that would move it most.
+3. Keep the stack, the content and what works. No framework or styling migration; check the dependency file before adding anything.
+4. Work in order of biggest effect for least risk: type, colour, the frame (margins, section rhythm, a title and headings), states (hover, focus, loading, empty, error), then the stock components.
+5. Prove it: measure again, compare before and after at every width, click through every link, form and menu that worked before, and report both sets of measurements side by side.
+
+Never do:
+- Change behaviour during a restyle.
+- Report a redesign without the before.
+</constraints>

package/packs/ui-craft/skills/ui-code-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ui-code-review
+description: Use when asked to review UI code, audit a page's source for accessibility or UX, or before handing a screen to design-review.
+---
+
+# Review UI code against the laws (one job: findings by file and line)
+
+Reads the source. For judging the rendered page, use `design-review`.
+
+<constraints>
+Always do:
+1. Read the named files; ask which ones if none are named.
+2. Go through the `ui-craft` rules in order: forms, motion, real data, URL state, touch, dates and numbers, copy, type and space, generated look. Then the `accessibility` rule where it is installed.
+3. Report terse findings by file, in `file:line` form, one line each: what is wrong and the fix.
+4. Rank them: **P0** blocks someone from using it, **P1** hurts many people, **P2** hurts a few, **P3** polish. A file with nothing to report says so in one line.
+5. Treat a `WARN`-level taste finding as wrong unless it can be defended to a designer in one sentence.
+
+Never do:
+- Rewrite the code during the review.
+- Rank a generated-look finding above an accessibility one.
+- Call something a law when it is taste: say which.
+</constraints>

package/packs/ui-craft/skills/write-the-page/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: write-the-page
+description: Use when a page needs its words: a landing page, a product page, a headline, or copy that reads as templated.
+---
+
+# Write the page before building it (one job: an argument, not sections)
+
+<constraints>
+Always do:
+1. Answer in one line each: who is reading, and what do they already know? What is this, said the way its maker would say it to a friend? What one thing should they believe after one screen? What would make them believe it? What do they do next?
+2. List the page as claims, one per section, each with its proof. A section with no claim is filler. The order of the argument is the order of the page.
+3. Budget the headline: characters per line is about line width divided by (font size x 0.5). About 32 characters, four to six words, survives every width at a confident size. Up to about 42 if the phone size comes down. Past that, you are writing a sentence: move the rest to the supporting line.
+4. Pick the plainest shape that is true: the name; what it is ("Furniture for small rooms"); the claim ("Your bank won't do this"); the instruction ("Understand your money").
+5. Control the break: `max-width` in `ch`, `text-wrap: balance`, an authored `<br>` where it matters, checked on the phone. Section headings are two to five words.
+6. Keep a statement a paragraph: an intro sentence set large is a `<p>` of about 25 words, at 36px or less on desktop and 24px on a phone.
+7. List sample details for the owner to confirm. Proof is never invented.
+
+Never do:
+- Fix a long headline only by shrinking it: five words at 64px beats nine at 28px.
+- Leave a single orphan word on line two: cut a word.
+</constraints>

package/packs/ui-craft/tools/page-measure.mjs

@@ -0,0 +1,41 @@
+// What a page gate measures in a real browser (0.22.0; the measurements come from taste-skill's inspector, written for the kit). measure()
+// runs in the page, with no dependencies: `const facts = await page.evaluate(measure)` in Playwright, at each width. judge(facts) lists what fails.
+// It is a floor, beside axe: `prove-page` says how to build the gate around it.
+export function measure() {
+  const vw = document.documentElement.clientWidth;
+  const seen = (el) => { const s = getComputedStyle(el); const r = el.getBoundingClientRect(); return s.display !== 'none' && s.visibility !== 'hidden' && r.width > 0 && r.height > 0; };
+  const lines = (el) => {
+    const range = document.createRange();
+    range.selectNodeContents(el);
+    return new Set([...range.getClientRects()].filter((r) => r.width > 1).map((r) => Math.round(r.top / 4))).size;
+  };
+  const headings = [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].filter(seen);
+  const texts = [...document.querySelectorAll('p,li,td,th,a,button,label,span')].filter((el) => seen(el) && [...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim()));
+  const levels = headings.map((h) => Number(h.tagName[1]));
+  const blocks = [...document.body.children].filter(seen).map((el) => el.getBoundingClientRect());
+  return {
+    width: vw,
+    h1s: headings.filter((h) => h.tagName === 'H1').length,
+    skippedHeading: levels.some((l, i) => i > 0 && l > levels[i - 1] + 1),
+    overflowX: document.documentElement.scrollWidth > vw + 1,
+    overflowing: [...document.querySelectorAll('body *')].filter((el) => seen(el) && el.getBoundingClientRect().right > vw + 1).slice(0, 5).map((el) => el.tagName.toLowerCase()),
+    longHeadlines: headings.filter((h) => lines(h) > 2).map((h) => h.textContent.trim().slice(0, 60)),
+    tinyText: texts.filter((el) => parseFloat(getComputedStyle(el).fontSize) < 12).slice(0, 5).map((el) => el.textContent.trim().slice(0, 40)),
+    brokenImages: [...document.images].filter((i) => i.complete && i.naturalWidth === 0).map((i) => i.getAttribute('src') ?? ''),
+    hiddenAtRest: texts.filter((el) => parseFloat(getComputedStyle(el).opacity) === 0).length,
+    margins: blocks.length ? [Math.round(Math.min(...blocks.map((b) => b.left))), Math.round(vw - Math.max(...blocks.map((b) => b.right)))] : [0, 0],
+  };
+}
+
+const LAWS = {
+  h1s: (f) => f.h1s !== 1 && `${f.h1s} h1 on the page; one says what this is`,
+  skippedHeading: (f) => f.skippedHeading && 'a heading level is skipped',
+  overflowX: (f) => f.overflowX && `the page scrolls sideways at ${f.width}px (${f.overflowing.join(', ')})`,
+  longHeadlines: (f) => f.longHeadlines.length > 0 && `headline over two lines: ${f.longHeadlines[0]}`,
+  tinyText: (f) => f.tinyText.length > 0 && `text under 12px: ${f.tinyText[0]}`,
+  brokenImages: (f) => f.brokenImages.length > 0 && `broken image: ${f.brokenImages[0]}`,
+  hiddenAtRest: (f) => f.hiddenAtRest > 0 && `${f.hiddenAtRest} text element(s) hidden at rest`,
+  margins: (f) => Math.abs(f.margins[0] - f.margins[1]) > 2 && `unequal page margins: ${f.margins.join(' and ')}px`,
+};
+
+export const judge = (facts) => Object.values(LAWS).map((law) => law(facts)).filter(Boolean);

package/packs/web/checks/a11y-img-needs-alt.json

@@ -0,0 +1,26 @@
+{
+  "id": "a11y-img-needs-alt",
+  "why": "An <img> with no alt attribute reads its filename to screen readers. Describe it, or alt=\"\" for decorative.",
+  "rule": ".claude/rules/accessibility.md",
+  "concepts": [
+    "markup"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/out/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/*.stories.*"
+  ],
+  "code": false,
+  "pattern": "<img\\b(?![^>]*\\balt\\s*=)[^>]*>",
+  "bad": "<img src=\"/hero.png\" width=\"800\" height=\"400\">",
+  "good": "<img src=\"/hero.png\" alt=\"The Decipherist studio desk\" width=\"800\" height=\"400\">\n<img src=\"/divider.svg\" alt=\"\" width=\"40\" height=\"4\">"
+}