opencode-skills-collection 2.0.0-beta.1 → 2.0.0-beta.3

package/bundled-skills/ui-review/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: ui-review
+description: "Review UI code for StyleSeed design-system compliance, accessibility, mobile ergonomics, spacing discipline, and implementation quality."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ui, review, design-system, accessibility, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UI Review
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill audits UI code against the Toss seed's conventions instead of reviewing it as generic frontend work. It focuses on design-token discipline, component ergonomics, accessibility, mobile readiness, typography, and spacing consistency.
+
+## When to Use
+
+- Use when a component or page should follow the StyleSeed Toss design language
+- Use when reviewing a UI-heavy PR for consistency and design-system violations
+- Use when the output looks "mostly fine" but feels off in subtle ways
+- Use when you need a structured review with concrete fixes
+
+## Review Checklist
+
+### Design Tokens
+
+- no hardcoded hex colors when semantic tokens exist
+- no improvised shadow values when tokenized shadows exist
+- no arbitrary radius choices outside the system scale
+- no random spacing values that break the seed rhythm
+
+### Component Conventions
+
+- uses the project's class merge helper
+- supports `className` extension when appropriate
+- uses the agreed typing pattern
+- avoids wrapper components that only forward one class string
+- reuses existing primitives before inventing new ones
+
+### Accessibility
+
+- touch targets large enough for mobile
+- visible keyboard focus states
+- labels and `aria-*` attributes where needed
+- adequate color contrast
+- reduced-motion respect for animation
+
+### Mobile UX
+
+- no horizontal overflow
+- safe-area handling where relevant
+- readable text sizes
+- thumb-friendly interaction spacing
+- bottom nav or sticky actions do not obscure content
+
+### Typography and Spacing
+
+- uses the system type hierarchy
+- display and headings are not overly loose
+- body text remains readable
+- spacing follows the seed grid instead of arbitrary values
+
+## Output Format
+
+Return:
+1. A verdict: Pass, Needs Improvement, or Fail
+2. A prioritized list of issues with file and line references when available
+3. Concrete fixes for each issue
+4. Any open questions where the design intent is ambiguous
+
+## Best Practices
+
+- Review against the seed, not against personal taste
+- Separate stylistic drift from real usability or accessibility bugs
+- Prefer actionable diffs over abstract criticism
+- Call out duplication when an existing component already solves the problem
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-review/SKILL.md)

package/bundled-skills/ui-setup/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ui-setup
+description: "Interactive StyleSeed setup wizard for choosing app type, brand color, visual style, typography, and the first screen scaffold."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ui, design-system, setup, frontend, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UI Setup
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this setup wizard turns a raw project into a design-system-guided workspace. It collects the minimum brand and product context needed to configure tokens, pick a visual direction, and generate an initial page without drifting into generic UI.
+
+## When to Use
+
+- Use when you are starting a new app with the StyleSeed Toss seed
+- Use when you copied the seed into an existing project and need to personalize it
+- Use when you want the AI to ask one design decision at a time instead of guessing
+- Use when you need a first page scaffold after selecting colors, font, and app type
+
+## How It Works
+
+### Step 1: Ask One Question at a Time
+
+Do not front-load the full questionnaire. Ask a single question, wait for the answer, store it, then continue.
+
+### Step 2: Capture the App Type
+
+Identify the product shape before touching tokens or layout recipes.
+
+Suggested buckets:
+- SaaS dashboard
+- E-commerce
+- Fintech
+- Social or content
+- Productivity or internal tool
+- Other with a short freeform description
+
+Use the answer to choose the page composition pattern and the type of first screen to scaffold.
+
+### Step 3: Choose the Brand Color
+
+Offer a few safe defaults plus a custom hex option. Once selected:
+- update the light theme brand token
+- update the dark theme brand token with a lighter accessible variant
+- keep all other colors semantic rather than hardcoding the brand everywhere
+
+If the project uses the StyleSeed Toss seed, the main target is `css/theme.css`.
+
+### Step 4: Offer an Optional Visual Reference
+
+Ask whether the user wants to borrow the feel of an established brand or design language. Good examples include Stripe, Linear, Vercel, Notion, Spotify, Supabase, and Airbnb.
+
+Use the reference to influence density, tone, and composition, not to clone assets or trademarks.
+
+### Step 5: Pick Typography
+
+Confirm the font direction:
+- keep the default stack
+- swap to a preferred font if already installed or available
+- preserve hierarchy rules for display, heading, body, and caption text
+
+If the seed is present, update the font-related files rather than scattering overrides across components.
+
+### Step 6: Generate the First Screen
+
+Ask for:
+- app name
+- first page or screen name
+- a one-sentence purpose for that page
+
+Then scaffold the page using the seed's page shell, top bar, navigation, spacing scale, and card structure.
+
+## Output
+
+Return:
+1. The captured setup decisions
+2. The files or tokens updated
+3. The first page or scaffold created
+4. Any follow-up recommendations for components, patterns, accessibility, or copy
+
+## Best Practices
+
+- Keep the interaction conversational, but deterministic
+- Make brand color changes through tokens, not component-by-component edits
+- Use an inspiration brand as a reference, not as a permission slip to copy
+- Prefer semantic tokens and reusable patterns over page-specific CSS
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [StyleSeed Toss seed](https://github.com/bitjaru/styleseed/tree/main/seeds/toss)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-setup/SKILL.md)

package/bundled-skills/ui-tokens/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ui-tokens
+description: "List, add, and update StyleSeed design tokens while keeping JSON sources, CSS variables, and dark-mode values in sync."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ui, tokens, design-system, theming, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UI Tokens
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill manages design tokens without letting the source-of-truth files drift apart. It is meant for teams using the Toss seed's JSON token files and CSS implementation together.
+
+## When to Use
+
+- Use when you need to inspect the current token set
+- Use when you want to add a new color, shadow, radius, spacing, or typography token
+- Use when you need to update a token and propagate the change safely
+- Use when the project has both JSON token files and CSS variables that must stay aligned
+
+## How It Works
+
+### Supported Actions
+
+- `list`: show the current tokens in a human-readable form
+- `add`: introduce a new token and wire it through the implementation
+- `update`: change an existing token value and audit the downstream usage
+
+### Typical Source-of-Truth Split
+
+For the Toss seed:
+- JSON under `tokens/`
+- CSS variables and theme wiring under `css/theme.css`
+- typography support in the font and base CSS files
+
+### Rules
+
+- keep JSON and CSS in sync
+- prefer semantic names over descriptive names
+- provide dark-mode support where relevant
+- update the token implementation, not just the source manifest
+- check for direct component usage that might now be stale
+
+## Output
+
+Return:
+1. The requested token inventory or change summary
+2. Every file touched
+3. Any affected components or utilities that should be reviewed
+4. Follow-up actions if the new token requires broader adoption
+
+## Best Practices
+
+- Add semantic intent, not one-off brand shades
+- Avoid token sprawl by extending existing scales first
+- Keep naming consistent with the rest of the system
+- Review contrast and accessibility when introducing new colors
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-tokens/SKILL.md)

package/bundled-skills/ux-audit/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: ux-audit
+description: "Audit screens against Nielsen's heuristics and mobile UX best practices using the StyleSeed Toss design language as the implementation context."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ux, audit, usability, mobile, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UX Audit
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill audits usability rather than just visuals. It uses Nielsen's 10 heuristics plus modern mobile UX expectations to find issues in navigation, feedback, recovery, hierarchy, and cognitive load.
+
+## When to Use
+
+- Use when a screen feels awkward even though the code and styling seem correct
+- Use when evaluating a flow before or after implementation
+- Use when reviewing a mobile-first product for usability regressions
+- Use when you want findings framed as user experience problems with remediation
+
+## Audit Framework
+
+Review the target against:
+- visibility of system status
+- match between system and real-world language
+- user control and freedom
+- consistency and standards
+- error prevention
+- recognition rather than recall
+- flexibility and efficiency
+- aesthetic and minimalist design
+- recovery from errors
+- help, onboarding, and empty-state guidance
+
+Add mobile-specific checks for reachability, touch ergonomics, input burden, and thumb-friendly action placement.
+
+## Output
+
+Return:
+1. A prioritized issue list
+2. The heuristic violated by each issue
+3. Why the issue matters to real users
+4. Specific remediation suggestions for the page, component, or flow
+
+## Best Practices
+
+- Judge the experience from the user's point of view, not the implementer's
+- Separate high-severity flow blockers from minor polish issues
+- Include recovery and state-management guidance, not only layout comments
+- Tie recommendations back to concrete UI changes
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ux-audit/SKILL.md)

package/bundled-skills/ux-copy/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: ux-copy
+description: "Generate UX microcopy in StyleSeed's Toss-inspired voice for buttons, empty states, errors, toasts, confirmations, and form guidance."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ux, copywriting, microcopy, frontend, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UX Copy
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill generates concise product copy for common UI states. It follows the Toss-inspired tone: casual but polite, direct, active, and specific enough to help the user recover or proceed.
+
+## When to Use
+
+- Use when you need button labels, helper text, toasts, empty states, or error messages
+- Use when a feature has functional UI but weak or robotic wording
+- Use when you want consistent product voice across a flow
+- Use when confirmation dialogs or state feedback need better phrasing
+
+## Tone Rules
+
+- casual but polite
+- active voice over passive voice
+- positive framing where it stays honest
+- plain language instead of internal jargon
+- concise wording where every word earns its place
+
+## Common Patterns
+
+### Buttons
+
+Use a short action verb plus object when needed.
+
+### Empty States
+
+Start with a friendly observation, then suggest the next action.
+
+### Errors
+
+Explain what happened in user-facing language and what to do next. Do not surface raw internal error strings.
+
+### Toasts
+
+Confirm the result quickly. Add an undo action for reversible destructive behavior.
+
+### Forms
+
+Use clear labels, useful placeholders, specific helper text, and corrective error messages.
+
+### Confirmation Dialogs
+
+State the action in plain language and explain the consequence if the decision is risky or irreversible.
+
+## Output
+
+Return:
+1. The requested microcopy grouped by UI surface
+2. Notes on tone or localization considerations if relevant
+3. Any places where the UX likely needs a structural fix in addition to better copy
+
+## Best Practices
+
+- Make the next action obvious
+- Avoid generic labels like "Submit" or "OK" when the action can be named precisely
+- Blame the system, not the user, when something fails
+- Keep error and empty states useful even without visual context
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ux-copy/SKILL.md)

package/bundled-skills/ux-feedback/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: ux-feedback
+description: "Add loading, empty, error, and success feedback states to StyleSeed components and pages with practical mobile-first rules."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ux, states, loading, error-handling, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UX Feedback
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill ensures data-dependent UI does not stop at the happy path. It adds the four core feedback states every serious product needs: loading, empty, error, and success.
+
+## When to Use
+
+- Use when a component or page fetches, mutates, or depends on async data
+- Use when a flow currently renders only the success path
+- Use when a card, list, or page needs better state communication
+- Use when the product needs clear recovery and confirmation behavior
+
+## The Four Required States
+
+### Loading
+
+Use skeletons that match the final layout. Avoid spinners inside cards unless the pattern genuinely requires them. Delay skeletons slightly to avoid flashes on fast responses.
+
+### Empty
+
+Provide a friendly explanation and a next action. Zero values should still render meaningfully instead of disappearing.
+
+### Error
+
+Use plain-language failure messages and always offer recovery where possible. Localize failures to the affected card or section if the rest of the page can still work.
+
+### Success
+
+Use toasts or equivalent lightweight confirmation for completed actions. Add undo for reversible destructive changes.
+
+## Output
+
+Return:
+1. The data-dependent areas identified
+2. The loading, empty, error, and success states added for each one
+3. Any reusable empty-state or toast patterns created
+4. Follow-up work needed for analytics, retries, or accessibility
+
+## Best Practices
+
+- Match loading placeholders to the real layout
+- Keep partial failure isolated whenever possible
+- Make recovery obvious, not hidden in logs or developer tools
+- Use success feedback sparingly but clearly
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ux-feedback/SKILL.md)

package/bundled-skills/ux-flow/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ux-flow
+description: "Design user flows and screen structure using StyleSeed UX patterns such as progressive disclosure, hub-and-spoke navigation, and information pyramids."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ux, flows, navigation, product-design, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UX Flow
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill designs flows before screens. It uses proven UX patterns to define entry points, exits, screen inventory, and navigation structure so the implementation has a coherent user journey instead of a pile of disconnected pages.
+
+## When to Use
+
+- Use when planning onboarding, checkout, account management, dashboards, or drill-down flows
+- Use when a new feature spans multiple screens or modal states
+- Use when users need a clear path through a task instead of a single isolated page
+- Use when the UI needs navigation logic before components are built
+
+## How It Works
+
+### Information Architecture Principles
+
+- progressive disclosure: reveal complexity only when needed
+- Miller's Law: chunk content into manageable groups
+- Hick's Law: minimize decision overload on each screen
+
+### Common Navigation Models
+
+- hub and spoke for dashboards and detail views
+- linear flow for onboarding, forms, and checkout
+- tab navigation for 3 to 5 top-level areas
+
+### Flow Rules
+
+- every flow has a clear entry point
+- every flow has a clear exit or success condition
+- key features should usually be reachable within three taps from home
+- non-root screens need back navigation
+- loading, empty, and error states need explicit recovery paths
+
+## Output
+
+Provide:
+1. An ASCII flow diagram
+2. A screen inventory with each screen's purpose
+3. Edge cases for loading, empty, and error states
+4. Recommended page scaffolds and reusable patterns to implement next
+
+## Best Practices
+
+- Optimize for clarity before density
+- Let one screen answer one primary question
+- Keep escape hatches visible for risky or destructive steps
+- Define state transitions before drawing detailed layouts
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ux-flow/SKILL.md)

package/dist/index.js

@@ -28,8 +28,8 @@ const OpenCodeSkillsCollection = async (_ctx) => {
         ensureDir(activeSkillsDir);
         runSkillPointer({ bundledSkillsPath, activeSkillsDir });
     }
-    catch {
-        // Plugin errors must never crash OpenCode.
+    catch (error) {
+        process.stderr.write(`[opencode-skills-collection] ${error}\n`);
     }
     return {};
 };

package/dist/skill-pointer/pointer-generator.js

@@ -56,11 +56,17 @@ export function generatePointers(activeSkillsDir, vaultDir, index = []) {
     }
     for (const categoryName of categoryDirs) {
         const categoryVaultPath = path.join(vaultDir, categoryName);
-        const skills = byCategory.get(categoryName) ?? [];
+        let skills = byCategory.get(categoryName) ?? [];
         if (skills.length === 0) {
             const subDirs = fs.readdirSync(categoryVaultPath).filter((e) => fs.statSync(path.join(categoryVaultPath, e)).isDirectory());
             if (subDirs.length === 0)
                 continue;
+            skills = subDirs.map((dir) => ({
+                id: dir,
+                category: categoryName,
+                name: dir.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+                description: dir.replace(/-/g, " "),
+            }));
         }
         const pointerDir = path.join(activeSkillsDir, `${categoryName}${POINTER_SUFFIX}`);
         ensureDir(pointerDir);

package/dist/utils/fs.utils.d.ts

@@ -1,8 +1,2 @@
-/**
- * Ensures a directory exists, creating it recursively if needed.
- */
 export declare function ensureDir(dirPath: string): void;
-/**
- * Returns the names of all direct child directories inside a given path.
- */
 export declare function listSubdirectories(dirPath: string): string[];

package/dist/utils/fs.utils.js

@@ -1,21 +1,12 @@
 import fs from "fs";
-import path from "path";
-/**
- * Ensures a directory exists, creating it recursively if needed.
- */
 export function ensureDir(dirPath) {
     fs.mkdirSync(dirPath, { recursive: true });
 }
-/**
- * Returns the names of all direct child directories inside a given path.
- */
 export function listSubdirectories(dirPath) {
     if (!fs.existsSync(dirPath))
         return [];
     return fs
-        .readdirSync(dirPath)
-        .filter((entry) => {
-        const fullPath = path.join(dirPath, entry);
-        return fs.statSync(fullPath).isDirectory();
-    });
+        .readdirSync(dirPath, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "opencode-skills-collection",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.3",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "bundled-skills"
+    "bundled-skills",
+    "skills_index.json"
   ],
   "repository": {
     "type": "git",