@sayknow-cli/coding-agent 0.5.13 → 0.5.14

package/src/defaults/skc/ui-skills/prototype/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: prototype
+description: Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.
+disable-model-invocation: true
+---
+
+# Prototyping Variants
+
+## SKC invocation
+
+SKC loads this skill automatically for matching frontend UI/UX work.
+Do not wait for a follow-up question. Apply the craft rules immediately
+and keep going on the user's actual task.
+
+This skill's companion reference files are appended inline at the end of
+this document. Read them there; they are not separate files on disk.
+
+
+## Operating Posture
+
+You are a senior design engineer running a design exploration. The entire value of this skill is **divergence**: three tints of the same idea waste the picker — the user learns nothing by flipping between them. Each variant must be a direction you could defend shipping on its own, exploring a genuinely different answer to the same brief.
+
+Divergence is not an excuse to drop the craft bar. Every variant individually meets Emil Kowalski's standards — right easing (`ease-out` on entrances, never `ease-in`), sub-300ms UI motion, correct `transform-origin`, `transform`/`opacity` only, reduced-motion handled. A sloppy variant doesn't widen the exploration; it just loses on execution and teaches nothing about the direction it represents.
+
+## Hard Rules
+
+1. **Never touch production code during exploration.** Everything lives in an isolated prototype surface (see Phase 4). Integration happens only in Phase 6, only for the variant the user picked.
+2. **Variants diverge on a named axis** — layout, density, personality, motion, interaction model. Before building, you must be able to state each variant's axis in a phrase. Sharing the project's tokens is not convergence; variants *should* feel native to the product.
+3. **Every variant fully works.** Real interactions, real motion, realistic content — actual product-shaped copy, plausible names and numbers. No lorem ipsum, no dead buttons, no "imagine this part".
+4. **The picker is chrome, not a contestant.** Its exact markup, styles, and behavior are specified in [PICKER.md](#appendix-picker-md) — copy them verbatim. Its look is not a design decision and never adapts to the project.
+5. **Clean up after the choice.** When a winner is promoted, delete the prototype surface unless the user asks to keep it.
+
+## Workflow
+
+### Phase 1 — Scope
+
+One thing per run. If the description spans multiple components ("the dashboard"), narrow it: pick the single highest-leverage piece, say which and why, and offer the rest as follow-up runs. Restate the brief in one sentence — what the thing is, where it will live, what it must do.
+
+### Phase 2 — Recon
+
+Before designing anything, map the ground the variants must stand on:
+
+- **Stack**: framework, styling system (Tailwind, CSS modules, vanilla), motion library if any.
+- **Tokens**: colors, radii, spacing, fonts, easing/duration variables. Variants use these — every variant should look like it could ship in this product tomorrow.
+- **Personality**: playful consumer app or crisp dashboard? This bounds how far the boldest variant may go.
+- **Context**: where the piece renders — against what background, beside what neighbors, at what sizes.
+
+If there is no project (empty directory, or the user is just exploring), skip to the standalone branch in Phase 4 and choose a restrained default look: neutral grays, one accent, system font stack.
+
+### Phase 3 — Choose directions
+
+Default **3 variants**; up to 5 when the user asks or the design space is genuinely wide. More than 5 dilutes the comparison.
+
+Before writing any code, list the set: a name and an axis for each. Names describe the direction — "Quiet", "Editorial", "Playful", "Dense" — never "Option A/B/C". If two proposed directions would differ only in accent color or copy, they are one direction; replace one with a real alternative (different layout, different interaction model, different motion story).
+
+**Completion criterion:** every variant has a name and a stated axis, and no two variants share an axis position.
+
+### Phase 4 — Build the picker harness
+
+Two branches, by what exists:
+
+- **In a project with a dev server** — an isolated route or page (`/prototypes/<slug>`, or the framework's equivalent), one file per variant plus a small harness file. Nothing imports from the prototype surface into production code.
+- **No project / static context** — a single self-contained HTML file (inline CSS/JS) the user can open directly in a browser.
+
+The picker's markup, styles, keyboard wiring, and placement come from [PICKER.md](#appendix-picker-md), verbatim — load it now and build exactly that. Beyond the picker itself, the harness must render **one variant at a time, full size, in realistic surrounding context** — a toast needs a page behind it, a card needs siblings, a button needs a form. Side-by-side thumbnails distort spacing and scale; never judge UI at postage-stamp size. Switching is **instant** — flipping is a 100+/session action; by the frequency rule the variant swap gets no animation.
+
+### Phase 5 — Verify and hand off
+
+Run the harness. Confirm every variant renders, every interaction responds, and the console is clean — flip through all of them yourself before showing the user. If browser tooling is available, screenshot each variant.
+
+Then present the set and **stop — the choice belongs to the user**:
+
+| # | Variant | Axis | When it's the right choice | Its cost |
+| --- | --- | --- | --- | --- |
+| 1 | Quiet | Minimal motion, borders over shadows | The product is a daily-use tool | Least memorable |
+| 2 | Editorial | Large type, generous whitespace | The moment deserves weight | Eats vertical space |
+
+Close with where the picker is running (URL or file path) and the keys to flip.
+
+**Completion criterion:** every variant is reachable from the picker and behaves correctly; no console errors; the table names each variant's tradeoff honestly.
+
+### Phase 6 — Promote on selection
+
+When the user picks: integrate that variant where it belongs, following the project's existing conventions (file layout, naming, token usage), then delete the prototype surface per Hard Rule 5. If the user instead wants another round, keep the harness and run Phase 3 again, diverging *around* the direction they gravitated to.
+
+## Invocation Variants
+
+| Invocation | Behavior |
+| --- | --- |
+| `<description>` | Full workflow: scope → recon → 3 variants → picker → wait for choice |
+| `<description> x5` | Same, with that many variants (capped at 5) |
+| `riff <variant>` | New round: keep the harness, generate a fresh set diverging around the named variant's direction |
+| `keep <variant>` | Promote that variant into the codebase and delete the prototype surface |
+| `keep <variant>, leave the picker` | Promote, but keep the prototype surface around |
+
+## Tone
+
+Sell each variant honestly — one line on when it wins, one on what it costs. Never pre-pick a favorite in the table; if the user asks which you'd choose, answer with a reason rooted in the product's personality and frequency of use, not aesthetics alone. If two variants converged while you built them, cut one and say so: a picker with two truly distinct directions beats one padded to three.
+
+---
+
+## Appendix: PICKER.md
+
+# The Picker
+
+The picker's appearance is **not a design decision** — it is this spec. Copy the markup, CSS, and wiring below verbatim; the only values that change per run are the variant names and count. It stays identical across every project so it always reads as harness chrome, never as part of the design being judged. Do not restyle it with the project's tokens, fonts, or colors.
+
+It is a floating dark pill, bottom-center. Dark glass works on top of any page — light or dark — which is why it is not theme-aware.
+
+## Markup
+
+The sliding highlight span first, one button per variant, a hairline divider, then the replay button (only when at least one variant has motion to re-trigger):
+
+```html
+<nav class="proto-picker" aria-label="Prototype variants">
+  <span class="proto-picker-highlight" aria-hidden="true"></span>
+  <button class="proto-picker-item" data-active aria-current="true">Quiet</button>
+  <button class="proto-picker-item">Editorial</button>
+  <button class="proto-picker-item">Playful</button>
+  <span class="proto-picker-divider" aria-hidden="true"></span>
+  <button class="proto-picker-item proto-picker-replay" aria-label="Replay animation (R)">↻</button>
+</nav>
+```
+
+In a framework, keep the class names and structure; only the rendering syntax changes.
+
+## Styles
+
+```css
+.proto-picker {
+  position: fixed;
+  bottom: 24px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 2147483647;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 4px;
+  border-radius: 999px;
+  background: rgba(10, 10, 10, 0.82);
+  -webkit-backdrop-filter: blur(12px) saturate(1.4);
+  backdrop-filter: blur(12px) saturate(1.4);
+  box-shadow:
+    0 0 0 1px rgba(255, 255, 255, 0.08) inset,
+    0 8px 24px rgba(0, 0, 0, 0.24),
+    0 2px 6px rgba(0, 0, 0, 0.12);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-size: 13px;
+  line-height: 1;
+  -webkit-font-smoothing: antialiased;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.proto-picker-highlight {
+  position: absolute;
+  top: 4px;
+  left: 0;
+  height: 28px;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.12);
+  will-change: transform;
+}
+
+/* The slide is enabled only after first paint (data-ready), so load doesn't animate. */
+.proto-picker[data-ready] .proto-picker-highlight {
+  transition:
+    transform 250ms cubic-bezier(0.23, 1, 0.32, 1),
+    width 250ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .proto-picker[data-ready] .proto-picker-highlight { transition: none; }
+}
+
+.proto-picker-item {
+  position: relative; /* sits above the highlight */
+  display: flex;
+  align-items: center;
+  height: 28px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: rgba(255, 255, 255, 0.55);
+  font: inherit;
+  cursor: pointer;
+  transition: color 150ms ease-out;
+}
+
+.proto-picker-item:hover {
+  color: rgba(255, 255, 255, 0.85);
+}
+
+.proto-picker-item:active {
+  transform: scale(0.97);
+}
+
+.proto-picker-item:focus-visible {
+  outline: 2px solid rgba(255, 255, 255, 0.4);
+  outline-offset: 2px;
+}
+
+.proto-picker-item[data-active] {
+  color: #fff;
+}
+
+.proto-picker-divider {
+  width: 1px;
+  height: 16px;
+  margin: 0 4px;
+  background: rgba(255, 255, 255, 0.12);
+}
+
+.proto-picker-replay {
+  padding: 0 10px;
+  font-size: 14px;
+}
+
+.proto-picker[data-position="top"] {
+  bottom: auto;
+  top: 24px;
+}
+```
+
+## Rules
+
+- **Verbatim.** These values are the spec. No project fonts, no brand colors, no theme switching, no extra shadows or borders.
+- **The highlight slides; the variant swap stays instant.** The active pill animates between buttons (250ms, strong ease-out) as spatial feedback on the picker itself — but the variant being previewed still switches with no transition. The `width` transition is a deliberate exception to the transform/opacity rule: the element is 28px tall, absolutely positioned, and has no layout dependents, so the paint cost is negligible.
+- **One allowed modification:** if a variant occupies the bottom-center of the screen (a toast stack, a bottom sheet, a dock), set `data-position="top"` so the picker never covers the work. Nothing else about it may move or change.
+- **Replay is conditional.** Render the replay button and its divider only when at least one variant has an entrance or state animation worth re-triggering; a static comparison gets a shorter pill.
+
+## Behavior contract
+
+The contract is fixed regardless of how the harness renders:
+
+- Number keys `1–N` and `←`/`→` switch variants; `R` replays. Ignore key events when focus is in an input, textarea, select, or contenteditable, or when a modifier is held.
+- Clicking an item switches to it; exactly one item carries `data-active` and `aria-current="true"` at all times, and the highlight slides to it.
+- Selection persists across reload via a URL param (`?v=2`), falling back to variant 1. The highlight takes its initial position without animating (`data-ready` is added after first paint).
+- Switching re-mounts the variant (so entrance animations re-run); the replay key re-mounts without switching.
+
+## Reference wiring
+
+Verbatim for the standalone-HTML branch; in a framework, keep the same behavior but express it idiomatically (state instead of `innerHTML`, a keyed re-mount instead of `requestAnimationFrame`, refs + a layout effect for the highlight measurement).
+
+```js
+// `variants` is an array of render functions, one per variant, in picker order.
+const stage = document.getElementById('stage');
+const picker = document.querySelector('.proto-picker');
+const highlight = picker.querySelector('.proto-picker-highlight');
+const items = [...picker.querySelectorAll('.proto-picker-item:not(.proto-picker-replay)')];
+const replay = picker.querySelector('.proto-picker-replay');
+let current = 0;
+
+function moveHighlight() {
+  const el = items[current];
+  highlight.style.width = el.offsetWidth + 'px';
+  highlight.style.transform = `translateX(${el.offsetLeft}px)`;
+}
+
+function mount(i) {
+  stage.innerHTML = '';
+  // Clear first, render next frame, so entrance animations re-run.
+  requestAnimationFrame(() => { stage.innerHTML = variants[i](); });
+}
+
+function setActive(i) {
+  if (i < 0 || i >= variants.length) return;
+  current = i;
+  items.forEach((el, j) => {
+    el.toggleAttribute('data-active', j === i);
+    if (j === i) el.setAttribute('aria-current', 'true');
+    else el.removeAttribute('aria-current');
+  });
+  moveHighlight();
+  const url = new URL(location);
+  url.searchParams.set('v', i + 1);
+  history.replaceState(null, '', url);
+  mount(i);
+}
+
+items.forEach((el, i) => el.addEventListener('click', () => setActive(i)));
+replay?.addEventListener('click', () => mount(current));
+window.addEventListener('resize', moveHighlight);
+
+document.addEventListener('keydown', (e) => {
+  if (/^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName) || e.target.isContentEditable) return;
+  if (e.metaKey || e.ctrlKey || e.altKey) return;
+  const num = parseInt(e.key, 10);
+  if (num >= 1 && num <= variants.length) setActive(num - 1);
+  else if (e.key === 'ArrowRight') setActive((current + 1) % variants.length);
+  else if (e.key === 'ArrowLeft') setActive((current - 1 + variants.length) % variants.length);
+  else if (e.key === 'r' || e.key === 'R') mount(current);
+});
+
+setActive((parseInt(new URLSearchParams(location.search).get('v'), 10) || 1) - 1);
+// Enable the slide only after first paint, so load doesn't animate.
+requestAnimationFrame(() => requestAnimationFrame(() => picker.setAttribute('data-ready', '')));
+```

package/src/defaults/skc/ui-skills/react-bits/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: react-bits
+description: Reach for the React Bits registry instead of hand-rolling animated React UI. Use when building or polishing animated text, animated backgrounds, cursor/hover effects, carousels, or other motion-heavy React components. Covers when React Bits is the right call, how to install a single component with shadcn, which variant to pick (JS/TS x CSS/Tailwind), and the license boundary. Trigger on "animated text", "animated background", "make this hero pop", "add a shiny/blur/glitch text effect", "particle background", "cursor effect", or any animated React component request.
+---
+
+# React Bits
+
+## SKC invocation
+
+SKC loads this skill automatically for matching frontend UI/UX work.
+Do not wait for a follow-up question. Apply the rules immediately
+and keep going on the user's actual task.
+
+This is SKC's own guidance for using the third-party
+[React Bits](https://reactbits.dev) registry
+([DavidHDev/react-bits](https://github.com/DavidHDev/react-bits)).
+SKC does not bundle React Bits components; you install the one you need
+into the user's project from the upstream registry.
+
+## When to use it
+
+Use React Bits when the request is an **animated or interactive React
+component** that the catalog below already solves — animated text, animated
+backgrounds, cursor and hover effects, scroll effects, carousels, decorative
+motion.
+
+Do not use it when:
+
+- The project is not React. Nothing here is portable to plain HTML, Vue, or
+  React Native as-is. (Official ports exist for Vue and Svelte; they are
+  separate projects.)
+- A plain CSS transition does the job. Pulling in a decorative component for a
+  150ms fade is over-engineering — the bundled `animate` skill covers that.
+- The surface is data the user reads or acts on. Decorative motion belongs on
+  marketing and hero surfaces, not on a banking table.
+- The component would be the product. See the license section.
+
+Run the frequency and purpose gate from the `animate` skill first. A component
+the user sees a hundred times a day should not be animated, whatever the
+catalog offers.
+
+## Installing one component
+
+React Bits ships through the shadcn registry. Install exactly the component you
+need — never the whole catalog.
+
+```bash
+npx shadcn@latest add @react-bits/<Component>-<Variant> --yes
+```
+
+`<Variant>` is one of `JS-CSS`, `JS-TW`, `TS-CSS`, `TS-TW`. Match the project:
+TypeScript + Tailwind means `TS-TW`, plain JS with stylesheets means `JS-CSS`.
+Read the repo before choosing; do not default to one blindly.
+
+```bash
+# TypeScript + Tailwind project
+npx shadcn@latest add @react-bits/BlurText-TS-TW --yes
+```
+
+**Precondition:** the project must be shadcn-initialized — `components.json`
+must exist at the project root. Without it the CLI stops and asks to create
+one, which will hang a non-interactive run. Check for `components.json` first;
+if it is missing, either run `npx shadcn@latest init` (only with the user's
+agreement — it rewrites config and CSS) or copy the component source from
+[reactbits.dev](https://reactbits.dev) by hand instead.
+
+The component lands in the project's configured components alias (typically
+`src/components/<Component>.tsx`). It is ordinary project source from that
+point on: read it, adapt the props, restyle it. Do not treat it as a
+node_modules dependency.
+
+## After installing
+
+- Check the component's dependencies actually installed; several pull
+  `motion`, `gsap`, `three`, or `ogl`. A 3D background is not free.
+- Reduced motion still applies. Most of these components animate
+  unconditionally — add a `prefers-reduced-motion` guard yourself.
+- Tune the props to the product. Shipping the demo defaults verbatim is how
+  every site using this library ends up looking identical.
+- Background and 3D components are the expensive ones. Measure before shipping
+  one above the fold on mobile.
+
+## License boundary
+
+React Bits is **MIT + Commons Clause**. Using a component in the user's
+application, website, or product — including commercially — is explicitly
+allowed. Selling, sublicensing, or redistributing the components themselves,
+alone or bundled or ported, is not.
+
+That is why SKC installs from the upstream registry instead of vendoring the
+components. Do not copy the catalog into a shared internal package that is
+itself distributed as a component library.
+
+## Catalog
+
+169 components. Names below are exact registry names — append the variant
+suffix when installing.
+
+### Text animations
+
+ASCIIText, BlurText, CircularText, CountUp, CurvedLoop, DecryptedText, DepthText, EchoText, FallingText, FoldText, FuzzyText, GlitchText, GradientText, MagicRings, MaskedHeading, ParticleText, RotatingText, ScrambledText, ScrollFloat, ScrollReveal, ScrollVelocity, ShinyText, Shuffle, SplitFlapText, SplitText, StrokeText, TextCursor, TextPressure, TextType, TrueFocus, VariableProximity, WarpText
+
+### Animations
+
+AnimatedContent, Antigravity, BlobCursor, ClickSpark, Crosshair, Cubes, ElasticMesh, ElectricBorder, FadeContent, GhostCursor, GlareHover, GlowCursor, GradualBlur, HalftoneReveal, ImageTrail, LaserFlow, LogoLoop, Magnet, MagnetLines, MetaBalls, MetallicPaint, Noise, OrbitImages, PixelSwap, PixelTrail, PixelTransition, Ribbons, RippleDistortion, ScrollExpand, ShapeBlur, SpecularButton, SplashCursor, StarBorder, StickerPeel, Strands, SwarmCursor, TargetCursor
+
+### Components
+
+AccordionGallery, AnimatedList, BorderGlow, BounceCards, BubbleMenu, CardNav, CardSwap, Carousel, ChromaGrid, CircularGallery, Counter, CursorGrid, CurvedInput, DecayCard, DepthCarousel, Dock, DomeGallery, DriftWall, ElasticSlider, FlowingMenu, FluidGlass, FlyingPosters, Folder, GlassIcons, GlassSurface, GooeyNav, InfiniteMenu, InfiniteSpiral, Lanyard, LineSidebar, MagicBento, Masonry, ModelViewer, MorphSlider, OptionWheel, PillNav, PixelCard, ProfileCard, ScrollStack, SpotlightCard, Stack, StaggeredMenu, Stepper, TiltedCard
+
+### Backgrounds
+
+AcidSquares, AeroShards, Aurora, Balatro, Ballpit, Beams, CRTWarp, ColorBends, DarkVeil, Dither, DotField, DotGrid, EvilEye, FaultyTerminal, Ferrofluid, FloatingLines, Galaxy, GhostFibers, GradientBlinds, GradientWaves, Grainient, GridDistortion, GridMotion, GridScan, Hyperspeed, Iridescence, LetterGlitch, LightPillar, LightRays, LightTunnel, Lightfall, Lightning, LineWaves, LiquidChrome, LiquidEther, MoltenMetal, Orb, Particles, PixelBlast, Plasma, PlasmaWave, Prism, PrismaticBurst, Radar, RippleGrid, Scanner, ShapeGrid, ShapeWaves, SideRays, Silk, SlicedWaves, SoftAurora, Threads, Topography, Waves, WebThreads