@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/minimalist-ui/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: minimalist-ui
+description: Use INSTEAD OF design-taste-frontend when user requests clean, editorial, or minimalist aesthetics. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
+---
+
+## When to Use
+
+- When the user requests clean, editorial, or minimalist aesthetics
+- For content-focused sites, blogs, or documentation pages
+- Instead of design-taste-frontend when warm monochrome and flat layouts are desired
+
+## When NOT to Use
+
+- When bold, attention-grabbing, or luxury visual design is requested
+- For data-heavy dashboards that need dense information display
+- When industrial-brutalist-ui or high-end-visual-design is a better fit
+
+
+# Protocol: Premium Utilitarian Minimalism UI Architect
+
+## 1. Protocol Overview
+Name: Premium Utilitarian Minimalism & Editorial UI
+Description: An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
+
+## 2. Absolute Negative Constraints (Banned Elements)
+The AI must strictly avoid the following generic web development defaults:
+- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
+- DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
+- DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
+- DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections).
+- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
+- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
+- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives.
+- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
+- DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
+
+## 3. Typographic Architecture
+The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel.
+- Primary Sans-Serif (Body, UI, Buttons): Use clean, geometric, or system-native fonts with character. Target: `font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`.
+- Editorial Serif (Hero Headings & Quotes): Target: `font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`. Apply tight tracking (`letter-spacing: -0.02em` to `-0.04em`) and tight line-height (`1.1`).
+- Monospace (Code, Keystrokes, Meta-data): Target: `font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`.
+- Text Colors: Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous `line-height` of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
+
+## 4. Color Palette (Warm Monochrome + Spot Pastels)
+Color is a scarce resource, utilized only for semantic meaning or subtle accents.
+- Canvas / Background: Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
+- Primary Surface (Cards): `#FFFFFF` or `#F9F9F8`.
+- Structural Borders / Dividers: Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
+- Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds.
+  - Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
+  - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
+  - Pale Green: `#EDF3EC` (Text: `#346538`)
+  - Pale Yellow: `#FBF3DB` (Text: `#956400`)
+
+## 5. Component Specifications
+- Bento Box Feature Grids:
+  - Utilize asymmetrical CSS Grid layouts.
+  - Cards must have exactly `border: 1px solid #EAEAEA`.
+  - Border-radius must be crisp: `8px` or `12px` maximum.
+  - Internal padding must be generous (e.g., `24px` to `40px`).
+- Primary Call-To-Action (Buttons):
+  - Solid background `#111111`, text `#FFFFFF`. 
+  - Slight border-radius (`4px` to `6px`). No box-shadow. 
+  - Hover state should be a subtle color shift to `#333333` or a micro-scale `transform: scale(0.98)`.
+- Tags & Status Badges:
+  - Pill-shaped (`border-radius: 9999px`), very small typography (`text-xs`), uppercase with wide tracking (`letter-spacing: 0.05em`).
+  - Background must use the defined Muted Pastels.
+- Accordions (FAQ):
+  - Strip all container boxes. Separate items only with a `border-bottom: 1px solid #EAEAEA`.
+  - Use a clean, sharp `+` and `-` icon for the toggle state.
+- Keystroke Micro-UIs:
+  - Render shortcuts as physical keys using `<kbd>` tags: `border: 1px solid #EAEAEA`, `border-radius: 4px`, `background: #F7F6F3`, using the Monospace font.
+- Faux-OS Window Chrome:
+  - When mocking up software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (replicating macOS window controls).
+
+## 6. Iconography & Imagery Directives
+- System Icons: Use "Phosphor Icons (Bold or Fill weights)" or "Radix UI Icons" for a technical, slightly thicker-stroke aesthetic. Standardize stroke width across all icons.
+- Illustrations: Monochromatic, rough continuous-line ink sketches on a white background, featuring a single offset geometric shape filled with a muted pastel color.
+- Photography: Use high-quality, desaturated images with a warm tone. Apply subtle overlays (`opacity: 0.04` warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use reliable placeholders like `https://picsum.photos/seed/{context}/1200/800` when real assets are unavailable.
+- Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (`radial-gradient` with warm tones at `opacity: 0.03`), or minimal geometric line patterns to add depth without breaking the clean aesthetic.
+
+## 7. Subtle Motion & Micro-Animations
+Motion should feel invisible — present but never distracting. The goal is quiet sophistication, not spectacle.
+- Scroll Entry: Elements fade in gently as they enter the viewport. Use `translateY(12px)` + `opacity: 0` resolving over `600ms` with `cubic-bezier(0.16, 1, 0.3, 1)`. Use `IntersectionObserver`, never `window.addEventListener('scroll')`.
+- Hover States: Cards lift with an ultra-subtle shadow shift (`box-shadow` transitioning from `0 0 0` to `0 2px 8px rgba(0,0,0,0.04)` over `200ms`). Buttons respond with `scale(0.98)` on `:active`.
+- Staggered Reveals: Lists and grid items enter with a cascade delay (`animation-delay: calc(var(--index) * 80ms)`). Never mount everything at once.
+- Background Ambient Motion: Optional. A single, very slow-moving radial gradient blob (`animation-duration: 20s+`, `opacity: 0.02-0.04`) drifting behind hero sections. Must be applied to a `position: fixed; pointer-events: none` layer. Never on scrolling containers.
+- Performance: Animate exclusively via `transform` and `opacity`. No layout-triggering properties (`top`, `left`, `width`, `height`). Use `will-change: transform` sparingly and only on actively animating elements.
+
+## 8. Execution Protocol
+When tasked with writing frontend code (HTML, React, Tailwind, Vue) or designing a layout:
+1. Establish the macro-whitespace first. Use massive vertical padding between sections (e.g., `py-24` or `py-32` in Tailwind).
+2. Constrain the main typography content width to `max-w-4xl` or `max-w-5xl`.
+3. Apply the custom typographic hierarchy and monochromatic color variables immediately.
+4. Ensure every card, divider, and border adheres strictly to the `1px solid #EAEAEA` rule.
+5. Add scroll-entry animations to all major content blocks.
+6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures — no empty flat backgrounds.
+7. Provide code that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments.

package/dist/template/.opencode/skill/mockup-to-code/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: mockup-to-code
+description: Use when converting UI mockups, screenshots, Figma/Sketch designs, wireframes, or building component libraries from design systems into production-ready code
+version: 1.0.0
+tags: [ui, workflow]
+dependencies: []
+---
+
+# Mockup to Code Skill
+
+> **Replaces** manual pixel-by-pixel CSS translation from designs — structured extraction of layout, colors, typography, and components from visual references
+
+## When to Use
+
+- Converting Figma/Sketch mockups to React/Vue/HTML
+- Implementing pixel-perfect designs
+- Building component libraries from design systems
+- Rapid prototyping from wireframes
+
+## When NOT to Use
+
+- No visual reference or mockup to implement.
+
+## Workflow
+
+1. **Analyze** — Use vision agent to extract: layout structure, color palette, typography, spacing, components
+2. **Map** — Match extracted elements to existing design tokens/components in the codebase
+3. **Implement** — Build components using extracted specs, reusing existing tokens where possible
+4. **Verify** — Screenshot the result and compare visually to the original mockup
+
+## Core Workflow
+
+### Phase 1: Design Analysis
+
+```
+Analyze this UI mockup and extract:
+
+1. LAYOUT STRUCTURE
+   - Grid system (columns, gutters, margins)
+   - Component hierarchy
+   - Container widths
+
+2. VISUAL SPECIFICATIONS
+   - Colors (hex values)
+   - Typography (sizes, weights)
+   - Spacing (padding, margins, gaps)
+   - Border radius, shadows
+
+3. COMPONENTS IDENTIFIED
+   - List each distinct component
+   - Note variations
+   - Identify reusable patterns
+
+4. RESPONSIVE CONSIDERATIONS
+   - How might this adapt to mobile?
+   - Collapsible sections
+   - Priority content
+
+Output as structured JSON.
+```
+
+### Phase 2: Component Breakdown
+
+```markdown
+## Component: [Name]
+
+**Priority:** High/Medium/Low
+**Complexity:** Simple/Medium/Complex
+**Reusability:** One-off/Reusable/Design System
+
+**Props Interface:**
+
+- variant: 'primary' | 'secondary'
+- size: 'sm' | 'md' | 'lg'
+- disabled?: boolean
+
+**Accessibility:**
+
+- Keyboard navigation
+- ARIA labels
+- Focus management
+```
+
+### Phase 3: Implementation
+
+Implement with comparison loop:
+
+```
+Compare mockup vs implementation:
+
+1. What differences do you see?
+2. What's missing?
+3. Spacing/sizing adjustments needed?
+4. Color accuracy?
+5. Typography match?
+
+Prioritize fixes by visual impact.
+```
+
+## Technology Patterns
+
+### React + Tailwind
+
+```
+Convert to React with Tailwind CSS.
+
+Requirements:
+- Functional components with TypeScript
+- Tailwind utility classes
+- Extract repeated patterns
+- Semantic HTML
+- Responsive classes (sm:, md:, lg:)
+```
+
+### Vue 3
+
+```
+Convert to Vue 3 component.
+
+Requirements:
+- Composition API with <script setup>
+- Scoped styles
+- Props with TypeScript
+```
+
+### Plain HTML/CSS
+
+```
+Convert to semantic HTML and CSS.
+
+Requirements:
+- Semantic HTML5 elements
+- CSS Grid/Flexbox layout
+- CSS custom properties
+```
+
+## Quality Checklist
+
+### Visual Fidelity
+
+- [ ] Colors match exactly
+- [ ] Typography matches
+- [ ] Spacing is consistent
+- [ ] Border radius matches
+- [ ] Shadows correct
+
+### Responsiveness
+
+- [ ] Desktop layout matches
+- [ ] Tablet works
+- [ ] Mobile is usable
+- [ ] No horizontal scroll
+
+### Interactions
+
+- [ ] Hover states
+- [ ] Focus states
+- [ ] Transitions smooth
+
+### Code Quality
+
+- [ ] Properly typed
+- [ ] Sensible defaults
+- [ ] Uses tokens (no hardcoded values)
+- [ ] Accessible markup
+
+## Anti-Patterns
+
+| Anti-Pattern                                                           | Why It Fails                                                | Instead                                                                 |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Hardcoding colors/sizes instead of using design tokens                 | Creates inconsistency and makes global updates expensive    | Map values to existing tokens first; add new tokens only when truly new |
+| Building from scratch when existing components cover 80% of the design | Reintroduces solved problems and increases maintenance cost | Compose and extend existing components, then patch gaps                 |
+| Pixel-perfect matching without responsive considerations               | Breaks on different viewport sizes and device classes       | Match intent at multiple breakpoints and validate mobile/tablet/desktop |
+| Not extracting reusable components from repeated patterns              | Duplicates code and drifts visual behavior over time        | Promote repeated UI blocks into reusable components with variants       |
+
+## Storage
+
+Save implementations to `.opencode/memory/design/implementations/`
+
+## See Also
+
+- `frontend-design`
+- `visual-analysis`
+- `accessibility-audit`

package/dist/template/.opencode/skill/opensrc/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: opensrc
+description: Use when you need to understand how a library works internally, debug dependency issues, or inspect package source code beyond types and docs. Fetches source for npm, PyPI, crates.io packages and GitHub repos. Includes structured research workflow for deep investigation.
+version: 1.1.0
+tags: [research, integration, source-code]
+dependencies: []
+---
+
+# opensrc
+
+Fetch and inspect dependency source code, then run a structured research workflow to answer implementation-level questions with evidence.
+
+## When to Use
+
+- Need to understand how a library/package works internally (not just its interface)
+- Debugging issues where types or docs are insufficient
+- Exploring implementation patterns in dependencies
+- Investigating edge cases and behavior not documented officially
+- Evaluating dependency quality before adoption
+
+## When NOT to Use
+
+- Official docs already answer the question (check Context7 first)
+- You only need public API syntax or quick examples
+- The target is your own codebase (use project search/LSP tools)
+
+## Quick Start
+
+```bash
+# Install globally or use npx
+npm install -g opensrc
+
+# Fetch npm package (auto-detects installed version from lockfile)
+npx opensrc zod
+
+# Fetch from other registries
+npx opensrc pypi:requests       # Python/PyPI
+npx opensrc crates:serde        # Rust/crates.io
+
+# Fetch GitHub repo directly
+npx opensrc vercel/ai           # owner/repo shorthand
+npx opensrc github:owner/repo   # explicit prefix
+npx opensrc https://github.com/colinhacks/zod  # full URL
+
+# Fetch specific version/ref
+npx opensrc zod@3.22.0
+npx opensrc owner/repo@v1.0.0
+```
+
+## Commands
+
+| Command                 | Description                     |
+| ----------------------- | ------------------------------- |
+| `opensrc <packages...>` | Fetch source for packages/repos |
+| `opensrc list`          | List all fetched sources        |
+| `opensrc remove <name>` | Remove specific source          |
+| `opensrc clean`         | Remove all sources              |
+
+## Output Structure
+
+After fetching, sources are stored in `opensrc/`:
+
+```
+opensrc/
+├── settings.json           # User preferences
+├── sources.json            # Index of fetched packages/repos
+└── repos/
+    └── github.com/
+        └── owner/
+            └── repo/       # Cloned source code
+```
+
+## File Modifications
+
+On first run, opensrc may prompt to modify:
+
+- `.gitignore` - adds `opensrc/` to ignore list
+- `tsconfig.json` - excludes `opensrc/` from compilation
+- `AGENTS.md` - adds section pointing agents to source code
+
+Use `--modify` or `--modify=false` to control this behavior.
+
+## Key Behaviors
+
+1. **Version Detection** - For npm, auto-detects installed version from `node_modules`, `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`
+2. **Repository Resolution** - Resolves package to its git repo via registry API, clones at matching tag
+3. **Monorepo Support** - Handles packages in monorepos via `repository.directory`
+4. **Shallow Clone** - Uses `--depth 1` for efficient cloning, removes `.git` after clone
+5. **Tag Fallback** - Tries `v{version}`, `{version}`, then default branch if tag not found
+
+## Research Workflow (Structured)
+
+Use this 5-step workflow for deep investigations.
+
+### Step 1: Identify
+
+Define the smallest useful target and scope:
+
+- Package/repo name and version
+- Specific question (e.g., retry behavior, parsing path, cache invalidation)
+- Candidate symbols/files to inspect first
+
+```bash
+# Good: scoped target with version
+npx opensrc zod@3.22.0
+
+# Also valid
+npx opensrc pypi:requests
+npx opensrc crates:serde
+npx opensrc vercel/ai@v3.0.0
+```
+
+### Step 2: Fetch
+
+Fetch source with opensrc and confirm location:
+
+```bash
+npx opensrc <target>
+npx opensrc list
+```
+
+Expected result:
+
+- Source cloned into `opensrc/repos/<host>/<owner>/<repo>/`
+- Metadata recorded in `opensrc/sources.json`
+
+### Step 3: Locate
+
+Find relevant files/symbols before deep reading:
+
+- Search by exported symbol names, error classes, feature flags, config keys
+- Prefer implementation files over declaration/type-only files
+- Include tests/examples to infer intended behavior
+
+Suggested search sequence:
+
+1. Entry points (`index`, `main`, package exports)
+2. Core implementation modules
+3. Tests and fixtures
+4. Changelog/release notes for behavioral changes
+
+### Step 4: Analyze
+
+Read code paths end-to-end and collect evidence:
+
+- Trace function call flow from public API to internal logic
+- Note edge-case guards, fallbacks, and error paths
+- Distinguish public API from private/internal contracts
+- Record exact file:line evidence for each claim
+
+Evidence standard:
+
+- Prefer direct source snippets + `file:line`
+- Mark uncertain conclusions explicitly
+- Avoid claims based only on docs/types when source contradicts them
+
+### Step 5: Document
+
+Write findings in a reusable format:
+
+```markdown
+# Research: <library>
+
+- Package/Version: <name@version>
+- Source Path: opensrc/repos/<host>/<owner>/<repo>
+- Research Question: <question>
+
+## Findings
+1. <claim>
+   - Evidence: `path/to/file.ts:42-68`
+   - Confidence: High | Medium | Low
+
+## Answer
+- <direct answer to original question>
+
+## Caveats
+- Version-specific behavior and limits
+```
+
+## Integration with Other Research Methods
+
+Use source inspection as part of a layered approach:
+
+| Method         | Best For                   | Source Code Adds               |
+| -------------- | -------------------------- | ------------------------------ |
+| **Context7**   | API docs, official guides  | Implementation details         |
+| **codesearch** | Usage patterns in the wild | Canonical implementation       |
+| **grepsearch** | Real-world examples        | How library itself works       |
+| **Web search** | Tutorials, blog posts      | Ground truth from source       |
+| **Codebase**   | Project-specific patterns  | How dependencies actually work |
+
+Recommended order:
+
+1. Context7 (official docs)
+2. Local codebase usage
+3. **opensrc source inspection**
+4. codesearch/grepsearch external usage patterns
+5. Web search for supplementary context
+
+## Limitations
+
+### When Source Code May Not Fully Explain Runtime Behavior
+
+- **Build-time transforms**: transpilation/macros/plugins can alter runtime shape
+- **Native modules**: C/C++/Rust bindings require native-level inspection
+- **Generated/minified artifacts**: published package may omit readable source
+- **Monorepo indirection**: behavior may span multiple internal packages
+- **Environment-specific paths**: Node/browser/edge branches can diverge
+
+### Practical Alternatives
+
+If opensrc is incomplete or blocked:
+
+1. Browse repository directly on GitHub
+2. Use `npm pack <package>` and inspect tarball contents
+3. Inspect installed `node_modules/<package>/` output
+4. Use source maps during runtime debugging when available
+
+## Common Workflows
+
+### Fetching a Package
+
+```bash
+# Understand zod implementation
+npx opensrc zod
+# → detects version from lockfile
+# → resolves registry metadata
+# → clones matching tag/revision
+```
+
+### Updating Sources
+
+```bash
+# Re-run to refresh against current installed version
+npx opensrc zod
+```
+
+### Multiple Sources
+
+```bash
+npx opensrc react react-dom next
+npx opensrc zod pypi:pydantic vercel/ai
+```
+
+### Cleanup
+
+```bash
+# Remove one source
+npx opensrc remove <package>
+
+# Remove all sources
+npx opensrc clean
+
+# Remove by ecosystem
+npx opensrc clean --npm --pypi --crates
+```
+
+## Success Criteria
+
+You are done when all are true:
+
+- [ ] Fetched the correct package/repo and version
+- [ ] Located the exact implementation path relevant to the question
+- [ ] Verified behavior by reading source (not only types/docs)
+- [ ] Captured file:line evidence for major claims
+- [ ] Answered the original question with explicit confidence
+- [ ] Documented caveats (version bounds, private API risks)
+
+## References
+
+Core opensrc references:
+
+- [CLI Usage & Options](references/cli-usage.md) - Full command reference
+- [Architecture](references/architecture.md) - Code structure and extension
+- [Registry Support](references/registry-support.md) - npm, PyPI, crates.io details
+
+Research workflow references (merged from source-code-research):
+
+- [Common Patterns](references/common-patterns.md) - Error handling, tracing behavior, quality evaluation patterns
+- [Source Structure](references/source-structure.md) - npm/PyPI/Rust source layouts
+- [Analysis Tips](references/analysis-tips.md) - Tests, examples, changelog, types, blame
+- [Example Workflow](references/example-workflow.md) - End-to-end library investigation example
+- [Anti-Patterns](references/anti-patterns.md) - What not to do when researching
+- [Further Reading](references/further-reading.md) - External links and complementary resources