diff --git a/README.md b/README.md index dde1e075..577cbd82 100644 --- a/README.md +++ b/README.md @@ -285,6 +285,7 @@ This collection would not be possible without the incredible work of the Claude ### Community Contributors - **[pumanitro/global-chat](https://github.com/pumanitro/global-chat)**: Source for the Global Chat Agent Discovery skill - cross-protocol discovery of MCP servers and AI agents across multiple registries. +- **[bitjaru/styleseed](https://github.com/bitjaru/styleseed)**: StyleSeed Toss UI and UX skill collection - setup wizard, page and pattern generation, design-token management, accessibility review, UX audits, feedback states, and microcopy guidance for professional mobile-first UI. - **[milkomida77/guardian-agent-prompts](https://github.com/milkomida77/guardian-agent-prompts)**: Source for the Multi-Agent Task Orchestrator skill - production-tested delegation patterns, anti-duplication, and quality gates for coordinated agent work. - **[Elkidogz/technical-change-skill](https://github.com/Elkidogz/technical-change-skill)**: Source for the Technical Change Tracker skill - structured JSON change records, session handoff, and accessible HTML dashboards for coding continuity. - **[rmyndharis/antigravity-skills](https://github.com/rmyndharis/antigravity-skills)**: For the massive contribution of 300+ Enterprise skills and the catalog generation logic. diff --git a/skills/ui-a11y/SKILL.md b/skills/ui-a11y/SKILL.md new file mode 100644 index 00000000..4a2482df --- /dev/null +++ b/skills/ui-a11y/SKILL.md @@ -0,0 +1,77 @@ +--- +name: ui-a11y +description: "Audit a StyleSeed-based component or page for WCAG 2.2 AA issues and apply practical accessibility fixes where the code makes them safe." +category: design +risk: safe +source: community +source_repo: bitjaru/styleseed +source_type: community +date_added: "2026-04-08" +author: bitjaru +tags: [ui, accessibility, wcag, audit, styleseed] +tools: [claude, cursor, codex, gemini] +--- + +# UI Accessibility Audit + +## Overview + +Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill audits components and pages for accessibility issues with an emphasis on the Toss seed's mobile UI patterns. It combines WCAG 2.2 AA checks with practical code fixes for touch targets, focus states, contrast, labels, and reduced motion. + +## When to Use + +- Use when reviewing a page or component for accessibility regressions +- Use when a StyleSeed UI looks polished but has uncertain keyboard or contrast behavior +- Use when adding new interactive controls to a mobile-first screen +- Use when you want a prioritized list of issues and fixable items + +## Audit Areas + +### Perceivable + +- text contrast +- non-text contrast for controls and graphics +- alt text for images +- labels for meaningful icons +- no information conveyed by color alone + +### Operable + +- touch targets at least 44x44px +- keyboard reachability for all interactive controls +- logical tab order +- visible focus indicators +- reduced-motion support for nonessential animation + +### Understandable + +- visible labels or `aria-label` on inputs +- error text associated with the correct field +- clear wording for errors and validation +- document language set appropriately + +### Robust + +- semantic HTML where possible +- correct use of ARIA when semantics alone are insufficient +- no faux buttons or links without the right roles and behavior + +## Output + +Return: +1. Issues found, grouped by severity +2. Safe autofixes that can be applied directly +3. Items that need manual review or product judgment +4. A short summary of the accessibility risk level + +## Best Practices + +- Fix semantics before layering on ARIA +- Use the design system tokens only if they still meet contrast requirements +- Treat touch target failures as real usability defects, not polish issues +- Prefer partial, verified fixes over speculative accessibility changes + +## Additional Resources + +- [StyleSeed repository](https://github.com/bitjaru/styleseed) +- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-a11y/SKILL.md) diff --git a/skills/ui-component/SKILL.md b/skills/ui-component/SKILL.md new file mode 100644 index 00000000..91b99db8 --- /dev/null +++ b/skills/ui-component/SKILL.md @@ -0,0 +1,100 @@ +--- +name: ui-component +description: "Generate a new UI component that follows StyleSeed Toss conventions for structure, tokens, accessibility, and component ergonomics." +category: design +risk: safe +source: community +source_repo: bitjaru/styleseed +source_type: community +date_added: "2026-04-08" +author: bitjaru +tags: [ui, components, design-system, frontend, styleseed] +tools: [claude, cursor, codex, gemini] +--- + +# UI Component + +## Overview + +Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill generates components that respect the Toss seed's design language instead of improvising ad hoc markup and styling. It emphasizes semantic tokens, predictable typing, reusable variants, and mobile-friendly accessibility defaults. + +## When to Use + +- Use when you need a new UI primitive or composed component inside a StyleSeed-based project +- Use when you want a component to match the existing Toss seed conventions +- Use when a component should be reusable, typed, and design-token driven +- Use when the AI might otherwise invent spacing, colors, or interaction patterns + +## How It Works + +### Step 1: Read the Local Design Context + +Before generating code, inspect the seed's source of truth: +- `CLAUDE.md` for conventions +- `css/theme.css` for semantic tokens +- at least one representative component from `components/ui/` + +If the user already has a better local example, follow the local codebase over a generic template. + +### Step 2: Choose the Correct Home + +Place the output where it belongs: +- `src/components/ui/` for primitives and low-level building blocks +- `src/components/patterns/` for composed sections or multi-part patterns + +Do not create a new primitive if an existing one can be extended safely. + +### Step 3: Follow the Structural Rules + +Use these defaults unless the host project strongly disagrees: +- function declaration instead of a `const` component +- `React.ComponentProps<>` or equivalent native prop typing +- `className` passthrough support +- `cn()` or the project's standard class merger +- `data-slot` for component identification +- CVA or equivalent only when variants are genuinely needed + +### Step 4: Use Semantic Tokens Only + +Do not hardcode visual values if the design system has a token for them. + +Preferred examples: +- `bg-card` +- `text-foreground` +- `text-muted-foreground` +- `border-border` +- `shadow-[var(--shadow-card)]` + +### Step 5: Preserve StyleSeed Typography and Spacing + +- Use the scale already defined by the seed +- Prefer multiples of 6px +- Use logical spacing utilities where supported +- Keep display and heading text tight, body text readable, captions restrained + +### Step 6: Bake in Accessibility + +- Touch targets should be at least 44x44px for interactive elements +- Keyboard focus must be visible +- Pass through `aria-*` attributes where appropriate +- Respect reduced-motion preferences for nonessential motion + +## Output + +Provide: +1. The generated component +2. The target path +3. Any required imports or dependencies +4. Notes on variants, tokens, or follow-up integration work + +## Best Practices + +- Compose from existing primitives before inventing new ones +- Keep the component API small and predictable +- Prefer semantic layout classes over arbitrary values +- Export named components unless the host project uses another standard consistently + +## Additional Resources + +- [StyleSeed repository](https://github.com/bitjaru/styleseed) +- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-component/SKILL.md) diff --git a/skills/ui-page/SKILL.md b/skills/ui-page/SKILL.md new file mode 100644 index 00000000..e8da4e8c --- /dev/null +++ b/skills/ui-page/SKILL.md @@ -0,0 +1,96 @@ +--- +name: ui-page +description: "Scaffold a new mobile-first page using StyleSeed Toss layout patterns, section rhythm, and existing shell components." +category: design +risk: safe +source: community +source_repo: bitjaru/styleseed +source_type: community +date_added: "2026-04-08" +author: bitjaru +tags: [ui, page-design, mobile, layout, styleseed] +tools: [claude, cursor, codex, gemini] +--- + +# UI Page + +## Overview + +Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill scaffolds a complete page or screen using the Toss seed's mobile-first composition rules. It keeps page structure consistent by building on the existing shell, top bar, bottom navigation, and card rhythm instead of producing disconnected sections. + +## When to Use + +- Use when you need a new page in a Toss-seed app +- Use when you want a consistent page shell, spacing, and navigation structure +- Use when you are adding a new product flow and need a solid starting layout +- Use when you want to stay mobile-first even if the project later expands to larger breakpoints + +## How It Works + +### Step 1: Inspect the Existing Shell + +Read the current page scaffolding patterns first, especially: +- page shell +- top bar +- bottom navigation +- representative pages using the same route family + +### Step 2: Define the Page Purpose + +Clarify: +- the page name +- the primary user question the screen answers +- the top one or two actions the user should take + +Every screen should have one dominant purpose. + +### Step 3: Use the Information Pyramid + +Lay out the page from highest importance to lowest: +1. Hero or top summary +2. KPI or key actions +3. detail cards or supporting modules +4. lists, history, or secondary content + +Avoid repeating the same section type mechanically from top to bottom. + +### Step 4: Apply the Toss Layout Rules + +Default layout choices: +- mobile viewport width around `max-w-[430px]` +- page background on `bg-background` +- horizontal padding around `px-6` +- section rhythm with `space-y-6` +- generous bottom padding if a bottom nav is present +- cards using semantic surface tokens, rounded corners, and light shadows + +### Step 5: Compose Instead of Rebuilding + +Use existing `ui/` and `patterns/` components wherever possible. New pages should primarily orchestrate existing building blocks, not recreate them. + +### Step 6: Account for Real Device Constraints + +- handle safe-area insets +- avoid horizontal overflow +- keep interactive clusters thumb-friendly +- ensure long content scrolls cleanly without clipping the bottom navigation + +## Output + +Return: +1. The page scaffold +2. The chosen section structure +3. Reused components and any newly required components +4. Empty, loading, and error states that the page will need next + +## Best Practices + +- Keep the first version structurally correct before adding decoration +- Use one strong hero instead of multiple competing highlights +- Preserve navigation consistency across sibling screens +- Prefer reusable section components when the page will likely repeat + +## Additional Resources + +- [StyleSeed repository](https://github.com/bitjaru/styleseed) +- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-page/SKILL.md) diff --git a/skills/ui-pattern/SKILL.md b/skills/ui-pattern/SKILL.md new file mode 100644 index 00000000..1fa05ba9 --- /dev/null +++ b/skills/ui-pattern/SKILL.md @@ -0,0 +1,88 @@ +--- +name: ui-pattern +description: "Generate reusable UI patterns such as card sections, grids, lists, forms, and chart wrappers using StyleSeed Toss primitives." +category: design +risk: safe +source: community +source_repo: bitjaru/styleseed +source_type: community +date_added: "2026-04-08" +author: bitjaru +tags: [ui, patterns, design-system, reuse, styleseed] +tools: [claude, cursor, codex, gemini] +--- + +# UI Pattern + +## Overview + +Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill builds reusable composed patterns from the seed's primitives. It is intended for sections like card lists, grids, form blocks, ranking lists, and chart wrappers that appear across multiple pages and need to look deliberate rather than ad hoc. + +## When to Use + +- Use when you need a reusable layout pattern rather than a one-off page section +- Use when a page repeats the same arrangement of cards, rows, filters, or data blocks +- Use when you want to build from existing StyleSeed primitives instead of copying markup +- Use when you want a pattern component with props for dynamic content + +## How It Works + +### Step 1: Identify the Pattern Type + +Common pattern families include: +- card section +- two-column grid +- horizontal scroller +- list section +- form section +- stat grid +- data table +- detail card +- chart card +- filter bar +- action sheet + +### Step 2: Read the Available Building Blocks + +Inspect both: +- `components/ui/` for primitives +- `components/patterns/` for neighboring patterns that can be extended + +The goal is composition, not duplication. + +### Step 3: Apply StyleSeed Layout Rules + +Keep the Toss seed defaults intact: +- card surfaces on semantic tokens +- rounded corners from the system scale +- shadow tokens instead of improvised shadow values +- consistent internal padding +- section wrappers that align with the page margin system + +### Step 4: Make the Pattern Dynamic + +Expose data through props instead of hardcoding content. If a pattern has multiple variants, keep the API explicit and small. + +### Step 5: Keep the Pattern Reusable Across Pages + +Avoid page-specific assumptions unless the user explicitly wants a one-off section. If the markup only works on one route, it probably belongs in a page component, not a shared pattern. + +## Output + +Provide: +1. The generated pattern component +2. The target location +3. Expected props and usage example +4. Notes on which existing primitives were reused + +## Best Practices + +- Start from the smallest existing building block that solves the problem +- Keep container, section, and item responsibilities separate +- Use tokens and spacing rules consistently +- Prefer extending a pattern over adding a near-duplicate sibling + +## Additional Resources + +- [StyleSeed repository](https://github.com/bitjaru/styleseed) +- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ui-pattern/SKILL.md) diff --git a/skills/ui-review/SKILL.md b/skills/ui-review/SKILL.md new file mode 100644 index 00000000..41ea7785 --- /dev/null +++ b/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) diff --git a/skills/ui-setup/SKILL.md b/skills/ui-setup/SKILL.md new file mode 100644 index 00000000..e839713c --- /dev/null +++ b/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) diff --git a/skills/ui-tokens/SKILL.md b/skills/ui-tokens/SKILL.md new file mode 100644 index 00000000..c7fe9c99 --- /dev/null +++ b/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) diff --git a/skills/ux-audit/SKILL.md b/skills/ux-audit/SKILL.md new file mode 100644 index 00000000..1a4f638a --- /dev/null +++ b/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) diff --git a/skills/ux-copy/SKILL.md b/skills/ux-copy/SKILL.md new file mode 100644 index 00000000..5df52af8 --- /dev/null +++ b/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) diff --git a/skills/ux-feedback/SKILL.md b/skills/ux-feedback/SKILL.md new file mode 100644 index 00000000..26e247a2 --- /dev/null +++ b/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) diff --git a/skills/ux-flow/SKILL.md b/skills/ux-flow/SKILL.md new file mode 100644 index 00000000..a2455a5e --- /dev/null +++ b/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)