StyleSeed

StyleSeed

Make expert design judgment
repeatable by coding agents.

_{StyleSeed turns recorded design decisions into project-local rules and implementation workflows. Support experts, not replace them with a collection of tastes. Open source, for Claude Code · Codex · Cursor.}

Same product. Same prompt. Only the rules changed.

Measured on 120 rendered benchmark cells: the enforced gate improved both Codex and Claude Code by +5.3 points. Raw rules alone were inconsistent (Codex +1.6, Claude Code −3.7), which is why StyleSeed ships a render → score → revise loop—not a prompt dump. Read BENCH-V1 and inspect the raw evidence →

Easy Start (30 seconds)

Our goal is repeatable application of expert judgment, not a claim of expert-level output today. The engine compiles selected rules, preserves project choices, and supports code and rendered checks. A score does not replace human design acceptance. Product principles · Quality-first roadmap

1. Open a terminal in your project folder and run this command. Requires Node.js/npm.

Already installed? Update and consolidate your existing skill list. One request covers the same install scope, verified backup, and revision checks.

npx -y skills add bitjaru/styleseed -a codex claude-code -y --copy

Installs the core skills for Codex and Claude Code together, with no agent, skill, or install-mode menus. It copies the skills into this project. It does not install globally or change other projects.

2. Send one message to your agent. Start a fresh session if the skills do not appear.

• Codex: $styleseed Help improve this screen. Preserve our existing design choices and show me what needs a decision.
• Claude Code: /styleseed Help improve this screen. Preserve our existing design choices and show me what needs a decision.

Only styleseed is registered. It selects the needed internal workflow from your request. Choose unresolved design decisions together, then inspect the actual rendered result.

Claude Code guide · Codex guide · See examples · Need help?

Evaluating the repository?

Use the three-minute verification path to test a clean public install before trusting the README. The source-level evaluator quickstart then connects that install to the published release manifest, Windows PowerShell evidence, CI, SBOM, benchmark boundary, and production build.

Want a first PR? Fix a doc, add a regression fixture, improve a skin, or claim a good first issue. Small docs and test fixes need no proposal. See the 15-minute contribution path.

For a fixed evaluation version, use the v5.0.0 release archive and its checksums. The default bitjaru/styleseed command follows mutable main.

Upgrading an existing 23-skill install

Reinstall through the same channel. Then ask StyleSeed, consolidate my old skill entries. The update workflow verifies the new unified payload and archives only unmodified old ss-* directories outside skill discovery; modified copies remain for review. Restart the agent session. Use $styleseed build / /styleseed build instead of the former $ss-build / /ss-build registrations. All 22 workflows remain bundled; selecting only styleseed is now sufficient.

What the current rules check

StyleSeed ships 74 craft rules and a 0–100 scored gate that tells an installed agent to revise screens below 80 before presentation. Checks must be interpreted through the selected grammar and project contract, not as universal taste. The workflow must actually be invoked; a markdown file alone cannot block delivery, and 80 points is not expert approval.

_{Banning the defaults isn't enough — agents converge on new uniforms once the old ones are blocked. That's why the rules come with an enforced score-then-fix loop, not a checklist. What happens after install ↓}

One component. Three token skins. Same chat UI morphing across Toss · Raycast · Arc-inspired token sets. A skin changes color and type material; a StyleSeed brand recipe changes the actual geometry, containment, controls, collections, density, and motion.

_{Skins are inspired-by token sets, not recreations. Compare the nine structural recipes →}

 

Expert decisions become repeatable instructions — not one universal aesthetic.

Judgment with implementation context — decisions, applicability, and evidence, not just palettes  ·  Right grammar for the result — consumer service, operations, technical, editorial, commerce, institutional, marketing, or sequential story  ·  Real morphology choices — nine brand recipes change structure and component selection, not just palette  ·  Generative palette engine — any key color becomes OKLCH ramps, context-fit surfaces, a scored companion, semantic roles, contrast evidence, CSS tokens, and media anchors; eight recipes remain maintained product postures  ·  Studio pipeline — three directions, human selection, interaction scenes, image/video jobs, working prototype, and a prototype-first reel  ·  References become rules — /styleseed reference compiles screenshots, URLs, Figma, or an existing UI into an evidence-backed project grammar  ·  Only the context you need — /styleseed resolve compiles the chosen method into a small, hash-verifiable project bundle  ·  Beyond web UI — adapters for product UI, social carousels, decks, documents, and graphics  ·  Fights the AI tells — the default indigo, the icon-chip cliché, template layouts, rainbow lists  ·  Auxiliary proof gates — code score + rendered pixel verification before you see it  ·  Every agent — ships CLAUDE.md + AGENTS.md + .cursorrules  ·  A design lock that stops drift  ·  Free & MIT

_{Core judgment × output grammar × surface adapter × domain/page × brand recipe × palette recipe × optional profile. Read the architecture →}

_{Full pages: before · after · more before/afters →}

_{🔥 We ran an early version of this page through our own gate. It scored 58/100 → here's the receipt}

_{Same product, six looks — each one /styleseed restyle <preset> away. Coherent, distinct, never generic.}

Easy Start · Studio · Palettes · Claude Code UI guide · Codex UI guide · Brand recipes · Architecture · Engine + Recipes + Skins · Motion · Skills · Wiki · 한국어

What happens after Easy Start

Why the prompt installs first: the context compiler and quality gates can only run when the skills are installed. Installing turns STYLESEED.md into a small source-hashed rule bundle, then actually scores and fixes the result before you see it. Without installation, llms.txt still tells any agent how StyleSeed is structured and where its machine-readable catalog lives, but compilation and gates become a weaker manual path. Works with Claude Code (CLAUDE.md), Codex / Amp / Gemini CLI (AGENTS.md), and Cursor (.cursorrules) — StyleSeed ships all three. (Planning first is what keeps the result from looking random — see Troubleshooting.)

What your agent actually does with StyleSeed loaded:

you    ▸  build me a billing settings page
agent  ▸  (plan mode) key color? for billing I'd go deep teal — #0F766E, mood: sharp · calm ·
          trustworthy (not the default indigo). Motion: Snap. ok?  ▸ y
agent  ▸  ✓ wrote STYLESEED.md — skin, accent, font, radius, motion locked for project-scoped visual work
agent  ▸  building… running the quality gate before I show you anything
gate   ▸  ✗ two accent colors   ✗ "normal" rows colored   ✗ no empty state   → fixing
agent  ▸  ✓ 88/100 — one accent, grey normal states, real empty/error states. here's the page.

The STYLESEED.md lock is the anti-drift mechanic. Your skin, key color, radius, and motion get written once. Installed project instructions and StyleSeed skills re-read it for visual work, so those decisions can survive new screens and sessions. When the build workflow runs, the Quality Gate reviews and fixes the UI (rainbow lists, two accents, missing states) before presentation — and it can retrofit an old generic build too.

The method stays open and portable. The sources are plain markdown; installation adds the deterministic context compiler, manifest, and executable gates. If installation is unavailable, llms.txt gives any agent the portable routing contract, but it cannot provide the same reproducible local compile by itself.

Want the single StyleSeed skill too (the styleseed router plus 22 ss-* workflows for Studio, context resolution, setup, build, review, score, and verification)?

npx -y skills add bitjaru/styleseed -a codex claude-code -y --copy

Installs one self-contained StyleSeed skill into Codex and Claude Code in this project. For other agents, use the interactive command in Easy Start. Then run /styleseed setup → /styleseed resolve in Claude Code or $styleseed setup → $styleseed resolve in Codex (you can also choose StyleSeed from Codex's /skills picker). The resolver writes a targeted .styleseed/effective-rules.md bundle plus a source-hash manifest, so the agent does not need the 220KB full handbook for every task. Your agent may ask you to approve tools on first use. No install possible? Read llms.txt for the portable routing contract.

claude plugin marketplace add bitjaru/styleseed
claude plugin install styleseed@styleseed

Your agent, its exact path:

_{More paths (manual copy, Cursor, awesome-design-md brands) in Install by hand below.}

Who is this for?

• You asked Claude Code or Cursor to build a dashboard and it came out amateur-looking
• You're vibe coding a SaaS app and don't want to hire a designer
• You use shadcn/ui but the output still feels generic
• You want Toss-like consumer refinement only where that grammar fits, not on every output
• You make social carousels, decks, reports, covers, or other vibe-coded visual artifacts
• You have references and want their repeatable design language extracted instead of cloned
• You're building a Claude Code skill or Cursor rules setup for design
• You ship fast with AI and need professional UI that doesn't look AI-generated

Spacing feels wrong? Inspect the live 64px → 12px CSS inheritance repair, then try the prompt on your own screen. This is a synthetic regression example, not a customer outcome or an optimal-spacing claim.

Where StyleSeed fits among design-AI skills

There are lots of "help your AI design" projects now. Most solve a slice. StyleSeed is the one that targets the whole "looks AI-generated" problem — and enforces the fix.

They're not all competitors — a DESIGN.md gives StyleSeed a skin; a generator gives it a first draft. StyleSeed is the judgment + enforcement layer the others don't have.

What it actually enforces (a taste)

The kind of specific, named calls a senior designer makes without thinking — written down so an AI applies them every time:

• The refined black is #2A2A2A, not #000 — a 5-step grayscale ramp, never pure black
• One accent, everything else greyscale — the single-accent law; a second hue is the fastest "un-designed" tell
• Numbers 2:1 with their unit — a 48px value over a 24px unit; equal sizes flatten magnitude into noise
• Nested-radius law: inner = outer − padding — concentric corners, so a card and its inner button agree
• Layered, low-opacity shadows (≤8%) lit from one direction — not one hard drop shadow
• Tabular numbers for anything that updates — no width jitter as values change
• Status color = severity only — a "normal" row is grey; color marks the exception, never a rainbow list
• No emoji icons, and no Lucide-in-a-pale-chip on every card (§CC-9b) — the two opposite AI icon tells
• 8px spatial grid; gap-around-a-group > gap-inside it — proximity that reads as structure
• Optical, not pixel, alignment — nudge arrows/play glyphs; center type by cap-height
• Desktop body ≥16px, one focal point per screen — the tight mobile scale and an all-even grid both read "machine-made"
• One radius personality · one icon set · one shadow language — the coherence laws (§C0), the #1 fix for "looks AI-generated"
• Motion scoped by surface — a dashboard stays calm; a landing page gets the Cinematic tier (scroll-linked reveals, 3D hero, animated gradients — the Stripe/Linear playbook). Scroll-jacking is still banned everywhere (§43)

See all 74 rules → · the craft & coherence laws →

Data vs Judgment

Tokens and components are necessary, but they do not explain every design decision. Agents also need to know when a pattern applies, why it fits the task, which choices are approved, and how to handle exceptions. Expert judgment and implementation material need to travel together.

StyleSeed's goal is to make that judgment repeatable while leaving intent, tradeoffs, and acceptance with people. The current engine is a starting point; component-context experiments and independent human evaluation are the next steps, not completed capabilities.

See the before/after → — the same dashboard brief, generated generically vs. with the 74 rules applied. Every fix annotated with the rule behind it.

StyleSeed is a design-method engine — 74 craft rules, 8 output grammars, 5 surface adapters, 48 components, a reference compiler, a named motion system, and one agent skill with 22 internal workflows:

"Use the approved semantic roles rather than inventing component-local colors."
"Select grouping and density for the task, not for a favorite template."
"Preserve the project's type and surface system across screens."
"Loading, empty, error, and recovery states are part of the implementation."
"Record unsupported choices instead of silently changing the design system."

StyleSeed organizes maintained guidance by grammar, adapter, domain, and project choices, then compiles the selected context for the agent. Defaults are not universal expert decisions: unsupported project choices need an explicit review, not a silent palette or component swap.

    
Same engine, different token skins. Examples, not proof that expert review is unnecessary.

See full page

    

Works with Claude Design

Claude Design generates UI fast — but it still picks #000 for text, reaches for six accent colors, and floats cards with no background separation. The missing piece isn't more templates. It's the 74 rules that tell the model when to use which pattern and why.

StyleSeed + Claude Design together:

1. Claude Design generates the layout and components (fast scaffolding)
2. StyleSeed's 74 rules refine the output (design judgment layer)
3. Brand skins make it look like your brand, not like "AI made this"

Drop DESIGN-LANGUAGE.md into your Claude Design workflow and the same model produces noticeably more refined output — without changing a single prompt.

"Why not just use the official frontend-design skill?"

Use both — they solve different halves of the problem. Anthropic's official frontend-design skill scaffolds a clean screen fast, and it's a great starting point. StyleSeed is the layer on top:

Official gets you coherent. StyleSeed keeps you from looking templated. Run the official skill to scaffold, then let StyleSeed's gate refine and enforce.

Install by hand

The fastest path is the single-command install above. To wire StyleSeed into an existing project manually, use one of the options below.

New to this? Read top to bottom — every step matters. The most common mistake is expecting setup to work before the skill is installed. Claude Code scans .claude/skills/; Codex scans .agents/skills/. Windows users can follow the copy-pasteable PowerShell verification path. Reviewers can run the end-to-end evaluator quickstart.

Option 1: Interactive Setup (Recommended)

Step 1 — Install the skills. For Codex and Claude Code together:

npx -y skills add bitjaru/styleseed -a codex claude-code -y --copy

For a manual project-local install, clone StyleSeed and copy the canonical skill folders into the path your agent scans:

git clone https://github.com/bitjaru/styleseed.git /tmp/styleseed

# Claude Code
mkdir -p .claude/skills
cp -r /tmp/styleseed/engine/.claude/skills/* .claude/skills/

# Codex (repository-scoped skills)
mkdir -p .agents/skills
cp -r /tmp/styleseed/engine/.claude/skills/* .agents/skills/

Step 2 — Start a fresh agent session, open your project, and invoke setup:

Claude Code: /styleseed setup
Codex:       $styleseed setup   # or open /skills and choose styleseed

The wizard then walks you through:

1. Product job, surface, and output grammar
2. One of nine brand recipes for morphology (enterprise-workbench, public-service, etc.)
3. Brand color or a custom/built-in token skin
4. Font, density, motion, and one signature move
5. A compiled rule bundle, first build, score, and rendered verification

Don't see the skills? For Claude Code, check .claude/skills/ and use the /styleseed command. For Codex, check .agents/skills/, open /skills, or invoke $styleseed setup. Start a new session after installing if discovery looks stale.

Option 2: Manual Setup

Already did step 1 above? These commands copy the rest of the engine into a typical src/-based React project. The source folder is engine/ (replace /tmp/styleseed with wherever you cloned it):

# Design reference + AI guide
mkdir -p .claude
cp /tmp/styleseed/engine/DESIGN-LANGUAGE.md .claude/DESIGN-LANGUAGE.md
cp /tmp/styleseed/engine/CLAUDE.md          ./CLAUDE.md

# Styles and components
mkdir -p src/styles src/components
cp -r /tmp/styleseed/engine/css/*        src/styles/
cp -r /tmp/styleseed/engine/components/*  src/components/

# Pick a skin — copy its theme.css alongside the other css files
cp /tmp/styleseed/skins/stripe/theme.css src/styles/theme.css

Option 3: Just give AI the URL

Refer to https://github.com/bitjaru/styleseed — read engine/CLAUDE.md 
and engine/DESIGN-LANGUAGE.md, then build a SaaS dashboard.
Use skins/stripe/theme.css for the color palette.

Option 4: Cursor

cp engine/.cursorrules your-project/.cursorrules

_{The core workflows share resolver and verification tools. Keep the core package together; use the router to choose which workflow to invoke.}

Troubleshooting — "I applied StyleSeed but the UI still looks bad"

For installation, configuration, or stale-evidence problems, first run the read-only project doctor. It separates a healthy installation and current compiled rules from missing or invalid evidence; it does not claim that a screen looks good.

The honest reason: consistency comes from constraints. If you used a bare "apply StyleSeed" prompt (without the plan-mode + key-color + quality-gate steps the prompt above includes), the agent reads a summary once and improvises — so colors land at random and there's no key color. The reference demo (styleseed-demo.vercel.app) came out polished because it was built with the full rules in context and iterated with /styleseed review — not one-shot. Recreate those conditions:

1. Plan first. In Claude Code press Shift+Tab to enter Plan Mode, then decide the design one step at a time, with full context, before any code is written. This is the single biggest fix.
2. Select the output grammar, adapter, and primary action color. Additional hues need stable semantic, categorical, editorial, or brand roles. No role = random color drift.
3. Compile only the selected rules: run /styleseed resolve or $styleseed resolve, then make the agent read .styleseed/effective-rules.md. The manifest pins selections and hashes. Use llms-full.txt only to debug an unresolved source ambiguity.
4. Lock the decisions in a file. Run /styleseed setup (or just ask the agent to "write a STYLESEED.md design lock"). It records your skin, key color, radius, and motion in STYLESEED.md at the repo root. Install the provider's project entry (CLAUDE.md, AGENTS.md, or .cursorrules) or invoke the installed StyleSeed skill so visual tasks actually read the lock. This is the single strongest fix for inconsistency.
5. Be specific: "Build a dashboard in the Linear skin, one blue accent, Snap motion, following StyleSeed's rules" beats "build a dashboard."
6. Check & iterate. Run /styleseed review or /styleseed score, or tell it: "self-check the effective grammar — coherent geometry, stable color roles, real empty/loading/error states — and fix violations." If it drifts: "re-read CLAUDE.md and fix the coherence violations."

More constraints = less variance. Plan mode + a pinned key color + installed rules + a review pass is the difference between "looks generated" and "looks designed."

Already built something generic? Retrofit it

StyleSeed isn't only for new screens — it's the design counterpart to a code review for UI you already shipped. If an earlier build looks coherent but generic (default indigo, tiny desktop text, the same Lucide-icon-in-a-pale-chip on every card, no focal point):

1. /styleseed score src/… — grades the screen 0–100 and names the exact "AI-made" tells (default accent, icon-chip cliché, sub-16px body on desktop, no focal point, missing states).
2. /styleseed review src/… — the design code-review: applies the fixes (retint to your key color, drop the chips, bump the type scale, create a focal point), then re-score to ≥80.
3. /styleseed update → Retrofit — no design lock yet? It writes a STYLESEED.md (mood, key color, font, surface) so the whole project stops drifting, then upgrades screen by screen.

The rules got stronger in v2.5.0, 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.

How It Works: Engine + Recipes + Skins

┌─────────────────────────────────────────────────┐
│  StyleSeed Engine (brand-agnostic)              │
│                                                 │
│  74 rules · 8 grammars · 5 adapters · 1 skill │
│  Layout · Composition · Typography · UX · A11y  │
└──────────────────────┬──────────────────────────┘
                       │
             Pick a recipe ↓
                       │
  calm · native · enterprise · developer · commerce
  public service · creative · editorial · expressive
                       │
               Apply a skin ↓
                       │
    ┌──────┬──────┬──────┬──────┬──────┬─────────┐
    │ Toss │Stripe│Linear│Vercel│Notion│ 58 more │
    │      │      │      │      │      │(awesome)│
    └──────┴──────┴──────┴──────┴──────┴─────────┘

Engine = how the artifact is judged (design intelligence)

• 74 visual design rules (layout, composition, rhythm, forbidden patterns)
• 48 React components (32 primitives + 16 patterns)
• A named motion system (5 seeds + a copy-paste keyword library)
• 22 internal workflows (Studio, context compiler, reference compiler, setup, UI, motion, UX, accessibility, and accessibility; learning is a separate extension)
• 8 maintained semantic palette recipes, with validated project overrides

Brand recipe = how the artifact is shaped (morphology)

• 9 maintained choices in BRAND-RECIPES.md
• Changes containment, radius/border/elevation, navigation, controls, collections, density, responsive behavior, and motion
• Carries source lineage without official logos, assets, fonts, copy, or trademarked arrangements

Palette recipe = how color roles relate (semantic hierarchy)

• 8 maintained choices in PALETTE-RECIPES.md
• Binds canvas, surface, navigation chrome, text, action, status, focus, and generated-media anchors
• Every required text/action/focus pair passes deterministic contrast validation

Skin = semantic color and type material (visual identity)

• Just a theme.css file with color variables
• 7 built-in skins: Toss, Stripe, Linear, Notion, Raycast, Arc, Vercel
• 58+ more available from awesome-design-md
• Or create your own (change --brand and you're done)

Data repos (awesome-design-md) = paint colors. StyleSeed = the rulebook for where to put the paint. Use them together: they provide the skin, StyleSeed provides the brain. (Full comparison in Where StyleSeed fits.)

Named Motion System

Flashy, named, copy-paste moves — live at /motion

Most AI-generated motion is the same default fade. StyleSeed gives motion a vocabulary — so you (and the LLM) can name a feel and get consistent, intentional animation across every page. Two layers:

1. Seeds = personality. Five named presets, each a spreadable framer-motion recipe in five contexts (entrance / exit / hover / press / layout):

import { spring } from "@engine/motion";

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

2. Keywords = distinctive moves. A library of copy-paste named motions behind one handle — toggle-flip, toggle-curtain, reveal-blur, pop-in, tilt-3d, magnetic, glow-pulse, confetti-pop, shimmer, and more. Say the keyword while vibe coding (or run /styleseed motion toggle-flip) and the same recipe lands in your code.

▶ Preview & copy every motion at the live gallery →  ·  Vibe-code your own → the motion guide

3. Motion is scoped by surface — calm apps, cinematic landing pages. This is the part most rule-sets get wrong: they ban scroll animation everywhere (so your marketing page ends up flat), or allow it everywhere (so your dashboard scroll-jacks). StyleSeed splits it:

The line StyleSeed draws: scroll-linked (native scroll drives it, you stay in control) is encouraged on brand pages; scroll-jacking (hijacking scroll speed, trapping you) is banned everywhere. The Cinematic tier keeps its guardrails — 60fps (transform/opacity only), never blocks the first read or the CTA, and prefers-reduced-motion always leaves a complete static page. So you can build a Stripe-grade landing page and a calm dashboard from the same engine, each with the right restraint. _{(Rules: DESIGN-LANGUAGE §43 · PAGE-TYPES → Landing)}

All seeds auto-respect prefers-reduced-motion, and the /styleseed motion skill pulls every recipe from one source of truth — so motion stays consistent no matter who (or what) writes the code.

Available Skins

Engine Contents

engine/
├── CLAUDE.md                 # AI reads this automatically
├── AGENTS.md                 # Codex and other AGENTS.md-compatible agents
├── DESIGN-LANGUAGE.md        # 74 visual design rules (brand-agnostic)
├── .claude/skills/styleseed/ # One registered skill
│   ├── SKILL.md              # Route the user's request
│   └── workflows/           # 22 internal workflows, each with WORKFLOW.md
│       ├── ss-resolve/       # Compiler and runtime
│       ├── ss-build/         # Build loop
│       ├── ss-verify/        # Rendered evidence
│       └── …                # Setup, tokens, review, motion, update, etc.
├── motion/                   # 5 motion seeds + keyword library
├── components/
│   ├── ui/                   # 32 primitives (shadcn/ui + motion)
│   └── patterns/             # 16 dashboard patterns
├── css/                      # base.css, fonts.css, index.css
├── tokens/                   # 6 JSON token files
├── utils/                    # Formatting utilities
├── icons/                    # Custom SVG icon library
└── scaffold/                 # Vite 6 + React 18 starter

One Skill, 22 Internal Workflows

Setup

UI — Build It Right

UX — Design It Right (No Designer Needed)

Optional repository-only learning extension

/ss-learn is not part of the single-skill core or the public npx skills add path. Its source lives under extensions/learning/ for security development and local contract testing. It records a generalized lesson only after a person asks for capture, then requires separate caller attestations before acceptance and before preparing a share package. Known high-risk identity patterns are blocked; this is a guardrail, not an anonymization guarantee; review the exact package before exposure. Source code, prompts, screenshots, URLs, brand tokens, and arbitrary extra fields are rejected. The prepared package stays local and untransmitted. The extension source includes a development-only bridge, but it must remain disabled until a host-owned proof adapter is verified. If it is ever enabled, one exact approved package would become visible to the connected client/model after a separate one-time grant. Neither the CLI nor the bridge uploads to a registry or changes core rules automatically.

Codex plugin package

The repository now includes a repository development .codex-plugin/plugin.json package boundary for local testing alongside the same core skill. The implemented default/core install contains neither ss-learn nor a learning MCP. Public directory release is not verified. npx skills add bitjaru/styleseed remains the portable released installation path today.

Example Workflow

/styleseed setup                    # Pick skin, configure project
/styleseed page Dashboard           # Scaffold main page
/styleseed copy "dashboard"         # Generate all microcopy
/styleseed feedback src/Dashboard   # Add loading/error states
/styleseed audit src/Dashboard      # Check UX quality
/styleseed lint src/Dashboard       # Quick violation scan
/styleseed review src/Dashboard     # Deep design compliance check
/styleseed update                   # Pull latest engine updates

Example Prompts

New project:

Refer to https://github.com/bitjaru/styleseed — read engine/CLAUDE.md 
and engine/DESIGN-LANGUAGE.md. Use skins/stripe/theme.css for colors.
Build a SaaS dashboard with revenue, users, and activity.

Add a page (engine already in project):

Follow CLAUDE.md and DESIGN-LANGUAGE.md rules.
Create a settings page with profile, notifications, and danger zone.
Run /styleseed review when done.

Improve existing page:

Refactor src/Dashboard.tsx to follow DESIGN-LANGUAGE.md.
Check visual rhythm (rule 61) and KPI variation (rule 62).

Update engine:

/styleseed update

Tech Stack

React 18 · TypeScript · Tailwind CSS v4 · Radix UI · Vite 6 · Lucide Icons · CVA

StyleSeed vs. the alternatives

TL;DR: component libraries supply implementation material. StyleSeed adds recorded design decisions and workflows for applying and checking them. Its goal is repeatable expert judgment, not replacing the designer or the project's component library.

FAQ

Q: Why does Claude Code / Cursor generate ugly UI? Because LLMs optimize for functional correctness, not visual refinement. They'll pick #000 for text, py-4 for spacing, text-xl for everything — all technically valid, all amateur. StyleSeed gives them the rules professional designers use.

Q: Is this a shadcn/ui replacement? No — it's built on top of shadcn/ui patterns. StyleSeed components use the same Radix primitives and CVA conventions. Think of it as shadcn/ui + design judgment + AI-tool integration.

Q: Does it work with Cursor too? Yes. The 74 design rules live in a .cursorrules file and CLAUDE.md. Cursor reads them automatically.

Q: How is this different from awesome-design-md? awesome-design-md gives you brand DESIGN.md files (what). StyleSeed gives you the engine that turns any brand into a working app (how). They pair well.

Q: Can I use it for a non-fintech app? Yes. The engine is brand-agnostic. Pick any skin, swap the brand color, ship.

Documentation

Full docs in the Wiki — design rules reference, composition recipes, chart guides, skills reference. Where the project is headed: ROADMAP.md.

Field notes — the thinking behind the rules

Longer-form writing on why AI-built UI looks the way it does (and what actually fixed it):

• Why AI-Generated UIs Look 'Off' — and the One Principle That Fixes It — coherence, the "one value per axis" law, with copy-paste CSS. (한국어판 — 3.5k+ reads)
• I catalogued every tell that makes a UI look AI-generated. My own tool kept failing the test. — the tells taxonomy + the 58/100 self-own.
• AI가 만든 UI, 보여주기 전에 채점시켜라 (KR) — why rules alone failed and the enforced gate was the fix.
• Your Vibe-Coded App Looks Ugly. Here's What I Did About It. — the origin story.

Contributing

StyleSeed is a living judgment framework — the rules aren't carved in stone. If you use it and find a pattern that reliably makes UI better, teach it to everyone's AI by proposing it as a rule.

⭐ Propose a design rule (the heart of it)

A good rule is a decision + the reason it works, written so a model can apply it — not an opinion.

**Rule:** Numbers are 2:1 with their unit (a 48px value over a 24px unit).
**Why it works:** The eye locks onto magnitude first; equal sizes flatten the value into noise.
**Source:** Refactoring UI.

Open a "Propose a design rule" issue, or PR it into engine/DESIGN-LANGUAGE.md (visual/layout) or engine/VISUAL-CRAFT.md (craft & coherence). The judgment compounds as the community adds to it.

Create a New Skin

Just a theme.css + skin.json:

mkdir skins/your-brand
cp skins/toss/theme.css skins/your-brand/theme.css   # copy a skin as a starting point
# Change the --brand color and other values

Improve the Engine

Better rules → better AI output: more specific design rules, new pattern components, accessibility improvements, new AI skills.

See CONTRIBUTING.md for the full rule format and quality checklist.

Updating

Already using StyleSeed? Check the exact rule/skill revision first:

# Claude Code: /styleseed update
# Codex: $styleseed update

ss-update compares the installed engineRevision, the revision recorded in .styleseed/manifest.json, and the published revision. A matching semantic version alone is not enough. Refresh through the original install channel, then re-resolve and inspect the bundle diff.

Preserved by the update contract: STYLESEED.md, app code, tokens, assets, customized components, and project-owned AGENTS.md / CLAUDE.md / .cursorrules.

Full guide: engine/UPDATE.md

Get notified: Click Watch → Custom → Releases on this repo.

License

MIT

Acknowledgments

• Design language inspired by Toss
• Components based on shadcn/ui
• Brand skins sourced from awesome-design-md
• UX principles from Laws of UX and Nielsen Norman Group

Update reminders and an optional freshness gate

After a one-time refresh, StyleSeed skills require a read-only revision check at the first workflow of each project/task session. Outdated installs recommend $styleseed update (Claude: /styleseed update), including changes that keep the same version number. Updates preserve project design decisions; offline checks are reported as unknown. Old installed skills cannot receive this instruction until updated once.

For CI/tasks that must use the current installed channel, run the installed ss-update/scripts/check-update.mjs --project-root . --require-current --json before your build. It exits 1 on outdated/unverifiable installs or any stale registry artifact; it never installs anything. Pinned projects can keep diagnostic mode without --require-current. See the update preflight contract.