From ffc99959adc0f7a36bcf36a02d5b50c64c59cd20 Mon Sep 17 00:00:00 2001 From: Abraham Date: Fri, 31 Jul 2026 09:22:04 -0600 Subject: [PATCH] =?UTF-8?q?Add=20the=20inspiration=20intake=E2=86=92corpus?= =?UTF-8?q?=E2=86=92graduate=20system=20(v0.5.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Turn per-build reference-study into an ongoing practice that compounds: a living inspiration corpus, a /prototype intake subcommand, and graduation rules that promote proven moves into the always-read menus. Seeded from a deep intake of 10 premium design sites. New: - reference/inspiration.md — dated/sourced/tagged corpus + graduation ledger - reference/ai-native-ui.md — the AI-native UI genre (thinking-state taxonomy, streaming, tool-call states, approval cards), zero-dep, wired to the loading engine - /prototype intake subcommand (reference/subcommands.md) Graduated from the first ten: - build.md — 3 page archetypes (single-artifact showcase, live component catalog, documentation-as-landing) + the playground pattern + legitimacy tells - color-palettes.md — dev-tool near-black, reconciled against the blue-on-black reflex - type-pairings.md — dev-tool/AI-native register (when reflex faces are earned) - microinteractions.md — number pop-in, spinner→check, dissolve, card-stack fan - ui.js — a `stream` fakeLatency kind for streaming text SKILL.md stays at 2598/2600 (intake made reachable by trimming the description). All findings from the adversarial review pass fixed before commit. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 34 ++++++++ SKILL.md | 5 +- reference/ai-native-ui.md | 97 +++++++++++++++++++++ reference/build.md | 35 ++++++++ reference/color-palettes.md | 24 ++++- reference/discovery.md | 15 ++++ reference/inspiration.md | 145 +++++++++++++++++++++++++++++++ reference/microinteractions.md | 47 ++++++++++ reference/subcommands.md | 22 +++++ reference/type-pairings.md | 19 +++- templates/scaffold-base/js/ui.js | 2 +- 11 files changed, 439 insertions(+), 6 deletions(-) create mode 100644 reference/ai-native-ui.md create mode 100644 reference/inspiration.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 712fd7e..483e63e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,39 @@ # Changelog +## v0.5.0 — 2026-07-31 + +The **inspiration-intake release** — the skill can now *learn from the web on an ongoing basis* +instead of studying a reference once and forgetting it. Seeded from a deep intake of ten premium +design sites (the Jakub Antalik showcase set, aicss, canvasui, beautiful-ui, originkit, agentation, +transitions.dev, landingfolio). + +### The ongoing loop — intake → corpus → graduate +- **A living inspiration corpus** (`reference/inspiration.md`, new) — a dated/sourced/tagged ledger + that persists a reference's distilled DNA (not screenshots) so each build compounds on the last. + On-demand, so the always-loaded router is untouched (SKILL.md stays at ~2598/2600 tokens). +- **`/prototype intake `** (new subcommand) — browse a site in full, distill its DNA, and + append a corpus entry; privacy-guarded (only the given URLs, never the user's own tabs). +- **A graduation ledger** — proven moves (recurring across ≥3 entries) promote from the corpus into + the menus the skill always reads. Discovery now reads *from* and feeds *back into* the corpus. + +### What graduated from the first ten +- **AI-native UI is now a first-class genre** (`reference/ai-native-ui.md`, new) — a zero-dep, à-la-carte + vocabulary wired to the existing loading engine: a *named* thinking-state taxonomy (Working / + Searching / Solving / Listening / Composing / Shaping, not one spinner), streaming text, tool-call + states, approval cards, tool chips, task rows, agent composer, plus AI-specific anti-slop (no violet + "AI gradient"). +- **Three page archetypes beyond the app-shell** (`build.md`) — *single-artifact showcase*, *live + component catalog*, and *documentation-as-landing* — plus the **playground pattern** (variant + toggles + slider → regenerated copy-paste code) and a few honest "legitimacy tells". +- **Two sharpened registers, reconciled with the anti-slop rules** — a *dev-tool near-black* ground + (`color-palettes.md`) that draws the exact line between the mastered version and the `blue-on-black` + reflex it already bans; and a *dev-tool / AI-native* type register (`type-pairings.md`) that explains + when the reflex faces (Inter/Geist) are *earned* — the real signature being mono-for-labels, not the + sans. +- **Four new micro-interactions** (`microinteractions.md`) — number pop-in / rolling counter, + spinner→check morph, dissolve-on-remove, and card-stack fan-on-hover — each motion-tier- and + reduced-motion-gated. + ## v0.4.0 — 2026-07-29 ### Motion tiers diff --git a/SKILL.md b/SKILL.md index a438f66..c31445b 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,6 +1,6 @@ --- name: prototype -description: Build production-feel HTML prototypes for sales demos, stakeholder reviews, and design exploration. Runs a discovery Q&A, scaffolds a zero-dep static site (HTML + Tailwind CDN + CSS variables + theme switcher + layout switcher + URL-state + feedback overlay + always-visible control bar), and runs a design-quality assessment loop. Use when the user says "prototype", "mockup", "demo", "pitch page", "sales demo", "click-through", or describes a UI they want to show someone without building the real thing. Also handles /prototype variant "" (fork a variant) and /prototype apply-feedback (apply pinned feedback JSON). +description: Build production-feel HTML prototypes for sales demos and reviews. Runs a discovery Q&A, scaffolds a zero-dep static site (HTML + Tailwind CDN + theme/layout switchers + URL-state + feedback overlay + control bar) and runs a design-quality loop. Use when the user says "prototype", "mockup", "demo", "pitch page", "sales demo", "click-through", or describes a UI they want to show someone without building the real thing. Also handles /prototype variant "" (fork a variant) and /prototype apply-feedback (apply pinned feedback JSON). --- # /prototype @@ -24,6 +24,7 @@ small vanilla JS files. /prototype → full flow: discover → build → assess → ship /prototype variant "" → fork current prototype into variants// /prototype apply-feedback → read feedback JSON, apply each comment, re-assess +/prototype intake → add sites to the inspiration corpus ``` ## The flow at a glance @@ -100,7 +101,7 @@ any screen — ask which page and how it should change (feel, layout, content, a apply it to just that screen, re-verify, and loop until they're happy. A prototype earns its keep by being iterated, not shipped once. -Subcommands (`variant`, `apply-feedback`) → `reference/subcommands.md`. +Subcommands (`variant`, `apply-feedback`, `intake`) → `reference/subcommands.md`. ## Non-negotiable constraints diff --git a/reference/ai-native-ui.md b/reference/ai-native-ui.md new file mode 100644 index 0000000..3eefad1 --- /dev/null +++ b/reference/ai-native-ui.md @@ -0,0 +1,97 @@ +# AI-native UI — components for agent & LLM interfaces + +Half the inspiration corpus (`reference/inspiration.md`) is about one emerging genre: interfaces +where an **agent or model is a first-class actor** — it thinks, streams, calls tools, proposes +actions, and asks for approval. If the prototype is an AI product (chat, agent console, copilot, +LLM tool), reach for this vocabulary the way a dashboard reaches for KPI cards. All of it is +zero-dep and rides the scaffold engine you already have (`js/ui.js`: `fakeLatency`, `withLoader`, +`announce`, `data-skeleton-*`; motion tiers on `html[data-motion]`). + +**Read this when** `DESIGN.md` register is an AI/agent product. **Register defaults for it:** motion +tier **calm or standard** (these are tools — cinematic motion is friction; the *one* exception is a +brand/landing page *about* an AI product, which goes expressive); icon stance **functional**; the +"signature move" is usually one of the states below done unusually well, not a decorative flourish. + +## The inventory (the checklist) + +Pulled from aicss.dev + beautiful-ui + orbs. Treat as an à-la-carte menu — build the ones the +product actually shows, skip the rest (respect scope). + +| Component | What it is | Zero-dep mechanic | +|---|---|---| +| **Thinking / reasoning** | agent is working, before output | see state taxonomy below; optional collapsible reasoning trace | +| **Streaming text** | tokens arriving live | reveal word-groups on a timer + a blinking caret; run through `fakeLatency('stream')` | +| **Tool-call / action state** | agent runs a tool (search, read file, run cmd, gen image) | a labeled card: pending → running (spinner/shimmer) → result; `withLoader` around the fake work | +| **Approval card** | agent proposes an action, needs a yes | summary + diff/preview + Approve/Reject; optimistic-with-undo on Approve | +| **Tool chips** | compact inline status | small pill: icon + label + state dot (queued/running/done/error) | +| **Task rows / plan** | agent's to-do list, live | rows with a per-item status (○ pending · ◐ running · ✓ done); check them off on a timer | +| **Agent composer** | the input | textarea + model/mode pickers + attach + send; disabled→busy→ready; ⌘↵ to send | +| **Structured output** | tables the model emitted | the scaffold `.table` inside `.proto-table-wrap` (the 390px overflow guard); records / comparison / diff / filter are content patterns, not separate classes | +| **Citations / context cards** | sources behind an answer | inline superscript links + a source card (favicon + title + domain) | +| **Insight / recommendation card** | a suggestion with confidence | claim + a confidence chip + a sparkline or a one-number reason | + +## Thinking is not one spinner — it's a named taxonomy + +`orbs` names six agent states — **Working · Searching · Solving · Listening · Composing · Shaping** — +each a distinct animation in a labeled pill. That's the lesson: a generic spinner says "loading"; +a *named* state ("Searching the web…", "Reading `auth.ts`…", "Composing the reply…") tells the user +what's happening and reads as a real system. Give the current step a **specific label**, not "Loading." + +- **Ambient indicator** (zero-dep, no WebGL): a small pulsing dot-ring, a shimmering glyph, or a + 3-dot bounce — one per state, tinted with the accent. A CSS dot-sphere or `conic-gradient` spinner + carries the same read as the WebGL orb without the dependency. +- **Reasoning trace** (optional): a collapsible "Thought for 4s ▸" that expands to a muted, + monospace list of steps. Collapsed by default. This is aicss's "Thinking + Reasoning" block. +- **A11y:** the thinking region sets `aria-busy="true"` on itself and posts each state label through + the scaffold's `announce()` (its polite live region); clear `aria-busy` and announce the result when + the answer lands. Note `announce()` only *speaks* — managing `aria-busy` is yours here (the scaffold + toggles it automatically only for `data-skeleton` containers, not a custom thinking region). + +## Streaming text — the mechanic + +Reveal in **word groups**, not per-character (per-char is slower to read and jankier). A caret +(`▍`) blinks at the tail while streaming, removed when done. Gate it on `data-motion`: **calm** +skips the animation and paints the full text (respect the scanning user); `prefers-reduced-motion` +always paints instantly. Drive the cadence through `fakeLatency('stream')` so the Loading Speed +control in the tweaks bar scales it (Instant paints immediately). + +## Tool-call & action states — the pattern + +Every tool call is a tiny three-state lifecycle: **pending → running → result|error**. Model it as a +card (or chip) that: +1. mounts in *running* with a labeled shimmer ("Searching the web…"), +2. resolves via `withLoader(fakeWork, …)` so the spinner-delay + min-visible discipline applies + (no flash on fast calls), +3. lands on a **result** (search hits, a file diff with red/green gutter, a generated-image frame) + or a **scoped error + Retry** (the `.state--error` component). + +This is the AI-native application of the loading/state engine already in the scaffold — reuse it, +don't reinvent it. + +## Approval & the human-in-the-loop + +When the agent proposes a mutation (send email, run migration, place order), show an **approval card**: +a plain-language summary + a preview/diff + **Approve / Reject**. On Approve, use +**optimistic-with-undo** (`UI.undoToast`) rather than a blocking confirm — the action appears done +with a 5s Undo, matching the microinteractions doctrine. Destructive proposals name the consequence +in the button ("Approve & send"), never a bare "OK". + +## Demo content — make the agent's world real + +Never "lorem" an AI demo — the fake content is what sells it. Give the agent a **specific domain** +(beautiful-ui themes its whole demo around a coffee roaster) and write real-sounding intermediate +work: actual file paths in the diff, plausible search results with real-looking domains, a to-do +list with domain tasks ("Scaffold the component registry", "Wire up Stripe checkout"). Generic +"Task 1 / Task 2" content is the tell that this isn't a real product. + +## Anti-slop for AI UIs + +- **No purple/violet "AI gradient."** The lazy signifier for "this is AI" is a violet→blue glow — + it's the #1 tell (`color-palettes.md`). An AI product earns its look like any other; one accent, + tinted neutrals. +- **One spinner style, named.** Don't scatter three different loaders; pick one thinking indicator + and label its states. +- **Don't fake streaming on static text** that was never generated (a nav label, a heading) — it + reads as a gimmick. Stream only what the model would actually produce. +- **Monospace with intent.** Mono belongs on code, diffs, file paths, token counts — not the whole + UI (see `type-pairings.md`: "mono is not a costume"). diff --git a/reference/build.md b/reference/build.md index f109943..7220ceb 100644 --- a/reference/build.md +++ b/reference/build.md @@ -554,6 +554,41 @@ One HTML file per screen. Each screen: - **Tight-leading display type needs clearance.** An oversized heading/wordmark with `line-height` below 1 (`leading-none`, `leading-[0.8]`, etc.) clips its own descenders/ascenders out of the line box — the glyphs are still there, just outside the box the layout thinks it reserved. Pair any such heading with `padding-bottom` (~0.15–0.25em of its font-size) or `margin-bottom` so a period or descender never collides with the next block. Tight leading is fine; tight leading with a flush neighbor and no clearance isn't. - **Icons & imagery.** *Decide the icon role from the register — `DESIGN.md` names it (discovery.md Step 4) — don't leave density to chance.* **Product** register (dashboards, tools, app shells): icons are **functional** — they carry affordances (nav destinations, row/card actions, status, controls); a product screen with no action or nav icons is usually under-built. **Brand** register (landing, pitch, editorial): icons are **earned, not default** — lead with type and space, use an icon only where it removes ambiguity (a play control on an audio CTA), never decorative above headings; zero icons is a legitimate, deliberate outcome. Where you do use them: inline SVG copied from [reicon.dev](https://reicon.dev) (MIT, 2,700+, multiple weights) at **one** weight — never a big rounded icon above every heading. `brands.reicon.dev` covers real-looking logos. For photos, follow "Real imagery for photo-forward products" below — a glyph tile is a fallback, never the plan. +### Page archetypes — beyond the app-shell + +Most prototypes are an app-shell (nav + screens). But three other whole-page shapes recur in the +best work (`reference/inspiration.md`) and fit specific briefs — pick the archetype in discovery, name +it in `DESIGN.md`, don't default to app-shell for everything: + +- **Single-artifact showcase** (beam / metal / orbs) — the page *is* one component, shown off. Centered, + quiet OKLCH-tinted near-black, one **hero live demo**, then `Installation → Usage → Playground`. + For a pitch of a single feature, effect, or primitive. Its engine is the **playground pattern** + below. Signature belongs on the artifact, not the chrome; GitHub/X pair + "Made by —" footer. +- **Live component catalog** (aicss / transitions.dev / beautiful-ui / originkit) — a category-labeled + grid (or left-TOC list) of **real running demos**, never screenshots. Each tile: the live thing + a + **name + one-line mechanic** + a copy affordance; band label + count on the right. For a library, + design-system, or "here's everything it does" page. Keep tiles as quiet frames so the content reads. +- **Documentation-as-landing** (agentation) — a technical product typeset as a beautiful *document*: + left TOC, numbered how-to, inline code chips, an **embedded working demo** inside the prose, one + expressive flourish (a script wordmark) on an otherwise-neutral face, "Made by / Colophon" footer. + For a dev tool / API / agent product where the audience is technical and prose is the pitch. + +**The playground pattern** (the showcase's engine, reusable anywhere): variant **toggles** (pill +segmented controls) + a **slider** drive a live preview *and* regenerate a copy-paste code/spec block +in real time. It's the control-bar philosophy (`Visible control bar` above) applied to one element — +wire it through `State.set()` so the shown config and the emitted snippet never drift, and put a +copy-as-label-swap button (`UI.copyButton`) on the snippet. + +**Legitimacy tells** (cheap, and they read as "a real team shipped this"): an `npm install …` line +with a copy button in the hero; a small **Pro** badge on premium items; a GitHub/X icon pair +top-right; a "Made by — / Colophon" footer; an inline "new stuff, in your inbox" capture. Use a few, +honestly — they're texture, not a checklist to spam. + +**AI / agent products → `reference/ai-native-ui.md`.** If the prototype has an agent or model as an +actor (chat, copilot, agent console), that file is the component vocabulary — thinking-state taxonomy, +streaming text, tool-call states, approval cards, task rows — all zero-dep and wired to the loading +engine. Don't invent AI UI from scratch; it has its own genre now. + ### Real imagery for photo-forward products Marketplaces, listings, and profiles can't demo credibly on placeholders — a reviewer diff --git a/reference/color-palettes.md b/reference/color-palettes.md index c08d2ec..e9fbfec 100644 --- a/reference/color-palettes.md +++ b/reference/color-palettes.md @@ -27,7 +27,8 @@ each deliberately dodges its category-reflex cliché. Preview them live in `desi - **Dark mode ≠ inverted light**: elevate with *lighter surfaces* (`surface` < `elevated` < `elevated-2`), not shadow; desaturate the accent; drop body weight a notch. - **Category-reflex check**: if the palette is guessable from the domain (finance→navy/gold, - health→teal/white, crypto→neon, dev-tool→blue-on-black), rework it. + health→teal/white, crypto→neon, dev-tool→blue-on-black), rework it. (One defined exception: the + *earned* near-black — no glow, no guessable accent — in "dev-tool near-black" below.) - **AI-editorial reflex check — passing the category-reflex check above is NOT enough.** A warm cream/paper or warm-carbon ground + a display serif + one lone amber/terracotta/oxblood accent is its own cross-domain "a machine made this" tell, independent of domain — a podcast site that @@ -93,6 +94,22 @@ surface, not a second hue. No card chrome, oversized whitespace, one near-invisi - **Light:** `#f8f6f1 · #fcfaf6 · #fefdfa · #26231f · #5c5750 · #8c867d · #e2ded6 · #f0ece4 · #3c2e24 · #faf7f2` - **Dark:** `#161411 · #1f1c18 · #292520 · #ede8e0 · #b0a99f · #847e75 · #342f29 · #26221d · #e9e3d9 · #181512` +### dev-tool near-black — earned monochrome · restrained (cross-tone ground) +Not a tone row — a **ground strategy** the premium dev-tool / AI sites in `reference/inspiration.md` +share (8 of 10 are near-black). It sits one inch from the **`dev-tool→blue-on-black` reflex banned +above**, so the line matters — and the line is *not* "pure `#000` vs tinted." The banned reflex is the +guessable dev-tool cliché: an accent (classically blue or neon) *glowing* on black. The earned version +keeps the near-black but removes **both** the glow **and** the guessable accent — distinctiveness comes +from the mono-label type register and one signature moment, not from color. Use only for a genuine +developer-tool / AI brief; if you're reaching for a glow or a blue to justify it, you're back in the reflex. +- **Dark:** `#0b0b0d · #141417 · #1c1c20 · #ececf0 · #a8a8b0 · #78787f · #2a2a30 · #201f25 · #ececf0 · #0b0b0d` + — the "accent" is a **monochrome inversion** (near-white on near-black), like `quiet` — no hue at all + is the strong default here. If the brief genuinely needs one, add exactly one **desaturated** hue that + is **not blue or green** (both *are* the dev-tool cliché this dodges) — a muted clay/amber like + `#b0805a` reads as chosen — on ≤5% of the surface, never a neon, never a glow, never a gradient. +- **Light counterpart:** don't invert to gray — use any tinted-light row above (e.g. `minimal`); this + register is dark-first, so ship the dark theme as the primary. + Free-text tones: map to the nearest row or shift the hue deliberately; keep the tinting + one-accent discipline. ## Anti-slop — never ship these @@ -102,7 +119,10 @@ default** (the #1 tell) · gray text on a colored ground (use a tint of the grou ## Contrast (verified, WCAG) -Body `ink` on `surface` clears 4.5:1 in both themes for all nine. Three honest flags: +Body `ink` on `surface` clears 4.5:1 in both themes for all nine tone rows. Four honest flags: +- **dev-tool near-black** (the cross-tone ground, not counted in the nine): its mono-inversion accent + trivially clears; if you add the optional clay/amber hue, verify it — `#b0805a`(~L0.62) on `#0b0b0d` + clears AA for a small chip/underline, but it's a fill role, not body text. - **`ink3`** (tertiary — timestamps, placeholders, captions) is AA-*Large* only in light mode. Never set body copy in it; use `ink2` for anything essential. - **playful marigold / bold lime** accents are **fill** roles (button background + `accent-ink` diff --git a/reference/discovery.md b/reference/discovery.md index 4c96258..416b1c8 100644 --- a/reference/discovery.md +++ b/reference/discovery.md @@ -54,6 +54,21 @@ a copy of the source: density), not the paint — see "Choosing layouts" (Step 3) for the category vocabulary. - **Accent** — the one accent move: which color, and how much of the surface it spends. +### The living corpus — read it, feed it + +The reading above is per-build; `reference/inspiration.md` is where it **persists** so the skill +compounds. Use it both directions: + +- **Read from it** — once tone (Step 2) and register (Step 4) are set, skim the corpus for entries + whose **register/genre matches** and pull concrete, zero-dep moves into the direction (e.g. a dev-tool brief → + the near-black + mono-label + playground moves the corpus already distilled). It's on-demand, so it + costs the router nothing. +- **Feed it** — when you study a genuinely good new reference, persist it as a corpus entry (schema at + the top of that file), or tell the user to run `/prototype intake ` (`reference/subcommands.md`). + When a move recurs (≥3 entries is the trigger for a cross-site pattern — though a single site can + still graduate a self-contained move that's obviously right), propose promoting it into the menus. + This is the "ongoing" loop: **intake → corpus → graduate.** + ### No reference? Point at a curated gallery Route by what you're building — these are inspiration sources, not built-in skill categories: diff --git a/reference/inspiration.md b/reference/inspiration.md new file mode 100644 index 0000000..2a8bbd5 --- /dev/null +++ b/reference/inspiration.md @@ -0,0 +1,145 @@ +# Inspiration corpus — a living, graduating ledger + +The skill already reads a **shared reference's DNA** per build (`reference/discovery.md` → +"Reading a shared reference"). This file is where that reading **persists** so each build gets +smarter than the last. It is a staging area, not a style to copy: entries are distilled to +*lessons*, and proven lessons **graduate** into the always-consulted menus. + +The loop is **intake → corpus → graduate**: + +1. **Intake** — study a site (by hand, or `/prototype intake `, see `reference/subcommands.md`). + Append a distilled entry below. Never copy a site; extract what's transferable. +2. **Corpus** — during discovery, after tone/register are set, skim the entries whose **register** + matches and pull concrete moves into the direction. This file is on-demand (read only when + relevant), so it costs the always-loaded router nothing. +3. **Graduate** — when a move recurs across **≥3 entries** (or is just obviously right), promote it + into the menu the skill *always* reads (`color-palettes.md`, `type-pairings.md`, `build.md`, + `microinteractions.md`, `ai-native-ui.md`) and tick it in the **graduation ledger** at the bottom. + The corpus is the memory; the menus are the muscle. + +**Entry schema** (keep it this tight — lessons, not screenshots): + +``` +### — (studied YYYY-MM-DD) +Register: + genre (dev-tool / editorial / AI-native / …) · Motion: · Ground: <…> · Type: <…> +Signature: +Steal: +Avoid: +Graduates → +``` + +> A note on the reflex faces. Several entries below run **Inter/Geist + a mono** — families the skill +> normally rejects (`type-pairings.md`). That is not a contradiction to wave through: those faces are +> banned *as a default*, and these sites earn them by spending the whole distinctiveness budget +> elsewhere (tinted near-black ground, a mono-label companion, one signature motion moment). The +> lesson that graduated is the **discipline**, not "Inter is fine now" — see the dev-tool notes in +> `type-pairings.md` and `color-palettes.md`. + +--- + +## Family ① — Indie-dev single-artifact showcase + +The recurring template across the Jakub Antalik set: pure, OKLCH-tinted near-black, one system sans, +centered, **one hero live demo**, then `Installation / Usage / Playground` where **variant toggles + +a slider regenerate a copy-paste snippet in real time**. The effect *is* the content; the chrome +disappears. GitHub+X icon pair top-right, "Made by —" footer. Reads as a real indie product, not a +pitch. + +### beam (Border Beam) — beam.jakubantalik.com (studied 2026-07-31) +Register: dev-tool/brand · Motion: expressive · Ground: near-black #070707, accent = the gradient beam (only color on the page) · Type: Inter +Signature: single-artifact showcase — the animated border travels an AI-composer input; a live Playground (Type/Color/Strength) rewrites the code below as you toggle. +Steal: the playground-regenerates-code pattern; accent-as-a-single-moving-event on mono; the GitHub/X pair + "Made by" footer as legitimacy tells. +Avoid: the beam itself is fine in pure CSS (conic-gradient + mask), but keep it to ONE surface. +Graduates → build.md ("single-artifact showcase" archetype + playground pattern) + +### metal (Liquid Metal) — metal.jakubantalik.com (studied 2026-07-31) +Register: dev-tool/brand · Motion: expressive · Ground: near-black #070707, no flat accent (the chrome shader IS the color) · Type: Inter +Signature: same showcase template; Playground adds Style/Type/Color/Strength + on/off Options (No Glow / No Reflection) → live `` code. +Steal: option *toggles as boolean chips* alongside variant pickers; a metallic sheen is approximable with an animated gradient + blend mode. +Avoid: the real thing is a WebGL shader — not zero-dep. Approximate or skip; don't import three.js. +Graduates → build.md (playground pattern) + +### orbs (Thinking Orbs) — orbs.jakubantalik.com (studied 2026-07-31) +Register: dev-tool/brand · Motion: expressive · Ground: near-black #070707 · Type: Inter +Signature: a 6-cell grid of **AI thinking-states** (Working · Searching · Solving · Listening · Composing · Shaping), each a distinct particle animation in a status pill; Playground toggles State/Size/Speed. +Steal: the *named taxonomy of agent states* — treat "thinking" as many distinct, labeled moments, not one spinner. Directly seeds `ai-native-ui.md`. +Avoid: particle spheres are WebGL; a CSS/canvas-2D dot-ring or pulsing glyph carries the same read. +Graduates → ai-native-ui.md (thinking/working state taxonomy) + +### transitions.dev — transitions.dev (studied 2026-07-31) +Register: product + genre dev-tool · Motion: expressive · Ground: near-black #121212 · Type: Inter + Saans +Signature: the catalog form of the same author — ~36 micro-interaction tiles, each a live demo with an "Animate" trigger, a **name + one-line mechanic** ("Distance falloff with bouncy return"), and a copy button; Pro items badged. +Steal: the **naming discipline** (every effect gets a name AND a one-sentence mechanic); tiles as quiet frames so motion reads; Pro-badge as a legitimacy tell. +Avoid: it's a paid catalog — don't reproduce it; mine it for individual effects. +Graduates → microinteractions.md (number pop-in, spinner→check morph, dissolve-on-remove, card-stack fan) + +--- + +## Family ② — AI-native component catalog + +Dark, a system-sans (most **+ a mono for labels** — originkit sets *every* label in mono; aicss is the +one that stays sans-only), category-labeled grids of **live** demos (never screenshots), "built for +agents", shadcn/copy-paste install. Together +they define an emerging genre the skill now has words for (`ai-native-ui.md`). + +### aicss — aicss.dev (studied 2026-07-31) +Register: dev-tool/product · Motion: standard · Ground: near-black #0a0a0a, one faint blue on the logo · Type: Inter +Signature: two-tone headline (white line + grey line), pill eyebrow, single CTA, then category-labeled card grids (Thinking · Tool & Action States · Text Outputs · Structured Outputs · Rich & Interactive) each a real running block. +Steal: the AI-native component *categories* as a checklist; category label + count on the right of each band; monochrome cards with subtle borders. +Avoid: — +Graduates → ai-native-ui.md (component taxonomy) + +### canvasui — canvasui.dev (studied 2026-07-31) +Register: dev-tool/brand · Motion: expressive · Ground: near-black, lab() color space · Type: Geist Sans + Geist Mono +Signature: "Creative components, in a new dimension" — numbered how-it-works (01/02/03), shadcn-CLI install, WebGL hero showcase card, FAQ. +Steal: numbered install/steps *when the content is genuinely sequential*; Geist+GeistMono as the honest modern-dev register (with the reflex caveat). +Avoid: the components are live WebGL — the *page craft* transfers, the canvas components don't. +Graduates → type-pairings.md (dev-tool register note) + +### beautiful-ui — beautiful-ui-five.vercel.app (studied 2026-07-31) +Register: product/dev-tool · Motion: standard · Ground: #1b1c1e · Type: Inter + JetBrains Mono +Signature: a long left-TOC catalog of AI-native primitives (Loading · Thinking · Streaming Text · Approval Card · Tool Chips · Task Rows · Chat · Recommendation · Context Cards · Diff/Records/Filter tables), demoed on **real editorial data** (coffee/flavors — same instinct as our Cardinal Coffee demo). +Steal: the primitive list is the single best inventory of AI-native components; sparkline-in-a-card; status pills; "New components, in your inbox" capture. +Avoid: — +Graduates → ai-native-ui.md (primitive inventory) + +### originkit — originkit.dev (studied 2026-07-31) +Register: product + genre dev-tool · Motion: expressive · Ground: #1e1e1f, orange accent (logo + one link only) · Type: Roboto Mono for ALL labels +Signature: an app-shell component browser — left rail with categories + counts (Text 61 · Button 5 · Image 14 · Cursor 6 …), ⌘K search, grid of dark video thumbnails. +Steal: **mono-for-every-label** as a deliberate developer register; category+count sidebar; ⌘K as the search affordance (already in the nav catalog). +Avoid: the components are generative/WebGL showpieces; the shell + mono-label discipline is what transfers. +Graduates → type-pairings.md (mono-label signal) + +--- + +## Family ③ — Editorial / meta + +### agentation — agentation.com (studied 2026-07-31) +Register: editorial/brand · Motion: standard · Ground: light/white, red accent used *only* on wordmark + one hand-drawn underline · Type: Inter + IBM Plex Serif + SF Mono +Signature: **documentation-as-landing** — a technical product typeset as a beautiful document: left TOC, script-cursive wordmark as the one flourish, numbered how-to, inline code chips, an embedded *working* demo (live buttons/inputs to annotate), "Made by / Colophon" footer. +Steal: the whole "docs page that is also the landing" archetype for technical/dev products; the ONE expressive flourish (script wordmark) on an otherwise-neutral face; hand-drawn underline as a warm accent; live-demo-embedded-in-prose. +Avoid: the annotation tooling is a real product; the *presentation* is the lesson. +Graduates → build.md ("documentation-as-landing" archetype) + +### landingfolio — landingfolio.com/inspiration/landing-page (studied 2026-07-31) +Register: product (a resource, not a design to copy) · Motion: calm · Ground: white, oklch() · Type: Plus Jakarta Sans +Signature: a filterable gallery — thumbnails **tagged (industry/color/device) + dated + sourced**, left-rail filters, lazy-loaded grid. +Steal: this is the model for *this file itself* — inspiration stored as tagged, dated, sourced entries you can filter by register. Use as an ongoing *source* to intake from, not a look to reproduce. +Avoid: it's a directory; don't clone its chrome. +Graduates → (meta) informed the corpus schema + +--- + +## Graduation ledger + +| Move | From (entries) | Graduated to | Status | +|---|---|---|---| +| Single-artifact showcase archetype | beam, metal, orbs | `build.md` → Page archetypes | ✅ 2026-07-31 | +| Playground: toggles + slider → regenerated code | beam, metal, orbs | `build.md` → Page archetypes | ✅ 2026-07-31 | +| Documentation-as-landing archetype | agentation | `build.md` → Page archetypes | ✅ 2026-07-31 | +| Live component-catalog archetype | aicss, transitions, beautiful-ui, originkit | `build.md` → Page archetypes | ✅ 2026-07-31 | +| Near-black *earned* vs blue-on-black *reflex* | 8/10 entries | `color-palettes.md` → dev-tool near-black | ✅ 2026-07-31 | +| Inter/Geist + mono-label = dev-tool register (with reflex caveat) | canvasui, originkit, aicss, beautiful-ui | `type-pairings.md` → dev-tool register | ✅ 2026-07-31 | +| AI-native UI vocabulary (thinking/streaming/tool-call/approval…) | aicss, beautiful-ui, orbs, agentation | `ai-native-ui.md` (new) | ✅ 2026-07-31 | +| New micro-interactions (number pop-in, spinner→check, dissolve-on-remove, card-stack fan) | transitions.dev | `microinteractions.md` | ✅ 2026-07-31 | +| npm-install snippet · Pro badge · GitHub/X pair · Colophon = legitimacy tells | family ①+② | `build.md` → Page archetypes → Legitimacy tells | ✅ 2026-07-31 | diff --git a/reference/microinteractions.md b/reference/microinteractions.md index 68df0f8..5e351e2 100644 --- a/reference/microinteractions.md +++ b/reference/microinteractions.md @@ -266,6 +266,53 @@ toast, because the user can't otherwise tell the action didn't work. - It's undoable and time-limited — that's the Undo-toast case above, which is a toast whose job is the Undo affordance, not the confirmation itself. +### Number pop-in / rolling counter + +**Rationale:** a KPI or total that *animates to* its value draws the eye to the one number that +changed — but only when it genuinely just changed (a live metric, a result landing). Animating every +number on page load is decoration. + +**Mechanic (zero-dep):** count from a start to the target over ~500–800ms with `requestAnimationFrame`, +easing out; write `tabular-nums` so the width doesn't jitter mid-count. For a small +1/-1 (a badge), +skip the roll — just a quick scale pop (`transform: scale(1.15)→1` over 150ms). **Gate on motion:** +`calm` and `prefers-reduced-motion` paint the final number instantly; drive the duration through the +loading-speed engine so the tweaks bar scales it. + +### Spinner → check morph + +**Rationale:** when a loading action succeeds, morphing the *same* spinner into a checkmark (rather +than swapping in a separate success element) keeps the user's eye anchored on one spot and reads as +"this finished," not "something new appeared." + +**Mechanic:** one SVG circle whose `stroke-dasharray` spins while pending, then on resolve stops and a +check path draws in (`stroke-dashoffset` 100→0 over 250ms). Pairs with `withLoader` (min-visible +discipline) so the check is actually seen on fast calls. On failure, morph to a shake + `.state--error` +instead — never a check. This is the AI-native tool-call "done" state (`reference/ai-native-ui.md`). +**Reduced-motion / calm:** skip the spin and the draw-in — swap straight to a static check (or error) +icon the moment the call resolves. + +### Dissolve on remove + +**Rationale:** deleting a row/card with a soft dissolve (rather than an instant vanish or a full +"smoky" particle effect) tells the user *which* thing left and where — the gap closing confirms the +delete without a toast. The particle/smoke version from the corpus needs canvas; the dissolve carries +the same read in pure CSS. + +**Mechanic:** on remove, transition `opacity 1→0` + a slight `filter: blur(4px)` + `scale(0.98)` over +~200ms, then collapse the height via `grid-template-rows: 1fr→0fr` (see "Height changes" above) so +neighbors slide up. **Reduced-motion / calm:** skip straight to the height collapse, no blur. + +### Card-stack fan on hover + +**Rationale:** a stacked set (saved items, versions, a deck) that **fans slightly on hover** signals +"there's more than one here, and it's browsable" — a discoverability cue, not eye-candy. Only earn it +when the stack really holds multiple things the user can act on. + +**Mechanic:** absolutely-stack the cards with a small `rotate`/`translate` offset per depth; on the +container's `:hover`/`:focus-within`, widen the offsets via `transform` (GPU-cheap). Keep it subtle +(≤6° / ≤12px) — a big fan reads as a toy. **Gate on motion:** `calm` shows the stack static with a +count badge instead; `prefers-reduced-motion` never fans. + ## Motion tells to avoid Named failure patterns — the visual signatures of un-crafted, generated-looking diff --git a/reference/subcommands.md b/reference/subcommands.md index 8579047..9650cca 100644 --- a/reference/subcommands.md +++ b/reference/subcommands.md @@ -11,6 +11,28 @@ Fork the current prototype into a sibling folder to explore an alternative direc 5. Run the same build → assess loop on the variant. 6. Leave the original untouched. Output: "Original at `/`, variant at `/variants//`." +## /prototype intake + +Absorb one or more sites into the living inspiration corpus (`reference/inspiration.md`) so future +builds get smarter. This is the "ongoing" half of the skill — run it whenever you see something good. + +1. For each URL, open it in a **fresh** browser tab (never reuse the user's active tab — it clobbers + their work). Use the session's browser tooling (claude-in-chrome, or the user's harness). If no + browser is available, fall back to fetching the HTML and note that the read is structure-only. +2. **Intake the whole thing, not a few clicks** — full-page screenshot(s) + structural extraction + (headings, nav, CTAs, computed body bg/color, font families, canvas/video counts, page height). + Scroll long or lazy-loaded pages so below-the-fold and scroll-triggered content actually render. +3. Distill to **DNA, not pixels** (`reference/discovery.md` → "Reading a shared reference"): register, + motion tier, ground+accent, type, the one signature move, what's zero-dep **Steal**-able, what does + **not** transfer (needs a build / WebGL / a backend). +4. Append an entry using the schema at the top of `reference/inspiration.md` (dated, sourced, tagged). + Group it under the right family, or start a new one. +5. If a move now recurs (**≥3 entries** for a cross-site pattern, or a single self-contained move + that's obviously right), propose graduating it into the menus and add a row to the graduation + ledger. Don't silently rewrite the menus — surface the promotion for a yes first. +6. **Privacy:** only intake the URLs given. If a tab lands on the user's own content (a logged-in app, + a private repo), discard it and re-navigate — never absorb it into the corpus. + ## /prototype apply-feedback 1. Read the feedback JSON. Validate the structure. diff --git a/reference/type-pairings.md b/reference/type-pairings.md index 1e7beb9..b208dde 100644 --- a/reference/type-pairings.md +++ b/reference/type-pairings.md @@ -55,6 +55,22 @@ flourish. **quiet** (minimal) commits to Instrument Sans alone, a quiet neo-grot not Geist, and not reaching for the menu's already-common Public Sans / Hanken Grotesk either. All three (plus IBM Plex Mono) are Google Fonts and already off the reflex-reject list below. +**The dev-tool / AI-native register — when the reflex faces are earned.** The premium dev-tool and +AI-product sites in `reference/inspiration.md` (canvasui, aicss, beautiful-ui, originkit, the Antalik +set) run **a system sans + a mono for labels** — often the very faces this table rejects (Inter, +Geist). That is not a loophole: those faces are banned *as a default*, and these sites earn them by +spending the entire distinctiveness budget elsewhere — an OKLCH-tinted near-black ground, one +signature motion moment, and above all a **mono companion carrying every label, count, path and +token** (originkit sets *all* labels in mono). The register's real signature is that mono discipline, +not the sans. So for a genuine developer-tool / AI brief: +- Reach first for the **technical / carbon** rows above (Hanken · Schibsted Grotesk · IBM Plex Sans + + JetBrains Mono / IBM Plex Mono) — they *are* this register, one notch less defaulted than Inter. +- Inter/Geist are permissible **only** when the brief is truly this category (a characterful display + would read as trying-too-hard) **and** the budget is spent on ground + mono + motion. Even then + Geist copies the category leader (Vercel) — use it only when the brief explicitly asks to read like + Vercel/Linear, and prefer the grotesque otherwise. +- The move to actually steal: **mono-for-labels as a deliberate signal**, not the reflex sans. + Free-text tones: map to the nearest row or combine deliberately (e.g. "warm + technical" → a grotesque display with a humanist body like IBM Plex Sans). One family in several weights often beats two competing typefaces — only add a second face for genuine contrast. @@ -63,7 +79,8 @@ beats two competing typefaces — only add a second face for genuine contrast. **Inter · Roboto · Open Sans · Lato · Montserrat · Arial · raw `system-ui` as the brand face.** Fine for docs or a pure tool where personality isn't the goal; wrong for a prototype meant to -impress. Two anti-reflexes: +impress. **Sole exception:** the dev-tool / AI-native register above, under its stated conditions +only (budget spent on ground + mono + motion) — never elsewhere. Two anti-reflexes: - **Mono is not a costume.** Use a monospace for numbers/code/eyebrows, never as lazy "developer vibes" across the whole UI. diff --git a/templates/scaffold-base/js/ui.js b/templates/scaffold-base/js/ui.js index 0468815..690cc56 100644 --- a/templates/scaffold-base/js/ui.js +++ b/templates/scaffold-base/js/ui.js @@ -55,7 +55,7 @@ // metronomic. nav is a cheap route change; read fetches a list/detail; mutate is // a save/submit; upload is the deliberately-slow outlier. function fakeLatency(kind) { - const base = ({ nav: 220, read: 700, mutate: 380, upload: 2200 })[kind] || 600; + const base = ({ nav: 220, read: 700, mutate: 380, upload: 2200, stream: 90 })[kind] || 600; const jitter = 0.45; // ±45%, never uniform return (base * (1 - jitter) + Math.random() * base * 2 * jitter) * SPEED[speedMode]; }