takomi 2.0.6 → 2.1.0

package/assets/.agent/skills/21st-dev-components/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: 21st-dev-components
+description: Use when the user wants to build a React site or app section from 21st.dev components, clone the structure of a reference site with 21st.dev building blocks, browse 21st.dev manually and return copied prompts/code, or says things like "build me a site like this", "use 21st.dev", "copy prompt", "component URL", "hero from 21st", or "match this landing page with ready-made components".
+---
+
+# 21st.dev Reference-to-Component Skill
+
+This skill routes between two flows:
+
+- **Auto mode**: the user provides a reference site URL and wants the agent to inspect it, infer the required sections, choose matching 21st.dev components automatically, and integrate them.
+- **Manual mode**: the user wants guided collection. The agent lists the sections, tells the user what to fetch from 21st.dev, then integrates the returned handoff.
+
+Use this skill only for **React-family** projects. If the repo is not React-based, explain that v1 of this skill is React-only and stop.
+
+## Bundled Resources
+
+- `references/categories.md`
+  Use for section-to-category mapping and direct 21st.dev category URLs.
+- `references/manual-handoff-template.md`
+  Use when the user is gathering components manually.
+- `references/section-detection-rubric.md`
+  Use during Auto mode after crawling the reference site.
+- `scripts/resolve-21st-component.mjs`
+  Resolve a 21st.dev component page into normalized metadata.
+- `scripts/fetch-21st-source.mjs`
+  Fetch raw source from 21st CDN URLs.
+- `scripts/build-manual-handoff-template.mjs`
+  Generate a manual handoff markdown file for the user.
+
+## Mode Router
+
+### Use Auto mode when
+
+- The user gives a live reference site URL.
+- The user says "build me something like this", "clone this layout", or "crawl this site and rebuild it".
+- The user expects the agent to choose components automatically.
+
+### Use Manual mode when
+
+- The user says they will browse 21st.dev themselves.
+- The user pastes 21st.dev component URLs, copied prompts, code fences, or a markdown handoff file.
+- The user wants the agent to tell them exactly what sections to gather.
+
+If Auto mode fails because the site is blocked, brittle, or the 21st lookup is weak, fall back to Manual mode immediately and generate the handoff template instead of dead-ending.
+
+## Auto Mode Workflow
+
+### Step 1: Crawl the reference site in a browser
+
+Use the browser-first workflow from the `webapp-testing` skill. Do not rely only on raw HTML if the page is clearly client-rendered.
+
+What to inspect:
+- header / navbar / announcement bars
+- hero block
+- feature grids or card rows
+- social proof / logos
+- testimonials
+- pricing
+- FAQ
+- forms / auth blocks
+- footer
+- app shell elements such as sidebar, table, tabs, or modals
+
+Load `references/section-detection-rubric.md` if the page structure is not obvious.
+
+### Step 2: Build a page anatomy model
+
+Write down the major sections in visual order. For each section, capture:
+- section name
+- rough structure
+- visual tone
+- obvious dependencies such as carousels, motion, video, maps, charts, or forms
+
+### Step 3: Map sections to 21st.dev categories
+
+Load `references/categories.md` and map each detected section to one or more category slugs.
+
+Rules:
+- Match structure first, style second.
+- Use one primary category and optional supporting categories.
+- Decorative elements like shaders, backgrounds, or borders are secondary, not the main section match.
+
+### Step 4: Discover and resolve candidate components
+
+Search 21st.dev for each mapped category. Once you have likely component URLs:
+
+1. Resolve each page:
+   ```bash
+   node scripts/resolve-21st-component.mjs --url "<21st-component-url>" --json
+   ```
+2. Inspect:
+   - dependency count
+   - component/demo CDN URLs
+   - tags
+   - author
+   - registry dependency hints
+
+### Step 5: Choose the best match automatically
+
+Default behavior is **not** to ask the user to choose.
+
+Prefer:
+- closest structural match
+- lowest dependency burden
+- compatibility with the current repo
+- easier adaptation to the existing styling system
+
+### Step 6: Fetch source and integrate
+
+Fetch component/demo source from CDN URLs:
+
+```bash
+node scripts/fetch-21st-source.mjs --url "<code-url>" --url "<demo-code-url>" --out-dir tmp/21st
+```
+
+Then integrate into the repo:
+- adapt file paths to the existing project structure
+- prefer the repo's current component locations
+- prefer existing Tailwind, TypeScript, and shadcn conventions when present
+- if shadcn conventions are absent, adapt rather than forcing `/components/ui`
+- if required dependencies or setup are missing, install/configure them first
+
+### Step 7: Report what was selected
+
+When you finish, state:
+- which sections were detected
+- which 21st.dev components were selected
+- which dependencies were added
+- any sections that required partial custom adaptation
+
+## Manual Mode Workflow
+
+### Step 1: Break the page into sections
+
+Identify the target sections from the user's request or reference URL:
+- header / navbar
+- hero
+- features
+- testimonials
+- pricing
+- footer
+- sidebar
+- CTA
+- forms
+- tables
+- auth
+- FAQ
+
+### Step 2: Tell the user what to collect
+
+Use `references/categories.md` to give the exact 21st.dev category links.
+
+Generate a checklist file when useful:
+
+```bash
+node scripts/build-manual-handoff-template.mjs --sections "header,hero,features,pricing,footer" --out 21st-handoff.md
+```
+
+Point the user at the template in `references/manual-handoff-template.md` if they want to paste directly in chat instead of using a file.
+
+### Step 3: Accept one combined handoff
+
+The handoff can contain:
+- 21st.dev URLs
+- copied prompt blocks
+- code fences
+- dependency lists
+- placement notes
+
+Do not make the user re-explain the same page structure if the handoff already contains it.
+
+### Step 4: Parse and integrate
+
+For each returned section:
+- resolve the component URL if present
+- fetch source if needed
+- merge copied prompt/code information with repo context
+- install dependencies
+- adapt imports, component paths, and utility functions to the current repo
+
+## Integration Rules
+
+- v1 supports React projects broadly.
+- Preserve the repo's existing file layout whenever possible.
+- If Tailwind or TypeScript is missing and the chosen component requires it, explain exactly what must be added before integration.
+- If the component assumes shadcn utilities like `cn` or `@/lib/utils`, either map them to the repo equivalent or add a minimal compatible helper.
+- If one section cannot be matched cleanly, integrate the rest and flag the unmatched section explicitly.
+
+## Failure Handling
+
+- Bad reference URL or blocked crawl: switch to Manual mode and generate a handoff template.
+- 21st.dev page resolves but source URLs are missing: use the copied prompt path or ask for the component's copied prompt/code only for that section.
+- Non-React target repo: explain the limitation and stop.
+
+## Output Defaults
+
+- **Auto mode**: inspect, choose, fetch, integrate, report.
+- **Manual mode**: generate checklist, ingest handoff, integrate, report.

package/assets/.agent/skills/21st-dev-components/references/categories.md

@@ -0,0 +1,91 @@
+# 21st.dev Category Map
+
+Use this file when mapping a reference site's sections to 21st.dev buckets or when generating a manual collection checklist.
+
+## Landing Page Sections
+
+| Section | Primary categories | Secondary categories |
+|---|---|---|
+| Announcement bar | `announcement` | `badge`, `text`, `link` |
+| Header / Navbar | `navbar-navigation` | `announcement`, `button`, `dropdown`, `menu` |
+| Hero | `hero` | `call-to-action`, `background`, `text`, `image` |
+| Feature grid | `features` | `card`, `icons`, `number` |
+| Social proof / logos | `image` | `icons`, `scroll-area` |
+| Testimonials | `testimonials` | `card`, `carousel` |
+| Pricing | `pricing-section` | `comparison`, `card`, `button` |
+| FAQ | `accordion` | `text` |
+| Footer | `footer` | `link`, `button` |
+
+## App / Dashboard Sections
+
+| Section | Primary categories | Secondary categories |
+|---|---|---|
+| Sidebar | `sidebar` | `menu`, `navbar-navigation`, `scroll-area` |
+| Data table | `table` | `pagination`, `tabs`, `card` |
+| Filters / forms | `form` | `input`, `select`, `radio-group`, `checkbox`, `button` |
+| Dialogs | `modal-dialog` | `popover`, `button`, `toast` |
+| Auth | `sign-in`, `registration-signup` | `form`, `input`, `button` |
+| Chat | `ai-chat` | `input`, `button`, `avatar` |
+
+## Raw Category Index
+
+| Slug | Label | Count | URL |
+|---|---|---:|---|
+| `announcement` | Announcements | 10 | `https://21st.dev/s/announcement` |
+| `background` | Backgrounds | 33 | `https://21st.dev/s/background` |
+| `border` | Borders | 12 | `https://21st.dev/s/border` |
+| `call-to-action` | Calls to Action | 34 | `https://21st.dev/s/call-to-action` |
+| `comparison` | Comparisons | 6 | `https://21st.dev/s/comparison` |
+| `dock` | Docks | 6 | `https://21st.dev/s/dock` |
+| `features` | Features | 36 | `https://21st.dev/s/features` |
+| `footer` | Footers | 14 | `https://21st.dev/s/footer` |
+| `hero` | Heroes | 73 | `https://21st.dev/s/hero` |
+| `hook` | Hooks | 31 | `https://21st.dev/s/hook` |
+| `image` | Images | 26 | `https://21st.dev/s/image` |
+| `map` | Maps | 2 | `https://21st.dev/s/map` |
+| `navbar-navigation` | Navigation Menus | 11 | `https://21st.dev/s/navbar-navigation` |
+| `pricing-section` | Pricing Sections | 17 | `https://21st.dev/s/pricing-section` |
+| `scroll-area` | Scroll Areas | 24 | `https://21st.dev/s/scroll-area` |
+| `shader` | Shaders | 15 | `https://21st.dev/s/shader` |
+| `testimonials` | Testimonials | 15 | `https://21st.dev/s/testimonials` |
+| `text` | Texts | 58 | `https://21st.dev/s/text` |
+| `video` | Videos | 9 | `https://21st.dev/s/video` |
+| `accordion` | Accordions | 40 | `https://21st.dev/s/accordion` |
+| `ai-chat` | AI Chats | 30 | `https://21st.dev/s/ai-chat` |
+| `alert` | Alerts | 23 | `https://21st.dev/s/alert` |
+| `avatar` | Avatars | 17 | `https://21st.dev/s/avatar` |
+| `badge` | Badges | 25 | `https://21st.dev/s/badge` |
+| `button` | Buttons | 130 | `https://21st.dev/s/button` |
+| `calendar` | Calendars | 34 | `https://21st.dev/s/calendar` |
+| `card` | Cards | 79 | `https://21st.dev/s/card` |
+| `carousel` | Carousels | 16 | `https://21st.dev/s/carousel` |
+| `checkbox` | Checkboxes | 19 | `https://21st.dev/s/checkbox` |
+| `date-picker` | Date Pickers | 12 | `https://21st.dev/s/date-picker` |
+| `modal-dialog` | Dialogs / Modals | 37 | `https://21st.dev/s/modal-dialog` |
+| `dropdown` | Dropdowns | 25 | `https://21st.dev/s/dropdown` |
+| `empty-state` | Empty States | 1 | `https://21st.dev/s/empty-state` |
+| `file-tree` | File Trees | 2 | `https://21st.dev/s/file-tree` |
+| `upload-download` | File Uploads | 7 | `https://21st.dev/s/upload-download` |
+| `form` | Forms | 23 | `https://21st.dev/s/form` |
+| `icons` | Icons | 10 | `https://21st.dev/s/icons` |
+| `input` | Inputs | 102 | `https://21st.dev/s/input` |
+| `link` | Links | 13 | `https://21st.dev/s/link` |
+| `menu` | Menus | 18 | `https://21st.dev/s/menu` |
+| `notification` | Notifications | 5 | `https://21st.dev/s/notification` |
+| `number` | Numbers | 18 | `https://21st.dev/s/number` |
+| `pagination` | Paginations | 20 | `https://21st.dev/s/pagination` |
+| `popover` | Popovers | 23 | `https://21st.dev/s/popover` |
+| `radio-group` | Radio Groups | 22 | `https://21st.dev/s/radio-group` |
+| `select` | Selects | 62 | `https://21st.dev/s/select` |
+| `sidebar` | Sidebars | 10 | `https://21st.dev/s/sidebar` |
+| `sign-in` | Sign Ins | 4 | `https://21st.dev/s/sign-in` |
+| `registration-signup` | Sign ups | 4 | `https://21st.dev/s/registration-signup` |
+| `slider` | Sliders | 45 | `https://21st.dev/s/slider` |
+| `spinner-loader` | Spinner Loaders | 21 | `https://21st.dev/s/spinner-loader` |
+| `table` | Tables | 30 | `https://21st.dev/s/table` |
+| `tabs` | Tabs | 38 | `https://21st.dev/s/tabs` |
+| `chip-tag` | Tags | 6 | `https://21st.dev/s/chip-tag` |
+| `textarea` | Text Areas | 22 | `https://21st.dev/s/textarea` |
+| `toast` | Toasts | 2 | `https://21st.dev/s/toast` |
+| `toggle` | Toggles | 12 | `https://21st.dev/s/toggle` |
+| `tooltip` | Tooltips | 28 | `https://21st.dev/s/tooltip` |

package/assets/.agent/skills/21st-dev-components/references/manual-handoff-template.md

@@ -0,0 +1,79 @@
+# 21st.dev Manual Handoff Template
+
+Use this structure when the user is gathering 21st.dev pieces manually.
+
+## Skeleton
+
+Copy this into a markdown file or paste it into chat:
+
+```text
+# 21st.dev Manual Handoff
+
+Reference URL:
+https://example.com
+
+Page goal:
+Build a React landing page inspired by the reference site.
+
+Desired page order:
+- header
+- hero
+- features
+- testimonials
+- pricing
+- footer
+
+General project notes:
+- Framework: React / Next.js / Vite
+- Styling stack: Tailwind / CSS modules / other
+- Existing component path:
+- Constraints:
+
+## header
+Suggested 21st.dev categories used:
+- https://21st.dev/s/navbar-navigation
+- https://21st.dev/s/announcement
+
+Chosen 21st.dev URLs:
+- https://21st.dev/community/components/<author>/<component>/<demo>
+
+Copy prompt or notes:
+[Paste the 21st.dev "Copy prompt" block here.]
+
+Component code blocks:
+[Paste component source here when needed.]
+
+Dependencies:
+- lucide-react
+- framer-motion
+
+Placement / styling notes:
+- Use as the top sticky navigation.
+
+## hero
+Suggested 21st.dev categories used:
+- https://21st.dev/s/hero
+- https://21st.dev/s/call-to-action
+
+Chosen 21st.dev URLs:
+- 
+
+Copy prompt or notes:
+[Paste copied prompt text here.]
+
+Component code blocks:
+[Paste source code here if needed.]
+
+Dependencies:
+- 
+
+Placement / styling notes:
+- 
+```
+
+## Rules
+
+- Keep one section per page slice.
+- Put every chosen 21st.dev URL in the same document.
+- Include dependency names exactly as shown on 21st.dev or in the copied prompt.
+- If you paste source, include the original filename immediately above the pasted code when possible.

package/assets/.agent/skills/21st-dev-components/references/section-detection-rubric.md

@@ -0,0 +1,59 @@
+# Reference Site Section Detection Rubric
+
+Use this when Auto mode crawls a reference site and needs to infer which 21st.dev component families to search.
+
+## Detection Order
+
+1. Capture the page at the top of the viewport.
+2. Identify the persistent shell first:
+   - announcement bar
+   - navbar / header
+   - sidebar / dock
+3. Walk top to bottom through the main content:
+   - hero
+   - trust / logos
+   - features
+   - stats / numbers
+   - gallery / image / video blocks
+   - testimonials
+   - pricing / comparison
+   - FAQ / accordion
+   - forms / CTA
+   - footer
+4. Record both structure and visual traits:
+   - column count
+   - card density
+   - media-heavy or text-heavy
+   - dark / light
+   - animated / static
+   - decorative borders, shaders, or backgrounds
+
+## DOM / Visual Heuristics
+
+| Signal | Likely section |
+|---|---|
+| Top horizontal bar with few links + logo + CTA | `header`, `navbar` |
+| Large headline + supporting copy + CTA near page top | `hero` |
+| Repeating 3-6 cards with icons or short bullets | `features` |
+| Customer quotes, avatars, star ratings | `testimonials` |
+| Tiered cards with prices, plan names, feature lists | `pricing` |
+| Expand/collapse question rows | `faq` |
+| Long form fields, search, email capture, sign-in area | `form`, `auth` |
+| Fixed left navigation or app shell | `sidebar` |
+| Repeating rows/columns of data | `table`, `dashboard` |
+| Large media, video poster, or carousel | `video`, `gallery`, `carousel` |
+
+## Category Mapping Rules
+
+- Prefer the exact section category first, then layer supporting categories.
+- For minimalist landing pages, combine `hero` with `text`, `image`, `background`, or `border`.
+- For app-like layouts, combine `sidebar`, `table`, `tabs`, `card`, and `pagination`.
+- If a block is visually impressive but structurally thin, use a decorative category like `background`, `shader`, or `border` in addition to the main section category.
+
+## Selection Rules
+
+- Match structure before style.
+- Prefer fewer external dependencies when two candidates are equally good.
+- Prefer components whose dependency list fits the target repo.
+- Prefer components whose layout can be adapted without rewriting most of the markup.
+- If the site has a clearly custom section with no close match, fall back to Manual mode for that section only.