ss-a11y

针对StyleSeed代码进行静态无障碍审计，确保符合WCAG 2.2 AA标准。检查对比度、键盘导航、语义标签及触控目标等合规性，并提供自动修复建议与手动审查标记。

用户要求对组件或页面进行无障碍审计需要检查代码是否符合WCAG 2.2 AA标准

engine/.claude/skills/ss-a11y/SKILL.md

npx skills add bitjaru/styleseed --skill ss-a11y -g -y

SKILL.md

Frontmatter

{
    "name": "ss-a11y",
    "description": "Audit a component or page for accessibility issues and fix them",
    "allowed-tools": "Read, Write, Edit, Grep, Glob",
    "argument-hint": "[file-path]"
}

Accessibility Audit

When NOT to use

For general design system compliance review → use /ss-review
For Nielsen UX heuristics → use /ss-audit
For non-StyleSeed code (no data-slot, no semantic tokens) — assumes StyleSeed conventions
For runtime testing — this is a static code audit, not a screen-reader simulation

Target: $ARGUMENTS

Audit Criteria

WCAG 2.2 AA Compliance

1. Perceivable

Color contrast: Text must meet 4.5:1 (normal) or 3:1 (large/bold text)
- Check text-muted-foreground (#717182) on bg-background (#FFFFFF) = 4.6:1 (passes)
- Check text-brand on white (verify contrast with your skin's brand color)
- Flag any custom colors that don't meet ratio
Non-text contrast: UI controls/graphics must meet 3:1
Text alternatives: All <img> need alt, icons need aria-label when meaningful
Color independence: Don't convey info by color alone (add icons/text)

2. Operable

Touch targets: Minimum 44x44px (min-h-11 min-w-11)
- Common violation: h-9 (36px) buttons — should be h-11
- Icon buttons need explicit size: w-11 h-11
Keyboard navigation: All interactive elements must be keyboard-accessible
- Tab order should be logical
- focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2

Motion: Animations must respect prefers-reduced-motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

3. Understandable

Labels: Form inputs must have visible labels or aria-label
Error messages: Form errors must be programmatically associated (aria-describedby)
Language: <html lang="en"> (or appropriate language code for your project)

4. Robust

Semantic HTML: Use appropriate elements (<button>, <nav>, <main>, <header>)
ARIA: Use Radix UI components (they handle ARIA automatically)
Roles: Custom interactive elements need proper role attributes

Design System Token Reference

Token	Minimum Contrast	Note
`--foreground`	7:1+	Body text — verify with your skin
`--muted-foreground`	4.5:1+	Secondary text — verify with your skin
`--brand`	4.5:1+	Accent — verify with your skin's brand color
`--destructive`	4.5:1+	Error — verify with your skin
`--success`	3:1+	Large text/icons only — verify with your skin
`--warning`	4.5:1+	Warning text — some skins need a darker variant

Output

Issues found: List with severity (Critical/Major/Minor)
Auto-fixes: Apply fixes directly where possible
Manual review needed: Flag items that need human judgment

ss-audit

基于尼尔森十大可用性启发式原则和现代移动端UX最佳实践，审查屏幕的UX问题。涵盖系统状态可见性、用户控制、一致性、错误预防等维度，旨在识别并优化交互体验缺陷。

审查移动应用界面的用户体验问题评估屏幕是否符合尼尔森可用性启发式原则检查移动端交互设计的一致性和易用性

engine/.claude/skills/ss-audit/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-audit -g -y

SKILL.md

Frontmatter

{
    "name": "ss-audit",
    "description": "Audit screens for UX issues using Nielsen's heuristics and modern mobile UX best practices",
    "allowed-tools": "Read, Grep, Glob",
    "argument-hint": "[file-path or screen-name]"
}

UX Audit

When NOT to use

For accessibility-only issues → use /ss-a11y
For design system token/golden-rule compliance → use /ss-review
For copy/microcopy quality → use /ss-copy
For brand new screens that don't exist yet — design first with /ss-page or /ss-flow

Target: $ARGUMENTS

Audit Framework

Nielsen's 10 Usability Heuristics

1. Visibility of System Status

Loading states present (skeleton screens, not spinners)
Success/error feedback after actions (toast notifications)
Progress indicators for multi-step flows
Active state clearly shown on navigation items
Real-time data has timestamp showing freshness

2. Match Between System and Real World

Labels use user's language, not technical jargon
Icons are universally recognizable (Lucide standard set)
Number formats match user expectations (comma separators, currency symbols)
Date formats are locale-appropriate

3. User Control and Freedom

Back navigation available on all non-root screens
Destructive actions have confirmation dialogs
Undo available for reversible actions (toast with undo)
Bottom sheet/modal can be dismissed (backdrop tap, swipe down, X button)
No dark patterns (no forced actions, always a way to dismiss)

4. Consistency and Standards

Same action = same appearance everywhere
Color meanings are consistent (green=success, red=error, brand=active)
Text hierarchy follows the 5-level grayscale system
All cards use the same shadow, radius, padding
Spacing follows the 6px grid system

5. Error Prevention

Destructive buttons are visually distinct (destructive variant)
Form validation happens on blur (not while typing)
Dangerous actions require explicit confirmation
Input constraints are visible before errors occur (character limits, format hints)

6. Recognition Rather Than Recall

Labels on all icons (especially BottomNav)
Current state visible without memorization (active tab highlighted)
Recent/frequent items shown for quick access
Placeholder text shows expected format

7. Flexibility and Efficiency

Key actions reachable within 3 taps from home
Pull-to-refresh on data screens
Touch targets >= 44x44px (no tiny tap areas)
Frequently used actions in easy-to-reach zones (bottom of screen)

8. Aesthetic and Minimalist Design

Each screen focuses on ONE primary task
No decorative elements that don't serve a purpose
Information pyramid respected (most important = biggest)
Card density follows the max-4-items rule
No competing visual elements (one hero metric per page)

9. Help Users Recover from Errors

Error messages explain what went wrong in plain language
Error messages suggest how to fix the problem
Partial failures don't break the whole page (one card fails, others load)
Network errors show retry button
Form errors highlight the specific field

10. Help and Documentation

Empty states guide users to take action
Onboarding for first-time features (if applicable)
Tooltips for complex metrics (if applicable)

Mobile-Specific UX Checks

Touch & Gesture

Touch targets minimum 44x44px
Minimum 8px between adjacent touch targets
No hover-dependent interactions (mobile has no hover)
Swipe gestures have visible affordances (carousel indicators)

Performance Perception

Skeleton screens appear within 300ms
Optimistic updates for user actions
Above-the-fold content loads first
No layout shift after content loads

Safe Areas

Content not hidden behind notch/Dynamic Island
Bottom content not behind home indicator
BottomNav has pb-safe padding

Dark Pattern Prevention

No forced bottom sheets on entry
No exit-prevention dialogs
Every screen has a way to go back/dismiss
CTA labels clearly describe the action
No manipulative graphics (begging, urgency)

Output Format

Score: A+ to F rating with breakdown
Critical Issues: Must fix (blocks usability)
Major Issues: Should fix (degrades experience)
Minor Issues: Nice to fix (polish)
Recommendations: Specific code changes for each issue

ss-component

根据StyleSeed设计规范生成新的UI组件。读取设计系统上下文，严格遵循函数声明、CVA变体、语义化Token及无障碍要求，输出符合约定的React组件代码。

需要创建新的UI组件生成符合StyleSeed规范的React组件

engine/.claude/skills/ss-component/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-component -g -y

SKILL.md

Frontmatter

{
    "name": "ss-component",
    "description": "Generate a new UI component following the StyleSeed design conventions",
    "allowed-tools": "Read, Write, Edit, Grep, Glob, Bash",
    "argument-hint": "[component-name] [description]"
}

UI Component Generator

When NOT to use

For full-page scaffolding → use /ss-page
For composed multi-component patterns → use /ss-pattern
For tweaking an existing component — just edit the file directly
For non-StyleSeed projects (no components/ui/ directory or no Tailwind v4)

Generate a new component: $0 Description: $ARGUMENTS

Instructions

First, read the design system seed for context:
- Read CLAUDE.md for component conventions
- Read css/theme.css for available design tokens
- Read components/ui/button.tsx as a reference pattern
Follow these conventions strictly:
- Use function declaration (not const)
- Add data-slot="component-name" attribute
- Use cn() from @/components/ui/utils for all className merging
- Use React.ComponentProps<> for prop typing
- Always support className prop for overrides
- Use CVA (class-variance-authority) if the component has variants
- Use semantic color tokens (bg-card, text-foreground) — never inline hex
Design token usage:
- Colors: text-foreground, bg-card, text-brand, text-muted-foreground, border-border
- Shadows: shadow-[var(--shadow-card)], shadow-[var(--shadow-elevated)]
- Radius: rounded-md, rounded-lg, rounded-2xl
- Spacing: multiples of 6px (p-1.5, p-3, p-6)
- Motion: duration-[var(--duration-fast)], ease-[var(--ease-default)]
Typography rules:
- Display (36-48px): leading-none tracking-[-0.02em]
- Heading (18-24px): leading-snug tracking-[-0.01em]
- Body (14-17px): leading-normal (default tracking)
- Caption uppercase (10-13px): tracking-[0.05em]
- Use size-* shorthand instead of w-* h-*
- Use ms-*/me-* instead of ml-*/mr-* (logical properties)
Accessibility requirements:
- Minimum touch target: 44x44px (min-h-11 min-w-11)
- Support aria-* attributes passthrough
- Use focus-visible:ring-2 focus-visible:ring-ring for keyboard focus
- Respect prefers-reduced-motion for animations
Export the component as a named export (not default)
Place the file in the appropriate directory:
- Primitive/reusable → src/components/ui/
- Composed pattern → src/components/patterns/

ss-copy

生成符合随意但礼貌语气的UX微文案，涵盖按钮、错误提示、空状态及Toast。遵循主动语态和简洁原则，避免技术术语，提供具体场景的文案范例与规范。

生成按钮标签编写错误消息设计空状态文案创建Toast通知文本

engine/.claude/skills/ss-copy/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-copy -g -y

SKILL.md

Frontmatter

{
    "name": "ss-copy",
    "description": "Generate UX microcopy (button labels, error messages, empty states, toasts) following a casual-but-polite voice and tone",
    "allowed-tools": "Read, Write, Edit, Grep, Glob",
    "argument-hint": "[context] [description]"
}

UX Microcopy Generator

When NOT to use

For long-form content (blog posts, docs, marketing pages) — out of scope
For full feedback state design (not just text) → use /ss-feedback
For brand voice/tone definition itself — this skill consumes a voice spec, doesn't create it
For translations to non-English languages — single-language only

Context: $0 Description: $ARGUMENTS

Read engine/UX-WRITING.md first — it's the rule set this skill applies: buttons name the action (not "Submit"), errors help instead of blame, empty states invite, money copy stays calm, one term per concept. Korean/CJK projects: see §W8 for the clear-calm-human "Toss feel" (존댓말 일관성, 사용자 관점 "내 계좌", 군더더기 빼기).

Instructions

Read the design language reference:
- DESIGN-LANGUAGE.md sections on Microcopy Tone Guide and UX Writing
Apply the voice principles:

Tone Rules

Casual but polite: Friendly, not robotic. Like talking to a helpful friend.
Active voice: "We saved your changes" not "Your changes have been saved"
Positive framing: "Free shipping on orders over $30" not "Orders under $30 have shipping fees"
Plain language: "Send money" not "Initiate transfer"
Concise: Every word must earn its place

Copy Patterns by Context

Button Labels (CTA)

Format: [Action verb] + [Object] (optional)
Good: "Place order", "Get started", "Save changes", "Try again"
Bad:  "Submit", "OK", "Click here", "Proceed to next step"

One primary CTA per screen
Label must clearly describe what happens next
Max 3 words for primary CTA

Empty States

Format: [Friendly observation] + [Suggested action]
Good: "No activity yet. Create your first project to get started."
Bad:  "No data found."

Always suggest a next action
Use a relevant icon (32px, text-text-tertiary)
Tone: encouraging, not blaming

Error Messages

Format: [What happened] + [What to do]
Good: "Couldn't load the data. Please try again."
Bad:  "Error 500: Internal Server Error"

Never show technical errors to users
Blame the system, not the user
Always provide a recovery action

Toast Notifications

Format: [Confirmation of what happened]
Good: "Saved!", "Changes applied", "Item deleted · Undo"
Bad:  "Operation completed successfully"

Max 2 lines
Include "Undo" link for reversible destructive actions
Info toasts: 3 seconds. Action toasts: 5 seconds.

Form Labels & Helpers

Label: Noun phrase ("Email address", "Password")
Placeholder: Example or hint ("name@example.com")
Helper: Format guidance ("Must be at least 8 characters")
Error: Specific issue ("This email is already registered")

Confirmation Dialogs

Title: [Question about the action]
Body: [Consequence explanation]
Primary: [Action verb] ("Delete", "Confirm")
Secondary: "Close" (not "Cancel" — avoids confusion)

Generate copy for the requested context, providing:
- Primary copy (what to display)
- Variants (if context varies)
- Do's and Don'ts for the specific context

ss-feedback

为组件或页面添加加载、成功、错误和空状态反馈。识别数据依赖区域，实现骨架屏、空状态、错误重试及操作提示，遵循设计语言规范与无障碍要求。

需要为UI组件添加加载、空、错误或成功状态时优化现有组件的数据驱动状态展示时

engine/.claude/skills/ss-feedback/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-feedback -g -y

SKILL.md

Frontmatter

{
    "name": "ss-feedback",
    "description": "Add appropriate user feedback states (loading, success, error, empty) to a component or page",
    "allowed-tools": "Read, Write, Edit, Grep, Glob",
    "argument-hint": "[file-path]"
}

UX Feedback States Generator

When NOT to use

For only the words inside a state → use /ss-copy
For accessibility issues in existing states → use /ss-a11y
For brand-new component creation → use /ss-component
For analytics or error-logging plumbing — UI presentation only

Target: $ARGUMENTS

Instructions

Read the target file and identify all data-dependent areas.
Read the design language reference:
- DESIGN-LANGUAGE.md sections on Loading States (Skeleton), Empty States, Error States
For each data-dependent area, implement ALL 4 states:

State 1: Loading (Skeleton)

// Skeleton must match the final layout shape
<div className="bg-card rounded-2xl p-6 shadow-[var(--shadow-card)]">
  <div className="flex items-center gap-2 mb-3">
    <div className="size-7 bg-surface-muted rounded-lg animate-pulse" />
    <div className="h-3 w-16 bg-surface-muted rounded animate-pulse" />
  </div>
  <div className="h-9 w-24 bg-surface-muted rounded-lg animate-pulse mb-3" />
  <div className="h-3 w-12 bg-surface-muted rounded animate-pulse" />
</div>

Rules:

Show skeleton for 300ms minimum (prevent flash)
Delay skeleton display by 300ms (fast loads skip skeleton entirely)
Use animate-pulse (1.5s cycle)
Match skeleton shapes to real content dimensions
Never use spinners inside cards

State 2: Empty (Zero Data)

<EmptyState
  icon={PackageIcon}
  title="No activity yet"
  description="Create your first project to get started."
  action={<Button>Create Project</Button>}
/>

Rules:

Center-aligned in the card
Icon: 32px, text-text-tertiary
Title: 14px, text-text-secondary
Always suggest a next action
Zero values show as "0" (don't hide or dash)

State 3: Error (Load Failed)

<div className="flex flex-col items-center justify-center py-8 text-center">
  <AlertCircle className="size-8 text-destructive mb-3" />
  <p className="text-[14px] text-text-secondary mb-4">Couldn't load the data</p>
  <Button variant="brandGhost" size="sm" onClick={retry}>Try again</Button>
</div>

Rules:

Partial failure: only affected card shows error, rest loads normally
Full page failure: full-screen EmptyState with retry
Error message: plain language, blame the system
Always provide retry button

State 4: Success (Action Feedback)

// Toast notification for action confirmations
toast("Changes saved")

// With undo for destructive actions
toast("Item deleted", { action: { label: "Undo", onClick: handleUndo } })

Rules:

Info toast: 3s display
Action toast (with undo): 5s display
Toast position: above BottomNav
One toast at a time (new replaces old)

Implementation pattern:

function DataCard({ data, isLoading, error }) {
  if (isLoading) return <DataCardSkeleton />
  if (error) return <DataCardError onRetry={refetch} />
  if (!data || data.length === 0) return <DataCardEmpty />
  return <DataCardContent data={data} />
}

Check prefers-reduced-motion — disable animate-pulse when reduced motion is preferred.

ss-flow

用于设计用户流程与导航结构，遵循UX模式。通过应用渐进式披露、米勒定律等原则，生成ASCII流程图、屏幕清单及边缘情况处理，为后续页面实现提供清晰的信息架构和交互逻辑。

需要设计用户操作流程规划应用导航结构优化信息层级与交互路径

engine/.claude/skills/ss-flow/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-flow -g -y

SKILL.md

Frontmatter

{
    "name": "ss-flow",
    "description": "Design user flows and navigation structure following proven UX patterns",
    "allowed-tools": "Read, Write, Edit, Grep, Glob, Bash",
    "argument-hint": "[flow-name] [description]"
}

UX Flow Designer

When NOT to use

For implementing a single page → use /ss-page after the flow is settled
For copy on each step → use /ss-copy after the structure is settled
For information architecture of an entire product — narrow scope to one flow first
For high-fidelity mockups — this produces a flow map, not pixel-perfect designs

Design a user flow: $0 Description: $ARGUMENTS

Instructions

Read the design system reference:
- CLAUDE.md for component inventory
- DESIGN-LANGUAGE.md for layout patterns (sections 13-14, 19-20)
- components/patterns/ for available building blocks
Apply these UX principles:

Information Architecture

Progressive Disclosure: Show only what's needed at each step. Hide complexity behind logical drill-downs.
Miller's Law: Chunk information into groups of 5-9 items maximum.
Hick's Law: Minimize choices per screen. Fewer options = faster decisions.

Navigation Patterns

Hub & Spoke: Dashboard → detail pages → back to dashboard (default for mobile apps)
Linear Flow: Step 1 → Step 2 → Step 3 (for forms, onboarding, checkout)
Tab Navigation: 3-5 top-level sections via BottomNav

Screen Flow Rules

Every flow must have a clear entry point and clear exit point
Maximum 3 taps to reach any key feature from the home screen
Back navigation must always be available (except root screens)
Error states must provide recovery paths (retry, go back, contact support)
Loading states must use skeleton screens (never spinners in cards)

Page Composition (from DESIGN-LANGUAGE.md)

Follow the Information Pyramid: Hero → KPI Grid → Details → Lists
Each screen should answer ONE primary question
Above the fold: the most important metric or action
Use the 4 section types: Full Card (A), Grid (B), Carousel (C), Hero (D)

Output format:
- Flow diagram in ASCII showing screen connections
- Screen inventory listing each screen's purpose and key components
- Edge cases (empty states, errors, loading) for each screen
- Scaffolded pages using PageShell, TopBar, BottomNav patterns
Generate the actual page files using /ss-page conventions.

ss-lint

快速自动化设计规范检查工具，通过正则扫描检测硬编码颜色、原始像素值、物理属性等常见设计系统违规项。运行速度快，适用于文件变更后的即时反馈，不替代深度审查或修复操作。

用户请求快速设计lint检查代码提交或保存后自动触发需要验证Tailwind类名是否符合语义化规范

engine/.claude/skills/ss-lint/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-lint -g -y

SKILL.md

Frontmatter

{
    "name": "ss-lint",
    "description": "Quick automated lint — detects common design system violations in seconds",
    "allowed-tools": "Read, Grep, Glob, Bash",
    "argument-hint": "[file-path or directory]"
}

Design Lint (Quick Check)

When NOT to use

For deeper review of design judgment (composition, hierarchy, rhythm) → use /ss-review
For accessibility specifically → use /ss-a11y
For Nielsen UX heuristics → use /ss-audit
For applying refactors — this only flags violations; use /ss-review to fix

Target: $ARGUMENTS

What This Does

Fast, grep-based scan for common design violations. Runs in seconds (unlike /ss-review which is a deep manual audit). Run this after every file change.

Checks

1. Hardcoded Colors

Search for hex colors in className strings that should be semantic tokens:

grep -n '#[0-9a-fA-F]\{3,8\}' [file] | grep -v 'theme.css\|tokens\|\.json'

Violation: text-[#3C3C3C], bg-[#721FE5] Fix: text-text-primary, bg-brand

2. Raw Pixel Values in Tailwind

grep -n 'p-\[.*px\]\|m-\[.*px\]\|gap-\[.*px\]' [file]

Violation: p-[24px], gap-[12px] Fix: p-6, gap-3

3. Old Width/Height Syntax

grep -n 'w-[0-9] h-[0-9]\|w-\[.*\] h-\[' [file]

Violation: w-4 h-4 Fix: size-4

4. Physical Properties (LTR-only)

grep -n ' ml-\| mr-\| pl-\| pr-' [file]

Violation: ml-2, mr-4 Fix: ms-2, me-4

5. Forbidden Colors

grep -n 'text-black\|bg-black\|#000000\|#000"' [file]

Violation: Any pure black Fix: Use skin's text-primary token

6. Missing data-slot

grep -n 'function [A-Z]' [file] # find components
grep -n 'data-slot' [file]       # check if present

Violation: Component without data-slot Fix: Add data-slot="component-name"

7. Font Size CSS Variables (CRITICAL — Tailwind v4 conflict)

grep -n 'text-\[var(--' [file]
grep -n '\-\-text-.*px\|--fs-.*px' [file]

Violation: text-[var(--text-sm)] or --text-sm: 13px in theme.css Fix: Use explicit text-[13px]. CSS variable font sizes conflict with Tailwind v4's --text-* namespace — Tailwind reads them as color, not font-size.

8. className Without cn()

grep -n 'className={`' [file]

Violation: Template literal className Fix: Use cn() for all className composition

Output Format

🔴 FAIL  [file:line] Hardcoded hex: text-[#3C3C3C] → use text-text-primary
🔴 FAIL  [file:line] Raw px: p-[24px] → use p-6
🟡 WARN  [file:line] Physical prop: ml-2 → use ms-2
🟡 WARN  [file:line] Missing data-slot on MyComponent
🟢 PASS  No violations found

Total: X errors, Y warnings

If errors > 0, list specific fixes for each violation.

ss-motion

将用户描述的动态风格或组件用途映射为具体的 Framer Motion 种子配置。支持品牌默认、情绪关键词及用例推荐，确保 React 组件动画的一致性与规范性。

用户描述 UI 交互的视觉风格（如弹跳、平滑）指定特定组件需要添加入场或悬停动画询问如何将品牌名称关联到默认动效种子

engine/.claude/skills/ss-motion/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-motion -g -y

SKILL.md

Frontmatter

{
    "name": "ss-motion",
    "description": "Apply a named StyleSeed motion to a component — either one of the 5 personality seeds (Spring\/Silk\/Snap\/Float\/Pulse × entrance\/exit\/hover\/press\/layout) or a distinctive keyword move from the motion library (toggle-flip, toggle-curtain, reveal-blur, pop-in, shimmer, …). Translates vibe words into framer-motion code from one source of truth.",
    "allowed-tools": "Read, Write, Edit, Grep, Glob, Bash",
    "argument-hint": "[vibe-seed-or-keyword] [context] [file-path]"
}

Motion Seed Applier

When NOT to use

For general framer-motion docs or learning → use the framer-motion site
For non-React motion (CSS-only transitions, GSAP) — this skill targets motion.X JSX only
For full scroll-linked timelines or parallax — out of scope per DESIGN-LANGUAGE.md Rule 59
For tweaking the existing FadeIn/FadeUp/Stagger wrappers — edit engine/components/ui/motion.tsx directly

Vibe → Seed mapping

Translate the user's prompt to one of the five seeds before applying. Use this lookup table from engine/motion/index.ts:

Words the user might say	Seed
bouncy, springy, playful, energetic, alive	Spring
smooth, silky, fluid, elegant, composed, continuous	Silk
snappy, quick, instant, decisive, sharp, precise	Snap
floaty, gentle, weightless, dreamy, ambient, drifting	Float
rhythmic, punchy, pulsing, heartbeat, beat	Pulse
"Toss style", "Arc style"	Spring (per brand default)
"Stripe style", "Notion style"	Silk
"Linear style", "Raycast style", "Vercel style"	Snap

If the user says only a brand name, use that brand's default seed from BRAND_DEFAULT_SEED. If the user is explicit about a seed name (spring, silk, etc.), respect it verbatim.

Recommend mode — use-case → motion (when the user describes the moment, not the vibe)

If the user describes what the thing is ("a like button", "a modal", "the loading state", "items in a feed") rather than a feeling, recommend from the use-case map (MOTION_BY_USECASE in engine/motion/library.ts, exported from @engine/motion):

Use case	Reach for	Why
Primary button / CTA press	`spring · press`	tactile, confident — the press should "give"
Modal / dialog / sheet enter	`silk · entrance`	smooth; never bounce serious/destructive content
Dropdown / popover / menu	`snap · entrance`	instant, precise — frequent UI shouldn't wait
Toast / inline notification	`spring · entrance`	small friendly arrival, non-blocking
List / feed items appearing	`stagger-cascade`	choreograph order, gently
Feature / marketing card hover	`tilt-3d`	depth/flair OK on content-light marketing
Dashboard / data card hover	`snap · hover`	a subtle lift only — keep dense UI calm
Like / favorite / reaction	`like-burst`	a celebratory one-shot; reward the tap
Live / online / recording dot	`pulse-beat`	looping heartbeat = "alive"
Loading / skeleton	`shimmer`	calm directional progress
Success / confirmation	`pop-in`	positive little "done"
Toggle / tab / segment switch	`toggle-flip`	distinctive, recognizable switch
Page / route transition	`silk · entrance`	smooth, minimal, get out of the way
Number / balance / KPI / price reveal	none	don't animate the payload — it must read instantly

Two anti-rules override the table (state them if you deviate):

One seed per product. If the project already uses a seed, match it — don't introduce a second personality.
Never delay the payload. Don't animate a balance, price, or search result into view; motion is for affordance, not content.

Named motion keywords (distinctive moves)

Seeds set a personality (how a fade/scale feels). The motion library in engine/motion/library.ts adds distinctive moves — a flip, a curtain wipe, a morph — each behind a unique keyword. Prefer a keyword when the user wants a specific, recognizable motion rather than a generic feel.

engine/motion/library.ts (exported as MOTION_LIBRARY / MOTION_BY_KEY from @engine/motion) is the single source of truth — every keyword carries its own runnable snippet. Pull the snippet from there; never hand-write the params.

Keyword	Move	Say it when the user wants…
`toggle-flip`	3D Y-axis card flip	a switch/toggle to flip between two faces
`toggle-slide`	slide-stack swap	a value to slide out and the next to slide in
`toggle-morph`	pill ⇄ circle morph	a control to change shape on toggle
`toggle-curtain`	top→bottom clip-path wipe	a panel to reveal like a curtain
`reveal-blur`	blur(12px)→0 focus-in	content to focus-pull into place
`reveal-rise`	masked clip-path text rise	a headline/text to climb into view
`reveal-unfold`	scaleY from top edge	an accordion/panel to unfold
`pop-in`	spring overshoot from 0	a badge/checkmark to pop in bouncily
`press-squish`	scale-down + skew	a button to feel jelly/tactile on tap
`tap-ripple`	radial ripple from tap	Material-style press feedback
`pulse-beat`	looping scale pulse	a live/recording/heartbeat indicator
`wiggle`	quick horizontal shake	error / invalid-input feedback
`shimmer`	skeleton loading sweep	a loading placeholder
`stagger-cascade`	children fade-up in sequence	a list to animate in one-by-one

Applying a keyword:

Read the exact recipe from engine/motion/library.ts — find the entry whose key matches, copy its snippet verbatim (it is calibrated and runnable).
Adapt only the element/content to the user's JSX; keep the transition values.
If the keyword is stateful (toggles, ripple), wire the useState shown in the snippet. If it's a one-shot reveal, a key bump replays it.
Tell the user the keyword you applied so they can reuse it elsewhere for consistency, and point them at /motion to preview/Copy others.

If the user describes a move but no exact keyword fits, fall back to a seed + context. If they say a keyword that doesn't exist, suggest the closest real one from the table — never invent a keyword.

Context detection

Infer one of the five contexts from the prompt:

"on hover" / "when hovered" → hover
"on press" / "on tap" / "on click" → press
"when it appears" / "on mount" / "entering" → entrance
"when it leaves" / "on close" / "exiting" → exit (requires <AnimatePresence>)
"when layout changes" / "FLIP" / "rearranging" → layout

If ambiguous, default to entrance. If multiple contexts are reasonable (e.g., a button needs both hover and press), apply both.

Application steps

Apply seed: $0 · Context: $1 · Target: $ARGUMENTS

Read the target file at the path given (or, if no path was given, ask the user which file). Locate the JSX element the user is talking about — usually a <button>, <div>, <Card>, or similar.
Confirm the import paths. The component file must be able to import:
- motion (and AnimatePresence for exit) from "framer-motion"
- the chosen seed from "@engine/motion" — in a project that doesn't use the @engine/* alias, use a relative path to engine/motion

Replace the target tag with a <motion.X> and spread the seed's recipe:

// hover example
<motion.button {...spring.hover}>Save</motion.button>

// press + hover combined
<motion.button {...spring.press} {...spring.hover}>Save</motion.button>

// entrance (mount)
<motion.div {...silk.entrance}>...</motion.div>

// exit (requires AnimatePresence wrapper somewhere up the tree)
<AnimatePresence>
  {open && <motion.div {...silk.entrance} {...silk.exit} />}
</AnimatePresence>

// layout (FLIP)
<motion.div {...snap.layout}>...</motion.div>

Do NOT inline the params. The whole point of the seed is that the values come from one source. Never expand { type: "spring", stiffness: 300, damping: 18 } into the JSX — always spread the recipe.
Respect prefers-reduced-motion in long-running surfaces. For one-off interactions (hover/press), framer-motion already throttles. For mount/exit/layout sequences in a long-lived page, import usePrefersReducedMotion and REDUCED_TRANSITION from @engine/motion and override the transition when reduced motion is on.
Validate by re-reading the file and confirming the JSX still parses (matching brackets, motion tag closed, AnimatePresence in place if exit was used).
Tell the user which seed and context you applied, and offer one related context they might want next ("Want press too so it feels clickable?").

Defaults if the user is vague

No file given → ask "which file?"
No vibe word → ask "any vibe word, brand, or seed name?"
Vibe is "natural" or "feel like a real app" → default to Silk (the safest of the five)
Element is a CTA button → also apply press

Forbidden

Do not invent new seed names. There are exactly five.
Do not edit engine/motion/seeds/*.ts from this skill — those are calibrated by hand. Add a new seed only via a separate, explicit ask.
Do not introduce a third-party animation lib (gsap, anime.js). StyleSeed targets framer-motion exclusively.
Do not add scroll-linked, parallax, or infinite animations (DESIGN-LANGUAGE.md Rule 59).

ss-page

基于StyleSeed规范快速搭建移动端页面骨架。提供标准布局模板、样式规则及组件组合指南，强制要求使用语义化颜色、安全区域适配，并包含严格的生成后黄金规则校验流程，确保页面符合设计规范。

需要创建新的移动端页面或屏幕初始化符合StyleSeed规范的移动应用界面

engine/.claude/skills/ss-page/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-page -g -y

SKILL.md

Frontmatter

{
    "name": "ss-page",
    "description": "Scaffold a new mobile page\/screen using the StyleSeed layout patterns",
    "allowed-tools": "Read, Write, Edit, Grep, Glob, Bash",
    "argument-hint": "[page-name] [description]"
}

Mobile Page Scaffolder

When NOT to use

For a single composed pattern within an existing page → use /ss-pattern
For desktop-only screens — this skill is mobile-first
For multi-page navigation structure → use /ss-flow first
For tweaking an existing page — edit the file directly

Create a new page: $0 Description: $ARGUMENTS

Instructions

Read the design system reference:
- CLAUDE.md for file structure and conventions
- components/patterns/page-shell.tsx for page layout
- components/patterns/top-bar.tsx for header pattern
- components/patterns/bottom-nav.tsx for navigation
Page structure template:

import { PageShell, PageContent } from "@/components/patterns/page-shell"
import { TopBar, TopBarAction } from "@/components/patterns/top-bar"
import { BottomNav } from "@/components/patterns/bottom-nav"

export default function PageName() {
  return (
    <PageShell>
      <TopBar
        logo={/* logo or page title */}
        subtitle={/* optional subtitle */}
        actions={/* optional action buttons */}
      />
      <PageContent>
        {/* Page sections with space-y-6 */}
      </PageContent>
      <BottomNav items={[/* nav items */]} activeIndex={0} />
    </PageShell>
  )
}

Layout rules:
- Container: max-w-[430px] (mobile viewport)
- Page background: bg-background
- Section horizontal padding: px-6
- Section vertical spacing: space-y-6
- Bottom padding for nav: pb-24
- Cards: bg-card rounded-2xl p-6 shadow-[var(--shadow-card)]
Use semantic tokens for all colors — never hardcode hex values.
Compose the page from existing components (ui/ and patterns/) wherever possible.
Safe area: include env(safe-area-inset-*) padding for modern devices.
Post-generation verification (MANDATORY): After creating the page, verify against the Golden Rules:
- All content is inside cards (no bare background content)
- Only --brand color used for accents (no other accent colors)
- No hardcoded hex values (all semantic tokens)
- Section types alternate (no two identical types in a row)
- Numbers have 2:1 ratio with units
- Spacing uses 6px multiples (p-1.5, p-3, p-6)
- mx-6 for single cards, px-6 for grids/carousels
- Touch targets ≥ 44px on all interactive elements If any violation is found, fix it before presenting the page to the user.

ss-pattern

根据设计系统原语生成可复用的组合UI模式，如卡片、列表、表单或网格。适用于需要布局组合的场景，而非单一组件或完整页面。

需要生成组合式UI布局创建卡片组、网格或表单区域

engine/.claude/skills/ss-pattern/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-pattern -g -y

SKILL.md

Frontmatter

{
    "name": "ss-pattern",
    "description": "Generate a composed UI pattern (card layout, list, form section, grid, etc.) using design system primitives",
    "allowed-tools": "Read, Write, Edit, Grep, Glob, Bash",
    "argument-hint": "[pattern-type] [description]"
}

UI Pattern Generator

When NOT to use

For a single primitive component → use /ss-component
For a full mobile screen → use /ss-page
For an entire multi-page user flow → use /ss-flow
For design tokens and color/spacing decisions → use /ss-tokens

Pattern type: $0 Description: $ARGUMENTS

Available Pattern Types

Layout Patterns

card-section: Card with title + content inside page section (mx-6)
grid-2col: 2-column grid of cards (grid grid-cols-2 gap-4 px-6)
scroll-horizontal: Horizontal scrolling card list (flex gap-3 overflow-x-auto scrollbar-hide)
list-section: Vertical list of items inside a card
form-section: Form with labeled inputs in a card
stat-grid: Grid of StatCard components

Data Display Patterns

data-table: Table with header and rows
detail-card: Key-value pair display
chart-card: Card wrapper for a Recharts chart
ranking-list: Numbered ranking with highlight

Interactive Patterns

action-sheet: Bottom sheet with action buttons
filter-bar: Horizontal filter/tab bar
search-header: Search input in header area

Instructions

Read the design system reference:
- CLAUDE.md for conventions
- components/ui/ for available primitives
- components/patterns/ for existing patterns
Compose the pattern from existing components — DO NOT recreate primitives.
Follow the design system layout rules:
- Cards: bg-card rounded-2xl p-6 shadow-[var(--shadow-card)]
- Section wrapper: mx-6 for horizontal margin
- Section title: text-foreground font-bold text-[18px] mb-4
- List gap: space-y-3
- Grid gap: gap-4
Use semantic tokens for all visual properties.
Make the pattern a reusable component with props for dynamic content.

ss-review

用于审查UI代码是否符合设计规范、无障碍标准及最佳实践。涵盖设计令牌合规、组件约定、可访问性、移动端适配、性能、排版、间距一致性及视觉连贯性，确保代码质量与系统一致性。

用户请求审查UI代码的设计规范合规性用户要求检查前端组件的可访问性和最佳实践

engine/.claude/skills/ss-review/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-review -g -y

SKILL.md

Frontmatter

{
    "name": "ss-review",
    "description": "Review UI code for design system compliance, accessibility, and best practices",
    "allowed-tools": "Read, Grep, Glob",
    "argument-hint": "[file-path]"
}

UI Design Review

When NOT to use

For accessibility-only issues → use /ss-a11y
For Nielsen UX heuristics → use /ss-audit
For a quick automated check → use /ss-lint
For non-UI code (data fetching, business rules)

Review the file: $ARGUMENTS

Checklist

1. Design Token Compliance

No hardcoded hex colors (use semantic tokens: text-foreground, bg-brand, etc.)
No hardcoded px spacing in Tailwind (use p-6 not p-[24px])
Shadows use CSS variables (shadow-[var(--shadow-card)])
Border radius follows the scale (rounded-md, rounded-lg, rounded-2xl)

2. Component Conventions

Uses data-slot attribute
Uses cn() for className merging
Props typed with React.ComponentProps<>
Supports className prop override
Named export (not default export for components)
No wrapper components that only add a className

3. Accessibility (a11y)

Touch targets >= 44x44px for interactive elements
focus-visible styles on all interactive elements
Proper aria-* attributes where needed
Color contrast meets WCAG AA (4.5:1 for text, 3:1 for large text)
Animations respect prefers-reduced-motion
Images have alt text
Form inputs have associated labels

4. Mobile Best Practices

No horizontal overflow
Touch-friendly spacing between interactive elements
Safe area insets handled for notched devices
Text sizes >= 12px for readability
Scrollable containers have -webkit-overflow-scrolling: touch

5. Performance

No unnecessary re-renders (stable references, memoization where needed)
Images are lazy-loaded
Heavy components are code-split

6. Typography

Uses the Pretendard/Inter font stack
Font sizes from the 14-step scale (10-48px, see CLAUDE.md)
Proper font weights (400, 500, 600, 700)
Display text (36-48px): leading-none + tracking-[-0.02em]
Heading text (18-24px): leading-snug + tracking-[-0.01em]
Body text (14-17px): leading-normal (no custom tracking)
Caption uppercase (10-13px): tracking-[0.05em] or tracking-wide
No line-height: 1.5 on display/heading text (too loose)

7. Spacing Consistency

All spacing values are multiples of 6px (p-1.5, p-3, p-6, etc.)
No arbitrary spacing (p-5=20px, gap-3.5=14px are violations)
Uses size-* shorthand instead of w-* h-*
Uses ms-*/me-* instead of ml-*/mr-* (logical properties)
Motion transitions use design tokens (duration-[var(--duration-fast)])

8. Coherence (VISUAL-CRAFT.md §C0 — the "one choice per axis" laws)

The biggest reason a UI reads as "AI-generated" isn't ugly parts — it's mixed parts. Check that each axis below uses ONE value system-wide; flag a mix as a real issue, not a nitpick.

One radius personality — sharp (0-4px) OR soft (8-12px) OR pill, applied to every card/button/input/modal. No mixing (e.g. a rounded-none panel with rounded-full buttons).
One accent color for interactive emphasis (+ semantic red/green/amber only) — not two+ competing accents.
No emoji as UI icons (🚗🧺⭐ as list/nav/status/category markers) — they inject many uncontrolled hues; use one line-icon set in currentColor.
Status color = severity, not decoration — a normal/OK/"보통" state is neutral grey (not colored); color marks only the minority of rows that need attention; same value → same color.
No decorative hues — favorite stars, category dots, avatars use the accent or grey, not a new color each.
One shadow language — same light direction, same scale/tint; not some black + some tinted, some up-lit + some down-lit.
One icon family / fill mode / stroke weight across the file.
Nested-radius law — an element inside a rounded container uses inner = outer − padding, not the same radius (which bulges).
Consistent control heights — buttons, inputs, selects share a height set (e.g. 40px).
Errors/states never rely on color alone (icon + text too).

Output Format

Provide:

Score: Pass / Needs Improvement / Fail
Issues: List each violation with file:line reference
Fixes: Concrete code changes for each issue

ss-score

基于StyleSeed设计规范对UI文件进行0-100分质量评分。涵盖色彩、层级、布局等六类加权指标，通过扣分制识别违规项并生成优先级修复列表，辅助量化追踪设计质量。

需要评估UI文件整体设计质量得分时希望获得按类别细分的设计问题及优先修复建议时

engine/.claude/skills/ss-score/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-score -g -y

SKILL.md

Frontmatter

{
    "name": "ss-score",
    "description": "Score a UI file's design quality 0-100 against StyleSeed's design language — per-category breakdown, the worst offenders, and a prioritized fix list. A quantified version of \/ss-review.",
    "allowed-tools": "Read, Grep, Glob, Bash",
    "argument-hint": "[file-path or directory]"
}

Design Score

/ss-review tells you what's wrong. /ss-score tells you how good it is overall and what to fix first — a single number plus a category breakdown, so you can track UI quality like you track test coverage.

When NOT to use

For a quick pass/fail before committing → use /ss-lint
For a full prose audit with fixes → use /ss-review
For non-UI files (logic, config) — scoring is meaningless

What to score

Score the file (or each file in a directory) on six weighted categories that map to the design language. Total = 100.

Category	Weight	Reads from
Color discipline	16	DESIGN-LANGUAGE §1, §18, §72 + VISUAL-CRAFT §C4
Hierarchy & typography	16	§2, §3, §4, §16 + Font Size table + VISUAL-CRAFT §C2
Layout & rhythm	12	§13, §14, §15, §61 + VISUAL-CRAFT §C1
Cards & elevation	10	§7, §8, §12, §1 + VISUAL-CRAFT §C3
States & a11y	18	§11, §70, §71, §72 + VISUAL-CRAFT §C3
Motion & interaction	6	§24, §59 + `engine/motion`
Coherence	12	VISUAL-CRAFT §C0 (one choice per axis)
Distinctiveness	10	Golden Rules 14–16 + VISUAL-CRAFT §CC-9b (not generic/default/template)

How to score each category

For each category, start at full marks and subtract for violations you find by reading the code. Be specific and evidence-based — cite the line.

Color discipline (16) — deduct for: any #000/text-black (−4 each, cap −8); more than one accent hue used decoratively (−5); emoji used as UI icons (multi-color, breaks single accent) (−5); a normal/OK/"보통" state shown in a status color instead of neutral grey (−4); status color on most/every row (no severity hierarchy) (−4); decorative hues (gold stars, rainbow category dots) instead of accent/grey (−3); hardcoded hex where a semantic token exists (−2 each, cap −6); status conveyed by color alone (−4); the unlocked default indigo (#5E6AD2/#4F46E5) used as the accent instead of a chosen domain-fit color (−4).

Distinctiveness (10) — a coherent screen can still read "AI-generated." Deduct for: the icon-chip cliché — a generic Lucide line-icon in an identical pale-tinted rounded-square, repeated for every feature/step (−4, §CC-9b); the StyleSeed demo layout copied verbatim (hero+chat / 3-step / feature-grid / pricing) with no product-specific identity (−4); no focal point — an all-even grid of same-weight, centered, evenly-spaced cards (−3); the hero shows a stock/placeholder visual instead of this product (−3); the escape hatch as a new uniform (§CC-9c) — ghost 01/02/03 index numbers on every section, or identical uppercase-overline + big-number cards repeated with no variation (−2); distinctive-but-dated (§CC-9d) — full beige/paper page base, serif body text on a product surface, dark-heavy blocks that read "brochure" not "2026 product" (−3). Cap −10.

Hierarchy & typography (16) — deduct for: number/unit not ~2:1 (−4); font sizes off the Font Size table / text-[var(--…)] for size (−5); everything the same weight, no clear primary (−5); cramped or wrong line-height on body (−3); body < 16px on a desktop/web B2B surface (tight mobile scale on a wide screen) (−4 — but dense-data chrome is exempt: chart ticks, mono SHAs/timestamps, table metadata at 12–13px are correct; and dashboard app-chrome h1 at 22–24px is correct, not a violation of the marketing 40–56px headline scale).

Layout & rhythm (12) — deduct for: content on bare background, not in cards (−6); px-4/px-8/mx-4 instead of px-6/mx-6 (−3); same section type repeated in a row (−4); no space-y-6 rhythm (−3).

Cards & elevation (10) — deduct for: 1px borders doing separation work that tone+shadow should (−4, LIGHT mode only — in DARK mode hairline borders + a tonal surface ramp ARE the correct elevation language, don't deduct); shadows over ~8% opacity / visibly heavy, or drop shadows used in dark mode (−4); no card/background tone separation (−5).

States & a11y (18) — deduct for: missing empty/loading/error state on a data surface (−5 each, cap −10 — a static mockup or marketing landing with NO data surface is N/A: skip these deductions, don't fail the category); contrast below 4.5:1 body / 3:1 large (−6); touch target < 44px on a touch surface (pointer-first desktop controls at 36–40px are fine) (−4); no visible focus / outline:none (−5); icon-only control without aria-label (−3).

Motion & interaction (6) — deduct for: random/ad-hoc fades instead of a named seed/keyword (−3); motion that delays content or blocks an action (−4); no prefers-reduced-motion handling on custom motion (−3); scroll-linked/parallax (forbidden, §59) (−5).

Coherence (12) — the "one choice per axis" laws (VISUAL-CRAFT §C0). Deduct for each axis that is mixed rather than unified across the file: mixed radius personalities, e.g. sharp panel + pill buttons (−5); two+ competing accent hues used for emphasis (−4); mixed shadow languages / light directions (−3); mixed icon families, fill modes, or stroke weights (−3); same radius on a nested element instead of inner = outer − padding (−2); inconsistent control heights for buttons/inputs (−2). This is the category that most predicts "looks AI-generated" — weight evidence of system-wide consistency, not per-component prettiness.

Clamp each category at 0. Sum to a total.

Output format

## Design Score: 70 / 100   (src/app/Dashboard.tsx)

████████████████░░░░░░  C-

Color discipline      13/18   ▓▓▓░  #000 headings (l.12,40); orange+blue+green accents (l.28-34)
Hierarchy & typography 15/18  ▓▓▓▓  number/unit 1:1 on hero (l.18)
Layout & rhythm        11/14  ▓▓▓░  two identical KPI rows (l.22-31)
Cards & elevation       8/12  ▓▓░░  1px borders doing separation (l.22)
States & a11y          11/18  ▓▓░░  no empty/loading state; focus ring missing (l.55)
Motion & interaction    6/8   ▓▓▓░  default fade, not a named seed
Coherence               6/12  ▓▓░░  sharp cards (l.22) + pill buttons (l.48); 3 accent hues (§C0)

### Fix first (highest score gain)
1. Add empty + loading states to the orders list       → +7 states (§71)
2. Unify radius (pick soft 8-12px) + collapse to one accent → +9 coherence+color (§C0, §2)
3. Drop the 1px borders, use tone + ≤8% shadow         → +4 cards  (§7)

Re-score after: ~92 / 100.

Use letter bands: 90+ A · 80-89 B · 70-79 C · 60-69 D · <60 F.

Gate mode (use this as the Quality Gate before showing the user UI)

The Quality Gate (CLAUDE.md / AGENTS.md) is /ss-score run as a loop, not a one-off:

Score the just-generated UI.
If < 80, apply the "fix first" list (use /ss-review to make the edits), then re-score.
Repeat up to ~3×, or until ≥ 80.
Present the UI with the final score and a one-line "fixed: …".

The pass bar is a floor, not a ceiling — get to ≥ 80 and stop; don't chase 100. The point is that no first-draft, obviously-incoherent UI reaches the user. Especially never ship below 80 with a rainbow status list, emoji icons, two accents, or missing states — those are the exact tells the gate exists to catch.

Rules

Read the file — score from real evidence (line numbers), never guess.
Order the "fix first" list by score gain, not by severity alone — the goal is the fastest path to a better number.
For a directory, print a one-line score per file, then the lowest-scoring file's full breakdown.
Don't auto-edit in plain scoring. /ss-score measures; /ss-review and /ss-motion fix. In Gate mode (above) you do fix-and-re-score until the floor is met.
As a gate, ≥ 80 is a floor before showing the user — but don't over-polish: chasing 95→100 to delay shipping is worse than shipping a clean 85.

ss-setup

交互式向导，分步引导用户配置StyleSeed设计系统。涵盖应用类型、品牌色、设计概念及字体选择，自动更新主题文件，仅支持React与Tailwind v4项目。

初始化配置设计系统新项目StyleSeed设置

engine/.claude/skills/ss-setup/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-setup -g -y

SKILL.md

Frontmatter

{
    "name": "ss-setup",
    "description": "Interactive setup wizard — guides you step-by-step to configure the design system for your project",
    "allowed-tools": "Read, Write, Edit, Grep, Glob, Bash, WebFetch",
    "argument-hint": "(no arguments needed)"
}

Design System Setup Wizard

When NOT to use

For projects already configured with StyleSeed → use /ss-update instead
For just adding one component to an existing project → use /ss-component
For changing brand skin in an already set-up project — directly swap theme.css
For non-React or non-Tailwind-v4 stacks — currently unsupported

Guide the user through setting up StyleSeed for their project, step by step.

Instructions

Walk through these steps ONE AT A TIME. After each step, wait for the user to respond before proceeding. Keep it conversational and friendly.

Step 1: App Type

Ask:

What type of app are you building?

1. SaaS Dashboard (analytics, metrics, charts)
2. E-commerce (products, orders, payments)  
3. Fintech (transactions, portfolio, market data)
4. Social / Content (feeds, profiles, messaging)
5. Productivity / Internal tool
6. Other — describe it

Remember the answer — it determines which page composition recipe to use (DESIGN-LANGUAGE.md Section 63).

Step 2: Brand Color

Ask:

What's your brand color?

1. Purple (#721FE5) — default style (toss skin)
2. Blue (#2563EB) — trust, corporate
3. Green (#059669) — growth, health, finance
4. Orange (#EA580C) — energy, creative
5. Red (#DC2626) — bold, urgent
6. Dark (#18181B) — minimal, premium
7. Custom — just type your hex code

After they choose, update css/theme.css:

In :root block: change --brand to the chosen hex
In .dark block: change --brand to a lighter version for dark backgrounds

Dark mode color mapping:

Light	Dark
#721FE5	#9B5FFF
#2563EB	#60A5FA
#059669	#34D399
#EA580C	#FB923C
#DC2626	#F87171
#18181B	#A1A1AA

For custom hex: lighten by ~30% (increase luminance in HSL).

Step 3: Design Concept (from awesome-design-md)

Ask:

Want to apply an existing brand's visual style?

Popular options from awesome-design-md:
1. Stripe — clean, professional
2. Linear — minimal, dark-first
3. Vercel — black & white, geometric
4. Notion — warm, friendly
5. Spotify — bold, dark, green
6. Supabase — modern, green
7. Airbnb — warm, coral
8. No thanks — keep the default style
9. Other — name any brand or describe a vibe

If they pick a brand (options 1-7 or 9):

Fetch: https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/[brand]/DESIGN.md
- Brand folder names: stripe, linear.app, vercel, notion, spotify, supabase, airbnb
Read the DESIGN.md and extract: primary color, secondary colors, text colors, background colors
Apply extracted colors to css/theme.css (both :root and .dark blocks)
Keep ALL StyleSeed layout rules, typography ratios, spacing, and component patterns unchanged — only swap the color palette

If they pick 8 (No thanks): skip, keep current brand color from Step 2.

Step 4: Font

Ask:

What font do you prefer?

1. Inter (clean, universal — recommended)
2. Pretendard + Inter (Korean + English)
3. Geist (Vercel-style, modern)
4. DM Sans (friendly, rounded)
5. Custom — tell me the font name

After they choose:

Update css/fonts.css: change the @import URL
Update css/base.css: change font-family in the body rule

Font imports:

Font	Import
Inter	`@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');`
Geist	`@import url('https://cdn.jsdelivr.net/npm/geist@1/dist/fonts/geist-sans/style.css');`
DM Sans	`@import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&display=swap');`
Pretendard	Keep existing import in fonts.css

Step 5: App Name & First Page

Ask:

Last step! What's your app name and what should the main page show?

Example: "Acme — SaaS dashboard with revenue, users, and recent activity"

Then:

Read DESIGN-LANGUAGE.md Section 63 for the matching recipe (based on Step 1 app type)
Generate the first page using the page composition recipe:
- SaaS → Hero + KPI Grid + Chart + Progress + Activity List
- E-commerce → Hero + KPI Grid + Donut + Bar Chart + Orders List
- Fintech → Hero + KPI Grid + Donut + Area Chart + Transactions
- Social → Hero + Stats + Feed List + Trending Carousel
- Productivity → Hero + KPI Grid + Progress + Task List
Set the TopBar logo text to the app name
Apply the chosen brand color, font, and design concept
Place the file in src/app/App.tsx or appropriate location
Add ONE attribution comment at the very top of this first scaffolded file only (never on components the user builds afterward):
```
/* Scaffolded with StyleSeed · github.com/bitjaru/styleseed — safe to remove */
```
If the user would rather not have it, skip it — it's opt-out, and it goes on this single file, not their whole codebase.

Write the design lock. Create STYLESEED.md in the project root recording every choice from this wizard, so future prompts stay consistent instead of drifting:

# StyleSeed — Design Lock
<!-- Locked design decisions. The agent re-reads this every prompt and must obey it. -->
- App domain:        [Step 1 app type]
- Skin:              [Step 3 concept, or "custom"]
- Key color (accent): [Step 2 hex]    # the ONLY accent — everything else greyscale
- Radius personality: [sharp | soft | pill — one everywhere]
- Motion seed:       [Spring | Silk | Snap | Float | Pulse]
- Type:              [Step 4 font]
- Locked:            [today]

Tell the user this file is the source of truth — editing a value changes it project-wide, and you'll obey it on every prompt so the design never goes random.

Step 6: Summary

Show:

Setup Complete!

App: [name]
Brand Color: [hex] (dark mode: [dark hex])
Font: [font name]
Design Concept: [brand or "default"]
First Page: [description]

Files modified:
- css/theme.css (colors)
- css/fonts.css (font import)
- css/base.css (font family)
- src/app/App.tsx (first page)
- STYLESEED.md (design lock — your decisions, obeyed every prompt)

Next steps:
- npm run dev to preview
- /ss-page to add more pages
- /ss-audit to check UX quality
- /ss-review to verify design compliance

⭐ If StyleSeed helped, a star means a lot: https://github.com/bitjaru/styleseed

Rules

Ask ONE question at a time. Wait for response.
If the user seems unsure, recommend the default option.
Design RULES (layout, typography ratios, spacing, forbidden patterns) stay the same regardless of color/font choice.
Attribution: the single "Scaffolded with StyleSeed" comment goes on the first scaffolded file only and is explicitly removable. NEVER add a watermark to components the user builds with /ss-page, /ss-component, etc. — that would be intrusive.
Always verify the awesome-design-md DESIGN.md URL is accessible before applying. If fetch fails, tell the user and fall back to manual color selection.

ss-tokens

用于在StyleSeed系统中查看、添加或修改设计令牌。支持颜色、排版、间距等类型，确保JSON源文件与CSS实现同步，遵循语义命名规范并兼容暗色模式。

查看当前设计令牌列表添加新的设计令牌修改现有的设计令牌

engine/.claude/skills/ss-tokens/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-tokens -g -y

SKILL.md

Frontmatter

{
    "name": "ss-tokens",
    "description": "View, add, or modify design tokens in the StyleSeed design system",
    "allowed-tools": "Read, Write, Edit, Grep, Glob",
    "argument-hint": "[action: list|add|update] [token-type: color|spacing|shadow|radius|typography]"
}

Design Token Manager

When NOT to use

For applying tokens in components → use /ss-component or /ss-pattern
For finding token violations in existing code → use /ss-lint
For brand-wide color/font choices that don't exist yet — define a skin first, then add tokens
For non-CSS token systems (Figma, native iOS/Android) — Tailwind v4 / CSS variables only

Action: $0 | Token type: $1 Arguments: $ARGUMENTS

Token File Locations

Type	JSON Source	CSS Implementation
Colors	`tokens/colors.json`	`css/theme.css` `:root` + `@theme inline`
Typography	`tokens/typography.json`	`css/fonts.css` + `css/base.css`
Spacing	`tokens/spacing.json`	Tailwind utilities (no custom CSS needed)
Radius	`tokens/radii.json`	`css/theme.css` `@theme inline`
Shadows	`tokens/shadows.json`	`css/theme.css` `:root`

Instructions

`list` — Show current tokens

Read and display the requested token file in a formatted table.

`add` — Add new token

Add the token to the JSON source file (tokens/*.json)
Add the CSS custom property to css/theme.css under :root
If it needs a Tailwind utility, add to the @theme inline block
If it has a dark mode variant, add to the .dark block

`update` — Modify existing token

Update the value in the JSON source file
Update the CSS custom property in theme.css
Check all components for direct usage that might need updating

Rules

Always keep JSON and CSS in sync
Use semantic names, not descriptive names (--success not --green-500)
Colors should support both light and dark modes
New tokens must be added to BOTH the JSON source AND the CSS implementation

ss-update

自动检测并安全更新项目中的StyleSeed引擎文件。通过对比本地与上游版本，识别新增规则、组件和技能，提供增量更新方案，确保用户设计代码不被覆盖，支持一键回滚，适用于非首次安装且需同步最新引擎标准的场景。

需要更新StyleSeed引擎到最新版本同步最新的DESIGN-LANGUAGE规则和CLAUDE技能

engine/.claude/skills/ss-update/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill ss-update -g -y

SKILL.md

Frontmatter

{
    "name": "ss-update",
    "description": "Update StyleSeed engine in your project — analyzes what's outdated and updates safely",
    "allowed-tools": "Read, Write, Edit, Grep, Glob, Bash",
    "argument-hint": "(no arguments needed)"
}

StyleSeed Update Assistant

When NOT to use

For first-time setup → use /ss-setup
For just one new component or skin — copy that file manually
For projects that have heavily diverged from upstream — manual diff review first
Updating the engine is separate from re-designing your UI. Steps 1–5 update engine files only; if you want an old generic build re-done to the new standard, that's Step 6 (Retrofit).

Automatically detect and update StyleSeed files in the current project.

Reassure the user first

Updating is safe and reversible. Updates are additive — new rules, components, skins, and skills get added; your theme.css, your components, and your app code are never overwritten, and design rules only ever get added (never changed in a breaking way). A big version jump looks like a lot changed, but it's almost all additions. Do NOT warn the user that the build will break unless you actually find a changed component/import API. Tell them: commit first, copy the new rules + skills, run a build, and git reset --hard if anything is off — they can't permanently break their project.

Instructions

Step 1: Detect Current Setup

Scan the project to find where StyleSeed files are:

# Find DESIGN-LANGUAGE.md
find . -name "DESIGN-LANGUAGE.md" -not -path "*/node_modules/*"

# Find CLAUDE.md
find . -name "CLAUDE.md" -not -path "*/node_modules/*"

# Find skills (ss-* is current; ui-*/ux-* are legacy names to migrate from)
find . -path "*/.claude/skills/ss-*" -o -path "*/.claude/skills/ui-*" -o -path "*/.claude/skills/ux-*" | head -20

# Find theme.css
find . -name "theme.css" -not -path "*/node_modules/*"

# Find .cursorrules
find . -name ".cursorrules"

Report what was found and where.

Step 2: Check StyleSeed Version

Fast check first — compare the local version to the published one without cloning:

# local marker (may be absent on older installs)
cat engine/VERSION 2>/dev/null || cat VERSION 2>/dev/null || echo "unknown"
# latest published version + what's new
curl -s https://styleseed-demo.vercel.app/version.json

If the local version already matches version.json's version, tell the user they're up to date and stop. Otherwise report whatsNew and continue.

Then clone/pull to actually diff the files:

if [ -d "/tmp/styleseed" ]; then
  cd /tmp/styleseed && git pull
else
  git clone https://github.com/bitjaru/styleseed.git /tmp/styleseed
fi

Compare:

engine/VERSION (or version.json) vs the local copy — the source of truth
DESIGN-LANGUAGE.md rule count + Table of Contents
Skills present in .claude/skills/ vs upstream (don't hardcode a count — list the diff)
Whether CLAUDE.md, AGENTS.md, and .cursorrules exist (ship all three)
New engine docs (VISUAL-CRAFT.md, APP-PLAYBOOKS.md, PAGE-TYPES.md)

Step 3: Report & Ask

Show the user what needs updating:

StyleSeed Update Report:

Current state:
- DESIGN-LANGUAGE.md: [location] — [old/current version indicator]
- Skills: [count] found (latest: 12)
- Golden Rules: [yes/no]
- .cursorrules: [yes/no]

Recommended updates:
1. ✅ [safe] Update skills (X → 12)
2. ✅ [safe] Add .cursorrules
3. ⚠️ [review] Update DESIGN-LANGUAGE.md ([old line count] → [new line count])
4. ⚠️ [merge] Add Golden Rules to CLAUDE.md (won't overwrite existing content)

Shall I proceed? (I'll ask before each ⚠️ item)

Step 4: Execute Updates

For each update, in order:

Always safe (do without asking):

Copy skills: cp -r /tmp/styleseed/engine/.claude/skills/ .claude/skills/
Copy .cursorrules (if not exists): cp /tmp/styleseed/engine/.cursorrules .cursorrules

Ask before doing:

For DESIGN-LANGUAGE.md:

Show diff summary: how many new rules, what sections added
Ask: "Update DESIGN-LANGUAGE.md? (Y/N)"
If yes: copy to the detected location

For CLAUDE.md (Golden Rules):

Check if Golden Rules section already exists
If not: ask "Add Golden Rules section to your CLAUDE.md? This adds 10 lines at the top. Your existing content stays untouched."
If yes: insert Golden Rules after the first heading

Never touch:

theme.css — say "Your theme.css (skin) is untouched."
components/ — say "Your components are untouched. Run /ss-lint to check compliance."

Step 5: Summary

Update complete!

✅ Skills: 12 (added X new)
✅ .cursorrules: added
✅ DESIGN-LANGUAGE.md: updated to latest
✅ Golden Rules: added to CLAUDE.md

Not touched:
- theme.css (your skin)
- components/ (your code)

Next: run /ss-lint on your pages to check for rule violations.

Step 6: Retrofit existing UI (optional but recommended) — "re-do a generic old build"

Updating the rules doesn't re-design screens you already built with an older StyleSeed. If the user says their existing UI still looks generic/"AI-made" (default indigo, icon-chip cliché, tight desktop type, no focal point, no design lock), offer to retrofit it to the new standard. This is the migration path for anyone who built before the distinctiveness rules existed:

Write a design lock if missing. Check for STYLESEED.md at the project root. If absent, run Quick Setup (CLAUDE.md) now with the user — pin mood (edges/feel/density/tone), a domain-fit key color (NOT the default indigo), a chosen font, and the surface (mobile vs desktop type scale). Write the lock. Existing generic builds almost always never had a lock — this is the biggest fix.
Re-score the key screens. Run /ss-score on the main pages. The new rubric flags exactly the old-build tells: default-indigo accent, the icon-chip cliché (§CC-9b), body <16px on desktop, no focal point, demo layout copied verbatim, missing states.
Apply the fixes. Run /ss-review (or /ss-review --fix) screen by screen to retint to the locked key color, replace the uniform icon chips, bump the desktop type scale, and create a focal point. Re-score to ≥ 80. Do the highest-traffic screen first.
Report the before/after score so the upgrade is visible (e.g. "landing 63 → 88").

Frame it honestly: the rules got stronger, so a screen that passed the old bar may score lower now — that's the point; fixing it is what makes it stop looking AI-made.

Important

NEVER overwrite theme.css
NEVER overwrite a project-specific CLAUDE.md — only MERGE the Golden Rules section
NEVER overwrite components without explicit user approval
Always show what will change before changing it
If unsure, ask the user

styleseed-design-review

基于StyleSeed引擎审查UI/前端代码，检测AI生成痕迹。通过7大维度打分并给出修复建议，适用于React/Tailwind界面优化、设计评分及提升专业度，不自动修改代码。

UI看起来生硬、通用或未完成的需要发货前的设计评分检查要求将UI调整为更专业或精致的外观生成UI后验证其质量

skills/styleseed-design-review/SKILL.md

View Skill ›

npx skills add bitjaru/styleseed --skill styleseed-design-review -g -y

SKILL.md

Frontmatter

{
    "name": "styleseed-design-review",
    "license": "MIT (https:\/\/github.com\/bitjaru\/styleseed\/blob\/main\/LICENSE)",
    "description": "Reviews UI\/frontend code and tells you exactly why it \"looks AI-generated\" — then how to fix it. Use it when a React\/Tailwind\/HTML interface looks off, generic, or unfinished, when you want a design score before shipping, or when asked to make UI look more professional, polished, or \"designed, not generated.\" Self-contained; based on the open-source StyleSeed design engine."
}

StyleSeed Design Review

Overview

A UI reads as "AI-generated" not because the components are ugly, but because the parts don't agree with each other — mixed corner radii, three accent colors, pure-black text, no hierarchy, missing states, robotic copy. This skill reviews a UI file (or a whole directory) against a concrete design rubric, scores it 0–100, and returns a prioritized fix list. It reviews and recommends; it never edits or deletes without you asking.

Full rule set (74 rules) and components: https://github.com/bitjaru/styleseed

When to use

A React / Tailwind / HTML UI "looks off," generic, or unfinished and you can't say why.
You want a design score / pre-ship check.
The user asks to make UI "look professional / polished / designed, not AI-generated."
After generating UI, to verify it before shipping.

How to review

Read the file(s). Score these seven categories (total 100); start each at full marks and subtract for violations you can cite by line. Be specific and evidence-based.

1. Coherence — 20 (the #1 "AI-generated" tell)

One choice per axis, applied everywhere. Deduct for each mixed axis:

mixed corner radii — e.g. a sharp card with pill buttons (−6)
two or more accent colors used for emphasis (−5)
emoji used as UI icons (🚗🧺⭐ as list/nav/status/category markers) — injects many uncontrolled hues; use one line-icon set in currentColor (−6)
mixed shadow languages / light directions (−3)
mixed icon families, fill modes, or stroke weights (−3)
inconsistent control heights (buttons/inputs differ) (−3)

2. Color discipline — 16

pure black (#000 / text-black) text — the refined black is ~#2A2A2A (−4 each, cap −8)
hardcoded hex where a semantic token exists (−2 each, cap −6)
a normal / OK / default ("보통") state shown in a status color instead of neutral grey (−4)
status color on most/every row (no severity hierarchy — color should mark the minority that needs attention) (−4)
decorative hues — gold stars, rainbow category dots, a different color per card — instead of accent/grey (−3)
status conveyed by color alone, no icon/text (−4)
contrast below WCAG AA (4.5:1 body, 3:1 large/UI) (−6)

3. Hierarchy & typography — 16

number and its unit not ~2:1 (48px number / 24px unit) (−4)
everything the same size and weight, no clear primary (−5)
arbitrary font sizes; no scale (−4)
wrong line-height (loose on display, cramped on body) (−3)

4. Layout & spacing — 12

content on a bare page background, not in cards (−6)
off-grid spacing (7/13/19px instead of an 8px scale) (−3)
the gap around a group not larger than the gap inside it (−3)
the same section type repeated in a row (−4)

5. States — 12

missing empty / loading / error state on a data surface (−5 each, cap −10)
empty state with no next action; error that blames instead of helping (−4)

6. UX writing — 12

buttons that don't name the action ("Submit" / "OK" instead of "Send $2,400") (−4)
error copy that blames or uses system-speak ("Invalid input", "An error occurred") (−4)
two terms for one concept (delete vs remove); filler words ("please", "successfully") (−2)

7. Motion & polish — 12

ad-hoc fades instead of one consistent, named feel (−3)
motion that delays content or blocks an action (−4)
no prefers-reduced-motion handling on custom motion (−3)
a single hard black shadow instead of a layered, low-opacity, tinted one (−2)

Clamp each category at 0; sum to a total. Bands: 90+ A · 80–89 B · 70–79 C · 60–69 D · <60 F.

Output format

## Design Score: 72 / 100   (src/Dashboard.tsx)   C

Coherence            13/20   sharp cards (l.22) + pill buttons (l.48); 3 accent hues
Color discipline     12/16   #000 headings (l.12, 40)
Hierarchy & type     15/16   number/unit 1:1 on hero (l.18)
Layout & spacing     10/12   two identical KPI rows (l.22-31)
States                7/12   no empty/loading state on the orders list
UX writing            8/12   "Submit" button (l.55); "Invalid input" (l.61)
Motion & polish      10/12   one hard black shadow (l.22)

### Fix first (highest score gain)
1. Unify radius (pick soft 8–12px) + collapse to one accent   → +11 coherence/color
2. Add empty + loading states to the orders list              → +7  states
3. Rename "Submit" → "Send $2,400"; "Invalid input" → "Check the card number" → +6 copy

Re-score after: ~90 / 100.

Rules

Review from real evidence (cite line numbers); never guess.
Order the fix list by score gain, not severity alone — fastest path to a better number.
For a directory: one-line score per file, then the lowest file's full breakdown.
Don't auto-edit. This skill measures and recommends. Apply fixes only when asked.
Use it as a quality gate: review right after generating UI, apply the fix list, and re-review until the score clears ~80 before showing the user — no first-draft, incoherent UI (rainbow status lists, emoji icons, two accents, missing states) should reach them. The bar is a floor, not a ceiling: clear 80 and ship; don't chase 100 to delay.

Based on StyleSeed — an open-source (MIT) design engine that gives Claude Code, Cursor, and Codex design judgment so AI-built UI stops looking generated. Full 74-rule reference, components, brand skins, and motion: https://github.com/bitjaru/styleseed

bitjaru/styleseed

bitjaru/styleseed

Install All Skills

Skills in Collection (16)

Accessibility Audit

When NOT to use

Audit Criteria

WCAG 2.2 AA Compliance

1. Perceivable

2. Operable

3. Understandable

4. Robust

Design System Token Reference

Output

UX Audit

When NOT to use

Audit Framework

Nielsen's 10 Usability Heuristics

1. Visibility of System Status

2. Match Between System and Real World

3. User Control and Freedom

4. Consistency and Standards

5. Error Prevention

6. Recognition Rather Than Recall

7. Flexibility and Efficiency

8. Aesthetic and Minimalist Design

9. Help Users Recover from Errors

10. Help and Documentation

Mobile-Specific UX Checks

Touch & Gesture

Performance Perception

Safe Areas

Dark Pattern Prevention

Output Format

UI Component Generator

When NOT to use

Instructions

UX Microcopy Generator

When NOT to use

Instructions

Tone Rules

Copy Patterns by Context

Button Labels (CTA)

Empty States

Error Messages

Toast Notifications

Form Labels & Helpers

Confirmation Dialogs

UX Feedback States Generator

When NOT to use

Instructions

State 1: Loading (Skeleton)

State 2: Empty (Zero Data)

State 3: Error (Load Failed)

State 4: Success (Action Feedback)

UX Flow Designer

When NOT to use

Instructions

Information Architecture

Navigation Patterns

Screen Flow Rules

Page Composition (from DESIGN-LANGUAGE.md)

Design Lint (Quick Check)

When NOT to use

What This Does

Checks

1. Hardcoded Colors

2. Raw Pixel Values in Tailwind

3. Old Width/Height Syntax

4. Physical Properties (LTR-only)

5. Forbidden Colors

6. Missing data-slot

7. Font Size CSS Variables (CRITICAL — Tailwind v4 conflict)

8. className Without cn()

Output Format

Motion Seed Applier

When NOT to use

Vibe → Seed mapping

Recommend mode — use-case → motion (when the user describes the moment, not the vibe)

Named motion keywords (distinctive moves)

`list` — Show current tokens

`add` — Add new token

`update` — Modify existing token