@palate/cli 0.0.0-stage → 0.0.2

package/kb/taste/garvit-portfolio.md

@@ -0,0 +1,94 @@
+---
+id: t.garvit-portfolio
+kind: taste
+title: Garvit's portfolio — clarity first, plus crafted personality
+tags: [taste, personality, tactile, paper, warm-neutral, scribble, stamps, sound, restraint, owner-taste]
+answers: How does the owner want creativity mixed with design, and how do I reproduce that quality in any product?
+use_when: [any screen that should feel crafted rather than generic, choosing where and how much personality to add, building tactile buttons and surfaces]
+---
+
+The owner's reference site (Vite, React 19, Tailwind 3). A plain, legible, centred page in a warm paper palette, with a small number of physical-object metaphors (pen, postage stamp, postcard, page corner) placed around the content, never inside it. Everything below is measured from source.
+
+## 1. Foundations
+
+**Colour.** One ink, one paper, one accent; everything else is opacity of the ink.
+- Paper `#f2f0ec` (hsl 40 17% 94%); cards are near-white glass `#fcfcfb` so they lift off it.
+- Ink `#3c3a38` (hsl 30 3.4% 22.7%) for text, primary buttons and outlines. Muted text hsl 30 3% 40%; borders hsl 30 4% 90%. Every neutral sits at hue 30 with 3–4% saturation: a warm grey, never blue-grey.
+- Accent orange: token hsl 26 88% 52% (focus ring, selection at 22%, "new" badge); the pen colour is a hotter literal `#ff7700` (scribble, postmark, bullets).
+- Story colours appear only inside metaphors: air-mail stripes `#e8663a`/`#3d63c9`, fountain-pen blue `#2f4db0` for handwriting, stamp papers `#fffdf8`/`#fffcf5`. Status is a single emerald dot.
+- Secondary text is ink at 45–80% opacity (`text-foreground/80`, `/45`), not new greys.
+
+**Type.** Four families with fixed jobs.
+- Display: Averia Sans Libre 700, tracking **-0.06em**, line-height 1.05. Hero 44 → 60 → 68px; section titles 36/48px; card titles 24px at 1.1.
+- Body: SF Pro Rounded, falling back to Nunito, weight **500** at 16px, +0.01em tracking. Ledes 18–20px, line-height 1.6, +0.02em. Rounded and slightly heavy, so text feels soft and friendly.
+- Hand: Caveat 600 at 21–30px, used only for the signature and address lines on the postcard.
+- Mono: JetBrains Mono, code only. Labels such as "POST CARD" or stamp captions are 10–13px, uppercase, tracked +0.16 to +0.5em.
+
+**Spacing.** Sections are 80/112px tall in padding; the container is 1152px max with 16/24/32px gutters; card grids use 16/20px gaps. A card is 10px padding around a media well, then text at 14px sides, 20px top, 24px bottom.
+
+**Radii are concentric.** Surface 22px with a 14px media well inside it. Nav pill 16px, buttons and fields 12px, nav links and icon buttons 10px, pills fully round, app icons 28%.
+
+**Depth, and how the tactile buttons work.** There are almost no CSS borders. Edges are 1px box-shadow rings at 6–8% ink. Each surface stacks:
+1. a hairline ring (`0 0 0 1px rgba(ink,.07)`),
+2. a tight contact shadow (`0 2px 1px rgba(0,0,0,.04)`),
+3. a long, soft, negatively spread drop shadow (`0 12px 24px -18px`),
+4. **inset bottom shading** (`inset 0 -3px 3px #fff, inset 0 -2px 2px rgba(0,0,0,.05)`). This gives the bottom edge a slight lip, so the object reads as a pillow rather than a flat card.
+
+The primary `btn-ink` is charcoal with a 2px ink ring, a 3px contact shadow, and `inset 0 -4px 2px rgba(255,255,255,.08)` as a bevel along the lower edge. Hover lightens it to `#4a4845`. The secondary `btn-soft` is 70% white, turning fully white on hover. Everything scales to 0.97 on press. The segmented filter is a sunken well (ink at 5%, `inset 0 1px 2px`) holding a raised white thumb.
+
+## 2. Personality moves
+
+| Move | Where | How it is built | Why it doesn't hurt clarity |
+|---|---|---|---|
+| **Scribble circle** | One word per heading: "feel", "shipped", "clean", "together", "free" | An SVG of two loose pen loops behind the word, `pathLength=1`, drawn with dash-offset over 1100ms `(.22,1,.36,1)` after 150ms. It draws once, when the word is fully in view. Tilted -1.6°, 1.6px non-scaling stroke | Emphasis, which typography already needs. The word stays real text, and the SVG is aria-hidden |
+| **Hero stamps** | Above the headline | Three stamps whose perforations are a CSS mask (a grid of radial-gradient holes plus a solid inner rect), with the shadow as a drop-shadow on a wrapper. Tilted -13°, 11° and -3°, they drop in from -18px at scale 1.12 over 650ms, staggered 0/80/200ms. On hover they rise 5px and straighten. A postmark SVG (text on a `textPath`, multiply blend) lands last with an overshoot `(.2,1.5,.4,1)` | It carries identity: the centre stamp is the avatar, captioned "Garvit · India" |
+| **Postcard contact** | The contact section | Cream card with an air-mail striped band (a repeating-gradient border cut out with mask-composite exclude). A message side and an address side. The real email sits on ruled handwriting lines. The stamp and postmark animations stay paused until the card is revealed | The metaphor is the contact block itself. The CTA is still a normal ink button |
+| **Peel corner** (theme switch) | Fixed dog-ear, bottom-right | 46px at rest, 84px on hover or focus, plus one 68px peek at 2.2s, once per session. The gap previews the other world and a hint label slides in. Clicking runs a View Transition: per-frame clip-path polygons peel the page along a 45° fold over 1150ms (ease-in-out cubic), starting from the current lift, with a synthesised paper rustle | A familiar affordance for a dark-mode toggle. It has an aria-label and keyboard focus, and swaps instantly under reduced motion |
+| **Sound** | Global | One delegated listener: soft click on buttons and links (volume 0.45), hover tick only on main buttons with fine pointers (0.25), a pop when sound is enabled. Peel and tear are synthesised noise. Mute toggle in the nav; `data-sound="off"` opts an element out | It reinforces actions and never replaces visual feedback. Off by default under reduced motion |
+| **Space world** | The whole site, after peeling | Same token names re-valued: true black, Inter Tight 300, giant type at -0.055em, real NASA photos, scroll-pinned scenes (a clip-path window, a black-hole approach), headings pulled toward the cursor on a spring (0.06/0.82), an optional VR lens view | Opt-in and reversible. The scribble switches off there, so the mood changes rather than flourishes piling up. The nav steps back during full-screen scenes |
+| **Pull-to-refresh** | Mobile | rAF loop writing transforms straight to the DOM. Resistance 0.5, threshold 80px, max 120px, icon turns 3°/px, eases back over 300ms | A native gesture done properly. No transform is left at rest, so sticky layers stay intact |
+| **Small crafted parts** | Throughout | Bevelled app-icon social links, tech pills with brand logos, "How I work" cards illustrated with mini UIs built in code (editor, settings panel, Lighthouse gauges, a flowing-dash diagram), footer wordmark at 18vw and 6% opacity | Each illustration shows the claim beside it |
+| **Lab tear-off** | /lab/stamp | Rubber-band drag (0.45 → 0.7 resistance) until 130px, then the stamp tears free and downloads. The shadow deepens with tension; it springs back with `(.34,1.56,.64,1)` over 420ms | The gesture is the download action |
+
+**Restraint.** In paper mode each viewport has about one signature object plus at most one scribbled word. Hero: stamp cluster and "feel". Projects: "shipped" only, and the cards are plain. About: one scribble inside one card title. Contact: the postcard is the section. Personality sits at the edges (above the headline, in a screen corner, around a single word, in the footer). It never touches data, card copy or CTAs. All decoration is aria-hidden and `pointer-events: none`.
+
+## 3. Motion and micro-interactions
+
+- One curve, `--ease-out-strong: cubic-bezier(.23,1,.32,1)`, used for nearly all UI motion. Cinematic scenes use `(.16,1,.3,1)`, and exits ease in with `(.7,0,.84,0)`.
+- Durations: buttons 160ms, hover lift 240ms at -3px, reveals 500ms over 12px, stagger items 400ms over 10px (steps of 30–80ms, set as CSS transition-delay so a group reveals in one frame), accordion 300ms on `grid-template-rows` 0fr→1fr with the chevron rotating 180°.
+- Hover lift only runs under `(hover: hover) and (pointer: fine)`. Press scale works everywhere. The tap highlight is removed.
+- Focus: a 2px orange outline at 3px offset. Inputs get a 2px orange ring with a white fill.
+- Lenis smooth scroll: 1.2s, exponential ease-out, anchor offset -80, scroll-padding-top 96px.
+- Reduced motion: animations and transitions are cut globally. The scribble appears already drawn, reveals apply at once, the peel swaps instantly, physics and the peek are off, and sound defaults to off.
+
+## 4. Layout and composition
+
+- One centred axis. The hero is a centred text block (max 768px, bio max 560px): CTA and social icons on one row, three status pills below.
+- Every section uses the same template: centred title, centred lede, an optional control, a 1→2-column grid of equal cards, one closing CTA. Because the rhythm is predictable, the personality reads as a deliberate exception.
+- Width narrows with the content: 1152px for grids, 896px for the postcard, 768px for the experience timeline, 720px for the sticky floating nav pill.
+- Experience: squircle company icons on a dotted timeline, each with an accordion card. The first role starts open.
+- Mobile: the CTA goes full width, stamps scale to 0.74, the menu opens inside the nav pill, secondary metadata moves into expanded panels, and the contribution graph scrolls to the latest weeks.
+
+## 5. Transferable principles
+
+1. **Build a plain, conventional page first.** Personality is added at the end, in a few marked places, and the page must still work if every flourish is removed.
+2. **Draw personality from one physical metaphor that fits the domain**, and reuse it in several forms (stamp, postmark, postcard, peel). A CRM might use index cards and rubber stamps; a docs site, margin notes and bookmarks.
+3. **Give each viewport one signature object plus at most one accent gesture.** Put them at the edges of the content: above, around, in the corner, or at the end of the page.
+4. **Let decoration carry information wherever possible**: the avatar on the stamp, the real email on the address line, mini-UIs that show the claim beside them.
+5. **Keep the palette to one tinted neutral family, one ink, one accent.** Derive secondary text from ink opacity. Allow extra colours only inside the metaphor's own objects.
+6. **Make depth physical.** Use a hairline ring, a contact shadow, a long soft drop and inset bottom shading instead of borders. Buttons get a bevel and scale to 0.97 on press.
+7. **Keep radii concentric** (outer = inner + padding). A card is a frame around a media well.
+8. **Pair a characterful display face with a calm, soft body face.** Tight display tracking (-0.03 to -0.06em), loose body tracking, line-height 1.6 for reading.
+9. **Use one ease-out curve and short durations** (160–500ms). Gate hover motion to fine pointers. Every animation fires once, on the user's view, never in a loop next to content.
+10. **Reimagine a commodity control** (theme toggle, refresh, download) as a gesture from the metaphor, with a hint, a one-time teaching peek, keyboard access and an instant fallback.
+11. **Treat sound and other extra senses as layers on visual feedback.** They should be quiet, delegated globally, easy to mute, and off under reduced motion.
+12. **Respect reduced motion by showing the end state**, not by removing it: the scribble appears drawn and reveals apply immediately.
+13. **When there are two modes, change the register, not the amount.** Dark mode is a different mood with fewer flourishes, not the same flourishes inverted.
+14. **Write copy that is short, first-person and concrete.** The scribble lands on the verb that carries the promise.
+
+**Deliberately avoids:**
+- Gradient blobs, glassmorphism everywhere, neon, and purple-blue "AI" gradients. Glass is only the nav pill.
+- Decorating data: no flourishes inside cards, tables, descriptions or buttons.
+- Several competing gestures in one viewport, or looping ambient animation behind text (the only loop is a 2s status pulse).
+- Hard 1px grey borders and cold blue-grey neutrals.
+- Novelty that blocks the task: every playful control has an aria-label, focus handling and a plain fallback, and the primary action is always an ordinary, obvious button.

package/kb/universal/color-roles.md

@@ -0,0 +1,26 @@
+---
+id: u.color-roles
+kind: universal
+title: Colour by role, not by mood
+tags: [color, colour, palette, status, accent, contrast, semantic, dark mode]
+answers: Where does colour go, and how much of it?
+use_when: [every screen]
+---
+
+**Roles**
+- **Neutrals (90% of the screen):** background, surface, borders, text in 3 steps (primary, secondary 4.5:1, disabled).
+- **One accent** for the primary action and focus/selection. Nothing decorative uses it.
+- **Status colours** (success, warning, danger, info), separate from the accent, used small: a dot, a 1px border, text, a tinted badge background at 8–12% opacity.
+- **Data colours** for charts and categories only (e.g. the `--chart-*` tokens).
+
+**Rules**
+- Colour carries meaning. If you remove all colour and the screen still works, colour is decoration; reduce it.
+- Text contrast 4.5:1, large text and UI parts 3:1. Muted greys fail most often; check them.
+- Tinted badges: background at 10% of the hue, text at the hue's dark step, optional 1px border at 20%.
+- Dark mode is not inverted light mode: surfaces get lighter as they rise, borders become subtle (white at 6–10%).
+
+**Mistakes**
+- Every card with its own coloured icon tile.
+- Gradient corner blobs on KPI cards.
+- Red, amber and green on the same row for unrelated things.
+- A brand accent used for status ("approved" in the brand purple).

package/kb/universal/copy.md

@@ -0,0 +1,16 @@
+---
+id: u.copy
+kind: universal
+title: Copy that designs
+tags: [copy, writing, microcopy, labels, buttons, headlines, honest, truthful, numbers]
+answers: What should the words on the screen say?
+use_when: [every screen]
+---
+
+- **Specific beats clever.** "5 open deals with no contact in 14 days · £218,500" beats "Pipeline insights".
+- **Buttons say what happens:** "Approve 4 changes", "Send invite", "Add to basket · £28".
+- **Headings carry meaning;** you should get the whole page from the headings alone.
+- **Never invent** numbers, logos, quotes or reviews. Missing proof is a `[NEEDS]` note, not a fake.
+- **Sentence case** everywhere. No Title Case Buttons.
+- **No buzzwords:** seamless, supercharge, cutting-edge, unlock, revolutionise, leverage, effortless.
+- **Microcopy under actions** removes doubt: "No card needed", "Invites expire after 7 days", "You can undo this".

package/kb/universal/details.md

@@ -0,0 +1,31 @@
+---
+id: u.details
+kind: universal
+title: The details checklist
+tags: [polish, details, alignment, icons, focus, hover, truncation, hit area, accessibility, finish]
+answers: What separates finished from almost-finished?
+use_when: [before calling any screen done]
+---
+
+**Alignment and rhythm**
+- Shared left edges across header, toolbar and content. Icons align optically with the first line of text.
+- One spacing scale (4/8/12/16/24/32/48). No 10px or 18px.
+- Icon sizes 16px in dense UI, 20px in roomy UI, stroke matched to text weight. One icon set.
+
+**Text**
+- No orphan words in headings (`text-wrap: balance`). No em dashes or emoji in UI copy.
+- Numbers: tabular in tables and counters only; thousands separators; currency in the data's currency.
+- Relative times ("3 days ago") with the absolute date in a `title` or below.
+- Truncate with ellipsis plus the full value on hover.
+
+**Interaction**
+- Every clickable thing has hover, focus-visible and pressed states. Focus ring: an outline (not a border), 2px, offset 2px, at least 3:1 against the colours next to it (two-tone on mixed backgrounds), keyboard only (`:focus-visible`).
+- Hit areas at least 24×24 (44×44 on phones). Small icon buttons get padding, not a bigger icon.
+- Destructive actions confirm inline or offer undo. Prefer undo.
+- Disabled buttons explain why (tooltip or helper text).
+
+**States** (see u.states): empty, loading, error, long content, one item, many items.
+
+**Motion** (see u.motion-feedback): 150–250ms, ease-out, transform and opacity only.
+
+**Final pass:** zoom the screenshot to 200% and look at the corners: radius consistency, borders doubling up, misaligned baselines, cut-off focus rings.

package/kb/universal/first-screen.md

@@ -0,0 +1,30 @@
+---
+id: u.first-screen
+kind: universal
+title: The first screen decides everything
+tags: [hierarchy, focal point, fold, layout, priority, first screen, above the fold]
+answers: What must be visible and loudest before anyone scrolls?
+use_when: [every screen]
+---
+
+People judge a screen in the first second, from the first viewport only. Design that frame first, then the rest.
+
+**Before you lay anything out, write down:**
+1. The one question this screen answers for this person, this visit. ("Who do I chase today?", "Is my rollout healthy?", "What does this cost?")
+2. The answer, as data on the screen. That answer is the focal point.
+3. The primary action, if there is one. Exactly one solid button per view.
+
+**Rules**
+- **One focal point.** The answer to the question is the biggest or highest-contrast thing on the first screen. If the biggest text is a page title like "Team" or "Agents", the hierarchy is wrong; the title is a label, not the content.
+- **Use the frame.** At 1440×900 the first screen should be mostly content. A centred 640px column on a 1440 screen wastes half the frame on app screens. Marketing can breathe; tools should not.
+- **State over chrome.** Lead with what's happening (2 approvals waiting, 5 deals quiet, 9 of 10 seats used) instead of with the navigation or a form.
+- **Show the product, not a description of it.** Real rows, real values, real states from the data.
+- **Everything is visible without animation or scroll triggers.** Animate from a visible state.
+
+**Check on the screenshot:** cover the page title with your thumb. Can you still tell what the screen is for and what needs doing? If not, the focal point is missing.
+
+**Mistakes**
+- Page title at 32px, the actual answer at 14px in a card below.
+- Four equal KPI cards where one number matters.
+- A form (invite people, filters) taking the top of the screen when the list is what people came for.
+- First screen of a product page that shows a colour block and no price.

package/kb/universal/fit-the-codebase.md

@@ -0,0 +1,29 @@
+---
+id: u.fit-the-codebase
+kind: universal
+title: Fit the product you're in
+tags: [tokens, design system, consistency, components, fonts, theme, existing app, shadcn, css variables]
+answers: How does a new screen look like it belongs to this app?
+use_when: [any change inside an existing app]
+avoid_when: [the project has no styling at all and the brief asks for a new identity]
+---
+
+A screen that ignores the app's system looks like a different product, however nice it is alone. Consistency is what reads as premium.
+
+**Do**
+- Run `palate context` and read one or two existing screens before designing.
+- Use the existing colour, radius, shadow, spacing and type tokens. In shadcn apps that means `bg-background`, `text-muted-foreground`, `border`, `bg-primary`, `rounded-lg` and friends, not hex values.
+- Build from the existing components (Button, Card, Table, Badge, Input…). Need a new variant? Add it to the component, don't fork it.
+- Keep the existing typeface. A new font for one screen is the clearest sign of a bolt-on.
+- If a needed colour doesn't exist (a status colour, a chart series), add one token to the token file and use it everywhere.
+- Match the density and spacing rhythm of neighbouring screens.
+
+**Character comes from the content, not the costume.** Make the screen distinctive with layout, hierarchy, one domain-specific element (see `u.signature`) and excellent details, inside the existing palette.
+
+**When the existing screens are bad** (generic gradients, emoji, template look), keep the tokens and components but don't copy the bad patterns. Note in the Decision Record what you didn't follow and why.
+
+**Mistakes**
+- Page-scoped palettes like "sage paper and navy ink" inside a neutral shadcn app.
+- Loading a Google Font in a route component.
+- 25 hard-coded hex values on one screen.
+- New `.card` styles next to an existing Card component.

package/kb/universal/layout-width.md

@@ -0,0 +1,28 @@
+---
+id: u.layout-width
+kind: universal
+title: Width, columns and density by screen type
+tags: [layout, grid, width, max-width, columns, density, whitespace, sidebar, split, responsive]
+answers: How wide should the content be, and how should it split?
+use_when: [every screen]
+---
+
+| Screen | Content width at 1440 | Composition |
+|---|---|---|
+| Data table / list (CRM, admin) | Full width minus 24–32px gutters (or minus a 240px sidebar) | Toolbar row, then the table. Filters in one 40px row, not a panel. |
+| Dashboard home | 1200–1320px | 12-column grid; the focal block spans 8, a side rail spans 4 |
+| Settings / team / forms | 960–1100px | Two columns: 280–320px left label/description, 640px right controls; or a 220px section nav + content |
+| Review / approvals | 1100–1280px | Queue on the left (8 cols), context rail on the right (4 cols) |
+| Docs / API reference | Full width | 240–280px nav · content 680–760px · 440–520px sticky code column |
+| Product detail (commerce) | 1200–1280px | 7/5 split, image left, sticky buy box right |
+| Landing page | 1200–1280px content, full-bleed bands | Alternating split 6/6 or 5/7, centred statements between |
+| Phone (390) | 100% minus 16–20px gutters | One column, primary action reachable by the thumb |
+
+**Density**
+- Tools: 8px grid, row heights 40–48px, section gaps 24–32px. Whitespace separates groups; it shouldn't fill the screen.
+- Marketing: section padding 96–128px desktop, 64–72px mobile.
+
+**Rules**
+- Use `gap`, not margins. Align left edges across sections; one column grid for the whole page.
+- Don't put a single narrow column in the middle of a wide app screen. Use the width for the thing people compare (table columns, side rail, code).
+- Phone: stack; turn tables into two-line rows; keep the primary action in a sticky bottom bar when the page is long.

package/kb/universal/motion-feedback.md

@@ -0,0 +1,23 @@
+---
+id: u.motion-feedback
+kind: universal
+title: Motion that confirms, not decorates
+tags: [motion, animation, transition, feedback, easing, duration, reduced motion, micro-interaction]
+answers: Which interactions get motion, and how much?
+use_when: [interactive screens]
+---
+
+**Durations:** 120–180ms for hovers and toggles, 200–260ms for panels and dialogs, exits faster than entrances.
+**Easing:** ease-out for entering and leaving (`cubic-bezier(0.22, 1, 0.36, 1)`); exits about 20% faster than entrances. Never scale from 0 (start at 0.95+). No animation on actions people repeat many times a day. Springs for drag and toggles (no bounce in tools).
+**Properties:** transform and opacity. Never `transition: all`, never width/height/top for UI motion.
+
+**Where motion earns its place**
+- Confirming an action: a check drawing in, a row settling into its new state, a count ticking.
+- Showing cause and effect: an approved field moving into "applied", a filter narrowing the list.
+- Keeping place: panels slide from where they were triggered.
+
+**Rules**
+- Entrances start from `scale(0.96)` and `opacity: 0`, never `scale(0)`.
+- No motion on keyboard-driven high-frequency actions.
+- `prefers-reduced-motion`: keep opacity fades, drop movement.
+- Nothing is hidden waiting for an animation to reveal it.

package/kb/universal/signature.md

@@ -0,0 +1,29 @@
+---
+id: u.signature
+kind: universal
+title: One signature element per screen
+tags: [signature, character, distinctive, memorable, domain, metaphor, delight, generic]
+answers: What makes this screen not look like every other generated screen?
+use_when: [every new screen or redesign]
+---
+
+Generic screens come from generic parts: header, cards, table, button. Distinctive screens have **one element that only this product would have**, drawn from its domain and data. Not decoration: it must carry information.
+
+**How to find it:** ask "what does this person look at in the real world when doing this job?" and turn that into the screen's key component.
+
+| Screen | Signature that carries information |
+|---|---|
+| Team & seats | A seat strip: one cell per paid seat, filled by a person, held by an invite, or free |
+| CRM pipeline | A stage track per row (dots along the deal path) or a "days quiet" heat on the last-contact column |
+| Agent approvals | A field-by-field diff like proofreading marks: old struck through, new underlined, source under it |
+| Habit tracker | A 7-day strip per habit; checking off is a satisfying stamp or fill |
+| Candle product page | The candle lit vs unlit; burn time shown as evenings |
+| API reference | The request line with path parameters highlighted, beside a live, copyable example |
+| Audio product | A playable sample in the hero |
+
+**Rules**
+- One per screen. Two signatures compete; three is a theme park.
+- It uses the app's tokens. Character comes from form and behaviour, not from a new palette or font.
+- It must survive the "remove it" test: take it away and the screen gets worse at its job, not just plainer.
+
+**Mistakes:** decorative blobs, giant product names as wallpaper, a novel visual metaphor that hides the numbers.

package/kb/universal/states.md

@@ -0,0 +1,17 @@
+---
+id: u.states
+kind: universal
+title: Empty, loading, error and edge states
+tags: [states, empty state, loading, skeleton, error, edge cases, zero data, no results]
+answers: What does the screen look like when the data isn't perfect?
+use_when: [every data-driven screen]
+---
+
+- **Empty (first use):** say what this place is for, and one action to fill it. No illustration needed; a 1-line explanation and a button beat a big empty graphic.
+- **No results (after filtering):** name the filters that caused it and offer one-click ways to widen them ("Clear owner filter", "Search all stages").
+- **Loading:** show nothing for the first ~1s (most loads finish). Longer page loads: skeleton rows in the real layout at the real row height. A single module or button: a small spinner in place. (NN/g; Viget found skeletons can feel slowest, so don't default to them.)
+- **Error:** what failed, in plain words, and the next step (Retry, contact). Keep the rest of the screen usable.
+- **Partial / degraded:** a failed item in a list shows inline with its reason, not as a toast that disappears.
+- **Long content:** 60-character names, 7-digit numbers, 0 and 1 items, 1,000 items.
+
+Design at least the empty and no-results states for every list, and show the error state for anything with a failure in the data.

package/kb/universal/type-app.md

@@ -0,0 +1,33 @@
+---
+id: u.type-app
+kind: universal
+title: Type for product UI and dashboards
+tags: [typography, type scale, font size, weight, numbers, tabular, app, dashboard, table]
+answers: What sizes and weights make a dense screen readable and calm?
+use_when: [app screens, dashboards, settings, tables, docs]
+avoid_when: [marketing heroes, editorial pages (see u.type-marketing)]
+---
+
+**Scale (px):** 12 · 13 · 14 · 16 · 20 · 24 · 32. Use 4–6 of them on one screen, not more.
+
+| Role | Size | Weight | Notes |
+|---|---|---|---|
+| Page title | 20–24 | 600 | It's a label. Keep it smaller than the key number. |
+| Key number / focal value | 28–40 | 500–600 | tabular-nums, tight leading (1.1) |
+| Section heading | 14–16 | 600 | Not uppercase by default |
+| Body, table cells | 14 | 400 | Line height 20px |
+| Secondary, meta | 12–13 | 400 | `muted-foreground`, never lighter than 4.5:1 |
+| Labels above values | 12 | 500 | Sentence case; uppercase only with +0.04em tracking and only for tiny group labels |
+
+**Rules**
+- Two weights carry most of the screen: 400 and 600 (500 for emphasis inside dense UI).
+- **Numbers:** `tabular-nums` on number columns, prices and counters only. Never on a wrapper or the whole page: in many fonts it widens commas and full stops in sentences ("$0 . 04").
+- Right-align numbers in tables; keep units and currency symbols muted.
+- Truncate long names with an ellipsis and a `title`, never wrap table rows unpredictably.
+- `text-wrap: balance` on headings, `pretty` on paragraphs.
+- Body text never below 14px in apps (16px on phones for inputs, so iOS doesn't zoom).
+
+**Mistakes**
+- Everything at 14px with a 32px title: no hierarchy in between.
+- Light grey 12px meta text that fails contrast.
+- Mixing 13, 13.5, 14 and 15px.

package/kb/universal/type-marketing.md

@@ -0,0 +1,28 @@
+---
+id: u.type-marketing
+kind: universal
+title: Type for marketing and editorial pages
+tags: [typography, headline, hero, landing, marketing, serif, display, editorial]
+answers: How big, how tight, and how many typefaces on a landing page?
+use_when: [landing pages, product pages, pricing, about, campaign pages]
+---
+
+| Role | Desktop | Mobile | Leading |
+|---|---|---|---|
+| H1 | 56–80px | 36–44px | 1.0–1.08, tracking −0.02em |
+| H2 | 36–48px | 28–32px | 1.1 |
+| H3 | 20–24px | 18–20px | 1.25 |
+| Body | 17–18px | 16px | 1.55–1.65, 60–72 characters per line |
+| Labels | 12–13px | 12px | uppercase +0.08em only if used sparingly |
+
+**Rules**
+- One family is the safest premium move. Two at most: a characterful display face plus a quiet text face.
+- Serif headline + sans body reads warm and editorial; sans + sans reads product and speed. Pick by the brand, not by habit.
+- The grey-continuation trick: a bold first sentence followed by a muted second sentence in the same paragraph ("Every pitch in one place. *Agents do the research; you approve what changes.*").
+- One H2 style for the whole site.
+- Headline sized so it fits in two or three lines at 1440 next to its visual, not one giant word that pushes the content below the fold.
+
+**Mistakes**
+- Display type so large that the price or the product falls below the first screen.
+- A light (300) weight for headings on screen.
+- Three fonts plus an icon font plus a handwritten accent.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@palate/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Design intelligence for AI coding agents.",
+  "type": "module",
+  "bin": {
+    "palate": "bin/palate.mjs"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "prepack": "node scripts/pack-assets.mjs in",
+    "postpack": "node scripts/pack-assets.mjs out"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "axe-core": "^4.14.0",
+    "playwright-core": "^1.64.1",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "kb",
+    "skill",
+    "scripts/pack-assets.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://palate.sh"
+}

package/scripts/pack-assets.mjs

@@ -0,0 +1,58 @@
+// `npm pack` / `npm publish` helper: copies the repo's kb/, skill/ and README.md into the package before packing
+// (prepack) and removes the copies after (postpack), so the published package carries what palate reads at runtime.
+// In the repo palate reads them from the repo root (src/paths.mjs), so the copies never need to be committed.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REPO = path.resolve(PKG, "..", "..");
+const ASSETS = [
+  { from: "kb", to: "kb" },
+  { from: "skill", to: "skill" },
+  { from: "README.md", to: "README.md" },
+];
+// Never shipped: maintainers' caches and drafts inside kb/.
+const SKIP = /(^|[\\/])(\.cache|drafts|\.DS_Store)([\\/]|$)/;
+
+// palate is proprietary: screenshots of copyleft (AGPL/GPL) apps stay in the repo for the owner's use but are left
+// out of the published package, entries and images both.
+export function dropCopyleftReferences(refDir) {
+  const index = path.join(refDir, "index.json");
+  if (!fs.existsSync(index)) return 0;
+  const all = JSON.parse(fs.readFileSync(index, "utf8"));
+  const copyleft = (r) => /\b(A?GPL|LGPL|copyleft)\b/i.test(String(r.license ?? ""));
+  const out = all.filter((r) => copyleft(r));
+  for (const r of out) fs.rmSync(path.join(refDir, "thumbs", `${r.id}.jpg`), { force: true });
+  if (out.length) fs.writeFileSync(index, JSON.stringify(all.filter((r) => !copyleft(r))));
+  return out.length;
+}
+
+// The repo is private, so the README that npm shows can't use repo-relative links: images point at the copies on
+// palate.sh (palate-site/public/readme) and the docs at palate.sh/docs.
+export function publicReadme(md) {
+  return md
+    .replace(/\]\(media\/palate\/([\w-]+\.jpg)\)/g, "](https://palate.sh/readme/$1)")
+    .replace(/\]\(docs\/[\w-]+\.md(#[\w-]+)?\)/g, "](https://palate.sh/docs)");
+}
+
+const mode = process.argv[2];
+if (mode === "in") {
+  for (const a of ASSETS) {
+    const src = path.join(REPO, a.from);
+    const dst = path.join(PKG, a.to);
+    if (!fs.existsSync(src)) throw new Error(`pack-assets: ${src} is missing`);
+    fs.rmSync(dst, { recursive: true, force: true });
+    fs.cpSync(src, dst, { recursive: true, filter: (p) => !SKIP.test(path.relative(src, p)) });
+  }
+  const readme = path.join(PKG, "README.md");
+  fs.writeFileSync(readme, publicReadme(fs.readFileSync(readme, "utf8")));
+  const dropped = dropCopyleftReferences(path.join(PKG, "kb", "references"));
+  console.log(`pack-assets: copied ${ASSETS.map((a) => a.to).join(", ")} into the package${dropped ? `; left out ${dropped} copyleft reference screenshots` : ""}`);
+} else if (mode === "out") {
+  for (const a of ASSETS) fs.rmSync(path.join(PKG, a.to), { recursive: true, force: true });
+  console.log("pack-assets: removed the copies");
+} else {
+  console.error("Usage: node scripts/pack-assets.mjs in|out");
+  process.exit(1);
+}