@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/deprecation-and-migration/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: deprecation-and-migration
+description: Use when deprecating APIs, migrating between library versions, removing legacy code, or planning breaking changes — covers deprecation notices, migration guides, codemods, and staged rollout
+version: 1.0.0
+tags: [architecture, workflow]
+dependencies: []
+---
+
+# Deprecation & Migration
+
+> **Replaces** sudden breaking changes with structured, communicable transitions that give consumers time to adapt
+
+## When to Use
+
+- Deprecating an API endpoint, function, or module
+- Migrating between major library/framework versions
+- Removing legacy code paths or feature flags
+- Planning breaking changes across multiple consumers
+
+## When NOT to Use
+
+- Internal refactors that don't affect any public API or consumer
+- Bug fixes that change behavior (that's a fix, not a migration)
+- Adding new features alongside existing ones (no deprecation needed)
+
+## Overview
+
+Deprecation is a communication protocol. Migration is the execution plan. Both must be explicit, gradual, and reversible until the cutover point.
+
+**Core principle:** Never remove without warning. Never warn without a replacement. Never migrate without a rollback plan.
+
+## Deprecation Process
+
+```
+1. ANNOUNCE  — Mark as deprecated with notice + replacement + timeline
+2. PROVIDE   — Ship the replacement alongside the deprecated code
+3. MIGRATE   — Help consumers move (codemods, guides, examples)
+4. MONITOR   — Track usage of deprecated paths
+5. REMOVE    — Remove only after usage drops to zero (or deadline passes)
+```
+
+## Deprecation Notices
+
+### In Code
+
+```typescript
+/**
+ * @deprecated Use `createUser()` instead. Will be removed in v3.0.
+ * Migration guide: https://docs.example.com/migrate-v3
+ */
+export function addUser(name: string): User {
+  console.warn(
+    "addUser() is deprecated. Use createUser() instead. See: https://docs.example.com/migrate-v3",
+  );
+  return createUser({ name });
+}
+```
+
+### Checklist
+
+- [ ] `@deprecated` JSDoc tag with replacement name
+- [ ] Runtime warning on first call (not every call — use a flag)
+- [ ] Migration guide URL in the deprecation message
+- [ ] Removal version/date specified
+- [ ] TypeScript: mark with `@deprecated` for IDE strikethrough
+
+## Migration Guide Template
+
+```markdown
+# Migration: v2 → v3
+
+## Breaking Changes
+
+| Change                   | Before          | After                  | Effort |
+| ------------------------ | --------------- | ---------------------- | ------ |
+| `addUser` → `createUser` | `addUser(name)` | `createUser({ name })` | S      |
+| Config format changed    | `config.key`    | `config.settings.key`  | M      |
+
+## Step-by-Step
+
+1. Update dependency: `npm install pkg@3.0.0`
+2. Run codemod: `npx pkg-migrate v2-to-v3`
+3. Manual fixes: [list of manual changes]
+4. Verify: `npm test && npm run typecheck`
+
+## Rollback
+
+If issues arise: `npm install pkg@2.x.x` — v2 APIs still work until v4.
+
+## Timeline
+
+- v2.5.0: Deprecation warnings added
+- v3.0.0: New API shipped, old API still works with warnings
+- v3.5.0: Old API removed (6 months after v3.0.0)
+```
+
+## Codemod Patterns
+
+### Simple Find & Replace
+
+```typescript
+// jscodeshift transform
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  return j(file.source)
+    .find(j.CallExpression, { callee: { name: "addUser" } })
+    .forEach((path) => {
+      path.node.callee.name = "createUser";
+      // Wrap string arg in object: addUser("name") → createUser({ name: "name" })
+      const arg = path.node.arguments[0];
+      path.node.arguments = [j.objectExpression([j.property("init", j.identifier("name"), arg)])];
+    })
+    .toSource();
+}
+```
+
+### When to Write a Codemod
+
+| Consumers       | Change Complexity   | Write Codemod?                             |
+| --------------- | ------------------- | ------------------------------------------ |
+| 1-5 call sites  | Simple rename       | No — manual is faster                      |
+| 5-20 call sites | Simple rename       | Maybe — saves time and ensures consistency |
+| 20+ call sites  | Any change          | Yes — manual migration is error-prone      |
+| Any count       | Complex restructure | Yes — reduce human error                   |
+
+## Staged Rollout
+
+```
+Phase 1: Ship new API alongside old (backward compatible)
+  └── Duration: 1-2 release cycles
+  └── Verify: New API works, old API still works
+
+Phase 2: Add deprecation warnings to old API
+  └── Duration: 2-4 release cycles
+  └── Monitor: Track warning frequency, identify stragglers
+
+Phase 3: Remove old API
+  └── Only when: Usage is zero OR deadline passed
+  └── Verify: No references remain in codebase
+  └── Rollback: Revert removal if unexpected breakage
+```
+
+## Common Rationalizations
+
+| Excuse                                 | Rebuttal                                                                           |
+| -------------------------------------- | ---------------------------------------------------------------------------------- |
+| "Nobody uses the old API"              | Prove it with usage data. Assumption ≠ evidence.                                   |
+| "It's an internal API, just change it" | Internal consumers break too. Deprecate or coordinate.                             |
+| "Deprecation warnings are noisy"       | That's the point — they surface migration debt before it becomes an emergency.     |
+| "We'll document later"                 | Undocumented breaking changes cause support load that dwarfs documentation effort. |
+| "The codemod is too much work"         | One codemod saves N manual migrations. Calculate the actual ROI.                   |
+| "Just bump the major version"          | A version bump without a migration path is abandonment, not deprecation.           |
+
+## Feature Flag Cleanup
+
+Feature flags are a form of deprecation — they accumulate if not cleaned up.
+
+```
+1. Deploy feature behind flag (OFF)
+2. Enable for team → canary → percentage → 100%
+3. Once stable at 100%: REMOVE the flag
+4. Delete: flag definition, branching code, old code path
+5. Verify: tests pass without the flag
+```
+
+**Flag lifecycle max:** 30 days at 100% before cleanup is mandatory.
+
+## Red Flags — STOP
+
+- Breaking change shipped without deprecation period
+- Deprecated code removed before usage reaches zero
+- No migration guide or codemod for complex changes
+- Feature flags older than 90 days without cleanup plan
+- Runtime deprecation warnings suppressed instead of addressed
+
+## Verification
+
+- [ ] Deprecated APIs have `@deprecated` tags with replacement
+- [ ] Runtime warnings fire on deprecated API usage
+- [ ] Migration guide exists with step-by-step + rollback
+- [ ] Usage of deprecated paths is tracked/monitored
+- [ ] Feature flags have documented cleanup dates
+- [ ] Codemod written for changes affecting 20+ call sites
+
+## See Also
+
+- **api-and-interface-design** — Designing APIs that minimize future deprecation
+- **incremental-implementation** — Migrating in thin vertical slices
+- **documentation-and-adrs** — Recording the decision to deprecate/migrate

package/dist/template/.opencode/skill/design-direction-advisor/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: design-direction-advisor
+description: Use when the user's design brief is vague ("make it look good", "design something", "I don't know what style I want", "make me a nice-looking page") OR when no brand context exists. Recommends 3 differentiated directions from 5 design schools × 20 named designer philosophies (Pentagram, Field.io, Kenya Hara, Sagmeister, etc.) with parallel visual demos so the user can choose by seeing, not imagining.
+---
+
+# Design Direction Advisor (Fallback Mode)
+
+> Adapted from `huashu-design`. When you don't have brand context and the user's brief is too vague to execute, **don't guess from generic intuition** — that produces AI slop. Convert ambiguity into structured choice.
+
+## When to Trigger
+
+- Vague briefs: "make it look good", "design something", "make me a page", "I don't know what I want"
+- User explicitly asks: "recommend a style", "give me some directions", "pick a philosophy", "show me different styles"
+- No design context exists: no design system, no brand kit, no Figma, no reference site
+- User says "I don't know what style I want either"
+
+## When to Skip
+
+- User already provided clear references (Figma / screenshots / brand spec) → run `brand-asset-protocol` instead
+- User already specified the direction ("Apple Silicon launch event style") → go directly to execution
+- Small fix or specific tool call ("convert this HTML to PDF") → skip
+- Uncertain → use the lightest version: list 3 directions in 2 sentences each and let the user pick. Don't generate demos prematurely.
+
+## The 8-Phase Flow
+
+### Phase 1 — Deep-Understand the Need
+
+Ask up to **3** focused questions (skip if already clear):
+
+- Target audience?
+- Core message?
+- Emotional tone?
+- Output format? (web page / slide / animation / app mockup)
+
+### Phase 2 — Advisor-Style Restatement (~150 words)
+
+In your own words, restate: the essential need, audience, scenario, emotional tone. End with: _"Based on this understanding, I've prepared 3 design directions for you."_
+
+This forces alignment before generation. If the restatement is wrong, the user corrects you cheaply.
+
+### Phase 3 — Recommend 3 Differentiated Philosophies
+
+Each direction must include:
+
+- **Named designer or studio** — "Kenya Hara-style Eastern minimalism," not just "minimalism"
+- 50-100 words explaining _why this designer fits your brief_
+- 3-4 signature visual features
+- 3-5 vibe keywords
+- Optional reference work
+
+**Differentiation rule (non-negotiable):** the 3 directions must come from **3 different schools** for clear visual contrast.
+
+### The 5 Schools × 20 Philosophies
+
+| School                               | Vibe                                    | Best as                         | Designers (pick 1 per recommendation)                             |
+| ------------------------------------ | --------------------------------------- | ------------------------------- | ----------------------------------------------------------------- |
+| **Information Architecture (01-04)** | Rational, data-driven, restrained       | Safe / professional choice      | Pentagram (Bierut), Stamen Design, Information Architects, Fathom |
+| **Motion Poetics (05-08)**           | Dynamic, immersive, technical aesthetic | Bold / cutting-edge choice      | Locomotive, Active Theory, Field.io, Resn                         |
+| **Minimalism (09-12)**               | Order, whitespace, refinement           | Safe / premium choice           | Experimental Jetset, Müller-Brockmann, Build, Sagmeister & Walsh  |
+| **Experimental Avant-garde (13-16)** | Generative art, visual impact           | Bold / innovative choice        | Zach Lieberman, Raven Kwok, Ash Thorp, Territory Studio           |
+| **Eastern Philosophy (17-20)**       | Warm, poetic, contemplative             | Differentiation / unique choice | Takram, Kenya Hara, Irma Boom, Neo Shen                           |
+
+❌ **Forbidden**: recommending 2 or more from the same school. Insufficient differentiation = user can't tell them apart.
+
+A good triplet typically pairs **one safe + one bold + one differentiating** choice.
+
+### Phase 4 — Show Reference Examples (Visual Anchor)
+
+Before generating live demos, **show 2-3 reference images per direction** if you can fetch them (search the designer's known projects). The user calibrates "yes, that vibe" or "no, not what I meant" against real work, not your description.
+
+Phrasing: _"Before I spin up live demos, here's how each style looks in similar scenarios →"_ then show references.
+
+### Phase 5 — Generate 3 Visual Demos
+
+> **Core principle: seeing beats describing.** Don't make the user imagine — show them.
+
+For each of the 3 directions, generate one demo using the user's **real content/topic**, not lorem ipsum.
+
+- **If parallel subagents are supported:** dispatch 3 in parallel (file-disjoint, see AGENTS.md "Parallel Execution Rules")
+- **If serial:** generate one at a time, all 3 before showing
+
+| Style type        | Demo path                                                         |
+| ----------------- | ----------------------------------------------------------------- |
+| HTML-friendly     | Generate full HTML → screenshot via Playwright                    |
+| AI-image-friendly | Use image generation (e.g. nano-banana-pro) with style DNA prompt |
+| Hybrid            | HTML layout + AI-generated illustrations slotted in               |
+
+Save HTML to `_temp/design-demos/demo-<style>.html`. Screenshot to `_temp/design-demos/demo-<style>.png`. Show all 3 screenshots together.
+
+```bash
+# Reference command
+npx playwright screenshot file:///<absolute-path>.html out.png --viewport-size=1200,900
+```
+
+### Phase 6 — User Chooses
+
+Options to present:
+
+- **Pick one** to deepen
+- **Mix** ("A's palette + C's layout")
+- **Tweak** specific aspects of one
+- **Restart** → return to Phase 3 with refined understanding
+
+### Phase 7 — Generate Production Prompt (if AI image-driven)
+
+Structure: `[design philosophy constraint] + [content description] + [technical params]`
+
+- ✅ Use **specific features**, not style names: "Kenya Hara whitespace + terracotta orange #C04A1A," not "minimalist"
+- ✅ Include HEX colors, ratios, space allocation, output spec
+- ❌ Avoid AI slop list (see `anti-ai-slop` skill)
+
+### Phase 8 — Hand Off to Main Build
+
+Direction confirmed → return to the main implementation flow (`hi-fi-prototype-html`, `frontend-design`, etc.). You now have **explicit design context** — no longer guessing.
+
+## Lightweight Variant (Time-Pressured)
+
+When the user is in a rush:
+
+- Skip Phase 4 references
+- Skip Phase 5 demos
+- Just present 3 named directions in 2 sentences each
+- Let user pick by name
+
+This trades signal-fidelity for speed but still beats "generic AI default."
+
+## Why This Beats "Just Make a Reasonable Default"
+
+1. **Generic default = AI slop** (see `anti-ai-slop`). It dilutes brand identity to the average of all training data.
+2. **Named designer references** give the user concrete vocabulary to push back ("more like Pentagram, less like Sagmeister").
+3. **3 differentiated demos** convert vague preferences into testable choices in one round, instead of N rounds of "looks ok but not quite right."
+4. **The advisor restatement (Phase 2)** catches misunderstandings before any pixel is committed — the cheapest possible correction point.
+
+## Pairs Well With
+
+- `brand-asset-protocol` — runs **after** direction is locked, when brand assets must be sourced
+- `anti-ai-slop` — keeps each demo from collapsing into the AI default
+- `hi-fi-prototype-html` — production target after direction is chosen
+- `brainstorming` — for non-visual, non-design ambiguity

package/dist/template/.opencode/skill/design-system-audit/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: design-system-audit
+description: Use when auditing an existing design system for consistency — token audits, pattern analysis, visual comparison against design specs. Load AFTER implementation to review, not during initial build.
+version: 2.0.0
+tags: [design, audit, ui]
+dependencies: []
+---
+
+# Design System Audit
+
+> **Replaces** separate, overlapping design review skills — unified design analysis covering UI patterns, design tokens, and visual properties
+
+Use this skill for end-to-end design analysis across code, screenshots, and design specs.
+
+## When to Use
+
+- Auditing UI consistency across a component library or app
+- Documenting existing patterns before refactor or migration
+- Extracting/validating design tokens from implementation and visuals
+- Comparing rendered output against mockups/Figma/screenshots
+
+## When NOT to Use
+
+- Pure backend work with no user-facing UI
+- One-off micro tweak where system-level consistency is irrelevant
+
+## Modes
+
+### UI Pattern Analysis
+Analyze component patterns, identify inconsistencies, document undocumented patterns.
+
+Focus areas:
+
+- Component variants and usage drift
+- Repeated interaction patterns (forms, tables, dialogs, navigation)
+- Pattern ownership (where canonical implementation should live)
+- Inconsistent states (hover/focus/disabled/error/loading)
+
+Deliverables:
+
+- Pattern inventory with file references
+- Consolidation candidates
+- Priority fixes by user impact
+
+### Design Token Audit
+Extract and verify color, typography, spacing tokens against implementation.
+
+Focus areas:
+
+- Color token usage vs one-off literals
+- Typography scale consistency (size/weight/line-height)
+- Spacing/radius/shadow value normalization
+- Semantic token gaps (text-muted, border-subtle, success, warning, etc.)
+
+Deliverables:
+
+- Token map (source of truth + current usage)
+- Drift report (where implementation diverges)
+- Proposed canonical token set and migration order
+
+### Visual Comparison
+Compare rendered output against mockups/specs with specific measurements.
+
+Focus areas:
+
+- Pixel-level spacing/sizing mismatches
+- Color differences (hex-level)
+- Typography mismatches (font, size, weight, line height)
+- Layout/responsive behavior across breakpoints
+
+Deliverables:
+
+- Spec-vs-implementation discrepancy list
+- Severity-ranked visual defects
+- Concrete fix list with measurable targets
+
+## Recommended Workflow
+
+1. **Scope**
+   - Identify target surfaces (pages/components/states/breakpoints)
+   - Gather artifacts (code paths, screenshots, mockups)
+
+2. **Inventory**
+   - Capture pattern and token inventory from code + visuals
+   - Note duplicates, drift, and undocumented conventions
+
+3. **Cross-Reference**
+   - Validate findings against design system tokens/components
+   - Distinguish intentional exceptions from accidental drift
+
+4. **Measure**
+   - Record measurable values for each issue:
+     - hex color
+     - px/rem size
+     - spacing/gap/padding values
+     - breakpoint-specific behavior
+
+5. **Report**
+   - Produce actionable findings with file:line and target value
+   - Group by severity and migration effort
+
+## Audit Output Template
+
+```markdown
+## Design Audit: [Scope]
+
+### Findings
+1. [Severity] [Issue]
+   - File: `path/to/file.tsx:123`
+   - Current: `#6B7280`, `14px`, `gap: 10px`
+   - Expected: `var(--color-text-muted)`, `13px`, `gap: 8px`
+   - Impact: [consistency/accessibility/brand mismatch]
+
+### Token Drift Summary
+- Colors: X one-offs, Y missing semantic mappings
+- Typography: X non-scale values
+- Spacing: X non-token values
+
+### Priority Actions
+- P0: [high impact, low effort]
+- P1: [high impact, medium effort]
+- P2: [design debt cleanup]
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Hurts | Better Approach |
+| --- | --- | --- |
+| Vague feedback ("looks good") instead of specific measurements | Not actionable, impossible to verify | Report concrete values (hex, px/rem, exact delta) |
+| Not checking existing design tokens before proposing new values | Creates token sprawl and inconsistency | Map to existing tokens first; add new tokens only when justified |
+| Auditing in isolation without cross-referencing the design system | Flags intentional patterns as bugs | Validate each finding against canonical component/token sources |
+| Reporting visual issues without checking responsive breakpoints | Misses major UX regressions on mobile/tablet | Verify each issue across defined breakpoints and states |
+
+## Verification
+
+After audit: every finding should reference a specific file:line and measurable value (hex color, px size, etc.)
+
+Minimum quality gate:
+
+- Each finding has location + current value + expected value
+- Each recommendation maps to token/system guidance
+- Responsive states checked for impacted components
+
+## Storage
+
+- Save audits to `.opencode/memory/design/audits/`
+- Save extracted token snapshots to `.opencode/memory/design/tokens/`
+
+## See Also
+
+- `mockup-to-code`
+- `frontend-design`
+- `accessibility-audit`