constella 0.1.0

package/skills/references/ai-attachments-ui/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ai-attachments-ui
+description: Attachment UI patterns for AI chat using AI Elements' Attachments component; consult when showing files/sources in prompts and messages.
+domain: reference
+category: reference
+tags: [ai-elements, attachments, file-upload, ai-ui, shadcn, react]
+official_sources:
+  - https://elements.ai-sdk.dev/components/attachments
+  - https://github.com/vercel/ai-elements
+verified: 2026-06-16
+---
+
+# AI Attachments UI
+
+## Overview
+The Attachments component from Vercel's AI Elements provides a unified way to display file attachments and source documents in AI chat UIs, with grid, inline, and list layout variants. It is a set of composable sub-components that render previews, file info, and a remove control, and it accepts AI SDK `FileUIPart` / `SourceDocumentUIPart` data. Read this when building file-upload affordances in a prompt input or showing attached/source files inside messages.
+
+## Official sources
+- Docs: https://elements.ai-sdk.dev/components/attachments
+- Repo: https://github.com/vercel/ai-elements
+- Setup: https://elements.ai-sdk.dev/docs/setup
+
+## Install / setup
+```bash
+npx ai-elements@latest add attachments
+```
+Requires shadcn/ui initialized and Tailwind CSS Variables mode (per AI Elements setup).
+
+## Core concepts
+- `<Attachments />` is the container and takes a `variant` of `"grid" | "inline" | "list"` to control layout.
+- `<Attachment />` wraps a single item and accepts `data` (a `FileUIPart` or `SourceDocumentUIPart` with an id) plus an `onRemove` callback.
+- Composable sub-parts: `<AttachmentPreview />` (image/video/icon), `<AttachmentInfo />` (filename + media type), `<AttachmentRemove />` (remove button), `<AttachmentHoverCard />` (hover preview), `<AttachmentEmpty />` (empty state).
+- `AttachmentInfo` exposes `showMediaType`, and `AttachmentRemove` accepts a custom `label` for accessibility.
+- Designed to map directly over AI SDK file/source-document parts, so it pairs naturally with Prompt Input and Message.
+
+## Best practices
+- Choose the layout `variant` to match context: `grid` for galleries, `inline` for compact prompt-bar chips, `list` for detailed/source views.
+- Provide an accessible `label` on `AttachmentRemove` so screen-reader users understand the remove action.
+- Render attachments by mapping AI SDK `FileUIPart` data rather than inventing a parallel attachment shape.
+- Use `AttachmentEmpty` to communicate the empty state instead of rendering nothing.
+
+## Common pitfalls
+- Passing data without a stable `id` → each attachment's `data` should carry an id so list rendering and removal stay correct.
+- Building custom remove buttons → use `AttachmentRemove` with `onRemove` so behavior and a11y are handled.
+- Forgetting media-type cues → enable `showMediaType` / previews so users can tell files apart at a glance.
+
+## Examples
+```tsx
+<Attachments variant="grid">
+  {files.map((file) => (
+    <Attachment key={file.id} data={file} onRemove={() => remove(file.id)}>
+      <AttachmentPreview />
+      <AttachmentInfo showMediaType />
+      <AttachmentRemove label="Remove attachment" />
+    </Attachment>
+  ))}
+</Attachments>
+```
+
+## Further reading
+- Prompt Input component: https://elements.ai-sdk.dev/
+- AI SDK docs: https://ai-sdk.dev/
+
+## Related skills
+- ../vercel-ai-sdk-elements — the parent AI Elements library
+- ../ai-tool-ui-patterns — rendering tool results in chat

package/skills/references/ai-in-browser-webllm/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ai-in-browser-webllm
+description: Run LLMs fully in-browser/locally with WebLLM via WebGPU; consult for client-side inference, offline AI, and OpenAI-style chat without a server.
+domain: reference
+category: reference
+tags: [webllm, llm, webgpu, in-browser, mlc, local-inference]
+official_sources:
+  - https://webllm.mlc.ai/docs/
+  - https://github.com/mlc-ai/web-llm
+verified: 2026-06-16
+---
+
+# WebLLM — In-Browser LLM Inference
+
+## Overview
+WebLLM is a high-performance, in-browser LLM inference engine from the MLC project. It runs open models (Llama 3, Phi 3, Gemma, Mistral, Qwen, and more) entirely on the client using WebGPU for hardware acceleration, with no server-side processing. It exposes an OpenAI-compatible API (streaming, JSON mode), making it useful for privacy-preserving, offline-capable, or zero-backend AI features. Read this when you need client-side inference in a web app.
+
+## Official sources
+- Docs: https://webllm.mlc.ai/docs/
+- Repo: https://github.com/mlc-ai/web-llm
+- Getting started: https://webllm.mlc.ai/docs/user/get_started.html
+
+## Install / setup
+```bash
+npm install @mlc-ai/web-llm
+```
+yarn and pnpm equivalents are documented:
+```bash
+yarn add @mlc-ai/web-llm
+pnpm install @mlc-ai/web-llm
+```
+
+## Core concepts
+- `MLCEngine` is the core interface for model loading, chat completions, and embeddings; create it with the `CreateMLCEngine` factory or `new MLCEngine()` then `engine.reload(model)`.
+- Models load asynchronously; pass an `initProgressCallback` to surface download/compile progress to users (first load can be large).
+- WebGPU is the acceleration backend — runs entirely in-browser with no server support required.
+- OpenAI-compatible chat completion API, including streaming and structured JSON-mode output.
+- Built-in model registry plus support for custom MLC-format models compiled via MLC LLM.
+- Cache backends for model weights: Cache API, IndexedDB, OPFS, and Cross-Origin Storage; optional SRI integrity verification.
+
+## Best practices
+- Offload generation to a Web Worker or Service Worker so heavy compute does not block the main UI thread (documented in Advanced Use Cases).
+- Reuse a single loaded engine instance and persist weights in a cache backend to avoid re-downloading on every visit.
+- Always wire `initProgressCallback` so users see progress during the first (potentially large) model download.
+- Pick the smallest model that meets quality needs; in-browser memory and download size are real constraints.
+
+## Common pitfalls
+- Assuming it works everywhere → WebGPU support is required; gate the feature and provide a fallback when the browser/device lacks it.
+- Loading the model on the main thread → use a Web Worker / Service Worker to keep the UI responsive.
+- Treating first load as instant → weights must download and compile; cache them and show progress.
+
+## Examples
+```javascript
+import { CreateMLCEngine } from "@mlc-ai/web-llm";
+
+const engine = await CreateMLCEngine(
+  "Llama-3.1-8B-Instruct-q4f32_1-MLC",
+  { initProgressCallback: (p) => console.log(p) }
+);
+
+const reply = await engine.chat.completions.create({
+  messages: [{ role: "user", content: "Hello!" }],
+});
+console.log(reply.choices[0].message.content);
+```
+
+## Further reading
+- Basic Usage: https://webllm.mlc.ai/docs/user/basic_usage.html
+- API Reference: https://webllm.mlc.ai/docs/user/api_reference.html
+- Advanced Use Cases (Web Worker): https://webllm.mlc.ai/docs/user/advanced_usage.html
+
+## Related skills
+- ../vercel-ai-sdk-elements — UI components for AI-native apps
+- ../ai-tool-ui-patterns — rendering tool-call results in chat UIs

package/skills/references/ai-tool-ui-patterns/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ai-tool-ui-patterns
+description: UI patterns for AI tool-calls and results — turn tool JSON into typed, validated components; consult when rendering tool outputs in chat.
+domain: reference
+category: reference
+tags: [tool-ui, ai-ui, tool-calling, zod, shadcn, assistant-ui]
+official_sources:
+  - https://www.tool-ui.com/docs/overview
+  - https://github.com/assistant-ui/tool-ui
+verified: 2026-06-16
+---
+
+# AI Tool UI Patterns
+
+## Overview
+When a model calls a tool, most apps dump raw JSON into the conversation. Tool UI (by the assistant-ui project) is an open-source component library where each component turns a specific kind of tool output — a card, table, option list, chart, approval, form, or media card — into real, interactive UI so users can understand and act without leaving the chat. It is JSON-native, typed (Zod schemas), accessible, and built on Tailwind, Radix, and shadcn/ui. Read this when designing how tool-call results render and how users approve or respond to them.
+
+## Official sources
+- Docs: https://www.tool-ui.com/docs/overview
+- Repo: https://github.com/assistant-ui/tool-ui
+- Quick start: https://www.tool-ui.com/docs/quick-start
+
+## Install / setup
+```bash
+npx shadcn@latest add @tool-ui/link-preview
+```
+Components use the shadcn copy/paste model — they live in your codebase with no dependency lock-in; swap `link-preview` for any component name.
+
+## Core concepts
+- Each component maps one kind of tool output to UI (table, chart, option list, approval, form, media card), instead of showing raw JSON.
+- Copy/paste model (like shadcn/ui): components live in your repo, so there is no dependency lock-in.
+- Every component ships a colocated `schema.ts` Zod schema; tool output is validated, rendered when valid, and fails safely when not.
+- A three-part flow: backend tool defines input/output via AI SDK + Zod, the schema validates on server and client, and a frontend `toolkit` maps tool names to components.
+- Built on Tailwind, Radix, and shadcn/ui, so it inherits accessible primitives and your theme.
+
+## Best practices
+- Validate tool output against the component's Zod schema on both server and client before rendering.
+- Maintain a `toolkit` mapping of backend tool names to frontend components so the runtime can pick the right renderer.
+- Prefer interactive surfaces (approvals, forms) over read-only JSON dumps for actions the user must take.
+- Since components are copied into your repo, version and customize them deliberately rather than expecting upstream updates.
+
+## Common pitfalls
+- Rendering unvalidated tool JSON → parse against the Zod schema and fail safely when it does not match.
+- Hard-coding which component renders a tool → use the `toolkit` name→component map so new tools are easy to wire.
+- Treating it like an installed npm package → it is copy/paste; you own the code and its updates.
+
+## Examples
+```ts
+// Register tools -> components so the runtime knows what to render.
+const toolkit = {
+  getMetrics: MetricsTable,
+  deployPlan: ApprovalCard,
+  linkPreview: LinkPreview,
+};
+```
+
+## Further reading
+- Quick start: https://www.tool-ui.com/docs/quick-start
+- assistant-ui project: https://github.com/assistant-ui
+
+## Related skills
+- ../vercel-ai-sdk-elements — AI Elements (includes a Tool component)
+- ../ai-attachments-ui — attachment UI patterns

package/skills/references/component-patterns-gallery/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: component-patterns-gallery
+description: Canonical UI component anatomy, naming, and patterns; consult to name, structure, and document components consistently with real design systems.
+domain: reference
+category: reference
+tags: [components, design-system, ui-patterns, anatomy, accessibility]
+official_sources:
+  - https://component.gallery/
+  - https://alignui.com/
+verified: 2026-06-16
+---
+
+# Component Patterns & Anatomy Gallery
+
+## Overview
+When you build a UI component you face two recurring questions: what is this thing actually called, and what parts does it have. The Component Gallery (component.gallery) answers the first by cataloging interface components from real-world design systems — each entry lists the component, its alternate names, a description, and links to how many systems implement it. AlignUI (alignui.com) answers the second as a production design system with React + Tailwind components and a synced Figma kit. Consult this skill before naming or structuring a component so your vocabulary and anatomy match established conventions instead of ad-hoc invention.
+
+## Official sources
+- The Component Gallery: https://component.gallery/
+- Components index: https://component.gallery/components/
+- Design systems index: https://component.gallery/design-systems/
+- AlignUI: https://alignui.com/
+
+## Core concepts
+- **Component anatomy.** Most components decompose into named parts (e.g. a card has container, media, header, body, actions; a dialog has overlay, container, title, description, close, footer). Naming the parts is the foundation of an API and of accessible markup.
+- **Canonical naming and aliases.** The same pattern goes by different names across systems (Accordion vs. Disclosure vs. Expander; Snackbar vs. Toast; Combobox vs. Autocomplete). The Component Gallery surfaces these aliases so you pick a recognizable name.
+- **Compare-across-systems.** For any component you can see how multiple mature design systems solved the same interaction/layout problem, which exposes the variants, props, and states worth supporting.
+- **States and variants.** Components are defined as much by their states (default, hover, focus, active, disabled, loading, error, selected) and variants (size, emphasis, intent) as by their static look.
+- **Design-to-code parity.** Systems like AlignUI keep a Figma kit and a coded library in sync; treat the design tokens and component contracts as a single source of truth across both.
+
+## Best practices
+- Use the canonical component name (and document its aliases) so designers, engineers, and future agents share one vocabulary — look it up in The Component Gallery rather than coining a new term.
+- Model the component's full state matrix (hover/focus/active/disabled/loading/error) up front; missing states are where UIs feel unfinished.
+- Build interactive components on accessible primitives (correct roles, keyboard support, focus management) — study how reference systems handle ARIA for the pattern before rolling your own.
+- Expose variation through a small, named prop API (size, variant/intent, emphasis) rather than many one-off boolean flags.
+- Keep design tokens (color, spacing, radius, typography) as the shared layer so Figma and code stay in parity.
+
+## Common pitfalls
+- Inventing a bespoke name for a well-known pattern → confuses collaborators and search; reuse the established name and list aliases.
+- Shipping only the happy-path visual and forgetting focus/disabled/loading/error states → incomplete, inaccessible component.
+- Cloning a screenshot's pixels but skipping keyboard and ARIA semantics → looks right, fails real use; reference how design systems implement the role and interactions.
+
+## Examples
+```text
+Dialog (aliases: Modal)
+  - Overlay        (scrim, click-to-dismiss optional)
+  - Container      (focus-trapped, role="dialog", aria-modal="true")
+    - Title        (aria-labelledby target)
+    - Description  (aria-describedby target)
+    - Content
+    - Footer       (primary + secondary actions)
+    - Close button (aria-label)
+  States: open / closed; initial focus + focus return on close
+```
+
+## Further reading
+- component.gallery component pages for per-pattern anatomy, aliases, and cross-system examples.
+- AlignUI docs for a concrete React + Tailwind implementation of these patterns.
+
+## Related skills
+- ../shadcn-tailwind-theming — implement these patterns as themeable shadcn/Tailwind components.
+- ../react-component-libraries — prebuilt implementations of common components.

package/skills/references/gradient-resources/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: gradient-resources
+description: CSS gradient functions plus generators for static and animated/shader gradients; consult when crafting backgrounds, accents, or hero visuals.
+domain: reference
+category: reference
+tags: [gradient, css, background, webgl, color, design]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/CSS/gradient
+  - https://craft-gradients.artcreativecode.com/
+verified: 2026-06-16
+---
+
+# Gradient Resources & CSS Techniques
+
+## Overview
+Gradients are the workhorse of modern backgrounds, buttons, and hero visuals. The MDN `<gradient>` reference (developer.mozilla.org) is the canonical, standards-aligned source for the CSS gradient functions and their syntax, color stops, and color-space interpolation. For richer or animated looks, Craft Gradients (craft-gradients.artcreativecode.com) is an interactive WebGL/shader gradient generator with presets you can record, embed, and export. Read this skill when you need correct CSS gradient syntax or a generator for static and animated gradient visuals.
+
+## Official sources
+- MDN CSS `<gradient>`: https://developer.mozilla.org/en-US/docs/Web/CSS/gradient
+- MDN `linear-gradient()`: https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient
+- Craft Gradients (WebGL generator): https://craft-gradients.artcreativecode.com/
+
+## Core concepts
+- **`<gradient>` is an `<image>`.** Per MDN, a gradient is a CSS `<image>` with no intrinsic size; it scales to its container and is used wherever an image is valid (e.g. `background-image`).
+- **Three base functions + repeating variants.** `linear-gradient()` (along a line/angle), `radial-gradient()` (from a center outward), and `conic-gradient()` (around a center) — each with a `repeating-` counterpart for banded/striped patterns.
+- **Color stops and positions.** Stops define where colors sit (`red 0%, blue 100%`); hard stops (two stops at the same position) create crisp bands; hints control the midpoint of a transition.
+- **Color-space interpolation.** Gradients interpolate in a chosen color space (sRGB, oklab, lch, display-p3, etc.) and use alpha-premultiplied math to avoid muddy grays when fading to transparent — choosing `in oklch`/`in oklab` often yields more even, vivid transitions than sRGB.
+- **Static CSS vs. animated WebGL.** CSS gradients are static (animatable only indirectly, e.g. moving `background-position`); shader/WebGL generators like Craft Gradients produce genuinely animated, organic gradients exported as embeds or recordings.
+
+## Best practices
+- Layer multiple gradients in one `background` (comma-separated) to build depth — e.g. a radial highlight over a linear base — instead of stacking extra DOM elements.
+- Choose a perceptual color space (`in oklch` / `in oklab`) for smoother, more uniform transitions, and use alpha-aware fades to avoid the gray-band artifact when fading to transparent. (See MDN interpolation notes.)
+- For "animated" CSS gradients, animate `background-position` on an oversized `background-size` rather than re-rendering colors, keeping it compositor-friendly.
+- Use hard color stops to create flat color blocks, stripes, or geometric backgrounds from a single gradient declaration.
+- Reach for a WebGL generator (Craft Gradients) only when you need living, organic motion; export and lazy-load it, and provide a static CSS fallback.
+
+## Common pitfalls
+- Fading a color to fully transparent and getting an unexpected gray band → the default sRGB transparent is `rgb(0 0 0 / 0)`; fade to the same color at 0 alpha (e.g. `rgba(255,0,0,0)`) or rely on the alpha-premultiplied/oklab interpolation MDN describes.
+- Expecting CSS gradients to animate their colors directly → CSS can't tween gradient color stops; animate `background-position` or use a shader/JS approach.
+- Heavy full-screen WebGL gradient on every page load → costs performance and battery; prefer CSS where it suffices and lazy-load shader backgrounds.
+
+## Examples
+```css
+/* Layered static gradient with a perceptual color space */
+.hero {
+  background:
+    radial-gradient(60% 60% at 50% 0%, rgba(99,102,241,.35), transparent 70%),
+    linear-gradient(in oklch to bottom, #0f172a, #1e293b);
+}
+
+/* "Animated" gradient via background-position (compositor-friendly) */
+.animated {
+  background: linear-gradient(120deg, #6366f1, #ec4899, #6366f1);
+  background-size: 200% 200%;
+  animation: pan 8s ease-in-out infinite;
+}
+@keyframes pan { 0%,100% { background-position: 0% 50%; } 50% { background-position: 100% 50%; } }
+```
+
+## Further reading
+- MDN pages for `radial-gradient()` and `conic-gradient()` for their full parameter syntax.
+- Craft Gradients to design, record, and embed animated shader gradients.
+
+## Related skills
+- ../shadcn-tailwind-theming — apply gradients as themed backgrounds/accents via CSS variables.
+- ../web-animation-codrops — combine gradients with motion for hero effects.

package/skills/references/react-component-libraries/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: react-component-libraries
+description: Curated React component sources for modern animated UI; consult to find prebuilt components, blocks, and effects instead of building from scratch.
+domain: reference
+category: reference
+tags: [react, components, tailwind, animation, framer-motion, shadcn]
+official_sources:
+  - https://magicui.design/
+  - https://reactbits.dev/
+  - https://21st.dev/
+verified: 2026-06-16
+---
+
+# React Component Libraries (Modern UI)
+
+## Overview
+For modern React UIs you rarely need to hand-build hero sections, animated text, marquees, or backgrounds — several curated sources provide them ready to drop in. Magic UI (magicui.design) offers 150+ free, open-source animated components built with React, TypeScript, Tailwind, and Motion, positioned as a companion to shadcn/ui. React Bits (reactbits.dev) is an open collection of 100+ animated, interactive components (text, backgrounds, effects) available in JS/TS and CSS/Tailwind variants. 21st.dev is a community registry of shadcn/Tailwind components and marketing blocks, with an AI "Magic" MCP that generates them inside IDEs. Read this skill to pick the right source for animated or prebuilt UI.
+
+## Official sources
+- Magic UI: https://magicui.design/
+- React Bits: https://reactbits.dev/
+- 21st.dev: https://21st.dev/
+- 21st Magic MCP (repo): https://github.com/21st-dev/magic-mcp
+
+## Core concepts
+- **Distribution by copy-paste, not just npm.** These sources favor copying component source into your project (often via a CLI like shadcn or jsrepo) so you own and can edit the code, mirroring the shadcn model.
+- **Animated/effect components.** Magic UI and React Bits specialize in motion: animated text, shimmer/marquee/border effects, particle and gradient backgrounds, built on Motion/Framer Motion or plain CSS.
+- **Variant flavors.** React Bits ships each component in JS or TS and CSS or Tailwind, so you match your stack without rewrites.
+- **Blocks vs. components.** 21st.dev separates page-level blocks (heroes, pricing, testimonials, CTAs) from atomic UI components (buttons, inputs, modals) — blocks accelerate landing pages, components fill gaps in a design system.
+- **AI generation via MCP.** 21st.dev's Magic MCP server lets IDE agents (Cursor, Windsurf, VS Code/Cline, Claude) generate and write components from natural-language prompts, drawing on the 21st.dev library.
+
+## Best practices
+- Prefer these as a companion to shadcn/ui (Magic UI explicitly positions itself this way): use shadcn for primitives and these libraries for animated flourishes and marketing blocks.
+- Install via the official CLI/registry path (shadcn or jsrepo where offered) so dependencies and file placement are handled correctly, then customize the copied source.
+- Match the component flavor to your stack (TS + Tailwind vs. JS + CSS) at copy time to avoid post-hoc conversion — React Bits offers all four combinations.
+- Treat copied components as your code: review, prune unused props, and align them to your theme tokens rather than leaving them as opaque imports.
+- Gate heavy animated backgrounds/effects behind `prefers-reduced-motion` and lazy-loading to protect performance and accessibility.
+
+## Common pitfalls
+- Assuming everything is an npm package → many components are copy-paste/CLI-installed source you own; check the source's install method.
+- Layering many simultaneous animated effects (particles + marquee + gradient + parallax) → visual noise and jank; use motion sparingly and purposefully.
+- Pasting components without theming them → they clash with your design tokens; remap colors/spacing to your variables.
+- Pulling a component without checking its license/attribution requirements → verify the source's license before shipping.
+
+## Examples
+```bash
+# Typical install paths (verify the exact command on each source's docs):
+# Magic UI / 21st.dev components often add via the shadcn CLI registry:
+npx shadcn@latest add "<registry-component-url>"
+
+# React Bits supports CLI install via shadcn or jsrepo, or plain copy-paste of the JSX.
+```
+
+## Further reading
+- magicui.design and reactbits.dev component galleries for the full catalogs.
+- 21st.dev Magic MCP repo (github.com/21st-dev/magic-mcp) for AI-in-IDE component generation.
+
+## Related skills
+- ../shadcn-tailwind-theming — theme these components consistently via CSS variables.
+- ../web-animation-codrops — understand the motion techniques these components implement.
+- ../saas-landing-patterns — assemble blocks into a converting landing page.

package/skills/references/saas-landing-patterns/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: saas-landing-patterns
+description: Proven SaaS landing-page structure, sections, copy and conversion patterns; consult when building or critiquing a marketing/landing page.
+domain: reference
+category: reference
+tags: [landing-page, saas, conversion, marketing, ux]
+official_sources:
+  - https://saaslandingpage.com/
+  - https://saaslandingpage.com/templates/
+verified: 2026-06-16
+---
+
+# SaaS Landing-Page Patterns
+
+## Overview
+A SaaS landing page exists to convert a visitor into a signup, trial, or demo. There is a well-worn, repeatable section order that high-performing SaaS sites converge on. SaaS Landing Page (saaslandingpage.com) is a curated gallery of hundreds of real, shipped landing pages from SaaS companies and startups, organized by section, technology, and template, that lets you study what real teams actually do. Read this skill when you need to scaffold, populate, or audit a landing page rather than inventing structure from scratch.
+
+## Official sources
+- Gallery: https://saaslandingpage.com/
+- Features-page examples: https://saaslandingpage.com/features/
+- Templates: https://saaslandingpage.com/templates/
+
+## Core concepts
+- **Canonical section order.** The dominant pattern is: hero (headline + subhead + primary CTA + product visual) → social proof (logo wall) → problem/value proposition → features/benefits → how-it-works → deeper social proof (testimonials, case studies, metrics) → pricing → FAQ → final CTA → footer. Order may flex, but the hero and a final CTA are non-negotiable bookends.
+- **Hero clarity over cleverness.** The headline must state what the product does and for whom within seconds. A subhead expands the value; one unmistakable primary CTA dominates; a product screenshot, demo loop, or illustration anchors the visual.
+- **Benefits vs. features.** Features are what the product has; benefits are the outcome the user gets. Effective pages lead each feature block with the benefit, then back it with the mechanism.
+- **Social proof as trust currency.** Logo walls, named testimonials, star ratings, customer counts, and quantified results ("saved 8 hrs/week") de-risk the decision and are placed near CTAs and the hero.
+- **One conversion goal per page.** A landing page funnels toward a single primary action (start trial / book demo / sign up). Competing CTAs dilute conversion.
+
+## Best practices
+- Repeat the primary CTA at natural decision points (after hero, after features, after pricing, in the footer) so the visitor never has to scroll back up to act. (Pattern observed across the saaslandingpage.com gallery.)
+- Place a logo wall or short testimonial immediately below the hero — early social proof lifts perceived credibility before the user reads features.
+- Make pricing legible: name tiers, show what each includes, highlight the recommended plan, and answer billing objections inline (cancel anytime, no card required).
+- Design mobile-first; a large share of SaaS traffic is mobile, so the hero, CTA, and pricing must work in a single column before desktop refinements.
+- Pair every feature claim with a concrete visual (screenshot, GIF, or annotated UI) rather than abstract iconography alone.
+
+## Common pitfalls
+- Vague hero copy ("Reimagine your workflow") that never says what the product is → state the job-to-be-done plainly in the first line.
+- Burying or omitting pricing → a missing or hidden pricing section forces visitors to bounce to find it; show it or explain why ("contact sales") explicitly.
+- Multiple competing CTAs of equal weight (signup + demo + docs + newsletter) → pick one primary action and demote the rest to secondary styling.
+- Wall-of-text feature lists with no visuals or hierarchy → chunk into benefit-led blocks with supporting imagery.
+
+## Examples
+```text
+Hero
+  H1: <verb-led outcome — what it does, for whom>
+  Sub: <one sentence expanding the value>
+  [ Start free trial ]  (primary)   [ Book a demo ] (secondary)
+  <product screenshot / looping demo>
+Logo wall: "Trusted by <brands>"
+Value prop / problem→solution
+Features (benefit-led, each with a visual)
+How it works (3 steps)
+Testimonials + metrics
+Pricing (tiers, recommended plan highlighted)
+FAQ
+Final CTA (repeat primary action)
+Footer
+```
+
+## Further reading
+- Section-specific galleries on saaslandingpage.com (features pages, pricing pages) for live structural references.
+- ../web-animation-codrops — motion and scroll interactions that elevate landing-page hero and section transitions.
+
+## Related skills
+- ../component-patterns-gallery — anatomy of the buttons, cards, pricing tables, and nav used on landing pages.
+- ../react-component-libraries — prebuilt hero/pricing/CTA blocks to assemble pages quickly.

package/skills/references/shadcn-tailwind-theming/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: shadcn-tailwind-theming
+description: Theme and generate shadcn/ui + Tailwind components via CSS variables and theme editors; consult when styling or scaffolding a shadcn-based UI.
+domain: reference
+category: reference
+tags: [shadcn, tailwind, theming, css-variables, design-tokens]
+official_sources:
+  - https://ui.shadcn.com/
+  - https://ui.shadcn.com/docs/theming
+  - https://tweakcn.com/
+verified: 2026-06-16
+---
+
+# shadcn/ui + Tailwind Theming
+
+## Overview
+shadcn/ui (ui.shadcn.com) is not a dependency you install and import — it is a set of accessible, Radix-based components styled with Tailwind that you copy into your codebase via a CLI and then own and customize. Theming runs entirely through CSS custom properties mapped to Tailwind, so one set of variables restyles every component and powers light/dark modes. Tools like tweakcn (tweakcn.com) and Magic UI Pro (pro.magicui.design) let you generate those variables visually or buy prebuilt blocks. Read this skill when you need to scaffold, theme, or recolor a shadcn-based interface.
+
+## Official sources
+- Docs: https://ui.shadcn.com/
+- Theming guide: https://ui.shadcn.com/docs/theming
+- CLI: https://ui.shadcn.com/docs/cli
+- Theme editor (tweakcn): https://tweakcn.com/
+- Premium blocks/templates (Magic UI Pro): https://pro.magicui.design/
+
+## Core concepts
+- **Copy-in, you-own-it model.** The CLI writes component source into your project (e.g. `components/ui/`). You edit the files directly; there is no black-box package to fight, and updates are deliberate copy-ins, not version bumps.
+- **CSS-variable theming.** Colors are defined as CSS custom properties (background, foreground, primary, secondary, muted, accent, destructive, border, ring, etc.) and consumed by Tailwind. Restyling means changing the variables, not editing each component.
+- **Light/dark via variable swap.** Dark mode is a second block of the same variables under a `.dark` selector (or media query); components don't change, only the values do.
+- **Registry / "Build Your Own".** Components and blocks are distributed through a registry the CLI can pull from, which extends to community registries and prebuilt block collections.
+- **Visual theme generation.** tweakcn provides a GUI to tune the palette, radius, and typography and export the exact CSS-variable block to paste into your stylesheet — faster and less error-prone than hand-tuning HSL values.
+
+## Best practices
+- Initialize with the official CLI and let it configure paths, Tailwind, and the base color, rather than copying files manually. (See the CLI docs.)
+- Theme by editing the CSS-variable layer (and its `.dark` counterpart), not by hardcoding colors inside components — this keeps every component consistent and re-themeable.
+- Keep semantic token names (primary, muted, destructive) and map brand colors onto them, so swapping brands is a one-place change.
+- Use a generator like tweakcn to produce a coherent, accessible palette and copy its exported variables verbatim, then commit them as your theme source of truth.
+- Define both light and dark variable sets together so contrast is verified in both modes before shipping.
+
+## Common pitfalls
+- Treating shadcn/ui like an npm component library and trying to `npm install` the components → it is a copy-in CLI distribution; run the CLI to add components.
+- Hardcoding hex/HSL colors inside individual components → breaks theming and dark mode; reference the CSS variables instead.
+- Forgetting the `.dark` variable block, so dark mode inherits light values → define both sets.
+- Pasting a generated palette without checking contrast on text/background pairs → run a contrast check before committing.
+
+## Examples
+```css
+/* app globals.css — semantic theme tokens consumed by Tailwind */
+:root {
+  --background: 0 0% 100%;
+  --foreground: 240 10% 3.9%;
+  --primary: 240 5.9% 10%;
+  --primary-foreground: 0 0% 98%;
+  --border: 240 5.9% 90%;
+  --ring: 240 5.9% 10%;
+}
+.dark {
+  --background: 240 10% 3.9%;
+  --foreground: 0 0% 98%;
+  --primary: 0 0% 98%;
+  --primary-foreground: 240 5.9% 10%;
+  --border: 240 3.7% 15.9%;
+  --ring: 240 4.9% 83.9%;
+}
+```
+
+## Further reading
+- ui.shadcn.com/docs/theming for the full variable list and conventions.
+- tweakcn.com to generate and export a custom theme's variable block.
+
+## Related skills
+- ../component-patterns-gallery — anatomy and naming for the components you theme.
+- ../react-component-libraries — Magic UI and others that compose with shadcn.
+- ../gradient-resources — gradient backgrounds and accents to layer onto themed UIs.

package/skills/references/vercel-ai-sdk-elements/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: vercel-ai-sdk-elements
+description: AI Elements — composable shadcn/ui components for AI-native apps (chat, reasoning, tools); consult when building AI SDK chat/agent UIs.
+domain: reference
+category: reference
+tags: [ai-sdk, ai-elements, vercel, shadcn, react, ai-ui]
+official_sources:
+  - https://elements.ai-sdk.dev/
+  - https://github.com/vercel/ai-elements
+verified: 2026-06-16
+---
+
+# Vercel AI SDK — AI Elements
+
+## Overview
+AI Elements is Vercel's component library and custom registry built on top of shadcn/ui to help you build AI-native applications faster. It ships composable, focused pieces (Conversation, Message, Prompt Input, Reasoning, Sources, Tool, Attachments, and more) with deep AI SDK integration — streaming, status states, and type safety built in. Because it follows shadcn/ui conventions, your existing theme applies automatically. Read this when building chat, agent, or generative UIs on the AI SDK.
+
+## Official sources
+- Docs: https://elements.ai-sdk.dev/
+- Repo: https://github.com/vercel/ai-elements
+- Setup: https://elements.ai-sdk.dev/docs/setup
+- AI SDK: https://ai-sdk.dev/
+
+## Install / setup
+```bash
+npx ai-elements@latest
+```
+Add individual components:
+```bash
+npx ai-elements@latest add message
+```
+pnpm/bun equivalents are documented (`pnpm dlx ai-elements@latest`, `bunx --bun ai-elements@latest`); the AI Elements CLI auto-initializes shadcn/ui if it is not already present.
+
+## Core concepts
+- Built on shadcn/ui as a custom registry — components are added into your codebase (copy/own model), not hidden behind a dependency.
+- Deep AI SDK integration: streaming, status states, and type safety are built into the components.
+- Fully composable: small, focused primitives combine into custom chat/agent UIs rather than one monolithic widget.
+- Component families span Chatbot (Conversation, Message, Prompt Input, Reasoning, Sources, Tool, Attachments), Code, Voice, and Workflow.
+- CSS Variables mode only — relies on shadcn/ui's CSS-variable theming, so your tokens style the components.
+
+## Best practices
+- Initialize shadcn/ui and configure Tailwind CSS Variables mode before adding Elements (the CLI can set up shadcn/ui automatically).
+- Run the CLI with your project's package runner (npx/pnpm dlx/bunx) so dependencies match your package manager.
+- Compose primitives (Message + Reasoning + Sources + Tool) instead of building bespoke chat markup, so streaming and status handling come for free.
+- Theme through shadcn/ui CSS variables so Elements inherit your brand automatically.
+
+## Common pitfalls
+- Expecting it to work without shadcn/ui or Tailwind → AI Elements requires shadcn/ui initialized and Tailwind configured (CSS Variables mode).
+- Treating it as an npm UI dependency → components are added into your repo via the registry; you own and customize the code.
+- Skipping the AI SDK wiring → Elements expect AI SDK message/streaming shapes; pair them with the SDK's hooks.
+
+## Examples
+```bash
+# Add a chat conversation surface and prompt input
+npx ai-elements@latest add conversation
+npx ai-elements@latest add prompt-input
+```
+
+## Further reading
+- Components index: https://elements.ai-sdk.dev/
+- AI SDK UI docs: https://ai-sdk.dev/
+
+## Related skills
+- ../ai-attachments-ui — attachment UI patterns in AI Elements
+- ../ai-tool-ui-patterns — rendering tool-call results
+- ../shadcn-tailwind-theming — theming the underlying shadcn/ui layer